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.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! A WebSocket connection: RFC 6455 §5 and §7, over a byte stream that is no//! longer carrying HTTP.//!//! The stream is whatever `Response.upgrade` handed back — a socket over//! HTTP/1.1, one HTTP/2 stream under RFC 8441 — and this type does not know//! which. That is the whole reason the two live in different libraries: by//! the time anything here runs, there is no HTTP left to speak of.//!//! ## Memory//!//! A message is assembled into a buffer the caller supplies, and its length//! is therefore the largest message this connection will accept: a bigger one//! is refused with `1009 Message Too Big` rather than grown into. How much//! memory a connection costs is the server's policy and not this type's,//! which is the same stance `hpack.Decoder` takes about its scratch space in//! zig-http.//!//! A `Message` points into that buffer and is valid until the next call to//! `receive`. A caller that wants to keep one copies it.//!//! ## What it does on its own//!//! Answers a Ping with a Pong, completes the closing handshake, and reasse//! mbles fragments. Everything else is the caller's: there is no ping timer//! and no read deadline, because both need an `Io` and a task of their own and//! a handler that wants them is better placed to say what they should be.
const std = @import("std");const Io = std.Io;const assert = std.debug.assert;
const frame = @import("frame.zig");const close_codes = @import("close.zig");
const Connection = @This();
pub const Code = close_codes.Code;
pub const Role = enum { /// Reads masked frames and writes unmasked ones (§5.1). server, /// The other way round. `connect.connect` performs the opening handshake /// for this role and returns a connection in it; a caller that obtains a /// stream by some other route can set it by hand. client,};
pub const Kind = enum { text, binary };
pub const Message = struct { kind: Kind, /// Points into the connection's buffer. Valid until the next `receive`. data: []u8,};
pub const Config = struct { /// Whether to answer a Ping with a Pong without troubling the caller. /// /// §5.5.2 makes the Pong a MUST, so switching this off means promising to /// send one by hand. auto_pong: bool = true,
/// Held around every frame written, for a connection read by one task /// and written by another. /// /// `receive` writes: it answers a Ping with a Pong and a Close with a /// Close. So a connection with a task blocked in `receive` and a second /// task sending has two writers, and without this a Pong can land in the /// middle of the other task's frame and corrupt the stream past recovery. /// Null, the default, is right for a connection that is only ever used /// from one task at a time. /// /// The lock covers the whole frame, masking key included, so the /// `random` a client is given is only ever called with it held and does /// not have to be thread-safe itself. write_lock: ?WriteLock = null,};
/// A mutex, and the `Io` to lock it with.pub const WriteLock = struct { io: Io, mutex: *Io.Mutex,};
input: *Io.Reader,output: *Io.Writer,role: Role,config: Config,/// Where a message is assembled, and the largest one that can be.buffer: []u8,/// Masking keys come from here, and only the client role needs one.random: ?std.Random,
state: State = .open,/// The code this endpoint put in the Close frame it sent, if it sent one.sent_code: ?Code = null,/// The code the peer sent, or `.no_status` if its Close frame had no body,/// or `.abnormal` if the stream simply ended. Those last two are exactly/// what §7.4.1 reserves 1005 and 1006 for.peer_code: ?Code = null,/// The peer's reason, pointing into `control_buf`. Valid until the next/// `receive`, which after a close never comes.peer_reason: []const u8 = &.{},
/// Control frames are read here rather than into `buffer`, because §5.5 lets/// one arrive in the middle of a fragmented message and assembling it into/// the message would corrupt it. 125 octets is the most one may carry.control_buf: [frame.max_control_payload_len]u8 = undefined,
/// How much of `buffer` the message in progress occupies.message_len: usize = 0,/// The kind of the message being assembled, or null when none is.message_kind: ?Kind = null,
pub const State = enum { open, /// A Close frame has been sent or received but the handshake is not /// finished. closing, closed,};
pub const Options = struct { input: *Io.Reader, output: *Io.Writer, /// Where messages are assembled; its length is the largest message. buffer: []u8, role: Role = .server, random: ?std.Random = null, config: Config = .{},};
pub fn init(options: Options) Connection { assert(options.buffer.len > 0); // A client masks every frame it sends (§5.3) and the key must be // unpredictable, so there is nothing sensible to do without a source. assert(options.role != .client or options.random != null); return .{ .input = options.input, .output = options.output, .role = options.role, .config = options.config, .buffer = options.buffer, .random = options.random, };}
pub const Error = error{ /// The peer broke the framing rules. A Close frame saying which has /// already gone out; `sent_code` says what it carried. ProtocolViolation, /// A message longer than `buffer`. MessageTooBig, /// A text message that was not valid UTF-8, or a Close frame whose /// reason was not. InvalidPayload, /// The stream ended in the middle of a frame. §7.1.5 calls this an /// abnormal closure; there is nowhere to send a Close frame to. Truncated, /// A control frame payload over the 125 octets §5.5 allows. PayloadTooLong, /// A send on a connection that is closing or closed. /// /// §5.5.1: "The application MUST NOT send any more data frames after /// sending a Close frame." Distinct from `WriteFailed` because it is not /// the stream that failed — it is this endpoint being told it has already /// said goodbye. Closed, /// Writing to the stream failed, so the peer will never hear anything /// more from us. WriteFailed, ReadFailed,};
/// The next message, or null once the connection is closed.////// Ping, Pong and Close are handled here and never returned: a caller writing/// an echo server writes `while (try conn.receive()) |m| try conn.send(...)`/// and is conformant.pub fn receive(c: *Connection) Error!?Message { while (true) { if (c.state == .closed) return null;
const header = (try c.readHeader()) orelse return null;
// §5.2: the reserved bits "MUST be 0 unless an extension is // negotiated that defines meanings for non-zero values". This library // negotiates none — there is no `permessage-deflate` here — so a set // bit means the peer thinks something was agreed that was not, and // every octet after it is suspect. if (header.rsv1 or header.rsv2 or header.rsv3) { return c.fail(.protocol_error, "reserved bit set"); } if (!header.opcode.isDefined()) { return c.fail(.protocol_error, "reserved opcode"); }
// §5.1: "The server MUST close the connection upon receiving a frame // that is not masked." The rule exists to stop a browser being used // to write chosen plaintext into a proxy's stream, and it is one of // the few places where the two roles genuinely differ. const masked = header.mask != null; switch (c.role) { .server => if (!masked) return c.fail(.protocol_error, "unmasked frame"), .client => if (masked) return c.fail(.protocol_error, "masked frame"), }
if (header.opcode.isControl()) { // §5.5: control frames are never fragmented and never longer than // 125 octets. if (!header.fin) return c.fail(.protocol_error, "fragmented control frame"); if (header.payload_len > frame.max_control_payload_len) { return c.fail(.protocol_error, "control frame too long"); } const payload = c.control_buf[0..@intCast(header.payload_len)]; try c.readPayload(header, payload);
switch (header.opcode) { .ping => { if (c.config.auto_pong and c.state == .open) { try c.writeFrame(.pong, payload); } continue; }, // §5.5.3: "A Pong frame MAY be sent unsolicited", and there is // nothing an endpoint is required to do with one. .pong => continue, .close => return c.onClose(payload), else => unreachable, // isControl and isDefined leave three. } }
// A data frame. const kind: ?Kind = switch (header.opcode) { .text => .text, .binary => .binary, .continuation => null, else => unreachable, };
if (kind) |k| { // §5.4: a new data frame while a fragmented message is in // progress is a protocol error — the two would interleave and // there is no way to tell which fragment belongs to which. if (c.message_kind != null) { return c.fail(.protocol_error, "interleaved message"); } c.message_kind = k; c.message_len = 0; } else if (c.message_kind == null) { return c.fail(.protocol_error, "continuation of nothing"); }
const start = c.message_len; const end = start +| @as(usize, @intCast(header.payload_len)); if (end > c.buffer.len) { return c.fail(.message_too_big, "message too big"); } try c.readPayload(header, c.buffer[start..end]); c.message_len = end;
if (!header.fin) continue;
const message: Message = .{ .kind = c.message_kind.?, .data = c.buffer[0..c.message_len], }; c.message_kind = null; c.message_len = 0;
// §5.6: "The 'Payload data' is text data encoded as UTF-8", and §8.1 // says an endpoint that receives one that is not must fail the // connection. Checked on the assembled message rather than frame by // frame, which is the same answer: a code point split across a // fragment boundary is valid in the message and invalid in neither // half on its own. if (message.kind == .text and !std.unicode.utf8ValidateSlice(message.data)) { return c.fail(.invalid_payload, "invalid utf-8"); } return message; }}
/// Sends one whole message.pub fn send(c: *Connection, kind: Kind, data: []const u8) Error!void { if (c.state != .open) return error.Closed; try c.writeFrame(switch (kind) { .text => .text, .binary => .binary, }, data);}
pub fn sendText(c: *Connection, text: []const u8) Error!void { return c.send(.text, text);}
pub fn sendBinary(c: *Connection, bytes: []const u8) Error!void { return c.send(.binary, bytes);}
/// §5.5.2. The payload comes back in the peer's Pong, which is what makes/// this a round-trip measurement rather than just a keepalive.pub fn ping(c: *Connection, payload: []const u8) Error!void { // §5.5: a control frame carries at most 125 octets, and a caller that // asks for more has made a mistake rather than met a broken stream. if (payload.len > frame.max_control_payload_len) return error.PayloadTooLong; if (c.state != .open) return error.Closed; try c.writeFrame(.ping, payload);}
pub fn pong(c: *Connection, payload: []const u8) Error!void { if (payload.len > frame.max_control_payload_len) return error.PayloadTooLong; if (c.state != .open) return error.Closed; try c.writeFrame(.pong, payload);}
/// Starts the closing handshake (§7.1.2).////// After this nothing more may be sent. A caller that wants the handshake/// finished keeps calling `receive` until it returns null, which happens when/// the peer's own Close arrives.pub fn close(c: *Connection, code: Code, reason: []const u8) Error!void { try c.sendClose(code, reason);}
fn sendClose(c: *Connection, code: Code, reason: []const u8) Error!void { assert(code.isSendable()); // §5.5.1 again: one Close and no more. Idempotent rather than an error, // because a handler that closes and then falls out of its loop into a // `defer` that closes again has done nothing wrong. if (c.sent_code != null or c.state == .closed) return; var payload: [frame.max_control_payload_len]u8 = undefined; std.mem.writeInt(u16, payload[0..2], @intFromEnum(code), .big); const len = @min(reason.len, payload.len - 2); @memcpy(payload[2..][0..len], reason[0..len]);
c.sent_code = code; c.state = if (c.state == .open) .closing else .closed; c.writeFrame(.close, payload[0 .. 2 + len]) catch |err| { // The peer is gone. It will not be hearing why, and there is nothing // further to do about that. c.state = .closed; return err; };}
/// Sends a Close frame saying what the peer did wrong and returns the error/// that names it.fn fail(c: *Connection, code: Code, reason: []const u8) Error { // The write is allowed to fail: this is already the unhappy path, and the // error the caller gets should say what the peer did rather than what // happened when we tried to tell it. c.sendClose(code, reason) catch {}; c.state = .closed; return switch (code) { .message_too_big => error.MessageTooBig, .invalid_payload => error.InvalidPayload, else => error.ProtocolViolation, };}
/// §7.1.5 and §5.5.1: what a Close frame means and what has to go back.fn onClose(c: *Connection, payload: []const u8) Error!?Message { // §5.5.1: "If there is a body, the first two bytes of the body MUST be a // 2-byte unsigned integer". One octet is neither a body nor no body. if (payload.len == 1) return c.fail(.protocol_error, "close payload of one octet");
if (payload.len >= 2) { const code: Code = @enumFromInt(std.mem.readInt(u16, payload[0..2], .big)); if (!code.isSendable()) return c.fail(.protocol_error, "reserved close code"); // §5.5.1: the reason is "UTF-8-encoded data". if (!std.unicode.utf8ValidateSlice(payload[2..])) { return c.fail(.invalid_payload, "invalid utf-8 in close reason"); } c.peer_code = code; c.peer_reason = payload[2..]; } else { // No body at all, which is exactly what 1005 is for. c.peer_code = .no_status; }
// §5.5.1: "If an endpoint receives a Close frame and did not previously // send a Close frame, the endpoint MUST send a Close frame in response. // (When sending a Close frame in response, the endpoint typically echos // the status code it received.)" if (c.sent_code == null) { const echo: Code = switch (c.peer_code.?) { // 1005 means "there was no code", so echoing it would be sending // something §7.4.1 forbids on the wire. .no_status => .normal, else => |code| code, }; c.sendClose(echo, "") catch {}; } c.state = .closed; return null;}
/// Reads one frame header, or returns null if the stream ended cleanly at a/// frame boundary.fn readHeader(c: *Connection) Error!?frame.Header { var buf: [frame.max_header_len]u8 = undefined;
// `readSliceShort` rather than `takeArray`, and the difference matters // twice over. It says how many octets it managed, which is what tells a // peer that went away between frames from one that vanished in the middle // of a header — and it does not need the reader to have a buffer, which // the one behind an HTTP/2 stream does not: there, DATA payloads are // copied straight out of the connection's own buffer and the stream's is // empty. A `take` of two octets on such a reader is not a short read, it // is an assertion failure. const got = c.input.readSliceShort(buf[0..2]) catch return error.ReadFailed; if (got == 0) { // Nothing was in the middle of being read, so the peer simply went // away. §7.1.5 calls that an abnormal closure and 1006 is the code // reserved for reporting it to an application. c.peer_code = c.peer_code orelse .abnormal; c.state = .closed; return null; } if (got != 2) return error.Truncated; const first = buf[0..2];
var extra: usize = switch (first[1] & 0x7f) { 126 => 2, 127 => 8, else => 0, }; if (first[1] & 0x80 != 0) extra += 4; if (extra != 0) { c.input.readSliceAll(buf[2..][0..extra]) catch |err| switch (err) { error.EndOfStream => return error.Truncated, error.ReadFailed => return error.ReadFailed, }; }
const parsed = frame.parse(buf[0 .. 2 + extra]) catch |err| switch (err) { error.NonMinimalLength => return c.fail(.protocol_error, "non-minimal length"), error.LengthHighBitSet => return c.fail(.protocol_error, "length high bit set"), }; // Everything the header needed has been read, so it cannot be short. return parsed.?.header;}
fn readPayload(c: *Connection, header: frame.Header, into: []u8) Error!void { assert(into.len == header.payload_len); if (into.len == 0) return; c.input.readSliceAll(into) catch |err| switch (err) { error.EndOfStream => return error.Truncated, error.ReadFailed => return error.ReadFailed, }; if (header.mask) |key| frame.applyMask(key, 0, into);}
fn writeFrame(c: *Connection, opcode: frame.Opcode, payload: []const u8) Error!void { // Uncancelable because a frame is all or nothing: a task canceled // between taking the lock and the flush would leave half a frame on the // stream, which no later frame can recover from. if (c.config.write_lock) |l| l.mutex.lockUncancelable(l.io); defer if (c.config.write_lock) |l| l.mutex.unlock(l.io);
var header: frame.Header = .{ .fin = true, .opcode = opcode, .payload_len = payload.len, }; if (c.role == .client) { var key: [4]u8 = undefined; c.random.?.bytes(&key); header.mask = key; }
var head_buf: [frame.max_header_len]u8 = undefined; c.output.writeAll(header.write(&head_buf)) catch return error.WriteFailed;
if (header.mask) |key| { // Masking transforms the payload, which is the caller's and const, so // it goes out a chunk at a time through a buffer of ours rather than // by copying the whole message. var chunk: [512]u8 = undefined; var at: usize = 0; while (at < payload.len) { const take = @min(chunk.len, payload.len - at); @memcpy(chunk[0..take], payload[at..][0..take]); frame.applyMask(key, at, chunk[0..take]); c.output.writeAll(chunk[0..take]) catch return error.WriteFailed; at += take; } } else { c.output.writeAll(payload) catch return error.WriteFailed; }
// Flushed on every frame. A WebSocket is a conversation and the peer is // usually waiting: a message left in a buffer is a message that has not // been sent, and the deadlock it causes looks like the application being // slow. c.output.flush() catch return error.WriteFailed;}
test "two tasks writing through a write lock keep their frames whole" { // Io.Writer copies a write that fits into its buffer without calling // anything, so a lock taken anywhere below the writer cannot protect it; // it has to be taken around the whole frame, which is what this checks. // A buffer big enough to hold everything makes every write one of those // unprotected copies, which is the case that goes wrong without the lock. const gpa = std.testing.allocator; var threaded: Io.Threaded = .init(gpa, .{}); defer threaded.deinit(); const io = threaded.io();
// Enough that the two tasks overlap every run: at a few hundred they // can finish one after the other and pass without the lock. const rounds = 20000; const text: [300]u8 = @splat('a'); const binary: [40]u8 = @splat('b');
const out = try gpa.alloc(u8, rounds * (text.len + binary.len + 2 * frame.max_header_len)); defer gpa.free(out); var sink: Io.Writer = .fixed(out);
var mutex: Io.Mutex = .init; var unused: [1]u8 = undefined; var writer = Connection.init(.{ .input = undefined, .output = &sink, .buffer = &unused, .config = .{ .write_lock = .{ .io = io, .mutex = &mutex } }, });
const Send = struct { // A group task cannot return an error of its own, so a failed send // is recorded and checked once both have finished. fn run(c: *Connection, kind: Kind, data: []const u8, failed: *std.atomic.Value(bool)) void { for (0..rounds) |_| c.send(kind, data) catch failed.store(true, .release); } }; var failed: std.atomic.Value(bool) = .init(false); var group: Io.Group = .init; try group.concurrent(io, Send.run, .{ &writer, .text, &text, &failed }); try group.concurrent(io, Send.run, .{ &writer, .binary, &binary, &failed }); try group.await(io); try std.testing.expect(!failed.load(.acquire));
// Read it all back as the client would. var input: Io.Reader = .fixed(sink.buffered()); var discard: Io.Writer.Discarding = .init(&.{}); var buf: [1024]u8 = undefined; var prng: std.Random.DefaultPrng = .init(0); var reader = Connection.init(.{ .input = &input, .output = &discard.writer, .buffer = &buf, .role = .client, .random = prng.random(), }); var texts: usize = 0; var binaries: usize = 0; while (reader.receive() catch |err| switch (err) { error.Truncated => null, else => return err, }) |m| switch (m.kind) { .text => { try std.testing.expectEqualSlices(u8, &text, m.data); texts += 1; }, .binary => { try std.testing.expectEqualSlices(u8, &binary, m.data); binaries += 1; }, }; try std.testing.expectEqual(rounds, texts); try std.testing.expectEqual(rounds, binaries);}
test { std.testing.refAllDecls(@This());}