@kb-labs/rest-api-app 1.3.0 → 1.4.0

package/src/middleware/mock-mode.ts

@@ -1,44 +0,0 @@
-/**
- * @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

@@ -1,284 +0,0 @@
-/**
- * @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

@@ -1,73 +0,0 @@
-/**
- * @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

@@ -1,72 +0,0 @@
-/**
- * @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

@@ -1,41 +0,0 @@
-/**
- * @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

@@ -1,69 +0,0 @@
-/**
- * @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

@@ -1,24 +0,0 @@
-/**
- * @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');
-    }
-  });
-}
-