summaryrefslogtreecommitdiff
path: root/docs/next-daemon.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-10-29 12:32:23 -0300
committerGabriel Schneider <[email protected]>2026-10-29 13:11:16 -0300
commitf1f52054e3fe82f94697561d6fe9f9c14774f5de (patch)
tree7d366158a0ba599449aaa5c20b03bbe8bdc3f8d3 /docs/next-daemon.md
parent7e6834ba5eff5c0e61891ec1935e5e0ca8291c2f (diff)
downloadpardes-f1f52054e3fe82f94697561d6fe9f9c14774f5de.tar.gz
pardes-f1f52054e3fe82f94697561d6fe9f9c14774f5de.zip
docs/next-daemon.md: FreeBSD notes, for phase 5 (building, deploying and running on the box, what differs there, what 207 ms costs)
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Diffstat (limited to 'docs/next-daemon.md')
-rw-r--r--docs/next-daemon.md133
1 files changed, 133 insertions, 0 deletions
diff --git a/docs/next-daemon.md b/docs/next-daemon.md
index d164eced..e63f69c6 100644
--- a/docs/next-daemon.md
+++ b/docs/next-daemon.md
@@ -267,3 +267,136 @@ Trap found on the way: glibc's `tcgetattr` writes its 60-byte `struct
termios` into Zig's `std.c.termios`, which is 44 (the kernel's layout),
and overran the stack, clobbering a neighbouring local in the forked
child; `std.posix.tcgetattr` (an ioctl on that layout) is the right one.
+
+## FreeBSD notes
+
+Groundwork for phase 5's main test, a client here and the session on the
+FreeBSD box (2026-10-29): the tty pardes is built here for FreeBSD and
+runs there. The GUI is not built for it, since frontends stay local.
+
+The box runs FreeBSD 15.1 amd64 at 65.109.81.103, 207 ms away. Port 22 is
+the host's root shell; port 2222 is a git jail and is never touched.
+Everything of ours lives in `/root/pardes-test`, nothing outside it.
+
+- **Building.** Everything, the C deps included, cross-compiles here:
+
+ ```sh
+ export PATH=$HOME/.local/bin:$PATH
+ E='env -u PARDES_PID -u PARDES_PANE -u PARDES_9P'
+ $E zig build -Dplatform=tty -Dtarget=x86_64-freebsd.15.0 >log 2>&1
+ # zig-out/bin/pardes-freebsd-x86_64
+ $E zig build test-install -Dplatform=tty -Dtarget=x86_64-freebsd.15.0 >log 2>&1
+ # zig-out/test/{main,panes,kitty,9p,fonts,...}, named for their root files
+ ```
+
+ The `.15.0` matters: Zig's default FreeBSD (14.0) links
+ `libutil.so.9`, and 15 ships only `.so.10`. `test-install` installs
+ the test-build programs instead of running them. A test binary takes
+ no filter when it runs, so running one test alone means a rebuild
+ with `-Dtest-filter=<name>` (and `--prefix <dir>` to keep the full set).
+- **Deploying.** `-F /dev/null` is required here, because /etc/ssh is
+ owned by nobody:
+
+ ```sh
+ S='-F /dev/null -o BatchMode=yes -o IdentitiesOnly=yes -o UserKnownHostsFile=/home/goblin/.ssh/known_hosts -i /home/goblin/.ssh/id_ed25519'
+ zstd -q -f -T0 zig-out/bin/pardes-freebsd-x86_64 -o p.zst # 108 MB Debug; ~11 s in all
+ scp $S p.zst [email protected]:/root/pardes-test/bin/pardes.zst
+ ssh $S [email protected] 'cd /root/pardes-test/bin && zstd -q -d -f pardes.zst && rm pardes.zst'
+ ```
+
+ The same steps are scripts in `.scratch/daemon/bsd/`: `zb.sh <log>
+ <args>` (a build, PARDES_* stripped, logged there), `deploy.sh <file>
+ [name]` and `bx.sh '<command>'` (a command run there with env.sh
+ sourced). `sshcheck.py` drives a session through `ssh -tt` from a
+ local pty, and `fwd9p.py` times 9P through `ssh -L`.
+- **The box's layout.** Under `/root/pardes-test`:
+ - `bin/`: pardes, and `python3` linked to python3.12;
+ - `run/`: the runtime directory (sockets, the daemon's lock);
+ - `home/` and `tmp/`;
+ - `src/`: the tracked tree, which the tests need: they read docs/typ,
+ and make their temporary directories in `.zig-cache/tmp` under the
+ working directory;
+ - `test-bin/test/` and `logs/`;
+ - `env.sh`, which points every path pardes uses there (HOME carries
+ the XDG defaults):
+
+ ```sh
+ T=/root/pardes-test
+ export HOME=$T/home XDG_RUNTIME_DIR=$T/run TMPDIR=$T/tmp
+ export PATH=$T/bin:$PATH SHELL=/usr/local/bin/bash TERM=${TERM:-xterm-256color}
+ ```
+- **Running.**
+ - A session: `ssh -t $S [email protected] '. /root/pardes-test/env.sh;
+ pardes notes.txt'`, and `pardes --attach=<name>` the same way.
+ - The unit tests: `cd /root/pardes-test/src && ../test-bin/test/main`.
+ Some tests name `/tmp/pardes-*` outright and leave seven empty
+ directories there (`pardes-arg-save` and the like): rmdir them after.
+ - The e2e scripts, from `src/`: `python3 -B test/daemon.py
+ /root/pardes-test/bin/pardes 20`, and `test/fs.py` the same way.
+ - Kill every process you start there by its pid, and check `ps -axww`
+ afterwards.
+- **What FreeBSD does differently.** Each item was found on the box, and
+ each is fixed where pardes met it unless it says otherwise:
+ - A write to a terminal that is gone fails with ENXIO, not EIO. std
+ does not expect that errno, and a Debug build traced it to stderr,
+ which is the same dead terminal, recursing until the stack ran out:
+ a session whose ssh dropped hung. Tracing is off on FreeBSD
+ (main.zig).
+ - A signal whose action is to be ignored is dropped when it is sent,
+ sigwait or not, so WINCH never reached the session's watcher. A
+ handler that does nothing keeps it (tty.zig).
+ - waitid's P_PID is 0, WEXITED 16 and WNOWAIT 8, and its id is 64
+ bits. With Linux's numbers a command pane's exit was never seen.
+ - There is no /proc. A shell's directory and program come from sysctl
+ instead (kern.proc.cwd, kern.proc.pathname).
+ - `ttyTaken` answers taken for any foreground group but the
+ shell's, so a nested shell counts as a job.
+ - `signalSession` stays Linux-only, so Kill leaves a command's `&`
+ jobs running there.
+ - File watching uses FreeBSD 15's inotify: Linux's events, with its
+ own IN_CLOEXEC and IN_NONBLOCK.
+ - `shm_open` refuses O_NONBLOCK; its names are not files, so there is
+ no FIFO to fear. A `write` does not grow a shared memory object.
+ - A kitty `t=f` naming a FIFO hung the open everywhere but Linux; a
+ stat by path now comes first.
+ - A Unix socket whose listen queue is full refuses a connect with
+ ECONNREFUSED, exactly as a socket nobody listens on does. The
+ registry sweep reads that refusal as a dead session, so it could
+ remove a live session's socket while its queue overflows. **Open:**
+ the unit test "the registry sweep takes the dead entries" fails on
+ it.
+- **The tests there.** The box runs them as root, with no zls, fish or
+ fonts installed.
+ - main: 1138 passed, 36 skipped, 4 failed: the sweep above; the LSP
+ format retry (no zls); and two tests that make a file or directory
+ unreadable, which root reads anyway.
+ - panes: 224 passed, 1 failed (`Shell fish`: no fish). kitty: 43
+ passed. The small programs all pass but fonts (no fonts).
+ - Off Linux, the parts of tests whose refusing path is Linux's
+ /proc/1 are skipped, and so is the builtins JSON check, since the
+ committed lists are Linux builds' (Tty9p included).
+ - test/daemon.py passes there at 20 cycles. One earlier run failed at
+ cycle 3, one process short in its count (most likely ps -e failing to
+ read an environment).
+ - test/fs.py runs as far as its `pardes -` +Pager checks. Those expect
+ one +Pager reused, which has not been true on Linux either since
+ 2026-10-22 (a new one each run).
+- **At 207 ms, for the replicas.**
+ - In today's model every key is a round trip. Measured through `ssh
+ -tt` (min, median and max):
+ - a key typed into a file was on screen in 213, 229 and 346 ms;
+ - a key typed into a shell pane in 218, 219 and 224 ms.
+
+ That is one RTT and about 15 ms.
+ - 9P over `ssh -L` of the session's socket costs one RTT a message:
+ 670 ms to connect, 1035 ms for a file read (walk, open, read, read,
+ clunk), 830 ms for a ctl write. A replica cannot fetch its state
+ file by file.
+ - The daemon's socket is SOCK_SEQPACKET and carries fds, so `ssh -L`
+ cannot forward it (tried: EPROTOTYPE here, connect failed there), and
+ no fd would cross anyway. The replication connection has to be a
+ stream of its own, as the 9P socket is, which the daemon hands on
+ locally.
+ - A dropped connection is a hangup: the session detaches, and
+ `pardes --attach` takes it back, as after a Detach.
+ - sun_path is 104 bytes there, not 108.