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
+