szn

Client-Server IPC Protocol

szn’s client and server talk over a UNIX-domain socket using a simple length-prefixed packet protocol (defined in src/server/protocol.zig). This replaces tmux’s imsg.

Referencing convention: this document names symbols and files, not line numbers. Line citations rot on every edit — an earlier revision carried 21 of them and all but two had drifted. Grep for the symbol name instead.

Note: the structs are not packed in the Zig sense — Header/Packet are plain structs with byte-exact manual encoding, to guarantee layout stability. MessageType is enum(u8).

Packet header (5 bytes)

Offset Field Type Encoding
0..4 length u32 little-endian, total size incl. header
4 msg_type u8 raw MessageType value

length total = 5 + data.len. Header.encode writes LE u32 then the type byte. Packet.deserialize requires buf.len >= 5 and buf.len >= len, so it parses the first packet in the buffer (extra trailing data is ignored); streaming framing is done by the readers in §4.

Packet.make keeps the header and body consistent by truncating the body to maxInt(u32) - 5 rather than clamping only the declared length (#389).

Direction convention

A single MessageType enum. isRequest() is @intFromEnum(self) < 0x80: < 0x80 = client→server, >= 0x80 = server→client. fromByte() maps a wire byte to a variant and returns null for anything unassigned, so unknown message types are rejected rather than coerced.

Message types

Client → Server (requests)

Value Variant Payload Status
0x01 identify_term opaque term string (live client sends raw "xterm-256color") used; payload ignored by server
0x04 command raw command-line string (e.g. "new-session test") used
0x05 resize 8 bytes: u32 LE width, then u32 LE height used
0x06 detach empty used (both directions)
0x08 stdin_data raw bytes from client stdin (max 4096/packet) used
0x09 cell_size 8 bytes: u32 LE cell_height_px, then u32 LE cell_width_px used
0x0A redraw empty used — reset this client’s diff state

The 0x02/0x03/0x07 slots (identify_cwd, identify_done, shell) were retired and are no longer part of the enum; fromByte() returns null for them.

Server → Client (responses)

Value Variant Payload Status
0x80 ready usually "ok", or captured response_buf text used
0x81 output raw terminal escape bytes (rendered frame; also OSC-52 clipboard) used
0x82 exit 1 byte exit code (u8) used
0x83 err error message string used
0x84 request_cell_size empty used
0x85 client_log path for the client’s log (empty = logging disabled) used

Key message behaviour

Framing (stream → packets)

Both streaming readers agree on the 5-byte LE-length header:

Size limits are unified using:

validPacketLength() (#375) validates a wire-declared length before the reader waits for the body, so a corrupted or hostile length can never pin the reader’s buffer forever.

Handshake / attach flow

  1. Client connects via connectToServer (src/client/connect.zig).
  2. Client sends identify_term then resize (w, h).
  3. Client enters raw mode + alt screen, installs SIGWINCH.
  4. Event loop: stdin → stdin_data; server → output written to stdout, detach ends the loop.
  5. Server on identify_term: appends fd to display_clients, replies ready("ok"), marks active pane dirty.

There is no per-session attach selection in the wire protocol — the daemon always serves its single active session. No initial-state dump either; the server simply begins streaming output once a client is a display client.

Cell-size discovery is on-demand, not at startup. A CSI 14 t query fired during alacritty -e szn startup returns wrong dimensions, so szn never queries at boot. Instead, when the first sixel is added the server sends request_cell_size; the client queries and replies cell_size (0x09), which the server applies to every screen. Until that reply lands, a sixel is buffered (Screen.pending_sixel) and the pane’s PTY feed is paused so the shell prompt can’t race the measurement.

Socket path / addressing

resolve() in src/socket_path.zig tries, in order: $XDG_RUNTIME_DIR/szn.sock → $TMPDIR/szn.sock → $HOME/.szn/szn.sock (mkdir 0700 first) → /tmp/szn-<uid>.sock.

src/server/socket.zig creates the AF_UNIX/SOCK_STREAM listener (createListener, listen(128), cloexec), accepts, and shuts down. It probes with connect() before unlinking a stale socket so a live server’s endpoint is never stolen, and forces 0700 on the socket path (#378).

Because the default path is global, tests that bind it must not run concurrently — see the socket-tests note in Build, Run, and Test.