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

package/src/middleware/startup-guard.ts

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

@@ -1,192 +0,0 @@
-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

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