ADR-0005 · Failures are named by the network edge that broke

Status: Accepted, 2026-10-10.

Context

On the tailnet a reader can be off the network, GitLab can be down, or the reader can lack a session. A generic error leaves them unable to act.

Decision

The service answers 502 gitlab-unreachable when GitLab cannot be reached and reports GitLab reachability in /v1/health. The client classifies a failure as offline-network (the fetch rejected), offline-gitlab, unauthenticated or error, and every component shows the matching message while the build-time content stays. Error responses carry CORS headers for an allowed origin so the browser can read them.

Why

Each state tells the reader what they can do: join the tailnet, wait, or sign in. Without CORS on errors, every 502 looked like a network failure.

Consequences

The smoke script uses the same classification and exit codes per edge.

Evidence

6bd168e, f428e5c, 8cdd08a; test/reachability.test.js, test/e2e/reachability.spec.js.

Revisit when

A new edge appears (a proxy, a second backend), or readers need retry controls.