Module ipc 

Local IPC channel between the running tray app and entracte CLI invocations.

Transport

• Unix (macOS + Linux): AF_UNIX socket. The preferred location is <data_dir>/ipc.sock, but sockaddr_un.sun_path is fixed at 104 bytes on macOS/BSD (108 on Linux, NUL included). Accounts with long usernames can push the full path past that limit and bind/connect fails with ENAMETOOLONG. When the data-dir path would exceed MAX_SOCKET_PATH_LEN we fall back to $TMPDIR/entracte-<uid>.sock (typically /var/folders/... on macOS, /tmp/... on Linux), which stays well under any limit. The chosen path is deterministic from data_dir so the CLI and the tray agree without an extra discovery file. The socket file is chmodded to 0o600 immediately after bind so other local UIDs cannot connect().
• Windows: named pipe at \\.\pipe\entracte-<sanitized-user>. The pipe is created with the default DACL, which grants access to the current user’s SID only. Pipe names cap at ~256 chars and the per-user scheme stays well under that — no fallback needed.

Both transports are user-scoped by the OS, so the threat model is “another process running as the same user”, not “any local UID with the token”. The token file (<data_dir>/ipc-token) stays in the data dir regardless of which socket path is chosen — only the socket may move. It is kept as a defense-in-depth secondary check — every request must still carry it and we still constant-time compare — but it’s no longer the sole line of defense.

Wire protocol

Newline-delimited JSON. Client sends one IpcEnvelope line, server replies with one IpcResponse line and closes the connection. Reads are bounded by MAX_REQUEST_BYTES so a hostile peer can’t OOM the server with an unbounded frame.

Modules

unix 🔒

Structs

IpcEnvelope

IpcResponse

Enums

IpcRequest

Constants

MAX_REQUEST_BYTES

Hard ceiling on a single IPC request frame. Anything larger is dropped — a CLI request is never bigger than a few hundred bytes, so 64 KiB is comfortably above the legitimate ceiling while still small enough to keep an attacker from exhausting memory.

MAX_SOCKET_PATH_LEN

Safe cushion below the smallest sun_path capacity we care about (104 bytes on macOS/BSD), leaving room for the trailing NUL and a couple of bytes of margin. If the preferred <data_dir>/ipc.sock path is longer than this we fall back to $TMPDIR.

SETTINGS_DENYLIST 🔒

Functions

call

dispatch 🔒

generate_token 🔒

ipc_data_dir

socket_path

start_server

status_payload 🔒

token_file_path

tokens_match 🔒