@kb-labs/rest-api-app 1.3.0

package/src/middleware/mock-mode.ts

@@ -0,0 +1,44 @@
+/**
+ * @module @kb-labs/rest-api-app/middleware/mock-mode
+ * Mock mode middleware (per-request)
+ */
+
+import type { FastifyInstance } from 'fastify';
+import type { RestApiConfig } from '@kb-labs/rest-api-core';
+import type { IncomingHttpHeaders } from 'http';
+
+type MockableRequest = {
+  headers: IncomingHttpHeaders;
+  mockMode?: boolean;
+};
+
+/**
+ * Check if mock mode should be enabled for this request
+ */
+export function isMockModeEnabled(
+  request: MockableRequest,
+  config: RestApiConfig
+): boolean {
+  // Check per-request header
+  const headerMock = request.headers['kb-mock'];
+  if (headerMock === 'true' || headerMock === '1') {
+    return true;
+  }
+
+  // Check global config
+  return config.mockMode || false;
+}
+
+/**
+ * Register mock mode middleware
+ */
+export function registerMockModeMiddleware(
+  server: FastifyInstance,
+  config: RestApiConfig
+): void {
+  server.addHook('onRequest', async (request) => {
+    const mockableRequest = request as MockableRequest;
+    mockableRequest.mockMode = isMockModeEnabled(mockableRequest, config);
+  });
+}
+

package/src/middleware/prom-metrics.ts

@@ -0,0 +1,284 @@
+/**
+ * @module @kb-labs/rest-api-app/middleware/prom-metrics
+ * Prometheus metrics using prom-client
+ */
+
+import { Registry, Histogram, Counter, Gauge } from 'prom-client';
+
+/**
+ * Prometheus metrics registry
+ */
+export const promRegistry = new Registry();
+
+/**
+ * HTTP request duration histogram with percentiles
+ * Automatically calculates p50, p95, p99
+ */
+export const httpRequestDuration = new Histogram({
+  name: 'http_request_duration_ms',
+  help: 'HTTP request duration in milliseconds',
+  labelNames: ['method', 'route', 'status_code', 'tenant', 'plugin'],
+  buckets: [5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000], // milliseconds
+  registers: [promRegistry],
+});
+
+/**
+ * HTTP requests total counter
+ */
+export const httpRequestsTotal = new Counter({
+  name: 'http_requests_total',
+  help: 'Total number of HTTP requests',
+  labelNames: ['method', 'route', 'status_code', 'tenant', 'plugin'],
+  registers: [promRegistry],
+});
+
+/**
+ * HTTP errors total counter
+ */
+export const httpErrorsTotal = new Counter({
+  name: 'http_errors_total',
+  help: 'Total number of HTTP errors (4xx, 5xx)',
+  labelNames: ['status_code', 'error_code', 'tenant'],
+  registers: [promRegistry],
+});
+
+/**
+ * Process uptime gauge
+ */
+export const processUptime = new Gauge({
+  name: 'process_uptime_seconds',
+  help: 'Process uptime in seconds',
+  registers: [promRegistry],
+});
+
+export const processCpuPercent = new Gauge({
+  name: 'process_cpu_percent',
+  help: 'Current process CPU usage percentage',
+  registers: [promRegistry],
+});
+
+export const processRssBytes = new Gauge({
+  name: 'process_rss_bytes',
+  help: 'Current process resident set size in bytes',
+  registers: [promRegistry],
+});
+
+export const processHeapUsedBytes = new Gauge({
+  name: 'process_heap_used_bytes',
+  help: 'Current process heap used in bytes',
+  registers: [promRegistry],
+});
+
+export const processEventLoopLagMs = new Gauge({
+  name: 'process_event_loop_lag_ms',
+  help: 'Current event loop lag in milliseconds',
+  registers: [promRegistry],
+});
+
+export const serviceHealthStatus = new Gauge({
+  name: 'service_health_status',
+  help: 'Service health status (2=healthy, 1=degraded, 0=unhealthy)',
+  registers: [promRegistry],
+});
+
+export const serviceRestartsTotal = new Gauge({
+  name: 'service_restarts_total',
+  help: 'Service restart counter within current process lifetime',
+  registers: [promRegistry],
+});
+
+export const serviceActiveOperations = new Gauge({
+  name: 'service_active_operations',
+  help: 'Current number of active operations',
+  registers: [promRegistry],
+});
+
+export const serviceOperationTotal = new Counter({
+  name: 'service_operation_total',
+  help: 'Total number of service operations',
+  labelNames: ['operation', 'status'],
+  registers: [promRegistry],
+});
+
+export const serviceOperationDuration = new Histogram({
+  name: 'service_operation_duration_ms',
+  help: 'Service operation duration in milliseconds',
+  labelNames: ['operation', 'status'],
+  buckets: [5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000],
+  registers: [promRegistry],
+});
+
+/**
+ * Header policy metrics
+ */
+export const headersFiltered = new Counter({
+  name: 'kb_headers_filtered_total',
+  help: 'Total headers filtered by policy enforcement',
+  labelNames: ['direction', 'plugin'],
+  registers: [promRegistry],
+});
+
+export const headersSensitiveInbound = new Counter({
+  name: 'kb_headers_sensitive_inbound_total',
+  help: 'Sensitive inbound headers observed',
+  labelNames: ['plugin'],
+  registers: [promRegistry],
+});
+
+export const headersValidationErrors = new Counter({
+  name: 'kb_headers_validation_errors_total',
+  help: 'Header validation errors encountered',
+  labelNames: ['plugin'],
+  registers: [promRegistry],
+});
+
+export const headersVaryApplied = new Counter({
+  name: 'kb_headers_vary_applied_total',
+  help: 'Vary header entries applied by policy',
+  labelNames: ['plugin'],
+  registers: [promRegistry],
+});
+
+export const headersDryRunDecisions = new Counter({
+  name: 'kb_headers_dry_run_decisions_total',
+  help: 'Header decisions skipped due to dry-run mode',
+  registers: [promRegistry],
+});
+
+/**
+ * Plugin metrics
+ */
+export const pluginRequestsTotal = new Counter({
+  name: 'kb_plugin_request_total',
+  help: 'Total HTTP requests per plugin',
+  labelNames: ['plugin'],
+  registers: [promRegistry],
+});
+
+export const pluginRequestDuration = new Histogram({
+  name: 'kb_plugin_request_duration_ms',
+  help: 'Plugin request duration metrics',
+  labelNames: ['plugin'],
+  buckets: [5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000],
+  registers: [promRegistry],
+});
+
+/**
+ * Tenant metrics
+ */
+export const tenantRequestsTotal = new Counter({
+  name: 'kb_tenant_request_total',
+  help: 'Total HTTP requests per tenant',
+  labelNames: ['tenant'],
+  registers: [promRegistry],
+});
+
+export const tenantErrorsTotal = new Counter({
+  name: 'kb_tenant_request_errors_total',
+  help: 'Total HTTP errors per tenant',
+  labelNames: ['tenant'],
+  registers: [promRegistry],
+});
+
+export const tenantRequestDuration = new Histogram({
+  name: 'kb_tenant_request_duration_ms',
+  help: 'Tenant request duration',
+  labelNames: ['tenant'],
+  buckets: [5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000],
+  registers: [promRegistry],
+});
+
+/**
+ * Plugin mount metrics
+ */
+export const pluginsMountTotal = new Gauge({
+  name: 'kb_plugins_mount_total',
+  help: 'Plugins processed during last mount run',
+  registers: [promRegistry],
+});
+
+export const pluginsMountSucceeded = new Gauge({
+  name: 'kb_plugins_mount_succeeded',
+  help: 'Plugins successfully mounted',
+  registers: [promRegistry],
+});
+
+export const pluginsMountFailed = new Gauge({
+  name: 'kb_plugins_mount_failed',
+  help: 'Plugins failed to mount',
+  registers: [promRegistry],
+});
+
+export const pluginsMountElapsed = new Gauge({
+  name: 'kb_plugins_mount_elapsed_ms',
+  help: 'Plugin mount elapsed time in milliseconds',
+  registers: [promRegistry],
+});
+
+/**
+ * Redis metrics
+ */
+export const redisStatusUpdates = new Counter({
+  name: 'kb_redis_status_updates_total',
+  help: 'Redis status updates observed',
+  registers: [promRegistry],
+});
+
+export const redisStatusTransitions = new Counter({
+  name: 'kb_redis_status_transitions_total',
+  help: 'Redis health transitions',
+  labelNames: ['state'],
+  registers: [promRegistry],
+});
+
+export const redisHealthy = new Gauge({
+  name: 'kb_redis_healthy',
+  help: 'Redis healthy flag (1 = healthy)',
+  registers: [promRegistry],
+});
+
+export const redisRoleState = new Gauge({
+  name: 'kb_redis_role_state_total',
+  help: 'Redis role state occurrences',
+  labelNames: ['role', 'state'],
+  registers: [promRegistry],
+});
+
+/**
+ * Update process uptime metric
+ */
+export function updateProcessUptime(startTimeMs: number): void {
+  const uptimeSeconds = (Date.now() - startTimeMs) / 1000;
+  processUptime.set(uptimeSeconds);
+}
+
+export function updateRuntimeObservabilityMetrics(input: {
+  cpuPercent: number;
+  rssBytes: number;
+  heapUsedBytes: number;
+  eventLoopLagMs: number;
+  activeOperations: number;
+  healthStatus?: 'healthy' | 'degraded' | 'unhealthy';
+}): void {
+  processCpuPercent.set(input.cpuPercent);
+  processRssBytes.set(input.rssBytes);
+  processHeapUsedBytes.set(input.heapUsedBytes);
+  processEventLoopLagMs.set(input.eventLoopLagMs);
+  serviceActiveOperations.set(input.activeOperations);
+  serviceRestartsTotal.set(0);
+
+  if (input.healthStatus) {
+    updateServiceHealthStatus(input.healthStatus);
+  }
+}
+
+export function updateServiceHealthStatus(status: 'healthy' | 'degraded' | 'unhealthy'): void {
+  serviceHealthStatus.set(status === 'healthy' ? 2 : status === 'degraded' ? 1 : 0);
+}
+
+/**
+ * Get all metrics in Prometheus format
+ */
+export async function getPrometheusMetrics(): Promise<string> {
+  return promRegistry.metrics();
+}

package/src/middleware/rate-limit-routes.ts

@@ -0,0 +1,73 @@
+/**
+ * @module @kb-labs/rest-api-app/middleware/rate-limit-routes
+ * Per-route rate limiting middleware
+ */
+
+import type { FastifyInstance } from 'fastify';
+import type { RestApiConfig } from '@kb-labs/rest-api-core';
+
+/**
+ * Rate limit configuration per route
+ */
+interface RouteRateLimit {
+  max: number;
+  timeWindow: string;
+}
+
+const routeLimits: Record<string, RouteRateLimit> = {
+  '/audit/runs': { max: 10, timeWindow: '1 minute' },
+  '/release/runs': { max: 5, timeWindow: '1 minute' },
+  '/devlink/check': { max: 20, timeWindow: '1 minute' },
+  // Health endpoints - higher limits
+  '/health': { max: 100, timeWindow: '1 minute' },
+  '/ready': { max: 60, timeWindow: '1 minute' },
+  '/observability/describe': { max: 60, timeWindow: '1 minute' },
+  '/observability/health': { max: 60, timeWindow: '1 minute' },
+  // Info endpoints - moderate limits
+  '/info': { max: 30, timeWindow: '1 minute' },
+  '/info/capabilities': { max: 30, timeWindow: '1 minute' },
+  // Jobs endpoints - moderate limits
+  '/jobs': { max: 60, timeWindow: '1 minute' },
+};
+
+/**
+ * Register per-route rate limiting
+ */
+export function registerRouteRateLimiting(
+  server: FastifyInstance,
+  config: RestApiConfig
+): void {
+  // Only apply if rate limiting is enabled globally
+  if (!config.rateLimit) {
+    return;
+  }
+
+  // Apply route-specific limits
+  for (const [route] of Object.entries(routeLimits)) {
+    const fullPath = `${config.basePath}${route}`;
+    
+    server.addHook('onRequest', async (request, _reply) => {
+      // Check if this route matches
+      if (!request.url.startsWith(fullPath)) {
+        return;
+      }
+
+      // Apply route-specific rate limit
+      // Note: This is a simplified implementation
+      // Full implementation would use @fastify/rate-limit with route-specific config
+      // For now, we rely on global rate limiting configured in plugins
+    });
+  }
+
+  // Apply stricter limits for POST requests to run endpoints
+  server.addHook('onRequest', async (request, _reply) => {
+    const isRunEndpoint = request.url.includes('/audit/runs') || 
+                          request.url.includes('/release/runs') ||
+                          request.url.includes('/devlink/check');
+    
+    if (isRunEndpoint && request.method === 'POST') {
+      // These limits are enforced by the queue adapter's concurrency limits
+      // Additional rate limiting is handled globally
+    }
+  });
+}

package/src/middleware/rate-limit.ts

@@ -0,0 +1,72 @@
+/**
+ * @module @kb-labs/rest-api-app/middleware/rate-limit
+ * Tenant-aware rate limiting middleware
+ */
+
+import type { FastifyRequest, FastifyReply } from 'fastify';
+
+interface TenantRateLimiter {
+  checkLimit(tenantId: string, resource: string): Promise<{
+    allowed: boolean;
+    limit: number;
+    remaining: number;
+    resetAt: number;
+  }>;
+}
+
+/**
+ * Extract tenant ID from request
+ * Priority order:
+ * 1. Header: X-Tenant-ID
+ * 2. Environment: KB_TENANT_ID
+ * 3. Default: 'default'
+ *
+ * @param request - Fastify request
+ * @returns Tenant ID
+ */
+export function extractTenantId(request: FastifyRequest): string {
+  return (
+    (request.headers['x-tenant-id'] as string) ||
+    process.env.KB_TENANT_ID ||
+    'default'
+  );
+}
+
+/**
+ * Create rate limiting middleware
+ *
+ * @param rateLimiter - Tenant rate limiter instance
+ * @returns Fastify preHandler hook
+ */
+export function createRateLimitMiddleware(rateLimiter: TenantRateLimiter) {
+  return async function rateLimitMiddleware(
+    request: FastifyRequest,
+    reply: FastifyReply
+  ) {
+    const tenantId = extractTenantId(request);
+
+    // Check rate limit for requests
+    const result = await rateLimiter.checkLimit(tenantId, 'requests');
+
+    // Add rate limit headers (standard X-RateLimit-* headers)
+    reply.header('X-RateLimit-Limit', result.limit);
+    reply.header('X-RateLimit-Remaining', result.remaining);
+    reply.header('X-RateLimit-Reset', result.resetAt);
+
+    if (!result.allowed) {
+      const retryAfter = Math.ceil((result.resetAt - Date.now()) / 1000);
+      reply.header('Retry-After', retryAfter);
+
+      return reply.code(429).send({
+        error: 'RATE_LIMIT_EXCEEDED',
+        message: 'Too many requests. Please try again later.',
+        retryAfter,
+        limit: result.limit,
+        resetAt: new Date(result.resetAt).toISOString(),
+      });
+    }
+
+    // Store tenantId in request context for downstream use
+    (request as any).tenantId = tenantId;
+  };
+}

package/src/middleware/request-id.ts

@@ -0,0 +1,41 @@
+/**
+ * @module @kb-labs/rest-api-app/middleware/request-id
+ * Request ID generation and correlation middleware
+ */
+
+import type { FastifyInstance } from 'fastify';
+import { ulid } from 'ulid';
+import { platform } from '@kb-labs/core-runtime';
+import { createCorrelatedLogger } from '@kb-labs/shared-http';
+
+/**
+ * Register request ID middleware
+ */
+export function registerRequestIdMiddleware(server: FastifyInstance): void {
+  server.addHook('onRequest', async (request, reply) => {
+    const requestId = (request.headers['x-request-id'] as string | undefined) || ulid();
+    const traceId = (request.headers['x-trace-id'] as string | undefined) || ulid();
+
+    request.id = requestId;
+    reply.header('X-Request-Id', requestId);
+    reply.header('X-Trace-Id', traceId);
+
+    // Store logger metadata on request for metrics middleware to use
+    (request as any).kbLogger = createCorrelatedLogger(platform.logger, {
+      serviceId: 'rest',
+      logsSource: 'rest',
+      layer: 'rest',
+      service: 'request',
+      requestId,
+      traceId,
+      method: request.method,
+      url: request.url,
+      operation: 'http.request',
+    });
+
+    // Log request received
+    const method = request.method.toUpperCase();
+    const fullUrl = request.url;
+    (request as any).kbLogger.info(`→ ${method} ${fullUrl}`);
+  });
+}

package/src/middleware/request-timeout.ts

@@ -0,0 +1,69 @@
+/**
+ * @module @kb-labs/rest-api-app/middleware/request-timeout
+ * Enforce route-level request timeouts
+ */
+
+import type { FastifyInstance } from 'fastify';
+import type { RestApiConfig } from '@kb-labs/rest-api-core';
+import { metricsCollector } from './metrics';
+
+type RouteConfig = {
+  kbRouteBudgetMs?: number | null;
+};
+
+export function registerRequestTimeoutGuard(
+  server: FastifyInstance,
+  config: RestApiConfig
+): void {
+  const defaultTimeout = config.timeouts?.requestTimeout ?? 30_000;
+
+  server.addHook('onRequest', (request, reply, done) => {
+    const routeConfig = (request.routeOptions?.config || {}) as RouteConfig;
+    let budget = typeof routeConfig.kbRouteBudgetMs === 'number' && routeConfig.kbRouteBudgetMs > 0
+      ? routeConfig.kbRouteBudgetMs
+      : null;
+
+    if (!budget) {
+      const normalized =
+        request.routeOptions?.url ??
+        request.url;
+      const inferred = normalized ? metricsCollector.getRouteBudget(request.method, normalized) : null;
+      if (inferred && inferred > 0) {
+        budget = inferred;
+      }
+    }
+
+    if (!budget || budget <= 0) {
+      budget = defaultTimeout;
+    }
+
+    if (!budget || budget <= 0) {
+      done();
+      return;
+    }
+
+    reply.raw.setTimeout(budget, () => {
+      if (reply.sent) {
+        return;
+      }
+      reply
+        .code(504)
+        .header('Content-Type', 'application/json')
+        .send({
+          schema: 'kb.errors/timeout/1',
+          status: 'error',
+          http: 504,
+          code: 'E_GATEWAY_TIMEOUT',
+          message: 'Request timed out',
+          meta: {
+            method: request.method,
+            route: request.routeOptions?.url ?? request.url,
+            timeoutMs: budget,
+          },
+        });
+    });
+
+    done();
+  });
+}
+

package/src/middleware/security-headers.ts

@@ -0,0 +1,24 @@
+/**
+ * @module @kb-labs/rest-api-app/middleware/security-headers
+ * Security headers middleware
+ */
+
+import type { FastifyInstance } from 'fastify';
+
+/**
+ * Register security headers middleware
+ */
+export function registerSecurityHeadersMiddleware(server: FastifyInstance): void {
+  server.addHook('onRequest', async (request, reply) => {
+    reply.header('X-Content-Type-Options', 'nosniff');
+    reply.header('X-Frame-Options', 'DENY');
+    reply.header('X-XSS-Protection', '1; mode=block');
+    reply.header('Referrer-Policy', 'strict-origin-when-cross-origin');
+    reply.header('Permissions-Policy', 'geolocation=(), microphone=(), camera=()');
+
+    if (request.protocol === 'https') {
+      reply.header('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
+    }
+  });
+}
+