@cyanautomation/kaseki-agent 1.4.1

package/src/kaseki-api-routes.ts

@@ -0,0 +1,643 @@
+import { Router, Request, Response, NextFunction } from 'express';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { randomUUID } from 'node:crypto';
+import { JobScheduler } from './job-scheduler';
+import { IdempotencyStore } from './idempotency-store';
+import { PreFlightValidator } from './pre-flight-validator';
+import { execDockerCommand } from './lib/subprocess-helpers';
+import {
+  RunRequestSchema,
+  RunResponse,
+  ValidationResponse,
+  PreflightCheck,
+  PreflightResponse,
+  Job,
+} from './kaseki-api-types';
+import { KasekiApiConfig, validateApiKey } from './kaseki-api-config';
+import { createEventLogger } from './logger';
+import { sendErrorResponse } from './utils/response-helpers';
+import { readFirstLine, commandOutput } from './utils/file-helpers';
+import { createStatusRoutes } from './routes/status-routes';
+import { createLogRoutes } from './routes/log-routes';
+import { createArtifactRoutes } from './routes/artifact-routes';
+import { createWebhookRoutes } from './routes/webhook-routes';
+import { metricsRegistry } from './metrics';
+import { ResultCache } from './result-cache';
+
+// Re-export UTF-8 helpers for backward compatibility
+export { decodeUtf8TailSafely, tailLogByLines, readTailBytes } from './utils/utf8-helpers';
+
+function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+  }
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function buildRequestFingerprint(runRequest: Record<string, unknown>): string {
+  const requestForFingerprint = { ...runRequest };
+  delete requestForFingerprint.idempotencyKey;
+  return crypto.createHash('sha256').update(stableStringify(requestForFingerprint)).digest('hex');
+}
+
+function readKasekiImage(templateDir = '/agents/kaseki-template'): string {
+  if (process.env.KASEKI_IMAGE) {
+    return process.env.KASEKI_IMAGE;
+  }
+  const imageFile = path.join(templateDir, '.kaseki-image');
+  try {
+    const value = fs.readFileSync(imageFile, 'utf-8').trim();
+    if (value) {
+      return value;
+    }
+  } catch {
+    // Fall through to the registry default.
+  }
+  return 'docker.io/cyanautomation/kaseki-agent:latest';
+}
+
+function inspectImageDigest(image: string): string | undefined {
+  return commandOutput('docker', ['image', 'inspect', image, '--format', '{{range .RepoDigests}}{{println .}}{{end}}'])
+    ?.split(/\r?\n/)
+    .find((line) => line.trim().length > 0);
+}
+
+// Re-export from subprocess-helpers for backward compatibility with tests
+export { classifyDockerFailure } from './lib/subprocess-helpers';
+
+function checkOpenRouterKey(): PreflightCheck {
+  if (process.env.OPENROUTER_API_KEY && process.env.OPENROUTER_API_KEY.length > 0) {
+    return { name: 'openrouter-key', ok: true, detail: 'OPENROUTER_API_KEY is present in the API environment.' };
+  }
+
+  const keyFile = process.env.OPENROUTER_API_KEY_FILE || '/run/secrets/openrouter_api_key';
+  try {
+    const stat = fs.statSync(keyFile);
+    if (stat.isFile() && stat.size > 0) {
+      return { name: 'openrouter-key', ok: true, detail: `Readable key file: ${keyFile}` };
+    }
+  } catch {
+    // Handled below.
+  }
+
+  return {
+    name: 'openrouter-key',
+    ok: false,
+    detail: 'No OpenRouter API key was found in env or the configured key file.',
+    remediation: 'Set OPENROUTER_API_KEY for API-triggered runs or mount OPENROUTER_API_KEY_FILE.',
+  };
+}
+
+function readSecretValue(inlineValue?: string, filePath?: string): string | undefined {
+  const trimmedInline = inlineValue?.trim();
+  if (trimmedInline) {
+    return trimmedInline;
+  }
+  if (!filePath) {
+    return undefined;
+  }
+  try {
+    const stat = fs.statSync(filePath);
+    if (!stat.isFile() || stat.size === 0) {
+      return undefined;
+    }
+    const value = fs.readFileSync(filePath, 'utf-8').replace(/^\uFEFF/, '').trim();
+    return value || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function checkGitHubAppCredentials(): PreflightCheck {
+  const configured =
+    Boolean(process.env.GITHUB_APP_ID || process.env.GITHUB_APP_ID_FILE) ||
+    Boolean(process.env.GITHUB_APP_CLIENT_ID || process.env.GITHUB_APP_CLIENT_ID_FILE) ||
+    Boolean(process.env.GITHUB_APP_PRIVATE_KEY || process.env.GITHUB_APP_PRIVATE_KEY_FILE);
+
+  if (!configured) {
+    return {
+      name: 'github-app',
+      ok: true,
+      detail: 'GitHub App credentials are not configured; PR creation will be disabled.',
+    };
+  }
+
+  const appId = readSecretValue(process.env.GITHUB_APP_ID, process.env.GITHUB_APP_ID_FILE);
+  const clientId = readSecretValue(process.env.GITHUB_APP_CLIENT_ID, process.env.GITHUB_APP_CLIENT_ID_FILE);
+  const privateKey =
+    process.env.GITHUB_APP_PRIVATE_KEY?.trim() ||
+    readSecretValue(undefined, process.env.GITHUB_APP_PRIVATE_KEY_FILE);
+
+  const missing: string[] = [];
+  if (!appId) {
+    missing.push('GITHUB_APP_ID or GITHUB_APP_ID_FILE');
+  }
+  if (!clientId) {
+    missing.push('GITHUB_APP_CLIENT_ID or GITHUB_APP_CLIENT_ID_FILE');
+  }
+  if (!privateKey) {
+    missing.push('GITHUB_APP_PRIVATE_KEY or GITHUB_APP_PRIVATE_KEY_FILE');
+  }
+
+  if (missing.length > 0) {
+    return {
+      name: 'github-app',
+      ok: false,
+      detail: `GitHub App credentials are incomplete: missing ${missing.join(', ')}.`,
+      remediation: 'Mount readable GitHub App secret files or set the corresponding environment variables.',
+    };
+  }
+  const keyLooksLikePem = /-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(privateKey as string);
+  if (!/^\d+$/.test(appId as string)) {
+    return {
+      name: 'github-app',
+      ok: false,
+      detail: 'GitHub App ID is present but is not numeric.',
+      remediation: 'Set GITHUB_APP_ID or GITHUB_APP_ID_FILE to the numeric GitHub App ID.',
+    };
+  }
+  if (!keyLooksLikePem) {
+    return {
+      name: 'github-app',
+      ok: false,
+      detail: 'GitHub App private key is present but does not look like a PEM private key.',
+      remediation: 'Mount the GitHub App private key PEM file and point GITHUB_APP_PRIVATE_KEY_FILE at it.',
+    };
+  }
+
+  return {
+    name: 'github-app',
+    ok: true,
+    detail: 'GitHub App credentials are readable and structurally valid for PR creation.',
+  };
+}
+
+function isGitHubAppReady(): boolean {
+  return checkGitHubAppCredentials().ok &&
+    (Boolean(process.env.GITHUB_APP_ID || process.env.GITHUB_APP_ID_FILE) ||
+      Boolean(process.env.GITHUB_APP_CLIENT_ID || process.env.GITHUB_APP_CLIENT_ID_FILE) ||
+      Boolean(process.env.GITHUB_APP_PRIVATE_KEY || process.env.GITHUB_APP_PRIVATE_KEY_FILE));
+}
+
+function buildPreflightResponse(config: KasekiApiConfig): PreflightResponse {
+  const templateDir = process.env.KASEKI_TEMPLATE_DIR || '/agents/kaseki-template';
+  const image = readKasekiImage(templateDir);
+  const templateImageDigest = readFirstLine(path.join(templateDir, '.kaseki-image-digest')) || inspectImageDigest(image);
+  const checkoutDir = process.env.KASEKI_CHECKOUT_DIR || '/agents/kaseki-agent';
+  const templateRef = fs.existsSync(path.join(checkoutDir, '.git'))
+    ? commandOutput('git', ['rev-parse', '--short', 'HEAD'], checkoutDir)
+    : undefined;
+  const checks: PreflightCheck[] = [];
+
+  try {
+    fs.accessSync(config.resultsDir, fs.constants.R_OK | fs.constants.W_OK);
+    checks.push({ name: 'results-dir', ok: true, detail: `${config.resultsDir} is readable and writable.` });
+  } catch (err) {
+    checks.push({
+      name: 'results-dir',
+      ok: false,
+      detail: `${config.resultsDir} is not readable and writable: ${(err as Error).message}`,
+      remediation: 'Create the results directory and make it writable by the API container user.',
+    });
+  }
+
+  checks.push(checkOpenRouterKey());
+  checks.push(checkGitHubAppCredentials());
+
+  const dockerVersion = execDockerCommand(['version', '--format', '{{.Client.Version}} -> {{.Server.Version}}']);
+  if (dockerVersion.ok) {
+    checks.push({ name: 'docker-daemon', ok: true, detail: dockerVersion.stdout });
+  } else {
+    const classified = dockerVersion.classification || { detail: 'Docker command failed', remediation: 'Check Docker daemon' };
+    checks.push({ name: 'docker-daemon', ok: false, ...classified });
+  }
+
+  const imageInspect = execDockerCommand(['image', 'inspect', image]);
+  if (imageInspect.ok) {
+    checks.push({ name: 'docker-image', ok: true, detail: `Image is present: ${image}` });
+  } else {
+    const classified = imageInspect.classification || { detail: 'Docker command failed', remediation: 'Check Docker daemon' };
+    const daemonFailed = checks.some((check) => check.name === 'docker-daemon' && !check.ok);
+    checks.push({
+      name: 'docker-image',
+      ok: false,
+      detail: daemonFailed ? classified.detail : `Docker image is not present locally: ${image}`,
+      remediation: daemonFailed ? classified.remediation : `Pull ${image} or set KASEKI_IMAGE to an available image.`,
+    });
+  }
+
+  const runScript = path.join(templateDir, 'run-kaseki.sh');
+  checks.push({
+    name: 'template',
+    ok: fs.existsSync(runScript),
+    detail: fs.existsSync(runScript) ? `Template runner exists: ${runScript}` : `Missing template runner: ${runScript}`,
+    remediation: fs.existsSync(runScript) ? undefined : 'Run scripts/kaseki-activate.sh --controller bootstrap.',
+  });
+
+  const status = checks.every((check) => check.ok)
+    ? 'ok'
+    : checks.some((check) => check.name === 'docker-daemon' && !check.ok)
+      ? 'error'
+      : 'degraded';
+  return {
+    status,
+    timestamp: new Date().toISOString(),
+    checks,
+    image,
+    imageDigest: templateImageDigest,
+    templateImage: image,
+    templateImageDigest,
+    templateDir,
+    templateRef,
+    resultsDir: config.resultsDir,
+    runtime: {
+      nodeVersion: process.version,
+      uid: process.getuid?.(),
+      gid: process.getgid?.(),
+      groups: process.getgroups?.(),
+    },
+    docker: {
+      version: dockerVersion.stdout,
+      clientVersion: dockerVersion.stdout?.split(' -> ')[0],
+      serverVersion: dockerVersion.stdout?.split(' -> ')[1],
+    },
+  };
+}
+
+function buildRunResponse(job: Job, cached = false): RunResponse {
+  return {
+    id: job.id,
+    status: job.status,
+    createdAt: job.createdAt.toISOString(),
+    correlationId: job.correlationId,
+    requestId: job.requestId,
+    cached: cached || undefined,
+    completedAt: job.completedAt?.toISOString(),
+    exitCode: job.exitCode,
+    failureClass: job.failureClass,
+    error: job.error,
+  };
+}
+
+/**
+ * Create the API routes.
+ */
+export function createApiRouter(
+  scheduler: JobScheduler,
+  config: KasekiApiConfig,
+  idempotencyStore: IdempotencyStore,
+  preFlightValidator: PreFlightValidator,
+  artifactCache = new ResultCache({
+    maxEntries: config.artifactCacheMaxEntries,
+    ttlMs: config.artifactCacheTtlMs,
+    maxFileBytes: config.artifactCacheMaxFileBytes,
+  }),
+): Router {
+  const router = Router();
+  const logger = createEventLogger('api');
+
+  /**
+   * Middleware: Request/Response logging.
+   */
+  router.use((req: Request, res: Response, next: NextFunction) => {
+    const startTime = Date.now();
+    const originalSend = res.send;
+
+    res.send = function (data: any) {
+      const duration = Date.now() - startTime;
+      const statusCode = res.statusCode;
+
+      // Log request/response event
+      logger.event('api_request_complete', {
+        method: req.method,
+        path: req.path,
+        statusCode,
+        durationMs: duration,
+        query: Object.keys(req.query).length > 0 ? req.query : undefined,
+      });
+
+      return originalSend.call(this, data);
+    };
+
+    next();
+  });
+
+  /**
+   * Middleware: API key validation.
+   */
+  router.use((req: Request, res: Response, next: NextFunction) => {
+    // Skip auth for health check
+    if (req.path === '/health' || req.path === '/ready') {
+      return next();
+    }
+
+    const authHeader = req.get('Authorization');
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      logger.event('api_auth_failed', {
+        path: req.path,
+        reason: 'missing_or_invalid_header',
+      });
+      return sendErrorResponse(res, 401, 'Unauthorized', 'Missing or invalid Authorization header');
+    }
+
+    const token = authHeader.slice(7);
+    if (!validateApiKey(config, token)) {
+      logger.event('api_auth_failed', {
+        path: req.path,
+        reason: 'invalid_api_key',
+      });
+      return sendErrorResponse(res, 401, 'Unauthorized', 'Invalid API key');
+    }
+
+    next();
+  });
+
+  /**
+   * Health check endpoint.
+   */
+  router.get('/health', (_req: Request, res: Response) => {
+    const queueStatus = scheduler.getQueueStatus();
+    const errors: string[] = [];
+
+    // Check if results directory is accessible
+    if (!fs.existsSync(config.resultsDir)) {
+      errors.push(`Results directory not accessible: ${config.resultsDir}`);
+    }
+
+    const status = errors.length === 0 ? 'healthy' : 'degraded';
+
+    res.json({
+      status,
+      timestamp: new Date().toISOString(),
+      queue: queueStatus,
+      errors: errors.length > 0 ? errors : undefined,
+    });
+  });
+
+  router.get('/ready', (_req: Request, res: Response) => {
+    const readiness = scheduler.getReadiness();
+    if (readiness.ready) {
+      return res.status(200).json({ status: 'ready', timestamp: new Date().toISOString() });
+    }
+    return res.status(503).json({
+      status: 'not_ready',
+      timestamp: new Date().toISOString(),
+      reasons: readiness.reasons,
+    });
+  });
+
+  router.get('/metrics', (_req: Request, res: Response) => {
+    const cacheStats = artifactCache.getStats();
+    const artifactCacheMetrics = [
+      '# HELP kaseki_artifact_cache_entries Number of artifact content cache entries currently held in memory.',
+      '# TYPE kaseki_artifact_cache_entries gauge',
+      `kaseki_artifact_cache_entries ${cacheStats.entries}`,
+      '# HELP kaseki_artifact_cache_bytes Bytes of artifact content currently held in memory.',
+      '# TYPE kaseki_artifact_cache_bytes gauge',
+      `kaseki_artifact_cache_bytes ${cacheStats.bytes}`,
+      '# HELP kaseki_artifact_cache_hits_total Total artifact content cache hits.',
+      '# TYPE kaseki_artifact_cache_hits_total counter',
+      `kaseki_artifact_cache_hits_total ${cacheStats.hits}`,
+      '# HELP kaseki_artifact_cache_misses_total Total artifact content cache misses.',
+      '# TYPE kaseki_artifact_cache_misses_total counter',
+      `kaseki_artifact_cache_misses_total ${cacheStats.misses}`,
+      '# HELP kaseki_artifact_cache_max_entries Configured maximum artifact content cache entries.',
+      '# TYPE kaseki_artifact_cache_max_entries gauge',
+      `kaseki_artifact_cache_max_entries ${cacheStats.maxEntries}`,
+      '# HELP kaseki_artifact_cache_max_file_bytes Configured maximum file size eligible for artifact content caching.',
+      '# TYPE kaseki_artifact_cache_max_file_bytes gauge',
+      `kaseki_artifact_cache_max_file_bytes ${cacheStats.maxFileBytes}`,
+    ].join('\n');
+
+    res.setHeader('Content-Type', 'text/plain; version=0.0.4; charset=utf-8');
+    res.status(200).send(`${metricsRegistry.renderPrometheus()}${artifactCacheMetrics}\n`);
+  });
+
+  /**
+   * GET /api/preflight - Controller-oriented readiness diagnostics.
+   */
+  router.get('/preflight', (_req: Request, res: Response) => {
+    const response = buildPreflightResponse(config);
+    res.status(response.status === 'error' ? 503 : 200).json(response);
+  });
+
+  /**
+   * POST /api/runs - Trigger a new kaseki run.
+   */
+  router.post('/runs', async (req: Request, res: Response) => {
+    try {
+      // Validate request body
+      const runRequest = RunRequestSchema.parse({
+        ...req.body,
+        startupCheck:
+          req.query.dryRun === 'true' || req.query.startupCheck === 'true'
+            ? true
+            : req.body?.startupCheck,
+      });
+
+      if ((runRequest.publishMode === 'branch' || runRequest.publishMode === 'draft_pr') && !isGitHubAppReady()) {
+        return sendErrorResponse(
+          res,
+          400,
+          'Bad Request',
+          `publishMode=${runRequest.publishMode} requires readable GitHub App credentials. Check /api/preflight before submitting publishable runs.`,
+        );
+      }
+
+      // Auto-generate idempotency key if not provided
+      const idempotencyKey = runRequest.idempotencyKey || randomUUID();
+      const requestFingerprint = buildRequestFingerprint(runRequest as Record<string, unknown>);
+
+      const claimResult = idempotencyStore.claimOrGet(idempotencyKey, requestFingerprint);
+      if (claimResult.kind === 'fulfilled') {
+        const currentJob = scheduler.getJob(claimResult.response.id);
+        const response = currentJob
+          ? buildRunResponse(currentJob, true)
+          : {
+            ...claimResult.response,
+            cached: true,
+          };
+        logger.event('api_idempotent_resubmission', {
+          jobId: response.id,
+          idempotencyKey,
+          currentStatus: currentJob?.status,
+        });
+        return res.status(200).json(response); // 200 OK, not 202
+      }
+      if (claimResult.kind === 'pending') {
+        return sendErrorResponse(res, 409, 'Conflict', 'Request with this idempotency key is already being processed');
+      }
+
+      // Log request
+      logger.event('api_run_request', {
+        repoUrl: runRequest.repoUrl,
+        ref: runRequest.ref,
+        taskMode: runRequest.taskMode,
+        publishMode: runRequest.publishMode,
+        startupCheck: runRequest.startupCheck,
+        idempotencyKey,
+      });
+
+      // Submit to scheduler
+      const job = await scheduler.submitJob(runRequest);
+
+      // Store idempotency key on job
+      job.idempotencyKey = idempotencyKey;
+
+      const response = buildRunResponse(job);
+
+      // Store in idempotency cache
+      idempotencyStore.storeResponse(idempotencyKey, response, requestFingerprint);
+
+      res.status(202).json(response); // 202 Accepted
+    } catch (err: unknown) {
+      if (err instanceof Error && 'errors' in err) {
+        // Zod validation error
+        const details = (err as any).errors.map((e: any) => `${(e.path as string[]).join('.')}: ${e.message}`).join('; ');
+        logger.event('api_validation_error', {
+          path: '/runs',
+          details,
+        });
+        return sendErrorResponse(res, 400, 'Bad Request', details);
+      }
+      logger.event('api_error', {
+        path: '/runs',
+        error: (err as Error).message,
+      });
+      return sendErrorResponse(res, 400, 'Bad Request', (err as Error).message);
+    }
+  });
+
+  /**
+   * POST /api/webhooks/test - Test webhook configuration.
+   */
+  router.post('/webhooks/test', async (req: Request, res: Response) => {
+    try {
+      const { url, secret } = req.body;
+
+      if (!url || typeof url !== 'string') {
+        return sendErrorResponse(res, 400, 'Bad Request', 'Webhook URL is required');
+      }
+
+      // Validate URL format
+      try {
+        new URL(url);
+      } catch {
+        return sendErrorResponse(res, 400, 'Bad Request', 'Invalid webhook URL format');
+      }
+
+      // Send test webhook
+      let statusCode: number | undefined;
+      let error: string | undefined;
+      let durationMs = 0;
+      const startTime = Date.now();
+
+      try {
+        const testPayload = {
+          eventType: 'webhook.test',
+          jobId: 'test',
+          timestamp: new Date().toISOString(),
+          data: { message: 'This is a test webhook from kaseki-agent API' },
+        };
+
+        // Generate HMAC signature if secret provided
+        let signature: string | null = null;
+        if (secret && typeof secret === 'string') {
+          const body = JSON.stringify(testPayload);
+          signature = crypto.createHmac('sha256', secret).update(body).digest('hex');
+        }
+
+        const response = await fetch(url, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'X-Kaseki-Event': 'webhook.test',
+            'X-Kaseki-Job-Id': 'test',
+            ...(signature && { 'X-Kaseki-Signature': `sha256=${signature}` }),
+          },
+          body: JSON.stringify(testPayload),
+          signal: AbortSignal.timeout(10000),
+        });
+
+        durationMs = Date.now() - startTime;
+        statusCode = response.status;
+
+        if (!response.ok) {
+          error = `HTTP ${response.status} ${response.statusText}`;
+        }
+      } catch (err) {
+        durationMs = Date.now() - startTime;
+        error = err instanceof Error ? err.message : String(err);
+      }
+
+      const result = {
+        url,
+        statusCode,
+        durationMs,
+        success: !error,
+        error,
+      };
+
+      logger.event('webhook_test', result);
+
+      res.json(result);
+    } catch (err) {
+      logger.event('api_error', {
+        path: '/webhooks/test',
+        error: (err as Error).message,
+      });
+      return sendErrorResponse(res, 400, 'Bad Request', (err as Error).message);
+    }
+  });
+
+  /**
+   * POST /api/validate - Pre-flight validation of job request (dry-run).
+   */
+  router.post('/validate', async (req: Request, res: Response) => {
+    try {
+      // Validate request body
+      const runRequest = RunRequestSchema.parse(req.body);
+
+      logger.event('api_validation_request', {
+        repoUrl: runRequest.repoUrl,
+        ref: runRequest.ref,
+      });
+
+      // Run pre-flight validation
+      const validationResult = await preFlightValidator.validate(runRequest);
+
+      const response: ValidationResponse = validationResult;
+
+      res.json(response);
+    } catch (err: unknown) {
+      if (err instanceof Error && 'errors' in err) {
+        // Zod validation error
+        const details = (err as any).errors.map((e: any) => `${(e.path as string[]).join('.')}: ${e.message}`).join('; ');
+        logger.event('api_validation_error', {
+          path: '/validate',
+          details,
+        });
+        return sendErrorResponse(res, 400, 'Bad Request', details);
+      }
+      logger.event('api_error', {
+        path: '/validate',
+        error: (err as Error).message,
+      });
+      return sendErrorResponse(res, 400, 'Bad Request', (err as Error).message);
+    }
+  });
+
+  // Register domain-focused route modules
+  router.use(createStatusRoutes(scheduler, config));
+  router.use(createLogRoutes(scheduler, config));
+  router.use(createArtifactRoutes(scheduler, config, artifactCache));
+  router.use(createWebhookRoutes());
+
+  return router;
+}