@kb-labs/rest-api-app 1.3.0

package/src/routes/analytics.ts

@@ -0,0 +1,328 @@
+/**
+ * @module @kb-labs/rest-api-app/routes/analytics
+ * Analytics endpoints for querying events, stats, and monitoring
+ */
+
+import type { FastifyInstance } from 'fastify';
+import type { RestApiConfig } from '@kb-labs/rest-api-core';
+import { normalizeBasePath, resolvePaths } from '../utils/path-helpers';
+import { platform } from '@kb-labs/core-runtime';
+import { restDomainOperationMetrics } from '../middleware/metrics.js';
+import type {
+  EventsQuery,
+  EventsResponse,
+  EventsStats,
+  BufferStatus,
+  DlqStatus,
+} from '@kb-labs/core-platform/adapters';
+
+/**
+ * Register analytics routes
+ *
+ * These are system-level analytics endpoints that expose events and statistics
+ * from the platform's analytics adapter (if configured).
+ *
+ * Returns 501 Not Implemented if analytics adapter doesn't support read methods.
+ */
+export async function registerAnalyticsRoutes(
+  fastify: FastifyInstance,
+  config: RestApiConfig
+): Promise<void> {
+  const basePath = normalizeBasePath(config.basePath);
+
+  // GET /api/v1/analytics/events
+  // Query analytics events with optional filters
+  const eventsPaths = resolvePaths(basePath, '/analytics/events');
+  for (const path of eventsPaths) {
+    fastify.get<{
+      Querystring: {
+        type?: string | string[];
+        source?: string;
+        actor?: string;
+        from?: string;
+        to?: string;
+        limit?: string;
+        offset?: string;
+      };
+    }>(path, async (request, reply) => {
+      try {
+        const analytics = platform.analytics;
+
+        // Check if analytics adapter supports read methods
+        const getEvents = analytics.getEvents;
+        if (!getEvents) {
+          fastify.log.debug('Analytics adapter does not implement getEvents()');
+          return reply.code(501).send({
+            ok: false,
+            error: {
+              code: 'ANALYTICS_NOT_IMPLEMENTED',
+              message: 'Analytics adapter does not support reading events',
+            },
+          });
+        }
+
+        // Build query from request params
+        const query: EventsQuery = {};
+
+        if (request.query.type !== undefined) {
+          query.type = request.query.type;
+        }
+        if (request.query.source) {
+          query.source = request.query.source;
+        }
+        if (request.query.actor) {
+          query.actor = request.query.actor;
+        }
+        if (request.query.from) {
+          query.from = request.query.from;
+        }
+        if (request.query.to) {
+          query.to = request.query.to;
+        }
+        if (request.query.limit) {
+          query.limit = Number.parseInt(request.query.limit, 10);
+        }
+        if (request.query.offset) {
+          query.offset = Number.parseInt(request.query.offset, 10);
+        }
+
+        fastify.log.debug({ query }, 'Fetching analytics events');
+
+        const response: EventsResponse = await restDomainOperationMetrics.observeOperation(
+          'analytics.events.query',
+          () => getEvents.call(analytics, query),
+        );
+
+        fastify.log.debug(
+          {
+            total: response.total,
+            count: response.events.length,
+            hasMore: response.hasMore,
+          },
+          'Analytics events fetched successfully'
+        );
+
+        return {
+          ok: true,
+          data: response,
+          meta: {
+            source: 'analytics-adapter',
+          },
+        };
+      } catch (error) {
+        platform.logger.error('Failed to fetch analytics events', error instanceof Error ? error : new Error(String(error)));
+
+        return reply.code(500).send({
+          ok: false,
+          error: {
+            code: 'ANALYTICS_ERROR',
+            message: error instanceof Error ? error.message : 'Failed to fetch analytics events',
+          },
+        });
+      }
+    });
+  }
+
+  // GET /api/v1/analytics/stats
+  // Get aggregated statistics
+  const statsPaths = resolvePaths(basePath, '/analytics/stats');
+  for (const path of statsPaths) {
+    fastify.get(path, async (_request, reply) => {
+      try {
+        const analytics = platform.analytics;
+
+        const getStats = analytics.getStats;
+        if (!getStats) {
+          fastify.log.debug('Analytics adapter does not implement getStats()');
+          return reply.code(501).send({
+            ok: false,
+            error: {
+              code: 'ANALYTICS_NOT_IMPLEMENTED',
+              message: 'Analytics adapter does not support reading stats',
+            },
+          });
+        }
+
+        fastify.log.debug('Fetching analytics stats');
+
+        // Cache stats for 60 seconds to avoid reprocessing 50k+ events on every request
+        const cacheKey = 'analytics:stats';
+        let stats = await platform.cache.get<EventsStats>(cacheKey);
+
+        if (!stats) {
+          fastify.log.debug('Cache miss, fetching stats from adapter');
+          stats = await restDomainOperationMetrics.observeOperation('analytics.stats.get', () => getStats.call(analytics));
+          await platform.cache.set(cacheKey, stats, 60 * 1000); // 60 second TTL
+        } else {
+          fastify.log.debug('Cache hit, returning cached stats');
+        }
+
+        fastify.log.debug(
+          {
+            totalEvents: stats.totalEvents,
+            timeRange: stats.timeRange,
+          },
+          'Analytics stats fetched successfully'
+        );
+
+        return {
+          ok: true,
+          data: stats,
+          meta: {
+            source: 'analytics-adapter',
+          },
+        };
+      } catch (error) {
+        platform.logger.error('Failed to fetch analytics stats', error instanceof Error ? error : new Error(String(error)));
+
+        return reply.code(500).send({
+          ok: false,
+          error: {
+            code: 'ANALYTICS_ERROR',
+            message: error instanceof Error ? error.message : 'Failed to fetch analytics stats',
+          },
+        });
+      }
+    });
+  }
+
+  // GET /api/v1/analytics/buffer/status
+  // Get WAL buffer status (if applicable)
+  const bufferPaths = resolvePaths(basePath, '/analytics/buffer/status');
+  for (const path of bufferPaths) {
+    fastify.get(path, async (_request, reply) => {
+      try {
+        const analytics = platform.analytics;
+
+        const getBufferStatus = analytics.getBufferStatus;
+        if (!getBufferStatus) {
+          fastify.log.debug('Analytics adapter does not implement getBufferStatus()');
+          return reply.code(501).send({
+            ok: false,
+            error: {
+              code: 'ANALYTICS_NOT_IMPLEMENTED',
+              message: 'Analytics adapter does not support buffer status',
+            },
+          });
+        }
+
+        fastify.log.debug('Fetching analytics buffer status');
+
+        const status: BufferStatus | null = await restDomainOperationMetrics.observeOperation(
+          'analytics.buffer.status',
+          () => getBufferStatus.call(analytics),
+        );
+
+        if (status === null) {
+          fastify.log.debug('Buffer status not applicable for current analytics backend');
+          return reply.code(501).send({
+            ok: false,
+            error: {
+              code: 'BUFFER_NOT_APPLICABLE',
+              message: 'Buffer status not applicable for current analytics backend',
+            },
+          });
+        }
+
+        fastify.log.debug(
+          {
+            segments: status.segments,
+            totalSizeBytes: status.totalSizeBytes,
+          },
+          'Analytics buffer status fetched successfully'
+        );
+
+        return {
+          ok: true,
+          data: status,
+          meta: {
+            source: 'analytics-adapter',
+          },
+        };
+      } catch (error) {
+        platform.logger.error('Failed to fetch analytics buffer status', error instanceof Error ? error : new Error(String(error)));
+
+        return reply.code(500).send({
+          ok: false,
+          error: {
+            code: 'ANALYTICS_ERROR',
+            message:
+              error instanceof Error
+                ? error.message
+                : 'Failed to fetch analytics buffer status',
+          },
+        });
+      }
+    });
+  }
+
+  // GET /api/v1/analytics/dlq/status
+  // Get Dead-Letter Queue status (if applicable)
+  const dlqPaths = resolvePaths(basePath, '/analytics/dlq/status');
+  for (const path of dlqPaths) {
+    fastify.get(path, async (_request, reply) => {
+      try {
+        const analytics = platform.analytics;
+
+        const getDlqStatus = analytics.getDlqStatus;
+        if (!getDlqStatus) {
+          fastify.log.debug('Analytics adapter does not implement getDlqStatus()');
+          return reply.code(501).send({
+            ok: false,
+            error: {
+              code: 'ANALYTICS_NOT_IMPLEMENTED',
+              message: 'Analytics adapter does not support DLQ status',
+            },
+          });
+        }
+
+        fastify.log.debug('Fetching analytics DLQ status');
+
+        const status: DlqStatus | null = await restDomainOperationMetrics.observeOperation(
+          'analytics.dlq.status',
+          () => getDlqStatus.call(analytics),
+        );
+
+        if (status === null) {
+          fastify.log.debug('DLQ status not applicable for current analytics backend');
+          return reply.code(501).send({
+            ok: false,
+            error: {
+              code: 'DLQ_NOT_APPLICABLE',
+              message: 'DLQ status not applicable for current analytics backend',
+            },
+          });
+        }
+
+        fastify.log.debug(
+          {
+            failedEvents: status.failedEvents,
+            oldestFailureTs: status.oldestFailureTs,
+          },
+          'Analytics DLQ status fetched successfully'
+        );
+
+        return {
+          ok: true,
+          data: status,
+          meta: {
+            source: 'analytics-adapter',
+          },
+        };
+      } catch (error) {
+        platform.logger.error('Failed to fetch analytics DLQ status', error instanceof Error ? error : new Error(String(error)));
+
+        return reply.code(500).send({
+          ok: false,
+          error: {
+            code: 'ANALYTICS_ERROR',
+            message:
+              error instanceof Error ? error.message : 'Failed to fetch analytics DLQ status',
+          },
+        });
+      }
+    });
+  }
+
+  fastify.log.info('Analytics routes registered');
+}

package/src/routes/cache.ts

@@ -0,0 +1,104 @@
+import { platform } from '@kb-labs/core-runtime';
+/**
+ * @module @kb-labs/rest-api-app/routes/cache
+ * Cache management routes
+ */
+
+import type { FastifyInstance } from 'fastify';
+import type { RestApiConfig } from '@kb-labs/rest-api-core';
+import type { IEntityRegistry } from '@kb-labs/core-registry';
+import { normalizeBasePath } from '../utils/path-helpers';
+import { restDomainOperationMetrics } from '../middleware/metrics.js';
+
+/**
+ * Register cache management routes
+ */
+export async function registerCacheRoutes(
+  server: FastifyInstance,
+  config: RestApiConfig,
+  registry: IEntityRegistry
+): Promise<void> {
+  const basePath = normalizeBasePath(config.basePath);
+
+  /**
+   * POST /api/v1/cache/invalidate
+   * Force cache invalidation and registry refresh
+   */
+  server.post(`${basePath}/cache/invalidate`, async (request, reply) => {
+    const start = Date.now();
+
+    try {
+      // Capture current state
+      const beforeSnapshot = registry.snapshot();
+      const previousRev = beforeSnapshot.rev;
+
+      platform.logger.info('Manual cache invalidation requested', {
+        requestId: request.id,
+        previousRev,
+      });
+      // Force cache invalidation and refresh discovery
+      // This will trigger re-discovery and clear stale cache
+      await restDomainOperationMetrics.observeOperation('cache.invalidate', async () => {
+        await registry.refresh();
+      });
+
+      // Get new state
+      const afterSnapshot = await restDomainOperationMetrics.observeOperation('plugin.registry.snapshot', async () =>
+        registry.snapshot(),
+      );
+      const plugins = await restDomainOperationMetrics.observeOperation('plugin.registry.list', async () =>
+        registry.listPlugins(),
+      );
+
+      const elapsed = Date.now() - start;
+
+      platform.logger.info('Cache invalidated successfully', {
+        requestId: request.id,
+        previousRev,
+        newRev: afterSnapshot.rev,
+        pluginsDiscovered: plugins.length,
+        elapsedMs: elapsed,
+      });
+
+      return reply.code(200).send({
+        ok: true,
+        data: {
+          invalidated: true,
+          timestamp: new Date().toISOString(),
+          previousRev,
+          newRev: afterSnapshot.rev,
+          pluginsDiscovered: plugins.length,
+        },
+        meta: {
+          requestId: request.id,
+          durationMs: elapsed,
+          apiVersion: '1.0.0',
+        },
+      });
+    } catch (error) {
+      const elapsed = Date.now() - start;
+
+      platform.logger.error(
+        'Cache invalidation failed',
+        error instanceof Error ? error : new Error(String(error)),
+        {
+          requestId: request.id as string,
+          elapsedMs: elapsed,
+        }
+      );
+
+      return reply.code(500).send({
+        ok: false,
+        error: {
+          code: 'CACHE_INVALIDATION_FAILED',
+          message: error instanceof Error ? error.message : 'Cache invalidation failed',
+        },
+        meta: {
+          requestId: request.id,
+          durationMs: elapsed,
+          apiVersion: '1.0.0',
+        },
+      });
+    }
+  });
+}

package/src/routes/debug-routes.ts

@@ -0,0 +1,95 @@
+/**
+ * @module @kb-labs/rest-api-app/routes/debug-routes
+ * Debug endpoint to list all registered routes
+ *
+ * GET /api/v1/routes - List all registered routes with methods
+ */
+
+import type { FastifyInstance, RouteOptions } from 'fastify';
+import type { RestApiConfig } from '@kb-labs/rest-api-core';
+import { normalizeBasePath, resolvePaths } from '../utils/path-helpers';
+
+interface RouteInfo {
+  method: string;
+  url: string;
+}
+
+// Store for collected routes (populated via onRoute hook)
+const collectedRoutes: RouteInfo[] = [];
+const seenRoutes = new Set<string>();
+
+/**
+ * Hook to collect routes as they are registered
+ */
+function collectRoute(routeOptions: RouteOptions): void {
+  const methods = Array.isArray(routeOptions.method)
+    ? routeOptions.method
+    : [routeOptions.method];
+
+  for (const method of methods) {
+    // Skip HEAD (auto-generated for GET routes) and internal routes
+    if (method === 'HEAD') {continue;}
+
+    const url = routeOptions.url;
+    const key = `${method}:${url}`;
+
+    if (!seenRoutes.has(key)) {
+      seenRoutes.add(key);
+      collectedRoutes.push({ method, url });
+    }
+  }
+}
+
+/**
+ * Register the onRoute hook to collect routes
+ * Must be called early, before other routes are registered
+ */
+export function registerRouteCollector(fastify: FastifyInstance): void {
+  fastify.addHook('onRoute', collectRoute);
+}
+
+/**
+ * Register debug routes endpoint
+ */
+export async function registerDebugRoutes(
+  fastify: FastifyInstance,
+  config: RestApiConfig
+): Promise<void> {
+  const basePath = normalizeBasePath(config.basePath);
+  const routesPaths = resolvePaths(basePath, '/routes');
+
+  for (const path of routesPaths) {
+    fastify.get(path, async (_request, reply) => {
+      // Filter to only show /api/v1 routes (skip duplicates without prefix)
+      let routes = collectedRoutes.filter(r => r.url.startsWith('/api/'));
+
+      // If no API routes found, show all (fallback)
+      if (routes.length === 0) {
+        routes = [...collectedRoutes];
+      }
+
+      // Sort routes by URL, then by method
+      routes.sort((a, b) => {
+        const urlCompare = a.url.localeCompare(b.url);
+        if (urlCompare !== 0) {return urlCompare;}
+        return a.method.localeCompare(b.method);
+      });
+
+      // Get raw printRoutes for debugging (optional)
+      let raw: string | null = null;
+      try {
+        raw = fastify.printRoutes({ commonPrefix: false });
+      } catch {
+        // Ignore if not available
+      }
+
+      return reply.send({
+        schema: 'kb.routes/1',
+        ts: new Date().toISOString(),
+        count: routes.length,
+        routes,
+        raw,
+      });
+    });
+  }
+}

package/src/routes/events.ts

@@ -0,0 +1,115 @@
+import type { FastifyInstance } from 'fastify';
+import type { RestApiConfig } from '@kb-labs/rest-api-core';
+import type { IEntityRegistry, SystemHealthSnapshot } from '@kb-labs/core-registry';
+import type { ReadinessState } from './readiness';
+import { isReady, resolveReadinessReason } from './readiness';
+import type { EventHub, BroadcastEvent } from '../events/hub';
+import { metricsCollector } from '../middleware/metrics.js';
+import { buildRegistrySseAuthHook } from '../utils/sse-auth';
+
+export async function registerEventRoutes(
+  server: FastifyInstance,
+  basePath: string,
+  registry: IEntityRegistry,
+  readiness: ReadinessState,
+  eventHub: EventHub,
+  config: RestApiConfig
+): Promise<void> {
+  const endpoint = `${basePath}/events/registry`;
+  const authHook = buildRegistrySseAuthHook(config);
+
+  server.route({
+    method: 'GET',
+    url: endpoint,
+    onRequest: authHook ? [authHook] : undefined,
+    handler: async (request, reply) => {
+      // Tell Fastify we're manually managing the response
+      reply.hijack();
+
+      // Explicit CORS headers for EventSource (browser requires these before opening connection)
+      const origin = request.headers.origin;
+      if (origin === 'http://localhost:3000' || origin === 'http://localhost:5173') {
+        reply.raw.setHeader('Access-Control-Allow-Origin', origin);
+        reply.raw.setHeader('Access-Control-Allow-Credentials', 'true');
+      }
+
+      reply.raw.setHeader('Content-Type', 'text/event-stream');
+      reply.raw.setHeader('Cache-Control', 'no-cache, no-transform');
+      reply.raw.setHeader('Connection', 'keep-alive');
+      reply.raw.flushHeaders?.();
+      reply.raw.write(': connected\n\n');
+
+      const send = (event: BroadcastEvent) => {
+        reply.raw.write(`event: ${event.type}\n`);
+        reply.raw.write(`data: ${JSON.stringify(event)}\n\n`);
+      };
+
+      const unsubscribe = eventHub.subscribe(send);
+
+      const snapshot = registry.snapshot();
+      const checksumAlgorithm = snapshot.checksumAlgorithm === 'sha256' ? 'sha256' : undefined;
+      send({
+        type: 'registry',
+        rev: snapshot.rev,
+        generatedAt: snapshot.generatedAt,
+        partial: snapshot.partial,
+        stale: snapshot.stale,
+        expiresAt: snapshot.expiresAt ?? null,
+        ttlMs: snapshot.ttlMs ?? null,
+        checksum: snapshot.checksum ?? undefined,
+        checksumAlgorithm,
+        previousChecksum: snapshot.previousChecksum ?? null,
+      });
+
+      const healthPromise = registry
+        .getSystemHealth()
+        .then((health: SystemHealthSnapshot) => {
+          const ready = isReady(readiness);
+          const reason = resolveReadinessReason(readiness);
+          const pluginSnapshot = metricsCollector.getLastPluginMountSnapshot();
+          const redisStatus = (registry as any).getRedisStatus?.();
+          send({
+            type: 'health',
+            status: health.status,
+            ts: health.ts,
+            ready,
+            reason,
+            registryPartial: readiness.registryPartial,
+            registryStale: readiness.registryStale,
+            registryLoaded: readiness.registryLoaded,
+            pluginMountInProgress: readiness.pluginMountInProgress,
+            pluginRoutesMounted: readiness.pluginRoutesMounted,
+            pluginsMounted: pluginSnapshot?.succeeded ?? 0,
+            pluginsFailed: pluginSnapshot?.failed ?? 0,
+            lastPluginMountTs: readiness.lastPluginMountTs ?? null,
+            pluginRoutesLastDurationMs: readiness.pluginRoutesLastDurationMs ?? null,
+            redisEnabled: redisStatus?.enabled ?? false,
+            redisHealthy: redisStatus?.healthy ?? true,
+            redisStates: redisStatus?.roles,
+          });
+        })
+        .catch((error: unknown) => {
+          if ((request as any).kbLogger) {
+            (request as any).kbLogger.warn('Failed to fetch system health for SSE client', { err: error });
+          }
+        });
+
+      await new Promise<void>((resolve) => {
+        request.raw.on('close', () => {
+          unsubscribe();
+          reply.raw.end();
+          resolve();
+        });
+        // In inject/test mode, the socket is not a real TCP socket and 'close' may not fire.
+        // Wait for health fetch to complete before resolving so health event is included in response.
+        if (request.raw.socket && !(request.raw.socket as any).writable) {
+          void healthPromise.then(() => {
+            unsubscribe();
+            reply.raw.end();
+            resolve();
+          });
+        }
+      });
+    },
+  });
+}