OCTOBER-REVIEW-REVISIONS unit 3: one socket module, one principal, and launch tracking #67

Sockets, principals and launches are tidied. The socket code is gathered into lichen-site/src/ipc/socket/ as a self-contained module (control channel frames, admin connection server, upgrade relay, the front's per-connection exchange, passed-connection listener). The front server works out a request's principal once and forwards it as one header, x-lichen-principal, believed only on connections passed on the control channel; the site's second mapping is removed and a request nothing resolved now fails closed as Visitor. A deleted-and-recreated site inherits nothing of the old process, and a stopped launch keeps telling until it is replaced (tracked by launch number).

---

OCTOBER-REVIEW-REVISIONS, unit 3 (subunits 3a, 3b, 3c combined, replacing their per-subunit PRs). Plan: https://tangled.org/notplants-bot.bsky.social/lichen-orchestrator/blob/main/machine-docs/plans/OCTOBER-REVIEW-REVISIONS-2026-10-28.md

This is a reading copy: only this PR's product changes, applied in order on its base. Nothing here is to be merged.

Source PRs on lichen.page.review (product), in order, with their original descriptions #

• #3400 s/768-orr-u3a-ipc-socket — ORR 3a: the socket code is self-contained in ipc/socket/ (AST-checked moves)

  OCTOBER-REVIEW-REVISIONS unit 3a, product: the socket code is self-contained in lichen-site/src/ipc/socket/ (A5). Moves only, AST-checked; renames are unit 7's.

  • Moved into ipc/socket/:
    • the control channel's frames with SCM_RIGHTS (site_process/control.rs, whole);
    • the admin thread's connection server (serve_admin, answer_refused);
    • relay_upgrade;
    • the front's per-connection exchange (exchange_on, UPGRADE_ERROR_DRAIN);
    • the main runtime's passed-connection listener (Passed and its two impls).
  • The front code moves into lichen-site, and lichen-server's forward_on calls it, since A5 allows no other file to use hyper's connection API.
  • Commits:
    • 606aa3898 and b10429de4 are AST-only moves.
    • a50890949, before the second move, is the one reshape. exchange_on turns from a method of lichen-server's SiteProcess into a free function, because the checker cannot move a method across crates. Passed's fields become named.
    • A docs commit and a rustfmt commit follow (whitespace and trailing commas).
  • Stays where it is: the non-HTTP pairs (the PTY request, the test-routes datagram probe, the test-only egress hand-over).

  AST move checks on lichen-ci (per-sha notify-fc50eca1, the checker built from the coordination repo's ast-checker/): 606aa3898 equal, moved 3, carried 22, errors 0; b10429de4 equal, moved 5, errors 0.

• #3402 s/770-orr-u3b-one-principal — ORR 3b: one principal, assigned once by the front server

  OCTOBER-REVIEW-REVISIONS unit 3b, product: one principal, assigned once, by the front server (A4).

  • The header: the front server works out the request's principal once, in its access check, and forwards it as one header: x-lichen-principal, JSON {principal, user, role}, with the host role inside it.
    • The site believes it only on connections passed on its control channel.
    • The site refuses a header that names a principal no request can be; only Owner, ShareGuest, FullToken, SafeToken and Visitor are taken.
  • Removed: the site's second mapping (forwarded_principal), the Forwarded marker and the token scope as a request extension. After entry, every check is permissions_of(principal).
  • Other readers:
    • the full-token push (hub_http) reads the principal;
    • a dashboard publish's "who" is set only for a token principal;
    • the safe-token refusal text comes from one function.
  • Departures from the plan's text, with reasons:
    • The signed-in name stays in the header for publish records and /cms/api/info. No check reads it.
    • A request nothing resolved is forwarded as Visitor, where it was Owner: it now fails closed.
    • The health check is sent as Visitor, since its route is public.

• #3404 s/772-orr-u3c-invariant — ORR 3c: a re-created site inherits nothing; a stopped launch tells until replaced

  OCTOBER-REVIEW-REVISIONS unit 3c, product: two fixes the invariant's tests found, and one from 3b's review.

  • A site deleted and re-created inherits nothing of the old process. delete_site now also forgets what the old process told the front (its auto-pull hint) and its exit and recycle back-off (SiteProcesses::forget).
  • A stopped launch still tells until it is replaced (lichen-adversary's item against 2c). stop() marked a launch retired before SIGTERM, so a publish that finished while the process drained, and its weight and sync tells, were dropped.
    • Each launch now carries its number and its site's latest launch number (LaunchNumber). told() acts while they match, so a launch that has stopped or exited still tells until a later launch starts or the site is deleted.
    • An old launch's frame still never reaches a recycled successor.
    • retired and is_current go.
  • A test-routes-only probe (probe::take_from) for the invariant's tests.

Commits #

• 0c8f86523 OCTOBER-REVIEW-REVISIONS unit 3: subunit 3a
• e34f40bd4 OCTOBER-REVIEW-REVISIONS unit 3: subunit 3b
• 279c62646 OCTOBER-REVIEW-REVISIONS unit 3: subunit 3c

Count and shas #

count-product-code-lines 828dafebcfb9..279c62646fe3: NET +132 · counted +667 -535 · moved out of the counted set +0 · comment-only deletions flagged 28 · macros flagged 0 · tests-folder code flagged 0

Base 828dafebcfb94ff3bcc6bed6b4ab78a14df44a50 (tip of s/767-orr-u2d-spindle-fixups-tests). Head 279c62646fe3e28954c66b1181a6c4834222dce4. 41 files changed.

Check #

Files that differ from s/772-orr-u3c-invariant (later tests PRs or merges touched them, or the diff was resolved): crates/lichen-server/src/tests/site_process__front.rs, crates/lichen-site/src/ipc/socket/control.rs, crates/lichen-site/src/ipc/socket/request.rs, crates/lichen-site/src/tests/site_process__control.rs, crates/lichen-site/src/tests/site_process__host.rs.

Files that a tests PR of this unit also changed (so a test-only edit could in principle sit in them): crates/lichen-server/src/tests/site_process__front.rs, crates/lichen-site/src/ipc/socket/control.rs, crates/lichen-site/src/ipc/socket/request.rs, crates/lichen-site/src/tests/site_process__host.rs.