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