From 969979d904a4b96b6fec2efc9e976c608b4c376f Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 3 Nov 2026 01:48:03 +0900 Subject: [PATCH] =?UTF-8?q?fix(http):=20=EC=A7=9D=20=EB=B0=B1=EC=97=94?= =?UTF-8?q?=EB=93=9C=EA=B0=80=20=EC=83=9D=EB=9E=B5=ED=95=9C=20Envelope=20?= =?UTF-8?q?=ED=82=A4=EB=A5=BC=20null=EA=B3=BC=20=EA=B0=99=EC=9D=B4=20?= =?UTF-8?q?=EC=9D=BD=EB=8A=94=EB=8B=A4=20(=EB=B0=B1=EC=97=94=EB=93=9C=2011?= =?UTF-8?q?01/02-02)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 짝 백엔드는 이제 값이 null인 필드를 키째 뺀다(백엔드 docs/web/http-contract.md §1). V2 Envelope 스키마 (src/adapters/http/schema-registry.ts)는 두 곳에서 "키 없음"을 null과 다르게 읽는다. - 성공 응답의 data: z.unknown()은 키가 없으면 거절한다(zod 4). 백엔드가 data:null을 빼고 보낸 성공이 ENVELOPE_MISMATCH 실패가 된다. data:null은 그대로 통과한다. - meta.requestId·traceId가 필수다. 백엔드는 요청 id 필터 앞에서 끊긴 응답(보안 entry point 등)에서 이 키를 뺄 수 있다고 적는다. 그러면 실패 Envelope 전체가 거절되어 백엔드 error.code가 HTTP_FAILURE로 바뀐다. error.details(키 없음 허용), meta.correlationId(선택), meta.page(strip)는 이미 키가 없어도 받는다. 고른 방법 - data를 z.unknown().default(null)로 둔다. 키가 없으면 스키마가 null을 채우므로 client.ts의 "data" in 검사와 payload 검증이 data:null과 같은 길을 탄다. 정규화가 wire 스키마 한 곳에 있다. - meta.requestId·traceId를 optional로 둔다. safeMeta()는 이미 키가 없는 경우를 처리한다. 버린 대안 - client.ts에서 "data" in 검사를 빼고 data ?? null로 읽기: 스키마와 클라이언트 두 곳이 같은 규칙을 나눠 갖는다. - 성공의 error:null, 실패의 data:null도 다시 받기: 백엔드가 더는 보내지 않는 모양이다. 최상위 strict는 그대로 둔다. 위험·한계 - meta id가 없는 Envelope도 이제 유효하다. 그런 응답의 HttpResult.meta와 AppFailure에는 requestId·traceId가 없다(이전에는 응답 전체가 거절됐다). - V3 실행기는 Envelope를 읽지 않는다(DTO 자체를 검증). 이 변경은 V2 경로만 바꾼다. bulk Envelope(results)는 프론트에 쓰는 곳이 없어 다루지 않았다. 검증 - RED: tests/integration/http-client.test.ts "envelope keys the paired backend omits" 5행 중 2행 실패. data 키 없는 성공이 ok:false, id 키 없는 403이 code HTTP_FAILURE. - GREEN: 같은 5행 통과. tests/integration/http-client·http-diagnostics· http-execution-contract·auth-recovery·legacy-http-credential-authority, tests/runtime-schema 8 files 150 tests 통과. tsc app·test 통과, 바꾼 파일 eslint 통과. Refs: clean-architecture-backend-template docs/reviews/2026-11-01-maturity-review/README.md 14.3, 15 --- src/adapters/http/schema-registry.ts | 13 ++++-- tests/integration/http-client.test.ts | 65 +++++++++++++++++++++++++++ 2 files changed, 75 insertions(+), 3 deletions(-) diff --git a/src/adapters/http/schema-registry.ts b/src/adapters/http/schema-registry.ts index ffe12b80..b22ca36b 100644 --- a/src/adapters/http/schema-registry.ts +++ b/src/adapters/http/schema-registry.ts @@ -1,10 +1,16 @@ import { z } from "../../contracts/zod.ts"; import { projectValidationIssues } from "../../contracts/validation-issues.ts"; +/** + * 백엔드 1101/02-02. The paired backend drops a null field together with its + * key (clean-architecture-backend-template docs/web/http-contract.md §1). The + * id keys are absent on an answer written before its request id filter, so + * they are optional here too. + */ const metaSchema = z .object({ - requestId: z.string().regex(/^[A-Za-z0-9._:-]{1,128}$/), - traceId: z.string().regex(/^[A-Za-z0-9._:-]{1,128}$/), + requestId: z.string().regex(/^[A-Za-z0-9._:-]{1,128}$/).optional(), + traceId: z.string().regex(/^[A-Za-z0-9._:-]{1,128}$/).optional(), correlationId: z.string().regex(/^[A-Za-z0-9._:-]{1,128}$/).optional(), }) .strip(); @@ -12,7 +18,8 @@ const metaSchema = z export const successEnvelopeSchema = z .object({ success: z.literal(true), - data: z.unknown(), + // A missing `data` is the null the backend dropped. + data: z.unknown().default(null), meta: metaSchema, }) .strict(); diff --git a/tests/integration/http-client.test.ts b/tests/integration/http-client.test.ts index bb8eb096..44243efe 100644 --- a/tests/integration/http-client.test.ts +++ b/tests/integration/http-client.test.ts @@ -3,6 +3,7 @@ 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, @@ -509,3 +510,67 @@ describe("shared HTTP client", () => { expect(JSON.stringify(result)).not.toContain("raw mapper detail"); }); }); + +// 백엔드 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 }, + }); + }); +});