문제 commandEffect.refusedBeforeWrite의 조립 검사는 code 문법, 멱등성 접두사, 중복, Envelope 여부만 본다. 계약 문서 6.1절은 BAD_PARAMETER(어느 층이든 IllegalArgumentException), MAPPING_FAILED(멱등성 응답 직렬화는 action 뒤), DB_* 8개, LOCK_ACQUISITION_TIMEOUT, fileserver code를 "쓰기 뒤 가능"으로 적는다. 이 code를 목록에 적어도 조립이 통과하고, 그 code로 온 400·409·422가 NOT_APPLIED가 된다. 쓰기 뒤에 난 실패를 사용자가 다시 저장하면 새 키나 키 없는 새 요청이 나가 같은 항목이 둘 생길 수 있다(리뷰 실험 X2: 네 code가 조립을 통과하고 모두 NOT_APPLIED). 고른 방법 6.1절의 "쓰기 뒤 가능" 플랫폼 code를 src/contracts/external-contract-runtime.ts에 PLATFORM_CODES_POSSIBLY_AFTER_WRITE로 두고, assertRefusedBeforeWrite가 그 code의 선언을 6.1절을 이유로 거절한다. 실행기의 fail-close(조립 없이 부른 경우)도 같은 목록을 무시한다. 목록을 adapters가 아니라 contracts에 둔 것은 조립 검사가 adapters를 import할 수 없기 때문이다(리뷰 문서의 최소 개선은 backend-envelope.ts에 두라고 했다). backend-contract-pin.test.ts가 계약 문서 6.1절 표의 "쓰기 뒤 가능" 행을 읽어 목록과 양방향으로 대조한다. 참조 도메인 code와 web-advanced patch code는 엔드포인트가 단계를 정하므로 테스트의 예외 목록에 적고 선언할 수 있게 둔다. 버린 대안 - 매뉴얼 문장만 둔다(현상 유지): 폼을 막는 code를 넣고 싶어지는 바로 그 자리에 통제가 없다. - 업무 code 접두사 규칙(<FEATURE>_로 시작하는 code만 허용): 다운스트림 code 이름을 강제해 과하다. 위험·한계 - 이미 이 code를 적은 다운스트림 계약은 부팅에서 조립이 실패한다. 의도한 실패다. - 6.1절 표에 플랫폼 code가 더해지면 목록도 같이 고쳐야 한다. 대조 테스트가 알린다. 백엔드가 code를 더한 것은 pin을 올릴 때 6.1절을 다시 읽어야 안다. - 업무 code를 잘못 선언하는 것은 여전히 막지 못한다(기능 작성자의 판단). - 대조 테스트는 계약 문서를 읽으므로, 문서를 복사하지 않는 기능 제거 드릴(FE-GATE-020의 optional-recipe·browser-file-storage·realtime)에서는 돌지 않는다. `scripts/lib/removal-fixture.ts`의 문서 테스트 목록에 `tests/unit/backend-contract-pin.test.ts`를 더했다. 저장소 자신의 test:unit은 그대로 돌린다. 검증 desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/external-contract-runtime.test.ts tests/unit/backend-envelope.test.ts tests/unit/backend-contract-pin.test.ts corepack pnpm test:optional-recipe-removal BREAKING CHANGE: refusedBeforeWrite에 계약 문서 6.1절이 "쓰기 뒤 가능"으로 둔 플랫폼 code(PLATFORM_CODES_POSSIBLY_AFTER_WRITE)를 적으면 composeContractContributions가 거절한다. 그 code를 목록에서 지운다. 그 code의 실패는 결과 불명으로 남는다. Refs: 1105/03-01
165 lines
6.6 KiB
TypeScript
165 lines
6.6 KiB
TypeScript
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");
|
|
});
|
|
|
|
// 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",
|
|
);
|
|
},
|
|
);
|
|
});
|