@aifabrix/builder 2.49.2 → 2.51.0

package/lib/programmatic/builder-api-request.js

@@ -0,0 +1,175 @@
+/**
+ * Authenticated capability execution for builder-api HTTP server.
+ *
+ * @fileoverview Idempotency, workspace lock, dispatch
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { authenticateRequest } = require('./bearer-auth');
+const { dispatchHandler } = require('./route-handlers');
+const { withWorkspaceLock } = require('./workspace-lock');
+const { getIdempotentResult, setIdempotentResult } = require('./idempotency-cache');
+const { withRequestTimeout } = require('./request-timeout');
+
+/**
+ * @param {Object} capability
+ * @returns {boolean}
+ */
+function requiresAuth(capability) {
+  return capability.handlerId !== 'health' && capability.handlerId !== 'ready';
+}
+
+/**
+ * @param {Object} capability
+ * @returns {boolean}
+ */
+function isMutating(capability) {
+  return capability.mutating === true;
+}
+
+/**
+ * @param {Object} params
+ * @param {Object} body
+ * @returns {string}
+ */
+function resolveIdempotencySystemKey(params, body) {
+  return params.systemKey || body.systemKey || '_workspace';
+}
+
+/**
+ * @param {Object} options
+ * @param {Object} options.auth
+ * @param {string|undefined} options.idempotencyKey
+ * @param {Object} options.capability
+ * @param {string} options.routeKey
+ * @param {Object} options.params
+ * @param {Object} options.body
+ * @param {string} options.requestId
+ * @returns {{ httpStatus: number, body: Object, requestId: string }|null}
+ */
+function lookupIdempotentResponse(options) {
+  const { auth, idempotencyKey, capability, routeKey, params, body, requestId } = options;
+  if (!idempotencyKey || !isMutating(capability)) {
+    return null;
+  }
+  const cached = getIdempotentResult({
+    userId: auth.userId,
+    idempotencyKey: String(idempotencyKey),
+    route: routeKey,
+    systemKey: resolveIdempotencySystemKey(params, body)
+  });
+  if (!cached) {
+    return null;
+  }
+  return { httpStatus: cached.httpStatus, body: cached.body, requestId: cached.correlationId || requestId };
+}
+
+/**
+ * @param {Object} auth
+ * @param {Object} capability
+ * @param {Object} params
+ * @param {Object} body
+ * @param {Object} query
+ * @returns {Promise<*>}
+ */
+async function runHandler(auth, capability, params, body, query) {
+  const run = () =>
+    withRequestTimeout(capability.handlerId, () =>
+      dispatchHandler(capability.handlerId, params, auth, body, query)
+    );
+  const lockKey = params.systemKey || body.systemKey;
+  if (isMutating(capability) && lockKey) {
+    return withWorkspaceLock(auth.userId, lockKey, run);
+  }
+  return run();
+}
+
+/**
+ * @param {Object} options
+ * @param {Object} options.auth
+ * @param {string|undefined} options.idempotencyKey
+ * @param {Object} options.capability
+ * @param {string} options.routeKey
+ * @param {Object} options.params
+ * @param {Object} options.body
+ * @param {string} options.requestId
+ * @param {Object} options.result
+ * @returns {{ httpStatus: number, body: Object, requestId: string, userId: string }}
+ */
+function buildSuccessResponse(options) {
+  const { auth, idempotencyKey, capability, routeKey, params, body, requestId, result } = options;
+  const responseBody = { success: true, data: result, correlationId: requestId };
+  if (idempotencyKey && isMutating(capability)) {
+    setIdempotentResult(
+      {
+        userId: auth.userId,
+        idempotencyKey: String(idempotencyKey),
+        route: routeKey,
+        systemKey: resolveIdempotencySystemKey(params, body)
+      },
+      { httpStatus: 200, body: responseBody, correlationId: requestId }
+    );
+  }
+  return { httpStatus: 200, body: responseBody, requestId, userId: auth.userId };
+}
+
+/**
+ * @typedef {Object} ExecuteCapabilityRequestOptions
+ * @property {import('http').IncomingMessage} req
+ * @property {Object} capability
+ * @property {Object} params
+ * @property {string} routeKey
+ * @property {string} requestId
+ * @property {Function} readJsonBody
+ * @property {Object} query
+ */
+
+/**
+ * @param {ExecuteCapabilityRequestOptions} options
+ * @returns {Promise<{ httpStatus: number, body: Object, requestId: string }>}
+ */
+async function executeCapabilityRequest(options) {
+  const { req, capability, params, routeKey, requestId, readJsonBody, query } = options;
+  const auth = requiresAuth(capability)
+    ? await authenticateRequest(req)
+    : { userId: 'anonymous', bearerToken: '' };
+
+  const body = req.method === 'GET' || req.method === 'DELETE' ? {} : await readJsonBody(req);
+
+  const cached = lookupIdempotentResponse({
+    auth,
+    idempotencyKey: req.headers['idempotency-key'],
+    capability,
+    routeKey,
+    params,
+    body,
+    requestId
+  });
+  if (cached) {
+    return { ...cached, userId: auth.userId };
+  }
+
+  const result = await runHandler(auth, capability, params, body, query);
+  return buildSuccessResponse({
+    auth,
+    idempotencyKey: req.headers['idempotency-key'],
+    capability,
+    routeKey,
+    params,
+    body,
+    requestId,
+    result
+  });
+}
+
+module.exports = {
+  executeCapabilityRequest,
+  requiresAuth,
+  isMutating,
+  lookupIdempotentResponse,
+  buildSuccessResponse,
+  resolveIdempotencySystemKey
+};

package/lib/programmatic/builder-api-route-dispatch.js

@@ -0,0 +1,82 @@
+/**
+ * Capability route execution for builder-api HTTP server.
+ *
+ * @fileoverview Keeps handleRequest under max-lines-per-function
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { executeCapabilityRequest } = require('./builder-api-request');
+
+/**
+ * @typedef {Object} DispatchCapabilityRouteOptions
+ * @property {import('http').IncomingMessage} req
+ * @property {import('http').ServerResponse} res
+ * @property {Function} sendJson
+ * @property {Function} sendProblem
+ * @property {Function} readJsonBody
+ * @property {Object} resolved
+ * @property {Object} query
+ * @property {string} requestId
+ * @property {string} pathname
+ * @property {Function} logRequestOutcome
+ */
+
+/**
+ * @param {DispatchCapabilityRouteOptions} options
+ */
+async function dispatchCapabilityRoute(options) {
+  const {
+    req,
+    res,
+    sendJson,
+    sendProblem,
+    readJsonBody,
+    resolved,
+    query,
+    requestId,
+    pathname,
+    logRequestOutcome
+  } = options;
+  try {
+    const outcome = await executeCapabilityRequest({
+      req,
+      capability: resolved.capability,
+      params: resolved.params,
+      routeKey: resolved.routeKey,
+      requestId,
+      readJsonBody,
+      query
+    });
+    sendJson(res, outcome.httpStatus, outcome.body, outcome.requestId);
+    logRequestOutcome({
+      requestId: outcome.requestId,
+      correlationId: outcome.body.correlationId,
+      route: resolved.routeKey,
+      method: req.method,
+      status: outcome.httpStatus,
+      systemKey: resolved.params.systemKey,
+      userId: outcome.userId
+    });
+  } catch (err) {
+    const status = err.statusCode || 500;
+    if (status === 409 && err.retryAfter) {
+      res.setHeader('Retry-After', String(err.retryAfter));
+    }
+    sendProblem(req, res, err, status, requestId, pathname);
+    logRequestOutcome({
+      requestId,
+      route: resolved.routeKey,
+      method: req.method,
+      status,
+      systemKey: resolved.params.systemKey,
+      error: err.message
+    });
+  }
+}
+
+module.exports = {
+  dispatchCapabilityRoute
+};

package/lib/programmatic/builder-api-runtime-config.js

@@ -0,0 +1,42 @@
+/**
+ * Docker dev-reload runtime config layout for builder-api.
+ *
+ * @fileoverview Ensures AIFABRIX_CONFIG parent directory exists before kv:// resolution
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('../internal/fs-real-sync');
+const path = require('path');
+
+/**
+ * Create the directory containing `AIFABRIX_CONFIG` when set (dev-reload bind mount).
+ * Does not write config or secrets — operators link or copy `config.yaml` and `secrets.local.yaml`
+ * under that directory (gitignored under repo `.aifabrix/` or persistent `mount/aifabrix/`).
+ */
+function ensureBuilderApiRuntimeConfigDir() {
+  const raw = process.env.AIFABRIX_CONFIG;
+  if (!raw || typeof raw !== 'string' || !raw.trim()) {
+    return;
+  }
+  const configPath = path.resolve(raw.trim());
+  const dir = path.dirname(configPath);
+  if (fs.existsSync(dir)) {
+    return;
+  }
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch (err) {
+    // Named Docker volumes are often root-owned when compose runs without bind mount + UID mapping.
+    if (err && (err.code === 'EACCES' || err.code === 'EPERM')) {
+      return;
+    }
+    throw err;
+  }
+}
+
+module.exports = {
+  ensureBuilderApiRuntimeConfigDir
+};

package/lib/programmatic/builder-api-server.js

@@ -0,0 +1,230 @@
+/**
+ * Builder API HTTP server (plan 154.0 — pre-Nest unified router).
+ *
+ * @fileoverview Full V1 route set via capability registry
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const http = require('http');
+const { URL } = require('url');
+const { randomUUID } = require('crypto');
+const { CAPABILITIES, getCapabilityByHandlerId } = require('./capability-registry');
+const { BASE, matchRoutePattern } = require('./http-route-match');
+const { buildOpenApiSpec } = require('./openapi-spec');
+const { writeAccessLog } = require('./access-log');
+const { dispatchCapabilityRoute } = require('./builder-api-route-dispatch');
+const { renderBuilderApiRedocHtml, resolvePublicBaseUrl } = require('./openapi-docs-serving');
+const { buildProblemDetails, writeProblemDetails } = require('./http-problem-details');
+
+/**
+ * @param {import('http').ServerResponse} res
+ * @param {number} status
+ * @param {Object} body
+ * @param {string} [requestId]
+ */
+function sendJson(res, status, body, requestId) {
+  const payload =
+    body && typeof body.openapi === 'string'
+      ? body
+      : { ...body, requestId: requestId || body.requestId };
+  res.writeHead(status, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(payload));
+}
+
+/**
+ * @param {import('http').IncomingMessage} req
+ * @param {import('http').ServerResponse} res
+ * @param {unknown} error
+ * @param {number} status
+ * @param {string} requestId
+ * @param {string} pathname
+ */
+function sendProblem(req, res, error, status, requestId, pathname) {
+  const body = buildProblemDetails(error, status, req, requestId, pathname);
+  writeProblemDetails(res, status, body);
+}
+
+/**
+ * @param {import('http').IncomingMessage} req
+ * @returns {Promise<Object>}
+ */
+function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    const max = Number(process.env.MAX_BODY_BYTES || 10 * 1024 * 1024);
+    req.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > max) {
+        reject(Object.assign(new Error('Request body too large'), { statusCode: 413 }));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => {
+      if (chunks.length === 0) {
+        resolve({});
+        return;
+      }
+      try {
+        resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+      } catch {
+        reject(Object.assign(new Error('Invalid JSON body'), { statusCode: 400 }));
+      }
+    });
+    req.on('error', reject);
+  });
+}
+
+/**
+ * @param {string} method
+ * @param {string} pathname
+ * @returns {{ capability: Object, params: Object, routeKey: string }|null}
+ */
+function resolveCapabilityRoute(method, pathname) {
+  for (const capability of CAPABILITIES) {
+    if (capability.method !== method) {
+      continue;
+    }
+    const params = matchRoutePattern(capability.route, pathname);
+    if (params) {
+      return { capability, params, routeKey: `${method} ${capability.route}` };
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {import('http').ServerResponse} res
+ * @param {number} status
+ * @param {string} html
+ * @param {string} [requestId]
+ */
+function sendHtml(res, status, html, requestId) {
+  const headers = {
+    'Content-Type': 'text/html; charset=utf-8',
+    'Cache-Control': 'public, max-age=60'
+  };
+  if (requestId) {
+    headers['X-Request-Id'] = requestId;
+  }
+  res.writeHead(status, headers);
+  res.end(html);
+}
+
+/**
+ * @param {string} pathname
+ * @returns {boolean}
+ */
+function isRedocHtmlPath(pathname) {
+  return pathname === '/api/docs' || pathname === `${BASE}/api-docs`;
+}
+
+/**
+ * @param {string} pathname
+ * @returns {boolean}
+ */
+function isOpenApiJsonPath(pathname) {
+  return pathname === `${BASE}/api-docs/openapi.json`;
+}
+
+/**
+ * @param {import('http').IncomingMessage} req
+ * @param {import('http').ServerResponse} res
+ * @param {string} pathname
+ * @param {string} requestId
+ */
+function handleOpenApiDocs(req, res, pathname, requestId) {
+  if (req.method !== 'GET') {
+    sendProblem(req, res, 'Method not allowed', 405, requestId, pathname);
+    return;
+  }
+  if (isOpenApiJsonPath(pathname)) {
+    const publicBaseUrl = resolvePublicBaseUrl(req);
+    sendJson(res, 200, buildOpenApiSpec({ publicBaseUrl }), requestId);
+    return;
+  }
+  if (isRedocHtmlPath(pathname)) {
+    sendHtml(res, 200, renderBuilderApiRedocHtml(req), requestId);
+  }
+}
+
+/**
+ * @param {Object} entry
+ */
+function logRequestOutcome(entry) {
+  if (process.env.BUILDER_API_ACCESS_LOG === '0') {
+    return;
+  }
+  writeAccessLog(entry);
+}
+
+/**
+ * @param {import('http').IncomingMessage} req
+ * @param {import('http').ServerResponse} res
+ */
+async function handleRequest(req, res) {
+  const requestId = req.headers['x-request-id'] || randomUUID();
+  const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
+  const pathname = url.pathname;
+
+  if (isRedocHtmlPath(pathname) || isOpenApiJsonPath(pathname)) {
+    handleOpenApiDocs(req, res, pathname, requestId);
+    logRequestOutcome({
+      requestId,
+      route: pathname,
+      method: req.method,
+      status: 200,
+      userId: 'anonymous'
+    });
+    return;
+  }
+
+  const resolved = resolveCapabilityRoute(req.method || 'GET', pathname);
+  if (!resolved || !getCapabilityByHandlerId(resolved.capability.handlerId)) {
+    sendProblem(req, res, 'Not found', 404, requestId, pathname);
+    logRequestOutcome({ requestId, route: pathname, method: req.method, status: 404, userId: 'anonymous' });
+    return;
+  }
+
+  const query = Object.fromEntries(url.searchParams.entries());
+  await dispatchCapabilityRoute({
+    req,
+    res,
+    sendJson,
+    sendProblem,
+    readJsonBody,
+    resolved,
+    query,
+    requestId,
+    pathname,
+    logRequestOutcome
+  });
+}
+
+/**
+ * @param {number} [port]
+ * @returns {import('http').Server}
+ */
+function createBuilderApiServer(port = Number(process.env.PORT || 3005)) {
+  const server = http.createServer((req, res) => {
+    handleRequest(req, res).catch((err) => {
+      const requestId = req.headers['x-request-id'] || randomUUID();
+      const pathname = String(req.url || '/').split('?')[0];
+      sendProblem(req, res, err, err.statusCode || 500, requestId, pathname);
+    });
+  });
+  server.listen(port);
+  return server;
+}
+
+module.exports = {
+  createBuilderApiServer,
+  handleRequest,
+  sendJson,
+  sendProblem,
+  BASE
+};