1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
|
//! 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 {} workspace_tag {} sources {}\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.workspace_tag, config.embed_sources, @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 before the rest of the hello, whose layout
/// may have moved: a mismatch is said in words, and a payload shorter than
/// two bytes is an error, not 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.
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" {
// What may reach the SESSION from a client.
//
// 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.
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));
}
|