@kb-labs/rest-api-app 1.3.0

package/src/routes/__tests__/cache.spec.ts

@@ -0,0 +1,264 @@
+import { beforeEach, describe, expect, it, vi, afterEach } from 'vitest';
+import Fastify from 'fastify';
+import type { IEntityRegistry, RegistrySnapshot } from '@kb-labs/core-registry';
+import type { RestApiConfig } from '@kb-labs/rest-api-core';
+import { registerCacheRoutes } from '../cache';
+
+const BASE_CONFIG: RestApiConfig = {
+  port: 3000,
+  basePath: '/api/v1',
+  apiVersion: 'test',
+  cors: {
+    origins: [],
+    allowCredentials: true,
+    profile: 'dev',
+  },
+  plugins: [],
+  mockMode: false,
+};
+
+function createMockSnapshot(rev: number): RegistrySnapshot {
+  return {
+    schema: 'kb.registry/1',
+    rev,
+    version: '1.0.0',
+    generatedAt: new Date().toISOString(),
+    expiresAt: new Date(Date.now() + 60_000).toISOString(),
+    ttlMs: 60_000,
+    partial: false,
+    stale: false,
+    source: { platformVersion: 'test', cwd: process.cwd() },
+    corrupted: false,
+    plugins: [],
+    manifests: [],
+    ts: Date.now(),
+  };
+}
+
+describe('registerCacheRoutes', () => {
+  let app: ReturnType<typeof Fastify>;
+  let mockCliApi: IEntityRegistry;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    app = Fastify({ logger: false });
+
+    mockCliApi = {
+      snapshot: vi.fn(),
+      refresh: vi.fn(),
+      listPlugins: vi.fn(),
+    } as unknown as IEntityRegistry;
+
+    await registerCacheRoutes(app, BASE_CONFIG, mockCliApi);
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  describe('POST /api/v1/cache/invalidate', () => {
+    it('successfully invalidates cache and refreshes registry', async () => {
+      const beforeSnapshot = createMockSnapshot(1);
+      const afterSnapshot = createMockSnapshot(2);
+      const plugins = [
+        { id: '@kb-labs/plugin-1', version: '1.0.0', source: { kind: 'local' as const, path: '/plugins/plugin-1' } },
+        { id: '@kb-labs/plugin-2', version: '1.0.0', source: { kind: 'local' as const, path: '/plugins/plugin-2' } },
+      ];
+
+      vi.mocked(mockCliApi.snapshot)
+        .mockReturnValueOnce(beforeSnapshot)
+        .mockReturnValueOnce(afterSnapshot);
+      vi.mocked(mockCliApi.refresh).mockResolvedValue(undefined);
+      vi.mocked(mockCliApi.listPlugins).mockResolvedValue(plugins);
+
+      const response = await app.inject({
+        method: 'POST',
+        url: '/api/v1/cache/invalidate',
+      });
+
+      expect(response.statusCode).toBe(200);
+      const payload = response.json();
+
+      expect(payload.ok).toBe(true);
+      expect(payload.data.invalidated).toBe(true);
+      expect(payload.data.previousRev).toBe(1);
+      expect(payload.data.newRev).toBe(2);
+      expect(payload.data.pluginsDiscovered).toBe(2);
+      expect(payload.data.timestamp).toBeDefined();
+      expect(payload.meta.requestId).toBeDefined();
+      expect(payload.meta.durationMs).toBeGreaterThanOrEqual(0);
+      expect(payload.meta.apiVersion).toBe('1.0.0');
+
+      expect(mockCliApi.snapshot).toHaveBeenCalledTimes(2);
+      expect(mockCliApi.refresh).toHaveBeenCalledTimes(1);
+      expect(mockCliApi.listPlugins).toHaveBeenCalledTimes(1);
+    });
+
+    it('returns previous and new revision numbers', async () => {
+      const beforeSnapshot = createMockSnapshot(42);
+      const afterSnapshot = createMockSnapshot(43);
+
+      vi.mocked(mockCliApi.snapshot)
+        .mockReturnValueOnce(beforeSnapshot)
+        .mockReturnValueOnce(afterSnapshot);
+      vi.mocked(mockCliApi.refresh).mockResolvedValue(undefined);
+      vi.mocked(mockCliApi.listPlugins).mockResolvedValue([]);
+
+      const response = await app.inject({
+        method: 'POST',
+        url: '/api/v1/cache/invalidate',
+      });
+
+      expect(response.statusCode).toBe(200);
+      const payload = response.json();
+      expect(payload.data.previousRev).toBe(42);
+      expect(payload.data.newRev).toBe(43);
+    });
+
+    it('includes plugin registry count', async () => {
+      const snapshot = createMockSnapshot(1);
+      const plugins = Array.from({ length: 15 }, (_, i) => ({
+        id: `@kb-labs/plugin-${i}`,
+        version: '1.0.0',
+        source: { kind: 'local' as const, path: `/plugins/plugin-${i}` },
+      }));
+
+      vi.mocked(mockCliApi.snapshot).mockReturnValue(snapshot);
+      vi.mocked(mockCliApi.refresh).mockResolvedValue(undefined);
+      vi.mocked(mockCliApi.listPlugins).mockResolvedValue(plugins);
+
+      const response = await app.inject({
+        method: 'POST',
+        url: '/api/v1/cache/invalidate',
+      });
+
+      expect(response.statusCode).toBe(200);
+      const payload = response.json();
+      expect(payload.data.pluginsDiscovered).toBe(15);
+    });
+
+    it('handles cache refresh errors gracefully', async () => {
+      const beforeSnapshot = createMockSnapshot(1);
+      const error = new Error('Registry refresh failed');
+
+      vi.mocked(mockCliApi.snapshot).mockReturnValue(beforeSnapshot);
+      vi.mocked(mockCliApi.refresh).mockRejectedValue(error);
+
+      const response = await app.inject({
+        method: 'POST',
+        url: '/api/v1/cache/invalidate',
+      });
+
+      expect(response.statusCode).toBe(500);
+      const payload = response.json();
+
+      expect(payload.ok).toBe(false);
+      expect(payload.error.code).toBe('CACHE_INVALIDATION_FAILED');
+      expect(payload.error.message).toBe('Registry refresh failed');
+      expect(payload.meta.requestId).toBeDefined();
+      expect(payload.meta.durationMs).toBeGreaterThanOrEqual(0);
+
+      expect(mockCliApi.refresh).toHaveBeenCalledTimes(1);
+      expect(mockCliApi.listPlugins).not.toHaveBeenCalled();
+    });
+
+    it('handles non-Error exceptions', async () => {
+      const beforeSnapshot = createMockSnapshot(1);
+
+      vi.mocked(mockCliApi.snapshot).mockReturnValue(beforeSnapshot);
+      vi.mocked(mockCliApi.refresh).mockRejectedValue('String error');
+
+      const response = await app.inject({
+        method: 'POST',
+        url: '/api/v1/cache/invalidate',
+      });
+
+      expect(response.statusCode).toBe(500);
+      const payload = response.json();
+
+      expect(payload.ok).toBe(false);
+      expect(payload.error.code).toBe('CACHE_INVALIDATION_FAILED');
+      expect(payload.error.message).toBe('Cache invalidation failed');
+    });
+
+    it('handles snapshot() errors', async () => {
+      vi.mocked(mockCliApi.snapshot).mockImplementation(() => {
+        throw new Error('Registry snapshot unavailable');
+      });
+
+      const response = await app.inject({
+        method: 'POST',
+        url: '/api/v1/cache/invalidate',
+      });
+
+      expect(response.statusCode).toBe(500);
+      const payload = response.json();
+      expect(payload.ok).toBe(false);
+      expect(payload.error.message).toBe('Registry snapshot unavailable');
+    });
+
+    it('tracks request timing in metadata', async () => {
+      const snapshot = createMockSnapshot(1);
+
+      vi.mocked(mockCliApi.snapshot).mockReturnValue(snapshot);
+      vi.mocked(mockCliApi.refresh).mockImplementation(async () => {
+        await new Promise((resolve) => {
+          setTimeout(resolve, 10);
+        });
+      });
+      vi.mocked(mockCliApi.listPlugins).mockResolvedValue([]);
+
+      const response = await app.inject({
+        method: 'POST',
+        url: '/api/v1/cache/invalidate',
+      });
+
+      expect(response.statusCode).toBe(200);
+      const payload = response.json();
+      expect(payload.meta.durationMs).toBeGreaterThanOrEqual(10);
+    });
+
+    it('includes timestamp in ISO format', async () => {
+      const snapshot = createMockSnapshot(1);
+
+      vi.mocked(mockCliApi.snapshot).mockReturnValue(snapshot);
+      vi.mocked(mockCliApi.refresh).mockResolvedValue(undefined);
+      vi.mocked(mockCliApi.listPlugins).mockResolvedValue([]);
+
+      const before = new Date();
+      const response = await app.inject({
+        method: 'POST',
+        url: '/api/v1/cache/invalidate',
+      });
+      const after = new Date();
+
+      expect(response.statusCode).toBe(200);
+      const payload = response.json();
+      const timestamp = new Date(payload.data.timestamp);
+
+      expect(timestamp).toBeInstanceOf(Date);
+      expect(timestamp.getTime()).toBeGreaterThanOrEqual(before.getTime());
+      expect(timestamp.getTime()).toBeLessThanOrEqual(after.getTime());
+    });
+
+    it('handles empty plugin list after refresh', async () => {
+      const beforeSnapshot = createMockSnapshot(1);
+      const afterSnapshot = createMockSnapshot(2);
+
+      vi.mocked(mockCliApi.snapshot)
+        .mockReturnValueOnce(beforeSnapshot)
+        .mockReturnValueOnce(afterSnapshot);
+      vi.mocked(mockCliApi.refresh).mockResolvedValue(undefined);
+      vi.mocked(mockCliApi.listPlugins).mockResolvedValue([]);
+
+      const response = await app.inject({
+        method: 'POST',
+        url: '/api/v1/cache/invalidate',
+      });
+
+      expect(response.statusCode).toBe(200);
+      const payload = response.json();
+      expect(payload.data.pluginsDiscovered).toBe(0);
+    });
+  });
+});

package/src/routes/__tests__/events.spec.ts

@@ -0,0 +1,434 @@
+import { beforeEach, describe, expect, it, vi, afterEach } from 'vitest';
+import Fastify from 'fastify';
+import type { IEntityRegistry, RegistrySnapshot, SystemHealthSnapshot } from '@kb-labs/core-registry';
+import type { RestApiConfig } from '@kb-labs/rest-api-core';
+import type { EventHub, BroadcastEvent } from '../../events/hub';
+import type { ReadinessState } from '../readiness';
+import { registerEventRoutes } from '../events';
+
+// Mock dependencies
+vi.mock('../../middleware/metrics', () => ({
+  metricsCollector: {
+    getLastPluginMountSnapshot: vi.fn(() => ({
+      succeeded: 5,
+      failed: 1,
+    })),
+  },
+}));
+
+vi.mock('../../utils/sse-auth', () => ({
+  buildRegistrySseAuthHook: vi.fn(() => null),
+}));
+
+const BASE_CONFIG: RestApiConfig = {
+  port: 3000,
+  basePath: '/api/v1',
+  apiVersion: 'test',
+  cors: {
+    origins: [],
+    allowCredentials: true,
+    profile: 'dev',
+  },
+  plugins: [],
+  mockMode: false,
+};
+
+function createMockSnapshot(): RegistrySnapshot {
+  return {
+    schema: 'kb.registry/1',
+    rev: 42,
+    version: '1.0.0',
+    generatedAt: new Date().toISOString(),
+    expiresAt: new Date(Date.now() + 60_000).toISOString(),
+    ttlMs: 60_000,
+    partial: false,
+    stale: false,
+    source: { platformVersion: 'test', cwd: process.cwd() },
+    corrupted: false,
+    plugins: [],
+    manifests: [],
+    ts: Date.now(),
+    checksum: 'abc123',
+    checksumAlgorithm: 'sha256',
+    previousChecksum: 'def456',
+  };
+}
+
+function createMockHealthSnapshot(): SystemHealthSnapshot {
+  return {
+    schema: 'kb.health/1',
+    ts: new Date().toISOString(),
+    uptimeSec: 42,
+    version: {
+      kbLabs: '1.0.0',
+      rest: '1.0.0',
+    },
+    registry: {
+      total: 5,
+      withRest: 3,
+      withStudio: 2,
+      errors: 0,
+      generatedAt: new Date().toISOString(),
+      expiresAt: new Date(Date.now() + 60_000).toISOString(),
+      partial: false,
+      stale: false,
+    },
+    status: 'healthy',
+    components: [],
+  };
+}
+
+function createMockReadinessState(): ReadinessState {
+  return {
+    cliApiInitialized: true,
+    registryLoaded: true,
+    registryPartial: false,
+    registryStale: false,
+    pluginRoutesMounted: true,
+    pluginMountInProgress: false,
+    pluginRoutesCount: 5,
+    pluginRouteErrors: 0,
+    pluginRouteFailures: [],
+    lastPluginMountTs: new Date().toISOString(),
+    pluginRoutesLastDurationMs: 128,
+    redisEnabled: false,
+    redisConnected: false,
+    redisStates: {
+      publisher: null,
+      subscriber: null,
+      cache: null,
+    },
+  };
+}
+
+describe('registerEventRoutes', () => {
+  let app: ReturnType<typeof Fastify>;
+  let mockCliApi: IEntityRegistry;
+  let mockEventHub: EventHub;
+  let readiness: ReadinessState;
+  let subscribers: Array<(event: BroadcastEvent) => void> = [];
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    subscribers = [];
+    app = Fastify({ logger: false });
+
+    mockCliApi = {
+      snapshot: vi.fn(() => createMockSnapshot()),
+      getSystemHealth: vi.fn(() => Promise.resolve(createMockHealthSnapshot())),
+      getRedisStatus: vi.fn(() => ({
+        enabled: false,
+        healthy: true,
+        roles: {
+          publisher: null,
+          subscriber: null,
+          cache: null,
+        },
+      })),
+    } as unknown as IEntityRegistry;
+
+    mockEventHub = {
+      subscribe: vi.fn((callback: (event: BroadcastEvent) => void) => {
+        subscribers.push(callback);
+        return () => {
+          const index = subscribers.indexOf(callback);
+          if (index > -1) {subscribers.splice(index, 1);}
+        };
+      }),
+      publish: vi.fn((event: BroadcastEvent) => {
+        subscribers.forEach((sub) => sub(event));
+      }),
+    } as any;
+
+    readiness = createMockReadinessState();
+
+    await registerEventRoutes(
+      app,
+      '/api/v1',
+      mockCliApi,
+      readiness,
+      mockEventHub,
+      BASE_CONFIG
+    );
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  describe('GET /api/v1/events/registry', () => {
+    it('returns SSE stream with correct headers', async () => {
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/events/registry',
+      });
+
+      // SSE uses response hijacking, so status code is 0
+      // Check headers instead
+      expect(response.headers['content-type']).toBe('text/event-stream');
+      expect(response.headers['cache-control']).toBe('no-cache, no-transform');
+      expect(response.headers['connection']).toBe('keep-alive');
+    });
+
+    it('sends initial registry event', async () => {
+      const snapshot = createMockSnapshot();
+      vi.mocked(mockCliApi.snapshot).mockReturnValue(snapshot);
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/events/registry',
+      });
+
+      const body = response.body;
+      expect(body).toContain('event: registry');
+      expect(body).toContain('"rev":42');
+      expect(body).toContain('"partial":false');
+      expect(body).toContain('"stale":false');
+      expect(body).toContain('"checksum":"abc123"');
+      expect(body).toContain('"checksumAlgorithm":"sha256"');
+    });
+
+    it('sends health event after registry event', async () => {
+      const health = createMockHealthSnapshot();
+      vi.mocked(mockCliApi.getSystemHealth).mockResolvedValue(health);
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/events/registry',
+      });
+
+      // Wait for async health fetch
+      await new Promise((resolve) => {
+        setTimeout(resolve, 10);
+      });
+
+      const body = response.body;
+      expect(body).toContain('event: health');
+      expect(body).toContain('"status":"healthy"');
+      expect(body).toContain('"ready":true');
+      expect(body).toContain('"pluginRoutesMounted":true');
+    });
+
+    it('subscribes to event hub', async () => {
+      await app.inject({
+        method: 'GET',
+        url: '/api/v1/events/registry',
+      });
+
+      expect(mockEventHub.subscribe).toHaveBeenCalledTimes(1);
+      expect(mockEventHub.subscribe).toHaveBeenCalledWith(expect.any(Function));
+    });
+
+    it('includes Redis status in health event when Redis is enabled', async () => {
+      vi.mocked((mockCliApi as any).getRedisStatus).mockReturnValue({
+        enabled: true,
+        healthy: true,
+        roles: {
+          publisher: 'ready',
+          subscriber: 'ready',
+          cache: 'ready',
+        },
+      });
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/events/registry',
+      });
+
+      await new Promise((resolve) => {
+        setTimeout(resolve, 10);
+      });
+
+      const body = response.body;
+      expect(body).toContain('"redisEnabled":true');
+      expect(body).toContain('"redisHealthy":true');
+      expect(body).toContain('"publisher":"ready"');
+    });
+
+    it('includes plugin mount statistics in health event', async () => {
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/events/registry',
+      });
+
+      await new Promise((resolve) => {
+        setTimeout(resolve, 10);
+      });
+
+      const body = response.body;
+      expect(body).toContain('"pluginsMounted":5');
+      expect(body).toContain('"pluginsFailed":1');
+      expect(body).toContain('"pluginRoutesLastDurationMs":128');
+    });
+
+    it('includes readiness state in health event', async () => {
+      readiness.registryPartial = true;
+      readiness.pluginMountInProgress = true;
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/events/registry',
+      });
+
+      await new Promise((resolve) => {
+        setTimeout(resolve, 10);
+      });
+
+      const body = response.body;
+      expect(body).toContain('"registryPartial":true');
+      expect(body).toContain('"pluginMountInProgress":true');
+      expect(body).toContain('"reason":"plugin_mount_in_progress"');
+    });
+
+    it('handles system health fetch errors gracefully', async () => {
+      vi.mocked(mockCliApi.getSystemHealth).mockRejectedValue(
+        new Error('Health fetch failed')
+      );
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/events/registry',
+      });
+
+      await new Promise((resolve) => {
+        setTimeout(resolve, 10);
+      });
+
+      // Should still send registry event, just not health event
+      const body = response.body;
+      expect(body).toContain('event: registry');
+      // Should not crash
+    });
+
+    it('sets CORS headers for localhost:3000 origin', async () => {
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/events/registry',
+        headers: {
+          origin: 'http://localhost:3000',
+        },
+      });
+
+      expect(response.headers['access-control-allow-origin']).toBe(
+        'http://localhost:3000'
+      );
+      expect(response.headers['access-control-allow-credentials']).toBe('true');
+    });
+
+    it('sets CORS headers for localhost:5173 origin (Vite dev)', async () => {
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/events/registry',
+        headers: {
+          origin: 'http://localhost:5173',
+        },
+      });
+
+      expect(response.headers['access-control-allow-origin']).toBe(
+        'http://localhost:5173'
+      );
+      expect(response.headers['access-control-allow-credentials']).toBe('true');
+    });
+
+    it('does not set CORS headers for other origins', async () => {
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/events/registry',
+        headers: {
+          origin: 'http://evil.com',
+        },
+      });
+
+      expect(response.headers['access-control-allow-origin']).toBeUndefined();
+    });
+
+    it('handles snapshot with missing checksum fields', async () => {
+      const snapshot = createMockSnapshot();
+      delete (snapshot as any).checksum;
+      delete (snapshot as any).checksumAlgorithm;
+      delete (snapshot as any).previousChecksum;
+
+      vi.mocked(mockCliApi.snapshot).mockReturnValue(snapshot);
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/events/registry',
+      });
+
+      const body = response.body;
+      expect(body).toContain('event: registry');
+      expect(body).not.toContain('"checksum"');
+      expect(body).not.toContain('"checksumAlgorithm"');
+    });
+
+    it('handles snapshot with null expiration fields', async () => {
+      const snapshot = createMockSnapshot();
+      (snapshot as any).expiresAt = null;
+      (snapshot as any).ttlMs = null;
+
+      vi.mocked(mockCliApi.snapshot).mockReturnValue(snapshot);
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/events/registry',
+      });
+
+      const body = response.body;
+      expect(body).toContain('"expiresAt":null');
+      expect(body).toContain('"ttlMs":null');
+    });
+
+    it('handles missing getRedisStatus method gracefully', async () => {
+      delete (mockCliApi as any).getRedisStatus;
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/events/registry',
+      });
+
+      await new Promise((resolve) => {
+        setTimeout(resolve, 10);
+      });
+
+      const body = response.body;
+      expect(body).toContain('"redisEnabled":false');
+      expect(body).toContain('"redisHealthy":true');
+    });
+
+    it('handles missing plugin mount snapshot', async () => {
+      const { metricsCollector } = await import('../../middleware/metrics');
+      vi.mocked(metricsCollector.getLastPluginMountSnapshot).mockReturnValue(null);
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/events/registry',
+      });
+
+      await new Promise((resolve) => {
+        setTimeout(resolve, 10);
+      });
+
+      const body = response.body;
+      expect(body).toContain('"pluginsMounted":0');
+      expect(body).toContain('"pluginsFailed":0');
+    });
+
+    it('handles null lastPluginMountTs', async () => {
+      readiness.lastPluginMountTs = null;
+      readiness.pluginRoutesLastDurationMs = null;
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/events/registry',
+      });
+
+      await new Promise((resolve) => {
+        setTimeout(resolve, 10);
+      });
+
+      const body = response.body;
+      expect(body).toContain('"lastPluginMountTs":null');
+      expect(body).toContain('"pluginRoutesLastDurationMs":null');
+    });
+  });
+});