fix(http): 필드 목록이 없는 422를 입력 오류로 읽지 않는다

문제
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
This commit is contained in:
DongHyeonka
2026-11-04 20:27:53 +09:00
parent 61f70cb9b8
commit 613c1cfd0c
5 changed files with 94 additions and 13 deletions
@@ -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 별도 |
+16 -10
View File
@@ -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) }
+52
View File
@@ -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(
<FormHarness
submit={async (command) => {
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",
@@ -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) => {
+20
View File
@@ -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) => {