Something went wrong. Try again.
The WebSocket Protocol (RFC 6455) for Zig: framing, a client, and a server handshake on zig-http
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430# SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us># 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 comesback is always well-formed. What neither can check is whether anybody elseagrees: every assertion in those files is this library reading what thislibrary wrote, and a framing mistake that is self-consistent passes both.
Python's `websockets` is the implementation to be judged by. It is strict, itis widely deployed, and it reports a framing disagreement as an exceptionrather 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 isto send frames a conformant client will not."""
import asyncioimport socketimport structimport sys
from websockets.asyncio.client import connectfrom 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)