Skip to content

feat(serve-http): GBRAIN_TRUST_PROXY env var + Supabase deploy docs#817

Open
knee5 wants to merge 1 commit into
garrytan:masterfrom
knee5:clevin/trust-proxy-env-var-2026-05-10
Open

feat(serve-http): GBRAIN_TRUST_PROXY env var + Supabase deploy docs#817
knee5 wants to merge 1 commit into
garrytan:masterfrom
knee5:clevin/trust-proxy-env-var-2026-05-10

Conversation

@knee5
Copy link
Copy Markdown
Contributor

@knee5 knee5 commented May 10, 2026

Summary

Two small changes for gbrain serve --http users deploying behind PaaS load balancers:

  1. GBRAIN_TRUST_PROXY env varsrc/commands/serve-http.ts makes the Express trust-proxy setting configurable. Default unchanged ('loopback'); set GBRAIN_TRUST_PROXY=1 for Fly.io/Render/Railway/Vercel where the real client IP arrives after exactly one hop. Required for both rate-limiting (correct client IPs) and req.secure detection (OAuth flows).

  2. Supabase Deployment Caveat docsdocs/mcp/DEPLOY.md adds a new section covering the three env vars external Supabase deployments need (GBRAIN_DISABLE_DIRECT_POOL=1, GBRAIN_POOL_SIZE=1, GBRAIN_TRUST_PROXY=1), the pooler URL gotcha (port 6543 not 5432), and a minimal Fly.io fly.toml example.

Why

Tested against a Supabase-backed brain on a self-hosted VPS. Without these flags + docs, the startup sequence wedges on an IPv6 connect to db.<project-ref>.supabase.co:5432 (unreachable from outside Supabase's VPC), and rate-limiting silently misclassifies clients because app.set('trust proxy', 'loopback') only trusts 127.0.0.1. After applying both, gbrain serve --http runs cleanly.

Replaces #759

This is the focused remainder of #759. That PR also bundled DCR /register rate-limiter changes; those landed independently via the v0.31 fix-wave (#776 et al). #760 also got incidentally fixed by the same fix-wave (the engine.connect() call you added to phaseBBackfill/phaseCVerify covers what we'd patched). So #759 is closed and only the trust-proxy + Supabase docs remain — narrower scope, cleaner review.

Test plan

  • tsc --noEmit passes
  • Default behavior unchanged when GBRAIN_TRUST_PROXY is unset
  • Manual smoke test: setting GBRAIN_TRUST_PROXY=1 correctly resolves to integer 1 (not the string)
  • Docs render cleanly on GitHub

🤖 Generated with Claude Code


View in Codesmith
Need help on this PR? Tag @codesmith with what you need.

  • Let Codesmith autofix CI failures and bot reviews

When deploying `gbrain serve --http` behind a PaaS load balancer (Fly.io,
Render, Railway, Vercel), Express's default `trust proxy: 'loopback'` is
too restrictive — the real client IP arrives in X-Forwarded-For after one
hop, and rate limiting + `req.secure` detection both need that hop trusted.

Adds GBRAIN_TRUST_PROXY env var. Default behavior unchanged ('loopback').
Set GBRAIN_TRUST_PROXY=1 for single-hop PaaS, or any other valid Express
trust-proxy value (boolean string, IP list, function name, etc).

Also adds a "Supabase Deployment Caveat" section to docs/mcp/DEPLOY.md
covering the common gotchas for external Supabase-backed deployments:
GBRAIN_DISABLE_DIRECT_POOL=1 (direct postgres host unreachable from outside
Supabase VPC), GBRAIN_POOL_SIZE=1 (transaction-pooler safe sizing), pooler
URL on port 6543 (not 5432), and a minimal Fly.io fly.toml example.

Replaces garrytan#759 — that PR also bundled DCR rate limiter changes which landed
independently in master (the v0.31 fix-wave subsumed them), so this is
the focused remainder.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant