feat(ipc): .ipc.on.* connection hooks

[singaraiona]

Replaces v1's two-letter port hooks with five descriptive hooks under .ipc.on.* plus a read-only .ipc.handle:

Name	Signature	Fires
.ipc.on.open	(fn [h] ...)	Inbound connection fully handshaked (and authed if -u/-U), before first header read.
.ipc.on.close	(fn [h] ...)	Inbound connection about to close, before fd/state teardown. Pairs 1-to-1 with on.open.
.ipc.on.sync	(fn [m] ...)	Sync request; return value becomes the response.
.ipc.on.async	(fn [m] ...)	Async message; return ignored, errors logged.
.ipc.on.auth	(fn [u p] ...)	After secret-compare passes in -u/-U auth. Truthy = accept, falsy = reject. Can only narrow.
.ipc.handle	(.ipc.handle)	Current handle inside any hook, -1 outside.

Install

Plain set / :, through a narrow allow-list carved out of ray_sym_is_reserved:

(set .ipc.on.open  (fn [h] (println "+ " h)))
(set .ipc.on.sync  (fn [m] (eval (parse m))))
(set .ipc.on.auth  (fn [u p] (!= u "ban")))

Only these five sym IDs are user-settable. Everything else under .ipc.* (open, close, send, handle) and every other dotted system namespace stays unsettable. Clearing a hook is (set .ipc.on.X 0) — anything that isn't a callable lambda is treated as "no hook installed".

Wiring

src/core/ipc.c covers both server paths:

• Poll: ipc_read_handshake (no-auth ready), ipc_read_creds (post-auth ready + on.auth narrow), ipc_on_close, ipc_read_payload (sync/async dispatch + handle scope).
• Legacy: conn_on_handshake, conn_on_creds, conn_close, conn_on_payload.

Lifecycle on.close fires only for connections that completed handshake, keeping the on.open / on.close pair balanced for the user. Hooks inherit the connection's restricted-mode flag — a .ipc.on.sync installed on a -U server cannot escalate.

Sym-cache lifetime

Hook sym IDs live in one place (g_ipc_hook_syms[] in env.c, accessed via ray_sym_ipc_hook(idx)) so a runtime destroy/recreate cycle (which tears the sym table down too) invalidates the cache exactly once. The IPC layer doesn't carry its own duplicate cache.

Deliberately not pre-interned in ray_env_init — single-char operator names need the low sym-ID slots so the resolve builtin's "slen<2 / operator-char" guard rejects them on small-int columns. Stealing IDs 1-5 for long dotted names silently promoted [1 2 3] columns to SYM (caught by print_resolve.rfl).

Per-hook error handling

Hook	Lambda error
on.open / on.close	Logged to stderr, swallowed.
on.sync	Serialised and shipped as the response (same as raw eval error).
on.async	Logged and dropped — no wire response on async anyway.
on.auth	Treated as reject; same 0x01 byte the wrong-password path uses.

Tests

• ipc/hooks_lifecycle — end-to-end open → sync → close round-trip on the legacy path; reads per-hook counters and .ipc.handle back through the global env.
• ipc/hooks_auth_narrow — poll-path -u server with an .ipc.on.auth that rejects one username; proves the hook can selectively narrow rather than blanket-reject.
• rfl/system/reserved_namespace — positive set/let cases for the five hook names + negatives ensuring the rest of .ipc.* and the new .ipc.handle stay reserved.

make test: 2847 of 2850 passed, 3 skipped, 0 failed (3 skipped pre-existed).

Docs

New "Connection Hooks" section in website/docs/ipc.html plus rows in website/docs/reference.html.

🤖 Generated with Claude Code