[swift-server-dev] Prototype of the discussed HTTP API Spec

Sat May 27 01:09:46 CDT 2017

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: http://github.com/Balancingrock
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 at 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 at 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 at 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 at IBM
> Carl.Brown1 at IBM.com (Work)
> Austin, TX
> 
> 
> _______________________________________________
> swift-server-dev mailing list
> swift-server-dev at swift.org
> https://lists.swift.org/mailman/listinfo/swift-server-dev

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-server-dev/attachments/20170527/01d60c52/attachment.html>