@kb-labs/gateway-app 0.2.0

package/src/execute/errors.ts

@@ -0,0 +1,21 @@
+/**
+ * @module gateway-app/execute/errors
+ *
+ * Shared error types for execution pipeline.
+ */
+
+import type { CancellationReason } from '@kb-labs/core-contracts';
+
+/**
+ * Thrown when an execution is cancelled (CC2).
+ * Caught by routes.ts to emit execution:cancelled + execution:done(130).
+ */
+export class CancelledError extends Error {
+  readonly reason: CancellationReason;
+
+  constructor(reason: CancellationReason) {
+    super(`Execution cancelled: ${reason}`);
+    this.name = 'CancelledError';
+    this.reason = reason;
+  }
+}

package/src/execute/execution-registry.ts

@@ -0,0 +1,84 @@
+/**
+ * @module gateway-app/execute/execution-registry
+ *
+ * Tracks active executions with AbortController for cancellation.
+ *
+ * Lifecycle:
+ *   1. POST /execute → registry.register(executionId, ...) → AbortSignal
+ *   2. POST /execute/:id/cancel → registry.cancel(executionId, reason) → abort()
+ *   3. Execution completes or aborted → registry.remove(executionId)
+ *
+ * Also supports host disconnect: cancelByHost() aborts all executions
+ * dispatched to a host that went offline.
+ */
+
+import type { CancellationReason } from '@kb-labs/core-contracts';
+
+export interface ActiveExecution {
+  executionId: string;
+  requestId: string;
+  namespaceId: string;
+  hostId: string;
+  pluginId: string;
+  handlerRef: string;
+  controller: AbortController;
+  startedAt: number;
+  cancelledReason?: CancellationReason;
+}
+
+export class ExecutionRegistry {
+  private executions = new Map<string, ActiveExecution>();
+
+  /** Register a new execution. Returns AbortSignal to wire into the dispatch. */
+  register(entry: Omit<ActiveExecution, 'controller' | 'startedAt'>): AbortSignal {
+    const controller = new AbortController();
+    this.executions.set(entry.executionId, {
+      ...entry,
+      controller,
+      startedAt: Date.now(),
+    });
+    return controller.signal;
+  }
+
+  /** Cancel an execution by ID. Returns true if found and aborted. */
+  cancel(executionId: string, reason: CancellationReason): boolean {
+    const entry = this.executions.get(executionId);
+    if (!entry) { return false; }
+    if (entry.controller.signal.aborted) { return false; }
+
+    entry.cancelledReason = reason;
+    entry.controller.abort(reason);
+    return true;
+  }
+
+  /** Remove a completed/cancelled execution. */
+  remove(executionId: string): void {
+    this.executions.delete(executionId);
+  }
+
+  /** Get an active execution. */
+  get(executionId: string): ActiveExecution | undefined {
+    return this.executions.get(executionId);
+  }
+
+  /** Cancel all executions dispatched to a host (on host disconnect). */
+  cancelByHost(hostId: string, reason: CancellationReason): string[] {
+    const cancelled: string[] = [];
+    for (const entry of this.executions.values()) {
+      if (entry.hostId === hostId && !entry.controller.signal.aborted) {
+        entry.cancelledReason = reason;
+        entry.controller.abort(reason);
+        cancelled.push(entry.executionId);
+      }
+    }
+    return cancelled;
+  }
+
+  /** Number of active executions. */
+  get size(): number {
+    return this.executions.size;
+  }
+}
+
+/** Singleton — shared across Gateway process. */
+export const executionRegistry = new ExecutionRegistry();

package/src/execute/retry-executor.ts

@@ -0,0 +1,159 @@
+/**
+ * @module gateway-app/execute/retry-executor
+ *
+ * Level 2 retry wrapper for execution dispatch (CC3).
+ *
+ * Wraps a dispatch function with configurable retry + exponential backoff.
+ * Emits execution:retry events between attempts so clients see progress.
+ * Respects AbortSignal — cancels immediately, no retry after abort.
+ *
+ * Each attempt is raced against the AbortSignal so that a cancelled
+ * execution doesn't block on a hung dispatcher call.
+ */
+
+import type { ExecutionRetryConfig, CancellationReason } from '@kb-labs/core-contracts';
+import type { ExecutionEventMessage } from '@kb-labs/gateway-contracts';
+import { CancelledError } from './errors.js';
+
+const DEFAULTS: Required<ExecutionRetryConfig> = {
+  maxAttempts: 1,
+  initialDelayMs: 1000,
+  backoffMultiplier: 2,
+  maxDelayMs: 30_000,
+  onlyRetryable: true,
+};
+
+export interface RetryContext {
+  executionId: string;
+  requestId: string;
+  signal: AbortSignal;
+  config: ExecutionRetryConfig | undefined;
+  /** Emit event to client stream (and WS subscribers via routes.ts). */
+  write: (event: ExecutionEventMessage) => void;
+}
+
+/**
+ * Execute dispatch function with retry + abort-race logic.
+ *
+ * - maxAttempts=1 (default) → single call, raced against signal.
+ * - maxAttempts>1 → retry loop with backoff, each attempt raced against signal.
+ */
+export async function executeWithRetry<T>(
+  ctx: RetryContext,
+  dispatch: () => Promise<T>,
+): Promise<T> {
+  const cfg = { ...DEFAULTS, ...ctx.config };
+  const maxAttempts = Math.max(1, cfg.maxAttempts);
+
+  let lastError: Error | null = null;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    if (ctx.signal.aborted) {
+      throw new CancelledError(ctx.signal.reason as CancellationReason);
+    }
+
+    try {
+      return await raceAbort(ctx.signal, dispatch());
+    } catch (err) {
+      // Cancellation is never retried
+      if (err instanceof CancelledError) { throw err; }
+
+      lastError = err instanceof Error ? err : new Error(String(err));
+
+      // Last attempt — propagate error
+      if (attempt >= maxAttempts) { break; }
+
+      // Check if error is retryable
+      const classified = classifyError(err);
+      if (cfg.onlyRetryable && !classified.retryable) { break; }
+
+      // Backoff delay
+      const delay = Math.min(
+        cfg.initialDelayMs * Math.pow(cfg.backoffMultiplier, attempt - 1),
+        cfg.maxDelayMs,
+      );
+
+      ctx.write({
+        type: 'execution:retry',
+        requestId: ctx.requestId,
+        executionId: ctx.executionId,
+        attempt,
+        maxAttempts,
+        delayMs: delay,
+        error: classified.message,
+      } satisfies ExecutionEventMessage);
+
+      await interruptibleDelay(delay, ctx.signal);
+    }
+  }
+
+  throw lastError ?? new Error('executeWithRetry: no attempts made');
+}
+
+// ── Internals ──
+
+/**
+ * Race a promise against an AbortSignal.
+ */
+function raceAbort<T>(signal: AbortSignal, promise: Promise<T>): Promise<T> {
+  if (signal.aborted) {
+    return Promise.reject(new CancelledError(signal.reason as CancellationReason));
+  }
+
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(new CancelledError(signal.reason as CancellationReason));
+    signal.addEventListener('abort', onAbort, { once: true });
+
+    promise.then(
+      (v) => { signal.removeEventListener('abort', onAbort); resolve(v); },
+      (e) => { signal.removeEventListener('abort', onAbort); reject(e); },
+    );
+  });
+}
+
+/**
+ * Sleep interruptible by AbortSignal.
+ */
+function interruptibleDelay(ms: number, signal: AbortSignal): Promise<void> {
+  if (signal.aborted) {
+    return Promise.reject(new CancelledError(signal.reason as CancellationReason));
+  }
+
+  return new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new CancelledError(signal.reason as CancellationReason));
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+interface ClassifiedError {
+  code: string;
+  message: string;
+  retryable: boolean;
+}
+
+function classifyError(err: unknown): ClassifiedError {
+  if (!(err instanceof Error)) {
+    return { code: 'UNKNOWN', message: String(err), retryable: false };
+  }
+
+  const msg = err.message;
+
+  // Transport / network — retryable
+  if (msg.includes('ECONNREFUSED') || msg.includes('ECONNRESET') ||
+      msg.includes('ETIMEDOUT') || msg.includes('timed out') ||
+      msg.includes('503') || msg.includes('Service Unavailable')) {
+    return { code: 'TRANSPORT_ERROR', message: msg, retryable: true };
+  }
+
+  // Host went offline — retryable (may reconnect)
+  if (msg.includes('Host not connected')) {
+    return { code: 'HOST_UNAVAILABLE', message: msg, retryable: true };
+  }
+
+  // Everything else — not retryable
+  return { code: 'HANDLER_ERROR', message: msg, retryable: false };
+}

package/src/execute/routes.ts

@@ -0,0 +1,239 @@
+/**
+ * @module gateway-app/execute/routes
+ *
+ * POST /api/v1/execute — Execute handler via Gateway with ndjson streaming.
+ * POST /api/v1/execute/:executionId/cancel — Cancel an active execution.
+ *
+ * Response: Transfer-Encoding: chunked, Content-Type: application/x-ndjson
+ * Each line = JSON ExecutionEvent.
+ *
+ * Integrates:
+ *   CC2 — Cancellation via ExecutionRegistry + AbortController
+ *   CC3 — Retry via executeWithRetry (exponential backoff, retryable errors)
+ *   CC5 — Broadcast to WS subscribers via SubscriptionRegistry
+ */
+
+import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+import { randomUUID } from 'node:crypto';
+import { ExecuteRequestSchema, type ExecutionEventMessage } from '@kb-labs/gateway-contracts';
+import { logDiagnosticEvent, type ILogger } from '@kb-labs/core-platform';
+import type { CancellationReason } from '@kb-labs/core-contracts';
+import { globalDispatcher } from '../hosts/dispatcher.js';
+import { executionRegistry } from './execution-registry.js';
+import { subscriptionRegistry } from '../clients/subscription-registry.js';
+import { executeWithRetry } from './retry-executor.js';
+import { CancelledError } from './errors.js';
+
+export function registerExecuteRoutes(app: FastifyInstance, logger: ILogger): void {
+  /**
+   * POST /api/v1/execute
+   * hide: true — uses ndjson chunked streaming via reply.raw, incompatible with OpenAPI response schema
+   */
+  app.post('/api/v1/execute', { schema: { tags: ['Execute'], summary: 'Execute a plugin handler', hide: true } }, async (request: FastifyRequest, reply: FastifyReply) => {
+    const auth = request.authContext;
+    if (!auth) {
+      return reply.code(401).send({ error: 'Unauthorized' });
+    }
+
+    const parsed = ExecuteRequestSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.code(400).send({ error: 'Bad Request', issues: parsed.error.issues });
+    }
+
+    const { pluginId, handlerRef, exportName, input, timeoutMs } = parsed.data;
+    const executionId = randomUUID();
+    const requestId = randomUUID();
+    const startTime = Date.now();
+
+    logger.info('Execute request received', {
+      executionId,
+      pluginId,
+      handlerRef,
+      namespaceId: auth.namespaceId,
+    });
+
+    // Resolve host with 'execution' capability
+    const hostId = globalDispatcher.firstHostWithCapability(auth.namespaceId, 'execution');
+    if (!hostId) {
+      logDiagnosticEvent(logger, {
+        domain: 'service',
+        event: 'gateway.execution.dispatch',
+        level: 'warn',
+        reasonCode: 'execution_host_unavailable',
+        message: 'No execution host connected for namespace',
+        outcome: 'failed',
+        serviceId: 'gateway',
+        evidence: {
+          namespaceId: auth.namespaceId,
+          pluginId,
+          handlerRef,
+        },
+      });
+      return reply.code(503).send({
+        error: 'No execution host connected',
+        hint: 'Ensure a RuntimeServer is running and connected to Gateway',
+        namespaceId: auth.namespaceId,
+      });
+    }
+
+    // Register in execution registry (CC2)
+    const signal = executionRegistry.register({
+      executionId,
+      requestId,
+      namespaceId: auth.namespaceId,
+      hostId,
+      pluginId,
+      handlerRef,
+    });
+
+    // Auto-cancel on client disconnect.
+    // reply.raw 'close' fires when connection drops before response finishes.
+    // Check writableFinished to distinguish mid-stream disconnect from normal completion.
+    reply.raw.on('close', () => {
+      if (!reply.raw.writableFinished && !signal.aborted) {
+        executionRegistry.cancel(executionId, 'disconnect');
+      }
+    });
+
+    // Hijack response for ndjson streaming
+    reply.raw.writeHead(200, {
+      'Content-Type': 'application/x-ndjson',
+      'Transfer-Encoding': 'chunked',
+      'Cache-Control': 'no-cache',
+      'X-Execution-Id': executionId,
+    });
+    // Flush headers immediately so the client can see X-Execution-Id before any events
+    reply.raw.flushHeaders();
+
+    // Write typed event to initiator ndjson stream + broadcast to WS subscribers (CC5)
+    const writeEvent = (event: ExecutionEventMessage): void => {
+      const payload = JSON.stringify(event) + '\n';
+      if (!reply.raw.writableEnded) {
+        reply.raw.write(payload);
+      }
+      subscriptionRegistry.broadcast(executionId, event);
+    };
+
+    try {
+      // Dispatch with retry + abort-race (CC2 + CC3)
+      // TODO: read retry config from platform config when available
+      const result = await executeWithRetry(
+        { executionId, requestId, signal, config: undefined, write: writeEvent },
+        () => globalDispatcher.call(
+          auth.namespaceId,
+          hostId,
+          'execution',
+          'execute',
+          [{ pluginId, handlerRef, exportName, input, executionId, requestId, timeoutMs }],
+        ),
+      );
+
+      writeEvent({
+        type: 'execution:done',
+        requestId,
+        executionId,
+        exitCode: 0,
+        durationMs: Date.now() - startTime,
+        metadata: { result: result as Record<string, unknown> },
+      });
+    } catch (err) {
+      if (err instanceof CancelledError) {
+        writeEvent({
+          type: 'execution:cancelled',
+          requestId,
+          executionId,
+          reason: err.reason ?? 'user',
+          durationMs: Date.now() - startTime,
+        });
+
+        writeEvent({
+          type: 'execution:done',
+          requestId,
+          executionId,
+          exitCode: 130,
+          durationMs: Date.now() - startTime,
+        });
+      } else {
+        const message = err instanceof Error ? err.message : String(err);
+        logDiagnosticEvent(logger, {
+          domain: 'service',
+          event: 'gateway.execution.dispatch',
+          level: 'error',
+          reasonCode: 'execution_dispatch_failed',
+          message: 'Gateway execution dispatch failed',
+          outcome: 'failed',
+          error: err instanceof Error ? err : new Error(String(err)),
+          serviceId: 'gateway',
+          evidence: {
+            namespaceId: auth.namespaceId,
+            executionId,
+            requestId,
+            pluginId,
+            handlerRef,
+            hostId,
+          },
+        });
+
+        writeEvent({
+          type: 'execution:error',
+          requestId,
+          executionId,
+          code: 'EXECUTION_FAILED',
+          message,
+          retryable: false,
+        });
+
+        writeEvent({
+          type: 'execution:done',
+          requestId,
+          executionId,
+          exitCode: 1,
+          durationMs: Date.now() - startTime,
+        });
+      }
+    } finally {
+      executionRegistry.remove(executionId);
+      if (!reply.raw.writableEnded) {
+        reply.raw.end();
+      }
+    }
+  });
+
+  /**
+   * POST /api/v1/execute/:executionId/cancel
+   */
+  app.post('/api/v1/execute/:executionId/cancel', { schema: { tags: ['Execute'], summary: 'Cancel an active execution' } }, async (request: FastifyRequest, reply: FastifyReply) => {
+    const auth = request.authContext;
+    if (!auth) {
+      return reply.code(401).send({ error: 'Unauthorized' });
+    }
+
+    const { executionId } = request.params as { executionId: string };
+    const body = request.body as { reason?: string } | undefined;
+    const reason = (body?.reason ?? 'user') as CancellationReason;
+
+    const execution = executionRegistry.get(executionId);
+    if (!execution) {
+      return reply.code(404).send({ error: 'Execution not found or already completed' });
+    }
+
+    if (execution.namespaceId !== auth.namespaceId) {
+      return reply.code(403).send({ error: 'Forbidden — execution belongs to another namespace' });
+    }
+
+    const cancelled = executionRegistry.cancel(executionId, reason);
+
+    logger.info('Cancel request processed', {
+      executionId,
+      reason,
+      cancelled,
+      namespaceId: auth.namespaceId,
+    });
+
+    return reply.code(cancelled ? 200 : 409).send({
+      executionId,
+      status: cancelled ? 'cancelled' : 'already_cancelled',
+      reason,
+    });
+  });
+}

package/src/hosts/dispatcher.ts

@@ -0,0 +1,2 @@
+// Re-export from gateway-core for backward compatibility within this app
+export { HostCallDispatcher, globalDispatcher } from '@kb-labs/gateway-core';