goplt/docs/content/stories/epic1/1.8-api-gateway.md

Story 1.8: API Gateway Implementation

Metadata

• Story ID: 1.8
• Title: API Gateway Implementation
• Epic: 1 - Core Kernel & Infrastructure
• Status: In Progress
• Priority: High
• Estimated Time: 8-10 hours
• Dependencies: 1.1, 1.5, 1.7

Goal

Implement API Gateway as core infrastructure component that routes all external traffic to backend services via service discovery (Consul). Gateway handles authentication, rate limiting, CORS, and request transformation.

Description

This story implements the API Gateway service that serves as the single entry point for all external traffic. The gateway routes requests to backend services via Consul service discovery, validates JWT tokens via Auth Service, checks permissions via Authz Service, and handles rate limiting and CORS.

Deliverables

1. API Gateway Service Entry Point (cmd/api-gateway/main.go)

• Service entry point for API Gateway
• Bootstrap with core kernel services
• Register with Consul service registry
• Start HTTP server

2. Gateway Implementation (services/gateway/internal/)

• Routing Engine (router.go):

  • Route configuration from YAML
  • Path matching and service routing
  • Service discovery integration (Consul)
  • Load balancing across service instances

• Authentication Middleware (auth.go):

  • JWT token extraction from headers
  • Token validation via Auth Service client
  • User context injection

• Authorization Middleware (authz.go):

  • Permission checking via Authz Service client (optional, for route-level auth)
  • Route-based permission configuration

• Rate Limiting (ratelimit.go):

  • Per-user rate limiting (via user ID from JWT)
  • Per-IP rate limiting
  • Redis-backed rate limiting state
  • Configurable limits per route

• CORS Support (cors.go):

  • Configurable CORS headers
  • Preflight request handling

• Request/Response Transformation (transform.go):

  • Request modification before forwarding
  • Response modification before returning
  • Header manipulation

3. Gateway Configuration (config/default.yaml)

gateway:
  port: 8080
  routes:
    - path: /api/v1/auth/**
      service: auth-service
      auth_required: false
      rate_limit:
        per_user: 100/minute
        per_ip: 1000/minute
    - path: /api/v1/users/**
      service: identity-service
      auth_required: true
      permission: user.read
      rate_limit:
        per_user: 50/minute
    - path: /api/v1/blog/**
      service: blog-service
      auth_required: true
      permission: blog.post.read
  cors:
    allowed_origins: ["*"]
    allowed_methods: ["GET", "POST", "PUT", "DELETE"]
    allowed_headers: ["Authorization", "Content-Type"]
  service_discovery:
    type: consul
    consul:
      address: "localhost:8500"

4. Service Discovery Integration

• Consul integration for service discovery
• Dynamic service endpoint resolution
• Health check filtering (only route to healthy services)
• Load balancing across service instances

5. Health Check Endpoint

• GET /healthz - Gateway health check
• GET /ready - Gateway readiness (checks service registry connectivity)

Implementation Steps

1. Create Service Entry Point

   • Create cmd/api-gateway/main.go
   • Bootstrap with core kernel
   • Register with Consul

2. Implement Routing Engine

   • Create services/gateway/internal/router.go
   • Implement route matching
   • Integrate with Consul service discovery
   • Implement load balancing

3. Implement Authentication

   • Create services/gateway/internal/auth.go
   • JWT token extraction
   • Token validation via Auth Service client
   • User context injection

4. Implement Rate Limiting

   • Create services/gateway/internal/ratelimit.go
   • Redis integration
   • Per-user and per-IP limiting

5. Implement CORS

   • Create services/gateway/internal/cors.go
   • Configurable CORS support

6. Add Configuration

   • Update config/default.yaml
   • Add gateway configuration

7. Test Gateway

   • Test routing to backend services
   • Test authentication
   • Test rate limiting
   • Test service discovery

Acceptance Criteria

• API Gateway service is independently deployable
• Gateway routes requests to backend services correctly
• JWT validation works via Auth Service client
• Rate limiting works correctly (per-user and per-IP)
• CORS is configurable and works
• Service discovery integration works (Consul)
• Gateway has health check endpoint
• All external traffic goes through gateway
• Gateway registers with Consul
• Load balancing works across service instances

Related ADRs

• ADR-0032: API Gateway Strategy
• ADR-0033: Service Discovery Implementation
• ADR-0030: Service Communication Strategy

Implementation Notes

• Gateway is a core infrastructure component, not optional
• All external traffic must go through gateway
• Gateway uses service clients for backend communication
• Service discovery via Consul is required
• Rate limiting state is stored in Redis
• Gateway should be horizontally scalable

Testing

# Test gateway startup
go run cmd/api-gateway/main.go

# Test routing
curl http://localhost:8080/api/v1/auth/login

# Test with Consul
docker-compose up consul
go test ./services/gateway/... -tags=integration

Files to Create/Modify

• cmd/api-gateway/main.go - Gateway service entry point
• services/gateway/internal/router.go - Routing engine
• services/gateway/internal/auth.go - Authentication middleware
• services/gateway/internal/authz.go - Authorization middleware
• services/gateway/internal/ratelimit.go - Rate limiting
• services/gateway/internal/cors.go - CORS support
• services/gateway/internal/transform.go - Request/response transformation
• config/default.yaml - Add gateway configuration