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:
@@ -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();
|
||||
|
||||
@@ -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 },
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user