diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-21 11:54:28 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-21 11:54:28 +0000 |
commit | e6918187568dbd01842d8d1d2c808ce16a894239 (patch) | |
tree | 64f88b554b444a49f656b6c656111a145cbbaa28 /src/seastar/doc/websocket.md | |
parent | Initial commit. (diff) | |
download | ceph-e6918187568dbd01842d8d1d2c808ce16a894239.tar.xz ceph-e6918187568dbd01842d8d1d2c808ce16a894239.zip |
Adding upstream version 18.2.2.upstream/18.2.2
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'src/seastar/doc/websocket.md')
-rw-r--r-- | src/seastar/doc/websocket.md | 45 |
1 files changed, 45 insertions, 0 deletions
diff --git a/src/seastar/doc/websocket.md b/src/seastar/doc/websocket.md new file mode 100644 index 000000000..bb7407e51 --- /dev/null +++ b/src/seastar/doc/websocket.md @@ -0,0 +1,45 @@ +# 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 + |