API Gateway

// ── Without API Gateway: ─────────────────────────────────────────────
//
//  Mobile App
//    ├── GET http://user-service:8081/api/users/1
//    ├── GET http://order-service:8082/api/orders?userId=1
//    └── GET http://payment-service:8083/api/payments?userId=1
//
//  Problems:
//  • Client must know 3 different host:port combinations
//  • Each service must implement auth, CORS, rate limiting independently
//  • Any service rename/move requires a client update
//  • Mobile app makes 3 round trips — slow on poor connections
//  • No single place to enforce security policies

// ── With API Gateway: ─────────────────────────────────────────────────
//
//  Mobile App
//    └── All requests → http://api.example.com  (gateway)
//            │
//            ├── /api/users/**    ──▶  user-service:8081
//            ├── /api/orders/**   ──▶  order-service:8082
//            └── /api/payments/** ──▶  payment-service:8083
//
//  Benefits:
//  + Client knows exactly ONE address
//  + Auth/CORS/rate limiting enforced ONCE at the gateway
//  + Internal topology hidden — move services without client changes
//  + Gateway can aggregate multiple service calls into one response
//  + SSL terminated at the gateway — internal traffic can be plain HTTP

// ── What a gateway handles on every request: ─────────────────────────
//
//  Inbound request
//       │
//       ▼
//  [1] SSL Termination    — decrypt HTTPS, forward HTTP internally
//  [2] Authentication     — validate JWT / API key
//  [3] Rate Limiting      — reject if client exceeds quota
//  [4] Request Logging    — log method, path, client IP, latency
//  [5] Routing            — which service handles this path?
//  [6] Load Balancing     — which instance of that service?
//  [7] Request Transform  — add/remove headers, rewrite paths
//       │
//       ▼
//  Downstream Service
//       │
//       ▼
//  [8] Response Transform — add CORS headers, strip internal headers
//  [9] Circuit Breaking   — return fallback if service is down
//       │
//       ▼
//  Client

// ── 1. ROUTING — path-based and header-based: ────────────────────────
//
//  /api/users/**    → user-service
//  /api/orders/**   → order-service
//  /api/v2/**       → new version of services (canary routing)
//  Header: X-Beta: true → beta-service  (header-based routing)

// ── 2. AUTHENTICATION — centralised JWT validation: ───────────────────
//
//  Gateway validates the JWT on every request.
//  If valid → strip the token, forward user identity in a header.
//  If invalid → return 401 immediately; downstream never sees the request.
//
//  Downstream services trust the gateway:
//    X-User-Id: 42
//    X-User-Role: ADMIN
//  No need for each service to re-validate the JWT.

// ── 3. RATE LIMITING — protect services from overload: ────────────────
//
//  Per-client limits (by IP or API key):
//    Free tier:    100 requests / minute
//    Pro tier:   1,000 requests / minute
//    Internal:  unlimited
//
//  Exceeded → 429 Too Many Requests (before the request reaches services)

// ── 4. REQUEST / RESPONSE TRANSFORMATION: ────────────────────────────
//
//  Add upstream headers:
//    X-Request-Id: uuid         (for distributed tracing)
//    X-Gateway-Source: gateway  (so services know request came via gateway)
//    X-Real-IP: <client IP>
//
//  Remove sensitive response headers before returning to client:
//    Remove: X-Powered-By, Server, X-Internal-Service-Version

// ── 5. AGGREGATION (Backend for Frontend pattern): ────────────────────
//
//  Mobile client needs: user profile + recent orders + payment status
//  Instead of 3 client round trips, the gateway (or a BFF service) calls
//  all three services and returns a single merged response.
//
//  Client:  GET /api/dashboard/42
//  Gateway calls:
//    → user-service/api/users/42
//    → order-service/api/orders?userId=42&limit=5
//    → payment-service/api/payments?userId=42&status=PENDING
//  Returns: { user: {...}, orders: [...], pendingPayments: [...] }

// ── 6. CIRCUIT BREAKING — fallback when a service is down: ────────────
//
//  payment-service is returning 503:
//    Without circuit breaker → gateway waits, threads pile up, gateway hangs
//    With circuit breaker    → gateway returns cached/default response fast
//    Fallback response: { "paymentStatus": "unavailable" }

// ── Comparison: ───────────────────────────────────────────────────────
//
// ┌────────────────────┬───────────────┬──────────────┬──────────────┐
// │ Feature            │ Reverse Proxy │ Load Balancer│ API Gateway  │
// ├────────────────────┼───────────────┼──────────────┼──────────────┤
// │ SSL termination    │ ✓             │ ✓            │ ✓            │
// │ Forward to backend │ ✓             │ ✓            │ ✓            │
// │ Distribute load    │ basic         │ ✓            │ ✓            │
// │ Path-based routing │ limited       │ ✗            │ ✓            │
// │ Header-based route │ ✗             │ ✗            │ ✓            │
// │ Authentication     │ ✗             │ ✗            │ ✓            │
// │ Rate limiting      │ ✗             │ ✗            │ ✓            │
// │ Request transform  │ ✗             │ ✗            │ ✓            │
// │ Circuit breaking   │ ✗             │ ✗            │ ✓            │
// │ Service discovery  │ ✗             │ ✗            │ ✓            │
// └────────────────────┴───────────────┴──────────────┴──────────────┘
//
// Real-world stack — these are often layered:
//
//  Internet
//     ↓
//  Cloud Load Balancer (AWS ALB / GCP LB)  ← distributes across gateway pods
//     ↓
//  API Gateway (Spring Cloud Gateway)      ← routing, auth, rate limiting
//     ↓
//  Microservices                           ← business logic

// ── Gateway types: ───────────────────────────────────────────────────
//
// Self-hosted (code in your repo):
//   Spring Cloud Gateway   → Java / Spring Boot
//   Netflix Zuul 2         → Java (legacy, mostly replaced by SCG)
//
// Infrastructure / cloud-managed:
//   AWS API Gateway        → managed, serverless-friendly
//   Kong                   → plugin-based, Lua / Go
//   NGINX API Gateway      → high-performance C-based proxy
//   Traefik                → cloud-native, auto-discovers Docker/K8s services

// ── Single gateway problem: ───────────────────────────────────────────
//
//  Web app   → needs full user profile, all order fields, charts data
//  Mobile app→ needs minimal profile, 3 most recent orders, no charts
//  Partner   → needs only order status and tracking number (no user PII)
//
//  One gateway trying to serve all three → complex conditional logic,
//  over-fetching on mobile, under-fetching for web.

// ── BFF pattern — one gateway per client: ─────────────────────────────
//
//                     ┌─────────────────┐
//  Browser ──────────▶│  Web BFF :8080  │
//                     └────────┬────────┘
//                              │ calls user-service, order-service,
//                              │ analytics-service, returns rich payload
//
//                     ┌─────────────────┐
//  Mobile App ────────▶│ Mobile BFF :8081│
//                     └────────┬────────┘
//                              │ calls same services, returns
//                              │ trimmed/compressed payload
//
//                     ┌─────────────────┐
//  Partner API ───────▶│Partner BFF :8082│
//                     └────────┬────────┘
//                              │ exposes only public-safe fields,
//                              │ enforces partner-specific rate limits
//
//  All three BFFs call the same downstream microservices.
//  Each shapes the response for its specific consumer.

// ── Mobile BFF example (returns trimmed order list): ─────────────────
@RestController
@RequiredArgsConstructor
@RequestMapping("/mobile/api")
public class MobileBffController {

    private final UserClient userClient;
    private final OrderClient orderClient;

    @GetMapping("/dashboard/{userId}")
    public MobileDashboardResponse getDashboard(@PathVariable Long userId) {
        UserResponse user   = userClient.findById(userId);
        List<OrderResponse> orders = orderClient.findRecent(userId, 3);

        // Shape response specifically for mobile — minimal payload:
        return MobileDashboardResponse.builder()
            .userName(user.getFirstName())       // not full profile
            .avatarUrl(user.getAvatarUrl())
            .recentOrders(orders.stream()
                .map(o -> new OrderSummary(o.getId(), o.getStatus()))
                .toList())                       // status only, no line items
            .build();
    }
}