Files
DongHyeonka 7395c78c3a fix(http): 202 REJECTED 업로드 실패에 응답의 traceId를 싣는다
문제: 짝 백엔드 Fileserver는 검증기가 거절한 업로드를 202 성공
Envelope(state REJECTED)로 답한다. client는 이 답을 FILE_REJECTED
실패로 바꾸는데, readSuccessEnvelope가 meta.traceId를 버려서 실패에
traceId가 없다. 같은 client의 Envelope 실패는 traceId를 싣는다
(1105/01-03). 서버가 정상으로 답해 trace 값이 손에 있는데도, 지원
담당이 이 거절을 서버 로그나 REJECTED 레코드와 잇지 못한다.

고른 방법: readSuccessEnvelope가 readFailureEnvelope처럼 meta.traceId가
있으면 traceId로 함께 돌려준다. Fileserver client는 202 REJECTED
실패에 그 값을 싣는다. V3 실행기는 value와 page만 읽으므로 동작이
같다. 매뉴얼 7절 결과 읽기 줄에 적었다.
버린 대안: fileserver-upload가 successEnvelopeSchema를 직접 파싱하면
Envelope 읽기가 backend-envelope.ts 밖으로 갈라진다. traceId만 읽는
함수를 따로 두면 같은 답을 두 번 파싱한다.
반환 칸이 늘어 readSuccessEnvelope 결과를 toEqual로 보는 테스트 두
곳(tests/runtime-schema/http-schema.test.ts,
tests/unit/a11y-api-answers.test.ts)의 기대값에 traceId를 더했다.
기대를 넓힌 것이 아니라 새 칸의 값까지 고정한 것이다.

위험·한계: 거절 이유는 여전히 없다. 프론트로는 고칠 수 없어
백엔드로 넘긴다.
- 사실(백엔드 45d2a478): FinalizeUploadApplicationUseCase
  #applyNonAcceptVerdict는 REJECT 판정의 code(FILE_TOO_LARGE,
  DIGEST_MALFORMED, 제품 검증기 code 등)를 FileRecordMutation.failure로
  레코드의 lastErrorCode에만 쓴다. FileUploadController#created는
  UploadedFileResponse 7칸(fileId, state, filename, mediaType, size,
  sha256, etag)을 202로 답한다. 이유 칸이 없다.
- 요청: REJECT를 실패 Envelope(422, error.code = 판정 code,
  retryable false)로 답하거나, 202 REJECTED 응답에 판정 code 칸을
  더한다. 앞의 것이면 프론트의 기존 422 경로가 code와 traceId를
  그대로 싣고 NOT_APPLIED로 읽는다. 그때 FILE_REJECTED 분기는 지운다.
- CHANGELOG의 "백엔드로 넘김" 목록에 이 항목을 더하는 일은 CHANGELOG
  담당에게 남긴다.
실제 배포 응답의 성공 meta에 traceId가 있는지는 백엔드 문서
(docs/web/http-contract.md §1 meta 키)와 EnvelopeBodyAdvice 코드로만
확인했다. backend-envelope.ts는 초기 번들에 있어 초기 JS가 수십 B
늘 수 있다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts tests/runtime-schema/http-schema.test.ts tests/unit/a11y-api-answers.test.ts
RED(이 커밋의 테스트 + 부모 src): "reads 202 REJECTED as a refused
file, not as a broken answer"가 traceId "trace-1"이 없어 실패한다.
"reads data, and a dropped data key as null"과 "answers an Envelope
list read with an empty list inside the Envelope"는 결과에 traceId
칸이 없어 실패한다.

Refs: 1106/01-01
2026-11-06 05:18:58 +09:00

103 lines
3.2 KiB
TypeScript

import { describe, expect, it } from "vitest";
import {
readFailureEnvelope,
readSuccessEnvelope,
} from "../../src/adapters/http/backend-envelope.ts";
import {
composeRuntimeSchemaCodecs,
validateWithRuntimeSchemaRegistry,
} from "../../src/contracts/schema-registry.ts";
describe("paired backend Envelope boundary", () => {
it("rejects an invalid top-level envelope", () => {
expect(readSuccessEnvelope({ success: true }).ok).toBe(false);
expect(
readSuccessEnvelope({ success: true, data: [], meta: {}, error: {} }).ok,
).toBe(false);
expect(readFailureEnvelope({ success: false, meta: {} }).ok).toBe(false);
});
it("reads data, and a dropped data key as null", () => {
// 1106/01-01. With `meta.traceId`, as the failure reader gives it.
expect(
readSuccessEnvelope({
success: true,
data: [],
meta: { requestId: "request-1", traceId: "trace-1" },
}),
).toEqual({ ok: true, value: [], traceId: "trace-1" });
expect(readSuccessEnvelope({ success: true, meta: {} })).toEqual({
ok: true,
value: null,
});
});
it("reads the failure error and refuses a code outside the backend grammar", () => {
expect(
readFailureEnvelope({
success: false,
error: { code: "NOT_FOUND", category: "NOT_FOUND", retryable: false },
meta: {},
}),
).toEqual({
ok: true,
value: { code: "NOT_FOUND", category: "NOT_FOUND", retryable: false },
});
expect(
readFailureEnvelope({ success: false, error: { code: "not-a-code" }, meta: {} }).ok,
).toBe(false);
});
});
describe("runtime schema codec contribution", () => {
const codec = {
schemaId: "Example",
parse: (value: unknown) => ({ success: true as const, data: value }),
};
it("resolves installed codecs and fails missing IDs closed", () => {
const registry = composeRuntimeSchemaCodecs([{ Example: codec }]);
expect(validateWithRuntimeSchemaRegistry("Example", 42, registry)).toEqual({
success: true,
data: 42,
});
expect(
validateWithRuntimeSchemaRegistry("Missing", 42, registry),
).toMatchObject({
success: false,
issues: [{ code: "SCHEMA_NOT_REGISTERED" }],
});
});
it("bounds failure issues returned by an installed codec", () => {
const noisyCodec = {
schemaId: "Noisy",
parse: () => ({
success: false as const,
issues: [
{ path: "p".repeat(121), code: "TOO_LONG_PATH" },
{ path: "field", code: "C".repeat(81) },
...Array.from({ length: 100 }, (_, index) => ({
path: `field.${index}`,
code: "INVALID",
})),
],
}),
};
const registry = composeRuntimeSchemaCodecs([{ Noisy: noisyCodec }]);
const result = validateWithRuntimeSchemaRegistry("Noisy", {}, registry);
expect(result.success).toBe(false);
if (result.success) throw new Error("expected validation failure");
expect(result.issues).toHaveLength(50);
expect(result.issues[0]).toEqual({ path: "field.0", code: "INVALID" });
});
it("rejects duplicate codec contributions", () => {
expect(() =>
composeRuntimeSchemaCodecs([{ Example: codec }, { Example: codec }]),
).toThrow("duplicate runtime schema codec");
});
});