From 67beb493ea18de9d7b0083ba20b34b8bb34fd74c Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Wed, 4 Nov 2026 23:15:35 -0300 Subject: wire.zig: the replica's wire codec moves from src/detached/, a directory of one file since the phase 3 frontends went, to src/wire.zig; its imports and the paths that name it follow Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNAtZenFv4weoMD3cge --- build.zig | 2 +- docs/typ/building.typ | 4 +- docs/web.md | 2 +- src/daemon.zig | 4 +- src/detached/wire.zig | 975 -------------------------------------------------- src/main.zig | 6 +- src/replica.zig | 6 +- src/wire.zig | 975 ++++++++++++++++++++++++++++++++++++++++++++++++++ test/daemon.py | 2 +- 9 files changed, 988 insertions(+), 988 deletions(-) delete mode 100644 src/detached/wire.zig create mode 100644 src/wire.zig diff --git a/build.zig b/build.zig index a5ae2dee..ebbffaf8 100644 --- a/build.zig +++ b/build.zig @@ -15,7 +15,7 @@ else /// Every dependency the manifest pins, by its content hash: a grammar, /// ghostty or the Unicode tables steps a core differently, so they are part -/// of a replica's semantics hash (src/detached/wire.zig `semantics`). +/// of a replica's semantics hash (src/wire.zig `semantics`). const deps_text = blk: { var text: []const u8 = ""; for (@typeInfo(@TypeOf(zon.dependencies)).@"struct".field_names) |name| { diff --git a/docs/typ/building.typ b/docs/typ/building.typ index 78cdba7e..b4d7cb82 100644 --- a/docs/typ/building.typ +++ b/docs/typ/building.typ @@ -178,7 +178,7 @@ Code map: `src/panes.zig` and the pane kinds it names (`src/File.zig`, mounts and resolution) and `src/pardes.zig` (input), with one file per thing beside them (`edit.zig`, `normal.zig`, `look.zig`, `exec.zig`, `mouse.zig`, ...). `src/ninep/` is the control tree, `src/daemon.zig` the -per-user daemon and a terminal's stub, `src/detached/wire.zig` the input +per-user daemon and a terminal's stub, `src/wire.zig` the input wire a remote client will speak, `src/lsp/` the language-server client; `test/` holds harnesses, goldens and helix cases, `build/` the snapshot suite's build step. @@ -225,7 +225,7 @@ own process, ended by its hangup. A replica (a client running its own copy of the core, phase 5 of `docs/next-daemon.md`) connects to `pardes-replica.sock`, a stream socket -beside it that `ssh -L` can forward. `src/detached/wire.zig` is its +beside it that `ssh -L` can forward. `src/wire.zig` is its protocol (version 14): fixed-width little-endian fields, a 5-byte header (tag, then a u32 length), the hello, a ping, the input events. The hello names a session and carries the client's semantics hash (the protocol, diff --git a/docs/web.md b/docs/web.md index b9d03b13..26646a38 100644 --- a/docs/web.md +++ b/docs/web.md @@ -92,7 +92,7 @@ the browser can never call. same gate: both are `enabled = pardes.hosted` (`src/builtins.zig`, and `pardes.hosted` is `tty or gui or macos`), because a detached session is a unix socket and a page has none. Nothing in this shell speaks -`src/detached/wire.zig`, and `detach` is one of the null vtable methods +`src/wire.zig`, and `detach` is one of the null vtable methods below. `src/web.zig` fills in six methods of `Host.VTable` and leaves the rest null, diff --git a/src/daemon.zig b/src/daemon.zig index fff7bbe5..7d2ca9b4 100644 --- a/src/daemon.zig +++ b/src/daemon.zig @@ -19,14 +19,14 @@ //! //! A replica (docs/next-daemon.md, phase 5) comes in on a stream socket of //! its own, `pardes-replica.sock`, which `ssh -L` can forward: its hello -//! (detached/wire.zig) names a session, and once its build is the session's +//! (wire.zig) names a session, and once its build is the session's //! the connection is handed to that session, which it talks to from then on. const std = @import("std"); const builtin = @import("builtin"); const libc = std.c; const posix = std.posix; const ninep_io = @import("9p_io.zig"); -const wire = @import("detached/wire.zig"); +const wire = @import("wire.zig"); const upgrade = @import("upgrade.zig"); const log = std.log.scoped(.replica); diff --git a/src/detached/wire.zig b/src/detached/wire.zig deleted file mode 100644 index 9d1abee5..00000000 --- a/src/detached/wire.zig +++ /dev/null @@ -1,975 +0,0 @@ -//! The framed stream a replica speaks (docs/next-daemon.md, phase 5), on -//! the daemon's `pardes-replica.sock` and then its session's: fixed-width -//! little-endian fields and explicit tags, the hello and its version, a -//! ping, and the input Events. Native struct layout never reaches the wire. -//! The cell frames that went the other way, and the frontends that drew -//! them, went with phase 3. -const std = @import("std"); -const builtin = @import("builtin"); -const pardes = @import("../pardes.zig"); -const config = @import("pardes_config"); - -/// 19: a client joining again names the view it had in its hello, and a -/// bye says whether it joins again for it (views.away); -/// 18: a replica's input is stamped with its guess of the session's -/// clocks, the time its step reads (phase 6's instant interaction notes); -/// 17: a pointer's hit carries the place it was made on (Layer.Place) and -/// a tag hit its line, which the step resolves it by, not by its frame; -/// 16: a far client says so, the session sends it its blobs' hashes before -/// the rest and only the blobs it asks for, all of it in zstd (phase 6's -/// content cache and zstd notes), and a client says its frontend (a window -/// or a terminal) as its first input, a window replicating a terminal's -/// session and back (phase 6's GUI replica notes); 15: the session streams -/// a replica its dump and units, and terminal deltas both ways (phase 5 -/// part B); 14: the hello names a session and -/// carries the semantics hash, and a ping is answered (phase 5's -/// groundwork); 13: the frames went (phase 3). -pub const version: u16 = 19; - -/// The terminal's build and the window's step alike (`semantics`). -const family = switch (config.platform) { - .tui, .gui => "desktop", - else => @tagName(config.platform), -}; - -/// What makes two cores step differently, hashed: a replica's hello carries -/// its own, and one of another build is refused. The protocol, the release -/// and commit, the platform and build options, every dependency's content -/// hash (grammars, ghostty, Unicode), the walker codec's assumptions -/// (pointer width, byte order) and the tape's shape (tape.shape: what each -/// input and each answer of the host's is laid out as). Not the OS: a Linux -/// client of a FreeBSD session is the main case, and what differs there is -/// the host's, taped, in a shape every OS shares (an error by its name, a -/// stat as fs.OsStat). Nor the build mode: a Debug build steps as a -/// release one does (regexp.zig's one budget). -/// Nor the terminal's build against the window's: their cores step alike, -/// the GUI's own words by the view's frontend (builtins.zig `here`), so a -/// window replicates a terminal's session and a terminal a window's. -/// ponytail: an unstamped build (Debug with -Dplatform, every test build) -/// has no commit, so two dev trees of one release are told apart only by -/// their options and dependencies; -Dstamp-commit stamps one. -pub const semantics: u64 = blk: { - @setEvalBranchQuota(1_000_000); - break :blk std.hash.Wyhash.hash(0, std.fmt.comptimePrint( - "wire {d}\npardes {s} {s}\n{s} grammars {} {} {} {} mupdf {} themes {} workspace_tag {} sources {} board {d}x{d}\nusize {d} {t}\n{s}\n{s}", - .{ - version, config.version, config.commit orelse "unstamped", - family, config.syntax_highlighting, config.syntax_zig_grammar, - config.syntax_minimal_grammars, config.syntax_full_grammars, config.mupdf, - config.theme_animation, config.workspace_tag, config.embed_sources, - config.esp32p4_cols, config.esp32p4_rows, @sizeOf(usize), - builtin.cpu.arch.endian(), config.deps, pardes.tape.shape, - }, - )); -}; - -/// EndOfStream: the message ends early; WriteFailed: no room for it. -/// ReadFailed is in only because std.Io.Reader says so: a fixed one never -/// fails a read. -pub const Error = error{ EndOfStream, ReadFailed, Overlong, BadTag, BadValue, Trailing, WriteFailed }; - -pub const max_cols: u16 = 512; -pub const max_rows: u16 = 128; -pub const max_payload: u32 = 16 << 20; -pub const header_len = 5; // tag:u8, payload length:u32le - -// Stable wire numbers; gaps are retired tags. Unknown tags are rejected by the decoder. -pub const ClientTag = enum(u8) { - hello = 0x01, - bye = 0x02, - ping = 0x03, - /// A replica's word about a terminal's state (src/screen_state.zig): the - /// delta it holds, or rows it asks for. Opaque here. - screen_ack = 0x04, - /// What is the session's digest, in stream order (a replica checks - /// itself against it once quiet). - check = 0x05, - /// A client's first word after its hello: whether it is far (through - /// ssh), so that it holds blobs by their hash and reads zstd. - far = 0x06, - /// The join's blobs a far client lacks, a bit each in `blobs` order. - want = 0x07, - /// The session's clocks (realtime and monotonic, ns) as the client - /// guessed them for the input that follows: its time, which the step - /// reads (src/replica.zig). - stamp = 0x08, - - key = 0x10, - mouse = 0x11, - resize = 0x12, - paste = 0x18, - command = 0x19, - pdf_scroll = 0x1a, - // 0x1b and 0x1c were a pinch and a touch scroll, gone since. - pointer_leave = 0x1d, - focus = 0x1e, - /// Which frontend the client is: a window, or a terminal. - frontend = 0x20, -}; - -const ButtonTag = enum(u8) { - left = 0x00, - middle = 0x01, - right = 0x02, - wheel_up = 0x03, - wheel_down = 0x04, - wheel_left = 0x05, - wheel_right = 0x06, - none = 0x07, - back = 0x08, - forward = 0x09, -}; -const KindTag = enum(u8) { press = 0x00, release = 0x01, motion = 0x02, drag = 0x03 }; - -// --------------------------------------------------------------------------- -// messages -// --------------------------------------------------------------------------- - -/// First message on every connection, and `version` is its first field at a -/// fixed offset for exactly one reason: a mismatch has to be diagnosable even -/// when the rest of the layout is the part that changed. -pub const Hello = struct { - version: u16 = version, - /// The client's `semantics`: the daemon refuses it unless the session's - /// is the same. - semantics: u64 = semantics, - /// Which session (its 9P name, as `--attach=` names it). - session: []const u8, - /// The view it had, joining again for it (a divergence's rejoin, an - /// Upgrade's): the daemon hands it on with the connection. 0xff: none. - view: ?u8 = null, -}; - -/// A session's name on the wire, as the daemon keeps it. -pub const max_name = 128; -/// The longest hello there is, header and all. -pub const hello_max = header_len + 2 + 8 + 2 + max_name + 1; - -/// Daemon or session -> client. -pub const ServerTag = enum(u8) { - /// The hello is accepted and the connection is the session's now: its pid - /// and name. - welcome = 0x01, - /// Refused, said in words; the connection ends. - refused = 0x02, - /// A ping's value back. - pong = 0x03, - /// A piece of the join's dump (src/dump.zig): the welcome says how long - /// it is whole. - dump = 0x04, - /// A unit of the authority's stream (src/replica.zig): its origin, seq, - /// clocks and tape. - unit = 0x05, - /// A terminal's delta, or rows asked for (src/screen_state.zig), applied - /// before the next unit. Opaque here. - screen = 0x06, - /// The session's digest (u64le), after every unit before it. - check = 0x07, - /// Part of the join's list of blobs, to a far client: each one's place - /// in the state, its length and its BLAKE3 hash (src/replica.zig). - blobs = 0x08, - /// A piece of a far client's stream from here on, zstd-compressed: the - /// messages in it are framed as these are. Opaque here. - zstd = 0x09, -}; - -pub const ServerMsg = union(ServerTag) { - /// Who the client is now (its id and view in the session), how long the - /// dump that follows is, and the session's offset from UTC (a replica - /// guesses the session's time of day). A far client is told how many - /// blobs the dump holds (`blobs`). - welcome: struct { pid: u32, session: []const u8, client: u16 = 0, view: u8 = 0, dump_len: u64 = 0, gmtoff: i32 = 0, digest: u64 = 0, semantics: u64 = 0, blobs: u32 = 0 }, - refused: []const u8, - pong: u64, - dump: []const u8, - unit: []const u8, - screen: []const u8, - check: u64, - blobs: []const u8, - zstd: []const u8, -}; - -/// A message's header, for a payload sent on its own (a unit, a dump's -/// piece): no copy of it into a message buffer. -pub fn header(tag: u8, len: usize) [header_len]u8 { - var h: [header_len]u8 = undefined; - h[0] = tag; - std.mem.writeInt(u32, h[1..5], @intCast(len), .little); - return h; -} - -/// The other way: what a client is told, its slices borrowing `payload`. -pub fn decodeServer(tag: u8, payload: []const u8) Error!ServerMsg { - var r: std.Io.Reader = .fixed(payload); - const msg: ServerMsg = switch (std.enums.fromInt(ServerTag, tag) orelse return error.BadTag) { - .welcome => .{ .welcome = .{ - .pid = try r.takeInt(u32, .little), - .session = try r.take(try r.takeInt(u16, .little)), - .client = try r.takeInt(u16, .little), - .view = try r.takeByte(), - .dump_len = try r.takeInt(u64, .little), - .gmtoff = try r.takeInt(i32, .little), - .digest = try r.takeInt(u64, .little), - .semantics = try r.takeInt(u64, .little), - .blobs = try r.takeInt(u32, .little), - } }, - .refused => .{ .refused = try r.take(try r.takeInt(u16, .little)) }, - .pong => .{ .pong = try r.takeInt(u64, .little) }, - .dump => return .{ .dump = payload }, - .unit => return .{ .unit = payload }, - .screen => return .{ .screen = payload }, - .check => .{ .check = try r.takeInt(u64, .little) }, - .blobs => return .{ .blobs = payload }, - .zstd => return .{ .zstd = payload }, - }; - try end(&r); - return msg; -} - -pub fn encodeServer(out: []u8, msg: ServerMsg) Error![]const u8 { - var w: std.Io.Writer = .fixed(out); - const at = try beginMessage(&w, @backingInt(std.meta.activeTag(msg))); - switch (msg) { - .welcome => |h| { - try w.writeInt(u32, h.pid, .little); - try putSlice16(&w, h.session); - try w.writeInt(u16, h.client, .little); - try w.writeByte(h.view); - try w.writeInt(u64, h.dump_len, .little); - try w.writeInt(i32, h.gmtoff, .little); - try w.writeInt(u64, h.digest, .little); - try w.writeInt(u64, h.semantics, .little); - try w.writeInt(u32, h.blobs, .little); - }, - .refused => |words| try putSlice16(&w, words), - .pong => |v| try w.writeInt(u64, v, .little), - .dump, .unit, .screen, .blobs, .zstd => |bytes| try w.writeAll(bytes), - .check => |v| try w.writeInt(u64, v, .little), - } - try finishMessage(&w, at); - return w.buffered(); -} - -/// `Hello.version` alone, read out of the still-undecoded payload. -/// -/// Separate from `decodeClient` because of the guarantee the fixed offset above -/// exists to give: a decoder that validates `cols` and `rows` and then refuses -/// trailing bytes can never deliver it. A v2 hello with one more field would be -/// closed as a malformed message, and the `Refusal.version` byte a frontend -/// needs in order to say something true would never be sent — which is exactly -/// the case the field was put at offset zero for. So the version is asked for -/// first, on its own, before any of the layout that may have moved. -/// -/// An error rather than a zero on a payload shorter than two bytes, so a -/// truncated hello stays diagnosable too instead of reading as version 0. -pub fn helloVersion(payload: []const u8) Error!u16 { - var r: std.Io.Reader = .fixed(payload); - return r.takeInt(u16, .little); -} - -/// Frontend -> core, decoded. The `Event`'s slices BORROW the payload buffer, -/// exactly like the pty chunks the tui host hands to `update`: valid for that -/// one call and no longer. -pub const ClientMsg = union(enum) { - hello: Hello, - /// The client's end: `again`, it joins again for its view at once. - bye: struct { again: bool = false }, - /// A round trip's probe, answered `pong` with the same value. - ping: u64, - screen_ack: []const u8, - check, - far: bool, - want: []const u8, - stamp: [2]i64, - event: pardes.Event, -}; - -// --------------------------------------------------------------------------- -// primitives -// --------------------------------------------------------------------------- - -/// Length-prefixed, u16: paths, command lines, a key's text. Nothing here -/// is legitimately longer than 64 KiB and a u16 says so on the wire. -fn putSlice16(w: *std.Io.Writer, v: []const u8) Error!void { - if (v.len > std.math.maxInt(u16)) return error.Overlong; - try w.writeInt(u16, @intCast(v.len), .little); - try w.writeAll(v); -} - -/// ...and u32 for the ones that are: pty output, a paste, a file. -fn putSlice32(w: *std.Io.Writer, v: []const u8) Error!void { - if (v.len > max_payload) return error.Overlong; - try w.writeInt(u32, @intCast(v.len), .little); - try w.writeAll(v); -} - -/// One byte, 0 or 1, never "nonzero": the writer's `@intFromBool`. -fn getBool(r: *std.Io.Reader) Error!bool { - return switch (try r.takeByte()) { - 0 => false, - 1 => true, - else => error.BadValue, - }; -} - -/// IEEE-754 binary32, as its bit pattern in an explicit u32. A scalar -/// bitcast and not a struct blit: the format is the one thing a riscv32 -/// and an x86_64 do agree about. -fn getF32(r: *std.Io.Reader) Error!f32 { - const v: f32 = @bitCast(try r.takeInt(u32, .little)); - // A NaN or an infinity here is not a scroll distance. - if (!std.math.isFinite(v)) return error.BadValue; - return v; -} - -fn getSlice32(r: *std.Io.Reader) Error![]const u8 { - const n = try r.takeInt(u32, .little); - if (n > max_payload) return error.Overlong; - return r.take(n); -} - -/// A pane id the core can actually index. `Event.output{ .pane = 200 }` -/// would reach `p.panes[200]`. -fn getPane(r: *std.Io.Reader) Error!u8 { - const pane = try r.takeByte(); - if (pane >= pardes.MAX_PANES) return error.BadValue; - return pane; -} - -/// A grid the core can render into. Zero is refused rather than clamped: a -/// frontend that has not been sized yet must not be allowed to collapse a -/// shared session to nothing (see server.zig `geometry`). -fn getCols(r: *std.Io.Reader) Error!u16 { - const v = try r.takeInt(u16, .little); - if (v == 0 or v > max_cols) return error.BadValue; - return v; -} - -fn getRows(r: *std.Io.Reader) Error!u16 { - const v = try r.takeInt(u16, .little); - if (v == 0 or v > max_rows) return error.BadValue; - return v; -} - -fn getTag(r: *std.Io.Reader, comptime T: type) Error!T { - return std.enums.fromInt(T, try r.takeByte()) orelse error.BadTag; -} - -fn end(r: *std.Io.Reader) Error!void { - if (r.seek != r.end) return error.Trailing; -} - -/// Reserve a message header; `finishMessage` back-patches the length. Two -/// passes would mean walking a frame's runs twice to find out how long they -/// are, and the walk is the expensive half. -fn beginMessage(w: *std.Io.Writer, tag: u8) Error!usize { - const at = w.end; - try w.writeByte(tag); - try w.writeInt(u32, 0, .little); - return at; -} - -fn finishMessage(w: *std.Io.Writer, at: usize) Error!void { - const len = w.end - at - header_len; - if (len > max_payload) return error.Overlong; - std.mem.writeInt(u32, w.buffer[at + 1 ..][0..4], @intCast(len), .little); -} - -/// One complete message at the front of a stream buffer, or null when the rest -/// has not arrived. `total` is what the caller consumes. -pub const Framed = struct { tag: u8, payload: []const u8, total: usize }; - -pub fn framed(buf: []const u8) Error!?Framed { - if (buf.len < header_len) return null; - const len = std.mem.readInt(u32, buf[1..5], .little); - // Refused BEFORE the caller grows a buffer to hold it: an over-long prefix - // is the one field in this protocol that can ask for memory. - if (len > max_payload) return error.Overlong; - if (buf.len - header_len < len) return null; - return .{ .tag = buf[0], .payload = buf[header_len..][0..len], .total = header_len + len }; -} - -// --------------------------------------------------------------------------- -// frontend -> core -// --------------------------------------------------------------------------- - -/// Which tag a message travels under: the `ClientTag` of the same NAME, so a -/// new `Event` variant does not compile until it has a number here, rather -/// than a written-out table that can drift. -fn clientTag(msg: ClientMsg) ClientTag { - return switch (msg) { - .event => |ev| switch (ev) { - // Machine-local reports and 9P requests belong to the session owner. - .output, .eof, .exited, .lsp_resp, .pipe_resp, .search, .file_changed, .handed, .tick => unreachable, - inline else => |_, t| @field(ClientTag, @tagName(t)), - }, - inline else => |_, t| @field(ClientTag, @tagName(t)), - }; -} - -/// Does the build this frontend was compiled with carry pixel dimensions in a -/// resize? The FIELD is comptime-conditional (pardes.zig `CellPixels`); the -/// WIRE is not. -const has_cell_pixels = @hasField(pardes.CellPixels, "w"); - -fn putMetrics(w: *std.Io.Writer, metrics: ?pardes.RowMetrics) Error!void { - try w.writeByte(@intFromBool(metrics != null)); - if (metrics) |m| { - try w.writeInt(u16, m.body_w, .little); - try w.writeInt(u16, m.body_h, .little); - try w.writeInt(u16, m.tagline_w, .little); - try w.writeInt(u16, m.tagline_h, .little); - } -} - -fn getMetrics(r: *std.Io.Reader) Error!?pardes.RowMetrics { - if (!try getBool(r)) return null; - const m: pardes.RowMetrics = .{ .body_w = try r.takeInt(u16, .little), .body_h = try r.takeInt(u16, .little), .tagline_w = try r.takeInt(u16, .little), .tagline_h = try r.takeInt(u16, .little) }; - if (m.body_w == 0 or m.body_h == 0 or m.tagline_w == 0 or m.tagline_h == 0) return error.BadValue; - return m; -} - -fn putPlace(w: *std.Io.Writer, at: pardes.Layer.Place) Error!void { - for ([_]u16{ at.viewport.x, at.viewport.y, at.viewport.w, at.viewport.h, at.cols, at.rows, at.context_rows }) |n| try w.writeInt(u16, n, .little); -} - -fn getPlace(r: *std.Io.Reader) Error!pardes.Layer.Place { - var n: [7]u16 = undefined; - for (&n) |*x| x.* = try r.takeInt(u16, .little); - if (n[6] > n[5]) return error.BadValue; - return .{ .viewport = .{ .x = n[0], .y = n[1], .w = n[2], .h = n[3] }, .cols = n[4], .rows = n[5], .context_rows = n[6] }; -} - -fn putBodyHit(w: *std.Io.Writer, hit: ?pardes.Mouse.BodyHit) Error!void { - try w.writeByte(@intFromBool(hit != null)); - if (hit) |h| { - try w.writeInt(u32, h.serial, .little); - try w.writeInt(u16, h.row, .little); - try w.writeInt(u16, h.col, .little); - try w.writeInt(u32, @bitCast(h.pixel_x), .little); - try w.writeInt(u32, @bitCast(h.pixel_y), .little); - try putMetrics(w, h.metrics); - try putPlace(w, h.place); - } -} - -fn getBodyHit(r: *std.Io.Reader) Error!?pardes.Mouse.BodyHit { - if (!try getBool(r)) return null; - const hit: pardes.Mouse.BodyHit = .{ .serial = try r.takeInt(u32, .little), .row = try r.takeInt(u16, .little), .col = try r.takeInt(u16, .little), .pixel_x = try getF32(r), .pixel_y = try getF32(r), .metrics = (try getMetrics(r)) orelse return error.BadValue, .place = try getPlace(r) }; - if (!std.math.isFinite(hit.pixel_x) or !std.math.isFinite(hit.pixel_y)) return error.BadValue; - return hit; -} - -fn putTagHit(w: *std.Io.Writer, hit: ?pardes.TagHit) Error!void { - try w.writeByte(@intFromBool(hit != null)); - if (hit) |h| { - try w.writeByte(@backingInt(h.kind)); - try w.writeInt(u16, h.id, .little); - try w.writeInt(u32, h.serial, .little); - try w.writeInt(u16, h.col, .little); - try w.writeInt(u16, h.line, .little); - try w.writeInt(u32, @bitCast(h.pixel_x), .little); - try w.writeInt(u32, @bitCast(h.pixel_y), .little); - try putMetrics(w, h.metrics); - try putPlace(w, h.place); - } -} - -fn getTagHit(r: *std.Io.Reader) Error!?pardes.TagHit { - if (!try getBool(r)) return null; - const hit: pardes.TagHit = .{ - .kind = try getTag(r, pardes.TagKind), - .id = try r.takeInt(u16, .little), - .serial = try r.takeInt(u32, .little), - .col = try r.takeInt(u16, .little), - .line = try r.takeInt(u16, .little), - .pixel_x = try getF32(r), - .pixel_y = try getF32(r), - .metrics = (try getMetrics(r)) orelse return error.BadValue, - .place = try getPlace(r), - }; - if (!std.math.isFinite(hit.pixel_x) or !std.math.isFinite(hit.pixel_y)) return error.BadValue; - return hit; -} - -pub fn encodeClient(out: []u8, msg: ClientMsg) Error![]const u8 { - var w: std.Io.Writer = .fixed(out); - const at = try beginMessage(&w, @backingInt(clientTag(msg))); - switch (msg) { - .hello => |h| { - try w.writeInt(u16, h.version, .little); - try w.writeInt(u64, h.semantics, .little); - if (h.session.len > max_name) return error.Overlong; - try putSlice16(&w, h.session); - try w.writeByte(h.view orelse 0xff); - }, - .bye => |b| try w.writeByte(@intFromBool(b.again)), - .ping => |v| try w.writeInt(u64, v, .little), - .screen_ack, .want => |bytes| try w.writeAll(bytes), - .check => {}, - .far => |far| try w.writeByte(@intFromBool(far)), - .stamp => |s| for (s) |v| try w.writeInt(i64, v, .little), - .event => |ev| switch (ev) { - .key => |k| { - try w.writeInt(u32, k.cp, .little); - try putSlice16(&w, k.text); - try w.writeByte(@intFromBool(k.ctrl)); - try w.writeByte(@intFromBool(k.alt)); - try w.writeByte(@intFromBool(k.shift)); - }, - .mouse => |m| { - try w.writeByte(switch (m.button) { - inline else => |t| @backingInt(@field(ButtonTag, @tagName(t))), - }); - try w.writeByte(switch (m.kind) { - inline else => |t| @backingInt(@field(KindTag, @tagName(t))), - }); - try w.writeInt(u16, m.col, .little); - try w.writeInt(u16, m.row, .little); - try w.writeByte(@intFromBool(m.ctrl)); - try w.writeByte(@intFromBool(m.shift)); - try w.writeByte(@intFromBool(m.alt)); - try putBodyHit(&w, m.body_hit); - try putTagHit(&w, m.tag_hit); - }, - .resize => |rs| { - try w.writeInt(u16, rs.cols, .little); - try w.writeInt(u16, rs.rows, .little); - // The conventional 1:2 cell aspect when this build has no - // pixels of its own, which is the same default the field - // carries where it exists. - try w.writeInt(u16, if (comptime has_cell_pixels) rs.cell_pixels.w else 8, .little); - try w.writeInt(u16, if (comptime has_cell_pixels) rs.cell_pixels.h else 16, .little); - try putMetrics(&w, rs.row_metrics); - }, - .paste => |b| try putSlice32(&w, b), - .command => |line| try putSlice16(&w, line), - .pdf_scroll => |s| { - try w.writeByte(s.pane); - try w.writeInt(u32, @bitCast(s.delta_pixels), .little); - try w.writeByte(@intFromBool(s.glide)); - }, - .pointer_leave => {}, - .focus => |focused| try w.writeByte(@intFromBool(focused)), - .frontend => |f| { - try w.writeByte(@intFromBool(f.windowed)); - try w.writeByte(@intFromBool(f.native_images)); - try w.writeByte(@intFromBool(f.native_image_patches)); - }, - // See `clientTag`: no tag, so nothing to encode. - .output, .eof, .exited, .lsp_resp, .pipe_resp, .search, .file_changed, .handed, .tick => unreachable, - }, - } - try finishMessage(&w, at); - return w.buffered(); -} - -pub fn decodeClient(tag: u8, payload: []const u8) Error!ClientMsg { - var r: std.Io.Reader = .fixed(payload); - const msg: ClientMsg = switch (std.enums.fromInt(ClientTag, tag) orelse return error.BadTag) { - .hello => .{ .hello = .{ - .version = try r.takeInt(u16, .little), - .semantics = try r.takeInt(u64, .little), - .session = blk: { - const n = try r.takeInt(u16, .little); - if (n > max_name) return error.BadValue; - break :blk try r.take(n); - }, - .view = switch (try r.takeByte()) { - 0xff => null, - else => |k| k, - }, - } }, - .bye => .{ .bye = .{ .again = try getBool(&r) } }, - .ping => .{ .ping = try r.takeInt(u64, .little) }, - .screen_ack => return .{ .screen_ack = payload }, - .check => .check, - .far => .{ .far = try getBool(&r) }, - .want => return .{ .want = payload }, - .stamp => .{ .stamp = .{ try r.takeInt(i64, .little), try r.takeInt(i64, .little) } }, - .key => blk: { - const cp = try r.takeInt(u32, .little); - // `Key.cp` is a u21, and the specials live in the private-use - // plane below this bound. A larger number is not a codepoint and - // @intCast of it would panic in a release build's own decoder. - if (cp > 0x10FFFF) return error.BadValue; - break :blk .{ .event = .{ .key = .{ - .cp = @intCast(cp), - .text = try r.take(try r.takeInt(u16, .little)), - .ctrl = try getBool(&r), - .alt = try getBool(&r), - .shift = try getBool(&r), - } } }; - }, - .mouse => .{ .event = .{ .mouse = .{ - .button = switch (try getTag(&r, ButtonTag)) { - inline else => |t| @field(pardes.Mouse.Button, @tagName(t)), - }, - .kind = switch (try getTag(&r, KindTag)) { - inline else => |t| @field(pardes.Mouse.Kind, @tagName(t)), - }, - .col = try r.takeInt(u16, .little), - .row = try r.takeInt(u16, .little), - .ctrl = try getBool(&r), - .shift = try getBool(&r), - .alt = try getBool(&r), - .body_hit = try getBodyHit(&r), - .tag_hit = try getTagHit(&r), - } } }, - .resize => blk: { - var ev: pardes.Event = .{ .resize = .{ .cols = try getCols(&r), .rows = try getRows(&r) } }; - const px_w = try r.takeInt(u16, .little); - const px_h = try r.takeInt(u16, .little); - // Read either way — the bytes are on the wire — and kept only by a - // build that has somewhere to keep them. - if (comptime has_cell_pixels) ev.resize.cell_pixels = .{ .w = px_w, .h = px_h }; - ev.resize.row_metrics = try getMetrics(&r); - break :blk .{ .event = ev }; - }, - .paste => .{ .event = .{ .paste = try getSlice32(&r) } }, - .command => .{ .event = .{ .command = try r.take(try r.takeInt(u16, .little)) } }, - .pdf_scroll => .{ .event = .{ .pdf_scroll = .{ .pane = try getPane(&r), .delta_pixels = try getF32(&r), .glide = try getBool(&r) } } }, - .pointer_leave => .{ .event = .pointer_leave }, - .focus => .{ .event = .{ .focus = try getBool(&r) } }, - .frontend => .{ .event = .{ .frontend = .{ .windowed = try getBool(&r), .native_images = try getBool(&r), .native_image_patches = try getBool(&r) } } }, - }; - try end(&r); - return msg; -} - -/// Slack over a message's variable payload, covering every fixed field any -/// message here has plus its own header. -const msg_slack = header_len + 64; - -/// An upper bound on `encodeClient`'s output, so a caller sizes its buffer -/// once instead of guessing and retrying. -pub fn clientBound(msg: ClientMsg) usize { - return msg_slack + switch (msg) { - .hello => |h| h.session.len, - .bye, .ping, .check, .far, .stamp => 0, - .screen_ack, .want => |bytes| bytes.len, - .event => |ev| switch (ev) { - // Its hits' places (14 bytes each) past the slack. - .mouse => 28, - .resize, .pdf_scroll, .pointer_leave, .focus, .frontend => 0, - .key => |k| k.text.len, - .paste => |b| b.len, - .command => |line| line.len, - // See `clientTag`: not on this wire in this direction. - .output, .eof, .exited, .lsp_resp, .pipe_resp, .search, .file_changed, .handed, .tick => unreachable, - }, - }; -} - -// --------------------------------------------------------------------------- -// tests -// --------------------------------------------------------------------------- -// -// Two obligations. Every message round-trips to a deep-equal value, because a -// codec written by hand is a codec whose two halves drift; and every malformed -// shape is REFUSED, because this parser is fed by a socket and a frame that is -// misread rather than refused is an out-of-bounds index. - -const testing = std.testing; - -/// Round-trip one frontend -> core message through the framing too, so a -/// length prefix that disagrees with the payload cannot pass. -fn roundClient(buf: []u8, msg: ClientMsg) !ClientMsg { - const bytes = try encodeClient(buf, msg); - const f = (try framed(bytes)).?; - try testing.expectEqual(bytes.len, f.total); - return decodeClient(f.tag, f.payload); -} - -test "detached wire: every Event variant round-trips" { - var buf: [4096]u8 = undefined; - - // The tag space is the protocol's own, so assert the numbers themselves: - // a renumbering here breaks every deployed frontend and must be a diff - // somebody reads, not a silent change. - try testing.expectEqual(@as(u8, 0x01), @backingInt(ClientTag.hello)); - try testing.expectEqual(@as(u8, 0x10), @backingInt(ClientTag.key)); - try testing.expectEqual(@as(u8, 0x1d), @backingInt(ClientTag.pointer_leave)); - - { - const got = try roundClient(&buf, .{ .hello = .{ .session = "work" } }); - try testing.expectEqual(version, got.hello.version); - try testing.expectEqual(semantics, got.hello.semantics); - try testing.expectEqualStrings("work", got.hello.session); - } - try testing.expect((try roundClient(&buf, .{ .bye = .{ .again = true } })).bye.again); - try testing.expectEqual(@as(?u8, 2), (try roundClient(&buf, .{ .hello = .{ .session = "work", .view = 2 } })).hello.view); - try testing.expectEqual(@as(u64, 0xfeed_beef_0000_0001), (try roundClient(&buf, .{ .ping = 0xfeed_beef_0000_0001 })).ping); - { - // The other way: framed the same, its tag the ServerTag's number. - const bytes = try encodeServer(&buf, .{ .welcome = .{ .pid = 42, .session = "work" } }); - const f = (try framed(bytes)).?; - try testing.expectEqual(@as(u8, 0x01), f.tag); - try testing.expectEqualSlices(u8, &.{ 42, 0, 0, 0, 4, 0, 'w', 'o', 'r', 'k', 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 }, f.payload); - const back = (try decodeServer(f.tag, f.payload)).welcome; - try testing.expectEqualStrings("work", back.session); - try testing.expectEqual(@as(u32, 42), back.pid); - try testing.expectEqual(@as(u8, 0x03), (try framed(try encodeServer(&buf, .{ .pong = 7 }))).?.tag); - } - - { - const key: pardes.Key = .{ .cp = pardes.Key.page_down, .text = "ü", .ctrl = true, .alt = false, .shift = true }; - const got = (try roundClient(&buf, .{ .event = .{ .key = key } })).event.key; - try testing.expectEqual(key.cp, got.cp); - try testing.expectEqualStrings(key.text, got.text); - try testing.expectEqual(key.ctrl, got.ctrl); - try testing.expectEqual(key.alt, got.alt); - try testing.expectEqual(key.shift, got.shift); - } - { - // Every button and every kind, because the two mapping switches are - // the only place a value can be mistranslated and still decode. - for (std.enums.values(pardes.Mouse.Button)) |button| { - for (std.enums.values(pardes.Mouse.Kind)) |kind| { - const m: pardes.Mouse = .{ .button = button, .kind = kind, .col = 4200, .row = 7, .ctrl = true, .shift = true, .alt = true }; - const got = (try roundClient(&buf, .{ .event = .{ .mouse = m } })).event.mouse; - try testing.expectEqual(m.button, got.button); - try testing.expectEqual(m.kind, got.kind); - try testing.expectEqual(m.col, got.col); - try testing.expectEqual(m.row, got.row); - try testing.expectEqual(m.ctrl, got.ctrl); - try testing.expectEqual(m.shift, got.shift); - try testing.expectEqual(m.alt, got.alt); - } - } - } - { - const got = (try roundClient(&buf, .{ .event = .{ .resize = .{ .cols = 56, .rows = 14 } } })).event.resize; - try testing.expectEqual(@as(u16, 56), got.cols); - try testing.expectEqual(@as(u16, 14), got.rows); - // Pixels travel whether or not this build has them; where it does, the - // conventional 1:2 default survives the trip. - if (comptime has_cell_pixels) { - try testing.expectEqual(@as(u16, 8), got.cell_pixels.w); - try testing.expectEqual(@as(u16, 16), got.cell_pixels.h); - } - } - try testing.expectEqualStrings("clip", (try roundClient(&buf, .{ .event = .{ .paste = "clip" } })).event.paste); - try testing.expectEqualStrings("Look /x", (try roundClient(&buf, .{ .event = .{ .command = "Look /x" } })).event.command); - { - const got = (try roundClient(&buf, .{ .event = .{ .pdf_scroll = .{ .pane = 2, .delta_pixels = -12.5, .glide = false } } })).event.pdf_scroll; - try testing.expectEqual(@as(u8, 2), got.pane); - try testing.expectEqual(@as(f32, -12.5), got.delta_pixels); - try testing.expect(!got.glide); - } - try testing.expectEqual( - std.meta.Tag(pardes.Event).pointer_leave, - (try roundClient(&buf, .{ .event = .pointer_leave })).event, - ); -} - -test "detached wire: a session is never told to do a frontend's remembering" { - // The mirror of the test above, and of client.zig's "a frontend is never - // asked to fork, write, or watch". That one pins what may reach a FRONTEND; - // this one pins what may reach the SESSION, and until the six tags below it - // names were deleted the protocol was asymmetric: server -> client carried - // only what a display can do, while client -> server still carried the - // machine-local host's own reports, which server.zig's `apply` hands - // straight to `core.update`. - // - // Adding a name here is meant to be an ARGUMENT, not a formality, and the - // bar is one sentence: A HUMAN DID IT. A keystroke, a click, a - // window resized, a paste, a command line executed, a pointer leaving the - // window, the window's focus — plus the session words that say who is speaking, time the link and end it. A pty's - // output, a worker's answer, a watched file's new bytes and an animation - // tick all fail that bar the same way: nobody did them, a machine reported - // them, and the machine that reports them is the one already holding the - // core. - const allowed = [_][]const u8{ - // Who this connection is, its round trip, and that it is finished, - // and which terminal state its replica holds (a protocol's word, - // as a ping is). - "hello", "bye", "ping", "screen_ack", "check", - // ...and how far it is, and which of the join's blobs it lacks. - "far", "want", - // ...and when its next input was, by the session's clocks. - "stamp", - // ...and everything a person can do to a window. - "key", "mouse", "resize", - "paste", "command", "pdf_scroll", "pointer_leave", "focus", - // ...and which of its frontends the person sits at: a window, or a - // terminal (what the view draws, and the words it takes). - "frontend", - }; - - // One: the tag set is exactly that, named rather than counted, so - // re-adding `output` fails with the name in the failure. - inline for (std.enums.values(ClientTag)) |t| { - for (allowed) |ok| { - if (std.mem.eql(u8, @tagName(t), ok)) break; - } else { - std.debug.print("ClientTag.{s} is not something a human did\n", .{@tagName(t)}); - return error.MachineLocalReportOnTheWire; - } - } - try testing.expectEqual(allowed.len, std.enums.values(ClientTag).len); - - // Two: and no tag BYTE outside them decodes either — the check above is - // about this build's enum, this one is about the bytes on the socket. The - // six deleted numbers (0x13..0x17, 0x1e) are in the ones that must answer - // `BadTag`, so a frontend built before this change cannot forge a pane's - // output into a session built after it (as are 0x1b and 0x1c, once a - // pinch and a touch scroll). - var accepted: usize = 0; - for (0..256) |i| { - const tag: u8 = @intCast(i); - // Empty payloads on purpose: what is asked is whether the TAG is known. - // A known one fails later (`EndOfStream`) or succeeds, never with - // `BadTag`. - if (decodeClient(tag, &.{})) |_| accepted += 1 else |err| switch (err) { - error.BadTag => continue, - else => accepted += 1, - } - const named = for (allowed) |ok| { - const want = std.meta.stringToEnum(ClientTag, ok).?; - if (@backingInt(want) == tag) break true; - } else false; - if (!named) { - std.debug.print("tag 0x{x:0>2} is decodable by a session and is not something a human did\n", .{tag}); - return error.MachineLocalReportOnTheWire; - } - } - try testing.expectEqual(allowed.len, accepted); -} - -test "detached wire: a truncated message is refused at every length" { - var buf: [4096]u8 = undefined; - - // Every prefix of a real message. The framing must say "not yet" for the - // ones that are short, and the decoder must say "truncated" for a payload - // whose header lies about its length — never read past the slice. - const whole = try encodeClient(&buf, .{ .event = .{ .key = .{ .cp = 'a', .text = "a" } } }); - var copy: [64]u8 = undefined; - @memcpy(copy[0..whole.len], whole); - for (header_len + 1..whole.len) |cut| { - try testing.expectEqual(@as(?Framed, null), try framed(copy[0..cut])); - // ...and the same bytes handed to the decoder with the header's length - // left claiming the whole message, which is how a decoder is walked - // off the end of its buffer. - try testing.expectError(error.EndOfStream, decodeClient(copy[0], copy[header_len..cut])); - } - // Shorter than the header itself is not yet a message at all. - for (0..header_len + 1) |cut| - try testing.expectEqual(@as(?Framed, null), try framed(copy[0..cut])); - // A payload with bytes LEFT OVER is refused too: it is not this message. - try testing.expectError(error.Trailing, decodeClient(@backingInt(ClientTag.pointer_leave), "x")); -} - -test "detached wire: an unknown tag is refused, never guessed" { - // 0x00 and 0xff have never been assigned, and 0x0f sits in the gap between - // the session tags and the input tags. All three are the same answer. - for ([_]u8{ 0x00, 0x0f, 0x1f, 0xff }) |tag| { - try testing.expectError(error.BadTag, decodeClient(tag, "")); - } - // A tag NESTED in a payload gets the same treatment: a mouse button. - try testing.expectError(error.BadTag, decodeClient( - @backingInt(ClientTag.mouse), - &.{ 0xff, 0x00, 0, 0, 0, 0, 0 }, - )); -} - -test "detached wire: an over-long length prefix is refused before it is believed" { - // The prefix a hostile or corrupt peer sends to make the receiver allocate - // or index by it. `framed` must refuse rather than wait for 4 GiB. - var head: [header_len]u8 = .{ @backingInt(ClientTag.paste), 0, 0, 0, 0 }; - std.mem.writeInt(u32, head[1..5], max_payload + 1, .little); - try testing.expectError(error.Overlong, framed(&head)); - std.mem.writeInt(u32, head[1..5], std.math.maxInt(u32), .little); - try testing.expectError(error.Overlong, framed(&head)); - // At the boundary it is a legal prefix and simply has not all arrived. - std.mem.writeInt(u32, head[1..5], max_payload, .little); - try testing.expectEqual(@as(?Framed, null), try framed(&head)); - - // An INNER length prefix, past the payload it sits in but inside the - // protocol's cap — the one an outer-frame check cannot catch. - var paste: [8]u8 = undefined; - std.mem.writeInt(u32, paste[0..4], 4096, .little); - @memcpy(paste[4..8], "abcd"); - try testing.expectError(error.EndOfStream, decodeClient(@backingInt(ClientTag.paste), &paste)); - // ...and past the cap, which is refused rather than read. - std.mem.writeInt(u32, paste[0..4], max_payload + 1, .little); - try testing.expectError(error.Overlong, decodeClient(@backingInt(ClientTag.paste), &paste)); -} - -test "detached wire: values a field cannot mean are refused" { - // A bool is 0 or 1. `2` used to be "true" in every hand-written codec that - // ever silently accepted a corrupt stream. - try testing.expectError(error.BadValue, decodeClient( - @backingInt(ClientTag.key), - &.{ 'a', 0, 0, 0, 0, 0, 2, 0, 0 }, - )); - // A codepoint past Unicode's last: @intCast into Key.cp's u21 would panic. - try testing.expectError(error.BadValue, decodeClient( - @backingInt(ClientTag.key), - &.{ 0x00, 0x00, 0x11, 0x00, 0, 0, 0, 0, 0 }, - )); - // A pane the core cannot index. `pdf_scroll` reads its pane byte before the - // f32 that follows, so a one-byte payload reaches the check this is about - // rather than tripping `EndOfStream` first. - try testing.expectError(error.BadValue, decodeClient( - @backingInt(ClientTag.pdf_scroll), - &.{pardes.MAX_PANES}, - )); - // A session name longer than the daemon keeps one: refused, never cut - // to another session's name. - { - var hello: [12 + max_name + 1]u8 = @splat('x'); - std.mem.writeInt(u16, hello[0..2], version, .little); - std.mem.writeInt(u16, hello[10..12], max_name + 1, .little); - try testing.expectError(error.BadValue, decodeClient(@backingInt(ClientTag.hello), &hello)); - std.mem.writeInt(u16, hello[10..12], max_name, .little); - hello[hello.len - 1] = 0xff; - try testing.expectEqual(@as(usize, max_name), (try decodeClient(@backingInt(ClientTag.hello), &hello)).hello.session.len); - try testing.expect(header_len + hello.len == hello_max); - } - // A NaN or an infinite scroll distance. - { - var scroll: [6]u8 = .{ 0, 0, 0, 0, 0, 1 }; - std.mem.writeInt(u32, scroll[1..5], @bitCast(std.math.nan(f32)), .little); - try testing.expectError(error.BadValue, decodeClient(@backingInt(ClientTag.pdf_scroll), &scroll)); - std.mem.writeInt(u32, scroll[1..5], @bitCast(std.math.inf(f32)), .little); - try testing.expectError(error.BadValue, decodeClient(@backingInt(ClientTag.pdf_scroll), &scroll)); - } -} - -test "detached wire: max_payload bounds every message this protocol can build" { - // A 4 MiB paste, which is the tty's own cap, fits. - try testing.expect((4 << 20) + header_len + 4 <= max_payload); - // A slice past the width of its own length prefix is refused by the - // ENCODER, rather than written and rejected at the far end. A command line - // is u16-prefixed because nothing legitimately types 64 KiB of one. - const gpa = testing.allocator; - const huge = try gpa.alloc(u8, std.math.maxInt(u16) + 1); - defer gpa.free(huge); - @memset(huge, 'x'); - const room = try gpa.alloc(u8, huge.len + header_len + 2); - defer gpa.free(room); - try testing.expectError(error.Overlong, encodeClient(room, .{ .event = .{ .command = huge } })); - // ...and a buffer the caller sized too small is WriteFailed, which is the - // server's signal to drop that one message rather than the client. - var small: [8]u8 = undefined; - try testing.expectError(error.WriteFailed, encodeClient(&small, .{ .event = .{ .paste = "0123456789" } })); -} - -test "detached wire carries exact pointer metrics" { - var logical: [12]pardes.Cell = @splat(.{}); - var layer: pardes.Layer = .{ .id = 0, .serial = 42, .viewport = .{ .x = 0, .y = 0, .w = 2, .h = 4 }, .cols = 2, .rows = 6, .context_rows = 2, .cells = &logical, .cursor = .{ .x = 0, .y = 5, .bar = true } }; - layer.context_separators.set(0); - var tag_cells: [3]pardes.Cell = @splat(.{}); - const tag: pardes.Layer = .{ .kind = .column, .id = 1, .viewport = .{ .x = 0, .y = 0, .w = 2, .h = 1 }, .cols = 3, .rows = 1, .bg = .{ 11, 22, 33 }, .cells = &tag_cells, .cursor = .{ .x = 2, .y = 0, .bar = true } }; - const pointer = layer.bodyHit(4, 27, 8, 16, 6, 8).?; - const tag_pointer = tag.tagHit(11, 8, 8, 16, 4, 8).?; - const message: ClientMsg = .{ .event = .{ .mouse = .{ .col = 0, .row = 1, .button = .left, .kind = .press, .body_hit = pointer, .tag_hit = tag_pointer } } }; - var mouse_bytes: [256]u8 = undefined; - const mouse_encoded = try encodeClient(&mouse_bytes, message); - const mouse_packet = (try framed(mouse_encoded)).?; - const mouse = (try decodeClient(mouse_packet.tag, mouse_packet.payload)).event.mouse; - try std.testing.expectEqualDeep(pointer, mouse.body_hit.?); - try std.testing.expectEqualDeep(tag_pointer, mouse.tag_hit.?); - try std.testing.expect(mouse_encoded.len <= clientBound(message)); -} diff --git a/src/main.zig b/src/main.zig index 9092e2f9..2b50273c 100644 --- a/src/main.zig +++ b/src/main.zig @@ -315,11 +315,11 @@ fn badArgs(io: std.Io, comptime fmt: []const u8, args: anytype) noreturn { } /// The second line is what a replica's build must share with its session's -/// (detached/wire.zig `semantics`). +/// (wire.zig `semantics`). const version_text = (if (pardes.commit) |c| "pardes " ++ pardes.version ++ " (" ++ c ++ ")\n" else - "pardes " ++ pardes.version ++ "\n") ++ std.fmt.comptimePrint("semantics {x:0>16}\n", .{@import("detached/wire.zig").semantics}); + "pardes " ++ pardes.version ++ "\n") ++ std.fmt.comptimePrint("semantics {x:0>16}\n", .{@import("wire.zig").semantics}); const nested_text = \\pardes: this shell is already inside pardes, and a pardes inside a pardes @@ -1176,7 +1176,7 @@ test { _ = @import("memory.zig"); _ = @import("locations.zig"); _ = @import("fs.zig"); - _ = @import("detached/wire.zig"); + _ = @import("wire.zig"); _ = @import("ShaderBuild.zig"); _ = @import("vaxis_input.zig"); _ = @import("daemon.zig"); diff --git a/src/replica.zig b/src/replica.zig index e567587c..633080e7 100644 --- a/src/replica.zig +++ b/src/replica.zig @@ -18,7 +18,7 @@ //! and the comparison catches a guess the authority did not share. //! //! No transport: messages are bytes in and out. A client's input is its -//! id, a sequence number and the event as detached/wire.zig frames it; a +//! id, a sequence number and the event as wire.zig frames it; a //! unit is the input's origin (0 for the authority's own: a pty's output, a //! tick), its sequence number and the authority's tape of it. const std = @import("std"); @@ -27,7 +27,7 @@ const pardes = @import("pardes.zig"); const tape = @import("tape.zig"); const rollback = @import("rollback.zig"); const walk = @import("walk.zig"); -const wire = @import("detached/wire.zig"); +const wire = @import("wire.zig"); const screen_state = @import("screen_state.zig"); const c_heap = @import("c_heap"); const terminal = pardes.panes.terminal; @@ -1338,7 +1338,7 @@ pub const Framer = struct { f.z = null; } - /// Framed messages off `fd` (detached/wire.zig) handed to `take` until + /// Framed messages off `fd` (wire.zig) handed to `take` until /// the stream ends, `take` says stop, or a message is malformed. An /// envelope's are handed on as if they had come bare. fn run(fr: *Framer, gpa: Allocator, fd: c_int, ctx: anytype, comptime take: fn (@TypeOf(ctx), u8, []const u8) bool) void { diff --git a/src/wire.zig b/src/wire.zig new file mode 100644 index 00000000..d572d469 --- /dev/null +++ b/src/wire.zig @@ -0,0 +1,975 @@ +//! The framed stream a replica speaks (docs/next-daemon.md, phase 5), on +//! the daemon's `pardes-replica.sock` and then its session's: fixed-width +//! little-endian fields and explicit tags, the hello and its version, a +//! ping, and the input Events. Native struct layout never reaches the wire. +//! The cell frames that went the other way, and the frontends that drew +//! them, went with phase 3. +const std = @import("std"); +const builtin = @import("builtin"); +const pardes = @import("pardes.zig"); +const config = @import("pardes_config"); + +/// 19: a client joining again names the view it had in its hello, and a +/// bye says whether it joins again for it (views.away); +/// 18: a replica's input is stamped with its guess of the session's +/// clocks, the time its step reads (phase 6's instant interaction notes); +/// 17: a pointer's hit carries the place it was made on (Layer.Place) and +/// a tag hit its line, which the step resolves it by, not by its frame; +/// 16: a far client says so, the session sends it its blobs' hashes before +/// the rest and only the blobs it asks for, all of it in zstd (phase 6's +/// content cache and zstd notes), and a client says its frontend (a window +/// or a terminal) as its first input, a window replicating a terminal's +/// session and back (phase 6's GUI replica notes); 15: the session streams +/// a replica its dump and units, and terminal deltas both ways (phase 5 +/// part B); 14: the hello names a session and +/// carries the semantics hash, and a ping is answered (phase 5's +/// groundwork); 13: the frames went (phase 3). +pub const version: u16 = 19; + +/// The terminal's build and the window's step alike (`semantics`). +const family = switch (config.platform) { + .tui, .gui => "desktop", + else => @tagName(config.platform), +}; + +/// What makes two cores step differently, hashed: a replica's hello carries +/// its own, and one of another build is refused. The protocol, the release +/// and commit, the platform and build options, every dependency's content +/// hash (grammars, ghostty, Unicode), the walker codec's assumptions +/// (pointer width, byte order) and the tape's shape (tape.shape: what each +/// input and each answer of the host's is laid out as). Not the OS: a Linux +/// client of a FreeBSD session is the main case, and what differs there is +/// the host's, taped, in a shape every OS shares (an error by its name, a +/// stat as fs.OsStat). Nor the build mode: a Debug build steps as a +/// release one does (regexp.zig's one budget). +/// Nor the terminal's build against the window's: their cores step alike, +/// the GUI's own words by the view's frontend (builtins.zig `here`), so a +/// window replicates a terminal's session and a terminal a window's. +/// ponytail: an unstamped build (Debug with -Dplatform, every test build) +/// has no commit, so two dev trees of one release are told apart only by +/// their options and dependencies; -Dstamp-commit stamps one. +pub const semantics: u64 = blk: { + @setEvalBranchQuota(1_000_000); + break :blk std.hash.Wyhash.hash(0, std.fmt.comptimePrint( + "wire {d}\npardes {s} {s}\n{s} grammars {} {} {} {} mupdf {} themes {} workspace_tag {} sources {} board {d}x{d}\nusize {d} {t}\n{s}\n{s}", + .{ + version, config.version, config.commit orelse "unstamped", + family, config.syntax_highlighting, config.syntax_zig_grammar, + config.syntax_minimal_grammars, config.syntax_full_grammars, config.mupdf, + config.theme_animation, config.workspace_tag, config.embed_sources, + config.esp32p4_cols, config.esp32p4_rows, @sizeOf(usize), + builtin.cpu.arch.endian(), config.deps, pardes.tape.shape, + }, + )); +}; + +/// EndOfStream: the message ends early; WriteFailed: no room for it. +/// ReadFailed is in only because std.Io.Reader says so: a fixed one never +/// fails a read. +pub const Error = error{ EndOfStream, ReadFailed, Overlong, BadTag, BadValue, Trailing, WriteFailed }; + +pub const max_cols: u16 = 512; +pub const max_rows: u16 = 128; +pub const max_payload: u32 = 16 << 20; +pub const header_len = 5; // tag:u8, payload length:u32le + +// Stable wire numbers; gaps are retired tags. Unknown tags are rejected by the decoder. +pub const ClientTag = enum(u8) { + hello = 0x01, + bye = 0x02, + ping = 0x03, + /// A replica's word about a terminal's state (src/screen_state.zig): the + /// delta it holds, or rows it asks for. Opaque here. + screen_ack = 0x04, + /// What is the session's digest, in stream order (a replica checks + /// itself against it once quiet). + check = 0x05, + /// A client's first word after its hello: whether it is far (through + /// ssh), so that it holds blobs by their hash and reads zstd. + far = 0x06, + /// The join's blobs a far client lacks, a bit each in `blobs` order. + want = 0x07, + /// The session's clocks (realtime and monotonic, ns) as the client + /// guessed them for the input that follows: its time, which the step + /// reads (src/replica.zig). + stamp = 0x08, + + key = 0x10, + mouse = 0x11, + resize = 0x12, + paste = 0x18, + command = 0x19, + pdf_scroll = 0x1a, + // 0x1b and 0x1c were a pinch and a touch scroll, gone since. + pointer_leave = 0x1d, + focus = 0x1e, + /// Which frontend the client is: a window, or a terminal. + frontend = 0x20, +}; + +const ButtonTag = enum(u8) { + left = 0x00, + middle = 0x01, + right = 0x02, + wheel_up = 0x03, + wheel_down = 0x04, + wheel_left = 0x05, + wheel_right = 0x06, + none = 0x07, + back = 0x08, + forward = 0x09, +}; +const KindTag = enum(u8) { press = 0x00, release = 0x01, motion = 0x02, drag = 0x03 }; + +// --------------------------------------------------------------------------- +// messages +// --------------------------------------------------------------------------- + +/// First message on every connection, and `version` is its first field at a +/// fixed offset for exactly one reason: a mismatch has to be diagnosable even +/// when the rest of the layout is the part that changed. +pub const Hello = struct { + version: u16 = version, + /// The client's `semantics`: the daemon refuses it unless the session's + /// is the same. + semantics: u64 = semantics, + /// Which session (its 9P name, as `--attach=` names it). + session: []const u8, + /// The view it had, joining again for it (a divergence's rejoin, an + /// Upgrade's): the daemon hands it on with the connection. 0xff: none. + view: ?u8 = null, +}; + +/// A session's name on the wire, as the daemon keeps it. +pub const max_name = 128; +/// The longest hello there is, header and all. +pub const hello_max = header_len + 2 + 8 + 2 + max_name + 1; + +/// Daemon or session -> client. +pub const ServerTag = enum(u8) { + /// The hello is accepted and the connection is the session's now: its pid + /// and name. + welcome = 0x01, + /// Refused, said in words; the connection ends. + refused = 0x02, + /// A ping's value back. + pong = 0x03, + /// A piece of the join's dump (src/dump.zig): the welcome says how long + /// it is whole. + dump = 0x04, + /// A unit of the authority's stream (src/replica.zig): its origin, seq, + /// clocks and tape. + unit = 0x05, + /// A terminal's delta, or rows asked for (src/screen_state.zig), applied + /// before the next unit. Opaque here. + screen = 0x06, + /// The session's digest (u64le), after every unit before it. + check = 0x07, + /// Part of the join's list of blobs, to a far client: each one's place + /// in the state, its length and its BLAKE3 hash (src/replica.zig). + blobs = 0x08, + /// A piece of a far client's stream from here on, zstd-compressed: the + /// messages in it are framed as these are. Opaque here. + zstd = 0x09, +}; + +pub const ServerMsg = union(ServerTag) { + /// Who the client is now (its id and view in the session), how long the + /// dump that follows is, and the session's offset from UTC (a replica + /// guesses the session's time of day). A far client is told how many + /// blobs the dump holds (`blobs`). + welcome: struct { pid: u32, session: []const u8, client: u16 = 0, view: u8 = 0, dump_len: u64 = 0, gmtoff: i32 = 0, digest: u64 = 0, semantics: u64 = 0, blobs: u32 = 0 }, + refused: []const u8, + pong: u64, + dump: []const u8, + unit: []const u8, + screen: []const u8, + check: u64, + blobs: []const u8, + zstd: []const u8, +}; + +/// A message's header, for a payload sent on its own (a unit, a dump's +/// piece): no copy of it into a message buffer. +pub fn header(tag: u8, len: usize) [header_len]u8 { + var h: [header_len]u8 = undefined; + h[0] = tag; + std.mem.writeInt(u32, h[1..5], @intCast(len), .little); + return h; +} + +/// The other way: what a client is told, its slices borrowing `payload`. +pub fn decodeServer(tag: u8, payload: []const u8) Error!ServerMsg { + var r: std.Io.Reader = .fixed(payload); + const msg: ServerMsg = switch (std.enums.fromInt(ServerTag, tag) orelse return error.BadTag) { + .welcome => .{ .welcome = .{ + .pid = try r.takeInt(u32, .little), + .session = try r.take(try r.takeInt(u16, .little)), + .client = try r.takeInt(u16, .little), + .view = try r.takeByte(), + .dump_len = try r.takeInt(u64, .little), + .gmtoff = try r.takeInt(i32, .little), + .digest = try r.takeInt(u64, .little), + .semantics = try r.takeInt(u64, .little), + .blobs = try r.takeInt(u32, .little), + } }, + .refused => .{ .refused = try r.take(try r.takeInt(u16, .little)) }, + .pong => .{ .pong = try r.takeInt(u64, .little) }, + .dump => return .{ .dump = payload }, + .unit => return .{ .unit = payload }, + .screen => return .{ .screen = payload }, + .check => .{ .check = try r.takeInt(u64, .little) }, + .blobs => return .{ .blobs = payload }, + .zstd => return .{ .zstd = payload }, + }; + try end(&r); + return msg; +} + +pub fn encodeServer(out: []u8, msg: ServerMsg) Error![]const u8 { + var w: std.Io.Writer = .fixed(out); + const at = try beginMessage(&w, @backingInt(std.meta.activeTag(msg))); + switch (msg) { + .welcome => |h| { + try w.writeInt(u32, h.pid, .little); + try putSlice16(&w, h.session); + try w.writeInt(u16, h.client, .little); + try w.writeByte(h.view); + try w.writeInt(u64, h.dump_len, .little); + try w.writeInt(i32, h.gmtoff, .little); + try w.writeInt(u64, h.digest, .little); + try w.writeInt(u64, h.semantics, .little); + try w.writeInt(u32, h.blobs, .little); + }, + .refused => |words| try putSlice16(&w, words), + .pong => |v| try w.writeInt(u64, v, .little), + .dump, .unit, .screen, .blobs, .zstd => |bytes| try w.writeAll(bytes), + .check => |v| try w.writeInt(u64, v, .little), + } + try finishMessage(&w, at); + return w.buffered(); +} + +/// `Hello.version` alone, read out of the still-undecoded payload. +/// +/// Separate from `decodeClient` because of the guarantee the fixed offset above +/// exists to give: a decoder that validates `cols` and `rows` and then refuses +/// trailing bytes can never deliver it. A v2 hello with one more field would be +/// closed as a malformed message, and the `Refusal.version` byte a frontend +/// needs in order to say something true would never be sent — which is exactly +/// the case the field was put at offset zero for. So the version is asked for +/// first, on its own, before any of the layout that may have moved. +/// +/// An error rather than a zero on a payload shorter than two bytes, so a +/// truncated hello stays diagnosable too instead of reading as version 0. +pub fn helloVersion(payload: []const u8) Error!u16 { + var r: std.Io.Reader = .fixed(payload); + return r.takeInt(u16, .little); +} + +/// Frontend -> core, decoded. The `Event`'s slices BORROW the payload buffer, +/// exactly like the pty chunks the tui host hands to `update`: valid for that +/// one call and no longer. +pub const ClientMsg = union(enum) { + hello: Hello, + /// The client's end: `again`, it joins again for its view at once. + bye: struct { again: bool = false }, + /// A round trip's probe, answered `pong` with the same value. + ping: u64, + screen_ack: []const u8, + check, + far: bool, + want: []const u8, + stamp: [2]i64, + event: pardes.Event, +}; + +// --------------------------------------------------------------------------- +// primitives +// --------------------------------------------------------------------------- + +/// Length-prefixed, u16: paths, command lines, a key's text. Nothing here +/// is legitimately longer than 64 KiB and a u16 says so on the wire. +fn putSlice16(w: *std.Io.Writer, v: []const u8) Error!void { + if (v.len > std.math.maxInt(u16)) return error.Overlong; + try w.writeInt(u16, @intCast(v.len), .little); + try w.writeAll(v); +} + +/// ...and u32 for the ones that are: pty output, a paste, a file. +fn putSlice32(w: *std.Io.Writer, v: []const u8) Error!void { + if (v.len > max_payload) return error.Overlong; + try w.writeInt(u32, @intCast(v.len), .little); + try w.writeAll(v); +} + +/// One byte, 0 or 1, never "nonzero": the writer's `@intFromBool`. +fn getBool(r: *std.Io.Reader) Error!bool { + return switch (try r.takeByte()) { + 0 => false, + 1 => true, + else => error.BadValue, + }; +} + +/// IEEE-754 binary32, as its bit pattern in an explicit u32. A scalar +/// bitcast and not a struct blit: the format is the one thing a riscv32 +/// and an x86_64 do agree about. +fn getF32(r: *std.Io.Reader) Error!f32 { + const v: f32 = @bitCast(try r.takeInt(u32, .little)); + // A NaN or an infinity here is not a scroll distance. + if (!std.math.isFinite(v)) return error.BadValue; + return v; +} + +fn getSlice32(r: *std.Io.Reader) Error![]const u8 { + const n = try r.takeInt(u32, .little); + if (n > max_payload) return error.Overlong; + return r.take(n); +} + +/// A pane id the core can actually index. `Event.output{ .pane = 200 }` +/// would reach `p.panes[200]`. +fn getPane(r: *std.Io.Reader) Error!u8 { + const pane = try r.takeByte(); + if (pane >= pardes.MAX_PANES) return error.BadValue; + return pane; +} + +/// A grid the core can render into. Zero is refused rather than clamped: a +/// frontend that has not been sized yet must not be allowed to collapse a +/// shared session to nothing (see server.zig `geometry`). +fn getCols(r: *std.Io.Reader) Error!u16 { + const v = try r.takeInt(u16, .little); + if (v == 0 or v > max_cols) return error.BadValue; + return v; +} + +fn getRows(r: *std.Io.Reader) Error!u16 { + const v = try r.takeInt(u16, .little); + if (v == 0 or v > max_rows) return error.BadValue; + return v; +} + +fn getTag(r: *std.Io.Reader, comptime T: type) Error!T { + return std.enums.fromInt(T, try r.takeByte()) orelse error.BadTag; +} + +fn end(r: *std.Io.Reader) Error!void { + if (r.seek != r.end) return error.Trailing; +} + +/// Reserve a message header; `finishMessage` back-patches the length. Two +/// passes would mean walking a frame's runs twice to find out how long they +/// are, and the walk is the expensive half. +fn beginMessage(w: *std.Io.Writer, tag: u8) Error!usize { + const at = w.end; + try w.writeByte(tag); + try w.writeInt(u32, 0, .little); + return at; +} + +fn finishMessage(w: *std.Io.Writer, at: usize) Error!void { + const len = w.end - at - header_len; + if (len > max_payload) return error.Overlong; + std.mem.writeInt(u32, w.buffer[at + 1 ..][0..4], @intCast(len), .little); +} + +/// One complete message at the front of a stream buffer, or null when the rest +/// has not arrived. `total` is what the caller consumes. +pub const Framed = struct { tag: u8, payload: []const u8, total: usize }; + +pub fn framed(buf: []const u8) Error!?Framed { + if (buf.len < header_len) return null; + const len = std.mem.readInt(u32, buf[1..5], .little); + // Refused BEFORE the caller grows a buffer to hold it: an over-long prefix + // is the one field in this protocol that can ask for memory. + if (len > max_payload) return error.Overlong; + if (buf.len - header_len < len) return null; + return .{ .tag = buf[0], .payload = buf[header_len..][0..len], .total = header_len + len }; +} + +// --------------------------------------------------------------------------- +// frontend -> core +// --------------------------------------------------------------------------- + +/// Which tag a message travels under: the `ClientTag` of the same NAME, so a +/// new `Event` variant does not compile until it has a number here, rather +/// than a written-out table that can drift. +fn clientTag(msg: ClientMsg) ClientTag { + return switch (msg) { + .event => |ev| switch (ev) { + // Machine-local reports and 9P requests belong to the session owner. + .output, .eof, .exited, .lsp_resp, .pipe_resp, .search, .file_changed, .handed, .tick => unreachable, + inline else => |_, t| @field(ClientTag, @tagName(t)), + }, + inline else => |_, t| @field(ClientTag, @tagName(t)), + }; +} + +/// Does the build this frontend was compiled with carry pixel dimensions in a +/// resize? The FIELD is comptime-conditional (pardes.zig `CellPixels`); the +/// WIRE is not. +const has_cell_pixels = @hasField(pardes.CellPixels, "w"); + +fn putMetrics(w: *std.Io.Writer, metrics: ?pardes.RowMetrics) Error!void { + try w.writeByte(@intFromBool(metrics != null)); + if (metrics) |m| { + try w.writeInt(u16, m.body_w, .little); + try w.writeInt(u16, m.body_h, .little); + try w.writeInt(u16, m.tagline_w, .little); + try w.writeInt(u16, m.tagline_h, .little); + } +} + +fn getMetrics(r: *std.Io.Reader) Error!?pardes.RowMetrics { + if (!try getBool(r)) return null; + const m: pardes.RowMetrics = .{ .body_w = try r.takeInt(u16, .little), .body_h = try r.takeInt(u16, .little), .tagline_w = try r.takeInt(u16, .little), .tagline_h = try r.takeInt(u16, .little) }; + if (m.body_w == 0 or m.body_h == 0 or m.tagline_w == 0 or m.tagline_h == 0) return error.BadValue; + return m; +} + +fn putPlace(w: *std.Io.Writer, at: pardes.Layer.Place) Error!void { + for ([_]u16{ at.viewport.x, at.viewport.y, at.viewport.w, at.viewport.h, at.cols, at.rows, at.context_rows }) |n| try w.writeInt(u16, n, .little); +} + +fn getPlace(r: *std.Io.Reader) Error!pardes.Layer.Place { + var n: [7]u16 = undefined; + for (&n) |*x| x.* = try r.takeInt(u16, .little); + if (n[6] > n[5]) return error.BadValue; + return .{ .viewport = .{ .x = n[0], .y = n[1], .w = n[2], .h = n[3] }, .cols = n[4], .rows = n[5], .context_rows = n[6] }; +} + +fn putBodyHit(w: *std.Io.Writer, hit: ?pardes.Mouse.BodyHit) Error!void { + try w.writeByte(@intFromBool(hit != null)); + if (hit) |h| { + try w.writeInt(u32, h.serial, .little); + try w.writeInt(u16, h.row, .little); + try w.writeInt(u16, h.col, .little); + try w.writeInt(u32, @bitCast(h.pixel_x), .little); + try w.writeInt(u32, @bitCast(h.pixel_y), .little); + try putMetrics(w, h.metrics); + try putPlace(w, h.place); + } +} + +fn getBodyHit(r: *std.Io.Reader) Error!?pardes.Mouse.BodyHit { + if (!try getBool(r)) return null; + const hit: pardes.Mouse.BodyHit = .{ .serial = try r.takeInt(u32, .little), .row = try r.takeInt(u16, .little), .col = try r.takeInt(u16, .little), .pixel_x = try getF32(r), .pixel_y = try getF32(r), .metrics = (try getMetrics(r)) orelse return error.BadValue, .place = try getPlace(r) }; + if (!std.math.isFinite(hit.pixel_x) or !std.math.isFinite(hit.pixel_y)) return error.BadValue; + return hit; +} + +fn putTagHit(w: *std.Io.Writer, hit: ?pardes.TagHit) Error!void { + try w.writeByte(@intFromBool(hit != null)); + if (hit) |h| { + try w.writeByte(@backingInt(h.kind)); + try w.writeInt(u16, h.id, .little); + try w.writeInt(u32, h.serial, .little); + try w.writeInt(u16, h.col, .little); + try w.writeInt(u16, h.line, .little); + try w.writeInt(u32, @bitCast(h.pixel_x), .little); + try w.writeInt(u32, @bitCast(h.pixel_y), .little); + try putMetrics(w, h.metrics); + try putPlace(w, h.place); + } +} + +fn getTagHit(r: *std.Io.Reader) Error!?pardes.TagHit { + if (!try getBool(r)) return null; + const hit: pardes.TagHit = .{ + .kind = try getTag(r, pardes.TagKind), + .id = try r.takeInt(u16, .little), + .serial = try r.takeInt(u32, .little), + .col = try r.takeInt(u16, .little), + .line = try r.takeInt(u16, .little), + .pixel_x = try getF32(r), + .pixel_y = try getF32(r), + .metrics = (try getMetrics(r)) orelse return error.BadValue, + .place = try getPlace(r), + }; + if (!std.math.isFinite(hit.pixel_x) or !std.math.isFinite(hit.pixel_y)) return error.BadValue; + return hit; +} + +pub fn encodeClient(out: []u8, msg: ClientMsg) Error![]const u8 { + var w: std.Io.Writer = .fixed(out); + const at = try beginMessage(&w, @backingInt(clientTag(msg))); + switch (msg) { + .hello => |h| { + try w.writeInt(u16, h.version, .little); + try w.writeInt(u64, h.semantics, .little); + if (h.session.len > max_name) return error.Overlong; + try putSlice16(&w, h.session); + try w.writeByte(h.view orelse 0xff); + }, + .bye => |b| try w.writeByte(@intFromBool(b.again)), + .ping => |v| try w.writeInt(u64, v, .little), + .screen_ack, .want => |bytes| try w.writeAll(bytes), + .check => {}, + .far => |far| try w.writeByte(@intFromBool(far)), + .stamp => |s| for (s) |v| try w.writeInt(i64, v, .little), + .event => |ev| switch (ev) { + .key => |k| { + try w.writeInt(u32, k.cp, .little); + try putSlice16(&w, k.text); + try w.writeByte(@intFromBool(k.ctrl)); + try w.writeByte(@intFromBool(k.alt)); + try w.writeByte(@intFromBool(k.shift)); + }, + .mouse => |m| { + try w.writeByte(switch (m.button) { + inline else => |t| @backingInt(@field(ButtonTag, @tagName(t))), + }); + try w.writeByte(switch (m.kind) { + inline else => |t| @backingInt(@field(KindTag, @tagName(t))), + }); + try w.writeInt(u16, m.col, .little); + try w.writeInt(u16, m.row, .little); + try w.writeByte(@intFromBool(m.ctrl)); + try w.writeByte(@intFromBool(m.shift)); + try w.writeByte(@intFromBool(m.alt)); + try putBodyHit(&w, m.body_hit); + try putTagHit(&w, m.tag_hit); + }, + .resize => |rs| { + try w.writeInt(u16, rs.cols, .little); + try w.writeInt(u16, rs.rows, .little); + // The conventional 1:2 cell aspect when this build has no + // pixels of its own, which is the same default the field + // carries where it exists. + try w.writeInt(u16, if (comptime has_cell_pixels) rs.cell_pixels.w else 8, .little); + try w.writeInt(u16, if (comptime has_cell_pixels) rs.cell_pixels.h else 16, .little); + try putMetrics(&w, rs.row_metrics); + }, + .paste => |b| try putSlice32(&w, b), + .command => |line| try putSlice16(&w, line), + .pdf_scroll => |s| { + try w.writeByte(s.pane); + try w.writeInt(u32, @bitCast(s.delta_pixels), .little); + try w.writeByte(@intFromBool(s.glide)); + }, + .pointer_leave => {}, + .focus => |focused| try w.writeByte(@intFromBool(focused)), + .frontend => |f| { + try w.writeByte(@intFromBool(f.windowed)); + try w.writeByte(@intFromBool(f.native_images)); + try w.writeByte(@intFromBool(f.native_image_patches)); + }, + // See `clientTag`: no tag, so nothing to encode. + .output, .eof, .exited, .lsp_resp, .pipe_resp, .search, .file_changed, .handed, .tick => unreachable, + }, + } + try finishMessage(&w, at); + return w.buffered(); +} + +pub fn decodeClient(tag: u8, payload: []const u8) Error!ClientMsg { + var r: std.Io.Reader = .fixed(payload); + const msg: ClientMsg = switch (std.enums.fromInt(ClientTag, tag) orelse return error.BadTag) { + .hello => .{ .hello = .{ + .version = try r.takeInt(u16, .little), + .semantics = try r.takeInt(u64, .little), + .session = blk: { + const n = try r.takeInt(u16, .little); + if (n > max_name) return error.BadValue; + break :blk try r.take(n); + }, + .view = switch (try r.takeByte()) { + 0xff => null, + else => |k| k, + }, + } }, + .bye => .{ .bye = .{ .again = try getBool(&r) } }, + .ping => .{ .ping = try r.takeInt(u64, .little) }, + .screen_ack => return .{ .screen_ack = payload }, + .check => .check, + .far => .{ .far = try getBool(&r) }, + .want => return .{ .want = payload }, + .stamp => .{ .stamp = .{ try r.takeInt(i64, .little), try r.takeInt(i64, .little) } }, + .key => blk: { + const cp = try r.takeInt(u32, .little); + // `Key.cp` is a u21, and the specials live in the private-use + // plane below this bound. A larger number is not a codepoint and + // @intCast of it would panic in a release build's own decoder. + if (cp > 0x10FFFF) return error.BadValue; + break :blk .{ .event = .{ .key = .{ + .cp = @intCast(cp), + .text = try r.take(try r.takeInt(u16, .little)), + .ctrl = try getBool(&r), + .alt = try getBool(&r), + .shift = try getBool(&r), + } } }; + }, + .mouse => .{ .event = .{ .mouse = .{ + .button = switch (try getTag(&r, ButtonTag)) { + inline else => |t| @field(pardes.Mouse.Button, @tagName(t)), + }, + .kind = switch (try getTag(&r, KindTag)) { + inline else => |t| @field(pardes.Mouse.Kind, @tagName(t)), + }, + .col = try r.takeInt(u16, .little), + .row = try r.takeInt(u16, .little), + .ctrl = try getBool(&r), + .shift = try getBool(&r), + .alt = try getBool(&r), + .body_hit = try getBodyHit(&r), + .tag_hit = try getTagHit(&r), + } } }, + .resize => blk: { + var ev: pardes.Event = .{ .resize = .{ .cols = try getCols(&r), .rows = try getRows(&r) } }; + const px_w = try r.takeInt(u16, .little); + const px_h = try r.takeInt(u16, .little); + // Read either way — the bytes are on the wire — and kept only by a + // build that has somewhere to keep them. + if (comptime has_cell_pixels) ev.resize.cell_pixels = .{ .w = px_w, .h = px_h }; + ev.resize.row_metrics = try getMetrics(&r); + break :blk .{ .event = ev }; + }, + .paste => .{ .event = .{ .paste = try getSlice32(&r) } }, + .command => .{ .event = .{ .command = try r.take(try r.takeInt(u16, .little)) } }, + .pdf_scroll => .{ .event = .{ .pdf_scroll = .{ .pane = try getPane(&r), .delta_pixels = try getF32(&r), .glide = try getBool(&r) } } }, + .pointer_leave => .{ .event = .pointer_leave }, + .focus => .{ .event = .{ .focus = try getBool(&r) } }, + .frontend => .{ .event = .{ .frontend = .{ .windowed = try getBool(&r), .native_images = try getBool(&r), .native_image_patches = try getBool(&r) } } }, + }; + try end(&r); + return msg; +} + +/// Slack over a message's variable payload, covering every fixed field any +/// message here has plus its own header. +const msg_slack = header_len + 64; + +/// An upper bound on `encodeClient`'s output, so a caller sizes its buffer +/// once instead of guessing and retrying. +pub fn clientBound(msg: ClientMsg) usize { + return msg_slack + switch (msg) { + .hello => |h| h.session.len, + .bye, .ping, .check, .far, .stamp => 0, + .screen_ack, .want => |bytes| bytes.len, + .event => |ev| switch (ev) { + // Its hits' places (14 bytes each) past the slack. + .mouse => 28, + .resize, .pdf_scroll, .pointer_leave, .focus, .frontend => 0, + .key => |k| k.text.len, + .paste => |b| b.len, + .command => |line| line.len, + // See `clientTag`: not on this wire in this direction. + .output, .eof, .exited, .lsp_resp, .pipe_resp, .search, .file_changed, .handed, .tick => unreachable, + }, + }; +} + +// --------------------------------------------------------------------------- +// tests +// --------------------------------------------------------------------------- +// +// Two obligations. Every message round-trips to a deep-equal value, because a +// codec written by hand is a codec whose two halves drift; and every malformed +// shape is REFUSED, because this parser is fed by a socket and a frame that is +// misread rather than refused is an out-of-bounds index. + +const testing = std.testing; + +/// Round-trip one frontend -> core message through the framing too, so a +/// length prefix that disagrees with the payload cannot pass. +fn roundClient(buf: []u8, msg: ClientMsg) !ClientMsg { + const bytes = try encodeClient(buf, msg); + const f = (try framed(bytes)).?; + try testing.expectEqual(bytes.len, f.total); + return decodeClient(f.tag, f.payload); +} + +test "detached wire: every Event variant round-trips" { + var buf: [4096]u8 = undefined; + + // The tag space is the protocol's own, so assert the numbers themselves: + // a renumbering here breaks every deployed frontend and must be a diff + // somebody reads, not a silent change. + try testing.expectEqual(@as(u8, 0x01), @backingInt(ClientTag.hello)); + try testing.expectEqual(@as(u8, 0x10), @backingInt(ClientTag.key)); + try testing.expectEqual(@as(u8, 0x1d), @backingInt(ClientTag.pointer_leave)); + + { + const got = try roundClient(&buf, .{ .hello = .{ .session = "work" } }); + try testing.expectEqual(version, got.hello.version); + try testing.expectEqual(semantics, got.hello.semantics); + try testing.expectEqualStrings("work", got.hello.session); + } + try testing.expect((try roundClient(&buf, .{ .bye = .{ .again = true } })).bye.again); + try testing.expectEqual(@as(?u8, 2), (try roundClient(&buf, .{ .hello = .{ .session = "work", .view = 2 } })).hello.view); + try testing.expectEqual(@as(u64, 0xfeed_beef_0000_0001), (try roundClient(&buf, .{ .ping = 0xfeed_beef_0000_0001 })).ping); + { + // The other way: framed the same, its tag the ServerTag's number. + const bytes = try encodeServer(&buf, .{ .welcome = .{ .pid = 42, .session = "work" } }); + const f = (try framed(bytes)).?; + try testing.expectEqual(@as(u8, 0x01), f.tag); + try testing.expectEqualSlices(u8, &.{ 42, 0, 0, 0, 4, 0, 'w', 'o', 'r', 'k', 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 }, f.payload); + const back = (try decodeServer(f.tag, f.payload)).welcome; + try testing.expectEqualStrings("work", back.session); + try testing.expectEqual(@as(u32, 42), back.pid); + try testing.expectEqual(@as(u8, 0x03), (try framed(try encodeServer(&buf, .{ .pong = 7 }))).?.tag); + } + + { + const key: pardes.Key = .{ .cp = pardes.Key.page_down, .text = "ü", .ctrl = true, .alt = false, .shift = true }; + const got = (try roundClient(&buf, .{ .event = .{ .key = key } })).event.key; + try testing.expectEqual(key.cp, got.cp); + try testing.expectEqualStrings(key.text, got.text); + try testing.expectEqual(key.ctrl, got.ctrl); + try testing.expectEqual(key.alt, got.alt); + try testing.expectEqual(key.shift, got.shift); + } + { + // Every button and every kind, because the two mapping switches are + // the only place a value can be mistranslated and still decode. + for (std.enums.values(pardes.Mouse.Button)) |button| { + for (std.enums.values(pardes.Mouse.Kind)) |kind| { + const m: pardes.Mouse = .{ .button = button, .kind = kind, .col = 4200, .row = 7, .ctrl = true, .shift = true, .alt = true }; + const got = (try roundClient(&buf, .{ .event = .{ .mouse = m } })).event.mouse; + try testing.expectEqual(m.button, got.button); + try testing.expectEqual(m.kind, got.kind); + try testing.expectEqual(m.col, got.col); + try testing.expectEqual(m.row, got.row); + try testing.expectEqual(m.ctrl, got.ctrl); + try testing.expectEqual(m.shift, got.shift); + try testing.expectEqual(m.alt, got.alt); + } + } + } + { + const got = (try roundClient(&buf, .{ .event = .{ .resize = .{ .cols = 56, .rows = 14 } } })).event.resize; + try testing.expectEqual(@as(u16, 56), got.cols); + try testing.expectEqual(@as(u16, 14), got.rows); + // Pixels travel whether or not this build has them; where it does, the + // conventional 1:2 default survives the trip. + if (comptime has_cell_pixels) { + try testing.expectEqual(@as(u16, 8), got.cell_pixels.w); + try testing.expectEqual(@as(u16, 16), got.cell_pixels.h); + } + } + try testing.expectEqualStrings("clip", (try roundClient(&buf, .{ .event = .{ .paste = "clip" } })).event.paste); + try testing.expectEqualStrings("Look /x", (try roundClient(&buf, .{ .event = .{ .command = "Look /x" } })).event.command); + { + const got = (try roundClient(&buf, .{ .event = .{ .pdf_scroll = .{ .pane = 2, .delta_pixels = -12.5, .glide = false } } })).event.pdf_scroll; + try testing.expectEqual(@as(u8, 2), got.pane); + try testing.expectEqual(@as(f32, -12.5), got.delta_pixels); + try testing.expect(!got.glide); + } + try testing.expectEqual( + std.meta.Tag(pardes.Event).pointer_leave, + (try roundClient(&buf, .{ .event = .pointer_leave })).event, + ); +} + +test "detached wire: a session is never told to do a frontend's remembering" { + // The mirror of the test above, and of client.zig's "a frontend is never + // asked to fork, write, or watch". That one pins what may reach a FRONTEND; + // this one pins what may reach the SESSION, and until the six tags below it + // names were deleted the protocol was asymmetric: server -> client carried + // only what a display can do, while client -> server still carried the + // machine-local host's own reports, which server.zig's `apply` hands + // straight to `core.update`. + // + // Adding a name here is meant to be an ARGUMENT, not a formality, and the + // bar is one sentence: A HUMAN DID IT. A keystroke, a click, a + // window resized, a paste, a command line executed, a pointer leaving the + // window, the window's focus — plus the session words that say who is speaking, time the link and end it. A pty's + // output, a worker's answer, a watched file's new bytes and an animation + // tick all fail that bar the same way: nobody did them, a machine reported + // them, and the machine that reports them is the one already holding the + // core. + const allowed = [_][]const u8{ + // Who this connection is, its round trip, and that it is finished, + // and which terminal state its replica holds (a protocol's word, + // as a ping is). + "hello", "bye", "ping", "screen_ack", "check", + // ...and how far it is, and which of the join's blobs it lacks. + "far", "want", + // ...and when its next input was, by the session's clocks. + "stamp", + // ...and everything a person can do to a window. + "key", "mouse", "resize", + "paste", "command", "pdf_scroll", "pointer_leave", "focus", + // ...and which of its frontends the person sits at: a window, or a + // terminal (what the view draws, and the words it takes). + "frontend", + }; + + // One: the tag set is exactly that, named rather than counted, so + // re-adding `output` fails with the name in the failure. + inline for (std.enums.values(ClientTag)) |t| { + for (allowed) |ok| { + if (std.mem.eql(u8, @tagName(t), ok)) break; + } else { + std.debug.print("ClientTag.{s} is not something a human did\n", .{@tagName(t)}); + return error.MachineLocalReportOnTheWire; + } + } + try testing.expectEqual(allowed.len, std.enums.values(ClientTag).len); + + // Two: and no tag BYTE outside them decodes either — the check above is + // about this build's enum, this one is about the bytes on the socket. The + // six deleted numbers (0x13..0x17, 0x1e) are in the ones that must answer + // `BadTag`, so a frontend built before this change cannot forge a pane's + // output into a session built after it (as are 0x1b and 0x1c, once a + // pinch and a touch scroll). + var accepted: usize = 0; + for (0..256) |i| { + const tag: u8 = @intCast(i); + // Empty payloads on purpose: what is asked is whether the TAG is known. + // A known one fails later (`EndOfStream`) or succeeds, never with + // `BadTag`. + if (decodeClient(tag, &.{})) |_| accepted += 1 else |err| switch (err) { + error.BadTag => continue, + else => accepted += 1, + } + const named = for (allowed) |ok| { + const want = std.meta.stringToEnum(ClientTag, ok).?; + if (@backingInt(want) == tag) break true; + } else false; + if (!named) { + std.debug.print("tag 0x{x:0>2} is decodable by a session and is not something a human did\n", .{tag}); + return error.MachineLocalReportOnTheWire; + } + } + try testing.expectEqual(allowed.len, accepted); +} + +test "detached wire: a truncated message is refused at every length" { + var buf: [4096]u8 = undefined; + + // Every prefix of a real message. The framing must say "not yet" for the + // ones that are short, and the decoder must say "truncated" for a payload + // whose header lies about its length — never read past the slice. + const whole = try encodeClient(&buf, .{ .event = .{ .key = .{ .cp = 'a', .text = "a" } } }); + var copy: [64]u8 = undefined; + @memcpy(copy[0..whole.len], whole); + for (header_len + 1..whole.len) |cut| { + try testing.expectEqual(@as(?Framed, null), try framed(copy[0..cut])); + // ...and the same bytes handed to the decoder with the header's length + // left claiming the whole message, which is how a decoder is walked + // off the end of its buffer. + try testing.expectError(error.EndOfStream, decodeClient(copy[0], copy[header_len..cut])); + } + // Shorter than the header itself is not yet a message at all. + for (0..header_len + 1) |cut| + try testing.expectEqual(@as(?Framed, null), try framed(copy[0..cut])); + // A payload with bytes LEFT OVER is refused too: it is not this message. + try testing.expectError(error.Trailing, decodeClient(@backingInt(ClientTag.pointer_leave), "x")); +} + +test "detached wire: an unknown tag is refused, never guessed" { + // 0x00 and 0xff have never been assigned, and 0x0f sits in the gap between + // the session tags and the input tags. All three are the same answer. + for ([_]u8{ 0x00, 0x0f, 0x1f, 0xff }) |tag| { + try testing.expectError(error.BadTag, decodeClient(tag, "")); + } + // A tag NESTED in a payload gets the same treatment: a mouse button. + try testing.expectError(error.BadTag, decodeClient( + @backingInt(ClientTag.mouse), + &.{ 0xff, 0x00, 0, 0, 0, 0, 0 }, + )); +} + +test "detached wire: an over-long length prefix is refused before it is believed" { + // The prefix a hostile or corrupt peer sends to make the receiver allocate + // or index by it. `framed` must refuse rather than wait for 4 GiB. + var head: [header_len]u8 = .{ @backingInt(ClientTag.paste), 0, 0, 0, 0 }; + std.mem.writeInt(u32, head[1..5], max_payload + 1, .little); + try testing.expectError(error.Overlong, framed(&head)); + std.mem.writeInt(u32, head[1..5], std.math.maxInt(u32), .little); + try testing.expectError(error.Overlong, framed(&head)); + // At the boundary it is a legal prefix and simply has not all arrived. + std.mem.writeInt(u32, head[1..5], max_payload, .little); + try testing.expectEqual(@as(?Framed, null), try framed(&head)); + + // An INNER length prefix, past the payload it sits in but inside the + // protocol's cap — the one an outer-frame check cannot catch. + var paste: [8]u8 = undefined; + std.mem.writeInt(u32, paste[0..4], 4096, .little); + @memcpy(paste[4..8], "abcd"); + try testing.expectError(error.EndOfStream, decodeClient(@backingInt(ClientTag.paste), &paste)); + // ...and past the cap, which is refused rather than read. + std.mem.writeInt(u32, paste[0..4], max_payload + 1, .little); + try testing.expectError(error.Overlong, decodeClient(@backingInt(ClientTag.paste), &paste)); +} + +test "detached wire: values a field cannot mean are refused" { + // A bool is 0 or 1. `2` used to be "true" in every hand-written codec that + // ever silently accepted a corrupt stream. + try testing.expectError(error.BadValue, decodeClient( + @backingInt(ClientTag.key), + &.{ 'a', 0, 0, 0, 0, 0, 2, 0, 0 }, + )); + // A codepoint past Unicode's last: @intCast into Key.cp's u21 would panic. + try testing.expectError(error.BadValue, decodeClient( + @backingInt(ClientTag.key), + &.{ 0x00, 0x00, 0x11, 0x00, 0, 0, 0, 0, 0 }, + )); + // A pane the core cannot index. `pdf_scroll` reads its pane byte before the + // f32 that follows, so a one-byte payload reaches the check this is about + // rather than tripping `EndOfStream` first. + try testing.expectError(error.BadValue, decodeClient( + @backingInt(ClientTag.pdf_scroll), + &.{pardes.MAX_PANES}, + )); + // A session name longer than the daemon keeps one: refused, never cut + // to another session's name. + { + var hello: [12 + max_name + 1]u8 = @splat('x'); + std.mem.writeInt(u16, hello[0..2], version, .little); + std.mem.writeInt(u16, hello[10..12], max_name + 1, .little); + try testing.expectError(error.BadValue, decodeClient(@backingInt(ClientTag.hello), &hello)); + std.mem.writeInt(u16, hello[10..12], max_name, .little); + hello[hello.len - 1] = 0xff; + try testing.expectEqual(@as(usize, max_name), (try decodeClient(@backingInt(ClientTag.hello), &hello)).hello.session.len); + try testing.expect(header_len + hello.len == hello_max); + } + // A NaN or an infinite scroll distance. + { + var scroll: [6]u8 = .{ 0, 0, 0, 0, 0, 1 }; + std.mem.writeInt(u32, scroll[1..5], @bitCast(std.math.nan(f32)), .little); + try testing.expectError(error.BadValue, decodeClient(@backingInt(ClientTag.pdf_scroll), &scroll)); + std.mem.writeInt(u32, scroll[1..5], @bitCast(std.math.inf(f32)), .little); + try testing.expectError(error.BadValue, decodeClient(@backingInt(ClientTag.pdf_scroll), &scroll)); + } +} + +test "detached wire: max_payload bounds every message this protocol can build" { + // A 4 MiB paste, which is the tty's own cap, fits. + try testing.expect((4 << 20) + header_len + 4 <= max_payload); + // A slice past the width of its own length prefix is refused by the + // ENCODER, rather than written and rejected at the far end. A command line + // is u16-prefixed because nothing legitimately types 64 KiB of one. + const gpa = testing.allocator; + const huge = try gpa.alloc(u8, std.math.maxInt(u16) + 1); + defer gpa.free(huge); + @memset(huge, 'x'); + const room = try gpa.alloc(u8, huge.len + header_len + 2); + defer gpa.free(room); + try testing.expectError(error.Overlong, encodeClient(room, .{ .event = .{ .command = huge } })); + // ...and a buffer the caller sized too small is WriteFailed, which is the + // server's signal to drop that one message rather than the client. + var small: [8]u8 = undefined; + try testing.expectError(error.WriteFailed, encodeClient(&small, .{ .event = .{ .paste = "0123456789" } })); +} + +test "detached wire carries exact pointer metrics" { + var logical: [12]pardes.Cell = @splat(.{}); + var layer: pardes.Layer = .{ .id = 0, .serial = 42, .viewport = .{ .x = 0, .y = 0, .w = 2, .h = 4 }, .cols = 2, .rows = 6, .context_rows = 2, .cells = &logical, .cursor = .{ .x = 0, .y = 5, .bar = true } }; + layer.context_separators.set(0); + var tag_cells: [3]pardes.Cell = @splat(.{}); + const tag: pardes.Layer = .{ .kind = .column, .id = 1, .viewport = .{ .x = 0, .y = 0, .w = 2, .h = 1 }, .cols = 3, .rows = 1, .bg = .{ 11, 22, 33 }, .cells = &tag_cells, .cursor = .{ .x = 2, .y = 0, .bar = true } }; + const pointer = layer.bodyHit(4, 27, 8, 16, 6, 8).?; + const tag_pointer = tag.tagHit(11, 8, 8, 16, 4, 8).?; + const message: ClientMsg = .{ .event = .{ .mouse = .{ .col = 0, .row = 1, .button = .left, .kind = .press, .body_hit = pointer, .tag_hit = tag_pointer } } }; + var mouse_bytes: [256]u8 = undefined; + const mouse_encoded = try encodeClient(&mouse_bytes, message); + const mouse_packet = (try framed(mouse_encoded)).?; + const mouse = (try decodeClient(mouse_packet.tag, mouse_packet.payload)).event.mouse; + try std.testing.expectEqualDeep(pointer, mouse.body_hit.?); + try std.testing.expectEqualDeep(tag_pointer, mouse.tag_hit.?); + try std.testing.expect(mouse_encoded.len <= clientBound(message)); +} diff --git a/test/daemon.py b/test/daemon.py index f3c927ad..52e0bccd 100644 --- a/test/daemon.py +++ b/test/daemon.py @@ -205,7 +205,7 @@ def semantics(binary): class Replica: - """A replica's connection (src/detached/wire.zig): length-prefixed + """A replica's connection (src/wire.zig): length-prefixed messages, a tag byte and a little-endian u32 length. It is a near client: its first word after the hello says so.""" WIRE = 19 -- cgit v1.3