@jskit-ai/kernel 0.1.55 → 0.1.56

package/server/http/lib/routeRegistration.js

@@ -1,28 +1,137 @@
-import { normalizeArray, normalizeObject } from "../../../shared/support/normalize.js";
+import { normalizeArray, normalizeObject, normalizeText } from "../../../shared/support/normalize.js";
+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 { RouteRegistrationError } from "./errors.js";
 import { executeMiddlewareStack, normalizeRuntimeMiddlewareConfig, resolveRouteMiddlewareHandlers } from "./middlewareRuntime.js";
 import { attachRequestScope } from "./requestScope.js";
 import { attachRequestActionExecutor } from "./requestActionExecutor.js";
+import { normalizeRouteOutputTransform, normalizeRouteTransport } 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";
 
 function toFastifyRouteOptions(route) {
   const sourceRoute = normalizeObject(route);
   const schema = cloneRouteSchema(sourceRoute.schema);
+  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,
     ...(schema ? { schema } : {}),
     ...(sourceRoute.bodyLimit ? { bodyLimit: sourceRoute.bodyLimit } : {}),
     config: {
-      ...(sourceRoute.config || {})
+      ...existingConfig,
+      ...(transportKind
+        ? {
+            transport: {
+              ...existingTransportConfig,
+              kind: transportKind,
+              runtime: sourceRoute.transport,
+              ...(normalizeText(sourceRoute?.transport?.contentType)
+                ? {
+                    contentType: normalizeText(sourceRoute.transport.contentType)
+                  }
+                : {})
+            }
+          }
+        : {})
     }
   };
 }
 
+function normalizeHeaderValue(value) {
+  if (Array.isArray(value)) {
+    return String(value[0] || "").trim();
+  }
+  return String(value || "").trim();
+}
+
+function normalizeMediaType(value = "") {
+  return normalizeHeaderValue(value)
+    .split(";")[0]
+    .trim()
+    .toLowerCase();
+}
+
+function routeDefinesRequestBody(route = null) {
+  if (!route || typeof route !== "object") {
+    return false;
+  }
+
+  return route.body != null || route.schema?.body != null;
+}
+
+function shouldEnforceRequestContentType(method = "", transport = null, route = null) {
+  return (
+    UNSAFE_BODY_METHODS.includes(String(method || "").toUpperCase()) &&
+    normalizeText(transport?.contentType).length > 0 &&
+    routeDefinesRequestBody(route)
+  );
+}
+
+function routeRequiresJsonApiContentTypeParser(route = null) {
+  return routeDefinesRequestBody(route) && normalizeMediaType(route?.transport?.contentType) === JSON_API_CONTENT_TYPE;
+}
+
+function enforceRequestContentType({ request = null, route = null, transport = null } = {}) {
+  if (!shouldEnforceRequestContentType(route?.method, transport, route)) {
+    return;
+  }
+
+  const expectedContentType = normalizeMediaType(transport?.contentType);
+  const actualContentType = normalizeMediaType(request?.headers?.["content-type"]);
+  if (actualContentType === expectedContentType) {
+    return;
+  }
+
+  throw new AppError(415, `Content-Type must be ${transport.contentType}.`, {
+    code: "unsupported_media_type"
+  });
+}
+
+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) {
+    return false;
+  }
+
+  if (typeof reply.hasHeader === "function") {
+    return reply.hasHeader(normalizedName);
+  }
+
+  if (typeof reply.getHeader === "function") {
+    return reply.getHeader(normalizedName) != null;
+  }
+
+  if (reply.headers && typeof reply.headers === "object") {
+    return Object.keys(reply.headers).some((key) => String(key || "").trim().toLowerCase() === normalizedName);
+  }
+
+  return false;
+}
+
 function normalizeRouteInputTransforms(route) {
   const routeInput = route?.input;
   if (routeInput == null) {
@@ -37,7 +146,7 @@ function normalizeRouteInputTransforms(route) {
 
   const normalized = {};
   for (const key of ["body", "query", "params"]) {
-    if (!Object.prototype.hasOwnProperty.call(routeInput, key)) {
+    if (!Object.hasOwn(routeInput, key)) {
       continue;
     }
 
@@ -58,12 +167,34 @@ function normalizeRouteInputTransforms(route) {
   return Object.freeze(normalized);
 }
 
-function buildRequestInput({ request = null, inputTransforms = null } = {}) {
+async function buildRequestInput({ request = null, inputTransforms = null, transportInputTransforms = null } = {}) {
   const transforms = inputTransforms && typeof inputTransforms === "object" ? inputTransforms : {};
+  const transportTransforms =
+    transportInputTransforms && typeof transportInputTransforms === "object" ? transportInputTransforms : {};
 
-  const body = typeof transforms.body === "function" ? transforms.body(request?.body, request) : request?.body;
-  const query = typeof transforms.query === "function" ? transforms.query(request?.query, request) : request?.query;
-  const params = typeof transforms.params === "function" ? transforms.params(request?.params, request) : request?.params;
+  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);
+  }
 
   return Object.freeze({
     body,
@@ -72,6 +203,62 @@ function buildRequestInput({ request = null, inputTransforms = null } = {}) {
   });
 }
 
+function wrapReplySend({ reply = null, request = null, route = null, outputTransform = null, transport = null } = {}) {
+  if (!reply || typeof reply.send !== "function") {
+    return;
+  }
+
+  const originalSend = reply.send.bind(reply);
+  reply.send = function transformedSend(payload) {
+    let nextPayload = payload;
+    if (typeof transport?.response === "function") {
+      const transportedPayload = transport.response(payload, {
+        request,
+        reply,
+        route,
+        transport,
+        statusCode: Number(reply?.statusCode || 200)
+      });
+
+      if (transportedPayload && typeof transportedPayload.then === "function") {
+        throw new RouteRegistrationError(
+          `Route ${String(route?.method || "<unknown>")} ${String(route?.path || "<unknown>")} transport.response must return synchronously.`
+        );
+      }
+
+      nextPayload = transportedPayload === undefined ? nextPayload : transportedPayload;
+    }
+
+    if (typeof outputTransform === "function") {
+      const transformedPayload = outputTransform(nextPayload, {
+        request,
+        reply,
+        route,
+        transport,
+        statusCode: Number(reply?.statusCode || 200)
+      });
+
+      if (transformedPayload && typeof transformedPayload.then === "function") {
+        throw new RouteRegistrationError(
+          `Route ${String(route?.method || "<unknown>")} ${String(route?.path || "<unknown>")} output transform must return synchronously.`
+        );
+      }
+
+      nextPayload = transformedPayload === undefined ? nextPayload : transformedPayload;
+    }
+
+    if (
+      normalizeText(transport?.contentType) &&
+      Number(reply?.statusCode || 200) !== 204 &&
+      !replyHasHeader(reply, "content-type")
+    ) {
+      reply.header("Content-Type", transport.contentType);
+    }
+
+    return originalSend(nextPayload);
+  };
+}
+
 function registerRoutes(
   fastify,
   {
@@ -99,12 +286,29 @@ function registerRoutes(
   const fallbackHandler = typeof missingHandler === "function" ? missingHandler : defaultMissingHandler;
   const runtimeMiddlewareConfig = normalizeRuntimeMiddlewareConfig(middleware);
 
+  if (normalizedRoutes.some((route) => routeRequiresJsonApiContentTypeParser(route))) {
+    registerJsonApiContentTypeParser(fastify);
+  }
+
   for (const route of normalizedRoutes) {
-    const baseOptions = toFastifyRouteOptions(route);
-    const routeOptions = policyApplier(baseOptions, route);
-    const routeHandler = typeof route?.handler === "function" ? route.handler : fallbackHandler;
-    const resolvedMiddlewareHandlers = resolveRouteMiddlewareHandlers(route, runtimeMiddlewareConfig);
-    const routeInputTransforms = normalizeRouteInputTransforms(route);
+    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 routeActionDefaultSurface = resolveDefaultSurfaceId(null, {
       defaultSurfaceId: route?.surface || routeOptions?.config?.surface || requestActionDefaultSurface
     });
@@ -141,13 +345,30 @@ function registerRoutes(
           defaultSurfaceId: routeActionDefaultSurface
         });
 
-        if (routeInputTransforms) {
-          request.input = buildRequestInput({
+        attachRouteTransport(request, routeTransport);
+        enforceRequestContentType({
+          request,
+          route: normalizedRoute,
+          transport: routeTransport
+        });
+
+        const transportInputTransforms = routeTransport?.request || null;
+        if (routeInputTransforms || transportInputTransforms) {
+          request.input = await buildRequestInput({
             request,
-            inputTransforms: routeInputTransforms
+            inputTransforms: routeInputTransforms,
+            transportInputTransforms
           });
         }
 
+        wrapReplySend({
+          reply,
+          request,
+          route: normalizedRoute,
+          outputTransform: routeOutputTransform,
+          transport: routeTransport
+        });
+
         await executeMiddlewareStack(resolvedMiddlewareHandlers, request, reply);
         if (reply?.sent) {
           return;

package/server/http/lib/routeTransport.js

@@ -0,0 +1,126 @@
+import { normalizeObject, normalizeText } from "../../../shared/support/normalize.js";
+
+const ROUTE_TRANSPORT_KINDS = Object.freeze([
+  "command",
+  "jsonapi-resource"
+]);
+
+function normalizeRouteOutputTransform(value, { context = "route output", ErrorType = Error } = {}) {
+  if (value == null) {
+    return null;
+  }
+
+  if (typeof value !== "function") {
+    throw new ErrorType(`${context} must be a function.`);
+  }
+
+  return value;
+}
+
+function normalizeRouteTransport(value, { context = "route transport", ErrorType = Error } = {}) {
+  if (value == null) {
+    return null;
+  }
+
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new ErrorType(`${context} must be an object.`);
+  }
+
+  const source = normalizeObject(value);
+  const unsupportedKeys = Object.keys(source).filter(
+    (key) => !["kind", "request", "response", "error", "contentType"].includes(key)
+  );
+  if (unsupportedKeys.length > 0) {
+    throw new ErrorType(`${context}.${unsupportedKeys[0]} is not supported.`);
+  }
+
+  const normalized = {};
+
+  if (Object.hasOwn(source, "kind")) {
+    const kind = normalizeText(source.kind).toLowerCase();
+    if (!kind) {
+      throw new ErrorType(`${context}.kind must be a non-empty string.`);
+    }
+    if (!ROUTE_TRANSPORT_KINDS.includes(kind)) {
+      throw new ErrorType(
+        `${context}.kind must be one of: ${ROUTE_TRANSPORT_KINDS.join(", ")}.`
+      );
+    }
+    normalized.kind = kind;
+  }
+
+  if (Object.hasOwn(source, "request")) {
+    const request = source.request;
+    if (request != null) {
+      if (!request || typeof request !== "object" || Array.isArray(request)) {
+        throw new ErrorType(`${context}.request must be an object.`);
+      }
+
+      const requestSource = normalizeObject(request);
+      const unsupportedRequestKeys = Object.keys(requestSource).filter(
+        (key) => !["body", "query", "params"].includes(key)
+      );
+      if (unsupportedRequestKeys.length > 0) {
+        throw new ErrorType(`${context}.request.${unsupportedRequestKeys[0]} is not supported.`);
+      }
+
+      const normalizedRequest = {};
+      for (const key of ["body", "query", "params"]) {
+        if (!Object.hasOwn(requestSource, key)) {
+          continue;
+        }
+
+        const transform = requestSource[key];
+        if (transform == null) {
+          continue;
+        }
+
+        if (typeof transform !== "function") {
+          throw new ErrorType(`${context}.request.${key} must be a function.`);
+        }
+
+        normalizedRequest[key] = transform;
+      }
+
+      if (Object.keys(normalizedRequest).length > 0) {
+        normalized.request = Object.freeze(normalizedRequest);
+      }
+    }
+  }
+
+  if (Object.hasOwn(source, "response")) {
+    const responseTransform = source.response;
+    if (responseTransform != null && typeof responseTransform !== "function") {
+      throw new ErrorType(`${context}.response must be a function.`);
+    }
+    if (responseTransform) {
+      normalized.response = responseTransform;
+    }
+  }
+
+  if (Object.hasOwn(source, "error")) {
+    const errorTransform = source.error;
+    if (errorTransform != null && typeof errorTransform !== "function") {
+      throw new ErrorType(`${context}.error must be a function.`);
+    }
+    if (errorTransform) {
+      normalized.error = errorTransform;
+    }
+  }
+
+  if (Object.hasOwn(source, "contentType")) {
+    const contentType = normalizeText(source.contentType);
+    if (!contentType) {
+      throw new ErrorType(`${context}.contentType must be a non-empty string.`);
+    }
+    normalized.contentType = contentType;
+  }
+
+  return Object.freeze(normalized);
+}
+
+export {
+  ROUTE_TRANSPORT_KINDS,
+  normalizeRouteOutputTransform,
+  normalizeRouteTransport
+};