Skip to content

Latest commit

 

History

History
139 lines (115 loc) · 5.44 KB

websocket.md

File metadata and controls

139 lines (115 loc) · 5.44 KB

websocket

A WebSocket client: RFC 6455 in Zig (websocket.Conn). For pages, it gives a WebSocket with the browser's API whose connections Zig makes. So the page's WebSocket:

  • sends any header with the opening handshake (Authorization, Cookie, Origin...);
  • is not subject to the page's Content Security Policy;
  • keeps the messages of a fast server in Zig while the page is behind.

wss: is TLS with the system's certificates. The handshake goes through std.http.Client, and the frames then use its connection.

The package is plugins/websocket (module websocket). It depends on mainthread. See Plugins for adding it to an app.

From pages

const websocket = @import("websocket");

var service: websocket.Service = try .init(gpa, app.io, .{}); // on the main thread
defer service.deinit();
try app.bind(&service);
try app.registerEvent(websocket.PartEvent);
// ... .assets = &.{ index_html, websocket.asset }
import { WebSocket } from "/plugins/websocket.js";

const ws = new WebSocket("wss://example.com/live", ["v1"], {
  headers: { authorization: `Bearer ${token}` },
});
ws.binaryType = "arraybuffer";
ws.onopen = () => ws.send(JSON.stringify({ subscribe: "prices" }));
ws.onmessage = (e) => console.log(e.data);
ws.onclose = (e) => console.log(e.code, e.reason, e.wasClean);

The page's WebSocket has the browser's API, plus a third argument with headers:

  • URLs are ws: and wss:. http: and https: become them, and relative ones resolve against the page's.
  • It has subprotocols (protocol once open), readyState, bufferedAmount (bytes Zig has not written yet) and binaryType.
  • Its events are open, message, error and close.
  • send takes strings, ArrayBuffers, typed arrays and Blobs, sent in order. It throws while connecting. Messages after closing are dropped.
  • close(code, reason) takes 1000 or 3000 to 4999, and a reason of at most 123 bytes.
  • After close, Zig waits close_timeout_ms for the server's close: wasClean, with the server's code and reason. Otherwise it drops the connection (1006).
  • Zig answers pings and reassembles fragmented messages.
  • Zig fails the connection (1002, 1007, 1009) when the server breaks the protocol, sends invalid UTF-8, or sends a message over max_message_size. The page then gets error, then close with 1006, and the console says why.
  • Zig reads no further while the page has more than window_bytes of messages to handle.
  • A page's connections are dropped (going away, 1001) when the page navigates, reloads or closes. This includes those waiting for it to read. service.deinit drops the rest.
  • No extensions (permessage-deflate) are negotiated.

Options

websocket.ServiceOptions:

field default
allow null fn (ctx, url, headers: []const websocket.Header) bool: may refuse a connection
allow_ctx null passed to allow
max_message_size 64 MiB the largest message from a server
close_timeout_ms 5000 how long a closing connection waits for the server's close
window_bytes 1 MiB messages the page may have unhandled before Zig stops reading

Each connection is two tasks on the app's Io. One connects and reads; one writes what the page sends. Their events (myzig-websocket) reach the page through the main thread (mainthread).

From Zig

var client: std.http.Client = .{ .allocator = gpa, .io = io };
defer client.deinit();
const c = try websocket.Conn.connect(&client, gpa, "wss://example.com/live", .{
    .protocols = &.{"v1"},
    .headers = &.{.{ .name = "Authorization", .value = "Bearer ..." }},
});
defer c.deinit();
try c.send(.text, "hello");
switch (try c.read(gpa)) { // blocks: pings are answered, fragments joined
    .text => |t| std.log.info("{s}", .{t}), // allocated with gpa
    .binary => |b| gpa.free(b),
    .close => |cl| std.log.info("closed {d}", .{cl.code}), // the server's close, echoed
}
try c.close(1000, "done"); // then read until .close
  • Options: protocols, headers, max_message_size (64 MiB).
  • send(.text or .binary, data), ping(data), close(code, reason).
  • fail(code) closes at once, as for a protocol error.
  • Reads and writes may run on two threads at once. Writes are serialized.
  • shutdown() stops a blocked read from another thread.
  • websocket.frame is the codec for either end. The example's server uses it as a server.
  • websocket.Code names the close codes.

Example and tests

example/ runs a WebSocket server on 127.0.0.1 and a page that talks to it. The server (example/server.zig) does std.http.Server's handshake, then uses this plugin's frames. zig build run shows it.

cd plugins/websocket
zig build test               # Conn and the frames against the in-process server, and the page, hidden
zig build test -Dpage=false  # without the page
zig build check -Dtarget=x86_64-linux-gnu

The tests cover:

  • RFC 6455's masking example, every length encoding, frames that break the rules, close payloads and the accept key;
  • echo of text and binary messages (200 KB), headers and subprotocols;
  • server-initiated closes, pings, fragmentation with a ping inside;
  • protocol errors, the message limit, refused upgrades and shutdown;
  • the browser API end to end, in the page test.

On Windows the shutdown test prints a stack trace from the standard library, and passes. A debug build reports the socket's PIPE_DISCONNECTED as unexpected.