[undertow-dev] Websocket High Level API

[Stuart Douglas]

Hi guys,

Last night Norman and I had a bit of a talk about what the high level 
Websocket API should look like, and Norman came up with some interfaces 
as a prototype.

So after looking at Norman's prototype I had a bit more of a think about 
what our high level API should look like and this is what I have come up 
with:

https://github.com/stuartwdouglas/undertow/compare/websockets_high_level_api

I have been thinking about the use cases that we want to address with 
the high level API, and when you would want to use the high level API vs 
the low level XNIO API.

My thinking is that in general if you want to use async IO and deal with 
message bytes as soon as they arrive this is covered quite nicely by our 
existing low level API. The high level API should focus on async 
operations involving complete messages, and blocking operations.

The JSR 356 implementation will just be implemented as a fairly thin 
wrapper around our high level API.

Sending:

This is handled by (Text|Binary)FrameSender.

I think there are a few different use cases for the high level API in 
terms of sending messages:

- Complete message async, with a callback on completion
- Complete message blocking
- Complete message blocking with Stream / Writer
- Fragmented versions of all of the above.

There is one use case that is not covered here, and that is sending a 
partial messaged using async IO, as mentioned above the reason why I 
don't think we should have this as part of the high level API is because 
this is essentially what is provided by our low level API.

Receiving:

In terms of receiving I think that we should just have a single handler 
type:

https://github.com/stuartwdouglas/undertow/compare/websockets_high_level_api#diff-5

This just receives complete messages. I think this is preferable to 
having to register 5 different types of handler for every frame type.

These handlers just receive complete messages that are fully buffered.

In terms of fragmented messages I think we should provide 2 ways of 
dealing with them, and have a setting that controls which one is in use:

https://github.com/stuartwdouglas/undertow/compare/websockets_high_level_api#L9R98

If this is true then we will just assemble the fragmented messaged 
automatically and deliver it as 1 logical message. Otherwise they will 
just be delivered as they arrive.

I would have liked to provide a way to receive messages via an 
InputStream / Reader, to provide a way to get around fully buffering 
messaged when using blocking IO, however I can't really think of a nice 
way to do this.

What do you guys think? I know there is still some stuff missing (e.g. 
we need a way to propagate auth and session information from the 
original HTTP request).

Stuart