@kb-labs/rest-api-app 1.3.0 → 1.4.0

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

@@ -1,244 +0,0 @@
-/**
- * @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

@@ -1,58 +0,0 @@
-/**
- * @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

@@ -1,113 +0,0 @@
-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

@@ -1,15 +0,0 @@
-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

@@ -1,42 +0,0 @@
-/**
- * @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

@@ -1,20 +0,0 @@
-/**
- * @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

@@ -1,81 +0,0 @@
-/**
- * @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

@@ -1,105 +0,0 @@
-#!/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

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