feat(gateway): tier-detector with fail-fast PG/Valkey/pgvector probes (FED-M1-04) #473

jason.woltje · 2026-04-20T00:03:41Z

jason.woltje commented

2026-04-20 00:03:41 +00:00

Summary

FED-M1-04 — Implements apps/gateway/src/bootstrap/tier-detector.ts, invoked from main.ts before NestJS bootstraps. For each storage tier:

local: no-op (PGlite is in-process)
standalone: probes Postgres + Valkey
federated: probes Postgres + Valkey + pgvector extension; rejects config upfront if queue.type !== 'bullmq'

Each probe enforces a 5-second hard cap and emits a structured TierDetectionError carrying service, host, port, and an actionable remediation. The pgvector probe discriminates between two failure modes:

Library not installed (extension "vector" is not available) → remediation points to pgvector/pgvector:pg17 image
Permission/other → remediation mentions CREATE permission / superuser

Adds postgres and ioredis as direct gateway dependencies (previously transitive only).

Process notes

Independent code review (sonnet) flagged 3 issues on the first delivery: missing Valkey connectTimeout, no error discrimination in pgvector catch, and federated tier silently skipping Valkey if queue.type !== 'bullmq'. All three fixed in this PR.
Independent verification (haiku) confirmed all fixes in place by line number, plus full test suite green.

Tests

12 unit tests in tier-detector.spec.ts:

8 baseline tests (local no-op, standalone happy/PG-fail/Valkey-fail, federated happy/pgvector-fail, error fields)
4 new tests covering the review-fix issues (Valkey timeout, pgvector library-missing remediation, pgvector permission remediation, federated rejects non-bullmq queue before any probe)

Test Files  1 passed (1)
Tests       12 passed (12)

Test plan

Manual smoke test on a federated stack once FED-M1-07 (integration test with real services) lands
CI green
No regression in existing standalone tier paths (covered by FED-M1-09)

Refs #460

## Summary FED-M1-04 — Implements `apps/gateway/src/bootstrap/tier-detector.ts`, invoked from `main.ts` before NestJS bootstraps. For each storage tier: - **`local`**: no-op (PGlite is in-process) - **`standalone`**: probes Postgres + Valkey - **`federated`**: probes Postgres + Valkey + pgvector extension; rejects config upfront if `queue.type !== 'bullmq'` Each probe enforces a 5-second hard cap and emits a structured `TierDetectionError` carrying `service`, `host`, `port`, and an actionable `remediation`. The pgvector probe discriminates between two failure modes: - **Library not installed** (`extension "vector" is not available`) → remediation points to `pgvector/pgvector:pg17` image - **Permission/other** → remediation mentions `CREATE` permission / superuser Adds `postgres` and `ioredis` as direct gateway dependencies (previously transitive only). ## Process notes - Independent code review (sonnet) flagged 3 issues on the first delivery: missing Valkey `connectTimeout`, no error discrimination in pgvector catch, and federated tier silently skipping Valkey if `queue.type !== 'bullmq'`. All three fixed in this PR. - Independent verification (haiku) confirmed all fixes in place by line number, plus full test suite green. ## Tests 12 unit tests in `tier-detector.spec.ts`: - 8 baseline tests (local no-op, standalone happy/PG-fail/Valkey-fail, federated happy/pgvector-fail, error fields) - 4 new tests covering the review-fix issues (Valkey timeout, pgvector library-missing remediation, pgvector permission remediation, federated rejects non-bullmq queue before any probe) ``` Test Files 1 passed (1) Tests 12 passed (12) ``` ## Test plan - [ ] Manual smoke test on a federated stack once FED-M1-07 (integration test with real services) lands - [ ] CI green - [ ] No regression in existing standalone tier paths (covered by FED-M1-09) Refs #460

jason.woltje added 2 commits 2026-04-20 00:03:42 +00:00

feat(gateway): tier-detector with fail-fast PG/Valkey/pgvector probes (FED-M1-04) 7383380f64

Implements `apps/gateway/src/bootstrap/tier-detector.ts` invoked from
`main.ts` before NestJS bootstraps. For each tier:

- `local`: no-op (PGlite is in-process)
- `standalone`: probe Postgres + Valkey
- `federated`: probe Postgres + Valkey + pgvector extension; reject
  config upfront if `queue.type !== 'bullmq'`

Each probe has a 5-second hard cap and emits a structured
`TierDetectionError` with service / host / port / remediation. The
remediation field discriminates pgvector failure modes ("library not
available" vs "permission denied") so operators get actionable hints
without leaking credentials.

Adds `postgres` and `ioredis` as direct gateway deps; previously only
transitive. 12 unit tests cover happy paths and each fail-fast branch.

Refs #460

docs(federation): mark FED-M1-02 done (PR #471 merged)

ci/woodpecker/push/ci Pipeline was successful

Details

ci/woodpecker/pr/ci Pipeline was successful

Details

f74fc9687f

jason.woltje merged commit 4c2b177eab into main

2026-04-20 00:07:08 +00:00

jason.woltje referenced this issue from a commit

2026-04-20 00:07:09 +00:00

feat(gateway): tier-detector with fail-fast PG/Valkey/pgvector probes (FED-M1-04) (#473)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: mosaicstack/stack#473