@kb-labs/rest-api-app 1.3.0

package/src/events/hub.ts

@@ -0,0 +1,60 @@
+import { EventEmitter } from 'node:events';
+
+export type RegistryBroadcast = {
+  type: 'registry';
+  rev: number;
+  generatedAt?: string;
+  partial?: boolean;
+  stale?: boolean;
+  expiresAt?: string | null;
+  ttlMs?: number | null;
+  checksum?: string;
+  checksumAlgorithm?: 'sha256';
+  previousChecksum?: string | null;
+};
+
+export type HealthBroadcast = {
+  type: 'health';
+  status: 'healthy' | 'degraded';
+  ts: string;
+  ready: boolean;
+  reason?: string;
+  registryPartial?: boolean;
+  registryStale?: boolean;
+  registryLoaded?: boolean;
+  pluginMountInProgress?: boolean;
+  pluginRoutesMounted?: boolean;
+  pluginsMounted?: number;
+  pluginsFailed?: number;
+  lastPluginMountTs?: string | null;
+  pluginRoutesLastDurationMs?: number | null;
+  redisEnabled?: boolean;
+  redisHealthy?: boolean;
+  redisStates?: {
+    publisher: string | null;
+    subscriber: string | null;
+    cache: string | null;
+  };
+};
+
+export type BroadcastEvent = RegistryBroadcast | HealthBroadcast;
+
+export class EventHub {
+  private emitter: EventEmitter;
+
+  constructor() {
+    this.emitter = new EventEmitter();
+    this.emitter.setMaxListeners(0);
+  }
+
+  publish(event: BroadcastEvent): void {
+    this.emitter.emit('broadcast', event);
+  }
+
+  subscribe(handler: (event: BroadcastEvent) => void): () => void {
+    this.emitter.on('broadcast', handler);
+    return () => {
+      this.emitter.off('broadcast', handler);
+    };
+  }
+}

package/src/events/index.ts

@@ -0,0 +1 @@
+export { EventHub, type BroadcastEvent, type RegistryBroadcast, type HealthBroadcast } from './hub';

package/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @module @kb-labs/rest-api-app
+ * REST API application entry point
+ */
+
+import { bootstrap } from './bootstrap';
+
+// process.cwd() = workspace root when launched via `node ./platform/kb-labs-rest-api/.../dist/index.js`
+bootstrap(process.cwd()).catch((error) => {
+  console.error('Failed to start server:', error);
+  process.exit(1);
+});
+

package/src/manifest.ts

@@ -0,0 +1,21 @@
+import type { ServiceManifest } from '@kb-labs/plugin-contracts';
+
+export const manifest: ServiceManifest = {
+  schema: 'kb.service/1',
+  id: 'rest',
+  name: 'REST API',
+  version: '1.2.0',
+  description: 'Platform REST API daemon — routes, plugin execution, OpenAPI',
+  runtime: {
+    entry: 'dist/index.js',
+    port: 5050,
+    healthCheck: '/api/v1/health',
+  },
+  dependsOn: ['qdrant'],
+  env: {
+    PORT: { description: 'HTTP port', default: '5050' },
+    NODE_ENV: { description: 'Environment mode', default: 'development' },
+  },
+};
+
+export default manifest;

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

@@ -0,0 +1,184 @@
+/**
+ * @module @kb-labs/rest-api-app/middleware/__tests__/cache
+ *
+ * Tests for cache middleware (ETag/Last-Modified support).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import Fastify from 'fastify';
+
+import { generateETag, registerCacheMiddleware } from '../cache';
+
+describe('generateETag', () => {
+  it('should generate consistent ETag for same string content', () => {
+    const content = 'Hello, World!';
+    const etag1 = generateETag(content);
+    const etag2 = generateETag(content);
+
+    expect(etag1).toBe(etag2);
+    expect(etag1).toMatch(/^"[a-f0-9]{16}"$/);
+  });
+
+  it('should generate different ETags for different content', () => {
+    const etag1 = generateETag('Hello');
+    const etag2 = generateETag('World');
+
+    expect(etag1).not.toBe(etag2);
+  });
+
+  it('should handle object content by stringifying', () => {
+    const obj = { foo: 'bar', num: 42 };
+    const etag = generateETag(obj);
+
+    expect(etag).toMatch(/^"[a-f0-9]{16}"$/);
+
+    // Same object should produce same ETag
+    const etag2 = generateETag({ foo: 'bar', num: 42 });
+    expect(etag).toBe(etag2);
+  });
+
+  it('should handle Buffer content', () => {
+    const buffer = Buffer.from('Hello, Buffer!');
+    const etag = generateETag(buffer);
+
+    expect(etag).toMatch(/^"[a-f0-9]{16}"$/);
+  });
+
+  it('should handle empty string', () => {
+    const etag = generateETag('');
+    expect(etag).toMatch(/^"[a-f0-9]{16}"$/);
+  });
+
+  it('should handle empty object', () => {
+    const etag = generateETag({});
+    expect(etag).toMatch(/^"[a-f0-9]{16}"$/);
+  });
+});
+
+describe('registerCacheMiddleware', () => {
+  let app: ReturnType<typeof Fastify>;
+
+  beforeEach(async () => {
+    app = Fastify({ logger: false });
+    registerCacheMiddleware(app);
+
+    // Add test route
+    app.get('/test', async () => {
+      return { message: 'Hello, World!' };
+    });
+
+    app.post('/test', async () => {
+      return { created: true };
+    });
+
+    await app.ready();
+  });
+
+  describe('ETag handling', () => {
+    it('should add ETag header to GET responses when If-None-Match is provided', async () => {
+      const response = await app.inject({
+        method: 'GET',
+        url: '/test',
+        headers: { 'if-none-match': '"invalid-etag"' },
+      });
+
+      expect(response.statusCode).toBe(200);
+      expect(response.headers.etag).toMatch(/^"[a-f0-9]{16}"$/);
+    });
+
+    it('should return 304 when ETag matches', async () => {
+      // First request to get the ETag
+      const firstResponse = await app.inject({
+        method: 'GET',
+        url: '/test',
+        headers: { 'if-none-match': '"dummy"' },
+      });
+
+      const etag = firstResponse.headers.etag as string;
+      expect(etag).toBeDefined();
+
+      // Second request with matching ETag
+      const secondResponse = await app.inject({
+        method: 'GET',
+        url: '/test',
+        headers: { 'if-none-match': etag },
+      });
+
+      expect(secondResponse.statusCode).toBe(304);
+      // Note: Fastify inject may still include body in response object,
+      // but HTTP clients won't receive body content for 304 responses
+    });
+
+    it('should return 304 when weak ETag matches', async () => {
+      // First request to get the ETag
+      const firstResponse = await app.inject({
+        method: 'GET',
+        url: '/test',
+        headers: { 'if-none-match': '"dummy"' },
+      });
+
+      const etag = firstResponse.headers.etag as string;
+
+      // Second request with weak ETag
+      const secondResponse = await app.inject({
+        method: 'GET',
+        url: '/test',
+        headers: { 'if-none-match': `W/${etag}` },
+      });
+
+      expect(secondResponse.statusCode).toBe(304);
+    });
+
+    it('should not add ETag to POST requests', async () => {
+      const response = await app.inject({
+        method: 'POST',
+        url: '/test',
+        headers: { 'if-none-match': '"some-etag"' },
+      });
+
+      expect(response.statusCode).toBe(200);
+      expect(response.headers.etag).toBeUndefined();
+    });
+  });
+
+  describe('Last-Modified handling', () => {
+    it('should add Last-Modified header when If-Modified-Since is provided', async () => {
+      const response = await app.inject({
+        method: 'GET',
+        url: '/test',
+        headers: { 'if-modified-since': 'Wed, 01 Jan 2020 00:00:00 GMT' },
+      });
+
+      expect(response.headers['last-modified']).toBeDefined();
+    });
+  });
+
+  describe('streaming responses', () => {
+    it('should skip cache for SSE responses', async () => {
+      const sseApp = Fastify({ logger: false });
+      registerCacheMiddleware(sseApp as any);
+
+      sseApp.get('/events', async (request, reply) => {
+        reply.header('content-type', 'text/event-stream');
+        return 'data: test\n\n';
+      });
+
+      await sseApp.ready();
+
+      const response = await sseApp.inject({
+        method: 'GET',
+        url: '/events',
+        headers: { 'if-none-match': '"some-etag"' },
+      });
+
+      expect(response.statusCode).toBe(200);
+      expect(response.headers.etag).toBeUndefined();
+
+      await sseApp.close();
+    });
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+});

package/src/middleware/__tests__/envelope.spec.ts

@@ -0,0 +1,268 @@
+/**
+ * @module @kb-labs/rest-api-app/middleware/__tests__/envelope
+ *
+ * Tests for response envelope middleware.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import Fastify from 'fastify';
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import type { RestApiConfig } from '@kb-labs/rest-api-core';
+import { registerEnvelopeMiddleware } from '../envelope';
+
+const TEST_CONFIG: RestApiConfig = {
+  port: 3000,
+  basePath: '/api/v1',
+  apiVersion: '1.0.0',
+  cors: {
+    origins: [],
+    allowCredentials: true,
+    profile: 'dev',
+  },
+  plugins: [],
+  mockMode: false,
+};
+
+describe('registerEnvelopeMiddleware', () => {
+  let app: ReturnType<typeof Fastify>;
+
+  beforeEach(async () => {
+    app = Fastify({ logger: false });
+    registerEnvelopeMiddleware(app, TEST_CONFIG);
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  describe('successful responses', () => {
+    it('should wrap JSON response in envelope', async () => {
+      app.get('/test', async () => {
+        return { message: 'Hello' };
+      });
+
+      await app.ready();
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/test',
+      });
+
+      expect(response.statusCode).toBe(200);
+
+      const body = response.json();
+      expect(body.ok).toBe(true);
+      expect(body.data).toEqual({ message: 'Hello' });
+      expect(body.meta).toBeDefined();
+      expect(body.meta.apiVersion).toBe('1.0.0');
+      expect(body.meta.requestId).toBeDefined();
+      expect(typeof body.meta.durationMs).toBe('number');
+    });
+
+    it('should add x-schema-version header', async () => {
+      app.get('/test', async () => ({ value: 42 }));
+
+      await app.ready();
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/test',
+      });
+
+      expect(response.headers['x-schema-version']).toBe('1.0.0');
+    });
+
+    it('should handle empty object response', async () => {
+      app.get('/empty', async () => ({}));
+
+      await app.ready();
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/empty',
+      });
+
+      const body = response.json();
+      expect(body.ok).toBe(true);
+      expect(body.data).toEqual({});
+    });
+
+    it('should handle null response', async () => {
+      app.get('/null', async () => null);
+
+      await app.ready();
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/null',
+      });
+
+      const body = response.json();
+      expect(body.ok).toBe(true);
+      expect(body.data).toBeNull();
+    });
+
+    it('should handle array response', async () => {
+      app.get('/array', async () => [1, 2, 3]);
+
+      await app.ready();
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/array',
+      });
+
+      const body = response.json();
+      expect(body.ok).toBe(true);
+      expect(body.data).toEqual([1, 2, 3]);
+    });
+
+    it('should not double-wrap already enveloped responses', async () => {
+      app.get('/enveloped', async () => ({
+        ok: true,
+        data: { already: 'wrapped' },
+        meta: { custom: 'meta' },
+      }));
+
+      await app.ready();
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/enveloped',
+      });
+
+      const body = response.json();
+      expect(body.ok).toBe(true);
+      expect(body.data).toEqual({ already: 'wrapped' });
+      expect(body.meta).toEqual({ custom: 'meta' });
+      // Should not have nested 'ok' in data
+      expect(body.data.ok).toBeUndefined();
+    });
+  });
+
+  describe('error responses', () => {
+    it('should wrap errors in error envelope', async () => {
+      app.get('/error', async () => {
+        const error = new Error('Something went wrong') as any;
+        error.statusCode = 400;
+        error.code = 'E_BAD_REQUEST';
+        throw error;
+      });
+
+      await app.ready();
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/error',
+      });
+
+      expect(response.statusCode).toBe(400);
+
+      const body = response.json();
+      expect(body.ok).toBe(false);
+      expect(body.error).toBeDefined();
+      expect(body.error.code).toBe('E_BAD_REQUEST');
+      expect(body.error.message).toBe('Something went wrong');
+      expect(body.meta).toBeDefined();
+      expect(body.meta.apiVersion).toBe('1.0.0');
+    });
+
+    it('should default to E_INTERNAL for unknown errors', async () => {
+      app.get('/internal-error', async () => {
+        throw new Error('Unexpected error');
+      });
+
+      await app.ready();
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/internal-error',
+      });
+
+      expect(response.statusCode).toBe(500);
+
+      const body = response.json();
+      expect(body.ok).toBe(false);
+      expect(body.error.code).toBe('E_INTERNAL');
+    });
+
+    it('should include error details when provided', async () => {
+      app.get('/detailed-error', async () => {
+        const error = new Error('Validation failed') as any;
+        error.statusCode = 422;
+        error.code = 'E_VALIDATION';
+        error.details = { field: 'email', reason: 'invalid format' };
+        throw error;
+      });
+
+      await app.ready();
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/detailed-error',
+      });
+
+      const body = response.json();
+      expect(body.error.details).toEqual({ field: 'email', reason: 'invalid format' });
+    });
+
+    it('should include traceId when provided', async () => {
+      app.get('/traced-error', async () => {
+        const error = new Error('Traceable error') as any;
+        error.statusCode = 500;
+        error.traceId = 'trace-123-abc';
+        throw error;
+      });
+
+      await app.ready();
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/traced-error',
+      });
+
+      const body = response.json();
+      expect(body.error.traceId).toBe('trace-123-abc');
+    });
+  });
+
+  describe('streaming responses', () => {
+    it('should skip envelope for SSE responses', async () => {
+      app.get('/events', async (request: FastifyRequest, reply: FastifyReply) => {
+        reply.header('content-type', 'text/event-stream');
+        return 'data: test\n\n';
+      });
+
+      await app.ready();
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/events',
+      });
+
+      // Should return raw SSE data, not wrapped
+      expect(response.body).toBe('data: test\n\n');
+      expect(response.headers['x-schema-version']).toBe('1.0.0');
+    });
+  });
+
+  describe('non-JSON responses', () => {
+    it('should pass through non-JSON string responses', async () => {
+      app.get('/text', async (request: FastifyRequest, reply: FastifyReply) => {
+        reply.header('content-type', 'text/plain');
+        return 'Plain text response';
+      });
+
+      await app.ready();
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/text',
+      });
+
+      // Plain text should be wrapped if it can be parsed
+      // but since 'Plain text response' is not valid JSON, it passes through
+      expect(response.body).toBe('Plain text response');
+    });
+  });
+});

package/src/middleware/__tests__/metrics.redis.spec.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest'
+import { metricsCollector } from '../metrics'
+
+type RedisStatus = {
+  enabled: boolean;
+  healthy: boolean;
+  roles: { publisher?: string | null; subscriber?: string | null; cache?: string | null };
+};
+
+function redisStatus(overrides: Partial<RedisStatus> = {}): RedisStatus {
+  const baseRoles: RedisStatus['roles'] = {
+    publisher: 'ready',
+    subscriber: 'subscribed',
+    cache: null,
+  }
+
+  const roles: RedisStatus['roles'] = {
+    publisher: overrides.roles?.publisher ?? baseRoles.publisher,
+    subscriber: overrides.roles?.subscriber ?? baseRoles.subscriber,
+    cache: overrides.roles?.cache ?? baseRoles.cache,
+  }
+
+  return {
+    enabled: overrides.enabled ?? true,
+    healthy: overrides.healthy ?? true,
+    roles,
+  }
+}
+
+describe('metricsCollector.recordRedisStatus', () => {
+  it('tracks redis health transitions and role states', () => {
+    metricsCollector.reset()
+
+    const initial = redisStatus()
+    const degraded = redisStatus({
+      healthy: false,
+      roles: { publisher: 'reconnecting', subscriber: 'reconnecting', cache: 'stale' },
+    })
+
+    metricsCollector.recordRedisStatus(initial)
+    metricsCollector.recordRedisStatus(degraded)
+
+    const snapshot = metricsCollector.getMetrics().redis
+
+    expect(snapshot.updates).toBe(2)
+    expect(snapshot.healthyTransitions).toBe(0)
+    expect(snapshot.unhealthyTransitions).toBe(1)
+    expect(snapshot.lastStatus).toMatchObject({
+      enabled: true,
+      healthy: false,
+      roles: {
+        publisher: 'reconnecting',
+        subscriber: 'reconnecting',
+        cache: 'stale',
+      },
+    })
+
+    const publisherStates = snapshot.roleStates.find((entry) => entry.role === 'publisher')
+    expect(publisherStates?.states.find((state) => state.state === 'ready')?.count).toBe(1)
+    expect(publisherStates?.states.find((state) => state.state === 'reconnecting')?.count).toBe(1)
+  })
+})
+
+