Skip to main content

Gateway Service

The Gateway is the single entry point for all external API traffic. It validates JWTs, enforces rate limits, and reverse-proxies requests to downstream services. It contains no business logic — it validates and routes.

Quick Reference​

PropertyValue
Port8080
LanguageGo
FrameworkChi v5
Module pathgithub.com/gospelib/main/services/gateway
Entry pointcmd/server/main.go
Docker imageMulti-stage → Alpine (~12MB)

Responsibilities​

  • JWT validation — Verifies Clerk-issued JWTs and extracts user claims
  • Rate limiting — Per-user and per-IP token bucket stored in Redis
  • Reverse proxy — Routes /api/v1/<resource> to the owning service
  • Entitlement enforcement — Checks plan-gated features via Redis cache
  • Request ID injection — Generates and propagates X-Request-ID headers
  • CORS — Configures allowed origins for web and mobile clients
  • Health checks — Exposes /health and /ready endpoints

What the Gateway Does NOT Do​

  • No database access
  • No user management
  • No business logic
  • No direct response generation (except health checks and errors)

Running Locally​

# From the repository root
cd services/gateway
go run ./cmd/server

The gateway starts on port 8080. It expects downstream services to be running at their configured URLs.

Environment Variables​

VariableDefaultDescription
GOSPELIB_GATEWAY_PORT8080HTTP listen port
GOSPELIB_GATEWAY_CONTENT_URLhttp://localhost:8100Content service URL
GOSPELIB_GATEWAY_AUTH_URLhttp://localhost:8200Auth service URL
GOSPELIB_GATEWAY_BILLING_URLhttp://localhost:8300Billing service URL
GOSPELIB_GATEWAY_AI_URLhttp://localhost:8400AI service URL
GOSPELIB_GATEWAY_NOTIFICATIONS_URLhttp://localhost:8500Notifications service URL
GOSPELIB_GATEWAY_REDIS_URLredis://localhost:6380Redis for rate limiting and entitlement cache
GOSPELIB_GATEWAY_CLERK_JWKS_URL—Clerk JWKS endpoint for JWT validation
GOSPELIB_GATEWAY_CORS_ORIGINShttp://localhost:3002Allowed CORS origins (comma-separated)

Health Check​

curl http://localhost:8080/health
# {"status": "ok"}

curl http://localhost:8080/ready
# {"status": "ready"}

Entry Point Pattern​

The Go entry point at cmd/server/main.go follows the standard GospeLib pattern:

  1. Configure Zerolog (JSON structured logging)
  2. Load config from environment variables
  3. Create Chi router with the global middleware stack
  4. Register routes — health first, then grouped by auth requirement
  5. Create http.Server
  6. Start in a goroutine
  7. Wait for SIGINT/SIGTERM
  8. Graceful shutdown with 10-second context

Docker​

FROM golang:1.25-alpine AS builder
WORKDIR /build
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /app ./cmd/server

FROM alpine:3.20
RUN apk --no-cache add ca-certificates
COPY --from=builder /app /app
EXPOSE 8080
ENTRYPOINT ["/app"]