@kb-labs/rest-api-app 1.3.0

package/src/services/system-metrics-collector.ts

@@ -0,0 +1,244 @@
+/**
+ * @module @kb-labs/rest-api-app/services/system-metrics-collector
+ * System metrics collector for REST API instances.
+ *
+ * Collects CPU, memory, uptime, and load average metrics from the current instance
+ * and writes them to platform.cache with TTL for automatic cleanup.
+ */
+
+import { platform } from '@kb-labs/core-runtime';
+import * as os from 'node:os';
+import * as process from 'node:process';
+import { monitorEventLoopDelay } from 'node:perf_hooks';
+import { updateRuntimeObservabilityMetrics } from '../middleware/prom-metrics.js';
+
+let latestSystemMetricsSnapshot: SystemMetrics | null = null;
+
+/**
+ * System metrics data structure
+ */
+export interface SystemMetrics {
+  /** Instance identifier (hostname) */
+  instanceId: string;
+
+  /** Timestamp when metrics were collected (ms since epoch) */
+  timestamp: number;
+
+  /** CPU usage information */
+  cpu: {
+    /** User CPU time in microseconds */
+    user: number;
+    /** System CPU time in microseconds */
+    system: number;
+    /** CPU usage percentage (0-100) */
+    percentage: number;
+  };
+
+  /** Memory usage information */
+  memory: {
+    /** Resident Set Size (bytes) - total memory allocated */
+    rss: number;
+    /** Heap total (bytes) - allocated heap */
+    heapTotal: number;
+    /** Heap used (bytes) - actual heap used */
+    heapUsed: number;
+    /** External memory (bytes) - C++ objects bound to JS */
+    external: number;
+    /** Array buffers (bytes) */
+    arrayBuffers: number;
+    /** RSS usage percentage (0-100) */
+    rssPercentage: number;
+    /** Heap usage percentage (0-100) */
+    heapPercentage: number;
+  };
+
+  /** Process uptime (seconds) */
+  uptime: number;
+  eventLoopLagMs: number;
+  activeOperations: number;
+
+  /** System load average (1, 5, 15 minutes) */
+  loadAvg: [number, number, number];
+
+  /** Total system memory (bytes) */
+  totalMemory: number;
+
+  /** Free system memory (bytes) */
+  freeMemory: number;
+}
+
+function toFiniteNumber(value: number): number {
+  return Number.isFinite(value) ? value : 0;
+}
+
+/**
+ * System metrics collector
+ * Periodically collects system metrics and writes to platform.cache
+ */
+export class SystemMetricsCollector {
+  private intervalId: NodeJS.Timeout | null = null;
+  private instanceId: string;
+  private lastCpuUsage = process.cpuUsage();
+  private lastCpuTime = Date.now();
+  private eventLoopDelay = monitorEventLoopDelay({ resolution: 20 });
+  private latestMetrics: SystemMetrics | null = null;
+
+  constructor(
+    private readonly serviceId: string = 'rest',
+    private readonly getActiveOperations: () => number = () => 0,
+  ) {
+    this.instanceId = `${os.hostname()}:${process.pid}`;
+  }
+
+  /**
+   * Calculate CPU percentage based on delta
+   */
+  private calculateCpuPercentage(): number {
+    const currentUsage = process.cpuUsage(this.lastCpuUsage);
+    const currentTime = Date.now();
+    const deltaTime = currentTime - this.lastCpuTime;
+
+    // Update for next calculation
+    this.lastCpuUsage = process.cpuUsage();
+    this.lastCpuTime = currentTime;
+
+    // Calculate CPU percentage
+    // cpuUsage() returns microseconds, convert to milliseconds and calculate percentage
+    const cpuTimeMs = (currentUsage.user + currentUsage.system) / 1000;
+    const percentage = (cpuTimeMs / deltaTime) * 100;
+
+    // Cap at 100% (can exceed on multi-core systems)
+    return Math.min(percentage, 100);
+  }
+
+  /**
+   * Collect current system metrics
+   */
+  private collectMetrics(): SystemMetrics {
+    const memoryUsage = process.memoryUsage();
+    const totalMemory = os.totalmem();
+    const heapPercentageRaw =
+      memoryUsage.heapTotal > 0 ? (memoryUsage.heapUsed / memoryUsage.heapTotal) * 100 : 0;
+    const eventLoopLagMs = toFiniteNumber(Number((this.eventLoopDelay.mean / 1_000_000).toFixed(2)));
+    const cpuPercentage = toFiniteNumber(this.calculateCpuPercentage());
+
+    return {
+      instanceId: this.instanceId,
+      timestamp: Date.now(),
+      cpu: {
+        user: this.lastCpuUsage.user,
+        system: this.lastCpuUsage.system,
+        percentage: cpuPercentage,
+      },
+      memory: {
+        rss: memoryUsage.rss,
+        heapTotal: memoryUsage.heapTotal,
+        heapUsed: memoryUsage.heapUsed,
+        external: memoryUsage.external,
+        arrayBuffers: memoryUsage.arrayBuffers,
+        rssPercentage: toFiniteNumber((memoryUsage.rss / totalMemory) * 100),
+        heapPercentage: toFiniteNumber(heapPercentageRaw),
+      },
+      uptime: process.uptime(),
+      eventLoopLagMs,
+      activeOperations: this.getActiveOperations(),
+      loadAvg: os.loadavg() as [number, number, number],
+      totalMemory,
+      freeMemory: os.freemem(),
+    };
+  }
+
+  /**
+   * Start collecting metrics at regular intervals
+   * @param intervalMs - Collection interval in milliseconds (default: 10000ms = 10s)
+   * @param ttlMs - Time-to-live for cache entries (default: 60000ms = 60s)
+   */
+  async start(intervalMs: number = 10000, ttlMs: number = 60000): Promise<void> {
+    if (this.intervalId) {
+      platform.logger.warn('SystemMetricsCollector already started');
+      return;
+    }
+
+    platform.logger.info('Starting system metrics collector', {
+      serviceId: this.serviceId,
+      instanceId: this.instanceId,
+      intervalMs,
+      ttlMs,
+    });
+
+    this.eventLoopDelay.enable();
+
+    // Collect immediately on start
+    await this.collect(ttlMs);
+
+    // Then collect at intervals
+    this.intervalId = setInterval(async () => {
+      await this.collect(ttlMs);
+    }, intervalMs);
+  }
+
+  /**
+   * Collect metrics and write to cache
+   */
+  private async collect(ttlMs: number): Promise<void> {
+    try {
+      const metrics = this.collectMetrics();
+      this.latestMetrics = metrics;
+      latestSystemMetricsSnapshot = metrics;
+
+      // Write to platform.cache with TTL
+      // Key pattern: system-metrics:{instanceId}
+      await platform.cache.set(
+        `system-metrics:${this.instanceId}`,
+        metrics,
+        ttlMs
+      );
+
+      updateRuntimeObservabilityMetrics({
+        cpuPercent: metrics.cpu.percentage,
+        rssBytes: metrics.memory.rss,
+        heapUsedBytes: metrics.memory.heapUsed,
+        eventLoopLagMs: metrics.eventLoopLagMs,
+        activeOperations: metrics.activeOperations,
+      });
+
+      platform.logger.debug('System metrics collected', {
+        serviceId: this.serviceId,
+        instanceId: this.instanceId,
+        cpu: metrics.cpu.percentage.toFixed(1) + '%',
+        memory: metrics.memory.rssPercentage.toFixed(1) + '%',
+        eventLoopLagMs: metrics.eventLoopLagMs,
+        activeOperations: metrics.activeOperations,
+        uptime: Math.floor(metrics.uptime) + 's',
+      });
+
+      this.eventLoopDelay.reset();
+    } catch (error) {
+      platform.logger.error('Failed to collect system metrics', error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+
+  getInstanceId(): string {
+    return this.instanceId;
+  }
+
+  getLatestMetrics(): SystemMetrics | null {
+    return this.latestMetrics;
+  }
+
+  /**
+   * Stop collecting metrics
+   */
+  stop(): void {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+      platform.logger.info('System metrics collector stopped');
+    }
+    this.eventLoopDelay.disable();
+  }
+}
+
+export function getLatestSystemMetrics(): SystemMetrics | null {
+  return latestSystemMetricsSnapshot;
+}

package/src/types/fastify.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @module @kb-labs/rest-api-app/types/fastify
+ * Fastify type extensions
+ */
+
+import type { FastifyBaseLogger } from 'fastify/types/logger';
+import type { FastifySchema } from 'fastify/types/schema';
+import type { FastifyTypeProvider, FastifyTypeProviderDefault } from 'fastify/types/type-provider';
+import type { ContextConfigDefault, RawReplyDefaultExpression, RawRequestDefaultExpression, RawServerBase, RawServerDefault } from 'fastify/types/utils';
+import type { IEntityRegistry } from '@kb-labs/core-registry';
+import type { ReadinessState } from '../routes/readiness';
+import '@fastify/type-provider-typebox';
+import type { EventHub } from '../events/hub';
+
+declare module 'fastify/types/instance' {
+  interface FastifyInstance<
+    RawServer extends RawServerBase = RawServerDefault,
+    RawRequest extends RawRequestDefaultExpression<RawServer> = RawRequestDefaultExpression<RawServer>,
+    RawReply extends RawReplyDefaultExpression<RawServer> = RawReplyDefaultExpression<RawServer>,
+    Logger extends FastifyBaseLogger = FastifyBaseLogger,
+    TypeProvider extends FastifyTypeProvider = FastifyTypeProviderDefault,
+    SchemaCompiler extends FastifySchema = FastifySchema,
+    ContextConfig = ContextConfigDefault
+  > {
+    registry?: IEntityRegistry;
+    kbReadiness?: ReadinessState;
+    kbStartupGuard?: {
+      inFlight: number;
+    };
+    kbEventHub?: EventHub;
+  }
+}
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    registry?: IEntityRegistry;
+    kbReadiness?: ReadinessState;
+    kbStartupGuard?: {
+      inFlight: number;
+    };
+    kbEventHub?: EventHub;
+  }
+}
+
+declare module 'fastify/types/request' {
+  interface FastifyRequest {
+    mockMode?: boolean;
+    kbStartupGuardActive?: boolean;
+    kbStartupGuardTimer?: NodeJS.Timeout;
+    kbMetricsStart?: number;
+    kbHeaderState?: {
+      vary: Set<string>;
+      sensitive: Set<string>;
+      rateLimitKeys: Record<string, string>;
+      sanitized: Record<string, string>;
+    };
+  }
+}

package/src/utils/__tests__/sse-auth.spec.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { RestApiConfig } from '@kb-labs/rest-api-core';
+import { buildRegistrySseAuthHook } from '../sse-auth';
+
+function baseConfig(overrides: Partial<RestApiConfig> = {}): RestApiConfig {
+  const { events, ...rest } = overrides;
+  const config: RestApiConfig = {
+    port: 5050,
+    basePath: '/api/v1',
+    apiVersion: 'test',
+    cors: {
+      origins: [],
+      allowCredentials: true,
+      profile: 'dev',
+    },
+    plugins: [],
+    mockMode: false,
+    ...rest,
+    events: events
+      ? {
+          registry: events.registry
+            ? {
+                token: events.registry.token,
+                headerName: events.registry.headerName ?? 'authorization',
+                queryParam: events.registry.queryParam ?? 'access_token',
+              }
+            : undefined,
+        }
+      : undefined,
+  };
+  return config;
+}
+
+describe('buildRegistrySseAuthHook', () => {
+  it('returns undefined when auth is not configured', () => {
+    const hook = buildRegistrySseAuthHook(baseConfig());
+    expect(hook).toBeUndefined();
+  });
+
+  it('allows requests with valid bearer token', () => {
+    const hook = buildRegistrySseAuthHook(
+      baseConfig({
+        events: {
+          registry: {
+            token: 'secret',
+            headerName: 'authorization',
+            queryParam: 'access_token',
+          },
+        },
+      })
+    );
+    expect(hook).toBeDefined();
+    const done = vi.fn();
+    const request = {
+      headers: {
+        authorization: 'Bearer secret',
+      },
+      query: {},
+    };
+    const reply = {
+      code: vi.fn().mockReturnThis(),
+      header: vi.fn().mockReturnThis(),
+      send: vi.fn(),
+    };
+    hook?.(request as any, reply as any, done as any);
+    expect(done).toHaveBeenCalledTimes(1);
+    expect(reply.send).not.toHaveBeenCalled();
+  });
+
+  it('rejects requests with invalid token', () => {
+    const hook = buildRegistrySseAuthHook(
+      baseConfig({
+        events: {
+          registry: {
+            token: 'secret',
+            headerName: 'x-api-token',
+            queryParam: 'auth',
+          },
+        },
+      })
+    );
+    const done = vi.fn();
+    const request = {
+      headers: {
+        'x-api-token': 'wrong',
+      },
+      query: { auth: 'wrong' },
+    };
+    const reply = {
+      statusCode: undefined as number | undefined,
+      payload: undefined as unknown,
+      code(status: number) {
+        this.statusCode = status;
+        return this;
+      },
+      header() {
+        return this;
+      },
+      send(payload: unknown) {
+        this.payload = payload;
+      },
+    };
+    hook?.(request as any, reply as any, done as any);
+    expect(done).not.toHaveBeenCalled();
+    expect(reply.statusCode).toBe(401);
+    expect(reply.payload).toMatchObject({
+      status: 'unauthorized',
+      reason: 'invalid_token',
+    });
+  });
+});
+
+

package/src/utils/path-helpers.ts

@@ -0,0 +1,15 @@
+export function normalizeBasePath(basePath?: string): string {
+  if (!basePath || basePath === '/') {
+    return '';
+  }
+  return basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
+}
+
+export function resolvePaths(basePath: string, route: string): string[] {
+  const normalizedRoute = route.startsWith('/') ? route : `/${route}`;
+  if (!basePath) {
+    return [normalizedRoute];
+  }
+  const base = normalizeBasePath(basePath);
+  return Array.from(new Set([normalizedRoute, `${base}${normalizedRoute}`]));
+}

package/src/utils/repo.ts

@@ -0,0 +1,42 @@
+/**
+ * @module @kb-labs/rest-api-app/utils/repo
+ * Repository utilities
+ */
+
+import * as path from 'node:path';
+import { promises as fs } from 'node:fs';
+
+/**
+ * Find monorepo root (prefer pnpm-workspace.yaml or .git over package.json)
+ */
+export async function findMonorepoRoot(startDir: string): Promise<string> {
+  let dir = path.resolve(startDir);
+  let foundRoot: string | null = null;
+  
+  while (true) {
+    try {
+      const hasGit = await fs.access(path.join(dir, '.git')).then(() => true).catch(() => false);
+      const hasWorkspace = await fs.access(path.join(dir, 'pnpm-workspace.yaml')).then(() => true).catch(() => false);
+      
+      if (hasGit && hasWorkspace) {
+        foundRoot = dir;
+      }
+    } catch {
+      // Continue
+    }
+    
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+  
+  if (foundRoot) {
+    return foundRoot;
+  }
+  
+  // Fallback: use startDir
+  return path.resolve(startDir);
+}
+

package/src/utils/schema.ts

@@ -0,0 +1,20 @@
+/**
+ * @module @kb-labs/rest-api-app/utils/schema
+ * Schema utilities for Fastify routes.
+ * Route-level Zod schemas live in @kb-labs/rest-api-contracts/route-schemas.
+ */
+
+/**
+ * Error response schema for Fastify's built-in error serialization.
+ * Used in non-Zod routes (health, metrics, internal).
+ */
+export const errorSchema = {
+  type: 'object',
+  properties: {
+    statusCode: { type: 'number' },
+    error: { type: 'string' },
+    message: { type: 'string' },
+    code: { type: 'string' },
+  },
+  additionalProperties: true,
+} as const;

package/src/utils/sse-auth.ts

@@ -0,0 +1,81 @@
+/**
+ * @module @kb-labs/rest-api-app/utils/sse-auth
+ * Helpers for SSE token validation
+ */
+
+import type { FastifyReply, FastifyRequest, HookHandlerDoneFunction } from 'fastify';
+import type { RestApiConfig } from '@kb-labs/rest-api-core';
+
+type RegistryAuthConfig = {
+  token: string;
+  headerName: string;
+  queryParam: string;
+};
+
+function extractTokenFromHeader(headerValue: unknown, headerName: string): string | undefined {
+  if (typeof headerValue === 'string') {
+    if (headerName === 'authorization') {
+      const match = headerValue.match(/^Bearer\s+(.+)$/i);
+      return match ? match[1] : undefined;
+    }
+    return headerValue;
+  }
+  if (Array.isArray(headerValue)) {
+    return headerValue[0];
+  }
+  return undefined;
+}
+
+function extractToken(request: FastifyRequest, config: RegistryAuthConfig): string | undefined {
+  const headerName = (config.headerName ?? 'authorization').toLowerCase();
+  const queryParam = config.queryParam ?? 'access_token';
+
+  const explicitHeader = extractTokenFromHeader(request.headers[headerName], headerName);
+  if (explicitHeader) {
+    return explicitHeader;
+  }
+
+  if (headerName !== 'authorization' && typeof request.headers.authorization === 'string') {
+    const fallback = extractTokenFromHeader(request.headers.authorization, 'authorization');
+    if (fallback) {
+      return fallback;
+    }
+  }
+
+  const query = request.query as Record<string, string | undefined>;
+  return query?.[queryParam] ?? query?.access_token;
+}
+
+export function buildRegistrySseAuthHook(config: RestApiConfig) {
+  const registryAuth = config.events?.registry;
+  if (!registryAuth?.token) {
+    return undefined;
+  }
+  const authConfig: RegistryAuthConfig = {
+    token: registryAuth.token,
+    headerName: registryAuth.headerName ?? 'authorization',
+    queryParam: registryAuth.queryParam ?? 'access_token',
+  };
+
+  return function registrySseAuthHook(
+    request: FastifyRequest,
+    reply: FastifyReply,
+    done: HookHandlerDoneFunction
+  ) {
+    const provided = extractToken(request, authConfig);
+    if (provided === authConfig.token) {
+      done();
+      return;
+    }
+
+    reply
+      .code(401)
+      .header('content-type', 'application/json')
+      .send({
+        status: 'unauthorized',
+        reason: 'invalid_token',
+      });
+  };
+}
+
+

package/test-sandbox.sh

@@ -0,0 +1,105 @@
+#!/bin/bash
+
+# Test script for KB Labs REST API with sandbox execution
+# Usage: ./test-sandbox.sh
+
+set -e
+
+echo "🧪 Testing KB Labs REST API Sandbox Execution"
+echo "=============================================="
+echo ""
+
+# Colors
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+API_URL="${API_URL:-http://localhost:3000}"
+BASE_PATH="/api/v1"
+
+echo "📡 API URL: ${API_URL}"
+echo ""
+
+# Test 1: Check if server is running
+echo "1️⃣  Testing server health..."
+if curl -s -f "${API_URL}${BASE_PATH}/health" > /dev/null; then
+    echo -e "${GREEN}✅ Server is running${NC}"
+else
+    echo -e "${RED}❌ Server is not running. Start it with: npm run dev${NC}"
+    exit 1
+fi
+
+# Test 2: Check plugin registry
+echo ""
+echo "2️⃣  Testing plugin registry..."
+REGISTRY_RESPONSE=$(curl -s "${API_URL}${BASE_PATH}/plugins/registry")
+if echo "$REGISTRY_RESPONSE" | grep -q "mind"; then
+    echo -e "${GREEN}✅ Mind plugin found in registry${NC}"
+    echo "   Found plugins: $(echo "$REGISTRY_RESPONSE" | jq -r '.manifests[].id' 2>/dev/null || echo 'unknown')"
+else
+    echo -e "${YELLOW}⚠️  Mind plugin not found in registry${NC}"
+    echo "   Response: $REGISTRY_RESPONSE"
+fi
+
+# Test 3: Test Mind query endpoint (sandbox execution)
+echo ""
+echo "3️⃣  Testing Mind query endpoint (sandbox execution)..."
+QUERY_RESPONSE=$(curl -s -X POST "${API_URL}${BASE_PATH}/plugins/mind/query" \
+    -H "Content-Type: application/json" \
+    -d '{
+        "query": "meta",
+        "params": {},
+        "options": {
+            "cwd": ".",
+            "json": true
+        }
+    }')
+
+if echo "$QUERY_RESPONSE" | grep -q "ok"; then
+    echo -e "${GREEN}✅ Query endpoint responded successfully${NC}"
+    echo "   Response structure:"
+    echo "$QUERY_RESPONSE" | jq '.' 2>/dev/null || echo "$QUERY_RESPONSE"
+else
+    echo -e "${RED}❌ Query endpoint failed${NC}"
+    echo "   Response: $QUERY_RESPONSE"
+fi
+
+# Test 4: Check for sandbox execution metrics
+echo ""
+echo "4️⃣  Checking for execution metrics..."
+if echo "$QUERY_RESPONSE" | grep -q "meta"; then
+    echo -e "${GREEN}✅ Execution metrics found${NC}"
+    METRICS=$(echo "$QUERY_RESPONSE" | jq -r '.meta.exec' 2>/dev/null || echo '{}')
+    echo "   Metrics: $METRICS"
+else
+    echo -e "${YELLOW}⚠️  No metrics found in response${NC}"
+fi
+
+# Test 5: Test error handling (invalid request)
+echo ""
+echo "5️⃣  Testing error handling..."
+ERROR_RESPONSE=$(curl -s -X POST "${API_URL}${BASE_PATH}/plugins/mind/query" \
+    -H "Content-Type: application/json" \
+    -d '{
+        "invalid": "request"
+    }')
+
+if echo "$ERROR_RESPONSE" | grep -q "error\|status.*error"; then
+    echo -e "${GREEN}✅ Error handling works${NC}"
+    echo "   Error response:"
+    echo "$ERROR_RESPONSE" | jq '.' 2>/dev/null || echo "$ERROR_RESPONSE"
+else
+    echo -e "${YELLOW}⚠️  Unexpected error response format${NC}"
+    echo "   Response: $ERROR_RESPONSE"
+fi
+
+echo ""
+echo "=============================================="
+echo -e "${GREEN}✅ Sandbox execution test complete!${NC}"
+echo ""
+echo "💡 Tips:"
+echo "   - Set KB_PLUGIN_DEV_MODE=true for in-process execution"
+echo "   - Check logs for detailed execution info"
+echo "   - Use --json flag in plugin responses for AI agents"
+

package/tsconfig.build.json

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