//! 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"); /// 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 = 14; /// 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) and the walker codec's assumptions /// (pointer width, byte order). Not the OS: a Linux client of a FreeBSD /// session is the main case, and what differs there is the host's, taped. /// 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{t} grammars {} {} {} {} mupdf {} themes {} workspace_tag {} sources {} board {d}x{d}\nusize {d} {t}\n{s}", .{ version, config.version, config.commit orelse "unstamped", config.platform, 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, }, )); }; /// 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, key = 0x10, mouse = 0x11, resize = 0x12, paste = 0x18, command = 0x19, pdf_scroll = 0x1a, pinch = 0x1b, touch_scroll = 0x1c, pointer_leave = 0x1d, focus = 0x1e, }; 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, }; /// 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; /// 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, }; pub const ServerMsg = union(ServerTag) { welcome: struct { pid: u32, session: []const u8 }, refused: []const u8, pong: u64, }; 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); }, .refused => |words| try putSlice16(&w, words), .pong => |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 tty host hands to `update`: valid for that /// one call and no longer. pub const ClientMsg = union(enum) { hello: Hello, bye, /// A round trip's probe, answered `pong` with the same value. ping: u64, 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. `pinch` in // particular multiplies into a zoom factor the pane keeps, so one bad // value poisons that pane for the rest of the session. 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 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); } } 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 }; 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(u32, @bitCast(h.pixel_x), .little); try w.writeInt(u32, @bitCast(h.pixel_y), .little); try putMetrics(w, h.metrics); } } 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), .pixel_x = try getF32(r), .pixel_y = try getF32(r), .metrics = (try getMetrics(r)) orelse return error.BadValue, }; 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); }, .bye => {}, .ping => |v| try w.writeInt(u64, 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)); }, .pinch => |v| try w.writeInt(u32, @bitCast(v), .little), .touch_scroll => |v| try w.writeInt(u32, @bitCast(v), .little), .pointer_leave => {}, .focus => |focused| try w.writeByte(@intFromBool(focused)), // 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); }, } }, .bye => .bye, .ping => .{ .ping = try r.takeInt(u64, .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) } } }, .pinch => .{ .event = .{ .pinch = try getF32(&r) } }, .touch_scroll => .{ .event = .{ .touch_scroll = try getF32(&r) } }, .pointer_leave => .{ .event = .pointer_leave }, .focus => .{ .event = .{ .focus = 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 => 0, .event => |ev| switch (ev) { .mouse, .resize, .pdf_scroll, .pinch, .touch_scroll, .pointer_leave, .focus => 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.expectEqual(ClientMsg.bye, try roundClient(&buf, .bye)); 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' }, f.payload); 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(@as(f32, 1.25), (try roundClient(&buf, .{ .event = .{ .pinch = 1.25 } })).event.pinch); try testing.expectEqual(@as(f32, -0.75), (try roundClient(&buf, .{ .event = .{ .touch_scroll = -0.75 } })).event.touch_scroll); 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 pinch, 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. "hello", "bye", "ping", // ...and everything a person can do to a window. "key", "mouse", "resize", "paste", "command", "pdf_scroll", "pinch", "touch_scroll", "pointer_leave", "focus", }; // 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 250 that must answer // `BadTag`, so a frontend built before this change cannot forge a pane's // output into a session built after it. 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); try testing.expectEqual(@as(usize, max_name), (try decodeClient(@backingInt(ClientTag.hello), hello[0 .. hello.len - 1])).hello.session.len); try testing.expect(header_len + hello.len - 1 == hello_max); } // A NaN scroll distance. `pinch` multiplies into a zoom the pane keeps. { var pinch: [4]u8 = undefined; std.mem.writeInt(u32, &pinch, @bitCast(std.math.nan(f32)), .little); try testing.expectError(error.BadValue, decodeClient(@backingInt(ClientTag.pinch), &pinch)); std.mem.writeInt(u32, &pinch, @bitCast(std.math.inf(f32)), .little); try testing.expectError(error.BadValue, decodeClient(@backingInt(ClientTag.touch_scroll), &pinch)); } } 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)); }