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)],