chez-websocket

• Chez WebSocket

[[https://github.com/Kiyomi-Computation-Systems/chez-websocket/actions/workflows/ci.yml][https://github.com/Kiyomi-Computation-Systems/chez-websocket/actions/workflows/ci.yml/badge.svg]]

WebSocket (RFC 6455) for [[https://github.com/Kiyomi-Computation-Systems/chez-http-server][chez-http-server]], the HTTP/1.1 server for Chez Scheme.

#+begin_quote ✨ AI Disclosure: LLMs are used extensively in the planning and development of this project. #+end_quote

** Features

• WebSockets from a handler. A chez-http-server handler takes a WebSocket by answering what websocket-accept returns. Its procedure reads with websocket-receive, which waits, and writes with websocket-send! and websocket-close!.
• Whole messages. A message arrives whole, a string for text and a bytevector for binary, however the client split it into frames. Text is checked as UTF-8 as it comes.
• Checked handshakes. A bad handshake is refused before your procedure runs, and a browser's page from another site is refused 403 unless you name its origin. A subprotocol is chosen from your list.
• Bounded by default. The message size, the queue of messages waiting, the ping and close timeouts and the unsent bytes each have a default and an environment override (see [[file:docs/configuration.md][docs/configuration.md]]).
• Slow and silent clients. A send waits while the client is behind, and a client that stops reading is cut off after a timeout. Pings are answered for you, and a quiet client is pinged, then closed with 1011 if no pong comes.
• A pure core. SHA-1, base64, UTF-8, the frame codec, the protocol and the handshake are pure libraries: steps that read no clock and do no I/O. A binding runs them over the server's transport. An idle connection costs the server about 5.6 KB.
• Tested against the real thing. [[https://github.com/crossbario/autobahn-testsuite][Autobahn|Testsuite]]'s 301 cases, without compression, run in CI against an echo server built from the library, and each case's verdict is held. RFC test vectors, Chrome's handshakes, and values computed by Python, Node, Perl, OpenSSL and ws check each part.

No compression and no client: this library is for servers. The API may change in any release before 1.0. [[file:CHANGELOG.md][CHANGELOG.md]] lists what each release changes.

** Quick start

#+begin_src scheme (import (rnrs) (http-server) (websocket))

(serve (lambda (request) (if (string=? (request-path request) "/echo") (websocket-accept request (lambda (ws) (let loop () (websocket-send! ws (websocket-receive ws)) (loop)))) (make-response 404 #f '() (string->utf8 "not found\n"))))) #+end_src

Save it as echo.sps, start it with make run PROGRAM=echo.sps, and connect a client such as websocat ws://127.0.0.1:8080/echo: each line you send comes back. How a handler reads, writes and closes is in [[file:docs/handlers.md][docs/handlers.md]], and the rest of the documentation starts at [[file:docs/README.md][docs/README.md]], also published at [[https://kiyomi-computation-systems.github.io/chez-websocket/][kiyomi-computation-systems.github.io/chez-websocket]].

** Build and test

Prerequisites:

• Chez Scheme 10.4.1 or later, threaded build (the binary is chez)
• libuv 1.48 or later that pkg-config can see (brew install libuv, or apt install libuv1-dev on Ubuntu 24.04 or later), plus a C compiler — the chez-libuv shim is built from source. With no libuv, or an older one such as Debian 12's 1.44, chez-libuv builds its own, which needs CMake 3.10 or later
• For make autobahn, Docker

The one dependency, chez-http-server, is a git submodule under vendor/, pinned at a release tag. It carries its own pins: chez-libuv, chez-httparse (with byte-machine), uriparse, and chez-srfi for the tests.

#+begin_src sh git clone https://github.com/Kiyomi-Computation-Systems/chez-websocket.git cd chez-websocket make build # clones the pins, builds the chez-libuv shim, assembles the library path make test # runs every tests/test-*.sps #+end_src

Clone without --recursive: make submodules, which make build runs, clones what the build needs and not the server's own test clients. make help lists every target; make check-pins verifies the server sits at its pin, and each pin it carries where the server records it.

make site renders docs/ into build/site/, the pages GitHub Pages publishes for each release. It needs the system cmark-gfm library (brew install cmark-gfm or apt install cmark-gfm); make check-site fails on a broken link or anchor.

** Autobahn

make autobahn runs Autobahn|Testsuite's fuzzing client in Docker against [[file:tests/autobahn/echo.sps][tests/autobahn/echo.sps]], and fails if any case's verdict differs from [[file:tests/autobahn/verdicts.txt][tests/autobahn/verdicts.txt]], better or worse. Autobahn's image is built for amd64, so Docker emulates it on other machines. On Linux the echo server runs on your machine. On macOS and Windows, whose Docker Desktop has no host network, it runs in a Linux container beside Autobahn: make echo-image builds it, the first time in about four minutes, and make docker-smoke checks it starts and stops.

** Configuration

Every limit has a default and a CHEZ_WS_ environment override, read once as your program starts — see [[file:docs/configuration.md][docs/configuration.md]]. The server's own CHEZ_HTTP_ variables still apply.

** Handlers

How a handler takes a WebSocket, what the handshake refuses, how to read, write and close, what each close means, and how to choose subprotocols, origins and limits of its own — see [[file:docs/handlers.md][docs/handlers.md]].

** Examples

[[file:examples/README.org][examples/]] holds small servers to run and talk to from your browser: an echo, a chat room, and a clock that sends a tick each second. Start one with make run PROGRAM=examples/echo.sps and open http://127.0.0.1:8080/.

** Contributing

[[file:CONTRIBUTING.md][CONTRIBUTING.md]] says how to set up, which checks a pull request must pass, and the house rules.

** Security

Report a vulnerability privately; [[file:SECURITY.md][SECURITY.md]] says how.

** License

© [[https://kiyomicomputation.systems/][Kiyomi Computation Systems LLC]]. Licensed under BSD 3-Clause — see [[file:LICENSE][LICENSE]].