@kb-labs/gateway-app 0.2.0

package/src/__tests__/execute-routes.test.ts

@@ -0,0 +1,408 @@
+/**
+ * Integration tests for execute routes (CC1/CC2/CC3/CC5).
+ *
+ * POST /api/v1/execute     — ndjson streaming, 400/401/503, cancellation flow
+ * POST /api/v1/execute/:id/cancel — 200/404/403/409
+ *
+ * Uses real Fastify instance with mocked globalDispatcher.
+ * ndjson response is collected line-by-line.
+ */
+import { describe, it, expect, vi, beforeAll, afterAll, beforeEach } from 'vitest';
+import Fastify, { type FastifyInstance } from 'fastify';
+import type { ILogger } from '@kb-labs/core-platform';
+
+// ── Mock heavy deps before importing routes ───────────────────────────────────
+// Use vi.hoisted() so variables are available when vi.mock() factory runs
+// (vi.mock calls are hoisted to the top of the file, before variable declarations)
+
+const { mockDispatcher, mockBroadcast } = vi.hoisted(() => {
+  const mockDispatcher = {
+    firstHost: vi.fn(),
+    firstHostWithCapability: vi.fn(),
+    call: vi.fn(),
+  };
+  const mockBroadcast = vi.fn();
+  return { mockDispatcher, mockBroadcast };
+});
+
+vi.mock('../hosts/dispatcher.js', () => ({
+  globalDispatcher: mockDispatcher,
+  HostCallDispatcher: vi.fn(),
+}));
+
+vi.mock('../clients/subscription-registry.js', () => ({
+  subscriptionRegistry: {
+    broadcast: mockBroadcast,
+    subscribe: vi.fn(),
+    unsubscribe: vi.fn(),
+  },
+  SubscriptionRegistry: vi.fn(),
+}));
+
+import { registerExecuteRoutes } from '../execute/routes.js';
+import { executionRegistry } from '../execute/execution-registry.js';
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const noopLogger: ILogger = {
+  info: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+  debug: vi.fn(),
+  child: vi.fn(() => noopLogger),
+} as unknown as ILogger;
+
+function makeAuthContext(namespaceId = 'ns-test') {
+  return {
+    type: 'machine' as const,
+    userId: 'host-001',
+    namespaceId,
+    tier: 'free' as const,
+    permissions: ['host:connect'],
+  };
+}
+
+/** Parse ndjson response body into array of parsed objects */
+function parseNdjson(body: string): unknown[] {
+  return body
+    .split('\n')
+    .filter((line) => line.trim() !== '')
+    .map((line) => JSON.parse(line) as unknown);
+}
+
+let app: FastifyInstance;
+
+beforeAll(async () => {
+  app = Fastify({ logger: false });
+
+  // Inject authContext via preHandler
+  app.addHook('preHandler', async (request) => {
+    (request as { authContext?: unknown }).authContext = makeAuthContext();
+  });
+
+  registerExecuteRoutes(app, noopLogger);
+  await app.ready();
+});
+
+afterAll(async () => {
+  await app.close();
+});
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  // By default, a host exists
+  mockDispatcher.firstHost.mockReturnValue('host-001');
+  mockDispatcher.firstHostWithCapability.mockReturnValue('host-001');
+  // By default, dispatch resolves with a result
+  mockDispatcher.call.mockResolvedValue({ output: 'test-result' });
+});
+
+// ── POST /api/v1/execute — happy path ─────────────────────────────────────────
+
+describe('POST /api/v1/execute — success', () => {
+  it('returns 200 with ndjson content-type', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/execute',
+      payload: { pluginId: 'my-plugin', handlerRef: 'handlers/main.js', input: { foo: 'bar' } },
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.headers['content-type']).toContain('application/x-ndjson');
+  });
+
+  it('response body contains execution:done as last event', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/execute',
+      payload: { pluginId: 'my-plugin', handlerRef: 'handlers/main.js', input: {} },
+    });
+
+    const events = parseNdjson(res.body);
+    const doneEvent = events.find((e) => (e as { type: string }).type === 'execution:done');
+    expect(doneEvent).toBeDefined();
+    expect((doneEvent as { exitCode: number }).exitCode).toBe(0);
+  });
+
+  it('X-Execution-Id header is present in response', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/execute',
+      payload: { pluginId: 'p', handlerRef: 'h', input: null },
+    });
+
+    expect(res.headers['x-execution-id']).toBeTruthy();
+    expect(typeof res.headers['x-execution-id']).toBe('string');
+  });
+
+  it('dispatches to correct namespace and host', async () => {
+    await app.inject({
+      method: 'POST',
+      url: '/api/v1/execute',
+      payload: { pluginId: 'test-plugin', handlerRef: 'handler.js', input: { x: 1 } },
+    });
+
+    expect(mockDispatcher.firstHostWithCapability).toHaveBeenCalledWith('ns-test', 'execution');
+    expect(mockDispatcher.call).toHaveBeenCalledWith(
+      'ns-test',
+      'host-001',
+      'execution',
+      'execute',
+      expect.arrayContaining([
+        expect.objectContaining({ pluginId: 'test-plugin', handlerRef: 'handler.js' }),
+      ]),
+    );
+  });
+
+  it('broadcasts execution:done event to WS subscribers', async () => {
+    await app.inject({
+      method: 'POST',
+      url: '/api/v1/execute',
+      payload: { pluginId: 'p', handlerRef: 'h', input: null },
+    });
+
+    // broadcast is called at least once (for execution:done)
+    const calls = mockBroadcast.mock.calls as [string, { type: string }][];
+    const doneCall = calls.find(([, event]) => event.type === 'execution:done');
+    expect(doneCall).toBeDefined();
+  });
+
+  it('execution is removed from registry after completion', async () => {
+    const before = executionRegistry.size;
+    await app.inject({
+      method: 'POST',
+      url: '/api/v1/execute',
+      payload: { pluginId: 'p', handlerRef: 'h', input: null },
+    });
+    // After response, execution should have been removed
+    expect(executionRegistry.size).toBe(before);
+  });
+});
+
+// ── POST /api/v1/execute — error cases ───────────────────────────────────────
+
+describe('POST /api/v1/execute — error cases', () => {
+  it('returns 400 when pluginId is missing', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/execute',
+      payload: { handlerRef: 'h', input: {} },
+    });
+    expect(res.statusCode).toBe(400);
+    const body = res.json() as { error: string };
+    expect(body.error).toBe('Bad Request');
+  });
+
+  it('returns 400 when handlerRef is missing', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/execute',
+      payload: { pluginId: 'p', input: {} },
+    });
+    expect(res.statusCode).toBe(400);
+  });
+
+  it('returns 503 when no host is connected for namespace', async () => {
+    mockDispatcher.firstHostWithCapability.mockReturnValue(null);
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/execute',
+      payload: { pluginId: 'p', handlerRef: 'h', input: null },
+    });
+
+    expect(res.statusCode).toBe(503);
+    const body = res.json() as { error: string; namespaceId: string };
+    expect(body.error).toBe('No execution host connected');
+    expect(body.namespaceId).toBe('ns-test');
+    expect(noopLogger.warn).toHaveBeenCalledWith(
+      'No execution host connected for namespace',
+      expect.objectContaining({
+        diagnosticEvent: 'gateway.execution.dispatch',
+        reasonCode: 'execution_host_unavailable',
+        serviceId: 'gateway',
+        evidence: expect.objectContaining({
+          namespaceId: 'ns-test',
+        }),
+      }),
+    );
+  });
+
+  it('on dispatch failure: streams execution:error + execution:done(exitCode=1)', async () => {
+    mockDispatcher.call.mockRejectedValue(new Error('ECONNREFUSED connection refused'));
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/execute',
+      payload: { pluginId: 'p', handlerRef: 'h', input: null },
+    });
+
+    expect(res.statusCode).toBe(200); // headers already sent
+    const events = parseNdjson(res.body);
+
+    const errorEvent = events.find((e) => (e as { type: string }).type === 'execution:error');
+    expect(errorEvent).toBeDefined();
+    expect((errorEvent as { code: string }).code).toBe('EXECUTION_FAILED');
+    expect(noopLogger.error).toHaveBeenCalledWith(
+      'Gateway execution dispatch failed',
+      expect.any(Error),
+      expect.objectContaining({
+        diagnosticEvent: 'gateway.execution.dispatch',
+        reasonCode: 'execution_dispatch_failed',
+        serviceId: 'gateway',
+      }),
+    );
+
+    const doneEvent = events.find((e) => (e as { type: string }).type === 'execution:done');
+    expect((doneEvent as { exitCode: number }).exitCode).toBe(1);
+  });
+});
+
+// ── POST /api/v1/execute/:id/cancel ──────────────────────────────────────────
+
+describe('POST /api/v1/execute/:id/cancel', () => {
+  it('returns 200 when execution is found and cancelled', async () => {
+    // Register a real execution so cancel can find it
+    const signal = executionRegistry.register({
+      executionId: 'exec-cancel-test',
+      requestId: 'req-1',
+      namespaceId: 'ns-test',
+      hostId: 'host-001',
+      pluginId: 'p',
+      handlerRef: 'h',
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/execute/exec-cancel-test/cancel',
+      payload: { reason: 'user' },
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as { executionId: string; status: string };
+    expect(body.status).toBe('cancelled');
+    expect(body.executionId).toBe('exec-cancel-test');
+    expect(signal.aborted).toBe(true);
+
+    executionRegistry.remove('exec-cancel-test');
+  });
+
+  it('returns 404 when execution does not exist', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/execute/nonexistent-id/cancel',
+      payload: {},
+    });
+
+    expect(res.statusCode).toBe(404);
+    const body = res.json() as { error: string };
+    expect(body.error).toContain('not found');
+  });
+
+  it('returns 403 when execution belongs to different namespace', async () => {
+    // Register an execution in a different namespace
+    executionRegistry.register({
+      executionId: 'exec-other-ns',
+      requestId: 'req-x',
+      namespaceId: 'ns-other', // different namespace
+      hostId: 'host-002',
+      pluginId: 'p',
+      handlerRef: 'h',
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/execute/exec-other-ns/cancel',
+      payload: {},
+    });
+
+    expect(res.statusCode).toBe(403);
+    const body = res.json() as { error: string };
+    expect(body.error).toContain('Forbidden');
+
+    executionRegistry.remove('exec-other-ns');
+  });
+
+  it('returns 409 when execution is already cancelled', async () => {
+    executionRegistry.register({
+      executionId: 'exec-already-cancelled',
+      requestId: 'req-2',
+      namespaceId: 'ns-test',
+      hostId: 'host-001',
+      pluginId: 'p',
+      handlerRef: 'h',
+    });
+    // Cancel it first
+    executionRegistry.cancel('exec-already-cancelled', 'user');
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/execute/exec-already-cancelled/cancel',
+      payload: {},
+    });
+
+    expect(res.statusCode).toBe(409);
+    const body = res.json() as { status: string };
+    expect(body.status).toBe('already_cancelled');
+
+    executionRegistry.remove('exec-already-cancelled');
+  });
+
+  it('defaults reason to "user" when not provided', async () => {
+    executionRegistry.register({
+      executionId: 'exec-default-reason',
+      requestId: 'req-3',
+      namespaceId: 'ns-test',
+      hostId: 'host-001',
+      pluginId: 'p',
+      handlerRef: 'h',
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/execute/exec-default-reason/cancel',
+      payload: {},
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as { reason: string };
+    expect(body.reason).toBe('user');
+
+    executionRegistry.remove('exec-default-reason');
+  });
+});
+
+// ── 401 without auth context ──────────────────────────────────────────────────
+
+describe('POST /api/v1/execute — auth guard', () => {
+  let appNoAuth: FastifyInstance;
+
+  beforeAll(async () => {
+    appNoAuth = Fastify({ logger: false });
+    // No preHandler — authContext stays undefined
+    registerExecuteRoutes(appNoAuth, noopLogger);
+    await appNoAuth.ready();
+  });
+
+  afterAll(async () => {
+    await appNoAuth.close();
+  });
+
+  it('returns 401 when authContext is absent', async () => {
+    const res = await appNoAuth.inject({
+      method: 'POST',
+      url: '/api/v1/execute',
+      payload: { pluginId: 'p', handlerRef: 'h', input: null },
+    });
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('cancel returns 401 when authContext is absent', async () => {
+    const res = await appNoAuth.inject({
+      method: 'POST',
+      url: '/api/v1/execute/some-id/cancel',
+      payload: {},
+    });
+    expect(res.statusCode).toBe(401);
+  });
+});

package/src/__tests__/execution-registry.test.ts

@@ -0,0 +1,218 @@
+/**
+ * Unit tests for ExecutionRegistry (CC2 — Cancellation).
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { ExecutionRegistry } from '../execute/execution-registry.js';
+
+function makeEntry(overrides: Partial<{
+  executionId: string;
+  requestId: string;
+  namespaceId: string;
+  hostId: string;
+  pluginId: string;
+  handlerRef: string;
+}> = {}) {
+  return {
+    executionId: 'exec-1',
+    requestId: 'req-1',
+    namespaceId: 'ns-1',
+    hostId: 'host-1',
+    pluginId: 'plugin-a',
+    handlerRef: 'handlers/run.ts',
+    ...overrides,
+  };
+}
+
+describe('ExecutionRegistry', () => {
+  let registry: ExecutionRegistry;
+
+  beforeEach(() => {
+    registry = new ExecutionRegistry();
+  });
+
+  // ── register ──────────────────────────────────────────────────────────────
+
+  describe('register()', () => {
+    it('returns an AbortSignal', () => {
+      const signal = registry.register(makeEntry());
+      expect(signal).toBeInstanceOf(AbortSignal);
+    });
+
+    it('signal is not aborted initially', () => {
+      const signal = registry.register(makeEntry());
+      expect(signal.aborted).toBe(false);
+    });
+
+    it('stores execution metadata', () => {
+      registry.register(makeEntry({ executionId: 'exec-x' }));
+      const entry = registry.get('exec-x');
+      expect(entry?.namespaceId).toBe('ns-1');
+      expect(entry?.hostId).toBe('host-1');
+      expect(entry?.pluginId).toBe('plugin-a');
+      expect(entry?.startedAt).toBeTypeOf('number');
+    });
+
+    it('increments size', () => {
+      registry.register(makeEntry({ executionId: 'a' }));
+      registry.register(makeEntry({ executionId: 'b' }));
+      expect(registry.size).toBe(2);
+    });
+  });
+
+  // ── cancel ────────────────────────────────────────────────────────────────
+
+  describe('cancel()', () => {
+    it('returns true and aborts signal', () => {
+      const signal = registry.register(makeEntry());
+      const result = registry.cancel('exec-1', 'user');
+      expect(result).toBe(true);
+      expect(signal.aborted).toBe(true);
+    });
+
+    it('stores cancellation reason on the entry', () => {
+      registry.register(makeEntry());
+      registry.cancel('exec-1', 'timeout');
+      expect(registry.get('exec-1')?.cancelledReason).toBe('timeout');
+    });
+
+    it('returns false for non-existent executionId', () => {
+      expect(registry.cancel('does-not-exist', 'user')).toBe(false);
+    });
+
+    it('returns false when already cancelled (idempotent)', () => {
+      registry.register(makeEntry());
+      expect(registry.cancel('exec-1', 'user')).toBe(true);
+      expect(registry.cancel('exec-1', 'timeout')).toBe(false);
+    });
+
+    it('abort signal reason matches provided reason', () => {
+      const signal = registry.register(makeEntry());
+      registry.cancel('exec-1', 'disconnect');
+      expect(signal.reason).toBe('disconnect');
+    });
+  });
+
+  // ── remove ────────────────────────────────────────────────────────────────
+
+  describe('remove()', () => {
+    it('removes execution from registry', () => {
+      registry.register(makeEntry());
+      registry.remove('exec-1');
+      expect(registry.get('exec-1')).toBeUndefined();
+    });
+
+    it('decrements size', () => {
+      registry.register(makeEntry({ executionId: 'a' }));
+      registry.register(makeEntry({ executionId: 'b' }));
+      registry.remove('a');
+      expect(registry.size).toBe(1);
+    });
+
+    it('is no-op for non-existent id', () => {
+      expect(() => registry.remove('ghost')).not.toThrow();
+    });
+  });
+
+  // ── get ───────────────────────────────────────────────────────────────────
+
+  describe('get()', () => {
+    it('returns undefined for unknown id', () => {
+      expect(registry.get('unknown')).toBeUndefined();
+    });
+
+    it('returns the active execution', () => {
+      registry.register(makeEntry({ executionId: 'exec-abc' }));
+      const entry = registry.get('exec-abc');
+      expect(entry?.executionId).toBe('exec-abc');
+    });
+  });
+
+  // ── cancelByHost ──────────────────────────────────────────────────────────
+
+  describe('cancelByHost()', () => {
+    it('cancels all executions for given hostId', () => {
+      const sig1 = registry.register(makeEntry({ executionId: 'e1', hostId: 'host-A' }));
+      const sig2 = registry.register(makeEntry({ executionId: 'e2', hostId: 'host-A' }));
+      const sig3 = registry.register(makeEntry({ executionId: 'e3', hostId: 'host-B' }));
+
+      const cancelled = registry.cancelByHost('host-A', 'disconnect');
+
+      expect(cancelled).toContain('e1');
+      expect(cancelled).toContain('e2');
+      expect(cancelled).not.toContain('e3');
+      expect(sig1.aborted).toBe(true);
+      expect(sig2.aborted).toBe(true);
+      expect(sig3.aborted).toBe(false);
+    });
+
+    it('returns empty array when no executions for host', () => {
+      registry.register(makeEntry({ executionId: 'e1', hostId: 'host-X' }));
+      const result = registry.cancelByHost('host-Z', 'disconnect');
+      expect(result).toEqual([]);
+    });
+
+    it('skips already-aborted executions', () => {
+      registry.register(makeEntry({ executionId: 'e1', hostId: 'host-A' }));
+      registry.cancel('e1', 'user'); // pre-cancel
+      const cancelled = registry.cancelByHost('host-A', 'disconnect');
+      expect(cancelled).not.toContain('e1');
+    });
+
+    it('returns executionIds of cancelled executions', () => {
+      registry.register(makeEntry({ executionId: 'alpha', hostId: 'host-1' }));
+      const result = registry.cancelByHost('host-1', 'disconnect');
+      expect(result).toEqual(['alpha']);
+    });
+  });
+
+  // ── size ──────────────────────────────────────────────────────────────────
+
+  describe('size', () => {
+    it('starts at 0', () => {
+      expect(registry.size).toBe(0);
+    });
+
+    it('tracks additions and removals correctly', () => {
+      registry.register(makeEntry({ executionId: 'a' }));
+      registry.register(makeEntry({ executionId: 'b' }));
+      registry.register(makeEntry({ executionId: 'c' }));
+      registry.remove('b');
+      expect(registry.size).toBe(2);
+    });
+  });
+});
+
+// ── CancelledError ────────────────────────────────────────────────────────────
+
+import { CancelledError } from '../execute/errors.js';
+
+describe('CancelledError', () => {
+  it('stores reason', () => {
+    const err = new CancelledError('timeout');
+    expect(err.reason).toBe('timeout');
+  });
+
+  it('has descriptive message', () => {
+    const err = new CancelledError('user');
+    expect(err.message).toContain('Execution cancelled');
+    expect(err.message).toContain('user');
+  });
+
+  it('has correct name', () => {
+    expect(new CancelledError('disconnect').name).toBe('CancelledError');
+  });
+
+  it('is instanceof Error', () => {
+    expect(new CancelledError('user')).toBeInstanceOf(Error);
+  });
+
+  it('is instanceof CancelledError', () => {
+    expect(new CancelledError('user')).toBeInstanceOf(CancelledError);
+  });
+
+  it('supports all cancellation reasons', () => {
+    for (const reason of ['user', 'timeout', 'disconnect'] as const) {
+      expect(() => new CancelledError(reason)).not.toThrow();
+    }
+  });
+});