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.
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! The WebSocket Protocol, RFC 6455: the framing, and both ends of the//! opening handshake.//!//! This is the `websocket` module, which depends on nothing but the standard//! library. The server half of the handshake is `websocket_server`, in//! `server.zig`, because it is written against zig-http; everything below it//! -- the framing, the connection, and `connect` -- is here.//!//! ```zig//! fn chat(req: *http.server.Request, res: *http.server.Response) anyerror!void {//! var buffer: [64 * 1024]u8 = undefined;//! var conn = ws.accept(req, res, .{ .buffer = &buffer }) catch |err| {//! return ws.refuse(res, err);//! };//! while (try conn.receive()) |message| {//! try conn.send(message.kind, message.data);//! }//! }//! ```//!//! That handler -- which needs `websocket_server` for its `accept` -- serves//! WebSocket over HTTP/1.1 and over HTTP/2 without//! knowing which it is doing. The two opening handshakes are different//! documents — RFC 6455 §4.2 and RFC 8441 §5 — and what makes them one//! function here is that zig-http's `Request` describes HTTP semantics rather//! than a wire format, so "did the client offer to switch to this protocol"//! is a question with one answer and two implementations.//!//! Opening a connection as the client is `connect`, and it is in this module//! rather than the server one because it needs no HTTP library: a client is//! sending the first bytes on a fresh connection, §4.1 describes exactly one//! HTTP version, and what comes back is a single response to accept or give//! up on.//!//! ```zig//! var buffer: [64 * 1024]u8 = undefined;//! const result = try ws.connect(&reader, &writer, .{//! .resource = "/mqtt",//! .host = "broker.example:8083",//! .subprotocols = &.{"mqtt"},//! .buffer = &buffer,//! .random = random,//! });//! ```//!//! ## Where the line is drawn//!//! This library speaks the framing; zig-http speaks the *server* handshake's//! HTTP. Everything from `Response.upgrade` onwards is here and nothing before//! it is, which is why the dependency points one way and why WebSocket framing//! is not in zig-http: after the handshake there is no HTTP left, and a//! masked, fragmented, opcode-tagged frame protocol shares not one rule with//! RFC 9110.//!//! ## What is not here//!//! * **No interop test for the client.** The framing is judged by Python's//! `websockets` acting as a client; nothing yet judges `connect` by//! anybody's server.//! * **No `permessage-deflate`** (RFC 7692). No extension is negotiated at//! all, and the handshake never sends `Sec-WebSocket-Extensions`: agreeing//! to an extension whose framing is not implemented would corrupt every//! message after the handshake.//! * **No ping timer and no read deadline.** Both want an `Io` and a task of//! their own, and a handler that wants them knows better than this library//! what they should be.
const std = @import("std");
pub const Connection = @import("Connection.zig");pub const frame = @import("frame.zig");pub const close = @import("close.zig");pub const handshake = @import("handshake_common.zig");
/// The opening handshake as the client: RFC 6455 §4.1. See `connect.connect`.pub const connect_client = @import("connect.zig");/// Open a connection to a server. The client half of the handshake, which/// needs no HTTP library -- see `connect.zig` for why.pub const connect = connect_client.connect;
pub const WriteLock = Connection.WriteLock;
pub const Code = close.Code;pub const Kind = Connection.Kind;pub const Message = Connection.Message;pub const Opcode = frame.Opcode;
test { std.testing.refAllDecls(@This());}