@jskit-ai/kernel 0.1.244 → 0.1.246

package/server/runtime/fastifyBootstrap.js

@@ -1,553 +0,0 @@
-import { ActionRuntimeError } from "../../shared/actions/actionDefinitions.js";
-import { normalizeOpaqueId, normalizeTransactionOutcome } from "../../shared/support/normalize.js";
-import { resolveDefaultSurfaceId } from "../support/appConfig.js";
-
-const JSON_API_CONTENT_TYPE = "application/vnd.api+json";
-const JSON_API_CONTENT_TYPE_PARSER_MARKER = Symbol.for("jskit.fastify.jsonApiContentTypeParserRegistered");
-const BODYLESS_CONTENT_TYPE_NORMALIZER_MARKER = Symbol.for("jskit.fastify.bodylessContentTypeNormalizerRegistered");
-
-function resolveLoggerLevel({ configuredLevel = "", nodeEnv = "development", allowedLevels = [] } = {}) {
-  const normalizedConfiguredLevel = String(configuredLevel || "")
-    .trim()
-    .toLowerCase();
-  const allowedLevelSet =
-    allowedLevels instanceof Set
-      ? new Set(allowedLevels)
-      : new Set(Array.isArray(allowedLevels) ? allowedLevels : []);
-  if (allowedLevelSet.has(normalizedConfiguredLevel)) {
-    return normalizedConfiguredLevel;
-  }
-
-  return String(nodeEnv || "").trim().toLowerCase() === "production" ? "info" : "debug";
-}
-
-function createFastifyLoggerOptions({
-  configuredLevel = "",
-  nodeEnv = "development",
-  allowedLevels = [],
-  redactPaths = [],
-  redactCensor = "[REDACTED]"
-} = {}) {
-  return {
-    level: resolveLoggerLevel({
-      configuredLevel,
-      nodeEnv,
-      allowedLevels
-    }),
-    redact: {
-      paths: Array.isArray(redactPaths) ? redactPaths : [],
-      censor: redactCensor
-    }
-  };
-}
-
-function createFallbackJsonBodyParser() {
-  return function parseJsonBody(_request, body, done) {
-    const source = typeof body === "string" ? body.trim() : "";
-    if (!source) {
-      done(null, {});
-      return;
-    }
-
-    try {
-      done(null, JSON.parse(source));
-    } catch (error) {
-      if (error && typeof error === "object" && !Array.isArray(error)) {
-        error.statusCode = 400;
-      }
-      done(error);
-    }
-  };
-}
-
-function registerJsonApiContentTypeParser(fastify) {
-  if (!fastify || typeof fastify.addContentTypeParser !== "function") {
-    throw new TypeError("registerJsonApiContentTypeParser requires a Fastify instance.");
-  }
-
-  if (fastify[JSON_API_CONTENT_TYPE_PARSER_MARKER]) {
-    return false;
-  }
-
-  if (typeof fastify.hasContentTypeParser === "function" && fastify.hasContentTypeParser(JSON_API_CONTENT_TYPE)) {
-    fastify[JSON_API_CONTENT_TYPE_PARSER_MARKER] = true;
-    return false;
-  }
-
-  const parser = typeof fastify.getDefaultJsonParser === "function"
-    ? fastify.getDefaultJsonParser("ignore", "ignore")
-    : createFallbackJsonBodyParser();
-
-  fastify.addContentTypeParser(JSON_API_CONTENT_TYPE, { parseAs: "string" }, parser);
-  fastify[JSON_API_CONTENT_TYPE_PARSER_MARKER] = true;
-  return true;
-}
-
-function hasHeaderValue(headers = {}, key = "") {
-  return String(headers?.[key] ?? "").trim().length > 0;
-}
-
-function hasRequestBody(headers = {}) {
-  const transferEncoding = String(headers?.["transfer-encoding"] ?? "").trim();
-  if (transferEncoding) {
-    return true;
-  }
-
-  const contentLengthHeader = String(headers?.["content-length"] ?? "").trim();
-  if (!contentLengthHeader) {
-    return false;
-  }
-
-  const contentLength = Number(contentLengthHeader);
-  if (!Number.isFinite(contentLength)) {
-    return true;
-  }
-
-  return contentLength > 0;
-}
-
-function normalizeBodylessContentTypeHeader(request = null) {
-  const headers = request?.headers;
-  if (!headers || typeof headers !== "object" || Array.isArray(headers)) {
-    return false;
-  }
-
-  if (!hasHeaderValue(headers, "content-type") && !hasHeaderValue(headers, "Content-Type")) {
-    return false;
-  }
-
-  if (hasRequestBody(headers)) {
-    return false;
-  }
-
-  delete headers["content-type"];
-  delete headers["Content-Type"];
-  return true;
-}
-
-function registerBodylessContentTypeNormalizer(fastify) {
-  if (!fastify || typeof fastify.addHook !== "function") {
-    throw new TypeError("registerBodylessContentTypeNormalizer requires a Fastify instance.");
-  }
-
-  if (fastify[BODYLESS_CONTENT_TYPE_NORMALIZER_MARKER]) {
-    return false;
-  }
-
-  fastify.addHook("onRequest", async (request) => {
-    normalizeBodylessContentTypeHeader(request);
-  });
-  fastify[BODYLESS_CONTENT_TYPE_NORMALIZER_MARKER] = true;
-  return true;
-}
-
-function registerRequestLoggingHooks(
-  app,
-  {
-    requestStartedAtSymbol,
-    getPathname,
-    getSurface,
-    observeRequest,
-    enableRequestLogs = true,
-    defaultSurfaceId = ""
-  } = {}
-) {
-  if (!app || typeof app.addHook !== "function") {
-    throw new TypeError("registerRequestLoggingHooks requires a Fastify instance.");
-  }
-
-  const startedAtSymbol = requestStartedAtSymbol || Symbol("request_started_at_ns");
-  const resolvePathname = typeof getPathname === "function" ? getPathname : () => "/";
-  const resolveSurface =
-    typeof getSurface === "function"
-      ? getSurface
-      : () =>
-          resolveDefaultSurfaceId(null, {
-            defaultSurfaceId
-          });
-
-  app.addHook("onRequest", async (request) => {
-    request[startedAtSymbol] = process.hrtime.bigint();
-  });
-
-  app.addHook("onResponse", async (request, reply) => {
-    const startedAt = request[startedAtSymbol];
-    const durationMs =
-      typeof startedAt === "bigint" ? Number(process.hrtime.bigint() - startedAt) / 1_000_000 : Number.NaN;
-    const pathnameValue = resolvePathname(request);
-    const routeUrl = String(request?.routeOptions?.url || "").trim();
-    const surface = resolveSurface(pathnameValue, request);
-    const actorId = normalizeOpaqueId(request?.user?.id);
-    const logPayload = {
-      requestId: String(request?.id || ""),
-      method: String(request?.method || ""),
-      path: pathnameValue,
-      routeUrl,
-      surface,
-      statusCode: Number(reply?.statusCode || 0),
-      durationMs: Number.isFinite(durationMs) ? Number(durationMs.toFixed(3)) : null
-    };
-
-    if (actorId != null) {
-      logPayload.actorId = actorId;
-    }
-
-    if (typeof observeRequest === "function") {
-      observeRequest({
-        method: logPayload.method,
-        route: routeUrl || pathnameValue,
-        surface,
-        statusCode: logPayload.statusCode,
-        durationMs
-      });
-    }
-
-    if (enableRequestLogs) {
-      request.log.info(logPayload, "request.completed");
-    }
-  });
-}
-
-function resolveValidationFieldErrors(error) {
-  const issues = Array.isArray(error?.validation) ? error.validation : [];
-  const fieldErrors = {};
-
-  for (const issue of issues) {
-    const fieldFromPath = String(issue.instancePath || "")
-      .replace(/^\//, "")
-      .replace(/\//g, ".");
-    const field =
-      fieldFromPath || String(issue.params?.missingProperty || issue.params?.additionalProperty || "request").trim();
-
-    if (!fieldErrors[field]) {
-      fieldErrors[field] = issue.message || "Invalid value.";
-    }
-  }
-
-  return fieldErrors;
-}
-
-function resolveRequestRouteTransport(request) {
-  const directTransport =
-    request?.routeTransport && typeof request.routeTransport === "object" && !Array.isArray(request.routeTransport)
-      ? request.routeTransport
-      : null;
-  if (directTransport) {
-    return directTransport;
-  }
-
-  const configTransport =
-    request?.routeOptions?.config?.transport &&
-    typeof request.routeOptions.config.transport === "object" &&
-    !Array.isArray(request.routeOptions.config.transport)
-      ? request.routeOptions.config.transport
-      : null;
-  const runtimeTransport =
-    configTransport?.runtime && typeof configTransport.runtime === "object" && !Array.isArray(configTransport.runtime)
-      ? configTransport.runtime
-      : null;
-  if (runtimeTransport) {
-    return runtimeTransport;
-  }
-
-  return configTransport;
-}
-
-function applyRouteTransportErrorResponse(reply, request, error, {
-  statusCode = 500,
-  normalizedErrorCode = "",
-  message = error?.message,
-  exposeDetails = true
-} = {}) {
-  const transport = resolveRequestRouteTransport(request);
-  const errorSerializer = transport && typeof transport.error === "function" ? transport.error : null;
-  if (!errorSerializer) {
-    return false;
-  }
-
-  const payload = errorSerializer(error, {
-    request,
-    reply,
-    statusCode,
-    code: normalizedErrorCode,
-    message,
-    exposeDetails
-  });
-
-  if (payload && typeof payload.then === "function") {
-    throw new TypeError("Route transport error serializer must return synchronously.");
-  }
-
-  if (transport.contentType) {
-    reply.header("Content-Type", transport.contentType);
-  }
-
-  reply.code(statusCode).send(payload);
-  return true;
-}
-
-function resolveApiErrorStatus(error, code) {
-  // JSON REST's public error codes need HTTP classification even without status hints.
-  switch (code) {
-    case "REST_API_VALIDATION":
-      return 422;
-    case "REST_API_RESOURCE":
-      switch (error?.subtype) {
-        case "not_found": return 404;
-        case "forbidden": return 403;
-        case "conflict": return 409;
-        default: return 400;
-      }
-    case "REST_API_VERSION_CONFLICT":
-      return 409;
-    case "REST_API_PRECONDITION_FAILED":
-      return 412;
-    case "REST_API_FIELDSET_INVALID":
-    case "REST_API_INCLUDE_INVALID":
-      return 400;
-    case "REST_API_PAYLOAD":
-      return error?.statusCode === 413 ? 413 : 400;
-    case "REST_API_TEMPORAL_DATA_INVALID":
-      return 500;
-    default: {
-      const status = Number(error?.statusCode || error?.status);
-      return Number.isInteger(status) && status >= 400 && status <= 599 ? status : 500;
-    }
-  }
-}
-
-function registerApiErrorHandler(
-  app,
-  {
-    isAppError,
-    onRecordDbError,
-    onCaptureServerError,
-    appErrorLogMessage = "AppError 5xx",
-    unhandledErrorLogMessage = "Unhandled error"
-  } = {}
-) {
-  if (!app || typeof app.setErrorHandler !== "function") {
-    throw new TypeError("registerApiErrorHandler requires a Fastify instance.");
-  }
-  if (typeof isAppError !== "function") {
-    throw new TypeError("registerApiErrorHandler requires isAppError.");
-  }
-
-  const recordDbError = typeof onRecordDbError === "function" ? onRecordDbError : () => {};
-  const captureServerError = typeof onCaptureServerError === "function" ? onCaptureServerError : () => {};
-
-  function shouldExposeAppErrorDetails(errorCode = "") {
-    return String(errorCode || "").trim() !== "ACTION_PERMISSION_DENIED";
-  }
-
-  app.setErrorHandler((error, request, reply) => {
-    const normalizedErrorCode = String(error?.code || "").trim();
-    const transactionOutcome = normalizeTransactionOutcome(error?.transactionOutcome);
-    const outcomeFields = transactionOutcome ? { transactionOutcome } : {};
-    const isCsrfErrorCode = normalizedErrorCode.startsWith("FST_CSRF_");
-    const statusCode = resolveApiErrorStatus(error, normalizedErrorCode);
-
-    if (Array.isArray(error?.validation)) {
-      const fieldErrors = resolveValidationFieldErrors(error);
-      const validationErrorCode = normalizedErrorCode || "validation_failed";
-      if (applyRouteTransportErrorResponse(reply, request, error, {
-        statusCode: 400,
-        normalizedErrorCode: validationErrorCode
-      })) {
-        return;
-      }
-      reply.code(400).send({
-        error: "Validation failed.",
-        code: validationErrorCode,
-        ...outcomeFields,
-        fieldErrors,
-        details: {
-          fieldErrors
-        }
-      });
-      return;
-    }
-
-    if (isAppError(error) || error instanceof ActionRuntimeError) {
-      if (applyRouteTransportErrorResponse(reply, request, error, {
-        statusCode: error.status,
-        normalizedErrorCode: normalizedErrorCode || "app_error",
-        exposeDetails: shouldExposeAppErrorDetails(normalizedErrorCode)
-      })) {
-        return;
-      }
-      if (error.status >= 500) {
-        recordDbError(error);
-        captureServerError(request, error, error.status);
-        app.log.error({ err: error }, appErrorLogMessage);
-      }
-
-      const appErrorCode = normalizedErrorCode || "app_error";
-      const payload = {
-        error: error.message,
-        code: appErrorCode,
-        ...outcomeFields
-      };
-      if (error.details && shouldExposeAppErrorDetails(appErrorCode)) {
-        payload.details = error.details;
-        if (error.details.fieldErrors) {
-          payload.fieldErrors = error.details.fieldErrors;
-        }
-      }
-
-      if (error.headers && typeof error.headers === "object") {
-        Object.entries(error.headers).forEach(([name, value]) => {
-          reply.header(name, value);
-        });
-      }
-
-      reply.code(error.status).send(payload);
-      return;
-    }
-
-    if (error.headers && typeof error.headers === "object") {
-      Object.entries(error.headers).forEach(([name, value]) => {
-        reply.header(name, value);
-      });
-    }
-
-    if (statusCode >= 500) {
-      recordDbError(error);
-    }
-    captureServerError(request, error, statusCode);
-    app.log.error({ err: error }, unhandledErrorLogMessage);
-
-    const message = statusCode >= 500 ? "Internal server error." : String(error?.message || "Request failed.");
-    const fallbackErrorCode =
-      normalizedErrorCode || (statusCode >= 500 ? "internal_server_error" : "request_failed");
-    const payload = {
-      error: message,
-      code: fallbackErrorCode,
-      ...outcomeFields
-    };
-    if (isCsrfErrorCode) {
-      payload.details = {
-        code: normalizedErrorCode
-      };
-    }
-    if (applyRouteTransportErrorResponse(reply, request, error, {
-      statusCode,
-      normalizedErrorCode: fallbackErrorCode,
-      message,
-      exposeDetails: statusCode < 500
-    })) {
-      return;
-    }
-    reply.code(statusCode).send(payload);
-  });
-}
-
-function resolveDatabaseErrorCode(error) {
-  const errorCode = String(error?.code || "")
-    .trim()
-    .toUpperCase();
-  if (errorCode && (errorCode.startsWith("ER_") || errorCode.startsWith("SQLITE_") || errorCode.startsWith("PG"))) {
-    return errorCode;
-  }
-
-  const sqlState = String(error?.sqlState || error?.sqlstate || "")
-    .trim()
-    .toUpperCase();
-  if (sqlState) {
-    return `SQLSTATE_${sqlState}`;
-  }
-
-  const errno = Number(error?.errno);
-  if (Number.isInteger(errno)) {
-    return `ERRNO_${errno}`;
-  }
-
-  const message = String(error?.message || "").toLowerCase();
-  const name = String(error?.name || "").toLowerCase();
-  if (message.includes("mysql") || message.includes("sql") || message.includes("knex") || name.includes("mysql")) {
-    return "DB_UNKNOWN";
-  }
-
-  return "";
-}
-
-function recordDbErrorBestEffort(observabilityService, error) {
-  if (!observabilityService || typeof observabilityService.recordDbError !== "function") {
-    return;
-  }
-
-  const code = resolveDatabaseErrorCode(error);
-  if (!code) {
-    return;
-  }
-
-  observabilityService.recordDbError({ code });
-}
-
-async function runGracefulShutdown({
-  signal = "",
-  exitProcess = false,
-  exitCode = 0,
-  timeoutMs = 10_000,
-  appInstance = null,
-  stopBackgroundRuntimes = () => {},
-  closeDatabase = async () => {},
-  logger = console
-} = {}) {
-  let forcedExitTimer = null;
-
-  if (signal) {
-    logger.log(`Received ${signal}. Shutting down.`);
-  }
-
-  stopBackgroundRuntimes();
-
-  if (exitProcess) {
-    forcedExitTimer = setTimeout(() => {
-      try {
-        appInstance?.server?.closeIdleConnections?.();
-        appInstance?.server?.closeAllConnections?.();
-      } catch {
-        // Ignore best-effort force-close failures.
-      }
-
-      logger.error(`Graceful shutdown timed out after ${timeoutMs}ms. Forcing process exit.`);
-      process.exit(1);
-    }, timeoutMs);
-    forcedExitTimer.unref?.();
-  }
-
-  try {
-    if (appInstance) {
-      await appInstance.close();
-    }
-    await closeDatabase();
-  } catch (error) {
-    logger.error("Failed to close server cleanly:", error);
-    if (exitProcess) {
-      process.exit(1);
-    }
-    throw error;
-  } finally {
-    if (forcedExitTimer) {
-      clearTimeout(forcedExitTimer);
-    }
-  }
-
-  if (exitProcess) {
-    process.exit(exitCode);
-  }
-}
-
-export {
-  resolveLoggerLevel,
-  createFastifyLoggerOptions,
-  registerJsonApiContentTypeParser,
-  normalizeBodylessContentTypeHeader,
-  registerBodylessContentTypeNormalizer,
-  registerRequestLoggingHooks,
-  registerApiErrorHandler,
-  resolveDatabaseErrorCode,
-  recordDbErrorBestEffort,
-  runGracefulShutdown
-};