[swift-server-dev] Upgrade

[Cory Benfield]

> On 14 Nov 2017, at 16:13, Helge Heß via swift-server-dev <swift-server-dev at swift.org> wrote:
> 
> Hi,
> 
> I’m wondering how we would want to do Upgrade in the API (e.g. to HTTP/2, or WebSocket, or a CONNECT).
> 
> I can see two options here:
> 
> a) we provide some kind of streaming API, maybe similar to DispatchIO
>   and still maintain the socket connection for the API consumer
> 
> b) we completely give up access to the file descriptor (and pass along
>   data already read).
> 
> The former is probably easier for someone implementing the stuff himself, 
> the latter can have advantages if another lib is being used that works on top of fds (though maybe not because extra data may have been read already).
> 
> In any case we need API for this.
> 
> hh

For low-level APIs, you usually want upgrade to evacuate the file descriptor in all cases. That vastly reduces the scope of the implementation (it only has to manage HTTP/1.1), and is comfortably the easiest thing for subsequent integrators to work with.

However, if the goal is to have a single unified higher-level HTTP API then you actually want to divide upgrade into two worlds: one world for upgrade to protocols that maintain the semantics of HTTP (e.g. HTTP/2), and one for those that don’t (e.g. WebSocket). In the first case, you arguably want to call that an implementation detail: the fact that the underlying wire protocol has changed is of no concern to the user. In the second case, either a) or b) work best depending on your I/O management. If your I/O is blocking or has some kind of global implicit event loop, then just giving access to the FD is fine. Otherwise, a managed stream is usually a better choice, if only because it helps users stay integrated with the application’s overall I/O strategy.

Just my 2¢ though.

Cory