@jskit-ai/http-runtime 0.1.182 → 0.1.184

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/http-runtime",
-  "version": "0.1.182",
+  "version": "0.1.184",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -78,6 +78,6 @@
     }
   },
   "peerDependencies": {
-    "@jskit-ai/kernel": "0.1.184"
+    "@jskit-ai/kernel": "0.1.186"
   }
 }

package/src/shared/clientRuntime/errors.js

@@ -1,3 +1,4 @@
+import { normalizeTransactionOutcome } from "@jskit-ai/kernel/shared/support/normalize";
 import { isRecord, resolveFieldErrors } from "../support/fieldErrors.js";
 import { createJsonApiClientErrorPayload } from "./jsonApiResourceTransport.js";
 
@@ -20,6 +21,10 @@ function createHttpError(response, data = {}) {
   const normalizedFieldErrors = resolveFieldErrors(payload);
   error.status = Number(response?.status || 0);
   error.code = String(payload.code || "").trim() || null;
+  const transactionOutcome = normalizeTransactionOutcome(payload.transactionOutcome);
+  if (transactionOutcome) {
+    error.transactionOutcome = transactionOutcome;
+  }
   error.fieldErrors = Object.keys(normalizedFieldErrors).length > 0 ? normalizedFieldErrors : null;
   if (isRecord(payload.details)) {
     error.details = payload.details;

package/src/shared/clientRuntime/jsonApiResourceTransport.js

@@ -1,4 +1,4 @@
-import { normalizeArray, normalizeObject, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeArray, normalizeObject, normalizeText, normalizeTransactionOutcome } from "@jskit-ai/kernel/shared/support/normalize";
 import {
   JSON_API_CONTENT_TYPE,
   createJsonApiDocument,
@@ -331,12 +331,14 @@ function createJsonApiClientErrorPayload(payload = {}) {
 
   const firstError = normalizeArray(document.errors)[0] || {};
   const fieldErrors = decodeJsonApiErrorFieldErrors(payload);
+  const transactionOutcome = normalizeTransactionOutcome(firstError.meta?.transactionOutcome);
 
   return {
     error: normalizeText(firstError.detail || firstError.title, {
       fallback: "Request failed."
     }),
     code: normalizeText(firstError.code) || null,
+    ...(transactionOutcome ? { transactionOutcome } : {}),
     ...(Object.keys(fieldErrors).length > 0
       ? {
           fieldErrors,

package/src/shared/clientRuntime/retry.js

@@ -1,3 +1,6 @@
+import { normalizeTransactionOutcome } from "@jskit-ai/kernel/shared/support/normalize";
+import { createJsonApiClientErrorPayload } from "./jsonApiResourceTransport.js";
+
 const DEFAULT_RETRYABLE_CSRF_ERROR_CODES = Object.freeze(["FST_CSRF_INVALID_TOKEN", "FST_CSRF_MISSING_SECRET"]);
 
 function toUpperStringSet(values, fallback = []) {
@@ -28,7 +31,13 @@ function shouldRetryForCsrfFailure({
     return false;
   }
 
-  const code = String(data?.details?.code || "")
+  const payload = createJsonApiClientErrorPayload(data) || data;
+  const transactionOutcome = normalizeTransactionOutcome(payload?.transactionOutcome);
+  if (["pending", "committed", "unknown"].includes(transactionOutcome)) {
+    return false;
+  }
+
+  const code = String(payload?.details?.code || payload?.code || "")
     .trim()
     .toUpperCase();
   const retryableCodes = toUpperStringSet(retryableErrorCodes, DEFAULT_RETRYABLE_CSRF_ERROR_CODES);

package/src/shared/validators/errorResponses.js

@@ -1,4 +1,5 @@
 import { createSchema } from "json-rest-schema";
+import { TRANSACTION_OUTCOMES } from "@jskit-ai/kernel/shared/support/normalize";
 import { deepFreeze } from "@jskit-ai/kernel/shared/support/deepFreeze";
 import { createEmbeddableTransportSchemaDocument } from "./transportSchemaEmbedding.js";
 
@@ -28,6 +29,7 @@ const apiErrorOutputValidator = deepFreeze({
   schema: createSchema({
     error: { type: "string", required: true, minLength: 1 },
     code: { type: "string", required: false, minLength: 1 },
+    transactionOutcome: { type: "string", required: false, enum: TRANSACTION_OUTCOMES },
     details: {
       type: "object",
       required: false,
@@ -46,6 +48,7 @@ const apiValidationErrorOutputValidator = deepFreeze({
   schema: createSchema({
     error: { type: "string", required: true, minLength: 1 },
     code: { type: "string", required: false, minLength: 1 },
+    transactionOutcome: { type: "string", required: false, enum: TRANSACTION_OUTCOMES },
     fieldErrors: {
       ...fieldErrorsFieldDefinition,
       required: true
@@ -77,6 +80,7 @@ const fastifyDefaultErrorTransportSchema = {
     error: { type: "string", minLength: 1 },
     message: { type: "string", minLength: 1 },
     code: { type: "string", minLength: 1 },
+    transactionOutcome: { type: "string", enum: TRANSACTION_OUTCOMES },
     details: {},
     fieldErrors: {
       type: "object",

package/src/shared/validators/jsonApiRouteTransport.js

@@ -864,9 +864,11 @@ function createJsonApiResourceRouteTransport({
     },
     error(error, {
       statusCode = 500,
-      code = ""
+      code = "",
+      message = error?.message,
+      exposeDetails = true
     } = {}) {
-      const fieldErrors = isRecord(error?.fieldErrors)
+      const fieldErrors = !exposeDetails ? {} : isRecord(error?.fieldErrors)
         ? error.fieldErrors
         : isRecord(error?.details?.fieldErrors)
           ? error.details.fieldErrors
@@ -875,9 +877,10 @@ function createJsonApiResourceRouteTransport({
       return createJsonApiErrorDocumentFromFailure({
         statusCode,
         code,
-        message: error?.message,
+        message,
+        transactionOutcome: error?.transactionOutcome,
         fieldErrors,
-        validationIssues: Array.isArray(error?.validation) ? error.validation : [],
+        validationIssues: exposeDetails && Array.isArray(error?.validation) ? error.validation : [],
         validationContext: String(error?.validationContext || "").trim(),
         pointerPrefix
       });

package/src/shared/validators/jsonApiTransport.js

@@ -1,4 +1,4 @@
-import { normalizeArray, normalizeObject, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeArray, normalizeObject, normalizeText, normalizeTransactionOutcome } from "@jskit-ai/kernel/shared/support/normalize";
 import { simplifyJsonApiResourceWithRelationshipIds } from "../support/jsonApiSimplify.js";
 
 const JSON_API_CONTENT_TYPE = "application/vnd.api+json";
@@ -388,11 +388,14 @@ function createJsonApiErrorDocumentFromFailure({
   statusCode = 500,
   code = "",
   message = "",
+  transactionOutcome,
   fieldErrors = {},
   validationIssues = [],
   validationContext = "",
   pointerPrefix = "/data/attributes"
 } = {}) {
+  const outcome = normalizeTransactionOutcome(transactionOutcome);
+  const meta = outcome ? { transactionOutcome: outcome } : undefined;
   const normalizedStatus = String(Number(statusCode) || 500);
   const normalizedCode = String(code || "").trim();
   const normalizedMessage = String(message || "").trim() || "Request failed.";
@@ -404,6 +407,7 @@ function createJsonApiErrorDocumentFromFailure({
       errors: issues.map((issue) =>
         createJsonApiErrorObject({
           status: normalizedStatus,
+          meta,
           code: normalizedCode,
           title: normalizedMessage,
           detail: String(issue?.message || "Invalid value.").trim() || "Invalid value.",
@@ -419,6 +423,7 @@ function createJsonApiErrorDocumentFromFailure({
       errors: fieldEntries.map(([field, detail]) =>
         createJsonApiErrorObject({
           status: normalizedStatus,
+          meta,
           code: normalizedCode,
           title: normalizedMessage,
           detail: String(detail || "Invalid value.").trim() || "Invalid value.",
@@ -434,6 +439,7 @@ function createJsonApiErrorDocumentFromFailure({
     errors: [
       createJsonApiErrorObject({
         status: normalizedStatus,
+        meta,
         code: normalizedCode,
         title: normalizedMessage
       })

package/test/client.test.js

@@ -21,6 +21,82 @@ function mockResponse({ status = 200, data = {}, contentType = "application/json
   };
 }
 
+test("request retains standard and JSON:API write outcomes without retrying", async () => {
+  for (const jsonapi of [false, true]) {
+    for (const outcome of ["committed", "rolledBack", "unknown", "invalid"]) {
+      let requests = 0;
+      const data = jsonapi
+        ? { errors: [{ status: "500", title: "Internal server error.", meta: { transactionOutcome: outcome } }] }
+        : { error: "Internal server error.", transactionOutcome: outcome };
+      const client = createHttpClient({
+        fetchImpl: async () => {
+          requests += 1;
+          return mockResponse({ status: 500, data, contentType: jsonapi ? "application/vnd.api+json" : "application/json" });
+        }
+      });
+      await assert.rejects(
+        () => client.request("/api/books/1", { method: "PATCH", body: { title: "Dune" }, csrf: false }),
+        (error) => {
+          assert.equal(error.status, 500);
+          assert.equal(error.transactionOutcome, outcome === "invalid" ? undefined : outcome);
+          return true;
+        }
+      );
+      assert.equal(requests, 1);
+    }
+  }
+});
+
+test("CSRF recovery replays writes only when their transaction outcome permits it", async (t) => {
+  for (const requestMethod of ["request", "requestStream"]) {
+    for (const jsonapi of [false, true]) {
+      for (const outcome of ["none", "rolledBack", "pending", "committed", "unknown"]) {
+        await t.test(`${requestMethod} ${jsonapi ? "JSON:API" : "plain"} ${outcome}`, async () => {
+          const calls = [];
+          let writes = 0;
+          const client = createHttpClient({
+            fetchImpl: async (url) => {
+              calls.push(url);
+              if (url === "/api/session") {
+                return mockResponse({ data: { csrfToken: "csrf-token" } });
+              }
+              writes += 1;
+              if (writes > 1) {
+                return mockResponse({ data: { ok: true } });
+              }
+              return mockResponse({
+                status: 403,
+                contentType: jsonapi ? "application/vnd.api+json" : "application/json",
+                data: jsonapi
+                  ? { errors: [{ status: "403", code: "FST_CSRF_INVALID_TOKEN", title: "Invalid CSRF token.", meta: { transactionOutcome: outcome } }] }
+                  : { error: "Invalid CSRF token.", details: { code: "FST_CSRF_INVALID_TOKEN" }, transactionOutcome: outcome }
+              });
+            }
+          });
+          const request = () => client[requestMethod]("/api/books", {
+            method: "POST",
+            body: { title: "Dune" }
+          });
+
+          if (["none", "rolledBack"].includes(outcome)) {
+            await request();
+            assert.equal(writes, 2);
+            assert.deepEqual(calls, ["/api/session", "/api/books", "/api/session", "/api/books"]);
+          } else {
+            await assert.rejects(request, (error) => {
+              assert.equal(error.status, 403);
+              assert.equal(error.transactionOutcome, outcome);
+              return true;
+            });
+            assert.equal(writes, 1);
+            assert.deepEqual(calls, ["/api/session", "/api/books"]);
+          }
+        });
+      }
+    }
+  }
+});
+
 test("request serializes json body and injects csrf token for unsafe methods", async () => {
   const calls = [];
   const fetchImpl = async (url, options) => {

package/test/errorResponses.test.js

@@ -118,3 +118,11 @@ test("error response validators export transport schemas from the same contracts
     true
   );
 });
+
+test("standard error schemas preserve optional transaction outcomes during serialization", () => {
+  const outcomes = ["none", "pending", "committed", "rolledBack", "unknown"];
+  for (const schema of [apiErrorTransportSchema, apiValidationErrorTransportSchema, fastifyDefaultErrorTransportSchema]) {
+    assert.deepEqual(schema.properties.transactionOutcome.enum, outcomes);
+    assert.equal(schema.required.includes("transactionOutcome"), false);
+  }
+});

package/test/jsonApiRouteTransport.test.js

@@ -1,8 +1,22 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import Fastify from "fastify";
+import knexLib from "knex";
+import {
+  RestApiFieldsetError,
+  RestApiIncludeError,
+  RestApiPayloadError,
+  RestApiPreconditionFailedError,
+  RestApiResourceError,
+  RestApiTemporalDataError,
+  RestApiValidationError,
+  RestApiVersionConflictError,
+  RestApiWriteError
+} from "json-rest-api";
 
 import {
   JSON_API_CONTENT_TYPE,
+  apiErrorTransportSchema,
   encodeJsonApiResourceQueryObject,
   createJsonApiResourceQueryTransportSchema,
   createJsonApiResourceRequestBodyTransportSchema,
@@ -15,6 +29,10 @@ import {
 } from "../src/shared/index.js";
 import { createSchema } from "../../kernel/shared/validators/index.js";
 import { resolveRouteValidatorOptions } from "../../kernel/server/http/lib/routeValidator.js";
+import { registerApiErrorHandler } from "../../kernel/server/runtime/fastifyBootstrap.js";
+import { AppError, isAppError } from "../../kernel/server/runtime/errors.js";
+import { createHttpError } from "../src/shared/clientRuntime/errors.js";
+import { createJsonRestApiHost } from "../../json-rest-api-core/src/server/jsonRestApiHost.js";
 
 const CONTACT_BODY_SCHEMA = Object.freeze({
   schema: createSchema({
@@ -197,6 +215,189 @@ test("createJsonApiResourceRouteTransport unwraps request payloads and wraps res
   assert.equal(errorPayload.errors[0].source.pointer, "/data/attributes/name");
 });
 
+test("real HTTP responses classify typed JSON REST read and write errors", async (t) => {
+  const app = Fastify();
+  t.after(() => app.close());
+  registerApiErrorHandler(app, { isAppError });
+  const transport = createJsonApiResourceRouteTransport({ type: "books" });
+  const cases = [
+    ["validation", () => new RestApiValidationError("Title is required."), 422],
+    ["missing", () => new RestApiResourceError("Book not found.", { subtype: "not_found" }), 404],
+    ["forbidden", () => new RestApiResourceError("Book is forbidden.", { subtype: "forbidden" }), 403],
+    ["conflict", () => new RestApiResourceError("Book conflicts.", { subtype: "conflict" }), 409],
+    ["resource", () => new RestApiResourceError("Invalid resource."), 400],
+    ["version", () => new RestApiVersionConflictError({ resourceType: "books", resourceId: "1" }), 409],
+    ["precondition", () => new RestApiPreconditionFailedError({ resourceType: "books", resourceId: "1" }), 412],
+    ["fieldset", () => new RestApiFieldsetError({ resourceType: "books", field: "missing" }), 400],
+    ["include", () => new RestApiIncludeError({ resourceType: "books", path: "missing" }), 400],
+    ["payload", () => new RestApiPayloadError("Invalid document."), 400],
+    ["large-payload", () => new RestApiPayloadError("Document too large.", { statusCode: 413 }), 413],
+    ["temporal", () => new RestApiTemporalDataError({ resourceType: "private_table", field: "private_column", fieldType: "date" }), 500],
+    ["custom-status", () => Object.assign(new Error("Custom error."), { status: 418 }), 418],
+    ["server-status", () => Object.assign(new Error("private server failure"), { statusCode: 503 }), 503],
+    ["invalid-status", () => Object.assign(new Error("private invalid status"), { statusCode: 200 }), 500]
+  ];
+
+  for (const jsonapi of [false, true]) {
+    for (const wrapped of [false, true]) {
+      const prefix = `/${jsonapi ? "jsonapi" : "plain"}/${wrapped ? "write" : "read"}`;
+      app.get(`${prefix}/:kind`, {
+        config: jsonapi ? { transport: { runtime: transport } } : {},
+        ...(jsonapi ? {} : { schema: { response: { "4xx": apiErrorTransportSchema, "5xx": apiErrorTransportSchema } } })
+      }, async (request) => {
+        const [, createError] = cases.find(([name]) => name === request.params.kind);
+        const cause = createError();
+        if (wrapped) {
+          throw new RestApiWriteError(cause.message, { cause, transactionOutcome: "rolledBack" });
+        }
+        throw cause;
+      });
+    }
+  }
+
+  for (const jsonapi of [false, true]) {
+    for (const wrapped of [false, true]) {
+      for (const [name, createError, expectedStatus] of cases) {
+        const url = `/${jsonapi ? "jsonapi" : "plain"}/${wrapped ? "write" : "read"}/${name}`;
+        const response = await app.inject({ method: "GET", url });
+        assert.equal(response.statusCode, expectedStatus, url);
+        const payload = response.json();
+        const clientError = createHttpError({ status: response.statusCode }, payload);
+        assert.equal(clientError.status, expectedStatus, url);
+        assert.equal(clientError.transactionOutcome, wrapped ? "rolledBack" : undefined, url);
+        assert.equal(clientError.message, expectedStatus >= 500 ? "Internal server error." : createError().message, url);
+        assert.equal(clientError.cause, undefined);
+        if (jsonapi) {
+          assert.equal(payload.errors[0].status, String(expectedStatus));
+          assert.match(response.headers["content-type"], /^application\/vnd\.api\+json/u);
+        }
+        if (expectedStatus >= 500) {
+          assert.doesNotMatch(response.body, /private/u);
+        }
+      }
+    }
+  }
+});
+
+test("real resource validation, permission hooks and completion failures retain HTTP semantics", async (t) => {
+  const app = Fastify();
+  t.after(() => app.close());
+  const knex = knexLib({ client: "better-sqlite3", connection: { filename: ":memory:" }, useNullAsDefault: true });
+  t.after(() => knex.destroy());
+  await knex.schema.createTable("books", (table) => {
+    table.increments("id");
+    table.string("title").notNullable();
+  });
+  const api = await createJsonRestApiHost({ knex, logger: { error() {} } });
+  await api.addResource("books", { schema: { title: { type: "string", required: true } } });
+  await api.customize({ hooks: {
+    checkPermissions({ context }) {
+      if ((context.originalContext ?? context).deny) {
+        throw new RestApiResourceError("Book access denied.", { subtype: "forbidden" });
+      }
+    },
+    afterCommit({ context }) {
+      if (context.failAfterCommit) {
+        throw new Error("private notification failure");
+      }
+    }
+  } });
+  registerApiErrorHandler(app, { isAppError });
+  const transport = createJsonApiResourceRouteTransport({ type: "books" });
+  for (const jsonapi of [false, true]) {
+    const prefix = `/${jsonapi ? "jsonapi" : "plain"}`;
+    const options = { config: jsonapi ? { transport: { runtime: transport } } : {} };
+    app.get(`${prefix}/denied`, options, async () => api.resources.books.query({}, { deny: true }));
+    app.post(`${prefix}/invalid`, options, async (request) => api.resources.books.post({ data: request.body }));
+    app.post(`${prefix}/committed`, options, async (request) => api.resources.books.post({ data: request.body }, { failAfterCommit: true }));
+  }
+
+  for (const jsonapi of [false, true]) {
+    const prefix = `/${jsonapi ? "jsonapi" : "plain"}`;
+    for (const [path, method, payload, status, code, outcome] of [
+      ["denied", "GET", undefined, 403, "REST_API_RESOURCE", undefined],
+      ["invalid", "POST", {}, 422, "REST_API_VALIDATION", "rolledBack"],
+      ["committed", "POST", { title: "Stored book" }, 500, "REST_API_WRITE", "committed"]
+    ]) {
+      const response = await app.inject({ method, url: `${prefix}/${path}`, ...(payload ? { payload } : {}) });
+      assert.equal(response.statusCode, status, response.body);
+      const clientError = createHttpError({ status: response.statusCode }, response.json());
+      assert.equal(clientError.status, status);
+      assert.equal(clientError.code, code);
+      assert.equal(clientError.transactionOutcome, outcome);
+      if (status === 500) {
+        assert.equal(clientError.message, "Internal server error.");
+        assert.doesNotMatch(response.body, /private/u);
+      }
+    }
+  }
+  assert.deepEqual(await knex("books").pluck("title"), ["Stored book", "Stored book"]);
+});
+
+test("error handler, JSON:API transport and client preserve outcomes without disclosing internal failures", () => {
+  const transport = createJsonApiResourceRouteTransport({ type: "books" });
+  const app = { log: { error() {} }, setErrorHandler(handler) { this.errorHandler = handler; } };
+  registerApiErrorHandler(app, { isAppError });
+
+  for (const transactionOutcome of ["none", "pending", "committed", "rolledBack", "unknown", "invalid", undefined]) {
+    const failure = Object.assign(new Error("Private SQL statement"), {
+      transactionOutcome,
+      code: "REST_API_WRITE",
+      fieldErrors: { secret: "Private SQL value" },
+      cause: { secret: "Private cause" },
+      cleanupErrors: [{ message: "Private cleanup" }]
+    });
+    for (const jsonapi of [false, true]) {
+      const reply = {
+        statusCode: 200,
+        headers: {},
+        code(value) { this.statusCode = value; return this; },
+        header(name, value) { this.headers[name] = value; return this; },
+        send(payload) { this.payload = payload; return this; }
+      };
+      app.errorHandler(failure, jsonapi ? { routeTransport: transport } : {}, reply);
+      assert.equal(reply.statusCode, 500);
+      const clientError = createHttpError({ status: reply.statusCode }, reply.payload);
+      assert.equal(clientError.message, "Internal server error.");
+      assert.equal(clientError.code, "REST_API_WRITE");
+      assert.equal(clientError.transactionOutcome, transactionOutcome === "invalid" ? undefined : transactionOutcome);
+      assert.equal(clientError.cause, undefined);
+      assert.equal(clientError.fieldErrors, null);
+      assert.equal(JSON.stringify(reply.payload).includes("Private"), false);
+      if (jsonapi) {
+        assert.equal(reply.headers["Content-Type"], JSON_API_CONTENT_TYPE);
+        assert.equal(reply.payload.errors[0].meta?.transactionOutcome, clientError.transactionOutcome);
+      }
+    }
+  }
+});
+
+test("JSON:API field errors retain outcomes and permission details remain private", () => {
+  const transport = createJsonApiResourceRouteTransport({ type: "books" });
+  const payload = transport.error({
+    message: "Validation failed.",
+    transactionOutcome: "rolledBack",
+    fieldErrors: { title: "Required", author: "Missing" }
+  }, { statusCode: 422 });
+  assert.equal(payload.errors.length, 2);
+  assert.ok(payload.errors.every((error) => error.meta.transactionOutcome === "rolledBack"));
+
+  const app = { log: { error() {} }, setErrorHandler(handler) { this.errorHandler = handler; } };
+  registerApiErrorHandler(app, { isAppError });
+  const reply = {
+    code() { return this; },
+    header() { return this; },
+    send(value) { this.payload = value; return this; }
+  };
+  app.errorHandler(new AppError(403, "Forbidden.", {
+    code: "ACTION_PERMISSION_DENIED",
+    details: { fieldErrors: { secret: "Required private permission" } }
+  }), { routeTransport: transport }, reply);
+  assert.deepEqual(reply.payload, {
+    errors: [{ status: "403", code: "ACTION_PERMISSION_DENIED", title: "Forbidden." }]
+  });
+});
+
 test("createJsonApiResourceQueryTransportSchema and route transport map list query params to JSON:API", () => {
   const schema = createJsonApiResourceQueryTransportSchema({
     query: CONTACT_LIST_QUERY_SCHEMA,