@kb-labs/rest-api-app 1.3.0

package/src/middleware/startup-guard.ts

@@ -0,0 +1,107 @@
+/**
+ * @module @kb-labs/rest-api-app/middleware/startup-guard
+ * Guard to prevent request storms during startup
+ */
+
+import type { FastifyInstance } from 'fastify';
+import type { RestApiConfig } from '@kb-labs/rest-api-core';
+import { isReady } from '../routes/readiness';
+
+type StartupCounters = {
+  inFlight: number;
+};
+
+type StartupConfig = {
+  maxConcurrent?: number;
+  queueLimit?: number;
+  timeoutMs?: number;
+  retryAfterSeconds?: number;
+};
+
+export function registerStartupGuard(
+  server: FastifyInstance,
+  config: RestApiConfig
+): void {
+  const startupConfig = (config as RestApiConfig & { startup?: StartupConfig }).startup;
+  if (!startupConfig) {
+    return;
+  }
+
+  const counters: StartupCounters = {
+    inFlight: 0,
+  };
+
+  server.kbStartupGuard = counters;
+
+  const maxConcurrent = startupConfig.maxConcurrent ?? 32;
+  const queueLimit = startupConfig.queueLimit ?? 128;
+  const timeoutMs = startupConfig.timeoutMs ?? 5000;
+  const retryAfterSeconds = startupConfig.retryAfterSeconds ?? 2;
+
+  server.addHook('onRequest', (request, reply, done) => {
+    const readiness = server.kbReadiness;
+    const infraReady = readiness ? isReady(readiness) : false;
+
+    if (infraReady) {
+      done();
+      return;
+    }
+
+    if (counters.inFlight >= queueLimit) {
+      reply
+        .code(503)
+        .header('Retry-After', retryAfterSeconds.toString())
+        .send({
+          schema: 'kb.startup/1',
+          status: 'initializing',
+          reason: 'startup_queue_limit',
+          maxConcurrent,
+          queueLimit,
+        });
+      return;
+    }
+
+    counters.inFlight += 1;
+    request.kbStartupGuardActive = true;
+
+    const timer = setTimeout(() => {
+      if (!reply.sent) {
+        reply
+          .code(504)
+          .header('Retry-After', retryAfterSeconds.toString())
+          .send({
+            schema: 'kb.startup/1',
+            status: 'timeout',
+            reason: 'startup_timeout',
+            timeoutMs,
+          });
+      }
+    }, timeoutMs);
+    timer.unref();
+    request.kbStartupGuardTimer = timer;
+
+    if (counters.inFlight > maxConcurrent) {
+      if ((request as any).kbLogger) {
+        (request as any).kbLogger.warn('Startup guard concurrency threshold exceeded', {
+          inFlight: counters.inFlight,
+          maxConcurrent,
+        });
+      }
+    }
+
+    done();
+  });
+
+  server.addHook('onResponse', (request, _reply, done) => {
+    if (request.kbStartupGuardActive) {
+      counters.inFlight = Math.max(0, counters.inFlight - 1);
+      if (request.kbStartupGuardTimer) {
+        clearTimeout(request.kbStartupGuardTimer);
+        request.kbStartupGuardTimer = undefined;
+      }
+      request.kbStartupGuardActive = false;
+    }
+    done();
+  });
+}
+

package/src/observability/service-contract.ts

@@ -0,0 +1,192 @@
+import { hostname } from 'node:os';
+import {
+  OBSERVABILITY_CONTRACT_VERSION,
+  OBSERVABILITY_SCHEMA,
+  CANONICAL_OBSERVABILITY_METRICS,
+  type ObservabilityCheck,
+} from '@kb-labs/core-contracts';
+import type {
+  ServiceObservabilityDescribe,
+  ServiceObservabilityHealth,
+  ServiceOperationSample,
+} from '@kb-labs/core-contracts';
+import {
+  createServiceObservabilityDescribe,
+  createServiceObservabilityHealth,
+} from '@kb-labs/shared-http';
+import type { SystemHealthSnapshot } from '@kb-labs/core-registry';
+import type { ReadinessState } from '../routes/readiness.js';
+import { restDomainOperationMetrics, type MetricsSnapshot } from '../middleware/metrics.js';
+import { getLatestSystemMetrics } from '../services/system-metrics-collector.js';
+
+declare const __REST_API_VERSION__: string;
+const REST_VERSION = typeof __REST_API_VERSION__ !== 'undefined' ? __REST_API_VERSION__ : '0.0.0';
+
+function resolveInstanceId(): string {
+  return `${hostname()}:${process.pid}`;
+}
+
+function mergeTopOperations(
+  httpOperations: ServiceOperationSample[],
+  domainOperations: ServiceOperationSample[],
+  limit = 5,
+): ServiceOperationSample[] {
+  const merged = new Map<string, ServiceOperationSample>();
+
+  for (const item of [...httpOperations, ...domainOperations]) {
+    const existing = merged.get(item.operation);
+    if (!existing) {
+      merged.set(item.operation, { ...item });
+      continue;
+    }
+
+    const count = (existing.count ?? 0) + (item.count ?? 0);
+    const totalDurationMs =
+      (existing.avgDurationMs ?? 0) * (existing.count ?? 0) +
+      (item.avgDurationMs ?? 0) * (item.count ?? 0);
+
+    merged.set(item.operation, {
+      operation: item.operation,
+      count,
+      avgDurationMs: count > 0 ? totalDurationMs / count : 0,
+      maxDurationMs: Math.max(existing.maxDurationMs ?? 0, item.maxDurationMs ?? 0),
+      errorCount: (existing.errorCount ?? 0) + (item.errorCount ?? 0),
+    });
+  }
+
+  const ranked = Array.from(merged.values())
+    .sort((a, b) => (b.count ?? 0) - (a.count ?? 0) || (b.maxDurationMs ?? 0) - (a.maxDurationMs ?? 0))
+  const sliced = ranked.slice(0, limit);
+
+  if (domainOperations.length === 0 || sliced.some((item) => !item.operation.startsWith('http.'))) {
+    return sliced;
+  }
+
+  const firstDomainOperation = ranked.find((item) => !item.operation.startsWith('http.'));
+  if (!firstDomainOperation) {
+    return sliced;
+  }
+
+  return [...sliced.slice(0, Math.max(0, limit - 1)), firstDomainOperation];
+}
+
+function finiteNumberOrUndefined(value: number | null | undefined): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+export function buildRestObservabilityDescribe(basePath: string): ServiceObservabilityDescribe {
+  return createServiceObservabilityDescribe({
+    schema: OBSERVABILITY_SCHEMA,
+    contractVersion: OBSERVABILITY_CONTRACT_VERSION,
+    serviceId: 'rest',
+    instanceId: resolveInstanceId(),
+    serviceType: 'http-api',
+    version: REST_VERSION,
+    environment: process.env.NODE_ENV ?? 'development',
+    startedAt: new Date(Date.now() - process.uptime() * 1000).toISOString(),
+    dependencies: [
+      {
+        serviceId: 'workflow',
+        required: true,
+        description: 'Workflow daemon for workflow and jobs APIs',
+      },
+      {
+        serviceId: 'state-daemon',
+        required: false,
+        description: 'State broker and cache-backed storage',
+      },
+    ],
+    metricsEndpoint: `${basePath}/metrics`,
+    healthEndpoint: `${basePath}/observability/health`,
+    logsSource: 'rest',
+    capabilities: ['httpMetrics', 'eventLoopMetrics', 'operationMetrics', 'logCorrelation'],
+    metricFamilies: [...CANONICAL_OBSERVABILITY_METRICS],
+  });
+}
+
+export function buildRestObservabilityHealth(
+  basePath: string,
+  healthSnapshot: SystemHealthSnapshot,
+  readiness: ReadinessState,
+  metrics: MetricsSnapshot,
+): ServiceObservabilityHealth {
+  const runtimeMetrics = getLatestSystemMetrics();
+  const checks: ObservabilityCheck[] = [
+    {
+      id: 'registry',
+      status: readiness.registryLoaded && !readiness.registryPartial && !readiness.registryStale
+        ? 'ok'
+        : readiness.registryLoaded ? 'warn' : 'error',
+      message: readiness.registryLoaded ? 'Registry snapshot loaded' : 'Registry snapshot incomplete',
+    },
+    {
+      id: 'plugin-routes',
+      status: readiness.pluginRouteErrors > 0 ? 'warn' : readiness.pluginRoutesMounted ? 'ok' : 'warn',
+      message: readiness.pluginRoutesMounted
+        ? `${readiness.pluginRoutesCount} plugin routes mounted`
+        : 'Plugin routes are still mounting',
+    },
+    {
+      id: 'redis',
+      status: !readiness.redisEnabled ? 'ok' : readiness.redisConnected ? 'ok' : 'warn',
+      message: !readiness.redisEnabled
+        ? 'Redis integration disabled'
+        : readiness.redisConnected
+          ? 'Redis healthy'
+          : 'Redis unavailable',
+    },
+  ];
+
+  const httpTopOperations = metrics.latency.histogram
+    .slice()
+    .sort((a, b) => b.count - a.count || b.max - a.max)
+    .slice(0, 5)
+    .map((entry) => ({
+      operation: `http.${entry.route}`,
+      count: entry.count,
+      avgDurationMs: entry.count > 0 ? entry.total / entry.count : 0,
+      maxDurationMs: entry.max,
+      errorCount: Object.entries(entry.byStatus)
+        .filter(([status]) => Number(status) >= 400)
+        .reduce((sum, [, count]) => sum + count, 0),
+    }));
+  const topOperations = mergeTopOperations(httpTopOperations, restDomainOperationMetrics.getTopOperations(5));
+
+  const latestOperation = topOperations[0];
+  const state = healthSnapshot.status === 'healthy'
+    ? 'active'
+    : runtimeMetrics || latestOperation
+      ? 'partial_observability'
+      : 'insufficient_data';
+
+  return createServiceObservabilityHealth({
+    schema: OBSERVABILITY_SCHEMA,
+    contractVersion: OBSERVABILITY_CONTRACT_VERSION,
+    serviceId: 'rest',
+    instanceId: resolveInstanceId(),
+    observedAt: healthSnapshot.ts,
+    status: healthSnapshot.status === 'healthy' ? 'healthy' : healthSnapshot.status === 'degraded' ? 'degraded' : 'unhealthy',
+    uptimeSec: healthSnapshot.uptimeSec,
+    metricsEndpoint: `${basePath}/metrics`,
+    logsSource: 'rest',
+    capabilities: ['httpMetrics', 'eventLoopMetrics', 'operationMetrics', 'logCorrelation'],
+    checks,
+    snapshot: {
+      cpuPercent: finiteNumberOrUndefined(runtimeMetrics?.cpu.percentage),
+      rssBytes: finiteNumberOrUndefined(runtimeMetrics?.memory.rss),
+      heapUsedBytes: finiteNumberOrUndefined(runtimeMetrics?.memory.heapUsed),
+      eventLoopLagMs: finiteNumberOrUndefined(runtimeMetrics?.eventLoopLagMs),
+      activeOperations: runtimeMetrics?.activeOperations ?? metrics.requests.active,
+    },
+    topOperations,
+    state,
+    meta: {
+      serviceHealthEndpoint: `${basePath}/health`,
+      readyEndpoint: `${basePath}/ready`,
+      runtimeMetricsCollectedAt: runtimeMetrics ? new Date(runtimeMetrics.timestamp).toISOString() : null,
+      lastRequestAt: metrics.timestamps.lastRequest
+        ? new Date(metrics.timestamps.lastRequest).toISOString()
+        : null,
+    },
+  });
+}

package/src/plugins/index.ts

@@ -0,0 +1,118 @@
+/**
+ * @module @kb-labs/rest-api-app/plugins
+ * Fastify plugins registration
+ */
+
+import type {
+  FastifyInstance,
+  FastifyPluginCallback,
+  FastifyBaseLogger,
+  RawServerDefault,
+  FastifyTypeProviderDefault,
+} from 'fastify';
+import type { RestApiConfig } from '@kb-labs/rest-api-core';
+import fastifyCors, { type FastifyCorsOptions } from '@fastify/cors';
+import fastifyRateLimit, { type RateLimitPluginOptions } from '@fastify/rate-limit';
+import { registerOpenAPI } from '@kb-labs/shared-http';
+
+/**
+ * Register all Fastify plugins
+ */
+export async function registerPlugins(
+  server: FastifyInstance,
+  config: RestApiConfig
+): Promise<void> {
+  // CORS plugin with profile support
+  const corsProfile = config.cors.profile || 'dev';
+  let corsOrigins: string[] | boolean = config.cors.origins;
+  
+  if (corsProfile === 'dev') {
+    // Dev: allow localhost origins
+    corsOrigins = config.cors.origins.length > 0 
+      ? config.cors.origins 
+      : ['http://localhost:3000', 'http://localhost:5173']; // Vite default + Studio
+  } else if (corsProfile === 'preview') {
+    // Preview: specific staging domains
+    corsOrigins = config.cors.origins.length > 0 
+      ? config.cors.origins 
+      : false; // Disable if not configured
+  } else if (corsProfile === 'prod') {
+    // Prod: strict whitelist
+    corsOrigins = config.cors.origins.length > 0 
+      ? config.cors.origins 
+      : false; // Disable if not configured
+  }
+
+  const corsOptions: FastifyCorsOptions = {
+    origin: corsOrigins,
+    credentials: config.cors.allowCredentials,
+    methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS', 'HEAD'],
+    allowedHeaders: [
+      'Content-Type', 
+      'Authorization', 
+      'X-Request-Id', 
+      'X-Trace-Id',  // Added for Studio widget tracing
+      'Idempotency-Key', 
+      'X-Client-Version'
+    ],
+    exposedHeaders: ['X-Request-Id', 'X-Schema-Version', 'X-RateLimit-Limit', 'X-RateLimit-Remaining', 'Retry-After'],
+    preflightContinue: false,
+  };
+
+  const corsPlugin: FastifyPluginCallback<
+    FastifyCorsOptions,
+    RawServerDefault,
+    FastifyTypeProviderDefault,
+    FastifyBaseLogger
+  > = fastifyCors;
+
+  await server.register(corsPlugin, corsOptions);
+
+  // Add Vary: Origin header for CORS caching
+  server.addHook('onSend', async (request, reply) => {
+    if (corsProfile !== 'prod') {
+      try {
+        if (!reply.raw.headersSent) {
+          reply.header('Vary', 'Origin');
+        }
+      } catch (err) {
+        // Headers already sent, ignore
+      }
+    }
+  });
+
+  // Rate limit plugin
+  if (config.rateLimit) {
+    const rateLimitOpts: RateLimitPluginOptions = {
+      max: config.rateLimit.max,
+      timeWindow: config.rateLimit.timeWindow,
+      addHeaders: {
+        'x-ratelimit-limit': true,
+        'x-ratelimit-remaining': true,
+        'x-ratelimit-reset': true,
+      },
+    };
+
+    const rateLimitPlugin: FastifyPluginCallback<
+      RateLimitPluginOptions,
+      RawServerDefault,
+      FastifyTypeProviderDefault,
+      FastifyBaseLogger
+    > = fastifyRateLimit;
+
+    await server.register(rateLimitPlugin, rateLimitOpts);
+  }
+
+  // OpenAPI / Swagger UI
+  // Must be registered after other plugins and before routes.
+  // Spec is at /openapi.json — canonical across all services.
+  // UI is disabled in production (hideUntagged: true keeps internal routes invisible).
+  await registerOpenAPI(server, {
+    title: 'KB Labs REST API',
+    description: 'Main platform REST API — jobs, workflows, plugins, adapters',
+    version: '1.0.0',
+    servers: [{ url: 'http://localhost:5050', description: 'Local dev' }],
+    ui: corsProfile !== 'prod',
+  });
+}
+