Files
clean-architecture-frontend…/tests/integration/http-client.test.ts
T
DongHyeonka 02e35d2b38 fix(http): 짝 백엔드의 400 VALIDATION_FAILED를 폼 필드 오류로 읽는다 (백엔드 1101/02-01)
문제
짝 백엔드는 필드 검증 실패를 400 VALIDATION_FAILED로 보낸다. details는
위반 하나마다 {field, code, message}인 배열이다(백엔드 docs/web/http-
contract.md 4절, ClientSafeValidationDetails). field는 점으로 이은 속성
이름이고 인덱스는 뺀다. 클래스 수준 오류는 "request"다.
프론트 V2 클라이언트(client.ts)는 422만 필드 검증으로 읽는다. 400은
UNKNOWN_CLIENT_FAILURE이고 validationIssues가 없어서, 폼(use-app-form.ts)이
필드 오류 대신 "unavailable" 상태를 보인다. safeValidationIssues도
{issues}·{fieldErrors} 객체만 읽어서 배열 details를 버린다.

고른 방법
- V2: 400 + code VALIDATION_FAILED + details가 배열이면 422와 같은 것으로
  본다. kind VALIDATION_REJECTED와 validationIssues를 422 경로와 같은 식으로
  만든다. 폼은 기존 mapValidationFailureToFields와 allowedServerFields를
  그대로 쓴다. 새 폼 경로는 없다.
- safeValidationIssues: details가 배열이면 각 항목의 field를 path로 읽는다.
  message는 버린다. 후보 수는 기존 상한(MAX_VALIDATION_ISSUE_CANDIDATES)으로
  자른 뒤 projectValidationIssues에 넘긴다.
- 그 밖의 400은 그대로 둔다: details가 {cause}인 VALIDATION_FAILED(본문
  파싱 실패), details 없는 VALIDATION_FAILED, BAD_PARAMETER,
  IDEMPOTENCY_KEY_INVALID(NOT_APPLIED 판정 유지).

버린 대안
- 400 VALIDATION_FAILED 전체를 VALIDATION_REJECTED로: 파싱 실패 같은
  클라이언트 버그가 "입력값을 다시 확인해 주세요."로 보인다. 필드 목록이
  있을 때만 바꾼다.
- 공용 projectValidationIssues가 field를 path 별칭으로 받게: zod 이슈와
  V3 경로까지 같은 규칙을 갖게 된다. 백엔드 wire 모양은 V2 전용
  safeValidationIssues에서만 읽는다.
- V3 참조 기능 mapProblem도 바꾸기: 참조 fixture는 problem+json
  (type·title·status·issues)이라 짝 백엔드 Envelope가 problem 검증을 통과하지
  않는다. 짝 백엔드 wire를 읽는 곳은 V2다.

위험·한계
- 백엔드 code(NOT_BLANK, SIZE 등)는 폼 문구 표(VALIDATION_COPY)에 없어서
  필드 문구가 "입력값을 확인해 주세요."(form.validation.unknown)다. 필드
  위치는 맞게 표시된다. 코드별 문구는 이 변경 밖이다.
- 페이지·정렬 파라미터 검증(PageValidationException)은 details가 배열이
  아닌 단일 {field, code}라 지금처럼 UNKNOWN_CLIENT_FAILURE로 남는다. 폼
  입력이 아니라 목록 조회 파라미터다.
- V2 필드 검증 실패에는 effect가 없다(422와 같다). mutation 코디네이터는
  이것을 MAYBE_APPLIED로 보고 admission을 붙든다. 422에도 있던 기존 동작이다.

검증
- RED: tests/component/form-foundation.test.tsx 새 행이 실패. V2
  클라이언트가 400 VALIDATION_FAILED를 받으면 폼 결과가 "unavailable"이고
  Name 필드에 aria-invalid가 없다. tests/integration/http-client.test.ts
  "reads the field details as validation issues" 실패(kind
  UNKNOWN_CLIENT_FAILURE, issues 없음). 다른 400 3행은 처음부터 통과(유지
  동작 고정).
- GREEN: 위 행 모두 통과. tests/unit·contract·runtime-schema·integration·
  component·features·platform 283 files 중 282 통과, 3394 tests 통과.
  실패 1개(tests/unit/second-api-feature-registries.test.ts "passes
  check-registries…")는 기준 3b7d73a에서도 같은 메시지로 실패한다.
  tsc app·test·node 통과, 바꾼 파일 eslint 통과, check:registries PASS.

Refs: clean-architecture-backend-template docs/web/http-contract.md 4절
2026-11-03 02:15:48 +09:00

691 lines
22 KiB
TypeScript

import { HttpResponse, http } from "msw";
import { setupServer } from "msw/node";
import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
import { createHttpClient } from "../../src/adapters/http/client.ts";
import { mappingSuccess } from "../../src/contracts/boundary-mapper.ts";
import {
TEST_HTTP_CONTRACT,
TEST_OPERATIONS,
} from "../helpers/http-contract-fixture.ts";
let attempts = 0;
const server = setupServer(
http.get("https://api.test/api/entities", () => {
attempts += 1;
if (attempts < 3) {
return HttpResponse.json(
{ success: false, error: { code: "TEMPORARY" } },
{ status: 503 },
);
}
return HttpResponse.json({
success: true,
data: [{ id: "resource-1", name: "Example" }],
meta: { requestId: "request-1", traceId: "trace-1" },
});
}),
);
beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
afterEach(() => {
attempts = 0;
server.resetHandlers();
});
afterAll(() => server.close());
const clock = {
now: () => 0,
sleep: async () => {},
};
type HttpDependencies = Parameters<typeof createHttpClient>[0];
function testClient(options: HttpDependencies) {
return createHttpClient({ ...TEST_HTTP_CONTRACT, ...options });
}
describe("shared HTTP client", () => {
it("retries a safe request at most twice and returns validated data", async () => {
const client = testClient({
baseUrl: "https://api.test",
clock,
random: () => 0,
});
await expect(
client.execute("LIST_ENTITIES", { routeId: "TEST_ROUTE" }),
).resolves.toMatchObject({
ok: true,
value: [{ id: "resource-1", displayName: "Example" }],
meta: { requestId: "request-1" },
});
expect(attempts).toBe(3);
});
it.each(["", " ", "bad\u0000key", "x".repeat(513)])(
"rejects invalid keyed command key %j before credentials and fetch",
async (idempotencyKey) => {
let fetched = 0;
let credentialAttempts = 0;
server.use(
http.post("https://api.test/api/entities", () => {
fetched += 1;
return HttpResponse.json({ success: true, data: {} });
}),
);
const client = testClient({
baseUrl: "https://api.test",
clock,
authSession: {
getState: () => "authenticated",
getSubject: () => "user-a",
subscribe: () => () => {},
beginSignIn: async () => {},
signOut: async () => {},
async credentialPatch() {
credentialAttempts += 1;
return { headers: {} };
},
recover: async () => "no-session" as const,
onUnauthenticated: () => {},
},
});
await expect(
client.execute("CREATE_ENTITY", {
body: { name: "n" },
idempotencyKey,
}),
).resolves.toMatchObject({
ok: false,
error: {
kind: "VALIDATION_REJECTED",
code: "IDEMPOTENCY_KEY_INVALID",
// The repository reports attempt counts as 1-based; the invariant
// proved below is that no physical attempt happened at all.
attemptCount: 1,
},
});
expect(fetched).toBe(0);
expect(credentialAttempts).toBe(0);
},
);
it("bounds a non-cooperative legacy credential owner by total deadline", async () => {
let fetched = 0;
let observedSignal: AbortSignal | undefined;
server.use(
http.get("https://api.test/api/entities", () => {
fetched += 1;
return HttpResponse.json({ success: true, data: [] });
}),
);
const client = testClient({
baseUrl: "https://api.test",
timeoutMs: 5,
clock: { now: () => 0, sleep: async () => {} },
authSession: {
getState: () => "authenticated",
getSubject: () => "user-a",
subscribe: () => () => {},
beginSignIn: async () => {},
signOut: async () => {},
credentialPatch: (_binding, context) => {
observedSignal = context?.signal;
// Never settles on its own.
return new Promise<never>(() => {});
},
recover: async () => "no-session" as const,
onUnauthenticated: () => {},
},
});
const result = await client.execute("LIST_ENTITIES");
expect(result).toMatchObject({ ok: false });
expect(fetched).toBe(0);
expect(observedSignal).toBeDefined();
});
it("rejects a non-JSON response without exposing its body", async () => {
server.use(
http.get(
"https://api.test/api/entities",
() => new HttpResponse("<secret>raw body</secret>", { status: 200 }),
),
);
const client = testClient({ baseUrl: "https://api.test", clock });
const result = await client.execute("LIST_ENTITIES");
expect(result).toMatchObject({
ok: false,
error: { kind: "CONTENT_TYPE_MISMATCH" },
});
expect(JSON.stringify(result)).not.toContain("raw body");
});
// Q-6.3-3b. A gateway 5xx/408/425 with an HTML, empty or broken body is a
// server outage, not a contract breach: it keeps its status and the V2
// SERVER_FAILURE retry rule (408/425/502/503/504, R3-1).
it.each([
{ status: 502, contentType: "text/html", body: "<secret>raw body</secret>", fetches: 3 },
{ status: 503, contentType: "application/json", body: "", fetches: 3 },
{ status: 504, contentType: "application/json", body: "{", fetches: 3 },
{ status: 408, contentType: "text/plain", body: "timeout", fetches: 3 },
{ status: 425, contentType: "text/html", body: "<p>too early</p>", fetches: 3 },
])(
"keeps a $status gateway body as a server failure with its status",
async ({ status, contentType, body, fetches }) => {
let fetched = 0;
server.use(
http.get("https://api.test/api/entities", () => {
fetched += 1;
return new HttpResponse(body, {
status,
headers: { "Content-Type": contentType },
});
}),
);
const client = testClient({
baseUrl: "https://api.test",
clock,
random: () => 0,
});
const result = await client.execute("LIST_ENTITIES");
expect(result).toMatchObject({
ok: false,
error: { kind: "SERVER_FAILURE", httpStatus: status },
});
expect(fetched).toBe(fetches);
expect(JSON.stringify(result)).not.toContain("raw body");
},
);
const errorEnvelope = {
success: false,
error: { code: "UPSTREAM_BUSY" },
meta: { requestId: "request-1", traceId: "trace-1" },
};
// A gateway body (not an envelope) or a valid V2 error envelope.
function busyResponse(
status: number,
envelope: boolean,
headers: Record<string, string> = {},
) {
return envelope
? HttpResponse.json(errorEnvelope, { status, headers })
: new HttpResponse("busy", {
status,
headers: { "Content-Type": "text/plain", ...headers },
});
}
const busyCases = [408, 425, 503].flatMap((status) => [
{ status, envelope: false },
{ status, envelope: true },
]);
// R3-1. A 408/425 with a valid error envelope is a server failure in V2 and
// keeps the backend code the envelope carries.
it.each([408, 425, 503])(
"retries a safe request on a %i error envelope and keeps its code",
async (status) => {
let fetched = 0;
server.use(
http.get("https://api.test/api/entities", () => {
fetched += 1;
return busyResponse(status, true);
}),
);
const client = testClient({
baseUrl: "https://api.test",
clock,
random: () => 0,
});
await expect(client.execute("LIST_ENTITIES")).resolves.toMatchObject({
ok: false,
error: {
kind: "SERVER_FAILURE",
code: "UPSTREAM_BUSY",
httpStatus: status,
requestId: "request-1",
},
});
expect(fetched).toBe(3);
},
);
// R3-1. 408/425/503 follow the retry rule of the operation: a keyed command
// may replay, a non-idempotent command is never replayed.
it.each(
busyCases.flatMap((busy) => [
{ ...busy, idempotency: "none" as const, fetches: 1 },
{ ...busy, idempotency: "keyed" as const, fetches: 3 },
]),
)(
"sends a $idempotency command $fetches time(s) on $status (envelope: $envelope)",
async ({ status, envelope, idempotency, fetches }) => {
let fetched = 0;
server.use(
http.post("https://api.test/api/entities", () => {
fetched += 1;
return busyResponse(status, envelope);
}),
);
const client = testClient({
baseUrl: "https://api.test",
clock,
random: () => 0,
getOperation: () => ({ ...TEST_OPERATIONS.CREATE_ENTITY, idempotency }),
});
const result = await client.execute("CREATE_ENTITY", {
body: { name: "n" },
...(idempotency === "keyed" ? { idempotencyKey: "key-1" } : {}),
});
expect(result).toMatchObject({
ok: false,
error: { kind: "SERVER_FAILURE", httpStatus: status },
});
expect(fetched).toBe(fetches);
},
);
function retryAfterClient(delays: number[]) {
return testClient({
baseUrl: "https://api.test",
clock: {
now: () => 0,
sleep: async (ms: number) => {
delays.push(ms);
},
},
random: () => 0.5, // local backoff for the first retry: 125ms
});
}
function listAfter(first: () => Response) {
let fetched = 0;
server.use(
http.get("https://api.test/api/entities", () => {
fetched += 1;
return fetched === 1
? first()
: HttpResponse.json({
success: true,
data: [],
meta: { requestId: "request-1", traceId: "trace-1" },
});
}),
);
}
// R3-1. The retry waits at least the Retry-After of a 408/425/503, under
// the same 30s ceiling as a 429.
it.each(busyCases)(
"waits for the Retry-After of a $status (envelope: $envelope)",
async ({ status, envelope }) => {
listAfter(() => busyResponse(status, envelope, { "Retry-After": "2" }));
const delays: number[] = [];
await expect(
retryAfterClient(delays).execute("LIST_ENTITIES"),
).resolves.toMatchObject({ ok: true });
expect(delays).toEqual([2_000]);
},
);
// R3-1. 502/504 keep the local backoff whatever Retry-After says.
it.each([502, 504])(
"ignores the Retry-After of a %i",
async (status) => {
listAfter(() => busyResponse(status, true, { "Retry-After": "2" }));
const delays: number[] = [];
await expect(
retryAfterClient(delays).execute("LIST_ENTITIES"),
).resolves.toMatchObject({ ok: true });
expect(delays).toEqual([125]);
},
);
it.each(busyCases)(
"does not retry a $status whose Retry-After exceeds 30 seconds (envelope: $envelope)",
async ({ status, envelope }) => {
let fetched = 0;
server.use(
http.get("https://api.test/api/entities", () => {
fetched += 1;
return busyResponse(status, envelope, { "Retry-After": "31" });
}),
);
const delays: number[] = [];
await expect(
retryAfterClient(delays).execute("LIST_ENTITIES"),
).resolves.toMatchObject({
ok: false,
error: { kind: "SERVER_FAILURE", httpStatus: status, retryAfterMs: 31_000 },
});
expect(fetched).toBe(1);
expect(delays).toEqual([]);
},
);
// R3-1. Retry-After goes through the platform kernel parser: delta-seconds
// or an IMF-fixdate only. Anything else falls back to the local backoff.
it.each([
{ value: "2", delay: 2_000 },
{ value: " 2 ", delay: 2_000 },
{ value: "Thu, 01 Jan 1970 00:00:05 GMT", delay: 5_000 },
{ value: "", delay: 125 },
{ value: " ", delay: 125 },
{ value: "1e3", delay: 125 },
{ value: "1.5", delay: 125 },
{ value: "0x10", delay: 125 },
{ value: "-1", delay: 125 },
{ value: "2099-01-01T00:00:00Z", delay: 125 },
{ value: "Thursday, 01-Jan-70 00:00:05 GMT", delay: 125 },
])("parses a 429 Retry-After of $value as $delay ms", async ({ value, delay }) => {
let fetched = 0;
server.use(
http.get("https://api.test/api/entities", () => {
fetched += 1;
return fetched === 1
? HttpResponse.json(
{
success: false,
error: { code: "RATE_LIMITED" },
meta: { requestId: "request-1", traceId: "trace-1" },
},
{ status: 429, headers: { "Retry-After": value } },
)
: HttpResponse.json({
success: true,
data: [],
meta: { requestId: "request-1", traceId: "trace-1" },
});
}),
);
const delays: number[] = [];
await expect(
retryAfterClient(delays).execute("LIST_ENTITIES"),
).resolves.toMatchObject({ ok: true });
expect(delays).toEqual([delay]);
});
it("classifies malformed JSON and invalid payloads at the boundary", async () => {
server.use(
http.get(
"https://api.test/api/entities",
() =>
new HttpResponse("{", {
headers: { "Content-Type": "application/json" },
}),
),
);
const client = testClient({ baseUrl: "https://api.test", clock });
await expect(client.execute("LIST_ENTITIES")).resolves.toMatchObject({
ok: false,
error: { kind: "MALFORMED_JSON" },
});
server.use(
http.get("https://api.test/api/entities", () =>
HttpResponse.json({
success: true,
data: [{ id: "resource-1", name: 42 }],
meta: { requestId: "request-1", traceId: "trace-1" },
}),
),
);
await expect(client.execute("LIST_ENTITIES")).resolves.toMatchObject({
ok: false,
error: { kind: "SCHEMA_MISMATCH" },
});
});
it("projects only approved 422 issue path and code metadata", async () => {
server.use(
http.post("https://api.test/api/entities", () =>
HttpResponse.json(
{
success: false,
error: {
code: "INVALID_INPUT",
message: "raw backend secret",
details: {
issues: [
{ path: "name", code: "REQUIRED", message: "raw field copy" },
{ path: 42, code: "INVALID" },
],
},
},
meta: { requestId: "request-422", traceId: "trace-422" },
},
{ status: 422 },
),
),
);
const client = testClient({ baseUrl: "https://api.test", clock });
const result = await client.execute("CREATE_ENTITY", {
routeId: "TEST_FORM",
body: { name: "Valid" },
});
expect(result).toMatchObject({
ok: false,
error: {
kind: "VALIDATION_REJECTED",
validationIssues: [{ path: "name", code: "REQUIRED" }],
},
});
expect(JSON.stringify(result)).not.toContain("raw backend secret");
expect(JSON.stringify(result)).not.toContain("raw field copy");
});
it("guards mapper exceptions as a mapping contract violation", async () => {
server.use(
http.get("https://api.test/api/entities", () =>
HttpResponse.json({
success: true,
data: [{ id: "resource-1", name: "Example" }],
meta: { requestId: "request-1", traceId: "trace-1" },
}),
),
);
const client = testClient({
baseUrl: "https://api.test",
clock,
mapPayload: () => {
throw new Error("raw mapper detail");
},
});
const result = await client.execute("LIST_ENTITIES");
expect(result).toMatchObject({
ok: false,
error: { kind: "MAPPING_CONTRACT_VIOLATION" },
});
expect(JSON.stringify(result)).not.toContain("raw mapper detail");
});
});
// 백엔드 1101/02-01. The paired backend answers a same-key request while the
// first still runs with 409 IDEMPOTENT_IN_FLIGHT, retryable and Retry-After 2.
// The client does not resend it itself (the result is unknown); it hands the
// Retry-After to whoever resends with the same key.
it("keeps the Retry-After of an in-flight 409 without resending", async () => {
let fetched = 0;
server.use(
http.post("https://api.test/api/entities", () => {
fetched += 1;
return HttpResponse.json(
{
success: false,
error: {
code: "IDEMPOTENT_IN_FLIGHT",
category: "CONFLICT",
message: "같은 요청을 처리하고 있습니다.",
retryable: true,
},
meta: { requestId: "request-1", traceId: "trace-1" },
},
{ status: 409, headers: { "Retry-After": "2" } },
);
}),
);
const client = testClient({ baseUrl: "https://api.test", clock });
await expect(
client.execute("CREATE_ENTITY", {
body: { name: "n" },
idempotencyKey: "key-1",
}),
).resolves.toMatchObject({
ok: false,
error: {
kind: "CONFLICT",
code: "IDEMPOTENT_IN_FLIGHT",
retryAfterMs: 2_000,
},
});
expect(fetched).toBe(1);
});
// 백엔드 1101/02-02. The paired backend drops a null field together with its
// key (its docs/web/http-contract.md §1). A missing key must read as the null
// it stands for.
describe("envelope keys the paired backend omits", () => {
const meta = { requestId: "request-1", traceId: "trace-1" };
it.each([
{ shape: "data: null", body: { success: true, data: null, meta } },
{ shape: "no data key", body: { success: true, meta } },
])("reads a success with $shape as null data", async ({ body }) => {
server.use(
http.get("https://api.test/api/entities", () => HttpResponse.json(body)),
);
const validated: unknown[] = [];
const client = testClient({
baseUrl: "https://api.test",
clock,
validatePayload: (_schemaId, value) => {
validated.push(value);
return { success: true, data: value };
},
mapPayload: (_operationId, value) => mappingSuccess(value),
});
await expect(client.execute("LIST_ENTITIES")).resolves.toMatchObject({
ok: true,
value: null,
});
expect(validated).toEqual([null]);
});
it.each([
{ shape: "with ids and details", meta, details: { reason: "X" } },
{ shape: "without details", meta, details: undefined },
// Answered before the request id filter: the id keys are absent.
{ shape: "without ids", meta: {}, details: undefined },
])("keeps the backend code of a failure $shape", async ({ meta, details }) => {
server.use(
http.get("https://api.test/api/entities", () =>
HttpResponse.json(
{
success: false,
error: {
code: "ACCESS_DENIED",
category: "FORBIDDEN",
message: "권한이 없습니다.",
retryable: false,
...(details === undefined ? {} : { details }),
},
meta,
},
{ status: 403 },
),
),
);
const client = testClient({ baseUrl: "https://api.test", clock });
await expect(client.execute("LIST_ENTITIES")).resolves.toMatchObject({
ok: false,
error: { kind: "FORBIDDEN", code: "ACCESS_DENIED", httpStatus: 403 },
});
});
});
// 백엔드 1101/02-01 후속. The paired backend answers a field validation
// failure with 400 VALIDATION_FAILED, details [{field, code, message}]
// (its docs/web/http-contract.md §4): read as the 422 field validation it is.
// Every other 400 keeps its reading.
describe("paired backend 400 VALIDATION_FAILED", () => {
const meta = { requestId: "request-1", traceId: "trace-1" };
function answer400(code: string, details?: unknown) {
server.use(
http.post("https://api.test/api/entities", () =>
HttpResponse.json(
{
success: false,
error: {
code,
category: "VALIDATION",
message: "요청 값이 올바르지 않습니다.",
retryable: false,
...(details === undefined ? {} : { details }),
},
meta,
},
{ status: 400 },
),
),
);
return testClient({ baseUrl: "https://api.test", clock }).execute(
"CREATE_ENTITY",
{ body: { name: "n" }, idempotencyKey: "key-1" },
);
}
it("reads the field details as validation issues, without backend copy", async () => {
const result = await answer400("VALIDATION_FAILED", [
{ field: "name", code: "NOT_BLANK", message: "raw backend copy" },
{ field: "items.name", code: "SIZE", message: "raw backend copy" },
{ field: "request", code: "INVALID", message: "raw backend copy" },
]);
expect(result).toMatchObject({
ok: false,
error: {
kind: "VALIDATION_REJECTED",
code: "VALIDATION_FAILED",
httpStatus: 400,
retryable: false,
validationIssues: [
{ path: "name", code: "NOT_BLANK" },
{ path: "items.name", code: "SIZE" },
{ path: "request", code: "INVALID" },
],
},
});
expect(JSON.stringify(result)).not.toContain("raw backend copy");
});
it.each([
// A body that did not parse: details names the cause, not a field.
{ code: "VALIDATION_FAILED", details: { cause: "JsonParseException" } },
{ code: "VALIDATION_FAILED", details: undefined },
{ code: "BAD_PARAMETER", details: { parameter: "limit" } },
])("keeps a 400 $code with details $details as before", async ({ code, details }) => {
const result = await answer400(code, details);
expect(result).toMatchObject({
ok: false,
error: { kind: "UNKNOWN_CLIENT_FAILURE", code, httpStatus: 400 },
});
expect(result.ok ? null : result.error.validationIssues).toBeUndefined();
});
});