WebSocket client API

[Simone Bordet]

Hi,

On Fri, Oct 9, 2015 at 3:18 PM, Pavel Rappo <pavel.rappo at oracle.com> wrote:
>> On 8 Oct 2015, at 20:51, Simone Bordet <simone.bordet at gmail.com> wrote:
>> For example, this is going to surprise users (simple echo):
>>
>> onBinary((ws, bytes, last) -> {
>>    ws.sendBinary(bytes, last, null, (_, failure) -> {});
>> }
>
> That would only surprise people who don't read javadoc. Or you
> want to say it's an inherently bad decision to allow people to
> reuse implementation's ByteBuffer?
>
>> It's not going to work because the send is async, and there is no
>> specification about who owns the ByteBuffer "bytes".
>> In my experience, it is bad to force applications to perform a copy
>> (not to mention that the copy could be really expensive, as WebSocket
>> frames could be large).
>
> I wonder what percentage of use cases this scenario corresponds to? Namely, a
> huge payload being received, transformed(?) and sent on the WebSocket. I ask
> this because I have to understand whether the added complexity worth the value
> provided by the functionality.

Allow me put some context around why I keep pushing for a completely async API.

The current API proposal is very low level (and that's ok).

The current API proposal deals with WebSocket frames, not messages.
Take for example the exchange of JSON messages over WebSocket.
The major JSON libraries available out there do not support
asynchronous JSON parsing: they can parse a *whole* JSON (or block
waiting for it), but they cannot parse chunks of it, asynchronously,
threadlessly waiting for the chunks to arrive.
This means that an application will have to recompose the whole JSON
message from the frames it gets from the current API before passing it
to the JSON parser.

The current API proposal requires users to understand what is
backpressure and that behind every invocation of onXXX() methods there
must be a call to WebSocket.request(long) that triggers the read of
more data by the implementation.
And that WebSocket.request(long) must be invoked at the right time to
produce proper backpressure, and this is even more important if the
users use the current API proposal it with some other async libraries
(that may do async socket, file, database, etc. I/O or other async
processing).

Given that the API is so low level, it would be a shame to not provide
that couple of primitives, that currently are not present, that will
make the API cover virtually all use cases and be very efficient.
I specifically refer here to a callback for onXXX() methods and a
better close status report.

With such a low level API, it would then be trivial to lay on top a
Flow-based API that deals with WebSocket messages (not frames) that
most applications may find more palatable.
Not a fan of Flow API ? Any other API can be based on top of a good,
complete, low level API, even a blocking one.

Yet, people that needs low-level, full control, highly efficient,
little-or-no-allocating, non-copying, API will be able to have it (and
build wonderful and efficient things on top of it).

Thanks !

-- 
Simone Bordet
http://bordet.blogspot.com
---
Finally, no matter how good the architecture and design are,
to deliver bug-free software with optimal performance and reliability,
the implementation technique must be flawless.   Victoria Livschitz