import { describe, expect, it } from "vitest"; import { envelopeFailureEffect, envelopeFailureReading, idempotencyRefusalReason, invitesKeyedResend, } from "../../src/adapters/http/backend-envelope.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", ); }, ); });