@kb-labs/gateway-app 0.2.0

package/src/telemetry/routes.ts

@@ -0,0 +1,89 @@
+/**
+ * @module Telemetry Ingestion — unified event collection endpoint.
+ *
+ * Exposes `POST /telemetry/v1/ingest` for external products to send events.
+ * Events are written to platform analytics via IAnalytics.track().
+ * Auth required — tenantId extracted from auth context.
+ */
+import type { FastifyInstance } from 'fastify';
+import { platform } from '@kb-labs/core-runtime';
+import type { ILogger } from '@kb-labs/core-platform';
+import {
+  TelemetryIngestRequestSchema,
+  type TelemetryIngestResponse,
+} from '@kb-labs/gateway-contracts';
+
+/**
+ * Register telemetry ingestion routes on the given Fastify scope.
+ * The scope is expected to have the auth middleware already applied.
+ */
+export function registerTelemetryRoutes(app: FastifyInstance, logger: ILogger): void {
+  app.post('/telemetry/v1/ingest', { schema: { tags: ['Telemetry'], summary: 'Ingest telemetry events' } }, async (request, reply) => {
+    const auth = request.authContext;
+    if (!auth) {
+      return reply.code(401).send({ error: 'Unauthorized' });
+    }
+
+    const parsed = TelemetryIngestRequestSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.code(400).send({
+        error: 'Bad Request',
+        issues: parsed.error.issues,
+      });
+    }
+
+    const analytics = platform.analytics;
+    if (!analytics) {
+      return reply.code(503).send({
+        error: 'Analytics adapter not configured',
+      });
+    }
+
+    const { events } = parsed.data;
+    let accepted = 0;
+    let rejected = 0;
+    const errors: Array<{ index: number; message: string }> = [];
+
+    for (let i = 0; i < events.length; i++) {
+      const event = events[i]!;
+      try {
+        await analytics.track(event.type, {
+          // Source attribution — who sent this event
+          _source: event.source,
+          _tenantId: auth.namespaceId,
+          _ts: event.timestamp ?? new Date().toISOString(),
+          // Tags as flat properties for indexing
+          ...event.tags,
+          // Free-form payload
+          ...event.payload,
+        });
+        accepted++;
+      } catch (err) {
+        rejected++;
+        const message = err instanceof Error ? err.message : String(err);
+        errors.push({ index: i, message });
+        logger.warn('Telemetry event rejected', {
+          index: i,
+          type: event.type,
+          source: event.source,
+          error: message,
+        });
+      }
+    }
+
+    logger.info('Telemetry ingest', {
+      tenantId: auth.namespaceId,
+      accepted,
+      rejected,
+      totalEvents: events.length,
+    });
+
+    const response: TelemetryIngestResponse = {
+      accepted,
+      rejected,
+      ...(errors.length > 0 ? { errors } : {}),
+    };
+
+    return reply.code(accepted > 0 ? 200 : 422).send(response);
+  });
+}

package/src/ws/gateway-ws.ts

@@ -0,0 +1,73 @@
+/**
+ * @module gateway-app/ws/gateway-ws
+ *
+ * Unified WebSocket upgrade handler for the gateway.
+ *
+ * Intercepts upgrade requests BEFORE @fastify/http-proxy:
+ *   - Gateway-own WS paths (/hosts/connect, /clients/connect) → raw ws handlers
+ *   - Everything else → delegated to @fastify/http-proxy for upstream WS proxy
+ *
+ * This eliminates the conflict between @fastify/websocket and @fastify/http-proxy
+ * which both try to attach 'upgrade' listeners and call assignSocket().
+ */
+
+import type { Server, IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { WebSocketServer } from 'ws';
+import type { ICache, ILogger } from '@kb-labs/core-platform';
+import type { JwtConfig } from '@kb-labs/gateway-auth';
+import { createWsHandler } from '../hosts/ws-handler.js';
+import { createClientWsHandler } from '../clients/ws-handler.js';
+
+const GATEWAY_WS_PATHS = new Set(['/hosts/connect', '/clients/connect']);
+
+/**
+ * Attach gateway-own WebSocket endpoints using raw `ws` package.
+ *
+ * Must be called AFTER `app.ready()` (so http-proxy has registered its
+ * upgrade listener) but BEFORE `app.listen()`.
+ *
+ * Captures all existing 'upgrade' listeners, removes them, then installs
+ * a single unified handler that dispatches:
+ *   - Gateway WS paths → raw ws handlers
+ *   - All other paths → delegated to captured listeners (http-proxy)
+ */
+export function attachGatewayWs(
+  server: Server,
+  cache: ICache,
+  jwtConfig: JwtConfig,
+  logger: ILogger,
+  hostRegistry?: import('../hosts/registry.js').HostRegistry,
+): void {
+  const wss = new WebSocketServer({ noServer: true });
+  const hostsHandler = createWsHandler(cache, jwtConfig, logger, hostRegistry);
+  const clientsHandler = createClientWsHandler(cache, jwtConfig, logger);
+
+  // Capture @fastify/http-proxy's upgrade listener(s)
+  const existingListeners = server.listeners('upgrade').slice() as Array<
+    (req: IncomingMessage, socket: Duplex, head: Buffer) => void
+  >;
+  server.removeAllListeners('upgrade');
+
+  server.on('upgrade', (req: IncomingMessage, socket: Duplex, head: Buffer) => {
+    const pathname = new URL(req.url ?? '/', 'http://localhost').pathname;
+
+    if (GATEWAY_WS_PATHS.has(pathname)) {
+      // Gateway-own WS — handle directly with raw ws
+      wss.handleUpgrade(req, socket, head, (ws) => {
+        if (pathname === '/hosts/connect') {
+          hostsHandler(ws, req);
+        } else {
+          clientsHandler(ws, req);
+        }
+      });
+    } else {
+      // Delegate to @fastify/http-proxy for upstream WS proxy
+      for (const listener of existingListeners) {
+        listener.call(server, req, socket, head);
+      }
+    }
+  });
+
+  logger.info('Gateway WS endpoints attached', { paths: [...GATEWAY_WS_PATHS] });
+}

package/tsconfig.build.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "baseUrl": ".",
+    "paths": {}
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "dist",
+    "node_modules"
+  ]
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "@kb-labs/devkit/tsconfig/node.json",
+  "include": [
+    "src"
+  ],
+  "compilerOptions": {
+    "noEmit": true,
+    "types": ["node", "@fastify/swagger"]
+  }
+}

package/tsup.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'tsup';
+import nodePreset from '@kb-labs/devkit/tsup/node';
+
+export default defineConfig({
+  ...nodePreset,
+  tsconfig: 'tsconfig.build.json',
+  entry: ['src/index.ts'],
+});

package/vitest.config.ts

@@ -0,0 +1,23 @@
+import { mergeConfig } from 'vitest/config';
+import base from '@kb-labs/devkit/vitest/node.js';
+
+/**
+ * Gateway app vitest config.
+ *
+ * live-gateway.e2e.test.ts is excluded from the default test run because it
+ * requires a standalone Gateway instance (no upstream proxy for /api/v1).
+ * In the standard dev setup the gateway proxies /api/v1 to the REST API,
+ * which shadows the gateway's own execute routes.
+ *
+ * To run the live tests: vitest run src/__tests__/live-gateway.e2e.test.ts
+ */
+export default mergeConfig(base, {
+  test: {
+    exclude: [
+      '**/node_modules/**',
+      '**/dist/**',
+      '**/*.live.test.ts',
+      '**/live-gateway.e2e.test.ts',
+    ],
+  },
+});