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

[Paulo Faria]

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 at 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 at 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 at swift.org> wrote:
>>
>>> On May 27, 2017, at 1:19 AM, Paulo Faria <paulo at 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 at swift.org> wrote:
>>> > On May 27, 2017, at 12:55 AM, Paulo Faria <paulo at 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 at swift.org
>>> > https://lists.swift.org/mailman/listinfo/swift-server-dev
>>> >
>>> >
>>>
>>>
>>> _______________________________________________
>>> 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/20170526/12a00bc0/attachment.html>