fix(http): 짝 백엔드가 생략한 Envelope 키를 null과 같이 읽는다 (백엔드 1101/02-02)

문제
짝 백엔드는 이제 값이 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
This commit is contained in:
DongHyeonka
2026-11-03 02:00:45 +09:00
parent 8b7c6ebf6c
commit 969979d904
2 changed files with 75 additions and 3 deletions
+10 -3
View File
@@ -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();
+65
View File
@@ -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 },
});
});
});