Files
clean-architecture-frontend…/tests/unit/backend-envelope.test.ts
DongHyeonka 42aa93d4c7
frontend-quality-gates / merge / static checks (pull_request) Successful in 2m56s
frontend-quality-gates / merge / tests (pull_request) Failing after 14m26s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 9m20s
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
fix(errors): 재전송이 결과 불명을 푸는지는 백엔드가 보낸 code로 정한다
isRefusedOnEveryAttempt는 failure.code를 읽는데, 그 값은 기능의 mapProblem이
정한다(1112/01-06). 그래서 둘이 틀린다.

- 기능이 백엔드 400 VALIDATION_FAILED를 자기 code로 바꾸면 모든 시도가 받는
  거절인데도 결과 불명이 풀리지 않는다.
- 기능이 시각·데이터베이스를 읽는 자기 거절(400)을 VALIDATION_FAILED로 바꾸면
  첫 요청이 반영됐을 수 있는데도 결과 불명이 풀린다.

AppFailure에 backendCode를 더한다(선택 칸, 추가만). HTTP 바인딩이 ENVELOPE_V1
operation의 PROBLEM에서 백엔드 error.code를 그대로 싣고, 판정은 이 칸과
status만 읽는다. Envelope가 없는 operation의 실패에는 싣지 않아 결과 불명이
풀리지 않는다(안전한 쪽). 버린 대안: 판정 표를 기능 code에 맞춰 늘리기(기능이
code를 바꿀 때마다 표가 어긋난다).

위험·한계: createFailure로 실패를 직접 만들어 재전송 거절을 흉내 내던 코드는
backendCode를 함께 줘야 결과 불명이 풀린다. 템플릿 안에서는 코디네이터 시험
넷뿐이고 고쳤다. 다운스트림 시험이 같은 방식이면 CHANGELOG [계약]에 적는다.
mapProblem이 예외를 던져 MAPPING_CONTRACT_VIOLATION이 된 실패에는 싣지 않는다.

Refs: 1112/01-06, 1106/03-01
2026-11-12 23:31:50 +09:00

251 lines
10 KiB
TypeScript

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);
});
});