@kb-labs/rest-api-app 1.3.0

package/src/routes/workflows.ts

@@ -0,0 +1,256 @@
+/**
+ * @module @kb-labs/rest-api-app/routes/workflows
+ * Workflow SSE streaming endpoint.
+ *
+ * All CRUD operations (list runs, get run, cancel, run workflow) are handled
+ * by the workflow plugin via plugin routes (/plugins/workflow/...).
+ * This file only provides the SSE event stream which requires a long-lived
+ * connection that cannot go through the plugin execution backend.
+ */
+
+import type { FastifyInstance } from 'fastify'
+import type { RestApiConfig } from '@kb-labs/rest-api-core'
+import { WORKFLOW_REDIS_CHANNEL } from '@kb-labs/workflow-constants'
+import { platform } from '@kb-labs/core-runtime'
+import { normalizeBasePath } from '../utils/path-helpers'
+
+const TERMINAL_EVENT_TYPES = ['run.finished', 'run.failed', 'run.cancelled']
+const KEEP_ALIVE_MS = 30_000
+const IDLE_TIMEOUT_MS = 60_000
+const EVENT_BUS_KEY = `eventbus:${WORKFLOW_REDIS_CHANNEL}`
+
+/**
+ * Replay past events for a runId from the Redis sorted set.
+ * Returns true if a terminal event was found (run already finished).
+ */
+async function replayHistory(
+  runId: string,
+  sendEvent: (type: string, payload: unknown, timestamp?: string) => void,
+): Promise<boolean> {
+  let hasTerminal = false
+  try {
+    const cache = platform.cache
+    if (!cache?.zrangebyscore) {return false}
+
+    const stored = await cache.zrangebyscore(EVENT_BUS_KEY, 0, Date.now())
+    for (const raw of stored) {
+      try {
+        const wrapper = JSON.parse(raw) as { data: { type: string; runId: string; payload?: unknown; timestamp?: string } }
+        const event = wrapper.data
+        if (event.runId !== runId) {continue}
+        sendEvent(event.type, event.payload, event.timestamp)
+        if (TERMINAL_EVENT_TYPES.includes(event.type)) {
+          hasTerminal = true
+        }
+      } catch { /* skip malformed entries */ }
+    }
+  } catch { /* cache unavailable — skip replay */ }
+  return hasTerminal
+}
+
+export async function registerWorkflowRoutes(
+  server: FastifyInstance,
+  config: RestApiConfig,
+): Promise<void> {
+  const basePath = normalizeBasePath(config.basePath)
+
+  // SSE stream of workflow run events via shared IEventBus.
+  // No local engine needed — events arrive through the distributed event bus
+  // (state broker / Redis / Kafka). The daemon publishes, we subscribe.
+  server.route({
+    method: 'GET',
+    url: `${basePath}/workflows/runs/:runId/events`,
+    handler: async (request, reply) => {
+      const runId = getRunId(request.params)
+
+      // SSE response — hijack from Fastify
+      reply.hijack()
+      const raw = reply.raw
+
+      const origin = request.headers.origin
+      if (typeof origin === 'string' && (origin === 'http://localhost:3000' || origin === 'http://localhost:5173')) {
+        raw.setHeader('Access-Control-Allow-Origin', origin)
+        raw.setHeader('Access-Control-Allow-Credentials', 'true')
+      }
+      raw.setHeader('Content-Type', 'text/event-stream')
+      raw.setHeader('Cache-Control', 'no-cache, no-transform')
+      raw.setHeader('Connection', 'keep-alive')
+      raw.flushHeaders?.()
+      raw.write(': connected\n\n')
+
+      const sentIds = new Set<string>()
+
+      const sendEvent = (type: string, payload: unknown, timestamp?: string) => {
+        if (raw.writableEnded) {return}
+        const data = { type, runId, payload, timestamp: timestamp ?? new Date().toISOString() }
+        // Dedup by type+timestamp to avoid replaying events that also arrive live
+        const dedup = `${type}:${data.timestamp}`
+        if (sentIds.has(dedup)) {return}
+        sentIds.add(dedup)
+        raw.write(`event: workflow.event\n`)
+        raw.write(`data: ${JSON.stringify(data)}\n\n`)
+      }
+
+      // Replay history — send past events for this run
+      const alreadyFinished = await replayHistory(runId, sendEvent)
+      if (alreadyFinished) {
+        raw.end()
+        return
+      }
+
+      let idleTimer: ReturnType<typeof setTimeout> | null = null
+
+      const resetIdle = () => {
+        if (idleTimer) {clearTimeout(idleTimer)}
+        idleTimer = setTimeout(() => {
+          cleanup()
+        }, IDLE_TIMEOUT_MS)
+      }
+
+      const keepAliveTimer = setInterval(() => {
+        if (raw.writableEnded) {return}
+        raw.write(': keep-alive\n\n')
+      }, KEEP_ALIVE_MS)
+
+      const unsubscribe = platform.eventBus.subscribe(WORKFLOW_REDIS_CHANNEL, async (rawEvent: unknown) => {
+        const event = rawEvent as { type: string; runId: string; payload?: unknown; timestamp?: string }
+        if (event.runId !== runId) {return}
+        sendEvent(event.type, event.payload, event.timestamp)
+        resetIdle()
+        if (TERMINAL_EVENT_TYPES.includes(event.type)) {
+          cleanup()
+        }
+      })
+
+      const cleanup = () => {
+        unsubscribe()
+        if (idleTimer) {clearTimeout(idleTimer)}
+        clearInterval(keepAliveTimer)
+        if (!raw.writableEnded) {
+          raw.write(`event: workflow.done\ndata: {}\n\n`)
+          raw.end()
+        }
+      }
+
+      resetIdle()
+      request.raw.on('close', cleanup)
+    },
+  })
+
+  // SSE stream of workflow run logs via shared IEventBus.
+  // Sends all events for a run as `workflow.log` entries with jobId/stepId context.
+  server.route({
+    method: 'GET',
+    url: `${basePath}/workflows/runs/:runId/logs`,
+    handler: async (request, reply) => {
+      const runId = getRunId(request.params)
+      const query = request.query as { idleTimeoutMs?: string }
+      const idleTimeout = query.idleTimeoutMs ? parseInt(query.idleTimeoutMs, 10) : IDLE_TIMEOUT_MS
+
+      reply.hijack()
+      const raw = reply.raw
+
+      const origin = request.headers.origin
+      if (typeof origin === 'string' && (origin === 'http://localhost:3000' || origin === 'http://localhost:5173')) {
+        raw.setHeader('Access-Control-Allow-Origin', origin)
+        raw.setHeader('Access-Control-Allow-Credentials', 'true')
+      }
+      raw.setHeader('Content-Type', 'text/event-stream')
+      raw.setHeader('Cache-Control', 'no-cache, no-transform')
+      raw.setHeader('Connection', 'keep-alive')
+      raw.flushHeaders?.()
+      raw.write(': connected\n\n')
+
+      const sentLogIds = new Set<string>()
+
+      const sendLog = (event: { type: string; runId: string; jobId?: string; stepId?: string; payload?: unknown; timestamp?: string }) => {
+        if (raw.writableEnded) {return}
+        const ts = event.timestamp ?? new Date().toISOString()
+        const dedup = `${event.type}:${event.jobId ?? ''}:${event.stepId ?? ''}:${ts}`
+        if (sentLogIds.has(dedup)) {return}
+        sentLogIds.add(dedup)
+        raw.write(`event: workflow.log\n`)
+        raw.write(`data: ${JSON.stringify({
+          type: event.type,
+          runId: event.runId,
+          jobId: event.jobId,
+          stepId: event.stepId,
+          payload: event.payload,
+          timestamp: ts,
+        })}\n\n`)
+      }
+
+      // Replay history for logs
+      let logsAlreadyFinished = false
+      try {
+        const cache = platform.cache
+        if (cache?.zrangebyscore) {
+          const stored = await cache.zrangebyscore(EVENT_BUS_KEY, 0, Date.now())
+          for (const rawStr of stored) {
+            try {
+              const wrapper = JSON.parse(rawStr) as { data: { type: string; runId: string; jobId?: string; stepId?: string; payload?: unknown; timestamp?: string } }
+              const ev = wrapper.data
+              if (ev.runId !== runId) {continue}
+              sendLog(ev)
+              if (TERMINAL_EVENT_TYPES.includes(ev.type)) {logsAlreadyFinished = true}
+            } catch { /* skip */ }
+          }
+        }
+      } catch { /* cache unavailable */ }
+
+      if (logsAlreadyFinished) {
+        raw.write(`event: workflow.done\ndata: {}\n\n`)
+        raw.end()
+        return
+      }
+
+      let idleTimer: ReturnType<typeof setTimeout> | null = null
+
+      const resetIdle = () => {
+        if (idleTimer) {clearTimeout(idleTimer)}
+        idleTimer = setTimeout(() => {
+          cleanup()
+        }, idleTimeout)
+      }
+
+      const keepAliveTimer = setInterval(() => {
+        if (raw.writableEnded) {return}
+        raw.write(': keep-alive\n\n')
+      }, KEEP_ALIVE_MS)
+
+      const unsubscribe = platform.eventBus.subscribe(WORKFLOW_REDIS_CHANNEL, async (rawEvent: unknown) => {
+        const event = rawEvent as { type: string; runId: string; jobId?: string; stepId?: string; payload?: unknown; timestamp?: string }
+        if (event.runId !== runId) {return}
+        sendLog(event)
+        resetIdle()
+        if (TERMINAL_EVENT_TYPES.includes(event.type)) {
+          cleanup()
+        }
+      })
+
+      const cleanup = () => {
+        unsubscribe()
+        if (idleTimer) {clearTimeout(idleTimer)}
+        clearInterval(keepAliveTimer)
+        if (!raw.writableEnded) {
+          raw.write(`event: workflow.done\ndata: {}\n\n`)
+          raw.end()
+        }
+      }
+
+      resetIdle()
+      request.raw.on('close', cleanup)
+    },
+  })
+}
+
+function getRunId(params: unknown): string {
+  const runId = (params as { runId?: unknown } | undefined)?.runId
+  if (!runId || typeof runId !== 'string') {
+    const error = new Error('runId must be provided')
+    ;(error as any).statusCode = 400
+    ;(error as any).code = 'WF_RUN_ID_REQUIRED'
+    throw error
+  }
+  return runId
+}

package/src/server.ts

@@ -0,0 +1,203 @@
+/**
+ * @module @kb-labs/rest-api-app/server
+ * Fastify server setup
+ */
+
+import Fastify from 'fastify';
+import type { FastifyInstance } from 'fastify';
+import type { RestApiConfig } from '@kb-labs/rest-api-core';
+import type { IEntityRegistry } from '@kb-labs/core-registry';
+import { registerRoutes } from './routes/index';
+import { registerPlugins } from './plugins/index';
+import { registerMiddleware } from './middleware/index';
+import { platform } from '@kb-labs/core-runtime';
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
+import type { ILogger } from '@kb-labs/core-platform';
+
+/**
+ * Fastify internal symbol to disable request logging
+ */
+const kDisableRequestLogging = Symbol.for('fastify.disableRequestLogging');
+
+/**
+ * Create a Pino-compatible wrapper for ILogger
+ * Fastify 5 expects a Pino instance, but we want vendor independence
+ */
+function createPinoCompatibleLogger(logger: ILogger): any {
+  const levels = {
+    trace: 10,
+    debug: 20,
+    info: 30,
+    warn: 40,
+    error: 50,
+    fatal: 60,
+  };
+
+  return {
+    // Pino log levels
+    trace: (msg: string | object, ...args: any[]) => {
+      if (typeof msg === 'object') {
+        logger.debug(JSON.stringify(msg), msg as Record<string, unknown>);
+      } else {
+        logger.debug(msg, ...args);
+      }
+    },
+    debug: (msg: string | object, ...args: any[]) => {
+      if (typeof msg === 'object') {
+        logger.debug(JSON.stringify(msg), msg as Record<string, unknown>);
+      } else {
+        logger.debug(msg, ...args);
+      }
+    },
+    info: (msg: string | object, ...args: any[]) => {
+      if (typeof msg === 'object') {
+        logger.info(JSON.stringify(msg), msg as Record<string, unknown>);
+      } else {
+        logger.info(msg, ...args);
+      }
+    },
+    warn: (msg: string | object, ...args: any[]) => {
+      if (typeof msg === 'object') {
+        logger.warn(JSON.stringify(msg), msg as Record<string, unknown>);
+      } else {
+        logger.warn(msg, ...args);
+      }
+    },
+    error: (msg: string | object, ...args: any[]) => {
+      if (typeof msg === 'object') {
+        logger.error(JSON.stringify(msg), msg instanceof Error ? msg : undefined);
+      } else {
+        logger.error(msg, args[0] instanceof Error ? args[0] : undefined);
+      }
+    },
+    fatal: (msg: string | object, ...args: any[]) => {
+      if (typeof msg === 'object') {
+        logger.error(`[FATAL] ${JSON.stringify(msg)}`, msg instanceof Error ? msg : undefined);
+      } else {
+        logger.error(`[FATAL] ${msg}`, args[0] instanceof Error ? args[0] : undefined);
+      }
+    },
+    // Pino child method
+    child: (bindings: Record<string, unknown>) => {
+      const childLogger = logger.child(bindings);
+      return createPinoCompatibleLogger(childLogger);
+    },
+    // Pino required properties for Fastify 5
+    level: 'info',
+    levels: {
+      values: levels,
+      labels: { 10: 'trace', 20: 'debug', 30: 'info', 40: 'warn', 50: 'error', 60: 'fatal' },
+    },
+    silent: false,
+    // Pino version symbol (required by Fastify 5 validation)
+    [Symbol.for('pino.version')]: '8.0.0',
+  };
+}
+
+/**
+ * Create and configure Fastify server
+ */
+export async function createServer(
+  config: RestApiConfig,
+  repoRoot: string,
+  registry: IEntityRegistry
+): Promise<FastifyInstance> {
+  // HTTP/2 configuration (requires HTTPS)
+  const useHttp2 = config.http2?.enabled ?? false;
+  const allowHTTP1 = config.http2?.allowHTTP1 ?? true;
+
+  // SSL configuration
+  let httpsOptions: { allowHTTP1: boolean; key: Buffer; cert: Buffer } | undefined;
+  if (useHttp2 && config.ssl?.keyPath && config.ssl?.certPath) {
+    const keyPath = config.ssl.keyPath;
+    const certPath = config.ssl.certPath;
+
+    if (existsSync(keyPath) && existsSync(certPath)) {
+      httpsOptions = {
+        allowHTTP1,
+        key: readFileSync(keyPath),
+        cert: readFileSync(certPath),
+      };
+    } else {
+      platform.logger.warn('HTTP/2 enabled but SSL certificates not found, falling back to HTTP/1.1', {
+        keyPath,
+        certPath,
+      });
+    }
+  }
+
+  // Create platform logger child for REST layer
+  const restLogger = platform.logger.child({
+    layer: 'rest',
+    service: 'server',
+    traceId: randomUUID(),
+  });
+
+  // Fastify 5 is too strict with logger validation, so disable it and use hooks
+  const server = useHttp2 && httpsOptions
+    ? Fastify({
+        logger: false,
+        requestIdHeader: 'X-Request-Id',
+        requestIdLogLabel: 'requestId',
+        disableRequestLogging: true,
+        requestTimeout: config.timeouts?.requestTimeout || 30000,
+        bodyLimit: config.timeouts?.bodyLimit || 10485760,
+        http2: true,
+        https: httpsOptions,
+      })
+    : Fastify({
+        logger: false,
+        requestIdHeader: 'X-Request-Id',
+        requestIdLogLabel: 'requestId',
+        disableRequestLogging: true,
+        requestTimeout: config.timeouts?.requestTimeout || 30000,
+        bodyLimit: config.timeouts?.bodyLimit || 10485760,
+      });
+
+  // Add our own logger to server instance
+  (server as any).log = restLogger;
+
+  // Override child logger factory to return our custom logger with disable flag
+  server.setChildLoggerFactory((logger, bindings, opts, rawReq) => {
+    const customLogger = {
+      [kDisableRequestLogging]: true, // Disable Fastify's built-in request logging
+      debug: (obj: any, msg?: string) => {},
+      info: (obj: any, msg?: string) => {},
+      warn: (obj: any, msg?: string) => {},
+      error: (obj: any, msg?: string) => {},
+      fatal: (obj: any, msg?: string) => {},
+      trace: (obj: any, msg?: string) => {},
+      child: () => customLogger,
+      level: 'silent',
+    };
+    return customLogger as any;
+  });
+
+  // Log protocol being used
+  if (useHttp2 && httpsOptions) {
+    restLogger.info('HTTP/2 enabled with HTTPS', {
+      allowHTTP1Fallback: allowHTTP1,
+    });
+  } else if (useHttp2) {
+    restLogger.warn('HTTP/2 requested but SSL certificates missing, using HTTP/1.1');
+  } else {
+    restLogger.info('Using HTTP/1.1');
+  }
+
+  // Store registry in server instance
+  server.registry = registry;
+
+  // Register plugins
+  await registerPlugins(server as unknown as FastifyInstance, config);
+
+  // Register middleware
+  registerMiddleware(server as unknown as FastifyInstance, config);
+
+  // Register routes
+  await registerRoutes(server as unknown as FastifyInstance, config, repoRoot, registry);
+
+  return server as unknown as FastifyInstance;
+}
+