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

package/src/routes/analytics.ts

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

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

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

@@ -1,115 +0,0 @@
-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();
-          });
-        }
-      });
-    },
-  });
-}