46 lines
2.1 KiB
Markdown
46 lines
2.1 KiB
Markdown
# WebSocket protocol implementation
|
|
|
|
Seastar includes an experimental implementation of a WebSocket server.
|
|
Refs:
|
|
https://datatracker.ietf.org/doc/html/rfc6455
|
|
https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers
|
|
|
|
## Handlers
|
|
|
|
A WebSocket server needs a user-defined handler in order to be functiomal. WebSocket specification defines a concept of subprotocols, and Seastar WebSocket server allows registering a single handler per subprotocol.
|
|
|
|
Each subprotocol has a unique name and is expected to be sent by the connecting client during handshake,
|
|
by sending a `Sec-Websocket-Protocol` header with the chosen value.
|
|
|
|
Aside from specifying the chosen subprotocol name for a handler, the developer is expected to provide a function
|
|
which handles the incoming stream of data and returns responses into the output stream.
|
|
|
|
Here's an example of how to register a simple echo protocol:
|
|
|
|
```cpp
|
|
using namespace seastar;
|
|
static experimental::websocket::server ws;
|
|
ws.register_handler("echo", [] (input_stream<char>& in, output_stream<char>& out) -> future<> {
|
|
while (true) {
|
|
auto buf = co_await in.read();
|
|
if (buf.empty()) {
|
|
co_return;
|
|
}
|
|
co_await out.write(std::move(buf));
|
|
co_await out.flush();
|
|
}
|
|
});
|
|
```
|
|
|
|
Note: the developers should assume that the input stream provides decoded and unmasked data - so the stream should be treated as if it was backed by a TCP socket. Similarly, responses should be sent to the output stream as is, and the WebSocket server implementation will handle its proper serialization, masking and so on.
|
|
|
|
## Error handling
|
|
|
|
Registered WebSocket handlers can throw arbitrary exceptions during their operation. Currently, exceptions that aren't explicitly handled within the handler will cause the established WebSocket connection to be terminated, and a proper error message will be logged.
|
|
|
|
## Secure WebSocket (wss://)
|
|
|
|
Implementation of Secure WebSocket standard, based on HTTPS is currently work in advanced progress. Once reviewed and merged, this section will contain documentation for it.
|
|
Ref: https://github.com/scylladb/seastar/pull/1044
|
|
|