@jskit-ai/kernel 0.1.244 → 0.1.246

package/server/{runtime/fastifyBootstrap.test.js → http/errorHandling.test.js}

@@ -1,22 +1,27 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 
-import { AppError, isAppError } from "./errors.js";
+import { AppError, isAppError } from "../runtime/errors.js";
 import {
   normalizeBodylessContentTypeHeader,
   registerApiErrorHandler,
   registerBodylessContentTypeNormalizer,
-  registerJsonApiContentTypeParser,
-  registerRequestLoggingHooks
-} from "./fastifyBootstrap.js";
+  registerJsonApiContentTypeParser
+} from "./errorHandling.js";
 
 function createFastifyStub() {
-  return {
+  const fastify = {
     errorHandler: null,
     hooks: {},
     contentTypeParsers: new Map(),
+    logged: [],
     log: {
-      error() {}
+      error(fields, message) {
+        this.owner.logged.push({ level: "error", fields, message });
+      },
+      info(fields, message) {
+        this.owner.logged.push({ level: "info", fields, message });
+      }
     },
     setErrorHandler(handler) {
       this.errorHandler = handler;
@@ -24,6 +29,9 @@ function createFastifyStub() {
     addHook(name, handler) {
       this.hooks[name] = handler;
     },
+    getDefaultJsonParser() {
+      return function parseJsonBody() {};
+    },
     hasContentTypeParser(contentType) {
       return this.contentTypeParsers.has(String(contentType || "").trim().toLowerCase());
     },
@@ -34,6 +42,32 @@ function createFastifyStub() {
       });
     }
   };
+  fastify.log.owner = fastify;
+  return fastify;
+}
+
+function transportRequest() {
+  return {
+    routeOptions: {
+      config: {
+        transport: {
+          kind: "jsonapi-resource",
+          contentType: "application/vnd.api+json",
+          error(currentError, { statusCode, code }) {
+            return {
+              errors: [
+                {
+                  status: String(statusCode),
+                  code,
+                  title: currentError.message
+                }
+              ]
+            };
+          }
+        }
+      }
+    }
+  };
 }
 
 function createReplyStub() {
@@ -227,22 +261,7 @@ test("registerApiErrorHandler uses route transport error serializer when present
 
   fastify.errorHandler(
     error,
-    {
-      routeTransport: {
-        contentType: "application/vnd.api+json",
-        error(currentError, { statusCode, code }) {
-          return {
-            errors: [
-              {
-                status: String(statusCode),
-                code,
-                title: currentError.message
-              }
-            ]
-          };
-        }
-      }
-    },
+    transportRequest(),
     reply
   );
 
@@ -259,55 +278,46 @@ test("registerApiErrorHandler uses route transport error serializer when present
   });
 });
 
-test("registerApiErrorHandler uses route config transport runtime serializer before handler attachment", () => {
+test("transport routes log 5xx AppErrors and keep their headers", () => {
   const fastify = createFastifyStub();
   registerApiErrorHandler(fastify, { isAppError });
 
   const reply = createReplyStub();
-  const error = new AppError(401, "Authentication required.", {
-    code: "AUTH_POLICY_ERROR"
+  const error = new AppError(503, "Try again shortly.", {
+    code: "service_unavailable",
+    headers: {
+      "Retry-After": "5"
+    }
   });
 
-  fastify.errorHandler(
-    error,
-    {
-      routeOptions: {
-        config: {
-          transport: {
-            kind: "jsonapi-resource",
-            contentType: "application/vnd.api+json",
-            runtime: {
-              contentType: "application/vnd.api+json",
-              error(currentError, { statusCode, code }) {
-                return {
-                  errors: [
-                    {
-                      status: String(statusCode),
-                      code,
-                      title: currentError.message
-                    }
-                  ]
-                };
-              }
-            }
-          }
-        }
-      }
-    },
-    reply
-  );
+  fastify.errorHandler(error, transportRequest(), reply);
 
-  assert.equal(reply.statusCode, 401);
+  assert.equal(reply.statusCode, 503);
+  assert.equal(reply.headers["Retry-After"], "5");
   assert.equal(reply.headers["Content-Type"], "application/vnd.api+json");
-  assert.deepEqual(reply.payload, {
-    errors: [
-      {
-        status: "401",
-        code: "AUTH_POLICY_ERROR",
-        title: "Authentication required."
-      }
-    ]
+  assert.equal(reply.payload.errors[0].code, "service_unavailable");
+  assert.deepEqual(fastify.logged.map(({ level, message }) => [level, message]), [["error", "AppError 5xx"]]);
+});
+
+test("Fastify client errors are logged below error level and server errors at error level", () => {
+  const fastify = createFastifyStub();
+  registerApiErrorHandler(fastify, { isAppError });
+
+  const tooLarge = Object.assign(new Error("Request body is too large"), {
+    statusCode: 413,
+    code: "FST_ERR_CTP_BODY_TOO_LARGE"
   });
+  const tooLargeReply = createReplyStub();
+  fastify.errorHandler(tooLarge, transportRequest(), tooLargeReply);
+  assert.equal(tooLargeReply.statusCode, 413);
+  assert.equal(tooLargeReply.payload.errors[0].code, "FST_ERR_CTP_BODY_TOO_LARGE");
+
+  fastify.errorHandler(new Error("Unexpected DB failure"), {}, createReplyStub());
+
+  assert.deepEqual(fastify.logged.map(({ level, fields }) => [level, fields.statusCode]), [
+    ["info", 413],
+    ["error", undefined]
+  ]);
 });
 
 test("registerJsonApiContentTypeParser installs the JSON:API media type parser once", () => {
@@ -358,61 +368,3 @@ test("registerBodylessContentTypeNormalizer installs the request hook once", asy
     "content-length": "0"
   });
 });
-
-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/http/lib/routeRegistration.js

@@ -3,49 +3,30 @@ import { AppError } from "../../runtime/errors.js";
 import { defaultApplyRoutePolicy } from "../../support/routePolicyConfig.js";
 import { resolveDefaultSurfaceId } from "../../support/appConfig.js";
 import { defaultMissingHandler } from "../../support/defaultMissingHandler.js";
-import { registerJsonApiContentTypeParser } from "../../runtime/fastifyBootstrap.js";
+import { registerJsonApiContentTypeParser } from "../errorHandling.js";
 import { RouteRegistrationError } from "./errors.js";
 import { executeMiddlewareStack, normalizeRuntimeMiddlewareConfig, resolveRouteMiddlewareHandlers } from "./middlewareRuntime.js";
 import { attachDirectRequestActionExecutor } from "../directRequestActionExecutor.js";
-import { normalizeRouteOutputTransform, normalizeRouteTransport } from "./routeTransport.js";
+import { resolveRouteLabel } from "./routeSupport.js";
+import { JSON_API_CONTENT_TYPE } from "./routeTransport.js";
 
 const { structuredClone: cloneRouteSchema } = globalThis;
 const UNSAFE_BODY_METHODS = Object.freeze(["POST", "PUT", "PATCH"]);
-const JSON_API_CONTENT_TYPE = "application/vnd.api+json";
+const REQUEST_INPUT_KEYS = Object.freeze(["body", "query", "params"]);
 
 function toFastifyRouteOptions(route) {
-  const sourceRoute = normalizeObject(route);
-  const schema = cloneRouteSchema(sourceRoute.schema);
-  if (shouldStripFastifyBodySchema(sourceRoute, schema)) {
+  const schema = cloneRouteSchema(route.schema);
+  if (shouldStripFastifyBodySchema(route, schema)) {
     delete schema.body;
   }
-  const existingConfig = normalizeObject(sourceRoute.config);
-  const transportKind = normalizeText(sourceRoute?.transport?.kind).toLowerCase();
-  const existingTransportConfig =
-    existingConfig.transport && typeof existingConfig.transport === "object" && !Array.isArray(existingConfig.transport)
-      ? normalizeObject(existingConfig.transport)
-      : {};
   return {
-    method: sourceRoute.method,
-    url: sourceRoute.path,
+    method: route.method,
+    url: route.path,
     ...(schema ? { schema } : {}),
-    ...(sourceRoute.bodyLimit ? { bodyLimit: sourceRoute.bodyLimit } : {}),
+    ...(route.bodyLimit ? { bodyLimit: route.bodyLimit } : {}),
     config: {
-      ...existingConfig,
-      ...(transportKind
-        ? {
-            transport: {
-              ...existingTransportConfig,
-              kind: transportKind,
-              runtime: sourceRoute.transport,
-              ...(normalizeText(sourceRoute?.transport?.contentType)
-                ? {
-                    contentType: normalizeText(sourceRoute.transport.contentType)
-                  }
-                : {})
-            }
-          }
-        : {})
+      ...normalizeObject(route.config),
+      ...(route.transport ? { transport: route.transport } : {})
     }
   };
 }
@@ -112,19 +93,6 @@ function enforceRequestContentType({ request = null, route = null, transport = n
   });
 }
 
-function attachRouteTransport(request, transport = null) {
-  if (!request || !transport) {
-    return;
-  }
-
-  Object.defineProperty(request, "routeTransport", {
-    value: transport,
-    enumerable: false,
-    configurable: true,
-    writable: false
-  });
-}
-
 function replyHasHeader(reply, name = "") {
   const normalizedName = String(name || "").trim().toLowerCase();
   if (!normalizedName || !reply) {
@@ -146,75 +114,21 @@ function replyHasHeader(reply, name = "") {
   return false;
 }
 
-function normalizeRouteInputTransforms(route) {
-  const routeInput = route?.input;
-  if (routeInput == null) {
-    return null;
-  }
-
-  if (!routeInput || typeof routeInput !== "object" || Array.isArray(routeInput)) {
-    throw new RouteRegistrationError(
-      `Route ${String(route?.method || "<unknown>")} ${String(route?.path || "<unknown>")} input must be an object.`
-    );
-  }
-
-  const normalized = {};
-  for (const key of ["body", "query", "params"]) {
-    if (!Object.hasOwn(routeInput, key)) {
-      continue;
-    }
-
-    const transform = routeInput[key];
-    if (transform == null) {
-      continue;
+async function buildRequestInput(request, { inputTransforms = null, transportInputTransforms = null } = {}) {
+  const input = {};
+  for (const key of REQUEST_INPUT_KEYS) {
+    let value = request?.[key];
+    const transportTransform = transportInputTransforms?.[key];
+    if (typeof transportTransform === "function" && (key !== "body" || value !== undefined)) {
+      value = await transportTransform(value, request);
     }
-
-    if (typeof transform !== "function") {
-      throw new RouteRegistrationError(
-        `Route ${String(route?.method || "<unknown>")} ${String(route?.path || "<unknown>")} input.${key} must be a function.`
-      );
+    const inputTransform = inputTransforms?.[key];
+    if (typeof inputTransform === "function") {
+      value = await inputTransform(value, request);
     }
-
-    normalized[key] = transform;
-  }
-
-  return Object.freeze(normalized);
-}
-
-async function buildRequestInput({ request = null, inputTransforms = null, transportInputTransforms = null } = {}) {
-  const transforms = inputTransforms && typeof inputTransforms === "object" ? inputTransforms : {};
-  const transportTransforms =
-    transportInputTransforms && typeof transportInputTransforms === "object" ? transportInputTransforms : {};
-
-  let body = request?.body;
-  if (body !== undefined && typeof transportTransforms.body === "function") {
-    body = await transportTransforms.body(body, request);
-  }
-  if (typeof transforms.body === "function") {
-    body = await transforms.body(body, request);
-  }
-
-  let query = request?.query;
-  if (typeof transportTransforms.query === "function") {
-    query = await transportTransforms.query(query, request);
-  }
-  if (typeof transforms.query === "function") {
-    query = await transforms.query(query, request);
-  }
-
-  let params = request?.params;
-  if (typeof transportTransforms.params === "function") {
-    params = await transportTransforms.params(params, request);
-  }
-  if (typeof transforms.params === "function") {
-    params = await transforms.params(params, request);
+    input[key] = value;
   }
-
-  return Object.freeze({
-    body,
-    query,
-    params
-  });
+  return Object.freeze(input);
 }
 
 function wrapReplySend({ reply = null, request = null, route = null, outputTransform = null, transport = null } = {}) {
@@ -248,9 +162,7 @@ function wrapReplySend({ reply = null, request = null, route = null, outputTrans
       });
 
       if (transportedPayload && typeof transportedPayload.then === "function") {
-        throw new RouteRegistrationError(
-          `Route ${String(route?.method || "<unknown>")} ${String(route?.path || "<unknown>")} transport.response must return synchronously.`
-        );
+        throw new RouteRegistrationError(`Route ${resolveRouteLabel(route)} transport.response must return synchronously.`);
       }
 
       nextPayload = transportedPayload === undefined ? nextPayload : transportedPayload;
@@ -266,9 +178,7 @@ function wrapReplySend({ reply = null, request = null, route = null, outputTrans
       });
 
       if (transformedPayload && typeof transformedPayload.then === "function") {
-        throw new RouteRegistrationError(
-          `Route ${String(route?.method || "<unknown>")} ${String(route?.path || "<unknown>")} output transform must return synchronously.`
-        );
+        throw new RouteRegistrationError(`Route ${resolveRouteLabel(route)} output transform must return synchronously.`);
       }
 
       nextPayload = transformedPayload === undefined ? nextPayload : transformedPayload;
@@ -317,39 +227,17 @@ function registerRoutes(
   }
 
   for (const route of publicRoutes) {
-    const routeTransport = normalizeRouteTransport(route?.transport, {
-      context: `Route ${String(route?.method || "<unknown>")} ${String(route?.path || "<unknown>")} transport`,
-      ErrorType: RouteRegistrationError
-    });
-    const routeOutputTransform = normalizeRouteOutputTransform(route?.output, {
-      context: `Route ${String(route?.method || "<unknown>")} ${String(route?.path || "<unknown>")} output`,
-      ErrorType: RouteRegistrationError
-    });
-    const normalizedRoute = {
-      ...route,
-      transport: routeTransport,
-      output: routeOutputTransform
-    };
-    const baseOptions = toFastifyRouteOptions(normalizedRoute);
-    const routeOptions = policyApplier(baseOptions, normalizedRoute);
-    const routeHandler = typeof normalizedRoute?.handler === "function" ? normalizedRoute.handler : fallbackHandler;
-    const resolvedMiddlewareHandlers = resolveRouteMiddlewareHandlers(normalizedRoute, runtimeMiddlewareConfig);
-    const routeInputTransforms = normalizeRouteInputTransforms(normalizedRoute);
+    const routeOptions = policyApplier(toFastifyRouteOptions(route), route);
+    const routeHandler = typeof route.handler === "function" ? route.handler : fallbackHandler;
+    const resolvedMiddlewareHandlers = resolveRouteMiddlewareHandlers(route, runtimeMiddlewareConfig);
+    const routeTransport = route.transport || null;
     const routeActionDefaultSurface = resolveDefaultSurfaceId(null, {
-      defaultSurfaceId: route?.surface || routeOptions?.config?.surface || requestActionDefaultSurface
+      defaultSurfaceId: route.surface || routeOptions?.config?.surface || requestActionDefaultSurface
     });
 
     fastify.route({
       ...routeOptions,
       handler: async (request, reply) => {
-        if (!request.routeOptions || typeof request.routeOptions !== "object") {
-          request.routeOptions = {
-            config: normalizeObject(routeOptions?.config)
-          };
-        } else if (!request.routeOptions.config || typeof request.routeOptions.config !== "object") {
-          request.routeOptions.config = normalizeObject(routeOptions?.config);
-        }
-
         attachDirectRequestActionExecutor({
           actions,
           request,
@@ -358,18 +246,16 @@ function registerRoutes(
           defaultSurfaceId: routeActionDefaultSurface
         });
 
-        attachRouteTransport(request, routeTransport);
         enforceRequestContentType({
           request,
-          route: normalizedRoute,
+          route,
           transport: routeTransport
         });
 
         const transportInputTransforms = routeTransport?.request || null;
-        if (routeInputTransforms || transportInputTransforms) {
-          request.input = await buildRequestInput({
-            request,
-            inputTransforms: routeInputTransforms,
+        if (route.input || transportInputTransforms) {
+          request.input = await buildRequestInput(request, {
+            inputTransforms: route.input,
             transportInputTransforms
           });
         }
@@ -377,8 +263,8 @@ function registerRoutes(
         wrapReplySend({
           reply,
           request,
-          route: normalizedRoute,
-          outputTransform: routeOutputTransform,
+          route,
+          outputTransform: route.output,
           transport: routeTransport
         });
 

package/server/http/lib/routeTransport.js

@@ -1,5 +1,6 @@
 import { normalizeObject, normalizeText } from "../../../shared/support/normalize.js";
 
+const JSON_API_CONTENT_TYPE = "application/vnd.api+json";
 const ROUTE_TRANSPORT_KINDS = Object.freeze([
   "command",
   "jsonapi-resource"
@@ -120,6 +121,7 @@ function normalizeRouteTransport(value, { context = "route transport", ErrorType
 }
 
 export {
+  JSON_API_CONTENT_TYPE,
   ROUTE_TRANSPORT_KINDS,
   normalizeRouteOutputTransform,
   normalizeRouteTransport

package/server/http/lib/routeValidator.js

@@ -1,13 +1,12 @@
 import { normalizeObject, normalizeText } from "../../../shared/support/normalize.js";
 import {
-  normalizeSchemaDefinition,
+  normalizeSingleSchemaDefinition,
   resolveSchemaTransportSchemaDefinition,
   validateSchemaPayload
 } from "../../../shared/validators/index.js";
 import { RouteDefinitionError } from "./errors.js";
 import { resolveRouteLabel } from "./routeSupport.js";
 
-const ROUTE_VALIDATOR_SYMBOL = "@jskit-ai/kernel/http/routeValidator";
 const JSON_REST_TRANSPORT_EXTENSION_KEY = "x-json-rest-schema";
 const VALIDATOR_OPTION_KEYS = Object.freeze([
   "meta",
@@ -50,7 +49,7 @@ function stripJsonRestTransportExtensions(value) {
 
 function normalizeRouteSchemaSection(value, { context = "route section", defaultMode = "patch" } = {}) {
   try {
-    return normalizeSchemaDefinition(value, {
+    return normalizeSingleSchemaDefinition(value, {
       context,
       defaultMode
     });
@@ -219,7 +218,8 @@ function normalizeRouteValidatorDefinition(sourceDefinition, { context = "route
   return Object.freeze(normalized);
 }
 
-function compileNormalizedRouteValidator(normalizedValidator) {
+function compileRouteValidator(validator, { context = "route validator" } = {}) {
+  const normalizedValidator = normalizeRouteValidatorDefinition(validator, { context });
   const schema = {};
   const input = {};
 
@@ -306,48 +306,6 @@ function compileNormalizedRouteValidator(normalizedValidator) {
   return Object.freeze(compiled);
 }
 
-function normalizeRouteValidatorSource(validator, { context = "route validator" } = {}) {
-  if (validator && typeof validator === "object") {
-    const precompiled = validator[ROUTE_VALIDATOR_SYMBOL];
-    if (precompiled && typeof precompiled === "object") {
-      return precompiled;
-    }
-  }
-
-  return normalizeRouteValidatorDefinition(validator, {
-    context
-  });
-}
-
-function compileRouteValidator(validator, { context = "route validator" } = {}) {
-  return compileNormalizedRouteValidator(
-    normalizeRouteValidatorSource(validator, {
-      context
-    })
-  );
-}
-
-function defineRouteValidator(definition = {}) {
-  const normalized = normalizeRouteValidatorDefinition(definition, {
-    context: "defineRouteValidator()"
-  });
-
-  const validator = {
-    toRouteOptions() {
-      return compileNormalizedRouteValidator(normalized);
-    }
-  };
-
-  Object.defineProperty(validator, ROUTE_VALIDATOR_SYMBOL, {
-    value: normalized,
-    enumerable: false,
-    configurable: false,
-    writable: false
-  });
-
-  return Object.freeze(validator);
-}
-
 function resolveRouteValidatorOptions({
   method = "",
   path = "",
@@ -401,4 +359,4 @@ function resolveRouteValidatorOptions({
   };
 }
 
-export { defineRouteValidator, compileRouteValidator, resolveRouteValidatorOptions };
+export { compileRouteValidator, resolveRouteValidatorOptions };