Failure modes & recovery

A stream read/write error on the edge (the session RSTs).

Requests in flight get an immediate 502error page; the session's Done() fires and ReleaseSession compare-and-deletes its hostnames, so subsequent requests get a cheap 404. There is no replay — the edge can't know whether the request was idempotent. A restarted agent gets a new InstanceID, so it reclaims its name via the dead-holder takeover rule rather than the same-identity one.

The agent's control-stream reads or keepalive start erroring.

All state is rebuilt from the client side: the agent backoff-reconnects, re-authenticates, and re-binds with Takeover: true, restoring the same public URL — typically under two seconds downtime with Restart=always. Certificates load from the state directory cache, provided the systemd unit is configured correctly.

yamux keepalive failure or three missed application pings — about 45 s either way.

The edge eventually frees the binding, returning 404s. The agent doesn't wait for that: its unchanged InstanceID matches the zombie binding on reconnect, so takeover rule (a) rebinds immediately even while the old session still looks alive to the edge. The zombie session is sent Evicted and force-closed.

ResponseHeaderTimeout at 30 s.

The public client gets a 504; the tunnel session itself is unaffected. Slowness after headers have started is legal — that's just streaming — and is bounded only by client patience and flow control, not by a server-side timer.

A Content-Length pre-check for declared-length bodies, MaxBytesReader plus a custom ErrorHandler for chunked ones.

A declared-length body over the 256 MiB cap gets a real 413 before anything crosses the tunnel. A chunked body over the cap is synthesized into a 413 from *http.MaxBytesError — with the caveat that the agent may already have forwarded a partial body to the local app by the time that fires.

The startup check on :4443 plus /healthz reporting each certificate's NotAfter separately.

If the apex order fails, public traffic keeps working fine on the wildcard cert — but no agent can connect, since the control plane depends on the apex cert. ngstoned refuses to accept on :4443 without a loadable apex cert and exits loudly rather than failing mysteriously later.