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) => {