@jskit-ai/kernel 0.1.4

package/server/runtime/fastifyBootstrap.js

@@ -0,0 +1,372 @@
+import { KERNEL_TOKENS } from "../../shared/support/tokens.js";
+import { ActionRuntimeError } from "../../shared/actions/actionDefinitions.js";
+import { normalizeOpaqueId } from "../../shared/support/normalize.js";
+import { isAppError } from "./errors.js";
+import { resolveDefaultSurfaceId } from "../support/appConfig.js";
+
+const API_ERROR_HANDLER_MARKER_TOKEN = "kernel.runtime.apiErrorHandlerRegistered";
+
+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 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 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 : () => {};
+
+  app.setErrorHandler((error, request, reply) => {
+    const normalizedErrorCode = String(error?.code || "").trim();
+    const isCsrfErrorCode = normalizedErrorCode.startsWith("FST_CSRF_");
+    const statusFromError = Number(error?.statusCode || error?.status);
+    const statusCode =
+      Number.isInteger(statusFromError) && statusFromError >= 400 && statusFromError <= 599 ? statusFromError : 500;
+
+    if (Array.isArray(error?.validation)) {
+      const fieldErrors = resolveValidationFieldErrors(error);
+      const validationErrorCode = normalizedErrorCode || "validation_failed";
+      reply.code(400).send({
+        error: "Validation failed.",
+        code: validationErrorCode,
+        fieldErrors,
+        details: {
+          fieldErrors
+        }
+      });
+      return;
+    }
+
+    if (isAppError(error) || error instanceof ActionRuntimeError) {
+      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
+      };
+      if (error.details) {
+        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
+    };
+    if (isCsrfErrorCode) {
+      payload.details = {
+        code: normalizedErrorCode
+      };
+    }
+    reply.code(statusCode).send(payload);
+  });
+}
+
+function ensureApiErrorHandling(
+  app,
+  {
+    fastifyToken = KERNEL_TOKENS.Fastify,
+    markerToken = API_ERROR_HANDLER_MARKER_TOKEN,
+    isAppError: isAppErrorOverride,
+    autoRegister = true,
+    ...handlerOptions
+  } = {}
+) {
+  if (!app || typeof app.make !== "function" || typeof app.has !== "function" || typeof app.instance !== "function") {
+    throw new TypeError("ensureApiErrorHandling requires an application instance.");
+  }
+
+  if (autoRegister === false) {
+    return false;
+  }
+
+  const normalizedMarkerToken = String(markerToken || "").trim() || API_ERROR_HANDLER_MARKER_TOKEN;
+  if (app.has(normalizedMarkerToken)) {
+    return false;
+  }
+
+  const fastify = app.make(fastifyToken);
+  if (!fastify || typeof fastify.setErrorHandler !== "function") {
+    throw new TypeError("ensureApiErrorHandling requires a Fastify instance.");
+  }
+
+  const appErrorPredicate = typeof isAppErrorOverride === "function" ? isAppErrorOverride : isAppError;
+  registerApiErrorHandler(fastify, {
+    ...handlerOptions,
+    isAppError: appErrorPredicate
+  });
+  app.instance(normalizedMarkerToken, true);
+
+  return true;
+}
+
+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,
+  registerRequestLoggingHooks,
+  registerApiErrorHandler,
+  ensureApiErrorHandling,
+  resolveDatabaseErrorCode,
+  recordDbErrorBestEffort,
+  runGracefulShutdown
+};

package/server/runtime/fastifyBootstrap.test.js

@@ -0,0 +1,194 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { AppError, isAppError } from "./errors.js";
+import { registerApiErrorHandler, registerRequestLoggingHooks } from "./fastifyBootstrap.js";
+
+function createFastifyStub() {
+  return {
+    errorHandler: null,
+    hooks: {},
+    log: {
+      error() {}
+    },
+    setErrorHandler(handler) {
+      this.errorHandler = handler;
+    },
+    addHook(name, handler) {
+      this.hooks[name] = handler;
+    }
+  };
+}
+
+function createReplyStub() {
+  return {
+    statusCode: 200,
+    payload: undefined,
+    headers: {},
+    code(value) {
+      this.statusCode = Number(value);
+      return this;
+    },
+    header(name, value) {
+      this.headers[name] = value;
+      return this;
+    },
+    send(payload) {
+      this.payload = payload;
+      return this;
+    }
+  };
+}
+
+test("registerApiErrorHandler includes code for validation errors", () => {
+  const fastify = createFastifyStub();
+  registerApiErrorHandler(fastify, { isAppError });
+
+  const reply = createReplyStub();
+  fastify.errorHandler(
+    {
+      validation: [
+        {
+          instancePath: "/email",
+          message: "must match format email"
+        }
+      ]
+    },
+    {},
+    reply
+  );
+
+  assert.equal(reply.statusCode, 400);
+  assert.equal(reply.payload.code, "validation_failed");
+  assert.deepEqual(reply.payload.fieldErrors, {
+    email: "must match format email"
+  });
+});
+
+test("registerApiErrorHandler includes code for AppError payloads", () => {
+  const fastify = createFastifyStub();
+  registerApiErrorHandler(fastify, { isAppError });
+
+  const reply = createReplyStub();
+  const error = new AppError(422, "Domain validation failed.", {
+    code: "domain_validation_failed",
+    details: {
+      fieldErrors: {
+        email: "invalid"
+      }
+    }
+  });
+
+  fastify.errorHandler(error, {}, reply);
+
+  assert.equal(reply.statusCode, 422);
+  assert.equal(reply.payload.code, "domain_validation_failed");
+  assert.equal(reply.payload.error, "Domain validation failed.");
+  assert.deepEqual(reply.payload.fieldErrors, {
+    email: "invalid"
+  });
+});
+
+test("registerApiErrorHandler falls back to app_error code for AppError without code", () => {
+  const fastify = createFastifyStub();
+  registerApiErrorHandler(fastify, { isAppError });
+
+  const reply = createReplyStub();
+  const error = new AppError(409, "Conflict.");
+  error.code = "";
+
+  fastify.errorHandler(error, {}, reply);
+
+  assert.equal(reply.statusCode, 409);
+  assert.equal(reply.payload.code, "app_error");
+});
+
+test("registerApiErrorHandler includes internal_server_error code for unhandled 500 errors", () => {
+  const fastify = createFastifyStub();
+  registerApiErrorHandler(fastify, { isAppError });
+
+  const reply = createReplyStub();
+  const error = new Error("Unexpected DB failure");
+
+  fastify.errorHandler(error, {}, reply);
+
+  assert.equal(reply.statusCode, 500);
+  assert.equal(reply.payload.code, "internal_server_error");
+  assert.equal(reply.payload.error, "Internal server error.");
+});
+
+test("registerApiErrorHandler keeps known error code for non-app errors", () => {
+  const fastify = createFastifyStub();
+  registerApiErrorHandler(fastify, { isAppError });
+
+  const reply = createReplyStub();
+  const error = new Error("CSRF token invalid");
+  error.statusCode = 403;
+  error.code = "FST_CSRF_BAD_TOKEN";
+
+  fastify.errorHandler(error, {}, reply);
+
+  assert.equal(reply.statusCode, 403);
+  assert.equal(reply.payload.code, "FST_CSRF_BAD_TOKEN");
+  assert.deepEqual(reply.payload.details, {
+    code: "FST_CSRF_BAD_TOKEN"
+  });
+});
+
+test("registerRequestLoggingHooks uses configured default surface when getSurface is absent", async () => {
+  const fastify = createFastifyStub();
+  let loggedPayload = null;
+
+  registerRequestLoggingHooks(fastify, {
+    defaultSurfaceId: "home"
+  });
+
+  const request = {
+    id: "req-home",
+    method: "GET",
+    routeOptions: {
+      url: "/status"
+    },
+    log: {
+      info(payload) {
+        loggedPayload = payload;
+      }
+    }
+  };
+  const reply = {
+    statusCode: 204
+  };
+
+  await fastify.hooks.onRequest(request);
+  await fastify.hooks.onResponse(request, reply);
+
+  assert.equal(loggedPayload.surface, "home");
+});
+
+test("registerRequestLoggingHooks leaves surface empty when no surface default is configured", async () => {
+  const fastify = createFastifyStub();
+  let loggedPayload = null;
+
+  registerRequestLoggingHooks(fastify);
+
+  const request = {
+    id: "req-public",
+    method: "GET",
+    routeOptions: {
+      url: "/status"
+    },
+    log: {
+      info(payload) {
+        loggedPayload = payload;
+      }
+    }
+  };
+  const reply = {
+    statusCode: 204
+  };
+
+  await fastify.hooks.onRequest(request);
+  await fastify.hooks.onResponse(request, reply);
+
+  assert.equal(loggedPayload.surface, "");
+});

package/server/runtime/index.js

@@ -0,0 +1,6 @@
+export { AppError, createValidationError } from "./errors.js";
+export { parsePositiveInteger } from "./integers.js";
+export { requireAuth } from "./serviceAuthorization.js";
+export { installServiceRegistrationApi, resolveServiceRegistrations } from "../registries/serviceRegistrationRegistry.js";
+export { registerDomainEventListener } from "../registries/domainEventListenerRegistry.js";
+export { registerBootstrapPayloadContributor } from "../registries/bootstrapPayloadContributorRegistry.js";

package/server/runtime/integers.js

@@ -0,0 +1,13 @@
+import { normalizePositiveInteger } from "../../shared/support/normalize.js";
+
+function parsePositiveInteger(value) {
+  return normalizePositiveInteger(value, {
+    fallback: null
+  });
+}
+
+function normalizeNullablePositiveInteger(value) {
+  return parsePositiveInteger(value);
+}
+
+export { parsePositiveInteger, normalizeNullablePositiveInteger };