kolu
Docs

The server half

A surface is a typed menu a server offers: cells, collections, procedures, streams. In the basics, the server and the browser share a machine. The server half is what happens when the server runs on another machine, on a socket your browser cannot reach.

Why the browser faces a local copy

The bridge does two things. It subscribes to everything the remote source serves and keeps a live local copy, the mirror. It then serves that copy onward to browsers, forwarding writes back up. The verb for the pair is reServeSurface: mirror it, then serve it again.

The browser always talks to the local copy, and only the pipe behind the copy changes. The same canvas works whether the source sits on this machine or across an ocean, because the browser faces nothing but a plain local server. Behind that server a pump keeps the copy current, so a pipe that drops and respawns reconciles the view without the browser re-wiring anything.

The parent implements the same surface the agent does. It is not proxying bytes. It re-serves a real local surface whose stores happen to be fed by a remote pump. The contract is identical on both hops, so a consumer written against the local copy is identical to one written against the agent. That is the link abstraction, one machine boundary further out.

Why values replay and byte streams break

A pump that replayed everything would lie. So a re-serve classifies every member of the contract once, as a value or a delta.

A value member is held open and replayed across a drop. The list of terminals and the connection preferences are still true while the pipe is down, so replaying them is honest. A delta member is a live byte stream, such as a terminal’s screen. It fails through: the drop ends the downstream stream, the client re-subscribes, and a snapshot only ever leads a fresh stream. Replaying stale bytes would paint a dead screen as a live one.

Holding a value open replays what the source said. It never supplies what the source has not said yet. A mirrored cell serves no frame until the first real fold from the authority, even though its store seeds the declared default. That default belongs to the one writer, so a mirror relays the truth or stays silent. This is reactive honesty’s rule that an empty must not lie, carried across a machine boundary.

Why absence gets a frame of its own

A hold-open relay rides out a drop by saying nothing. That is right for a link that is coming back, and wrong for one that was never there or has been stopped. The subscriber keeps painting its last live frame, and a reader cannot tell a still board from a dead one.

So a re-serve may name, per value member, the frame a subscriber gets while the upstream is absent. The frame is a value the source contract declares, never one the relay invents, because the shape of “nothing to say” belongs to the contract exactly as a cell’s default does. Naming a member that could not carry such a frame fails the build, since a frame nobody could ever receive is worse than no frame at all.

Only a session that can tell absence from unreachability ever sends one. The options are in the mirror pump.

Why a refusal stops the relay

A daemon that answers, and speaks a contract this build cannot read, is the opposite fact from absence. It is an install to go and look at, not a quiet machine. A frame is how a member says “nothing is there”, and there is no honest frame for “something is there that I cannot read”.

So a hold-open relay that sees a standing refusal stops holding and fails its subscription, carrying the far end’s own sentence. The failure is raised as a defect. A streaming member declares no error channel, so a typed failure there would reach the subscriber as a complaint about the encoding rather than as the far end’s words. A defect is also never retried, which is right here: no retry unmakes a version skew.

Why demand is counted in one place

Every downstream call enters through the re-serve’s own handlers, so that is where demand is counted. One gate covers cells, collections, streams, events and procedures alike, and there is no per-member-kind count that could disagree with itself.

An upstream nobody subscribes to is therefore never dialled. That is what makes an optional upstream cheap: a daemon most machines do not run costs nothing until somebody looks at it. A parent that wants a link up regardless pins the session itself.

Why the session owns the pipe

The pump does not own the connection. A session does. A session is a durable, supervised relationship the parent keeps to one remote. It holds the link open across reconnects, watches health, and hands the pump a fresh client each time the agent respawns. The pump loops over those clients, and the session decides when there is a new one.

The split is deliberate. The session is the transport-agnostic part: reconnect, backoff, give-up and the liveness watchdog. The pump is the surface-shaped part, folding these frames into those stores. Swap ssh for a unix socket and the pump does not notice.

Why a dial waits for the peer to greet

A dial does not attach a typed link to a pipe it has not heard from. It reads the peer’s readiness banner off the very stream it is about to use, and the link takes that proof as a required argument, so a blind attach does not compile.

Without the gate, a peer from an earlier protocol epoch accepts the pipe and then says nothing. The link dies at its keep-alive backstop, and a consumer that reconnects on that retries a peer which will never speak.

Why the session sorts silence into kinds

A remote that says nothing can be several different things, and confusing them misleads you in a different way each time.

  • A transport gap means the host went away. It retries at a capped backoff and resets the bounded run of host-side failures, because the next remote failure is fresh evidence of a sleeping host rather than more of a standing fault.
  • An endpoint that is not there is a steady state, not a failure, and records nothing in the give-up ledger. An absence that aged into a terminal failure would make “that daemon was never installed here” indistinguishable from “that daemon is broken here”.
  • A probe shell that exits 127 means the host has no runnable Nix, and that verdict is read off the exit code. The shells word the message three different ways (bash, dash and fish), so matching the prose would only add ways to miss it.

One bound is deliberately not yours to set. The backstop that cycles a campaign gone quiet has to stay above the connector’s longest per-step budget, so the per-step budget always gives up first. Baking the figure in is what keeps that ordering true. Each verdict and its arms are listed under lifecycle invariants.

Why faults get a channel of their own

A mirror reports on two channels. One carries chatter, such as reconnects and link ends, which you can filter down to debug level. The other carries a structured fault and belongs at error level. A fault scoped to one key never reaches the mirror’s completion, so that channel is its only notice.

The split exists because the single-channel version hid a real freeze. kolu wired a projection layer’s only channel at debug level, and a deploy then froze without saying so anywhere an operator was reading (kolu#2101).

The far end is a plain server

Nothing about the mirror requires the far end to be exotic. The ssh mirror fronts a plain surface server: the agent runs implementSurface and serves over stdio, exactly as a local process would. Each host in drishti, a browser fronting an ssh fleet with one session per host, is an ordinary agent, and that fleet is the multi-host exemplar. The session and the pump are what make it remote; the agent is oblivious.

Where it costs you

The mirror buys indifference to where the source runs, and pays for it in latency and a copy. Every value lives twice, once on the source and once in the parent’s stores, and every write takes two hops.

For a value that changes slowly, the copy is cheap. For a byte stream, the fail-through rule makes a reconnect a visible reattach rather than a seamless resume. You give up the look of one continuous connection, and in return the browser can never be shown a stale screen dressed as a live one.