perf(web): use read replica for gateway balance checks

[chrarnoldus]

Summary

• pass the region-aware readDb into the OpenRouter gateway balance and organization settings lookup
• add route coverage that verifies the lookup receives readDb

Consequences

This moves a high-volume, read-only gateway query off the primary PostgreSQL instance. In US regions it avoids the cross-region read to the Frankfurt primary and should reduce balance-check latency; in EU regions it distributes reads across replicas, reducing primary connection and query load. If no replica is configured, readDb falls back to the primary, so behavior is unchanged.

The tradeoff is eventual consistency. Replica lag is normally slight (typically under 100 ms), but immediately after a write the gateway can briefly observe stale organization balances, per-user usage or limits, membership, settings, plan, seat requirements, auto-top-up state, or credit-expiration metadata. Depending on which value changed, a request may be briefly accepted or rejected using the prior state, or use the prior organization routing/data-collection policy. No writes are redirected: expiry processing, auto-top-up, usage accounting, and all other mutations continue to use the primary database.

Verification

• pnpm --filter web exec jest --runInBand --runTestsByPath 'src/app/api/openrouter/[...path]/route.test.ts' (21 tests)
• scripts/typecheck-all.sh --changes-only
• pnpm -w exec oxlint --config .oxlintrc.json 'apps/web/src/app/api/openrouter/[...path]/route.ts' 'apps/web/src/app/api/openrouter/[...path]/route.test.ts'
• pnpm -w exec oxfmt --write 'apps/web/src/app/api/openrouter/[...path]/route.ts' 'apps/web/src/app/api/openrouter/[...path]/route.test.ts'
• git diff --check

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Executive Summary

The change routes only the read-only getBalanceAndOrgSettings lookup through readDb (an existing, already-supported fromDb parameter used identically by api/fim/completions, api/edit/completions, and api/exa/[...path]), with no writes redirected; high confidence.

Notes (no action required)

• getBalanceForOrganizationUser still performs its lazy credit-expiration write via processOrganizationExpirations and schedules maybePerformOrganizationAutoTopUp from replica-read values. Both are guarded on the primary (optimistic concurrency check on total_microdollars_acquired/next_credit_expiration_at, and a lock plus fresh primary balance re-check before charging), so replica lag degrades to a no-op rather than a duplicate charge. This is the same tradeoff already accepted by the other readDb callers of this function.
• The new test mock jest.mock('@/lib/drizzle', () => ({ readDb: {} })) matches the existing pattern in apps/web/src/app/api/openrouter/models/route.test.ts.
• No new per-request listeners, pools, or unbounded caches are introduced, so no memory-leak risk from this diff.

Files Reviewed (2 files)

• apps/web/src/app/api/openrouter/[...path]/route.ts
• apps/web/src/app/api/openrouter/[...path]/route.test.ts

---

_{Reviewed by claude-opus-5 · Input: 42 · Output: 9.1K · Cached: 1.1M}

_{Review guidance: REVIEW.md from base branch main}