From 613c1cfd0cdf4ede72eb4747c16d4495d74f7b34 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 20:27:53 +0900 Subject: [PATCH] =?UTF-8?q?fix(http):=20=ED=95=84=EB=93=9C=20=EB=AA=A9?= =?UTF-8?q?=EB=A1=9D=EC=9D=B4=20=EC=97=86=EB=8A=94=20422=EB=A5=BC=20?= =?UTF-8?q?=EC=9E=85=EB=A0=A5=20=EC=98=A4=EB=A5=98=EB=A1=9C=20=EC=9D=BD?= =?UTF-8?q?=EC=A7=80=20=EC=95=8A=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 Envelope 실패 해석이 422를 모두 필드 검증으로 본다 (isFieldValidationFailure). 짝 백엔드의 422 IDEMPOTENT_REQUEST_MISMATCH는 "같은 키를 다른 본문으로 보냈다"는 뜻이고 필드 목록이 없다. 그런데 kind가 VALIDATION_REJECTED가 되어 폼이 "입력값을 다시 확인해 주세요."를 띄운다. 사용자는 고칠 것이 없는 입력을 고치라는 말을 듣고, validation-error 상태는 지원 참조도 보이지 않는다. fileserver의 422(INTEGRITY_MISMATCH 등)도 같다. 고른 방법 422는 details에서 필드 목록(safeValidationIssues가 읽는 모양)이 나올 때만 필드 검증으로 본다. 필드 목록이 없는 422의 kind는 UNKNOWN_CLIENT_FAILURE다. 400 IDEMPOTENCY_KEY_INVALID와 같은 읽기다. 폼은 unavailable 상태와 지원 참조를 보인다. effect 판정(표)은 바꾸지 않았다. 422 MISMATCH는 그대로 NOT_APPLIED, 표 밖 422는 그대로 MAYBE_APPLIED다. 버린 대안 IDEMPOTENT_REQUEST_MISMATCH 한 code만 빼기: fileserver 422처럼 필드 목록 없는 다른 422가 계속 입력 오류로 보인다. 위험·한계 422로 필드 오류를 보내면서 details에 목록을 싣지 않는 백엔드는 이제 필드 오류 대신 실패 상태를 보인다. 짝 백엔드는 필드 검증을 400으로 보낸다. 검증 - RED: backend-envelope 단위 1건, envelope 통합 2건(422 MISMATCH· INTEGRITY_MISMATCH의 kind), form-foundation 1건(결과 unavailable, 문구 없음) 실패. - GREEN: tests/unit·integration·component·features·contract 250파일 3,114건 통과. details.issues가 있는 422는 그대로 필드 오류다 ("keeps the save off after a 422 the backend may have applied"). - check:types:app·test, eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-05 --- .../backend-api-and-server-state-contract.md | 2 +- src/adapters/http/backend-envelope.ts | 26 ++++++---- tests/component/form-foundation.test.tsx | 52 +++++++++++++++++++ .../http-execution-v3-envelope.test.ts | 7 ++- tests/unit/backend-envelope.test.ts | 20 +++++++ 5 files changed, 94 insertions(+), 13 deletions(-) diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index e3e644b6..f58e526a 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -184,7 +184,7 @@ Envelope의 모양과 키 존재 규칙은 짝 백엔드 템플릿 문서가 정 | `404` | authorization 정책상 공개 가능한 not-found | | `409` | domain revision 또는 semantic conflict. 멱등성 응답(409·422·400)은 6절 | | `412` | selected conditional write의 `If-Match` precondition 실패 | -| `422` | 짝 백엔드에서는 field validation이 아니다. 기본 배포는 `IDEMPOTENT_REQUEST_MISMATCH`(6절)만, fileserver 모듈은 쓰기 뒤에도 나오는 code를 422로 보낸다. 프론트는 `IDEMPOTENT_REQUEST_MISMATCH`만 적용 안 됨으로 보고, 폼 필드 오류는 `details.issues[]`가 있으면 읽는다. 적용 여부는 6.1절 | +| `422` | 짝 백엔드에서는 field validation이 아니다. 기본 배포는 `IDEMPOTENT_REQUEST_MISMATCH`(6절)만, fileserver 모듈은 쓰기 뒤에도 나오는 code를 422로 보낸다. 프론트는 `IDEMPOTENT_REQUEST_MISMATCH`만 적용 안 됨으로 보고, 폼 필드 오류는 `details.issues[]`가 있으면 읽는다. 필드 목록이 없는 422는 입력 오류가 아니라 `UNKNOWN_CLIENT_FAILURE`다(폼은 지원 참조가 있는 실패 상태를 보인다). 적용 여부는 6.1절 | | `429` | rate limit. 유효한 `Retry-After`와 operation 정책 제공 | | `500/502/503/504` | server/provider failure. command effect certainty 별도 | diff --git a/src/adapters/http/backend-envelope.ts b/src/adapters/http/backend-envelope.ts index 374ca0c1..f6ac34a0 100644 --- a/src/adapters/http/backend-envelope.ts +++ b/src/adapters/http/backend-envelope.ts @@ -133,20 +133,24 @@ export function idempotencyRefusalReason( } /** - * 백엔드 1101/02-01 후속. A failure the form shows on its fields: a 422, or - * the paired backend's 400 VALIDATION_FAILED whose details is the field list - * (§4). This decides the kind and the issues only, not whether it applied. + * 백엔드 1101/02-01 후속. A failure the form shows on its fields: the paired + * backend's 400 VALIDATION_FAILED whose details is the field list (§4), or a + * 422 that carries a field list. This decides the kind and the issues only, + * not whether it applied. + * + * 1103/08-05. A 422 without one is not an input error: the paired backend's + * 422 IDEMPOTENT_REQUEST_MISMATCH (the same key went out with another body) + * and fileserver's 422s leave the user nothing to correct. */ export function isFieldValidationFailure( status: number, error: EnvelopeError, ): boolean { - return ( - status === 422 || - (status === 400 && - error.code === "VALIDATION_FAILED" && - Array.isArray(error.details)) - ); + return status === 422 + ? safeValidationIssues(error.details).length > 0 + : status === 400 && + error.code === "VALIDATION_FAILED" && + Array.isArray(error.details); } /** @@ -209,7 +213,9 @@ export function envelopeFailureReading( return Object.freeze({ kind: fieldValidation ? "VALIDATION_REJECTED" - : gatewayFailureOr(status, kindForStatus(status)), + : status === 422 + ? "UNKNOWN_CLIENT_FAILURE" + : gatewayFailureOr(status, kindForStatus(status)), code: error.code, ...(fieldValidation ? { validationIssues: safeValidationIssues(error.details) } diff --git a/tests/component/form-foundation.test.tsx b/tests/component/form-foundation.test.tsx index dc0e893e..16357041 100644 --- a/tests/component/form-foundation.test.tsx +++ b/tests/component/form-foundation.test.tsx @@ -317,6 +317,58 @@ describe("local form facade", () => { expect(document.body).not.toHaveTextContent("raw backend copy"); }); + // 1103/08-05. The same key went out with another body. The user has + // nothing to correct, so the form shows a status with a support reference. + it("shows a paired backend 422 IDEMPOTENT_REQUEST_MISMATCH as a status, not an input error", async () => { + const user = userEvent.setup(); + const http = formBinding(async () => + Response.json( + { + success: false, + error: { + code: "IDEMPOTENT_REQUEST_MISMATCH", + category: "VALIDATION", + message: "요청 값이 올바르지 않습니다.", + retryable: false, + }, + meta: { requestId: "request-1", traceId: "trace-1" }, + }, + { status: 422, headers: { "x-correlation-id": "corr-422" } }, + ), + ); + render( + { + const result = await http.execute( + "FORM_CREATE_ENTITY", + { name: command.name }, + { + intent: Object.freeze({ + intentId: "intent-1", + operationId: "FORM_CREATE_ENTITY", + canonicalInputIdentity: "{}", + idempotencyKey: "key-1", + createdAtMonotonicMs: 0, + }), + }, + ); + if (result.ok) throw new Error("expected a mismatch refusal"); + return result; + }} + />, + ); + await user.type(screen.getByRole("textbox", { name: /Name/ }), "Valid"); + await user.click(screen.getByRole("button", { name: "Submit" })); + + expect(await screen.findByTestId("result")).toHaveTextContent("unavailable"); + expect(document.body).not.toHaveTextContent("입력값을 다시 확인해 주세요."); + expect(screen.getByRole("textbox", { name: /Name/ })).not.toHaveAttribute( + "aria-invalid", + ); + expect(screen.getByRole("alert")).toHaveTextContent("지원 참조: corr-422"); + expect(screen.getByRole("button", { name: "Submit" })).toBeEnabled(); + }); + it.each([ [ "AUTH_REQUIRED", diff --git a/tests/integration/http-execution-v3-envelope.test.ts b/tests/integration/http-execution-v3-envelope.test.ts index ade862e8..2626feea 100644 --- a/tests/integration/http-execution-v3-envelope.test.ts +++ b/tests/integration/http-execution-v3-envelope.test.ts @@ -501,7 +501,9 @@ describe("V3 Envelope verdicts follow the backend's refusal table", () => { effect: "MAYBE_APPLIED", retryAfterMs: 2_000, }, - "422 IDEMPOTENT_REQUEST_MISMATCH": { kind: "VALIDATION_REJECTED", effect: "NOT_APPLIED" }, + // 08-05. The same key went out with another body: nothing for the user + // to correct in the input. + "422 IDEMPOTENT_REQUEST_MISMATCH": { kind: "UNKNOWN_CLIENT_FAILURE", effect: "NOT_APPLIED" }, "400 IDEMPOTENCY_KEY_INVALID": { kind: "UNKNOWN_CLIENT_FAILURE", effect: "NOT_APPLIED" }, "503 IDEMPOTENCY_UNAVAILABLE": { kind: "SERVER_FAILURE", effect: "MAYBE_APPLIED" }, "400 VALIDATION_FAILED with the field list": { @@ -523,7 +525,8 @@ describe("V3 Envelope verdicts follow the backend's refusal table", () => { }, "400 BAD_PARAMETER": { kind: "UNKNOWN_CLIENT_FAILURE", effect: "MAYBE_APPLIED" }, "409 domain conflict": { kind: "CONFLICT", effect: "MAYBE_APPLIED" }, - "422 INTEGRITY_MISMATCH": { kind: "VALIDATION_REJECTED", effect: "MAYBE_APPLIED" }, + // 08-05. A 422 without a field list is no input error either. + "422 INTEGRITY_MISMATCH": { kind: "UNKNOWN_CLIENT_FAILURE", effect: "MAYBE_APPLIED" }, }; it.each(cases)("%s", async (label, response) => { diff --git a/tests/unit/backend-envelope.test.ts b/tests/unit/backend-envelope.test.ts index fa09e59a..baf3d8a9 100644 --- a/tests/unit/backend-envelope.test.ts +++ b/tests/unit/backend-envelope.test.ts @@ -51,6 +51,26 @@ describe("backend Envelope failure table", () => { expect(envelopeFailureEffect(404, { code: "NOT_FOUND" })).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) => {