Prototype of the discussed HTTP API Spec

I don’t think adding a prefix will add too much noise to the API, and if

it does it cost less than resolving namespace collision.

It is true that user can use HTTP.Request and SOAP.Request to make it

clean which one ppl is referring to, but it also make code hard to debug
once anyone has accidentally forgot to add the “HTTP.” preflx, and this is
kind of error that the compiler cannot catch sometimes, especially when
they have members and methods used in the function body with the same name
and type (which for a req/res this should be pretty common).

I honestly never seen it happen. Vapor is one of the most popular
frameworks and they also use Request and Response. I'd love to see
real-life reports of issues regarding this matter.

···

On 26 May 2017 at 20:59, Michael Chiu <hatsuneyuji@icloud.com> wrote:

When importing HTTP you know you'll deal with HTTP requests and not
anything else. And if you do import another module which also has Request
(never happened to me) you have to make it clear which one you're referring
to. So you'll have to do HTTP.Request, SOAP.Request. So in both scenarios,
there won't be any confusion. On the other hand prefixing everything ends
up adding noise to the API.

I don’t think adding a prefix will add too much noise to the API, and if
it does it cost less than resolving namespace collision.
It is true that user can use HTTP.Request and SOAP.Request to make it
clean which one ppl is referring to, but it also make code hard to debug
once anyone has accidentally forgot to add the “HTTP.” preflx, and this is
kind of error that the compiler cannot catch sometimes, especially when
they have members and methods used in the function body with the same name
and type (which for a req/res this should be pretty common).

Michael

Was there a discussion on the module name yet? I would assume it to be

more like S3.HTTPRequest, alongside the other protocols. Or is there even
an explicit module, or just an abstract API?

There wasn't any discussion. I'm just assuming it would a module called
HTTP. Of course it could be anything else.

It is Friday night and there about 3 opinions on that. Give it some time …

I didn't mean this is settled. I meant I'm OK with the prefixes if
eventually people decide in favor of it.

no real complex project AFAIK had built on any of the swift web framework

available yet.

My response was to that particular section in the quote above. We do have
complex projects running in production. I'm not saying S3 is completely
mature. It isn't.

That seems pretty optimistic given the past discussions. No protocols,

structs, enums, etc. It may be what we end up with, but I don’t
particularly like it :-) It still makes sense as a basis to go forward from.

Exactly my point. We need something to build upon. All I'm proposing is
that we start with the basics. Given the discussions we had so far the
design below looks like the most consensual (or maybe the least
controversial).

public struct HTTPVersion {
    public var major: Int
    public var minor: Int

    public init(major: Int, minor: Int) {
        self.major = major
        self.minor = minor
    }
}

public struct HTTPHeaders {
    public var headers: [(Field, String)]

    public init(_ headers: [(Field, String)]) {
        self.headers = headers
    }

    /// Field's implementation of `Equatable` performs a case-insensitive
comparison.
    public struct Field {
        public let original: String

        public init(_ original: String) {
            self.original = original
        }
    }
}

public protocol HTTPMessage {
    var version: HTTPVersion { get set }
    var headers: HTTPHeaders { get set }
}

public struct HTTPRequest : HTTPMessage {
    public var method: HTTPMethod
    public var uri: String
    public var version: HTTPVersion
    public var headers: HTTPHeaders

    public init(
        method: HTTPMethod,
        uri: URI,
        headers: HTTPHeaders,
        version: HTTPVersion
    ) {
        self.method = method
        self.uri = uri
        self.headers = headers
        self.version = version
    }
}

public struct HTTPMethod {
    public let method: String

    init(_ method: String) {
        self.method = method.uppercased()
    }
}

public struct HTTPResponse : HTTPMessage {
    public var status: HTTPStatus
    public var headers: HTTPHeaders
    public var version: HTTPVersion

    public init(
        status: HTTPStatus,
        headers: HTTPHeaders,
        version: HTTPVersion
    ) {
        self.status = status
        self.headers = headers
        self.version = version
    }
}

public struct HTTPStatus {
    public let statusCode: Int
    public let reasonPhrase: String

    public init(statusCode: Int, reasonPhrase: String) {
        self.statusCode = statusCode
        self.reasonPhrase = reasonPhrase
    }
}

Hi, Paulo and Michael,

I’ll be honest, this feels counterproductive to me. Folks on this list already spent weeks discussing that API proposal starting on Friday, Mar 24th (https://lists.swift.org/pipermail/swift-server-dev/Week-of-Mon-20170320/000329.html\) and going until the discussion died out on Wednesday, April 12th (https://lists.swift.org/pipermail/swift-server-dev/Week-of-Mon-20170410/000450.html\).

That’s not to say the API should now be locked in stone, but it just doesn’t seem useful to me at this point to throw all that discussion away, start over from scratch and not even plan to have something we can start implementing any time soon.

Am I the only one who feels that way?

-Carl

···

On May 26, 2017, at 8:04 PM, Michael Chiu <hatsuneyuji@icloud.com> wrote:

In general I agree this is how we should process, components by components, arguing around implementation detail won’t help much here.

Tho we do need to agree an architecture to start with before we know what are the components we need.

I do agree that version, req method and res status is something quite orthogonal to the actual architecture hence a good place to discuss ahead.

Michael

On May 26, 2017, at 4:57 PM, Paulo Faria via swift-server-dev <swift-server-dev@swift.org <mailto:swift-server-dev@swift.org>> wrote:

> What do you mean by "the framework" here? I can think of several things that could be referred to by that phrase, and I'm not sure which one you mean.

Sorry, it was really confusing. I meant higher level web frameworks like Kitura, for example. It looks like the code you have go all the way up there.. The WebApp type says it all. I don't think we should have this at all. At least not for now.. I believe we should only go up to the HTTP server/client. I think the types we should implement are in order (naming aside, adding prefixes or not, Sync, Async etc)

Week 1

Version
Headers
Message
Request
Response

Week 2

SyncBody
AsyncBody

Week 3

SyncRequestParser
AsyncRequestParser
SyncResponseParser
AsyncResponseParser

Week 4

SyncRequestSerializer
AsyncRequestSerializer
SyncResponseSerializer
AsyncResponseSerializer

Week 5

SyncServer
AsyncServer

Week 6

SyncClient
AsyncClient

We would have one week to discuss each the API of the types in each set. After we decide on the API we implement in the following week while discussing the next set of APIs. Once we settle on the API for each type implementing shouldn't take more than 2 days based on our experience with the subject.

Using this scheme we would have the API ready in mid-july. What do you guys think? I really think this is a good way to follow on the discussion/implementation.

--
Carl Brown, Swift@IBM
Carl.Brown1@IBM.com (Work)
Austin, TX

Hi Carl,

I feel the same way as you feel.

I have no mean to have everybody start the discussion again :).

What I mean is that we should pick one architecture, either yours xor Paulo’s, and start work on it (on github) component by component, as Paulo suggested.

The reason why I’m mentioning architecture is that unlike your proposal, Paulo’s Req/Res are confirming to the Message protocol, so now we have to think what the protocol, Message should actually be if we pick Paulo’s. that says if we pick a different base, the components we’re going to discuss later on github will be different.

Hi everyone,

Personally, This is how I feel comparing two proposals:

I like how HTTPHeaders work on Paulo’s side, since it is implemented as ExpressibleByDictionaryLiteral, I can imagine providing a list-like data structure can provide functionality of a [Key: [Values]] in a memory friendly way.

On Carl's proposal, I think HTTPResponseWriter is a bit obsoleted, I think the req/res itself are capable to contains session info if we add a session-id property and bitmap flag to the req/res, In that cause, I think it can simplify the ownership model (just a thought, no prove provided).

On the Paulo side the Async/Sync read/write is a bit strange to me, and it doesn’t quite show how is it necessary. Since if we are providing api to mutate the body of a req/res, explicitly making a AsyncBody enum is a bit over engineered for me.

I like the RequestMethod and ResponseStatus on Carl’s side better, since it is implemented as enum and hence easily for user to use in a switch statement.

On Paulo's IO side, Duration sounds real cool to me but that should be the stream-side’s responsibility.

HTTPTransferEncoding is a big plus on Carl’s side.

TL;DR:

I think there’s some cool stuff on both side that can mix and match. I think we should just pick a base and work on it.

Michael.

···

On May 26, 2017, at 9:21 PM, Carl Brown <carl.brown.swift@linuxswift.com <mailto:carl.brown.swift@linuxswift.com>> wrote:

Hi, Paulo and Michael,

I’ll be honest, this feels counterproductive to me. Folks on this list already spent weeks discussing that API proposal starting on Friday, Mar 24th (https://lists.swift.org/pipermail/swift-server-dev/Week-of-Mon-20170320/000329.html\) and going until the discussion died out on Wednesday, April 12th (https://lists.swift.org/pipermail/swift-server-dev/Week-of-Mon-20170410/000450.html\).

That’s not to say the API should now be locked in stone, but it just doesn’t seem useful to me at this point to throw all that discussion away, start over from scratch and not even plan to have something we can start implementing any time soon.

Am I the only one who feels that way?

-Carl

On May 26, 2017, at 8:04 PM, Michael Chiu <hatsuneyuji@icloud.com <mailto:hatsuneyuji@icloud.com>> wrote:

In general I agree this is how we should process, components by components, arguing around implementation detail won’t help much here.

Tho we do need to agree an architecture to start with before we know what are the components we need.

I do agree that version, req method and res status is something quite orthogonal to the actual architecture hence a good place to discuss ahead.

Michael

On May 26, 2017, at 4:57 PM, Paulo Faria via swift-server-dev <swift-server-dev@swift.org <mailto:swift-server-dev@swift.org>> wrote:

> What do you mean by "the framework" here? I can think of several things that could be referred to by that phrase, and I'm not sure which one you mean.

Sorry, it was really confusing. I meant higher level web frameworks like Kitura, for example. It looks like the code you have go all the way up there.. The WebApp type says it all. I don't think we should have this at all. At least not for now.. I believe we should only go up to the HTTP server/client. I think the types we should implement are in order (naming aside, adding prefixes or not, Sync, Async etc)

Week 1

Version
Headers
Message
Request
Response

Week 2

SyncBody
AsyncBody

Week 3

SyncRequestParser
AsyncRequestParser
SyncResponseParser
AsyncResponseParser

Week 4

SyncRequestSerializer
AsyncRequestSerializer
SyncResponseSerializer
AsyncResponseSerializer

Week 5

SyncServer
AsyncServer

Week 6

SyncClient
AsyncClient

We would have one week to discuss each the API of the types in each set. After we decide on the API we implement in the following week while discussing the next set of APIs. Once we settle on the API for each type implementing shouldn't take more than 2 days based on our experience with the subject.

Using this scheme we would have the API ready in mid-july. What do you guys think? I really think this is a good way to follow on the discussion/implementation.

--
Carl Brown, Swift@IBM
Carl.Brown1@IBM.com <mailto:Carl.Brown1@IBM.com> (Work)
Austin, TX

Am I the only one who feels that way?

You are not the only one who feels that way.

···

Sent from my iPhone

On May 26, 2017, at 11:21 PM, Carl Brown via swift-server-dev <swift-server-dev@swift.org> wrote:

I don’t really care, though more history is always better? :-> Also you don’t have to do it just for me ;-> It was just my second reaction to Chris’ post. He said it is based on Johannes` but there wasn’t a description of the changes or why.

Someone has to go forward, Johannes started it, IMO you can just go ahead with it and provide more stuff people can comment on. It is git, we can always change&revert stuff … If Paulo thinks there is too much, he can trim it down in a pull request. Sounds more productive to me than arbitrary email discussions.

hh

···

On May 27, 2017, at 1:21 AM, Carl Brown <carl.brown.swift@linuxswift.com> wrote:

This looks like an earlier version of Johannes' code (probably from https://lists.swift.org/pipermail/swift-server-dev/Week-of-Mon-20170320/000329.html\). I was working off the April 5th version. (The one with "HTTP API Sketch v2" in the subject from https://lists.swift.org/pipermail/swift-server-dev/Week-of-Mon-20170403/000422.html\).

Do we need to start with the March version?

I'm not sure I follow your example. Cat.Animal doesn't make much sense to me while Animal.Cat makes perfect sense.

Precisely. Name it after the concrete thing, not after the abstract concept.

When importing HTTP you know you'll deal with HTTP requests and not anything else.

HTTP servers don’t exist in the void. Your endpoint is going to do something, e.g. some other form of request. In the case of HTTP application servers this is going to be quite often an: NSFetchRequest ... well, a CoreData.Query.Request in your API naming convention …

But we can leave it at that. If people think that this is a good idea, go ahead. I recommend against it.

most of the APIs are synchronous

If you say so. I notice exactly the reverse ;-) Most of the API in Node.js is async for sure and good reason.

> For async you usually need some way to hold on to a buffer, and that is DispatchData

Sorry can you elucidate that? If you have the pointer, you're holding the buffer aren't you? I'm not sure I follow the issue.

In a synchronous setup you usually ‘receive’ (and send) directly into a buffer and may not even need to allocate it on the heap. In a asynchronous setup you have to allocate it on the heap, because - well, the reference/buffer needs to stay until the receive is completed. Well, and, DispatchData is a heap object optimized for that. Though I don’t know why this isn’t integrated with Data.

hh

···

On May 27, 2017, at 1:19 AM, Paulo Faria <paulo@zewo.io> wrote:

On 26 May 2017 at 20:09, Helge Heß via swift-server-dev <swift-server-dev@swift.org> wrote:
On May 27, 2017, at 12:55 AM, Paulo Faria <paulo@zewo.io> wrote:
> Helge! I agree with most of your suggestions and I'll update my proposal with them. There's only one I'm not with you and it's about the HTTP prefix. The example you mentioned could be easily solved by adding `HTTP.` when referring to the specific type.
>
> import HTTP
> import SOAP
>
> let request = HTTP.Request()
>
> We have used Request and Response without prefixes for about two years and not once anyone complained about that. I imagine others who use the same naming scheme can testify to that.

Having seen such overloading in Java frameworks before I simply disagree with that. The object in question is plainly a HTTPRequest(Head) not just some arbitrary request. The ‘HTTP’ really is part of the thing. In fact the ‘arbitrary’ request could be an NSOperation, providing functionalities such as pause, cancel, etc.

In a way it is like

  import Cat

  let pet = Animal() // resolving to Cat.Animal()

But well, if people really like that … ;-) I vote against it.

> About Sync/Async prefix. I was talking about type prefixes not method prefixes. We definitely shouldn't prefix function APIs with sync or async. I honestly don't care too much about which one to use as a default. I just think it makes more sense to prefix the Async ones.

Your particular setup is sync, right? ;->

> About raw buffers we could provide APIs that take an array of Unsafe[Mutable]RawBufferPointer to pass them to readv, writev and company. Those could also be easily converted to DispatchData in the frameworks that prefer to use it.

This is a little related to sync vs async. For async you usually need some way to hold on to a buffer, and that is DispatchData. For sync you usually don’t have to, and pointers to buffers can be faster.

Though I do think that sync is more appropriate for many server builders, I think that the goal for Swift-Server would be more oriented towards async. I may be wrong.

hh

_______________________________________________
swift-server-dev mailing list
swift-server-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-server-dev

Hi, Michael,

  We’re not really talking about the same thing here.

  This email thread isn’t about an API proposal. It’s about a prototype implementation of an API that was already proposed and discussed a month and a half ago. The prototype isn't a full-featured framework like Vapor or Kitura, but it does actually work and it even has XCTests with decent (>75%) code coverage.

  Also, please note that I didn’t play any part in proposing this API back in March/April - it’s not “Carl’s proposal.” I just took the existing API that the group had previously discussed and implemented enough of it so that we could measure the utility and performance of the API as proposed and so that we could have better informed discussions about potential alternatives.

-Carl

···

On May 27, 2017, at 1:47 AM, Michael Chiu <hatsuneyuji@icloud.com> wrote:

Hi Carl,

I feel the same way as you feel.

I have no mean to have everybody start the discussion again :).

What I mean is that we should pick one architecture, either yours xor Paulo’s, and start work on it (on github) component by component, as Paulo suggested.

The reason why I’m mentioning architecture is that unlike your proposal, Paulo’s Req/Res are confirming to the Message protocol, so now we have to think what the protocol, Message should actually be if we pick Paulo’s. that says if we pick a different base, the components we’re going to discuss later on github will be different.

Hi everyone,

Personally, This is how I feel comparing two proposals:

I like how HTTPHeaders work on Paulo’s side, since it is implemented as ExpressibleByDictionaryLiteral, I can imagine providing a list-like data structure can provide functionality of a [Key: [Values]] in a memory friendly way.

On Carl's proposal, I think HTTPResponseWriter is a bit obsoleted, I think the req/res itself are capable to contains session info if we add a session-id property and bitmap flag to the req/res, In that cause, I think it can simplify the ownership model (just a thought, no prove provided).

On the Paulo side the Async/Sync read/write is a bit strange to me, and it doesn’t quite show how is it necessary. Since if we are providing api to mutate the body of a req/res, explicitly making a AsyncBody enum is a bit over engineered for me.

I like the RequestMethod and ResponseStatus on Carl’s side better, since it is implemented as enum and hence easily for user to use in a switch statement.

On Paulo's IO side, Duration sounds real cool to me but that should be the stream-side’s responsibility.

HTTPTransferEncoding is a big plus on Carl’s side.

TL;DR:

I think there’s some cool stuff on both side that can mix and match. I think we should just pick a base and work on it.

Michael.

On May 26, 2017, at 9:21 PM, Carl Brown <carl.brown.swift@linuxswift.com <mailto:carl.brown.swift@linuxswift.com>> wrote:

Hi, Paulo and Michael,

I’ll be honest, this feels counterproductive to me. Folks on this list already spent weeks discussing that API proposal starting on Friday, Mar 24th (https://lists.swift.org/pipermail/swift-server-dev/Week-of-Mon-20170320/000329.html\) and going until the discussion died out on Wednesday, April 12th (https://lists.swift.org/pipermail/swift-server-dev/Week-of-Mon-20170410/000450.html\).

That’s not to say the API should now be locked in stone, but it just doesn’t seem useful to me at this point to throw all that discussion away, start over from scratch and not even plan to have something we can start implementing any time soon.

Am I the only one who feels that way?

-Carl

On May 26, 2017, at 8:04 PM, Michael Chiu <hatsuneyuji@icloud.com <mailto:hatsuneyuji@icloud.com>> wrote:

In general I agree this is how we should process, components by components, arguing around implementation detail won’t help much here.

Tho we do need to agree an architecture to start with before we know what are the components we need.

I do agree that version, req method and res status is something quite orthogonal to the actual architecture hence a good place to discuss ahead.

Michael

On May 26, 2017, at 4:57 PM, Paulo Faria via swift-server-dev <swift-server-dev@swift.org <mailto:swift-server-dev@swift.org>> wrote:

> What do you mean by "the framework" here? I can think of several things that could be referred to by that phrase, and I'm not sure which one you mean.

Sorry, it was really confusing. I meant higher level web frameworks like Kitura, for example. It looks like the code you have go all the way up there.. The WebApp type says it all. I don't think we should have this at all. At least not for now.. I believe we should only go up to the HTTP server/client. I think the types we should implement are in order (naming aside, adding prefixes or not, Sync, Async etc)

Week 1

Version
Headers
Message
Request
Response

Week 2

SyncBody
AsyncBody

Week 3

SyncRequestParser
AsyncRequestParser
SyncResponseParser
AsyncResponseParser

Week 4

SyncRequestSerializer
AsyncRequestSerializer
SyncResponseSerializer
AsyncResponseSerializer

Week 5

SyncServer
AsyncServer

Week 6

SyncClient
AsyncClient

We would have one week to discuss each the API of the types in each set. After we decide on the API we implement in the following week while discussing the next set of APIs. Once we settle on the API for each type implementing shouldn't take more than 2 days based on our experience with the subject.

Using this scheme we would have the API ready in mid-july. What do you guys think? I really think this is a good way to follow on the discussion/implementation.

--
Carl Brown, Swift@IBM
Carl.Brown1@IBM.com <mailto:Carl.Brown1@IBM.com> (Work)
Austin, TX

That is indeed a problem with discussions, they never end… </joking>

However, if you have a real world application, my advice would be not to wait for public solutions. It will kill your project.
I have been developing a Swift server for quite some time now, and will continue my work, irrespective of what may come out of this discussion.

If at some time in the future this list produces something that is better than my own code, I will happily throw my own stuff away and rewrite my own project to use the list’s solutions.

That said, there are only so many ways to implement an HTTP API, and the proposal very closely resembles my own solution. Hence any future rewrite is probably very limited in scope.

About the proposal so far:

1) I agree with another commenter that I think in “200” and “503” or “401” and not in the descriptions. Besides, the numbers are grouped logically. Code completion is very convenient if the names begin with the number. Suppose you want to flag a server problem, then typing HttpResponseCode.code5… will immediately show you all the possible options. Works faster this way. Hence my code definitions all start with codeXXX but they also include the description afterwards. Example snippet:

public enum HttpResponseCode: String {
    
    /// The client SHOULD continue with its request. This interim response is used to inform the client that the initial part of the request has been received and has not yet been rejected by the server. The client SHOULD continue by sending the remainder of the request or, if the request has already been completed, ignore this response. The server MUST send a final response after the request has been completed. See section 8.2.3 for detailed discussion of the use and handling of this status code.
    
    case code100_Continue = "100 Continue"
    
    /// The server understands and is willing to comply with the client's request, via the Upgrade message header field (section 14.42), for a change in the application protocol being used on this connection. The server will switch protocols to those defined by the response's Upgrade header field immediately after the empty line which terminates the 101 response.
    /// The protocol SHOULD be switched only when it is advantageous to do so. For example, switching to a newer version of HTTP is advantageous over older versions, and switching to a real-time, synchronous protocol might be advantageous when delivering resources that use such features.
    
    case code101_SwitchingProtocols = "101 Switching Protocols"
    
As you see I have also included the comments from the specs. Also quite convenient when working in xcode.

2) Another issue is CamelCase. I personally find HTTPResponse quite unreadable. I prefer HttpResponse. I always use CamelCase, even when dealing with abbreviations. But I admit that is subjective. It does touch upon the issue with HTTP.Response vs HTTPResponse though for readability issues.

3) Originally I used pointers everywhere, but my experience has been that this does not work nicely with Cocoa. I have since changed to using Data and that has simplified life. I do not know about efficiency as that is not yet a concern for me. (Performance comes later). There is something to be said for using pointers on the Request side and Data on the Response side of thing though. I still use pointers for the socket API.

4) External dependencies: This may be a major issue for me. I do not object to some external dependencies, but I do most certainly NOT want my code to depend on 50 other frameworks. (slight exaggeration?) One thing you might notice -if you check out my work- is that I have only 1 external dependency and that is on OpenSSL. All the rest is made by me.
As you can guess from this, I have been burnt in the past by relying on external frameworks, and that is not going to happen again. I will -as said previously- happily rewrite my code base to use a ‘standard’. But if that results in having to use 20 other ‘standards’, then its a no-go for me.

If you want to take a peek at my work, see the links below. But be aware that I want to do some recoding myself now that I am getting closer to release 1.0
(Also note that the swiftfire website needs updating, as usual it lags developments, though I do try and keep the gap as small as possible)

Regards,
Rien

Site: http://balancingrock.nl
Blog: http://swiftrien.blogspot.com
Github: Balancingrock (Rien) · GitHub
Project: http://swiftfire.nl - A server for websites build in Swift

···

On 27 May 2017, at 06:21, Carl Brown via swift-server-dev <swift-server-dev@swift.org> wrote:

Hi, Paulo and Michael,

I’ll be honest, this feels counterproductive to me. Folks on this list already spent weeks discussing that API proposal starting on Friday, Mar 24th (https://lists.swift.org/pipermail/swift-server-dev/Week-of-Mon-20170320/000329.html\) and going until the discussion died out on Wednesday, April 12th (https://lists.swift.org/pipermail/swift-server-dev/Week-of-Mon-20170410/000450.html\).

That’s not to say the API should now be locked in stone, but it just doesn’t seem useful to me at this point to throw all that discussion away, start over from scratch and not even plan to have something we can start implementing any time soon.

Am I the only one who feels that way?

-Carl

On May 26, 2017, at 8:04 PM, Michael Chiu <hatsuneyuji@icloud.com> wrote:

In general I agree this is how we should process, components by components, arguing around implementation detail won’t help much here.

Tho we do need to agree an architecture to start with before we know what are the components we need.

I do agree that version, req method and res status is something quite orthogonal to the actual architecture hence a good place to discuss ahead.

Michael

On May 26, 2017, at 4:57 PM, Paulo Faria via swift-server-dev <swift-server-dev@swift.org> wrote:

> What do you mean by "the framework" here? I can think of several things that could be referred to by that phrase, and I'm not sure which one you mean.

Sorry, it was really confusing. I meant higher level web frameworks like Kitura, for example. It looks like the code you have go all the way up there.. The WebApp type says it all. I don't think we should have this at all. At least not for now.. I believe we should only go up to the HTTP server/client. I think the types we should implement are in order (naming aside, adding prefixes or not, Sync, Async etc)

Week 1

Version
Headers
Message
Request
Response

Week 2

SyncBody
AsyncBody

Week 3

SyncRequestParser
AsyncRequestParser
SyncResponseParser
AsyncResponseParser

Week 4

SyncRequestSerializer
AsyncRequestSerializer
SyncResponseSerializer
AsyncResponseSerializer

Week 5

SyncServer
AsyncServer

Week 6

SyncClient
AsyncClient

We would have one week to discuss each the API of the types in each set. After we decide on the API we implement in the following week while discussing the next set of APIs. Once we settle on the API for each type implementing shouldn't take more than 2 days based on our experience with the subject.

Using this scheme we would have the API ready in mid-july. What do you guys think? I really think this is a good way to follow on the discussion/implementation.

--
Carl Brown, Swift@IBM
Carl.Brown1@IBM.com (Work)
Austin, TX

_______________________________________________
swift-server-dev mailing list
swift-server-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-server-dev

Hi,

> What do you mean by "the framework" here? I can think of several things that could be referred to by that phrase, and I'm not sure which one you mean.

Sorry, it was really confusing. I meant higher level web frameworks like Kitura, for example. It looks like the code you have go all the way up there.. The WebApp type says it all. I don't think we should have this at all. At least not for now.. I believe we should only go up to the HTTP server/client. I think the types we should implement are in order (naming aside, adding prefixes or not, Sync, Async etc)

I don't quite see why we need (or should even offer) a synchronous API for anything that involves IO (disk, network, ...). Sure, many of us would like to have a synchronous and non-blocking programming model, that'd be great. Today in Swift unfortunately we can only go asynchronous&non-blocking or synchronous&blocking (causing undefined behaviour [1] with setjmp/longjmp to get synchronous&non-blocking is cool but certainly not supported today).

Now at least in Cocoa/Foundation, Dispatch is the de facto standard for concurrency. And given that Dispatch doesn't mix well with blocking code (on Darwin a maximum of $(sysctl kern.wq_max_constrained_threads) threads (default is 64) are used to dequeue work items from DispatchQueues), I don't see why we should be providing a synchronous API for anything that involves IO as that would block. In other words, Dispatch usually has exactly one thread pool of finite size (not implemented on Linux today AFAIK). Proposing synchronous&blocking APIs to swift-evolution would I believe get us into a corner we really wouldn't want to be in.

With Swift 5+ we might get a language-level concurrency model which might involve a synchronous programming model that is non-blocking but for quite some time we won't have that. But we can be pretty sure that there will be a migration path from asynchronous IO using Dispatch to whatever Swift's concurrency model will be.

After all, there aren't many non-deprecated APIs left in Foundation/Cocoa that do synchronous (blocking) IO and I think we should follow this trend and go asynchronous only for all IO APIs. That's what I believe any Swift programmer would assume and presumably what the Swift core team will provide migration paths for.

-- Johannes
[1]: [swift-evolution] Swift null safety questions

···

On 27 May 2017, at 12:57 am, Paulo Faria via swift-server-dev <swift-server-dev@swift.org> wrote:

Week 1

Version
Headers
Message
Request
Response

Week 2

SyncBody
AsyncBody

Week 3

SyncRequestParser
AsyncRequestParser
SyncResponseParser
AsyncResponseParser

Week 4

SyncRequestSerializer
AsyncRequestSerializer
SyncResponseSerializer
AsyncResponseSerializer

Week 5

SyncServer
AsyncServer

Week 6

SyncClient
AsyncClient

We would have one week to discuss each the API of the types in each set. After we decide on the API we implement in the following week while discussing the next set of APIs. Once we settle on the API for each type implementing shouldn't take more than 2 days based on our experience with the subject.

Using this scheme we would have the API ready in mid-july. What do you guys think? I really think this is a good way to follow on the discussion/implementation.

On 26 May 2017 at 20:40, Carl Brown <carl.brown.swift@linuxswift.com> wrote:

On May 26, 2017, at 6:07 PM, Paulo Faria via swift-server-dev <swift-server-dev@swift.org> wrote:

Hi, Carl!

I honestly think the code is too overwhelming.

I can see that. It was important to us to get something that actually worked end-to-end, could be profiled and had test coverage. We couldn't get it much smaller.

I'm also a bit confused about the IBM dependencies. Is this supposed to stay in the swift server repos or is it just momentary so we have working code?

It's a stand-in until the Transport part of the working group has a reference implementation of a socket/stream API and the Security part of the working group has a reference implementation of SSL/TLS. The HTTP part of the group is just ahead of everyone else.

I'm not very fond of the first option if it is the case, and about the second option... If it's just to see working code.. Then we should have in swift server org only the HTTP module and then have the actual implementation of the framework reside elsewhere importing HTTP module as a dependency. This way we have an view of how people will import and use the framework. It also gives the other frameworks a chance to implement their solutions on top of the common HTTP module.

What do you mean by "the framework" here? I can think of several things that could be referred to by that phrase, and I'm not sure which one you mean.

I think we should start moving small bits of code, for example, Version, Headers, Message, Request and Response. After we have that code in the repo working with all the frameworks which are validating the API, then we move on to the body (which is probably going to be the hardest part to settle for everyone). After that we go to the parser/serializer.

Again, I'm not sure what you mean by "the frameworks" here, but putting that aside, there's the issue of timing. I can see value in asking the group for comments on a small piece of code and not moving on to the next small piece until after everyone has had a chance to comment, but given the pace of progress that's been made by this group so far, don't you think that would take a very, very long time?

-Carl

On 26 May 2017 at 19:51, Helge Heß via swift-server-dev <swift-server-dev@swift.org> wrote:
Hi Carl,

> But the question of the moment (for you and for the group) is - do you think this is a good enough starting point for us to move it to the Swift on Server · GitHub organization and start iterating via GitHub issues & Pull Requests, or do you think we're still at the stage where we need to have more email discussions about it before we're ready to take that step?

that seems perfectly reasonable to me.

What I personally would like best is submitting Johannes’ proposal first, and on top of that submit your changes (w/ explanations what you changed and why in the commits).

I have Johannes’ original proposal in code over here, in case you need it as a basis:

  https://github.com/ApacheExpress/ApacheExpress/tree/s3wg-api-proposal-1/S3WGAPIProposal1

hh

_______________________________________________
swift-server-dev mailing list
swift-server-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-server-dev

_______________________________________________
swift-server-dev mailing list
swift-server-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-server-dev

_______________________________________________
swift-server-dev mailing list
swift-server-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-server-dev

In a synchronous setup you usually ‘receive’ (and send) directly into a

buffer and may not even need to allocate it on the heap. In a asynchronous
setup you have to allocate it on the heap, because - well, the
reference/buffer needs to stay until the receive is completed. Well, and,
DispatchData is a heap object optimized for that. Though I don’t know why
this isn’t integrated with Data.

What I mean is.. Nothing is stopping one to hold the reference to the
buffer, right? I mean, having buffers don't make async APIs impossible.

···

On 26 May 2017 at 20:54, Helge Heß via swift-server-dev < swift-server-dev@swift.org> wrote:

On May 27, 2017, at 1:19 AM, Paulo Faria <paulo@zewo.io> wrote:
> I'm not sure I follow your example. Cat.Animal doesn't make much sense
to me while Animal.Cat makes perfect sense.

Precisely. Name it after the concrete thing, not after the abstract
concept.

> When importing HTTP you know you'll deal with HTTP requests and not
anything else.

HTTP servers don’t exist in the void. Your endpoint is going to do
something, e.g. some other form of request. In the case of HTTP application
servers this is going to be quite often an: NSFetchRequest ... well, a
CoreData.Query.Request in your API naming convention …

But we can leave it at that. If people think that this is a good idea, go
ahead. I recommend against it.

> most of the APIs are synchronous

If you say so. I notice exactly the reverse ;-) Most of the API in Node.js
is async for sure and good reason.

> > For async you usually need some way to hold on to a buffer, and that
is DispatchData
>
> Sorry can you elucidate that? If you have the pointer, you're holding
the buffer aren't you? I'm not sure I follow the issue.

In a synchronous setup you usually ‘receive’ (and send) directly into a
buffer and may not even need to allocate it on the heap. In a asynchronous
setup you have to allocate it on the heap, because - well, the
reference/buffer needs to stay until the receive is completed. Well, and,
DispatchData is a heap object optimized for that. Though I don’t know why
this isn’t integrated with Data.

hh

>
>
> On 26 May 2017 at 20:09, Helge Heß via swift-server-dev < > swift-server-dev@swift.org> wrote:
> On May 27, 2017, at 12:55 AM, Paulo Faria <paulo@zewo.io> wrote:
> > Helge! I agree with most of your suggestions and I'll update my
proposal with them. There's only one I'm not with you and it's about the
HTTP prefix. The example you mentioned could be easily solved by adding
`HTTP.` when referring to the specific type.
> >
> > import HTTP
> > import SOAP
> >
> > let request = HTTP.Request()
> >
> > We have used Request and Response without prefixes for about two years
and not once anyone complained about that. I imagine others who use the
same naming scheme can testify to that.
>
> Having seen such overloading in Java frameworks before I simply disagree
with that. The object in question is plainly a HTTPRequest(Head) not just
some arbitrary request. The ‘HTTP’ really is part of the thing. In fact the
‘arbitrary’ request could be an NSOperation, providing functionalities such
as pause, cancel, etc.
>
> In a way it is like
>
> import Cat
>
> let pet = Animal() // resolving to Cat.Animal()
>
> But well, if people really like that … ;-) I vote against it.
>
> > About Sync/Async prefix. I was talking about type prefixes not method
prefixes. We definitely shouldn't prefix function APIs with sync or async.
I honestly don't care too much about which one to use as a default. I just
think it makes more sense to prefix the Async ones.
>
> Your particular setup is sync, right? ;->
>
> > About raw buffers we could provide APIs that take an array of
Unsafe[Mutable]RawBufferPointer to pass them to readv, writev and
company. Those could also be easily converted to DispatchData in the
frameworks that prefer to use it.
>
> This is a little related to sync vs async. For async you usually need
some way to hold on to a buffer, and that is DispatchData. For sync you
usually don’t have to, and pointers to buffers can be faster.
>
> Though I do think that sync is more appropriate for many server
builders, I think that the goal for Swift-Server would be more oriented
towards async. I may be wrong.
>
> hh
>
>
> _______________________________________________
> swift-server-dev mailing list
> swift-server-dev@swift.org
> https://lists.swift.org/mailman/listinfo/swift-server-dev
>
>

_______________________________________________
swift-server-dev mailing list
swift-server-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-server-dev

I mean, having buffers don't make async APIs impossible.

Having raw buffers instead of DispatchData.

···

On 26 May 2017 at 21:05, Paulo Faria <paulo@zewo.io> wrote:

> In a synchronous setup you usually ‘receive’ (and send) directly into a
buffer and may not even need to allocate it on the heap. In a asynchronous
setup you have to allocate it on the heap, because - well, the
reference/buffer needs to stay until the receive is completed. Well, and,
DispatchData is a heap object optimized for that. Though I don’t know why
this isn’t integrated with Data.

What I mean is.. Nothing is stopping one to hold the reference to the
buffer, right? I mean, having buffers don't make async APIs impossible.

On 26 May 2017 at 20:54, Helge Heß via swift-server-dev < > swift-server-dev@swift.org> wrote:

On May 27, 2017, at 1:19 AM, Paulo Faria <paulo@zewo.io> wrote:
> I'm not sure I follow your example. Cat.Animal doesn't make much sense
to me while Animal.Cat makes perfect sense.

Precisely. Name it after the concrete thing, not after the abstract
concept.

> When importing HTTP you know you'll deal with HTTP requests and not
anything else.

HTTP servers don’t exist in the void. Your endpoint is going to do
something, e.g. some other form of request. In the case of HTTP application
servers this is going to be quite often an: NSFetchRequest ... well, a
CoreData.Query.Request in your API naming convention …

But we can leave it at that. If people think that this is a good idea, go
ahead. I recommend against it.

> most of the APIs are synchronous

If you say so. I notice exactly the reverse ;-) Most of the API in
Node.js is async for sure and good reason.

> > For async you usually need some way to hold on to a buffer, and that
is DispatchData
>
> Sorry can you elucidate that? If you have the pointer, you're holding
the buffer aren't you? I'm not sure I follow the issue.

In a synchronous setup you usually ‘receive’ (and send) directly into a
buffer and may not even need to allocate it on the heap. In a asynchronous
setup you have to allocate it on the heap, because - well, the
reference/buffer needs to stay until the receive is completed. Well, and,
DispatchData is a heap object optimized for that. Though I don’t know why
this isn’t integrated with Data.

hh

>
>
> On 26 May 2017 at 20:09, Helge Heß via swift-server-dev < >> swift-server-dev@swift.org> wrote:
> On May 27, 2017, at 12:55 AM, Paulo Faria <paulo@zewo.io> wrote:
> > Helge! I agree with most of your suggestions and I'll update my
proposal with them. There's only one I'm not with you and it's about the
HTTP prefix. The example you mentioned could be easily solved by adding
`HTTP.` when referring to the specific type.
> >
> > import HTTP
> > import SOAP
> >
> > let request = HTTP.Request()
> >
> > We have used Request and Response without prefixes for about two
years and not once anyone complained about that. I imagine others who use
the same naming scheme can testify to that.
>
> Having seen such overloading in Java frameworks before I simply
disagree with that. The object in question is plainly a HTTPRequest(Head)
not just some arbitrary request. The ‘HTTP’ really is part of the thing. In
fact the ‘arbitrary’ request could be an NSOperation, providing
functionalities such as pause, cancel, etc.
>
> In a way it is like
>
> import Cat
>
> let pet = Animal() // resolving to Cat.Animal()
>
> But well, if people really like that … ;-) I vote against it.
>
> > About Sync/Async prefix. I was talking about type prefixes not method
prefixes. We definitely shouldn't prefix function APIs with sync or async.
I honestly don't care too much about which one to use as a default. I just
think it makes more sense to prefix the Async ones.
>
> Your particular setup is sync, right? ;->
>
> > About raw buffers we could provide APIs that take an array of
Unsafe[Mutable]RawBufferPointer to pass them to readv, writev and
company. Those could also be easily converted to DispatchData in the
frameworks that prefer to use it.
>
> This is a little related to sync vs async. For async you usually need
some way to hold on to a buffer, and that is DispatchData. For sync you
usually don’t have to, and pointers to buffers can be faster.
>
> Though I do think that sync is more appropriate for many server
builders, I think that the goal for Swift-Server would be more oriented
towards async. I may be wrong.
>
> hh
>
>
> _______________________________________________
> swift-server-dev mailing list
> swift-server-dev@swift.org
> https://lists.swift.org/mailman/listinfo/swift-server-dev
>
>

_______________________________________________
swift-server-dev mailing list
swift-server-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-server-dev

I updated my proposal according to Helge's suggestions. I really think we
can settle the following APIs very quickly:

Version
Headers
Message
Request
Request.Method
Response
Response.Status

Apart from naming the properties are identical to what Carl proposed. Helge
didn't comment anything about URI and Storage. I don't feel strongly about
either one.

https://github.com/paulofaria/http-api-proposal/blob/master/Sources/HTTP.swift

···

On 26 May 2017 at 21:06, Paulo Faria <paulo@zewo.io> wrote:

> I mean, having buffers don't make async APIs impossible.

Having raw buffers instead of DispatchData.

On 26 May 2017 at 21:05, Paulo Faria <paulo@zewo.io> wrote:

> In a synchronous setup you usually ‘receive’ (and send) directly into
a buffer and may not even need to allocate it on the heap. In a
asynchronous setup you have to allocate it on the heap, because - well,
the reference/buffer needs to stay until the receive is completed. Well,
and, DispatchData is a heap object optimized for that. Though I don’t know
why this isn’t integrated with Data.

What I mean is.. Nothing is stopping one to hold the reference to the
buffer, right? I mean, having buffers don't make async APIs impossible.

On 26 May 2017 at 20:54, Helge Heß via swift-server-dev < >> swift-server-dev@swift.org> wrote:

On May 27, 2017, at 1:19 AM, Paulo Faria <paulo@zewo.io> wrote:
> I'm not sure I follow your example. Cat.Animal doesn't make much sense
to me while Animal.Cat makes perfect sense.

Precisely. Name it after the concrete thing, not after the abstract
concept.

> When importing HTTP you know you'll deal with HTTP requests and not
anything else.

HTTP servers don’t exist in the void. Your endpoint is going to do
something, e.g. some other form of request. In the case of HTTP application
servers this is going to be quite often an: NSFetchRequest ... well, a
CoreData.Query.Request in your API naming convention …

But we can leave it at that. If people think that this is a good idea,
go ahead. I recommend against it.

> most of the APIs are synchronous

If you say so. I notice exactly the reverse ;-) Most of the API in
Node.js is async for sure and good reason.

> > For async you usually need some way to hold on to a buffer, and that
is DispatchData
>
> Sorry can you elucidate that? If you have the pointer, you're holding
the buffer aren't you? I'm not sure I follow the issue.

In a synchronous setup you usually ‘receive’ (and send) directly into a
buffer and may not even need to allocate it on the heap. In a asynchronous
setup you have to allocate it on the heap, because - well, the
reference/buffer needs to stay until the receive is completed. Well, and,
DispatchData is a heap object optimized for that. Though I don’t know why
this isn’t integrated with Data.

hh

>
>
> On 26 May 2017 at 20:09, Helge Heß via swift-server-dev < >>> swift-server-dev@swift.org> wrote:
> On May 27, 2017, at 12:55 AM, Paulo Faria <paulo@zewo.io> wrote:
> > Helge! I agree with most of your suggestions and I'll update my
proposal with them. There's only one I'm not with you and it's about the
HTTP prefix. The example you mentioned could be easily solved by adding
`HTTP.` when referring to the specific type.
> >
> > import HTTP
> > import SOAP
> >
> > let request = HTTP.Request()
> >
> > We have used Request and Response without prefixes for about two
years and not once anyone complained about that. I imagine others who use
the same naming scheme can testify to that.
>
> Having seen such overloading in Java frameworks before I simply
disagree with that. The object in question is plainly a HTTPRequest(Head)
not just some arbitrary request. The ‘HTTP’ really is part of the thing. In
fact the ‘arbitrary’ request could be an NSOperation, providing
functionalities such as pause, cancel, etc.
>
> In a way it is like
>
> import Cat
>
> let pet = Animal() // resolving to Cat.Animal()
>
> But well, if people really like that … ;-) I vote against it.
>
> > About Sync/Async prefix. I was talking about type prefixes not
method prefixes. We definitely shouldn't prefix function APIs with sync or
async. I honestly don't care too much about which one to use as a default.
I just think it makes more sense to prefix the Async ones.
>
> Your particular setup is sync, right? ;->
>
> > About raw buffers we could provide APIs that take an array of
Unsafe[Mutable]RawBufferPointer to pass them to readv, writev and
company. Those could also be easily converted to DispatchData in the
frameworks that prefer to use it.
>
> This is a little related to sync vs async. For async you usually need
some way to hold on to a buffer, and that is DispatchData. For sync you
usually don’t have to, and pointers to buffers can be faster.
>
> Though I do think that sync is more appropriate for many server
builders, I think that the goal for Swift-Server would be more oriented
towards async. I may be wrong.
>
> hh
>
>
> _______________________________________________
> swift-server-dev mailing list
> swift-server-dev@swift.org
> https://lists.swift.org/mailman/listinfo/swift-server-dev
>
>

_______________________________________________
swift-server-dev mailing list
swift-server-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-server-dev

Swift is still minority in server side and early user are mostly from iOS

and no real complex project AFAIK had built on any of the swift web
framework available yet.

I don't think this is correct. We have swift server software running in
hospitals. But anyway, I'm OK with adding the prefixes if that's the
consensus.

HTTPVersion
HTTPHeaders
HTTPHeaders.Field
HTTPRequest
HTTPRequest.Method
HTTPResponse
HTTPResponse.Status

I just think HTTP.HTTPRequest is quite weird (that *is* the full name of
the type anyway).

···

On 26 May 2017 at 21:47, Paulo Faria <paulo@zewo.io> wrote:

I updated my proposal according to Helge's suggestions. I really think we
can settle the following APIs very quickly:

Version
Headers
Message
Request
Request.Method
Response
Response.Status

Apart from naming the properties are identical to what Carl proposed.
Helge didn't comment anything about URI and Storage. I don't feel strongly
about either one.

https://github.com/paulofaria/http-api-proposal/blob/master/
Sources/HTTP.swift

On 26 May 2017 at 21:06, Paulo Faria <paulo@zewo.io> wrote:

> I mean, having buffers don't make async APIs impossible.

Having raw buffers instead of DispatchData.

On 26 May 2017 at 21:05, Paulo Faria <paulo@zewo.io> wrote:

> In a synchronous setup you usually ‘receive’ (and send) directly into
a buffer and may not even need to allocate it on the heap. In a
asynchronous setup you have to allocate it on the heap, because - well,
the reference/buffer needs to stay until the receive is completed. Well,
and, DispatchData is a heap object optimized for that. Though I don’t know
why this isn’t integrated with Data.

What I mean is.. Nothing is stopping one to hold the reference to the
buffer, right? I mean, having buffers don't make async APIs impossible.

On 26 May 2017 at 20:54, Helge Heß via swift-server-dev < >>> swift-server-dev@swift.org> wrote:

On May 27, 2017, at 1:19 AM, Paulo Faria <paulo@zewo.io> wrote:
> I'm not sure I follow your example. Cat.Animal doesn't make much
sense to me while Animal.Cat makes perfect sense.

Precisely. Name it after the concrete thing, not after the abstract
concept.

> When importing HTTP you know you'll deal with HTTP requests and not
anything else.

HTTP servers don’t exist in the void. Your endpoint is going to do
something, e.g. some other form of request. In the case of HTTP application
servers this is going to be quite often an: NSFetchRequest ... well, a
CoreData.Query.Request in your API naming convention …

But we can leave it at that. If people think that this is a good idea,
go ahead. I recommend against it.

> most of the APIs are synchronous

If you say so. I notice exactly the reverse ;-) Most of the API in
Node.js is async for sure and good reason.

> > For async you usually need some way to hold on to a buffer, and
that is DispatchData
>
> Sorry can you elucidate that? If you have the pointer, you're holding
the buffer aren't you? I'm not sure I follow the issue.

In a synchronous setup you usually ‘receive’ (and send) directly into a
buffer and may not even need to allocate it on the heap. In a asynchronous
setup you have to allocate it on the heap, because - well, the
reference/buffer needs to stay until the receive is completed. Well, and,
DispatchData is a heap object optimized for that. Though I don’t know why
this isn’t integrated with Data.

hh

>
>
> On 26 May 2017 at 20:09, Helge Heß via swift-server-dev < >>>> swift-server-dev@swift.org> wrote:
> On May 27, 2017, at 12:55 AM, Paulo Faria <paulo@zewo.io> wrote:
> > Helge! I agree with most of your suggestions and I'll update my
proposal with them. There's only one I'm not with you and it's about the
HTTP prefix. The example you mentioned could be easily solved by adding
`HTTP.` when referring to the specific type.
> >
> > import HTTP
> > import SOAP
> >
> > let request = HTTP.Request()
> >
> > We have used Request and Response without prefixes for about two
years and not once anyone complained about that. I imagine others who use
the same naming scheme can testify to that.
>
> Having seen such overloading in Java frameworks before I simply
disagree with that. The object in question is plainly a HTTPRequest(Head)
not just some arbitrary request. The ‘HTTP’ really is part of the thing. In
fact the ‘arbitrary’ request could be an NSOperation, providing
functionalities such as pause, cancel, etc.
>
> In a way it is like
>
> import Cat
>
> let pet = Animal() // resolving to Cat.Animal()
>
> But well, if people really like that … ;-) I vote against it.
>
> > About Sync/Async prefix. I was talking about type prefixes not
method prefixes. We definitely shouldn't prefix function APIs with sync or
async. I honestly don't care too much about which one to use as a default.
I just think it makes more sense to prefix the Async ones.
>
> Your particular setup is sync, right? ;->
>
> > About raw buffers we could provide APIs that take an array of
Unsafe[Mutable]RawBufferPointer to pass them to readv, writev and
company. Those could also be easily converted to DispatchData in the
frameworks that prefer to use it.
>
> This is a little related to sync vs async. For async you usually need
some way to hold on to a buffer, and that is DispatchData. For sync you
usually don’t have to, and pointers to buffers can be faster.
>
> Though I do think that sync is more appropriate for many server
builders, I think that the goal for Swift-Server would be more oriented
towards async. I may be wrong.
>
> hh
>
>
> _______________________________________________
> swift-server-dev mailing list
> swift-server-dev@swift.org
> https://lists.swift.org/mailman/listinfo/swift-server-dev
>
>

_______________________________________________
swift-server-dev mailing list
swift-server-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-server-dev

Hi Carl

  This email thread isn’t about an API proposal. It’s about a prototype implementation of an API that was already proposed and discussed a month and a half ago. The prototype isn't a full-featured framework like Vapor or Kitura, but it does actually work and it even has XCTests with decent (>75%) code coverage.

I see, I was confused by the email contents instead of reading the subject and thought we are finally implementing some code. TBH, I don’t see any reason why this should not move to swift-server on github, It sounds a good start to me.
Thank you guys’ hard work for building it.

  Also, please note that I didn’t play any part in proposing this API back in March/April - it’s not “Carl’s proposal.” I just took the existing API that the group had previously discussed and implemented enough of it so that we could measure the utility and performance of the API as proposed and so that we could have better informed discussions about potential alternatives.

You’re right. it was Johannes’ proposal, I’m so sorry for that.

Michael.

I just think HTTP.HTTPRequest is quite weird (that *is* the full name of the type anyway).

Was there a discussion on the module name yet? I would assume it to be more like S3.HTTPRequest, alongside the other protocols. Or is there even an explicit module, or just an abstract API?

I think you really need to distinguish between modules (‘products’) and type names (yes, there is a overlap, but don’t abuse it).

I’m not against namespaces, but that would be

  enum HTTP {
    class Request {
      ..
    }
  }

This seems reasonable to me (apart from Swift lacking a `namespace` type which makes it look a little funny ;-). It separates the names like you desire, but still requires explicit naming unless you extend the type (in that case you can refer to the shortname).

I'm OK with adding the prefixes if that's the consensus

It is Friday night and there about 3 opinions on that. Give it some time …

I really think we can settle the following APIs very quickly.

That seems pretty optimistic given the past discussions. No protocols, structs, enums, etc. It may be what we end up with, but I don’t particularly like it :-) It still makes sense as a basis to go forward from.

> Swift is still minority in server side and early user are mostly from iOS and no real complex project AFAIK had built on any of the swift web framework available yet.

I don't think this is correct.

Right. We are delivering hundreds of cows via Server Side Swift for quite a long time. That’s no easy beef!

It is a matter of fact that Swift is _tiny_ on the server side, but hey, presumably most of us are here to change that! ;-> It would be plain stupid to ignore experiences w/ other languages/frameworks and it makes more sense to look at those than at the few Swift deployments by early adaptors (yeah, no need to ignore those either).

hh

···

On May 27, 2017, at 2:50 AM, Paulo Faria <paulo@zewo.io> wrote:

I'm just proposing we move the code incrementally. The "most consentual"
list I sent yesterday isn't radically different from the code Johannes
proposed. I really don't want to discuss this over and over, ad infinitum.
The most important in the messages I sent before is that we need a well
defined process. We don't have it. Just taking the first implementation,
with a lot of things that admitedly don't fit the scope, and adding that so
we can rework doesn't feel right to me. I'm actually confused about the
scope this project is taking. The code there explicitly mentions a WebApp,
which is a higher responsibility than HTTP. When we started this project
the scope as very clear. Crypto/TLS, Socket, HTTP. A well designed HTTP
module shouldn't depend *at all* on the socket implementation. Providing an
implementation would be just a matter of injecting a dependency. Moving
that code as is to the org really doesn't feel right to me. All I'm saying
is that we definitely should start having code on the org. But I say we
move first Version, Headers, Message, Request, Response. And again, the
"least controversial" I sent yesterday isn't radically strange. It's an
evolution of Johaness original proposal, plus Carl's, plus Helge's
suggestions, plus my suggestions. The only thing I added that wasn't
discussed before is HTTPHeader.Field which does a case insensitive
comparison in its equatable implementation, and the Message protocol which
holds the properties common to request and response (version and headers).
If we can't agree on that, which is the sum of everything that was
discussed about these particular types. How can we agree on that full
implementation?

···

On May 27, 2017 05:13, "Michael Chiu" <hatsuneyuji@icloud.com> wrote:

Hi Carl

> This email thread isn’t about an API proposal. It’s about a
prototype implementation of an API that was already proposed and discussed
a month and a half ago. The prototype isn't a full-featured framework like
Vapor or Kitura, but it does actually work and it even has XCTests with
decent (>75%) code coverage.

I see, I was confused by the email contents instead of reading the subject
and thought we are finally implementing some code. TBH, I don’t see any
reason why this should not move to swift-server on github, It sounds a good
start to me.
Thank you guys’ hard work for building it.

> Also, please note that I didn’t play any part in proposing this
API back in March/April - it’s not “Carl’s proposal.” I just took the
existing API that the group had previously discussed and implemented enough
of it so that we could measure the utility and performance of the API as
proposed and so that we could have better informed discussions about
potential alternatives.

You’re right. it was Johannes’ proposal, I’m so sorry for that.

Michael.

This has clearly sparked a lot more discussion about the API surface,
which is a good thing. Equally we need to progress this towards having a
concrete solution.

Whilst I agree with Paulo's proposal to iterate through the types and APIs
over the coming weeks, I believe we need to do this on a working
implementation rather than abstract definitions (even if those definitions
are code).

What's in the carlbrown/HTTPSketch repo is the result of our last round of
abstract discussions, plus a couple of very minor modifications - we could
revert those before moving over to swift-server, but there's probably
little value in that as we're going to crawl through everything that's
there and debate it all anyway!

As part of moving it over, I'll also try to capture a list of all of the
discussion points from the mailing list and from Paulo's README so that we
make sure we discuss and check off each item.

Chris

···

From: Michael Chiu via swift-server-dev <swift-server-dev@swift.org>
To: Carl Brown <carl.brown.swift@linuxswift.com>
Cc: Paulo Faria via swift-server-dev <swift-server-dev@swift.org>
Date: 27/05/2017 09:13
Subject: Re: [swift-server-dev] Prototype of the discussed HTTP API
Spec
Sent by: swift-server-dev-bounces@swift.org

Hi Carl

               This email thread isn’t about an API proposal. It’s about

a prototype implementation of an API that was already proposed and
discussed a month and a half ago. The prototype isn't a full-featured
framework like Vapor or Kitura, but it does actually work and it even has
XCTests with decent (>75%) code coverage.

I see, I was confused by the email contents instead of reading the subject
and thought we are finally implementing some code. TBH, I don’t see any
reason why this should not move to swift-server on github, It sounds a
good start to me.
Thank you guys’ hard work for building it.

               Also, please note that I didn’t play any part in

proposing this API back in March/April - it’s not “Carl’s proposal.” I
just took the existing API that the group had previously discussed and
implemented enough of it so that we could measure the utility and
performance of the API as proposed and so that we could have better
informed discussions about potential alternatives.

You’re right. it was Johannes’ proposal, I’m so sorry for that.

Michael.

_______________________________________________
swift-server-dev mailing list
swift-server-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-server-dev

Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number
741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU

I don't quite see why we need (or should even offer) a synchronous API for anything that involves IO (disk, network, ...). Sure, many of us would like to have a synchronous and non-blocking programming model, that'd be great. Today in Swift unfortunately we can only go asynchronous&non-blocking or synchronous&blocking (causing undefined behaviour [1] with setjmp/longjmp to get synchronous&non-blocking is cool but certainly not supported today).

I’m a bit confused here, synchronous&non-blocking can be done by kqueue/epoll/select/poll in swift.

It is true that kqueue and epoll are some low level C API but not having synchronous API basically screwed everyone who prefer to do their own scheduling for whatever reason.

Michael

Regarding that. I'm fine with not providing synchronous APIs, right now. As
long as we design the APIs in a way that adding those later becomes
natural. (I *really* *really* hope we get support for coroutines in Swift
5). That's my only concern.

About the undefined behaviour regarding setjmp/longjmp. Interestingly, I've
been using libmill/libdill (provides coroutines with context switching
using assembly instead of setjmp/longjmp) with Zewo for the past 2 years.
And we never once had a problem with that.