Phase 3 cutover: single listener, datastore type-swap, Keycloak removal, deliberate breaks live

[SyniRon]

Parent

Part of #112 (PRD: Goodbye gRPC) — Phase 3 (Rewrite). The cutover deploy — the one that swaps stacks.

What to build

Cut the public surface over to the new stack, in one revertible deploy:

• Single public listener serves every route through the new chain (sentry → metrics → auth → gzip → mux). The second port stops listening. Docs UI + spec keep serving at unchanged URLs, with the version templated from the build-time variable (this replaces the CI proto-sed step).
• The datastore type-swap rides this change (the PRD's deliberate answer to the dual-stack trap): the Datastore interface and its implementations move from generated proto types to the types package — import surgery plus enum constants and slice allocation. Whatever old-stack serving code the swap breaks is unwired/removed here; the full toolchain sweep stays in Phase 4.
• Keycloak surface removed: route → standard JSON 404, fields gone from both profile shapes, the datastore lookup method deleted. This delivers what Remove MilpacService.GetUserViaKeycloakId (Phase 2 of 2) #100 scoped — close it as superseded by this change.
• Vestigial-join cleanup rides the swap: the roster queries LEFT JOIN xf_user_connected_account purely vestigially (measured: 1,397 rows scanned for 845 profiles; gorm dedups in Go); the join only matters for the discord/keycloak WHERE variants. Behavior-preserving removal — the roster goldens prove it.
• The deliberate breaks go live (the PRD's complete enumerated list — same list the consumer heads-up carries).
• The datastore behavior tests get their mechanical type update.

After the deploy: close #94 (gateway dial deprecations — superseded; the dial leaves the serving path) and close #100 (delivered here).

Workflow: /tdd — the full golden corpus is the red suite; this issue is done when it's green against the deployed configuration.

Acceptance criteria

• Full golden suite green against the new stack; two-way spec coverage green
• Past Members roster streams clean — 4,776 profiles / 30.4MB JSON, ~75% of the old 20MB internal gRPC ceiling; the ceiling is gone by design (mirror-measured 1.56s indexed)
• Single listener; second port not listening; docs/spec URLs unchanged, version templated
• 405 + Allow on wrong method; JSON 404 on unknown API paths; 400 on invalid query enums
• Grpc-Metadata-*, X-HTTP-Method-Override, form-POST-to-GET, legacy unescaping: gone
• Keycloak: route 404s, fields absent, datastore method deleted
• Vestigial connected-account join removed; roster goldens still green
• Consumer heads-up (Phase 3: consumer heads-up before cutover with the deliberate-breaks list #133) sent and the feedback window closed before deploy
• Replace deprecated grpc.DialContext / WithBlock / WithInsecure in the gateway #94 and Remove MilpacService.GetUserViaKeycloakId (Phase 2 of 2) #100 closed after deploy

Live spot-check notes: temporary API key recipe — xf_cav7_api_key row with key_hash = UNHEX(SHA2('<plaintext>',256)), unique user_id, is_active=1, plus xf_cav7_api_key_scope rows for both scopes; delete after use. Local mirror at ~/srv/xenforo-mirror (DB env per that compose file — credentials stay out of issues; no Redis needed once Phase 2 has landed).

Blocked by

• Phase 2: delete the cache package, table-update poller, and Redis (post-soak) #124 — Phase 2 deployed and soaked (deploy gate)
• Phase 3: profile lookup routes - id, username, discord, gamertag #126, Phase 3: roster routes in all three profile shapes (Roster, LiteRoster, S1Uniforms) #127, Phase 3: position groups, position search, and AWOL routes #128, Phase 3: tickets routes - list, by id, by ref, messages, categories #129 — all route groups green
• Phase 3: Prometheus metrics on an internal-only listener #130, Phase 3: Cache-Control headers on read endpoints #131, Phase 3: full Sentry wiring in the new stack #132 — the chain is complete (metrics, Cache-Control, Sentry)
• Phase 3: consumer heads-up before cutover with the deliberate-breaks list #133 — consumer heads-up
• Phase 3: datastore behavior tests on the MariaDB harness (retire the sqlmock pattern) #120 — the SQL-seam tests exist to ride the type swap
• Question: does any consumer generate client code from the served swagger.json? #117 — codegen answer (decides whether a frozen Swagger 2.0 alias ships alongside the 3.1 spec)

[SyniRon]

#132 hand-off obligation (from wave-2 review, recorded per maintainer ruling):

rest/sentry.go replaces servers/sentry.go's env-gate, recovery middleware, and choke-point 5xx reporting — but NOT its boot-lifecycle pieces. Before this slice deletes servers/sentry.go, port (or consciously drop with a documented reason):

• sentryDialCheck (servers/sentry.go:138-151) — boot-time DSN reachability warning
• sentryStartupProbe (servers/sentry.go:167-192) — canary event + flush at boot
• flushSentryOnShutdown (servers/sentry.go:202-231, wired at servers/server.go:123-124) — SIGTERM flush of the SDK's async ring buffer

Without these: a dead DSN/blocked egress becomes invisible at boot (no always-on signal), and shutdown-window events are silently dropped (the v0.46.2 transport buffers cap-100 DropOldest with no sync flush).

Also at cutover: replace the setupSentry() call with rest.SetupSentry(version) (release string is a parameter — rest/ cannot import servers/ without a cycle).