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:
@@ -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 별도 |
|
||||
|
||||
|
||||
@@ -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) }
|
||||
|
||||
@@ -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) => {
|
||||
|
||||
@@ -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) => {
|
||||
|
||||
Reference in New Issue
Block a user