# SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie # SPDX-License-Identifier: MIT """The demonstration server, judged by an implementation that is not this one. `tests/e2e.zig` checks what this server does with a given sequence of octets, far more thoroughly than this can, and `tests/fuzz.zig` checks that what comes back is always well-formed. What neither can check is whether anybody else agrees: every assertion in those files is this library reading what this library wrote, and a framing mistake that is self-consistent passes both. Python's `websockets` is the implementation to be judged by. It is strict, it is widely deployed, and it reports a framing disagreement as an exception rather than quietly recovering from it -- which is what makes it useful here. The last few checks drop to a raw socket, because the whole point of them is to send frames a conformant client will not. """ import asyncio import socket import struct import sys from websockets.asyncio.client import connect from websockets.exceptions import ConnectionClosedError, InvalidStatus URL = "ws://server:8080" def check(name): print(f" ok: {name}", flush=True) async def text_and_binary(): async with connect(f"{URL}/echo") as ws: await ws.send("hello") assert await ws.recv() == "hello" check("a text message comes back as text") await ws.send(b"\x00\x01\xfe\xff") got = await ws.recv() assert got == b"\x00\x01\xfe\xff", got # The distinction is carried by the opcode, not guessed from the # bytes: a server that answered binary with text would hand a Python # caller a `str` here and the assertion above would already have # failed on the decode. assert isinstance(got, bytes), type(got) check("a binary message comes back as binary, still binary") await ws.send("") assert await ws.recv() == "" check("an empty message is a message") async def sizes(): async with connect(f"{URL}/echo", max_size=None) as ws: # Every boundary in RFC 6455 5.2's three length forms: 125 is the # last that fits in the seven-bit field, 126 the first that needs the # two-octet one, 65535 the last it holds and 65536 the first that # needs the eight-octet one. 65536 is also exactly the demonstration # server's buffer, so it is the largest message it will take -- one # octet more is `oversized_message_is_refused` below. for size in (0, 1, 125, 126, 127, 65535, 65536): payload = "x" * size await ws.send(payload) got = await ws.recv() assert got == payload, f"{size}: got {len(got)} octets" check("every boundary of the three payload length forms") async def fragments(): async with connect(f"{URL}/echo") as ws: # `send` with an iterable fragments the message across frames, which # is the thing a server has to reassemble. It comes back as one # message or the server did not. await ws.send(["Hel", "lo", ", world"]) assert await ws.recv() == "Hello, world" check("a fragmented message is reassembled") # A code point split across the boundary, which is why UTF-8 has to be # validated on the message and not on each frame. await ws.send([b"\xf0\x9f", b"\x92\xa9"], text=True) assert await ws.recv() == "\U0001f4a9" check("a code point split across two frames survives") async def control_frames(): async with connect(f"{URL}/echo") as ws: pong = await ws.ping(b"round trip") await asyncio.wait_for(pong, timeout=5) check("a ping comes back as a pong") # And the connection still works afterwards, which it would not if the # control frame had been assembled into the message buffer. await ws.send("still here") assert await ws.recv() == "still here" check("a control frame does not disturb the conversation") async def ping_during_fragments(): async with connect(f"{URL}/echo") as ws: # RFC 6455 5.5: "Control frames can be interjected in the middle of a # fragmented message." Sent by hand, because the client library sends # a fragmented message in one call and leaves no room to interleave. await ws.send(["part one ", "part two"]) pong = await ws.ping(b"interleaved") await asyncio.wait_for(pong, timeout=5) assert await ws.recv() == "part one part two" check("a ping alongside a fragmented message") async def closing(): async with connect(f"{URL}/echo") as ws: await ws.send("last words") assert await ws.recv() == "last words" await ws.close(code=1000, reason="done") # The client sees the server's echo of its code, which is what finishes # the closing handshake of RFC 6455 7.1.2. assert ws.close_code == 1000, ws.close_code check("the closing handshake completes with the code echoed") async def subprotocols(): async with connect(f"{URL}/chat", subprotocols=["chat.v1"]) as ws: assert ws.subprotocol == "chat.v1", ws.subprotocol await ws.send("hi") assert await ws.recv() == "hi" check("a subprotocol the client offered is negotiated") # The server prefers chat.v2, and gets it when the client offers both. async with connect(f"{URL}/chat", subprotocols=["chat.v1", "chat.v2"]) as ws: assert ws.subprotocol == "chat.v2", ws.subprotocol check("the server's preference decides between two the client offered") # And one it does not speak gets no subprotocol rather than a refusal. async with connect(f"{URL}/chat", subprotocols=["nothing.like.it"]) as ws: assert ws.subprotocol is None, ws.subprotocol check("a subprotocol nobody speaks is answered without one") async def binary_to_a_text_endpoint(): # `/chat` speaks text only and says so with 1003 rather than dropping it. async with connect(f"{URL}/chat") as ws: await ws.send(b"\x00\x01\x02") try: await asyncio.wait_for(ws.recv(), timeout=5) raise AssertionError("expected the connection to be closed") except ConnectionClosedError as err: assert err.rcvd.code == 1003, err.rcvd check("a binary message to a text endpoint is refused with 1003") async def not_a_websocket(): # A handler that never calls `accept` cannot be upgraded by a client # asking nicely: it answers the request as the ordinary GET it also is. # The property is that the status is not 101 -- a server that switched # protocols here would leave the client speaking WebSocket at something # that is speaking HTTP. try: async with connect(f"{URL}/count"): raise AssertionError("expected no protocol switch") except InvalidStatus as err: assert err.response.status_code == 200, err.response.status_code check("a route that never upgrades answers as ordinary HTTP") # And one that does upgrade, asked by something that is not offering to, # says so with 426 rather than half-succeeding. body = await asyncio.get_running_loop().run_in_executor(None, plain_get, "/echo") assert body.startswith("HTTP/1.1 426 "), body[:64] check("a WebSocket route asked without an offer answers 426") def plain_get(path): s = socket.create_connection(("server", 8080), timeout=10) s.sendall(f"GET {path} HTTP/1.1\r\nHost: server\r\n\r\n".encode()) data = b"" while b"\r\n\r\n" not in data: chunk = s.recv(4096) if not chunk: break data += chunk s.close() return data.decode("latin-1") # -- the frames a conformant client will not send --------------------------- def raw_handshake(path="/echo"): """An opening handshake by hand, leaving a socket with frames to come.""" s = socket.create_connection(("server", 8080), timeout=10) s.sendall( f"GET {path} HTTP/1.1\r\n" "Host: server\r\n" "Upgrade: websocket\r\n" "Connection: Upgrade\r\n" "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n" "Sec-WebSocket-Version: 13\r\n" "\r\n".encode() ) head = b"" while b"\r\n\r\n" not in head: chunk = s.recv(4096) assert chunk, "the server closed during the handshake" head += chunk assert head.startswith(b"HTTP/1.1 101 "), head[:64] # The token from RFC 6455 1.3, which is the one this key determines. assert b"s3pPLMBiTxaQ9kYGzzhZRbK+xOo=" in head, head return s, head.split(b"\r\n\r\n", 1)[1] def read_close_code(s, already=b""): """The close code from the next frame the server sends.""" data = already while len(data) < 4: chunk = s.recv(4096) if not chunk: break data += chunk assert len(data) >= 4, f"expected a close frame, got {data!r}" assert data[0] == 0x88, f"expected a close frame, got opcode {data[0] & 0x0f}" # A server never masks, so the payload starts at octet two. return struct.unpack(">H", data[2:4])[0] def masked(opcode, payload, fin=True): first = (0x80 if fin else 0) | opcode key = b"\x37\xfa\x21\x3d" out = bytes([first]) if len(payload) < 126: out += bytes([0x80 | len(payload)]) else: out += bytes([0x80 | 126]) + struct.pack(">H", len(payload)) out += key out += bytes(b ^ key[i % 4] for i, b in enumerate(payload)) return out def unmasked_frame_is_refused(): s, rest = raw_handshake() # RFC 6455 5.1: "The server MUST close the connection upon receiving a # frame that is not masked." The rule is why a browser cannot be used to # write chosen bytes into a proxy's stream. s.sendall(b"\x81\x05Hello") assert read_close_code(s, rest) == 1002 s.close() check("an unmasked frame from a client is refused with 1002") def bad_utf8_is_refused(): s, rest = raw_handshake() s.sendall(masked(0x1, b"\xff\xfe")) assert read_close_code(s, rest) == 1007 s.close() check("a text message that is not UTF-8 is refused with 1007") def reserved_opcode_is_refused(): s, rest = raw_handshake() s.sendall(masked(0x3, b"")) assert read_close_code(s, rest) == 1002 s.close() check("an opcode nobody has defined is refused with 1002") def reserved_bit_is_refused(): s, rest = raw_handshake() # FIN + RSV1 + text, with no extension negotiated. s.sendall(b"\xc1\x80\x00\x00\x00\x00") assert read_close_code(s, rest) == 1002 s.close() check("a reserved bit is refused with 1002") def oversized_message_is_refused(): s, rest = raw_handshake() # The demonstration server's buffer is 64 KiB. s.sendall(masked(0x1, b"x" * 200)) # fine s.recv(4096) big = b"x" * 70000 first = bytes([0x81, 0x80 | 127]) + struct.pack(">Q", len(big)) key = b"\x00\x00\x00\x00" s.sendall(first + key + big) assert read_close_code(s) == 1009 s.close() check("a message larger than the server's buffer is refused with 1009") # -- the same thing over HTTP/2, through RFC 8441 --------------------------- def websocket_over_http2(): """A WebSocket on one stream of an HTTP/2 connection. `h2` is a real HTTP/2 implementation with its own HPACK, which is what makes this worth doing: `tests/h2.zig` drives the same path with a client written by hand in the same repository, and a mistake shared between the two would pass there and fail here. It also checks the negotiation for us without being asked. `h2` refuses to send a `:protocol` pseudo-header unless the peer's SETTINGS actually carried `ENABLE_CONNECT_PROTOCOL`, so reaching the end of this function at all is a statement that the server advertised it. """ import h2.config import h2.connection import h2.events sock = socket.create_connection(("server", 8080), timeout=10) conn = h2.connection.H2Connection( config=h2.config.H2Configuration(client_side=True, header_encoding="utf-8") ) conn.initiate_connection() sock.sendall(conn.data_to_send()) def pump(): """Read once and hand the events back.""" data = sock.recv(65536) assert data, "the server closed the connection" events = conn.receive_data(data) out = conn.data_to_send() if out: sock.sendall(out) return events # Wait for the server's SETTINGS, which is where the permission to send # `:protocol` comes from. enabled = False while not enabled: for event in pump(): if isinstance(event, h2.events.RemoteSettingsChanged): enabled = conn.remote_settings.enable_connect_protocol == 1 check("the server advertises SETTINGS_ENABLE_CONNECT_PROTOCOL") # RFC 8441 5.1's request. `:scheme` and `:path` are required beside # `:protocol`, which is what makes this different from a plain CONNECT. conn.send_headers( 1, [ (":method", "CONNECT"), (":protocol", "websocket"), (":scheme", "http"), (":authority", "server"), (":path", "/echo"), ], end_stream=False, ) sock.sendall(conn.data_to_send()) status = None while status is None: for event in pump(): if isinstance(event, h2.events.ResponseReceived): status = dict(event.headers)[":status"] # A 2xx, not a 101: over HTTP/2 there is nothing to switch, and the stream # is the tunnel as soon as the status goes out. assert status == "200", status check("an extended CONNECT is answered 200 and the stream becomes a tunnel") # And now it is WebSocket, in DATA frames. The same masked "Hello" from # RFC 6455 5.7 that the HTTP/1.1 checks above use. conn.send_data(1, masked(0x1, b"Hello")) sock.sendall(conn.data_to_send()) body = b"" while len(body) < 7: for event in pump(): if isinstance(event, h2.events.DataReceived): body += event.data conn.acknowledge_received_data(event.flow_controlled_length, 1) sock.sendall(conn.data_to_send()) assert body == b"\x81\x05Hello", body check("a WebSocket message travels over HTTP/2 and comes back") # RFC 8441 5: "Orderly TCP-level closures are represented as END_STREAM # flags." So a WebSocket Close still travels as a Close frame, inside a # DATA frame, and the stream ends after it. conn.send_data(1, masked(0x8, struct.pack(">H", 1000))) sock.sendall(conn.data_to_send()) ended = False rest = b"" while not ended: for event in pump(): if isinstance(event, h2.events.DataReceived): rest += event.data if isinstance(event, h2.events.StreamEnded): ended = True assert rest[:1] == b"\x88", rest assert struct.unpack(">H", rest[2:4])[0] == 1000, rest check("the closing handshake ends the stream, not the connection") sock.close() async def main(): print("websocket interoperability:", flush=True) await text_and_binary() await sizes() await fragments() await control_frames() await ping_during_fragments() await closing() await subprotocols() await binary_to_a_text_endpoint() await not_a_websocket() print("the same thing over HTTP/2:", flush=True) websocket_over_http2() print("frames a conformant client will not send:", flush=True) unmasked_frame_is_refused() bad_utf8_is_refused() reserved_opcode_is_refused() reserved_bit_is_refused() oversized_message_is_refused() print("all interoperability checks passed", flush=True) if __name__ == "__main__": try: asyncio.run(main()) except Exception: import traceback traceback.print_exc() sys.exit(1)