@jskit-ai/kernel 0.1.245 → 0.1.246

package/{shared → server}/actions/registry.test.js

@@ -26,10 +26,6 @@ test("action registry executes latest version by default", async () => {
             surfaces: ["app", "admin", "console"],
             input: { schema: createPassThroughSchema() },
             idempotency: "none",
-            audit: {
-              actionName: "settings.read"
-            },
-            observability: {},
             async execute() {
               calls.push("version-one");
               return {
@@ -46,10 +42,6 @@ test("action registry executes latest version by default", async () => {
             surfaces: ["app", "admin", "console"],
             input: { schema: createPassThroughSchema() },
             idempotency: "none",
-            audit: {
-              actionName: "settings.read"
-            },
-            observability: {},
             async execute() {
               calls.push("v2");
               return {
@@ -107,10 +99,6 @@ test("action registry validates action input with a single schema contract", asy
               })
             },
             idempotency: "optional",
-            audit: {
-              actionName: "workspace.settings.update"
-            },
-            observability: {},
             async execute(input) {
               return input;
             }
@@ -157,10 +145,6 @@ test("action registry fails startup on duplicate action id + version", () => {
                 surfaces: ["app"],
                 input: { schema: createPassThroughSchema() },
                 idempotency: "optional",
-                audit: {
-                  actionName: "settings.profile.update"
-                },
-                observability: {},
                 async execute() {
                   return {
                     ok: true
@@ -182,10 +166,6 @@ test("action registry fails startup on duplicate action id + version", () => {
                 surfaces: ["app"],
                 input: { schema: createPassThroughSchema() },
                 idempotency: "optional",
-                audit: {
-                  actionName: "settings.profile.update"
-                },
-                observability: {},
                 async execute() {
                   return {
                     ok: true
@@ -216,10 +196,6 @@ test("action registry rejects invalid version requests", async () => {
             surfaces: ["app"],
             input: { schema: createPassThroughSchema() },
             idempotency: "none",
-            audit: {
-              actionName: "settings.read"
-            },
-            observability: {},
             async execute() {
               return {
                 ok: true
@@ -268,10 +244,6 @@ test("action registry ignores unknown extra fields", async () => {
             consoleUsersOnly: true,
             input: { schema: createPassThroughSchema() },
             idempotency: "none",
-            audit: {
-              actionName: "settings.internal.ping"
-            },
-            observability: {},
             async execute() {
               return { ok: true };
             }
@@ -311,10 +283,6 @@ test("action registry enforces action-level permissions", async () => {
             },
             input: { schema: createPassThroughSchema() },
             idempotency: "optional",
-            audit: {
-              actionName: "workspace.settings.update"
-            },
-            observability: {},
             async execute() {
               return { ok: true };
             }
@@ -353,3 +321,73 @@ test("action registry enforces action-level permissions", async () => {
 
   assert.deepEqual(allowed, { ok: true });
 });
+
+function createSingleActionRegistry(action, options = {}) {
+  return createActionRegistry({
+    ...options,
+    contributors: [
+      {
+        contributorId: "tests.single",
+        domain: "tests",
+        actions: [
+          {
+            id: "tests.run",
+            version: 1,
+            kind: "command",
+            channels: ["api"],
+            surfaces: ["app"],
+            input: { schema: createPassThroughSchema() },
+            ...action
+          }
+        ]
+      }
+    ]
+  });
+}
+
+test("action registry requires an idempotency key only for required actions", async () => {
+  const registry = createSingleActionRegistry({
+    idempotency: "required",
+    async execute() {
+      return { ok: true };
+    }
+  }, { logger: null });
+  const context = { channel: "api", surface: "app" };
+
+  await assert.rejects(
+    () => registry.execute({ actionId: "tests.run", context }),
+    { code: "ACTION_IDEMPOTENCY_KEY_REQUIRED", status: 400 }
+  );
+  assert.deepEqual(
+    await registry.execute({ actionId: "tests.run", context: { ...context, requestMeta: { commandId: " cmd-1 " } } }),
+    { ok: true }
+  );
+});
+
+test("action registry logs one debug entry per outcome and returns the result directly", async () => {
+  const entries = [];
+  const logger = { debug: (payload, message) => entries.push({ payload, message }) };
+  let fail = false;
+  const registry = createSingleActionRegistry({
+    idempotency: "optional",
+    async execute() {
+      if (fail) {
+        throw Object.assign(new Error("boom"), { code: "TEST_FAILED" });
+      }
+      return { ok: true };
+    }
+  }, { logger });
+  const context = { channel: "api", surface: "app", requestMeta: { requestId: "req-1" } };
+
+  assert.deepEqual(await registry.execute({ actionId: "tests.run", context }), { ok: true });
+  fail = true;
+  await assert.rejects(() => registry.execute({ actionId: "tests.run", context }), { code: "TEST_FAILED" });
+
+  assert.deepEqual(
+    entries.map(({ payload, message }) => ({ ...payload, durationMs: typeof payload.durationMs, message })),
+    [
+      { action: "tests.run", version: 1, channel: "api", surface: "app", requestId: "req-1", durationMs: "number", outcome: "success", errorCode: null, message: "action.execution" },
+      { action: "tests.run", version: 1, channel: "api", surface: "app", requestId: "req-1", durationMs: "number", outcome: "failure", errorCode: "TEST_FAILED", message: "action.execution" }
+    ]
+  );
+});

package/server/actions/requestMeta.js

@@ -0,0 +1,17 @@
+import { normalizeText } from "../../shared/support/normalize.js";
+
+const TEXT_FIELDS = Object.freeze(["requestId", "commandId", "idempotencyKey", "ip", "userAgent"]);
+
+function normalizeRequestMeta(requestMeta = {}) {
+  const source = requestMeta && typeof requestMeta === "object" ? requestMeta : {};
+  const normalized = {
+    ...source,
+    request: source.request || null
+  };
+  for (const field of TEXT_FIELDS) {
+    normalized[field] = normalizeText(source[field]);
+  }
+  return normalized;
+}
+
+export { normalizeRequestMeta };

package/server/http/capabilityHttpRuntime.js

@@ -9,7 +9,7 @@ import { registerRoutes } from "./lib/routeRegistration.js";
 import {
   registerApiErrorHandler,
   registerBodylessContentTypeNormalizer
-} from "../runtime/fastifyBootstrap.js";
+} from "./errorHandling.js";
 import { isAppError } from "../runtime/errors.js";
 
 function normalizeResolver({ id, resolve } = {}) {

package/server/http/capabilityHttpRuntime.test.js

@@ -159,3 +159,59 @@ test("direct HTTP action execution preserves request-scoped stream dependencies"
   assert.deepEqual(reply.payload, { writerId: "writer-1", aborted: false });
   await runtime.shutdown();
 });
+
+test("route transport reaches the error handler before the route handler runs, even without a kind", async () => {
+  const fastify = createFastifyStub();
+  const transport = {
+    contentType: "application/vnd.api+json",
+    request: {
+      query: (query) => ({ ...query, steps: [...(query.steps || []), "transport"] })
+    },
+    error(error, { statusCode, code }) {
+      return { errors: [{ status: String(statusCode), code, title: error.message }] };
+    }
+  };
+  const feature = defineFeature({
+    id: "feature.transport-proof",
+    domain: "transport-proof",
+    requires: { http: "runtime.http" },
+    setup({ http }) {
+      http.router.get("/transport-proof/", {
+        surface: "app",
+        visibility: "public",
+        transport
+      }, async (request, reply) => {
+        reply.code(200).send({ query: request.input.query });
+      });
+      return {};
+    },
+    actions: []
+  });
+  const runtime = createCapabilityRuntime({
+    inputs: { "runtime.fastify": fastify },
+    providers: [createActionProvider(), HttpProvider, feature]
+  });
+
+  await runtime.start();
+  const [route] = fastify.routes;
+  assert.equal(route.url, "/transport-proof");
+  assert.equal(typeof route.config.transport.error, "function");
+
+  const errorReply = createReply();
+  fastify.errorHandler(
+    { message: "querystring/limit must be integer", validation: [{ instancePath: "/limit", message: "must be integer" }] },
+    { routeOptions: { config: route.config } },
+    errorReply
+  );
+  assert.equal(errorReply.statusCode, 400);
+  assert.equal(errorReply.headers["content-type"], "application/vnd.api+json");
+  assert.deepEqual(errorReply.payload, {
+    errors: [{ status: "400", code: "validation_failed", title: "querystring/limit must be integer" }]
+  });
+
+  const reply = createReply();
+  await route.handler({ query: { steps: ["client"] }, routeOptions: { config: route.config } }, reply);
+  assert.deepEqual(reply.payload, { query: { steps: ["client", "transport"] } });
+  assert.equal(reply.headers["content-type"], "application/vnd.api+json");
+  await runtime.shutdown();
+});

package/server/http/errorHandling.js

@@ -0,0 +1,291 @@
+import { ActionRuntimeError } from "../actions/actionDefinitions.js";
+import { isRecord, normalizeTransactionOutcome } from "../../shared/support/normalize.js";
+import { JSON_API_CONTENT_TYPE } from "./lib/routeTransport.js";
+
+const JSON_API_CONTENT_TYPE_PARSER_MARKER = Symbol.for("jskit.fastify.jsonApiContentTypeParserRegistered");
+const BODYLESS_CONTENT_TYPE_NORMALIZER_MARKER = Symbol.for("jskit.fastify.bodylessContentTypeNormalizerRegistered");
+
+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;
+  }
+
+  fastify.addContentTypeParser(
+    JSON_API_CONTENT_TYPE,
+    { parseAs: "string" },
+    fastify.getDefaultJsonParser("ignore", "ignore")
+  );
+  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")) {
+    return false;
+  }
+
+  if (hasRequestBody(headers)) {
+    return false;
+  }
+
+  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 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 transport = request?.routeOptions?.config?.transport;
+  return isRecord(transport) ? transport : null;
+}
+
+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 applyErrorHeaders(reply, error) {
+  if (error?.headers && typeof error.headers === "object") {
+    for (const [name, value] of Object.entries(error.headers)) {
+      reply.header(name, value);
+    }
+  }
+}
+
+function registerApiErrorHandler(app, { isAppError } = {}) {
+  if (!app || typeof app.setErrorHandler !== "function") {
+    throw new TypeError("registerApiErrorHandler requires a Fastify instance.");
+  }
+  if (typeof isAppError !== "function") {
+    throw new TypeError("registerApiErrorHandler requires isAppError.");
+  }
+
+  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;
+    }
+
+    applyErrorHeaders(reply, error);
+
+    if (isAppError(error) || error instanceof ActionRuntimeError) {
+      if (error.status >= 500) {
+        app.log.error({ err: error }, "AppError 5xx");
+      }
+      const appErrorCode = normalizedErrorCode || "app_error";
+      const exposeDetails = shouldExposeAppErrorDetails(appErrorCode);
+      if (applyRouteTransportErrorResponse(reply, request, error, {
+        statusCode: error.status,
+        normalizedErrorCode: appErrorCode,
+        exposeDetails
+      })) {
+        return;
+      }
+
+      const payload = {
+        error: error.message,
+        code: appErrorCode,
+        ...outcomeFields
+      };
+      if (error.details && exposeDetails) {
+        payload.details = error.details;
+        if (error.details.fieldErrors) {
+          payload.fieldErrors = error.details.fieldErrors;
+        }
+      }
+
+      reply.code(error.status).send(payload);
+      return;
+    }
+
+    if (statusCode >= 500) {
+      app.log.error({ err: error }, "Unhandled error");
+    } else {
+      app.log.info({ err: error, statusCode }, "Request rejected");
+    }
+
+    const message = statusCode >= 500 ? "Internal server error." : String(error?.message || "Request failed.");
+    const fallbackErrorCode =
+      normalizedErrorCode || (statusCode >= 500 ? "internal_server_error" : "request_failed");
+    if (applyRouteTransportErrorResponse(reply, request, error, {
+      statusCode,
+      normalizedErrorCode: fallbackErrorCode,
+      message,
+      exposeDetails: statusCode < 500
+    })) {
+      return;
+    }
+    const payload = {
+      error: message,
+      code: fallbackErrorCode,
+      ...outcomeFields
+    };
+    if (isCsrfErrorCode) {
+      payload.details = {
+        code: normalizedErrorCode
+      };
+    }
+    reply.code(statusCode).send(payload);
+  });
+}
+
+export {
+  registerJsonApiContentTypeParser,
+  normalizeBodylessContentTypeHeader,
+  registerBodylessContentTypeNormalizer,
+  registerApiErrorHandler
+};