@kb-labs/rest-api-app 1.3.0

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

@@ -0,0 +1,204 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import Fastify from 'fastify'
+import type { RestApiConfig } from '@kb-labs/rest-api-core'
+import { registerWorkflowRoutes } from '../workflows'
+
+const BASE_CONFIG: RestApiConfig = {
+  port: 3000,
+  basePath: '/api/v1',
+  apiVersion: 'test',
+  cors: {
+    origins: [],
+    allowCredentials: true,
+    profile: 'dev',
+  },
+  plugins: [],
+  mockMode: false,
+}
+
+type EventHandler = (event: unknown) => Promise<void>
+let capturedHandlers: EventHandler[] = []
+
+const { mockUnsubscribe, mockSubscribe } = vi.hoisted(() => {
+  const mockUnsubscribe = vi.fn()
+  const mockSubscribe = vi.fn((_channel: string, handler: EventHandler) => {
+    capturedHandlers.push(handler)
+    // Immediately emit a terminal event to close the SSE stream,
+    // so app.inject() resolves instead of hanging.
+    setTimeout(() => {
+      handler({ type: 'run.finished', runId: 'run-123', payload: { status: 'success' } })
+    }, 10)
+    return mockUnsubscribe
+  })
+  return { mockUnsubscribe, mockSubscribe }
+})
+
+vi.mock('@kb-labs/core-runtime', () => ({
+  platform: {
+    eventBus: {
+      subscribe: mockSubscribe,
+    },
+  },
+}))
+
+vi.mock('@kb-labs/workflow-constants', () => ({
+  WORKFLOW_REDIS_CHANNEL: 'kb:wf:events',
+}))
+
+describe('registerWorkflowRoutes', () => {
+  let app: ReturnType<typeof Fastify>
+
+  beforeEach(async () => {
+    vi.clearAllMocks()
+    capturedHandlers = []
+    app = Fastify({ logger: false })
+    await registerWorkflowRoutes(app, BASE_CONFIG)
+  })
+
+  afterEach(async () => {
+    await app.close()
+  })
+
+  describe('GET /workflows/runs/:runId/events (SSE)', () => {
+    it('returns SSE headers and connected comment', async () => {
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/workflows/runs/run-123/events',
+      })
+
+      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')
+      expect(response.body).toContain(': connected')
+    })
+
+    it('emits workflow.event for matching runId', async () => {
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/workflows/runs/run-123/events',
+      })
+
+      expect(response.body).toContain('event: workflow.event')
+      expect(response.body).toContain('"type":"run.finished"')
+      expect(response.body).toContain('"runId":"run-123"')
+    })
+
+    it('sets CORS headers for localhost:3000', async () => {
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/workflows/runs/run-123/events',
+        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', async () => {
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/workflows/runs/run-123/events',
+        headers: { origin: 'http://localhost:5173' },
+      })
+
+      expect(response.headers['access-control-allow-origin']).toBe('http://localhost:5173')
+    })
+
+    it('does not set CORS headers for other origins', async () => {
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/workflows/runs/run-123/events',
+        headers: { origin: 'http://evil.com' },
+      })
+
+      expect(response.headers['access-control-allow-origin']).toBeUndefined()
+    })
+
+    it('calls unsubscribe on terminal event', async () => {
+      await app.inject({
+        method: 'GET',
+        url: '/api/v1/workflows/runs/run-123/events',
+      })
+
+      expect(mockUnsubscribe).toHaveBeenCalled()
+    })
+
+    it('filters events by runId — ignores other runs', async () => {
+      // Override the mock to emit an event for a different runId first
+      mockSubscribe.mockImplementationOnce((_channel, handler: EventHandler) => {
+        setTimeout(async () => {
+          // Event for a different run — should be ignored
+          await handler({ type: 'step.started', runId: 'other-run', payload: {} })
+          // Terminal event for our run — closes the stream
+          await handler({ type: 'run.finished', runId: 'run-123', payload: {} })
+        }, 10)
+        return mockUnsubscribe
+      })
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/workflows/runs/run-123/events',
+      })
+
+      // Should NOT contain the other-run event
+      expect(response.body).not.toContain('other-run')
+      expect(response.body).toContain('"runId":"run-123"')
+    })
+  })
+
+  describe('GET /workflows/runs/:runId/logs (SSE)', () => {
+    it('returns SSE headers and connected comment', async () => {
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/workflows/runs/run-123/logs?follow=1',
+      })
+
+      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')
+      expect(response.body).toContain(': connected')
+    })
+
+    it('emits workflow.log events', async () => {
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/workflows/runs/run-123/logs',
+      })
+
+      expect(response.body).toContain('event: workflow.log')
+      expect(response.body).toContain('"type":"run.finished"')
+      expect(response.body).toContain('"runId":"run-123"')
+    })
+
+    it('sets CORS headers for localhost:3000', async () => {
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/workflows/runs/run-123/logs',
+        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('does not set CORS headers for unknown origins', async () => {
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/workflows/runs/run-123/logs',
+        headers: { origin: 'http://attacker.com' },
+      })
+
+      expect(response.headers['access-control-allow-origin']).toBeUndefined()
+    })
+
+    it('respects custom idleTimeoutMs query param', async () => {
+      // Just verify the route accepts the param without error
+      const response = await app.inject({
+        method: 'GET',
+        url: '/api/v1/workflows/runs/run-123/logs?idleTimeoutMs=5000',
+      })
+
+      expect(response.headers['content-type']).toBe('text/event-stream')
+    })
+  })
+})

package/src/routes/adapter-call.ts

@@ -0,0 +1,220 @@
+/**
+ * Internal adapter-call endpoint — reverse proxy for Workspace Agent.
+ *
+ * Receives adapter:call from Gateway (forwarded from Host via WS),
+ * executes against platform services, returns result.
+ *
+ * Flow: Host → WS adapter:call → Gateway → HTTP POST here → platform.adapter.method()
+ *
+ * Security:
+ * - Auth: x-internal-secret (server-to-server, same as /internal/dispatch)
+ * - Adapter allowlist enforced (AdapterNameSchema)
+ * - Method allowlist per adapter (AdapterRegistry)
+ * - Zod validation on input/output
+ * - Audit logging on every call
+ *
+ * @see ADR-0051: Bidirectional Gateway Protocol
+ */
+
+import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+import { z } from 'zod';
+import { platform } from '@kb-labs/core-runtime';
+import { AdapterNameSchema, type AdapterName } from '@kb-labs/gateway-contracts';
+import { restDomainOperationMetrics } from '../middleware/metrics.js';
+
+// ── Adapter Registry ──
+
+interface AdapterMethodEntry {
+  inputSchema: z.ZodType;
+  outputSchema: z.ZodType;
+  execute: (args: unknown[], context: AdapterCallContext) => Promise<unknown>;
+}
+
+interface AdapterCallContext {
+  namespaceId: string;
+  hostId: string;
+  workspaceId?: string;
+  environmentId?: string;
+  executionRequestId?: string;
+  userId?: string;
+  sessionId?: string;
+}
+
+class AdapterRegistry {
+  private methods = new Map<string, AdapterMethodEntry>();
+
+  register(
+    adapter: AdapterName,
+    method: string,
+    entry: AdapterMethodEntry,
+  ): void {
+    this.methods.set(`${adapter}.${method}`, entry);
+  }
+
+  get(adapter: string, method: string): AdapterMethodEntry | undefined {
+    return this.methods.get(`${adapter}.${method}`);
+  }
+
+  has(adapter: string, method: string): boolean {
+    return this.methods.has(`${adapter}.${method}`);
+  }
+}
+
+// ── Request schema ──
+
+const AdapterCallRequestSchema = z.object({
+  requestId: z.string(),
+  adapter: AdapterNameSchema,
+  method: z.string(),
+  args: z.array(z.unknown()),
+  context: z.object({
+    namespaceId: z.string(),
+    hostId: z.string(),
+    workspaceId: z.string().optional(),
+    environmentId: z.string().optional(),
+    executionRequestId: z.string().optional(),
+    userId: z.string().optional(),
+    sessionId: z.string().optional(),
+  }),
+});
+
+// ── Registry initialization ──
+
+function createAdapterRegistry(): AdapterRegistry {
+  const registry = new AdapterRegistry();
+
+  // LLM
+  registry.register('llm', 'complete', {
+    inputSchema: z.array(z.unknown()),
+    outputSchema: z.unknown(),
+    execute: async (args) => {
+      const llm = platform.getAdapter<any>('llm');
+      if (!llm) { throw new Error('LLM adapter not available'); }
+      return llm.complete(...args);
+    },
+  });
+
+  // Cache
+  registry.register('cache', 'get', {
+    inputSchema: z.array(z.unknown()),
+    outputSchema: z.unknown().nullable(),
+    execute: async (args) => platform.cache.get(args[0] as string),
+  });
+
+  registry.register('cache', 'set', {
+    inputSchema: z.array(z.unknown()),
+    outputSchema: z.void(),
+    execute: async (args) => platform.cache.set(args[0] as string, args[1], args[2] as number | undefined),
+  });
+
+  registry.register('cache', 'delete', {
+    inputSchema: z.array(z.unknown()),
+    outputSchema: z.void(),
+    execute: async (args) => platform.cache.delete(args[0] as string),
+  });
+
+  // VectorStore
+  registry.register('vectorStore', 'search', {
+    inputSchema: z.array(z.unknown()),
+    outputSchema: z.unknown(),
+    execute: async (args) => {
+      const vs = platform.getAdapter<any>('vectorStore');
+      if (!vs) { throw new Error('VectorStore adapter not available'); }
+      return vs.search(...args);
+    },
+  });
+
+  // Embeddings
+  registry.register('embeddings', 'embed', {
+    inputSchema: z.array(z.unknown()),
+    outputSchema: z.unknown(),
+    execute: async (args) => {
+      const emb = platform.getAdapter<any>('embeddings');
+      if (!emb) { throw new Error('Embeddings adapter not available'); }
+      return emb.embed(...args);
+    },
+  });
+
+  // Storage
+  registry.register('storage', 'read', {
+    inputSchema: z.array(z.unknown()),
+    outputSchema: z.unknown(),
+    execute: async (args) => {
+      const storage = platform.getAdapter<any>('storage');
+      if (!storage) { throw new Error('Storage adapter not available'); }
+      return storage.read(...args);
+    },
+  });
+
+  registry.register('storage', 'write', {
+    inputSchema: z.array(z.unknown()),
+    outputSchema: z.void(),
+    execute: async (args) => {
+      const storage = platform.getAdapter<any>('storage');
+      if (!storage) { throw new Error('Storage adapter not available'); }
+      return storage.write(...args);
+    },
+  });
+
+  return registry;
+}
+
+// ── Route registration ──
+
+export async function registerAdapterCallRoutes(
+  server: FastifyInstance,
+): Promise<void> {
+  const registry = createAdapterRegistry();
+  const internalSecret = process.env.GATEWAY_INTERNAL_SECRET;
+  const logger = platform.logger.child({ layer: 'rest', route: 'adapter-call' });
+
+  server.post('/api/v1/internal/adapter-call', async (
+    request: FastifyRequest,
+    reply: FastifyReply,
+  ) => {
+    // 1. Auth: x-internal-secret
+    const provided = request.headers['x-internal-secret'] as string | undefined;
+    if (!internalSecret || provided !== internalSecret) {
+      return reply.code(403).send({ ok: false, error: { code: 'FORBIDDEN', message: 'Invalid internal secret', retryable: false } });
+    }
+
+    // 2. Parse & validate request
+    const parsed = AdapterCallRequestSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.code(400).send({ ok: false, error: { code: 'VALIDATION_ERROR', message: parsed.error.message, retryable: false } });
+    }
+
+    const { requestId, adapter, method, args, context } = parsed.data;
+    const startMs = Date.now();
+
+    // 3. Check registry
+    const entry = registry.get(adapter as string, method);
+    if (!entry) {
+      logger.warn('Adapter call rejected', { requestId, adapter, method, hostId: context.hostId });
+      return reply.code(403).send({ ok: false, error: { code: 'ADAPTER_CALL_REJECTED', message: `Method not allowed: ${adapter}.${method}`, retryable: false } });
+    }
+
+    // 4. Execute
+    try {
+      const operation = `adapter.call.${adapter}.${method}`;
+      const result = await restDomainOperationMetrics.observeOperation(operation, async () =>
+        entry.execute(args, context),
+      );
+      const latencyMs = Date.now() - startMs;
+
+      logger.info('Adapter call success', { requestId, adapter, method, hostId: context.hostId, latencyMs });
+
+      return { ok: true, result };
+    } catch (err) {
+      const latencyMs = Date.now() - startMs;
+      const message = err instanceof Error ? err.message : String(err);
+
+      logger.error('Adapter call failed', err instanceof Error ? err : undefined, { requestId, adapter, method, hostId: context.hostId, latencyMs });
+
+      return reply.code(500).send({
+        ok: false,
+        error: { code: 'ADAPTER_ERROR', message, retryable: false },
+      });
+    }
+  });
+}