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
This commit is contained in:
@@ -324,7 +324,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기
|
||||
- 멱등성 응답(`IDEMPOTENT_*`, `IDEMPOTENCY_*`)과 V3 표에 있는 web 공통 응답은 V3 실행기와 같은 표(`backend-envelope.ts`, 4절)로 판정한다. 400 `IDEMPOTENCY_KEY_INVALID`·422 `IDEMPOTENT_REQUEST_MISMATCH`는 `NOT_APPLIED`, 409 `IDEMPOTENT_IN_FLIGHT`·503 `IDEMPOTENCY_UNAVAILABLE`·503 `IDEMPOTENCY_COMPLETION_UNKNOWN`·500 `IDEMPOTENCY_RECOVERY_REQUIRED`는 `MAYBE_APPLIED`다.
|
||||
- `APPLIED_CONFIRMED`: 서버는 만들었다고 답했지만 응답을 읽지 못했다. 다시 올리지 않는다.
|
||||
- `code`는 백엔드 code 그대로다(`FILE_TOO_LARGE`, `UNSUPPORTED_MEDIA_TYPE`, `MALWARE_DETECTED` …). 백엔드가 code를 주지 않는 거절은 client가 이름을 붙인다(`FILE_REJECTED`, `FILE_EMPTY`, `FILE_NOT_READABLE`). 화면 문구는 기능이 code로 고른다.
|
||||
- 실패 Envelope의 `meta.traceId`는 실패의 `traceId`로 온다. V3 실행기와 같다. 지원 담당이 서버 로그에서 그 요청을 찾을 때 쓴다.
|
||||
- 실패 Envelope의 `meta.traceId`는 실패의 `traceId`로 온다. V3 실행기와 같다. 지원 담당이 서버 로그에서 그 요청을 찾을 때 쓴다. 202 `REJECTED`의 `FILE_REJECTED`도 성공 Envelope의 `meta.traceId`를 싣는다. 이 응답에는 거절 이유가 없다. 짝 백엔드는 검증기 code를 파일 레코드에만 적는다. 그래서 화면은 이유별 문구를 고를 수 없다.
|
||||
- client는 스스로 다시 보내지 않는다. `retryable: true`이고 `retryAfterMs`가 있으면 그만큼 기다린 뒤 기능이 다시 부른다. 서버가 상한(`maxRetryAfterMs`, 기본 30초)보다 길게 기다리라고 하면 `retryable: false`다.
|
||||
- `MAYBE_APPLIED`는 언제나 `retryable: false`다. 백엔드가 Envelope에 `retryable: true`와 `Retry-After`를 붙여도(504 `TRANSFER_TIMEOUT`) 기능이 자동으로 다시 부르지 않는다. 아래 주의대로 먼저 확인한다.
|
||||
|
||||
|
||||
@@ -93,13 +93,23 @@ const ENVELOPE_INVALID: EnvelopeRead<never> = Object.freeze({ ok: false });
|
||||
/**
|
||||
* The success `data`. A missing key is the null the backend dropped.
|
||||
* 1103/03-02. A page list's `meta.page` comes with it.
|
||||
* 1106/01-01. And the backend's `meta.traceId`, when it sent one, as
|
||||
* `readFailureEnvelope` gives it, for a client that turns a well-formed
|
||||
* answer into a failure (Fileserver's 202 `REJECTED`).
|
||||
*/
|
||||
export function readSuccessEnvelope(
|
||||
value: unknown,
|
||||
): Readonly<{ ok: true; value: unknown; page?: EnvelopePage }> | Readonly<{ ok: false }> {
|
||||
):
|
||||
| Readonly<{
|
||||
ok: true;
|
||||
value: unknown;
|
||||
page?: EnvelopePage;
|
||||
traceId?: string;
|
||||
}>
|
||||
| Readonly<{ ok: false }> {
|
||||
const parsed = successEnvelopeSchema.safeParse(value);
|
||||
if (!parsed.success) return ENVELOPE_INVALID;
|
||||
const page = parsed.data.meta.page;
|
||||
const { page, traceId } = parsed.data.meta;
|
||||
return Object.freeze({
|
||||
ok: true as const,
|
||||
value: parsed.data.data,
|
||||
@@ -113,6 +123,7 @@ export function readSuccessEnvelope(
|
||||
...(typeof page.sort === "string" ? { sort: page.sort } : {}),
|
||||
}),
|
||||
}),
|
||||
...(traceId === undefined ? {} : { traceId }),
|
||||
});
|
||||
}
|
||||
|
||||
|
||||
@@ -682,9 +682,15 @@ async function readAnswer(
|
||||
// 1105/01-01. The file is the user's to replace, as with a 413, 415 or
|
||||
// 422 refusal. The backend keeps the record unpublished and schedules
|
||||
// its bytes for removal, so nothing usable was stored.
|
||||
// 1106/01-01. The server answered, so the failure carries its
|
||||
// `meta.traceId` as an Envelope failure does (1105/01-03). The answer
|
||||
// names no reason: the backend keeps the verifier's code on its record.
|
||||
return failure("VALIDATION_REJECTED", "FILE_REJECTED", {
|
||||
httpStatus: status,
|
||||
effect: "NOT_APPLIED",
|
||||
...(envelope.traceId === undefined
|
||||
? {}
|
||||
: { traceId: envelope.traceId }),
|
||||
});
|
||||
}
|
||||
return Object.freeze({
|
||||
@@ -790,6 +796,7 @@ function failure(
|
||||
details: Readonly<{
|
||||
effect: FailureEffectCertainty;
|
||||
httpStatus?: number;
|
||||
traceId?: string;
|
||||
}>,
|
||||
): Result<never, AppFailure> {
|
||||
return Object.freeze({
|
||||
|
||||
@@ -214,6 +214,8 @@ describe("Fileserver multipart upload — success", () => {
|
||||
|
||||
it("reads 202 REJECTED as a refused file, not as a broken answer", async () => {
|
||||
// 1105/01-01. A verifier refused the file for a reason other than malware.
|
||||
// 1106/01-01. The server answered, so its `meta.traceId` comes with the
|
||||
// failure for support to find the upload in the server logs.
|
||||
answer({
|
||||
status: 202,
|
||||
body: successEnvelope(
|
||||
@@ -233,6 +235,7 @@ describe("Fileserver multipart upload — success", () => {
|
||||
retryable: false,
|
||||
action: "none",
|
||||
operationId: "FILESERVER_UPLOAD",
|
||||
traceId: "trace-1",
|
||||
}),
|
||||
});
|
||||
});
|
||||
|
||||
@@ -19,13 +19,14 @@ describe("paired backend Envelope boundary", () => {
|
||||
});
|
||||
|
||||
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: [] });
|
||||
).toEqual({ ok: true, value: [], traceId: "trace-1" });
|
||||
expect(readSuccessEnvelope({ success: true, meta: {} })).toEqual({
|
||||
ok: true,
|
||||
value: null,
|
||||
|
||||
@@ -50,7 +50,12 @@ describe("accessibility e2e API answers", () => {
|
||||
expect(answer.kind).toBe("empty-list");
|
||||
if (answer.kind !== "empty-list") return;
|
||||
// What the executor reads out of the frame is what the operation accepts.
|
||||
expect(readSuccessEnvelope(answer.body)).toEqual({ ok: true, value: [] });
|
||||
// 1106/01-01. The reader also gives the scenario meta's `traceId`.
|
||||
expect(readSuccessEnvelope(answer.body)).toEqual({
|
||||
ok: true,
|
||||
value: [],
|
||||
traceId: "0af7651916cd43dd8448eb211c80319c",
|
||||
});
|
||||
expect(LIST!.contract.outputValidator.safeParse([]).success).toBe(true);
|
||||
});
|
||||
|
||||
|
||||
Reference in New Issue
Block a user