writeonce/docs/stories/language-runtime-database/refine/35-net-runtime-seams.md

iteration	status
35	refine

Iteration 35 — net runtime seams: timeouts, Unix sockets, peer address

Format: product/story-iteration-template. Part of Story — one language, one runtime, one database, one binary.

Inserted 2026-08-22 — the framework ledger's three 🔧 rows get one owner: "Read/write/idle timeouts — net has no timeout surface", "Unix socket binding — net.listen is TCP-only", and "Trusted-proxy client IP — needs a peer-address runtime seam". Each is a small builtin-surface addition; the framework knobs built ON them stay framework slices. Off the concurrency chain; no chain item depends on it, but a production-shaped deployment (proxy in front, sockets not ports, slow-client defense) needs all three.

Why this iteration exists

The framework cannot defend against a slow client (no read deadline — one stalled socket parks a fiber forever), cannot sit behind a same-host proxy the idiomatic way (Unix socket beats a loopback port), and cannot TRUST X-Forwarded-For (parsing is expressible in .wo today, but verifying the peer actually IS the proxy needs the peer's address, which no builtin exposes). All three are runtime seams by nature: the information or mechanism lives at the fd level.

Goals

• Deadlines on parked net I/O. A read/accept/write that would park can carry a deadline; expiry resumes the fiber with a distinguishable timeout result (nil-or-trap decided by the spec, consistent with the stdlib's nil-vs-trap contracts). On serving shards this composes with the existing plane — a park is ALREADY a POLL_ADD or TIMEOUT submission (arc T4); the seam arms both and takes whichever fires. Program mode gets the same surface over blocking syscalls.
• Unix-domain listeners and connections beside the TCP ones — same accept/read/write/close builtins afterward (an fd is an fd; only the bind/connect shape differs).
• The peer's address, readable — for an accepted connection, enough to answer "is this my trusted proxy?" (address + family; port where meaningful). The framework's trusted-proxy middleware then becomes a pure-.wo candidate slice.
• The framework knobs are explicitly NOT here — timeout defaults, proxy allowlists, socket-path config all live in framework slices that consume these seams.

Acceptance Criteria (draft — the spec refines)

• Given a fiber reading a socket whose peer sends nothing, when the declared deadline expires, then the fiber resumes with the timeout result (never a hang), other fibers having run throughout (TID-verified), and the fd is still usable or cleanly closed per the spec's stated semantics.
• Given a listener on a Unix socket path, when a client connects and exchanges bytes, then the whole existing net surface works unchanged over it, and the log-watcher/web-app gates stay byte-identical on TCP.
• Given an accepted connection, when the handler asks for the peer address, then loopback TCP and Unix-socket peers are both identifiable, and the answer round-trips into the trusted-proxy check's comparison.
• Given the full battery plus a soak with deliberately stalled clients, when it runs, then zero leaked fds and flat RSS — timeouts must CLEAN UP, not merely return.

Out Of Scope

• Framework policy (default timeout values, proxy allowlist shape, keep-alive idle policy) — framework slices on top.
• TLS, h2c — unchanged owners (proxy; parked behind 23).
• Connect-side timeouts for outbound clients beyond what the deadline seam gives free — no workload asks yet.
• Cancellation as a general mechanism — iteration 31's request/response + timers own actor-level cancellation; this is strictly fd-level deadlines.

Info

Forks the spec must settle:

1. Timeout result shape: nil result vs a distinguishable trap — must follow the stdlib's existing nil-vs-trap doctrine (07-series contracts; a timeout is an EXPECTED outcome, which argues nil).
2. Deadline plumbing on the plane: one park may need BOTH a POLL_ADD and a TIMEOUT in flight (io_uring linked ops vs two submissions + first-wins cancel; epoll fallback = the existing deadline scan). The park protocol contract (03-concurrency-coroutines.md) gains the rule.
3. Surface shape: per-call deadline argument vs per-fd setting (net.set_deadline(fd, ms)); leaning per-call — no hidden fd state, matches the no-coloring doctrine.
4. Unix-socket path semantics: unlink-before-bind? stale-socket handling on restart (the never-stopping-runtime doctrine says a restart must not need manual cleanup).

Proposed Solution

Brainstorm → small spec settling the four forks → implement in the time.ticks/34 shape (builtin ids + park.c deadline arming + contract rows + fixtures incl. a stalled-client corpus case). Independent of the chain; natural pairing is right before or with iteration 24 (chat wants read deadlines for dead-client eviction even before lifecycle timers).