relay: startup self-check refuses to run as multi-instance deploy

[ilmoniemi]

User Story

As an operator who accidentally runs fly scale count 3 (or any equivalent on another host), I want the relay to refuse to start on any replica past the first with a loud, specific error, so that silent server-id routing breakage is caught before phones connect.

Context

The connection registry (internal/relay/registry.go) is in-memory per process. Two replicas serve disjoint registries: a phone connected to replica A cannot reach a binary connected to replica B. Docker + Fly.io makes fly scale count 3 a one-line command. Without a runtime guard, an operator or AI agent could scale out and silently break server-id routing for half the connections.

This ticket is the deterministic backstop in the belt-and-suspenders pair noted in docs/PROJECT-MEMORY.md — the doc half (sibling #64, already merged) handles the stochastic guard.

Acceptance Criteria

• At process startup, the relay performs a self-check intended to detect that it is part of a multi-instance deploy.
• On positive detection, the process refuses to start (non-zero exit) and emits an ERROR-level log whose message contains the substring multi-instance deploy detected and names the bypass env var PYRYCODE_RELAY_SINGLE_INSTANCE so an operator can grep for it.
• Setting PYRYCODE_RELAY_SINGLE_INSTANCE=1 causes the self-check to be skipped, and startup proceeds. Bypass is intended for emergencies and migration windows.
• When no multi-instance signal is present (the common single-instance case), startup proceeds unchanged. Existing single-instance deployments must not regress.
• Tests cover at minimum: (a) multi-instance signal present → refuses to start with the documented error substring; (b) PYRYCODE_RELAY_SINGLE_INSTANCE=1 → starts; (c) no multi-instance signal → starts.

Technical Notes

• The bypass env var name PYRYCODE_RELAY_SINGLE_INSTANCE is fixed — sibling relay: document v1 single-instance constraint in architecture.md #64 has merged and committed that literal name (and the value 1) into docs/architecture.md. Do not rename; if a rename is genuinely needed, raise it as a fresh ticket against docs/architecture.md first.
• The parent body (relay: single-instance constraint — doc + startup self-check (registry is in-memory) #39) sketched two candidate detection mechanisms: (1) an env-var contract PYRYCODE_RELAY_ASSERT_SINGLE_INSTANCE=true set by the deploy manifest, refuse-to-start when absent; (2) host-exposed signals like FLY_MACHINE_ID combined with a count assertion. Mechanism (1) would regress existing deployments that don't set the assertion (violates AC relay: WS upgrade for /v1/server — accept binary connection, validate headers, claim server-id #4), and the repo has no fly.toml or other host manifest under our control today (the deploy artifact is Dockerfile only) — so mechanism (2), or any equivalent local-only host-env signal, is the natural choice. Architect confirms.
• No new runtime dependency on platform-specific SDKs/API clients (e.g. no Fly machines API client). The detection mechanism must be either an env-var contract or a local-only signal (env vars exposed by the host).
• The check belongs in the cmd/pyrycode-relay/main.go startup path or a small helper in internal/relay/. Architect's call.

Out of scope

• Implementing shared-registry support (Redis / NATS / sticky-session).
• Health-check integration with platform autoscalers.

Size Estimate

XS

Split from #39.

[ilmoniemi]

🤖 Product Owner — creates structured issues

po agent has completed work on this ticket.

Agent output (click to expand)

Done. Refined issue #65 with three changes:

1. **AC #2 & #3 tightened** — bypass env var is now stated as the literal `PYRYCODE_RELAY_SINGLE_INSTANCE` (with value `1`), not "architect's choice; suggested". Sibling #64 has merged and committed that name into `docs/architecture.md`, so the choice is no longer open.
2. **AC #6 dropped from criteria, folded into Technical Notes** — "no platform SDKs" is a design constraint, not a behavior to test.
3. **Technical Notes expanded** — calls out that mechanism (1) from #39's body would violate AC #4 (no `fly.toml` in repo → existing deploys lack the assertion → would regress), pointing the architect toward mechanism (2) without forbidding equivalents.

Labels (`size:xs`, `security-sensitive`) remain correct. Dispatcher will add `ready:po` and advance to In Architecture.

Ready for human review. Move to the next column when approved.

[ilmoniemi]

Blocked by #30: overlapping changes to cmd/pyrycode-relay/main.go.

The startup self-check for this ticket lands in cmd/pyrycode-relay/main.go (most natural site for the env-var probe + os.Exit(2) on positive detection; the existing --domain / --insecure-listen validation already sits inline in main() and is the pattern this check mirrors). #30 (PR #43, open against feature/30) modifies the same file — the ClientHandler signature change at line 51 is the only diff line today, but the branch-overlap check is file-level, not region-level, and per the WIP=N policy I do not write the spec while a sibling branch is in flight against the same file.

Will write the spec once #30 lands. When PR #43 merges, the blockedBy flips to CLOSED and the ticket auto-advances out of Backlog; my next run will start fresh from the merged main.

No design content lost — the design is straightforward (single-helper + main.go wiring), the architecture doc (#64) has already pinned the bypass env-var name and value, and the AC list is unambiguous.