@kb-labs/rest-api-app 1.3.0

package/src/routes/health.ts

@@ -0,0 +1,348 @@
+/**
+ * @module @kb-labs/rest-api-app/routes/health
+ * Health check and diagnostics endpoints
+ */
+
+import type { FastifyInstance } from 'fastify';
+import type { RestApiConfig } from '@kb-labs/rest-api-core';
+import type { IEntityRegistry, SystemHealthSnapshot } from '@kb-labs/core-registry';
+import { normalizeBasePath, resolvePaths } from '../utils/path-helpers';
+import type { ReadinessState } from './readiness';
+import { isReady, resolveReadinessReason } from './readiness';
+import type { PluginsMetricsSnapshot } from '../middleware/metrics.js';
+import { metricsCollector } from '../middleware/metrics.js';
+import { updateServiceHealthStatus } from '../middleware/prom-metrics.js';
+import {
+  buildRestObservabilityDescribe,
+  buildRestObservabilityHealth,
+} from '../observability/service-contract.js';
+
+// Version is injected at build time by tsup define
+declare const __REST_API_VERSION__: string;
+const REST_VERSION = typeof __REST_API_VERSION__ !== 'undefined' ? __REST_API_VERSION__ : '0.0.0';
+
+const CACHE_WINDOW_MS = 200;
+const READY_SCHEMA = 'kb.ready/1';
+
+interface CachedSnapshot {
+  base: SystemHealthSnapshot;
+  expiresAt: number;
+}
+
+let cachedBaseSnapshot: CachedSnapshot | null = null;
+let inFlightBaseSnapshot: Promise<SystemHealthSnapshot> | null = null;
+
+/**
+ * Register health and readiness routes
+ */
+export async function registerHealthRoutes(
+  fastify: FastifyInstance,
+  config: RestApiConfig,
+  _repoRoot: string,
+  registry: IEntityRegistry,
+  readiness: ReadinessState
+): Promise<void> {
+  const basePath = normalizeBasePath(config.basePath);
+  const healthPaths = resolvePaths(basePath, '/health');
+  const readyPaths = resolvePaths(basePath, '/ready');
+  const observabilityDescribePaths = resolvePaths(basePath, '/observability/describe');
+  const observabilityHealthPaths = resolvePaths(basePath, '/observability/health');
+
+  for (const path of healthPaths) {
+    fastify.get(path, async (_request, reply) => {
+      const eventHub = fastify.kbEventHub;
+      try {
+        const baseSnapshot = await getBaseSnapshot(registry);
+        const { registryLoaded, registryPartial, registryStale } = evaluateRegistryState(registry);
+        readiness.registryLoaded = registryLoaded;
+        readiness.registryPartial = registryPartial;
+        readiness.registryStale = registryStale;
+        const ready = isReady(readiness);
+        const reason = resolveReadinessReason(readiness);
+        const pluginsMetrics = metricsCollector.getLastPluginMountSnapshot();
+        const response = augmentSnapshot(baseSnapshot, readiness, pluginsMetrics);
+        updateServiceHealthStatus(
+          response.status === 'healthy' ? 'healthy' : response.status === 'degraded' ? 'degraded' : 'unhealthy',
+        );
+        eventHub?.publish({
+          type: 'health',
+          status: response.status,
+          ts: response.ts,
+          ready,
+          reason,
+          registryPartial: readiness.registryPartial,
+          registryStale: readiness.registryStale,
+          registryLoaded: readiness.registryLoaded,
+        });
+        return reply.send(response);
+      } catch (error) {
+        const fallback = buildFallbackSnapshot(error, readiness);
+        updateServiceHealthStatus('degraded');
+        const ready = isReady(readiness);
+        const reason = resolveReadinessReason(readiness);
+        eventHub?.publish({
+          type: 'health',
+          status: fallback.status,
+          ts: fallback.ts,
+          ready,
+          reason,
+          registryPartial: readiness.registryPartial,
+          registryStale: readiness.registryStale,
+          registryLoaded: readiness.registryLoaded,
+        });
+        return reply.send(fallback);
+      }
+    });
+  }
+
+  for (const path of readyPaths) {
+    fastify.get(path, async (_request, reply) => {
+      const eventHub = fastify.kbEventHub;
+      const { registryLoaded, registryPartial, registryStale } = evaluateRegistryState(registry);
+      readiness.registryLoaded = registryLoaded;
+      readiness.registryPartial = registryPartial;
+      readiness.registryStale = registryStale;
+
+      const response = buildReadinessResponse(readiness);
+      const statusCode = response.ready ? 200 : 503;
+      updateServiceHealthStatus(response.ready ? 'healthy' : 'degraded');
+
+      eventHub?.publish({
+        type: 'health',
+        status: response.ready ? 'healthy' : 'degraded',
+        ts: new Date().toISOString(),
+        ready: response.ready,
+        reason: response.reason,
+        registryPartial: readiness.registryPartial,
+        registryStale: readiness.registryStale,
+        registryLoaded: readiness.registryLoaded,
+        pluginMountInProgress: readiness.pluginMountInProgress,
+        pluginRoutesMounted: readiness.pluginRoutesMounted,
+        lastPluginMountTs: readiness.lastPluginMountTs,
+        pluginRoutesLastDurationMs: readiness.pluginRoutesLastDurationMs,
+        pluginsMounted: metricsCollector.getLastPluginMountSnapshot()?.succeeded ?? 0,
+        pluginsFailed: metricsCollector.getLastPluginMountSnapshot()?.failed ?? 0,
+      });
+
+      return reply.code(statusCode).send(response);
+    });
+  }
+
+  for (const path of observabilityDescribePaths) {
+    fastify.get(path, async () => buildRestObservabilityDescribe(basePath));
+  }
+
+  for (const path of observabilityHealthPaths) {
+    fastify.get(path, async () => {
+      try {
+        const baseSnapshot = await getBaseSnapshot(registry);
+        const pluginsMetrics = metricsCollector.getLastPluginMountSnapshot();
+        const augmented = augmentSnapshot(baseSnapshot, readiness, pluginsMetrics);
+        updateServiceHealthStatus(
+          augmented.status === 'healthy' ? 'healthy' : augmented.status === 'degraded' ? 'degraded' : 'unhealthy',
+        );
+        return buildRestObservabilityHealth(basePath, augmented, readiness, metricsCollector.getMetrics());
+      } catch (error) {
+        const fallback = buildFallbackSnapshot(error, readiness);
+        updateServiceHealthStatus('degraded');
+        return buildRestObservabilityHealth(basePath, fallback, readiness, metricsCollector.getMetrics());
+      }
+    });
+  }
+}
+
+async function getBaseSnapshot(registry: IEntityRegistry): Promise<SystemHealthSnapshot> {
+  const now = Date.now();
+  if (cachedBaseSnapshot && now < cachedBaseSnapshot.expiresAt) {
+    return cachedBaseSnapshot.base;
+  }
+
+  if (inFlightBaseSnapshot) {
+    return inFlightBaseSnapshot;
+  }
+
+  inFlightBaseSnapshot = registry
+    .getSystemHealth({
+      uptimeSec: process.uptime(),
+      version: { rest: REST_VERSION },
+    })
+    .then(snapshot => {
+      cachedBaseSnapshot = {
+        base: snapshot,
+        expiresAt: Date.now() + CACHE_WINDOW_MS,
+      };
+      inFlightBaseSnapshot = null;
+      return snapshot;
+    })
+    .catch(error => {
+      inFlightBaseSnapshot = null;
+      throw error;
+    });
+
+  return inFlightBaseSnapshot;
+}
+
+function augmentSnapshot(
+  base: SystemHealthSnapshot,
+  readiness: ReadinessState,
+  pluginsMetrics?: PluginsMetricsSnapshot | null
+): SystemHealthSnapshot {
+  const snapshot = cloneSnapshot(base);
+  const failures = new Map(readiness.pluginRouteFailures.map(f => [f.id, f.error]));
+
+  const components = snapshot.components.map(component => {
+    const failure = failures.get(component.id);
+    return failure
+      ? {
+          ...component,
+          lastError: failure,
+        }
+      : component;
+  });
+
+  const readinessMeta = {
+    pluginRoutesMounted: readiness.pluginRoutesMounted,
+    pluginMountInProgress: readiness.pluginMountInProgress,
+    pluginRoutesCount: readiness.pluginRoutesCount,
+    pluginRouteErrors: readiness.pluginRouteErrors,
+    pluginRouteFailures: readiness.pluginRouteFailures,
+    registryPartial: readiness.registryPartial,
+    registryStale: readiness.registryStale,
+    pluginMounts: pluginsMetrics ?? null,
+    lastPluginMountTs: readiness.lastPluginMountTs ?? null,
+    pluginRoutesLastDurationMs: readiness.pluginRoutesLastDurationMs ?? null,
+    redisEnabled: readiness.redisEnabled,
+    redisConnected: readiness.redisConnected,
+    redisStates: readiness.redisStates,
+  };
+
+  const meta: Record<string, unknown> = {
+    source: 'rest',
+    ...(snapshot.meta || {}),
+    readiness: readinessMeta,
+  };
+
+  if (readiness.pluginRouteFailures.length > 0) {
+    meta.readinessFailures = readiness.pluginRouteFailures;
+  }
+
+  const hasReadinessErrors = readiness.pluginRouteErrors > 0 || readiness.pluginRouteFailures.length > 0;
+
+  return {
+    ...snapshot,
+    status: hasReadinessErrors ? 'degraded' : snapshot.status,
+    components,
+    meta,
+  };
+}
+
+function buildFallbackSnapshot(
+  error: unknown,
+  readiness: ReadinessState
+): SystemHealthSnapshot {
+  const message = sanitizeError(error);
+  const now = new Date();
+
+  const snapshot: SystemHealthSnapshot = {
+    schema: 'kb.health/1',
+    ts: now.toISOString(),
+    uptimeSec: Math.max(0, Math.floor(process.uptime())),
+    version: {
+      kbLabs: process.env.KB_LABS_VERSION || process.env.KB_VERSION || 'unknown',
+      rest: REST_VERSION,
+    },
+    registry: {
+      total: 0,
+      withRest: 0,
+      withStudio: 0,
+      errors: 1,
+      generatedAt: new Date(0).toISOString(),
+      expiresAt: undefined,
+      partial: true,
+      stale: true,
+    },
+    status: 'degraded',
+    components: [],
+    meta: {
+      source: 'rest',
+      error: message,
+    },
+  };
+
+  return augmentSnapshot(snapshot, readiness, metricsCollector.getLastPluginMountSnapshot());
+}
+
+function cloneSnapshot(base: SystemHealthSnapshot): SystemHealthSnapshot {
+  return {
+    schema: base.schema,
+    ts: base.ts,
+    uptimeSec: base.uptimeSec,
+    version: { ...base.version },
+    registry: { ...base.registry },
+    status: base.status,
+    components: base.components.map(component => ({ ...component })),
+    ...(base.meta ? { meta: { ...base.meta } } : {}),
+  };
+}
+
+function sanitizeError(error: unknown): string {
+  if (!error) {
+    return 'unknown_error';
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  const firstLine = message.trim().split('\n')[0] ?? message.trim();
+  return firstLine.length > 160 ? `${firstLine.slice(0, 157)}...` : firstLine;
+}
+
+function evaluateRegistryState(registry: IEntityRegistry): {
+  registryLoaded: boolean;
+  registryPartial: boolean;
+  registryStale: boolean;
+} {
+  const snapshot = registry.snapshot();
+  return {
+    registryLoaded: snapshot.plugins.length > 0 && !snapshot.partial && !snapshot.stale,
+    registryPartial: snapshot.partial,
+    registryStale: snapshot.stale,
+  };
+}
+
+function buildReadinessResponse(readiness: ReadinessState) {
+  const ready = isReady(readiness);
+  const pluginIssues =
+    readiness.pluginRouteErrors > 0 || readiness.pluginRouteFailures.length > 0;
+  const status = ready ? (pluginIssues ? 'degraded' : 'ready') : 'initializing';
+  const reason = ready ? 'ready' : resolveReadinessReason(readiness);
+
+  return {
+    schema: READY_SCHEMA,
+    ts: new Date().toISOString(),
+    ready,
+    status,
+    reason,
+    components: {
+      cliApi: {
+        initialized: readiness.cliApiInitialized,
+      },
+      registry: {
+        loaded: readiness.registryLoaded,
+        partial: readiness.registryPartial,
+        stale: readiness.registryStale,
+      },
+      plugins: {
+        mounted: readiness.pluginRoutesMounted,
+        inProgress: readiness.pluginMountInProgress,
+        routeCount: readiness.pluginRoutesCount,
+        errors: readiness.pluginRouteErrors,
+        failures: readiness.pluginRouteFailures,
+        lastCompletedAt: readiness.lastPluginMountTs ?? null,
+        lastDurationMs: readiness.pluginRoutesLastDurationMs ?? null,
+      },
+      redis: {
+        enabled: readiness.redisEnabled,
+        healthy: readiness.redisConnected,
+        states: readiness.redisStates,
+      },
+    },
+  };
+}

package/src/routes/hello.ts

@@ -0,0 +1,47 @@
+/**
+ * @module @kb-labs/rest-api-app/routes/hello
+ * Hello service endpoint — simple liveness / greeting check
+ */
+
+import type { FastifyInstance } from 'fastify';
+import type { RestApiConfig } from '@kb-labs/rest-api-core';
+import type { HelloResponse } from '@kb-labs/rest-api-contracts';
+import { normalizeBasePath } from '../utils/path-helpers';
+
+/**
+ * Register hello routes
+ *
+ * GET /api/v1/hello
+ *   Returns a greeting message together with the current server timestamp.
+ *   Useful as a lightweight smoke-test that the REST API is reachable.
+ */
+export async function registerHelloRoutes(
+  fastify: FastifyInstance,
+  config: RestApiConfig
+): Promise<void> {
+  const basePath = normalizeBasePath(config.basePath);
+
+  /**
+   * GET /hello
+   * Returns { schema, message, ts } wrapped in a SuccessEnvelope.
+   */
+  fastify.get(`${basePath}/hello`, async (request, reply) => {
+    const start = Date.now();
+
+    const response: HelloResponse = {
+      ok: true,
+      data: {
+        schema: 'kb.hello/1',
+        message: 'Hello from KB Labs REST API!',
+        ts: new Date().toISOString(),
+      },
+      meta: {
+        requestId: request.id as string,
+        durationMs: Date.now() - start,
+        apiVersion: '1.0.0',
+      },
+    };
+
+    return reply.code(200).send(response);
+  });
+}