From 631ce339b970c8a24f94a0de1fdd23a94487cede Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 20:49:30 +0900 Subject: [PATCH] =?UTF-8?q?fix(http):=20=EC=8B=A4=ED=8C=A8=20Envelope?= =?UTF-8?q?=EC=9D=98=20meta.traceId=EB=A5=BC=20AppFailure.traceId=EB=A1=9C?= =?UTF-8?q?=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 문제 AppFailure와 createFailure는 traceId를 받는다. 이를 채우던 곳은 V2 client.ts의 Envelope meta.traceId였고, 048f490이 V2를 지운 뒤 src에서 traceId를 넘기는 곳이 없다. 빈 칸을 믿고 만든 화면·진단 코드는 늘 undefined를 받는다. 짝 백엔드는 모든 실패 Envelope의 meta에 W3C trace id를 싣는다(http-contract.md §1). 고른 방법 - readFailureEnvelope가 error와 함께 meta.traceId를 돌려준다. 값은 이미 meta 스키마의 id 문법([A-Za-z0-9._:-]{1,128})을 통과한 것이다. - 실행기가 그 값을 PROBLEM 결과의 SafeResponseMetadata.traceReference에 싣고, 바인딩이 AppFailure.traceId로 옮긴다. requestId 경로(반사 헤더 → 보낸 id)는 그대로다. - 계약 문서 5절의 correlation 문단에 한 줄 더했다. 버린 대안 traceId를 타입에서 지우기(리뷰의 다른 선택지): 다운스트림이 쓰는지 확인이 필요하고, 백엔드가 이미 주는 지원용 id를 버린다. 위험·한계 - Envelope operation의 실패 응답만 채운다. 성공 뒤 매핑 실패, 전송 실패, Envelope 없는 operation은 traceId가 없다. - 텔레메트리에는 싣지 않는다(요청 단위 값). - 같은 발견의 VD-23 401 문장은 다른 작업 몫이라 건드리지 않았다. 검증 - RED: envelope 통합 1건 실패(404 실패의 traceId 없음). - GREEN: meta.traceId가 있으면 그 값, 없으면 칸 없음. tests/unit· integration·component·features·contract·runtime-schema 253파일 중 252파일 통과. 남은 1건(provider-guardian-transaction "cleans a linked raw inode")은 이 기계의 inotify 한도(ENOSPC watch)로 단독 실행에서도 실패하며 이 변경과 무관하다. - check:types, lint, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-06 --- .../backend-api-and-server-state-contract.md | 3 ++- src/adapters/http/backend-envelope.ts | 19 +++++++++++---- src/adapters/http/feature-http-binding.ts | 16 ++++++++----- src/adapters/http/http-execution-v3.ts | 16 +++++++++++-- .../http-execution-v3-envelope.test.ts | 23 +++++++++++++++++++ 5 files changed, 63 insertions(+), 14 deletions(-) diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index 4fabc602..00ba8467 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -238,7 +238,8 @@ Cross-origin bearer provider 최소 CORS: - 필요한 경우 `ETag`, `Retry-After`, request/trace header만 expose. `X-Correlation-ID`를 expose하면 V3 실패의 `AppFailure.requestId`가 된다 (`src/adapters/http/feature-http-binding.ts`). expose하지 않거나 응답이 없으면 - 클라이언트가 보낸 값이 된다 + 클라이언트가 보낸 값이 된다. Envelope operation의 실패 본문 `meta.traceId`는 + `AppFailure.traceId`가 된다(헤더가 아니라 본문이라 CORS expose와 상관없다) - redirect login page, HTML error body와 wildcard credential 금지 ## 6. Command와 idempotency diff --git a/src/adapters/http/backend-envelope.ts b/src/adapters/http/backend-envelope.ts index 894bfaba..10b55e55 100644 --- a/src/adapters/http/backend-envelope.ts +++ b/src/adapters/http/backend-envelope.ts @@ -115,14 +115,23 @@ export function readSuccessEnvelope( }); } -/** The failure `error` object, as the backend sent it. */ +/** + * The failure `error` object, as the backend sent it. + * 1103/03-06. With the backend's `meta.traceId`, when it sent one. + */ export function readFailureEnvelope( value: unknown, -): EnvelopeRead { +): + | Readonly<{ ok: true; value: EnvelopeError; traceId?: string }> + | Readonly<{ ok: false }> { const parsed = failureEnvelopeSchema.safeParse(value); - return parsed.success - ? Object.freeze({ ok: true as const, value: parsed.data.error }) - : ENVELOPE_INVALID; + if (!parsed.success) return ENVELOPE_INVALID; + const traceId = parsed.data.meta.traceId; + return Object.freeze({ + ok: true as const, + value: parsed.data.error, + ...(traceId === undefined ? {} : { traceId }), + }); } /** diff --git a/src/adapters/http/feature-http-binding.ts b/src/adapters/http/feature-http-binding.ts index 162c222b..f4370851 100644 --- a/src/adapters/http/feature-http-binding.ts +++ b/src/adapters/http/feature-http-binding.ts @@ -357,6 +357,7 @@ function envelopeProblemMapping( * so the support reference a user reports points at one server log entry. * 0929/03-04. Without an echo (timeout, lost connection, a gateway that drops * the header) it is the id the request carried. + * 1103/03-06. A failure Envelope's `meta.traceId` becomes `traceId`. */ function projectExecutionOutcome( operationId: string, @@ -373,15 +374,18 @@ function projectExecutionOutcome( outcome: HttpExecutionOutcome, ): Result { const projected = projectOutcome(operationId, mapSuccess, mapProblem, outcome); - const requestId = - ("metadata" in outcome - ? outcome.metadata?.correlationReference - : undefined) ?? outcome.sentRequestId; - return projected.ok || requestId === undefined + const metadata = "metadata" in outcome ? outcome.metadata : undefined; + const requestId = metadata?.correlationReference ?? outcome.sentRequestId; + const traceId = metadata?.traceReference; + return projected.ok || (requestId === undefined && traceId === undefined) ? projected : Object.freeze({ ok: false as const, - error: Object.freeze({ ...projected.error, requestId }), + error: Object.freeze({ + ...projected.error, + ...(requestId === undefined ? {} : { requestId }), + ...(traceId === undefined ? {} : { traceId }), + }), }); } diff --git a/src/adapters/http/http-execution-v3.ts b/src/adapters/http/http-execution-v3.ts index 89eccf06..1c5a0e3a 100644 --- a/src/adapters/http/http-execution-v3.ts +++ b/src/adapters/http/http-execution-v3.ts @@ -89,6 +89,11 @@ import { export type SafeResponseMetadata = Readonly<{ status: number; correlationReference?: string; + /** + * 1103/03-06. A failure Envelope's `meta.traceId`, already held to the + * request id grammar. The failure's `traceId`; never telemetry. + */ + traceReference?: string; retryAfterMs?: number; validatorToken?: string; }>; @@ -1693,6 +1698,7 @@ async function admitProblem( // 1101 README 14.3. An Envelope operation's problem is the `error` object. // A body that is not a failure Envelope is an unreadable problem. let validated: ValidatorInvocation; + let problemMetadata = metadata; let backendEffect: "NOT_APPLIED" | "MAYBE_APPLIED" | undefined; let refusalReason: IdempotencyRefusalReason | undefined; let keyedResend = false; @@ -1702,6 +1708,12 @@ async function admitProblem( ? invokeValidator(contract.problemValidator, framed.value) : UNFRAMED_PROBLEM; if (framed.ok) { + if (framed.traceId !== undefined) { + problemMetadata = Object.freeze({ + ...metadata, + traceReference: framed.traceId, + }); + } // 1103/03-01. The operation's own pre-write refusals join the table. backendEffect = envelopeFailureEffect( status, @@ -1725,7 +1737,7 @@ async function admitProblem( : "PROBLEM_SCHEMA_INVALID", "VALIDATION", postDispatchEffect(isCommand), - metadata, + problemMetadata, ), certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED", retryHint: retryable, @@ -1752,7 +1764,7 @@ async function admitProblem( result: Object.freeze({ kind: "PROBLEM" as const, problem: validated.value, - metadata, + metadata: problemMetadata, effect: (effect === "NOT_STARTED" ? "NOT_APPLIED" : effect) as "NOT_APPLIED" | "APPLIED_CONFIRMED" | "MAYBE_APPLIED", diff --git a/tests/integration/http-execution-v3-envelope.test.ts b/tests/integration/http-execution-v3-envelope.test.ts index d921c2b6..a747ee29 100644 --- a/tests/integration/http-execution-v3-envelope.test.ts +++ b/tests/integration/http-execution-v3-envelope.test.ts @@ -433,6 +433,29 @@ describe("V3 operation that reads the paired backend's Envelope", () => { expect(JSON.stringify(result)).not.toContain("서버가 보낸 문구"); }); + // 1103/03-06. The failure carries the backend's trace id, so support can + // find the server's trace from the failure a user reports. + it("carries the failure Envelope's meta.traceId on the failure", async () => { + answer("get", "/api/envelope-items", failure("NOT_FOUND", "NOT_FOUND", false), { + status: 404, + }); + await expect( + v3().execute("ENVELOPE_LIST_ITEMS", Object.freeze({})), + ).resolves.toMatchObject({ + ok: false, + error: { code: "NOT_FOUND", traceId: META.traceId }, + }); + + answer( + "get", + "/api/envelope-items", + { ...failure("NOT_FOUND", "NOT_FOUND", false), meta: {} }, + { status: 404 }, + ); + const untraced = await v3().execute("ENVELOPE_LIST_ITEMS", Object.freeze({})); + expect(untraced.ok ? undefined : untraced.error).not.toHaveProperty("traceId"); + }); + it.each([ ["a bare DTO", [{ id: "item-1", name: "First" }]], ["a failure Envelope", failure("NOT_FOUND", "NOT_FOUND", false)],