Hi Joakim,
First of all, thank you so much for such a comprehensive list of questions! I'll
try to answer them to the best of my knowledge.
But before, I need to clarify one thing. I've noticed many of the questions are
about lack of some advanced features in the API. Well, they are for sure
negotiable, but let's for now (for initial pass) answer those as "[*]" (to not
repeat the same argument over and over again), which would mean the following:
We have a design goal for this to be a very lightweight API. It focuses on
simplicity and convenience of data exchange -- primary service provided by the
WebSocket protocol. The feature mentioned seems to be an advanced one, and
though might be very useful for other APIs, at first glance doesn't look like
a necessary requirement from our point of view.
> On 31 Aug 2015, at 18:01, Joakim Erdfelt wrote:
>
> - There's 2 ways some of the websocket headers can be declared, and 1 way for
> others.
>Origin - easy enough, only in HttpClient.
This particular header may only be set by an HttpClient.
>Sec-WebSocket-Protocol - easy enough to declare as header in HttpClient,
> but it also exists in WebSocket.Builder (with a nice interface), but what
> happens if both are used?
This is a good question. I think the expected behaviour would be to overwrite
headers specified in the HttpClient with those specified in the
WebSocket.Builder. This should be mentioned explicitly in the javadoc though.
Thanks.
It might be harder to overwrite 'Sec-WebSocket-Extensions' header, since its
values might be spread across several fields. But that's more of a concern from
an implementation point of view rather than from an API's.
Another option would be to throw some sort of unchecked exception. But I think
it's less robust and might not be a good choice here.
>Sec-WebSocket-Extensions - this is tricky to declare correctly, the
> extensions themselves should be the canonical source for a properly formatted
> Extension (with parameters) for this header.
> I think it's a mistake to rely on only String
> here.
> See the history of extension configuration
> strings in the various PMCE specs.
Interesting. Could you please provide any links and/or examples? To be honest, I
suspect most users will simply copy-paste opaque strings with required
extensions' configurations for particular servers and since the syntax is
well-defined, there's nothing to worry about. But yes, I've noticed it's done
differently in other APIs.
There's one more reason that extensions have never been represented by anything
other than strings. As previously mentioned, since the intention is to keep this
API lightweight and as you can see no negotiation process abstraction is
provided, it's basically a single shot action. User states what they need
(subprotocol, extensions, etc.) Then user (hopefully) gets a connection. Then
user checks with accessors (extensions/subprotocol) what's in-use and if, for
some reason, they don't like the result, they simply abandon the WebSocket and
try again differently.
> - Make sure that adding Cookies to the upgrade is bullet-proof, its the
> feature with the most questions on
> stackoverflow (for all languages, even the Javascript WebSocket API)
Thanks. I will keep an eye on that.
> - Errors during upgrade are communicated only via the WebSocket.create() and
> WebSocket.createAsync() exceptions.
> Access to the HTTP Response (headers, and status codes) are very important,
> even when using the
> non HttpClient version via WebSocket.newBuilder(String uri)
So if I understand you correctly you are saying that in case of a failed
negotiation, the Builder should throw an exception with HTTP response fields? Is
that for diagnostics or for some other reason?
> - Add new WebSocket.newBuilder(URI) method for formal URI use
OK. Btw, do you think that String version has a certain value or we are better
without it? In my opinion it looks nicer (shorter) in examples, and removes
additional boilerplate code. But I'm not too sure about real life usage.
> Extensions:
>
> - Extensions should be better formalized, real objects, or at least real
> configuration objects.
> - New extension implementations should be able to be provided.
> - WebSocket.extensions() should have apidoc indicating that it is list of
> extensions that were negotiated during the upgrade.
> - How can someone plug in a new extension implementation?
Initially there were some thoughts on designing an SPI for extensions. But
having analyzed the history and the current state of official extensions these
ideas were set aside. I'm sure you know well that out of 2 official extensions
that hit the RFC road (mux [1], perframe-compress [2]) none succeeded. mux's
been abandoned because of similar features in HTTP/2; after consecutive 5
drafts, perframe-compress turned into PMCE [3] -- a spec for compression
exte
