From 8b92f45f5eefe85c92a58a3cd65fc7b2bd6b30b1 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:12:19 +0900 Subject: [PATCH] =?UTF-8?q?fix(http):=20Fileserver=20=EC=97=85=EB=A1=9C?= =?UTF-8?q?=EB=93=9C=20=EC=8B=A4=ED=8C=A8=EC=97=90=20Envelope=EC=9D=98=20t?= =?UTF-8?q?raceId=EB=A5=BC=20=EC=8B=A3=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: readFailureEnvelope는 실패 Envelope의 meta.traceId를 함께 돌려주고, V3 실행기는 그 값을 AppFailure.traceId로 싣는다(1103/03-06). Fileserver client는 envelope.value만 넘겨 traceId를 버린다. 지원 담당이 업로드 실패를 서버 로그의 요청과 잇지 못한다. 같은 백엔드의 다른 쓰기 실패는 이을 수 있다. 고른 방법: envelopeFailure가 읽은 Envelope 전체를 받아 traceId가 있으면 createFailure의 traceId로 싣는다. V3와 같은 규칙이다. 없으면 키를 두지 않는다. 매뉴얼 7절 결과 읽기에 한 줄 적었다. 위험·한계: Envelope 실패에만 싣는다. 성공 Envelope을 읽지 못한 실패 (SCHEMA_MISMATCH 등, 202 REJECTED 포함)는 readSuccessEnvelope가 meta를 돌려주지 않아 traceId가 없다. V3도 같다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts RED(이 커밋의 테스트 + 부모 src): Envelope failures 표 17행이 traceId "trace-1"이 없어 모두 실패한다. Refs: 1105/01-03 --- docs/manual/02-decision-tables.md | 1 + src/adapters/http/fileserver-upload.ts | 8 ++++++-- tests/integration/fileserver-upload.test.ts | 15 +++++++++++++++ 3 files changed, 22 insertions(+), 2 deletions(-) diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index 77f5d1ad..3571f427 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -321,6 +321,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 실행기와 같다. 지원 담당이 서버 로그에서 그 요청을 찾을 때 쓴다. - client는 스스로 다시 보내지 않는다. `retryable: true`이고 `retryAfterMs`가 있으면 그만큼 기다린 뒤 기능이 다시 부른다. 서버가 상한(`maxRetryAfterMs`, 기본 30초)보다 길게 기다리라고 하면 `retryable: false`다. - `MAYBE_APPLIED`는 언제나 `retryable: false`다. 백엔드가 Envelope에 `retryable: true`와 `Retry-After`를 붙여도(504 `TRANSFER_TIMEOUT`) 기능이 자동으로 다시 부르지 않는다. 아래 주의대로 먼저 확인한다. diff --git a/src/adapters/http/fileserver-upload.ts b/src/adapters/http/fileserver-upload.ts index 2ef5465c..736392ed 100644 --- a/src/adapters/http/fileserver-upload.ts +++ b/src/adapters/http/fileserver-upload.ts @@ -695,15 +695,16 @@ async function readAnswer( if (status < 400) return unreadable("ENVELOPE_MISMATCH", "STATUS_UNEXPECTED"); const envelope = readFailureEnvelope(json); if (!envelope.ok) return unreadable("ENVELOPE_MISMATCH", "ENVELOPE_INVALID"); - return envelopeFailure(status, envelope.value, response, settings); + return envelopeFailure(status, envelope, response, settings); } function envelopeFailure( status: number, - error: EnvelopeError, + envelope: Readonly<{ value: EnvelopeError; traceId?: string }>, response: Response, settings: Settings, ): Result { + const error = envelope.value; const effect = fileserverFailureEffect(status, error); const retryAfterMs = parseRetryAfterDelay( response.headers.get("retry-after"), @@ -731,6 +732,9 @@ function envelopeFailure( ...(reading.validationIssues === undefined ? {} : { validationIssues: reading.validationIssues }), + // 1105/01-03. The backend's `meta.traceId`, as the V3 executor carries it + // (1103/03-06), so support can find this upload in the server logs. + ...(envelope.traceId === undefined ? {} : { traceId: envelope.traceId }), }); // `retryable` in the Envelope is the server's decision for this answer and // can only narrow the client's. diff --git a/tests/integration/fileserver-upload.test.ts b/tests/integration/fileserver-upload.test.ts index c8f9aa86..41595697 100644 --- a/tests/integration/fileserver-upload.test.ts +++ b/tests/integration/fileserver-upload.test.ts @@ -397,11 +397,26 @@ describe("Fileserver multipart upload — Envelope failures", () => { effect, retryable: clientRetryable, operationId: "FILESERVER_UPLOAD", + // 1105/01-03. The Envelope's meta.traceId, as V3 carries it. + traceId: META.traceId, }, }); }, ); + it("carries no traceId when the failure Envelope has none", async () => { + const envelope = failureEnvelope("STORAGE_UNAVAILABLE", "TRANSIENT_DEPENDENCY", true); + answer({ + status: 503, + body: { success: envelope.success, error: envelope.error, meta: { requestId: "req-1" } }, + }); + + const result = await client().client.upload(upload()); + + expect(result.ok).toBe(false); + expect(result.ok ? undefined : Object.hasOwn(result.error, "traceId")).toBe(false); + }); + it("409 IDEMPOTENT_IN_FLIGHT keeps the server's wait and asks for the same key", async () => { const captured = answer( {