@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/api-gateway.md

@@ -0,0 +1,341 @@
+---
+name: api-gateway
+description: API gateway patterns for routing, rate limiting, authentication, request transformation, load balancing, and health checks.
+---
+
+# API Gateway Patterns
+
+## When to Use
+Implement an API gateway when you have multiple backend services and need a unified entry point for clients. Gateways handle cross-cutting concerns: authentication, rate limiting, request routing, response transformation, and load balancing. Use these patterns in microservice architectures, BFF (Backend for Frontend) setups, or any system where you need to decouple client-facing APIs from internal service topology.
+
+## How It Works
+
+### Express-Based API Gateway
+
+```typescript
+// src/gateway.ts
+import express from 'express';
+import { createProxyMiddleware } from 'http-proxy-middleware';
+import rateLimit from 'express-rate-limit';
+import helmet from 'helmet';
+import cors from 'cors';
+
+const app = express();
+
+// Security headers
+app.use(helmet());
+app.use(cors({ origin: process.env.ALLOWED_ORIGINS?.split(','), credentials: true }));
+app.use(express.json({ limit: '1mb' }));
+
+// Service registry
+const services: Record<string, { target: string; healthPath: string }> = {
+  users: { target: 'http://user-service:3001', healthPath: '/health' },
+  posts: { target: 'http://post-service:3002', healthPath: '/health' },
+  billing: { target: 'http://billing-service:3003', healthPath: '/health' },
+  search: { target: 'http://search-service:3004', healthPath: '/health' },
+};
+
+// Global rate limiter
+app.use(rateLimit({
+  windowMs: 60_000,
+  max: 100,
+  standardHeaders: true,
+  legacyHeaders: false,
+  keyGenerator: (req) => req.headers['x-forwarded-for'] as string || req.ip,
+  message: { error: 'Too many requests', retryAfter: 60 },
+}));
+
+// Route to services
+for (const [name, config] of Object.entries(services)) {
+  app.use(`/api/${name}`, createProxyMiddleware({
+    target: config.target,
+    changeOrigin: true,
+    pathRewrite: { [`^/api/${name}`]: '' },
+    timeout: 30_000,
+    proxyTimeout: 30_000,
+    on: {
+      proxyReq: (proxyReq, req) => {
+        // Forward auth context
+        if ((req as any).userId) {
+          proxyReq.setHeader('X-User-Id', (req as any).userId);
+        }
+        proxyReq.setHeader('X-Request-Id', req.headers['x-request-id'] || crypto.randomUUID());
+      },
+      error: (err, req, res) => {
+        console.error(`Proxy error [${name}]:`, err.message);
+        (res as express.Response).status(502).json({
+          error: 'Service unavailable',
+          service: name,
+        });
+      },
+    },
+  }));
+}
+
+app.listen(3000, () => console.log('Gateway listening on :3000'));
+```
+
+### Authentication Middleware
+
+```typescript
+// src/middleware/auth.ts
+import jwt from 'jsonwebtoken';
+import type { Request, Response, NextFunction } from 'express';
+
+interface AuthConfig {
+  publicPaths: string[];
+  jwtSecret: string;
+}
+
+export function authMiddleware(config: AuthConfig) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    // Skip auth for public paths
+    if (config.publicPaths.some((p) => req.path.startsWith(p))) {
+      return next();
+    }
+
+    const authHeader = req.headers.authorization;
+    if (!authHeader?.startsWith('Bearer ')) {
+      return res.status(401).json({ error: 'Missing authorization header' });
+    }
+
+    const token = authHeader.slice(7);
+    try {
+      const payload = jwt.verify(token, config.jwtSecret) as { userId: string; role: string };
+      (req as any).userId = payload.userId;
+      (req as any).userRole = payload.role;
+      next();
+    } catch (err) {
+      if ((err as jwt.JsonWebTokenError).name === 'TokenExpiredError') {
+        return res.status(401).json({ error: 'Token expired', code: 'TOKEN_EXPIRED' });
+      }
+      return res.status(401).json({ error: 'Invalid token' });
+    }
+  };
+}
+
+// Register before proxy routes
+app.use(authMiddleware({
+  publicPaths: ['/api/auth', '/health', '/api/docs'],
+  jwtSecret: process.env.JWT_SECRET!,
+}));
+```
+
+### Per-Route Rate Limiting
+
+```typescript
+// src/middleware/rate-limit.ts
+import rateLimit from 'express-rate-limit';
+import RedisStore from 'rate-limit-redis';
+import { createClient } from 'redis';
+
+const redis = createClient({ url: process.env.REDIS_URL });
+await redis.connect();
+
+export function createRateLimiter(windowMs: number, max: number) {
+  return rateLimit({
+    windowMs,
+    max,
+    standardHeaders: true,
+    store: new RedisStore({
+      sendCommand: (...args: string[]) => redis.sendCommand(args),
+    }),
+    keyGenerator: (req) => {
+      const userId = (req as any).userId;
+      return userId ? `user:${userId}` : req.ip;
+    },
+  });
+}
+
+// Different limits per route
+app.use('/api/auth/login', createRateLimiter(15 * 60_000, 5));   // 5 per 15 min
+app.use('/api/search', createRateLimiter(60_000, 30));             // 30 per min
+app.use('/api/billing', createRateLimiter(60_000, 10));            // 10 per min
+```
+
+### Request/Response Transformation
+
+```typescript
+// src/middleware/transform.ts
+import type { Request, Response, NextFunction } from 'express';
+
+// Version-based response transformation
+export function apiVersionTransform(req: Request, res: Response, next: NextFunction) {
+  const version = req.headers['api-version'] || 'v2';
+
+  // Intercept response for transformation
+  const originalJson = res.json.bind(res);
+  res.json = function (body: any) {
+    if (version === 'v1' && body?.data) {
+      // v1 clients expect flat response, v2 uses envelope
+      return originalJson(body.data);
+    }
+    return originalJson(body);
+  };
+
+  next();
+}
+
+// Request enrichment
+export function enrichRequest(req: Request, _res: Response, next: NextFunction) {
+  const requestId = req.headers['x-request-id'] || crypto.randomUUID();
+  req.headers['x-request-id'] = requestId;
+  req.headers['x-gateway-timestamp'] = new Date().toISOString();
+  req.headers['x-client-ip'] = req.headers['x-forwarded-for'] as string || req.ip;
+  next();
+}
+```
+
+### Health Check Aggregation
+
+```typescript
+// src/health.ts
+import type { Request, Response } from 'express';
+
+interface ServiceHealth {
+  name: string;
+  status: 'healthy' | 'degraded' | 'down';
+  latencyMs: number;
+  lastChecked: string;
+}
+
+async function checkServiceHealth(name: string, url: string): Promise<ServiceHealth> {
+  const start = Date.now();
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5000);
+    const res = await fetch(url, { signal: controller.signal });
+    clearTimeout(timeout);
+
+    return {
+      name,
+      status: res.ok ? 'healthy' : 'degraded',
+      latencyMs: Date.now() - start,
+      lastChecked: new Date().toISOString(),
+    };
+  } catch {
+    return {
+      name,
+      status: 'down',
+      latencyMs: Date.now() - start,
+      lastChecked: new Date().toISOString(),
+    };
+  }
+}
+
+app.get('/health', async (_req: Request, res: Response) => {
+  const checks = await Promise.all(
+    Object.entries(services).map(([name, config]) =>
+      checkServiceHealth(name, `${config.target}${config.healthPath}`)
+    )
+  );
+
+  const allHealthy = checks.every((c) => c.status === 'healthy');
+  const anyDown = checks.some((c) => c.status === 'down');
+
+  res.status(anyDown ? 503 : 200).json({
+    status: anyDown ? 'degraded' : allHealthy ? 'healthy' : 'degraded',
+    services: checks,
+    uptime: process.uptime(),
+    timestamp: new Date().toISOString(),
+  });
+});
+
+// Liveness probe (lightweight)
+app.get('/health/live', (_req, res) => res.status(200).send('ok'));
+
+// Readiness probe (checks dependencies)
+app.get('/health/ready', async (_req, res) => {
+  const critical = ['users', 'billing'];
+  const checks = await Promise.all(
+    critical.map((name) =>
+      checkServiceHealth(name, `${services[name].target}${services[name].healthPath}`)
+    )
+  );
+  const ready = checks.every((c) => c.status !== 'down');
+  res.status(ready ? 200 : 503).json({ ready, services: checks });
+});
+```
+
+### Circuit Breaker
+
+```typescript
+// src/circuit-breaker.ts
+type State = 'closed' | 'open' | 'half-open';
+
+export class CircuitBreaker {
+  private state: State = 'closed';
+  private failures = 0;
+  private lastFailure = 0;
+  private successCount = 0;
+
+  constructor(
+    private readonly threshold: number = 5,
+    private readonly resetTimeoutMs: number = 30_000,
+    private readonly halfOpenMax: number = 3,
+  ) {}
+
+  async execute<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.state === 'open') {
+      if (Date.now() - this.lastFailure > this.resetTimeoutMs) {
+        this.state = 'half-open';
+        this.successCount = 0;
+      } else {
+        throw new Error('Circuit breaker is open');
+      }
+    }
+
+    try {
+      const result = await fn();
+      this.onSuccess();
+      return result;
+    } catch (err) {
+      this.onFailure();
+      throw err;
+    }
+  }
+
+  private onSuccess() {
+    if (this.state === 'half-open') {
+      this.successCount++;
+      if (this.successCount >= this.halfOpenMax) {
+        this.state = 'closed';
+        this.failures = 0;
+      }
+    } else {
+      this.failures = 0;
+    }
+  }
+
+  private onFailure() {
+    this.failures++;
+    this.lastFailure = Date.now();
+    if (this.failures >= this.threshold) {
+      this.state = 'open';
+    }
+  }
+
+  getState(): State { return this.state; }
+}
+```
+
+## Examples
+
+| Concern | Implementation | Where |
+|---------|---------------|-------|
+| Auth | JWT verification middleware | Before proxy |
+| Rate limiting | Redis-backed sliding window | Per-route |
+| Routing | `http-proxy-middleware` | Path prefix mapping |
+| Transformation | Response interceptor | API version compat |
+| Health | Aggregated service checks | `/health` endpoint |
+| Circuit breaking | Failure counter + timeout | Per-service proxy |
+
+## Checklist
+- [ ] All requests authenticated before reaching backend services
+- [ ] Rate limiting applied globally and per-route with Redis backing
+- [ ] Proxy forwards `X-Request-Id` for distributed tracing
+- [ ] Service errors return 502 with service name, not raw proxy errors
+- [ ] Health endpoint checks all downstream services with timeout
+- [ ] Liveness and readiness probes separated for Kubernetes
+- [ ] Circuit breaker prevents cascading failures between services
+- [ ] Request/response logged with request ID for debugging

package/assets/skills/api-versioning.md

@@ -0,0 +1,226 @@
+---
+name: api-versioning
+description: API versioning patterns with URL, header, and query param versioning, deprecation strategy, and changelog.
+---
+
+# API Versioning
+
+## When to Use
+Apply when your API has external consumers and you need to make breaking changes without disrupting them. Version your API from day one. Use URL-based versioning for simplicity, header-based for cleanliness, and maintain a deprecation strategy that gives consumers time to migrate.
+
+## How It Works
+
+### URL-Based Versioning (Recommended Default)
+
+The most common and discoverable approach:
+
+```typescript
+import { Router } from "express";
+
+const v1Router = Router();
+const v2Router = Router();
+
+v1Router.get("/users/:id", async (req, res) => {
+  const user = await userService.getById(req.params.id);
+  res.json({ id: user.id, name: user.fullName, email: user.email });
+});
+
+v2Router.get("/users/:id", async (req, res) => {
+  const user = await userService.getById(req.params.id);
+  res.json({
+    id: user.id,
+    name: { first: user.firstName, last: user.lastName },
+    email: user.email,
+    createdAt: user.createdAt.toISOString(),
+    links: { self: `/api/v2/users/${user.id}` },
+  });
+});
+
+app.use("/api/v1", v1Router);
+app.use("/api/v2", v2Router);
+```
+
+### Header-Based Versioning
+
+Keeps URLs clean; version is in the Accept header:
+
+```typescript
+function versionMiddleware(req: Request, _res: Response, next: NextFunction) {
+  const accept = req.headers.accept ?? "";
+  const match = accept.match(/application\/vnd\.myapp\.v(\d+)\+json/);
+  req.apiVersion = match ? parseInt(match[1]) : 1;
+  next();
+}
+
+app.use(versionMiddleware);
+
+app.get("/api/users/:id", (req, res) => {
+  switch (req.apiVersion) {
+    case 2: return getUserV2(req, res);
+    default: return getUserV1(req, res);
+  }
+});
+```
+
+Client sends: `Accept: application/vnd.myapp.v2+json`
+
+### Deprecation Strategy
+
+Give consumers clear warnings and a migration timeline:
+
+```typescript
+function deprecationMiddleware(
+  deprecatedVersion: number,
+  sunsetDate: string,
+  migrationGuide: string
+) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    if (req.apiVersion <= deprecatedVersion) {
+      res.setHeader("Deprecation", "true");
+      res.setHeader("Sunset", new Date(sunsetDate).toUTCString());
+      res.setHeader("Link", `<${migrationGuide}>; rel="deprecation"`);
+      logger.warn({
+        apiVersion: req.apiVersion,
+        path: req.path,
+        clientId: req.headers["x-client-id"],
+      }, "Deprecated API version called");
+    }
+    next();
+  };
+}
+
+app.use(deprecationMiddleware(
+  1,
+  "2027-06-01",
+  "https://docs.example.com/api/migration-v2"
+));
+```
+
+### Breaking vs. Non-Breaking Changes
+
+```
+NON-BREAKING (no new version needed):
+- Adding a new field to the response
+- Adding a new optional query parameter
+- Adding a new endpoint
+- Making a required field optional
+
+BREAKING (needs new version):
+- Removing or renaming a field
+- Changing a field's type (string -> number)
+- Changing the response structure (flat -> nested)
+- Making an optional field required
+- Changing error response format
+- Changing authentication method
+```
+
+### Version Negotiation Middleware
+
+```typescript
+interface VersionConfig {
+  supported: number[];
+  current: number;
+  deprecated: number[];
+  sunset: Record<number, string>;
+}
+
+const versionConfig: VersionConfig = {
+  supported: [1, 2, 3],
+  current: 3,
+  deprecated: [1],
+  sunset: { 1: "2027-03-01T00:00:00Z" },
+};
+
+function versionNegotiation(config: VersionConfig) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const requested = parseInt(req.headers["x-api-version"] as string) || config.current;
+
+    if (!config.supported.includes(requested)) {
+      return res.status(400).json({
+        error: `API version ${requested} not supported`,
+        supported: config.supported,
+      });
+    }
+
+    if (config.deprecated.includes(requested)) {
+      res.setHeader("Deprecation", "true");
+      if (config.sunset[requested]) {
+        res.setHeader("Sunset", config.sunset[requested]);
+      }
+    }
+
+    req.apiVersion = requested;
+    res.setHeader("X-API-Version", String(requested));
+    next();
+  };
+}
+```
+
+### API Changelog
+
+```markdown
+## v2.3.0 -- 2026-06-15
+### Added
+- `GET /users/:id` now includes `createdAt` field
+- New endpoint: `POST /users/:id/avatar`
+### Deprecated
+- `items` field in `POST /orders` -- use `lineItems`. Sunset: 2027-01-01.
+- `GET /api/v1/*` -- migrate to v2. Sunset: 2027-03-01.
+
+## v2.2.0 -- 2026-04-20
+### Fixed
+- Pagination correctly returns `hasNextPage: false` on last page
+```
+
+### OpenAPI Spec Per Version
+
+```yaml
+openapi: 3.0.3
+info:
+  title: My API
+  version: "2.0.0"
+servers:
+  - url: https://api.example.com/api/v2
+paths:
+  /users:
+    get:
+      summary: List users
+      parameters:
+        - name: cursor
+          in: query
+          schema: { type: string }
+        - name: limit
+          in: query
+          schema: { type: integer, default: 20, maximum: 100 }
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items: { $ref: "#/components/schemas/UserV2" }
+                  pagination:
+                    $ref: "#/components/schemas/CursorPagination"
+```
+
+## Examples
+
+| Strategy | Pros | Cons |
+|----------|------|------|
+| URL (`/api/v2/`) | Discoverable, cacheable | URL pollution |
+| Header (`Accept: vnd.app.v2`) | Clean URLs | Less discoverable |
+| Query param (`?version=2`) | Easy to test | Pollutes caching |
+| GraphQL `@deprecated` | No versioning needed | Requires schema discipline |
+
+## Checklist
+- [ ] API versioned from v1 on day one
+- [ ] Versioning strategy is consistent (URL or header -- pick one)
+- [ ] Breaking changes only in new version numbers
+- [ ] Deprecated versions send `Deprecation` and `Sunset` headers
+- [ ] Migration guide published for every breaking change
+- [ ] Changelog maintained with every release
+- [ ] OpenAPI spec exists per active version
+- [ ] Old versions have sunset date and caller monitoring