summaryrefslogtreecommitdiff
path: root/src/detached
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-04 23:15:35 -0300
committerGabriel Schneider <[email protected]>2026-11-05 09:54:56 -0300
commit67beb493ea18de9d7b0083ba20b34b8bb34fd74c (patch)
treeb1d9c39dadf3b90cbeeb3ffaa55b90b2ae0e3c21 /src/detached
parentba3f55e71325f31399fbd2134868d6ba7f774451 (diff)
downloadpardes-67beb493ea18de9d7b0083ba20b34b8bb34fd74c.tar.gz
pardes-67beb493ea18de9d7b0083ba20b34b8bb34fd74c.zip
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 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNAtZenFv4weoMD3cge
Diffstat (limited to 'src/detached')
-rw-r--r--src/detached/wire.zig975
1 files changed, 0 insertions, 975 deletions
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));
-}