// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // 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()); }