import { describe, expect, it } from "vitest"; import { envelopeFailureEffect, envelopeFailureReading, idempotencyRefusalReason, invitesKeyedResend, refusedBeforeWriteRows, } from "../../src/adapters/http/backend-envelope.ts"; import { createFailure, isRefusedOnEveryAttempt, REFUSALS_OF_EVERY_ATTEMPT, } from "../../src/contracts/errors.ts"; /** * 1103/10-02. The backend's refusal table, read status by status. The * integration test sends each table code with its own status; these rows pin * the edges it does not reach: a table code under another status, a 422 * outside the table, and the gateway statuses that keep the server-failure * kind. */ describe("backend Envelope failure table", () => { it.each([ [400, "VALIDATION_FAILED", undefined], [400, "IDEMPOTENCY_KEY_INVALID", "IDEMPOTENCY_KEY_RULE_MISMATCH"], [422, "IDEMPOTENT_REQUEST_MISMATCH", "IDEMPOTENT_REQUEST_MISMATCH"], ] as const)("reads %i %s as refused before the write", (status, code, reason) => { expect(envelopeFailureEffect(status, { code })).toBe("NOT_APPLIED"); expect(idempotencyRefusalReason(code, status)).toBe(reason); }); // The table names a status and a code together. The same code under // another status is not the refusal the backend documents. it.each([ [409, "VALIDATION_FAILED"], [422, "VALIDATION_FAILED"], [400, "IDEMPOTENT_REQUEST_MISMATCH"], [409, "IDEMPOTENT_REQUEST_MISMATCH"], [422, "IDEMPOTENCY_KEY_INVALID"], ] as const)("reads a table code under another status (%i %s) as maybe applied", (status, code) => { expect(envelopeFailureEffect(status, { code })).toBe("MAYBE_APPLIED"); expect(idempotencyRefusalReason(code, status)).toBeUndefined(); }); it.each([ [400, "BAD_PARAMETER"], [409, "IDEMPOTENT_IN_FLIGHT"], [409, "RESOURCE_CONFLICT"], // A 422 outside the table stays with the backend's verdict, never with a // package that reads every 422 as refused (fileserver writes first). [422, "INTEGRITY_MISMATCH"], ] as const)("keeps %i %s, outside the table, maybe applied", (status, code) => { expect(envelopeFailureEffect(status, { code })).toBe("MAYBE_APPLIED"); }); // 1105/03-02. http-contract.md §4: the edge rate limiter answers before the // controller runs. Status and code together, like the other rows. it.each(["RATE_LIMIT_UNAVAILABLE", "RATE_LIMIT_INCOMPATIBLE"])( "reads the edge's 503 %s as refused before the write", (code) => { expect(envelopeFailureEffect(503, { code })).toBe("NOT_APPLIED"); expect(invitesKeyedResend(503, { code })).toBe(false); expect(idempotencyRefusalReason(code, 503)).toBeUndefined(); expect(envelopeFailureReading(503, { code }).kind).toBe("SERVER_FAILURE"); expect(envelopeFailureEffect(500, { code })).toBeUndefined(); }, ); // 1103/03-04. http-contract.md §2 and §4: the command may have run. it.each([ [503, "IDEMPOTENCY_UNAVAILABLE", true], [503, "IDEMPOTENCY_COMPLETION_UNKNOWN", false], [500, "IDEMPOTENCY_RECOVERY_REQUIRED", false], [503, "REQUEST_TIMEOUT", false], ] as const)("reads %i %s as maybe applied", (status, code, resend) => { expect(envelopeFailureEffect(status, { code })).toBe("MAYBE_APPLIED"); expect(invitesKeyedResend(status, { code })).toBe(resend); }); // 1103/03-01. An operation names the codes its endpoint raises only before // it writes (`commandEffect.refusedBeforeWrite`). describe("with the operation's declared pre-write refusals", () => { const declared = ["WORKLOG_INVALID", "POSTER_ALREADY_EXISTS", "VALIDATION_FAILED"]; it.each([ [400, "WORKLOG_INVALID"], [409, "POSTER_ALREADY_EXISTS"], [422, "WORKLOG_INVALID"], ] as const)("reads a declared %i %s as not applied", (status, code) => { expect(envelopeFailureEffect(status, { code }, declared)).toBe("NOT_APPLIED"); }); it("keeps every code the operation did not declare maybe applied", () => { expect(envelopeFailureEffect(400, { code: "BAD_PARAMETER" }, declared)).toBe( "MAYBE_APPLIED", ); expect(envelopeFailureEffect(400, { code: "WORKLOG_INVALID" })).toBe("MAYBE_APPLIED"); }); it("never lets a declaration decide an idempotency answer or a table code", () => { const reckless = [ "IDEMPOTENT_IN_FLIGHT", "IDEMPOTENCY_UNAVAILABLE", "IDEMPOTENCY_COMPLETION_UNKNOWN", "VALIDATION_FAILED", ]; expect(envelopeFailureEffect(409, { code: "IDEMPOTENT_IN_FLIGHT" }, reckless)).toBe( "MAYBE_APPLIED", ); expect( envelopeFailureEffect(503, { code: "IDEMPOTENCY_UNAVAILABLE" }, reckless), ).toBe("MAYBE_APPLIED"); expect( envelopeFailureEffect(503, { code: "IDEMPOTENCY_COMPLETION_UNKNOWN" }, reckless), ).toBe("MAYBE_APPLIED"); // The table's status rule still holds for its own code. expect(envelopeFailureEffect(409, { code: "VALIDATION_FAILED" }, reckless)).toBe( "MAYBE_APPLIED", ); }); // 1105/03-01. The runtime's own fail-close for an executor called without // composition: a platform code 6.1 reads as possibly after the write // stays maybe applied, declared or not. it.each([ [400, "BAD_PARAMETER"], [400, "MAPPING_FAILED"], [409, "DB_UNIQUE_VIOLATION"], [409, "LOCK_ACQUISITION_TIMEOUT"], [422, "INTEGRITY_MISMATCH"], ] as const)("keeps a declared platform code %i %s maybe applied", (status, code) => { expect(envelopeFailureEffect(status, { code }, [code])).toBe("MAYBE_APPLIED"); }); it("does not reach statuses outside 400, 409 and 422", () => { expect(envelopeFailureEffect(500, { code: "WORKLOG_INVALID" }, declared)).toBeUndefined(); expect(envelopeFailureEffect(503, { code: "REQUEST_TIMEOUT" }, ["REQUEST_TIMEOUT"])).toBe( "MAYBE_APPLIED", ); }); }); it("leaves a status the table does not speak for to the package", () => { expect(envelopeFailureEffect(404, { code: "NOT_FOUND" })).toBeUndefined(); expect(envelopeFailureEffect(500, { code: "INTERNAL_ERROR" })).toBeUndefined(); // Status and code together: these codes under another 5xx are not the // backend's documented answers. expect( envelopeFailureEffect(500, { code: "IDEMPOTENCY_COMPLETION_UNKNOWN" }), ).toBeUndefined(); expect(envelopeFailureEffect(502, { code: "REQUEST_TIMEOUT" })).toBeUndefined(); }); // 1103/08-05. Only a field list makes a 422 an input error. it("reads a 422 without a field list as a client failure, not an input error", () => { expect( envelopeFailureReading(422, { code: "IDEMPOTENT_REQUEST_MISMATCH" }), ).toEqual({ kind: "UNKNOWN_CLIENT_FAILURE", code: "IDEMPOTENT_REQUEST_MISMATCH" }); expect(envelopeFailureReading(422, { code: "INTEGRITY_MISMATCH" }).kind).toBe( "UNKNOWN_CLIENT_FAILURE", ); expect( envelopeFailureReading(422, { code: "INVALID_INPUT", details: { issues: [{ path: "name", code: "REQUIRED" }] }, }), ).toEqual({ kind: "VALIDATION_REJECTED", code: "INVALID_INPUT", validationIssues: [{ path: "name", code: "REQUIRED" }], }); }); it.each([408, 425, 500, 502, 503, 504])( "reads a gateway %i as a server failure, not a client one", (status) => { expect(envelopeFailureReading(status, { code: "GATEWAY_REFUSED" }).kind).toBe( "SERVER_FAILURE", ); }, ); }); /** * 1106/03-01 (D10 supplement). The refusals every attempt of one request * gets (`REFUSALS_OF_EVERY_ATTEMPT`, which the mutation coordinator and the * form read) are rows of this table. Every other row is sorted to the other * side here, so a new row fails this test until someone decides it. */ describe("refusals every attempt of a request gets", () => { it("are rows of the refusal table, code and status", () => { for (const [code, status] of Object.entries(REFUSALS_OF_EVERY_ATTEMPT)) { expect(refusedBeforeWriteRows()).toContainEqual({ code, status }); } }); it("leave the table's other rows to keep a resent request unknown", () => { expect( refusedBeforeWriteRows() .filter(({ code }) => !Object.hasOwn(REFUSALS_OF_EVERY_ATTEMPT, code)) .map(({ code }) => code), ).toEqual([ "IDEMPOTENT_REQUEST_MISMATCH", "RATE_LIMIT_UNAVAILABLE", "RATE_LIMIT_INCOMPATIBLE", ]); }); // The failure the binding builds from each answer: kind from // envelopeFailureReading, effect from envelopeFailureEffect. it.each([ ["400 VALIDATION_FAILED with a field list", 400, "VALIDATION_FAILED", [{ field: "name", code: "NOT_BLANK" }], undefined, true], ["400 VALIDATION_FAILED whose body did not parse", 400, "VALIDATION_FAILED", { cause: "JsonParseException" }, undefined, true], ["400 IDEMPOTENCY_KEY_INVALID", 400, "IDEMPOTENCY_KEY_INVALID", undefined, undefined, true], ["422 IDEMPOTENT_REQUEST_MISMATCH", 422, "IDEMPOTENT_REQUEST_MISMATCH", undefined, undefined, false], ["503 RATE_LIMIT_UNAVAILABLE", 503, "RATE_LIMIT_UNAVAILABLE", undefined, undefined, false], ["a code the operation declared", 400, "WORKLOG_INVALID", undefined, ["WORKLOG_INVALID"], false], ] as const)("decides whether %s is refused on every attempt", (_label, status, code, details, declared, expected) => { const error = { code, ...(details === undefined ? {} : { details }) }; const effect = envelopeFailureEffect(status, error, declared); expect(effect).toBe("NOT_APPLIED"); const failure = createFailure( envelopeFailureReading(status, error).kind, "ENVELOPE_OPERATION", 0, { code, backendCode: code, httpStatus: status, effect: "NOT_APPLIED" }, ); expect(isRefusedOnEveryAttempt(failure)).toBe(expected); }); // 1112/01-06. The decision reads the paired backend's own code. A feature's // mapProblem may rename the code it shows (to a declared one, or to // VALIDATION_FAILED), and that rename must change neither answer. it.each([ ["a backend VALIDATION_FAILED a feature renamed", "WORKLOG_RENAMED", "VALIDATION_FAILED", true], ["a declared code a feature renamed to VALIDATION_FAILED", "VALIDATION_FAILED", "WORKLOG_INVALID", false], ["a code with no backend code (no Envelope)", "VALIDATION_FAILED", undefined, false], ] as const)("reads the backend's code for %s", (_label, code, backendCode, expected) => { const failure = createFailure("VALIDATION_REJECTED", "ENVELOPE_OPERATION", 0, { code, ...(backendCode === undefined ? {} : { backendCode }), httpStatus: 400, effect: "NOT_APPLIED", }); expect(isRefusedOnEveryAttempt(failure)).toBe(expected); }); });