fix(http): 실패 Envelope의 meta.traceId를 AppFailure.traceId로 싣는다

문제
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
This commit is contained in:
DongHyeonka
2026-11-04 20:49:30 +09:00
parent 49a09868ad
commit 631ce339b9
5 changed files with 63 additions and 14 deletions
@@ -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
+14 -5
View File
@@ -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<EnvelopeError> {
):
| 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 }),
});
}
/**
+10 -6
View File
@@ -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<WireOutput, Problem, Value>(
operationId: string,
@@ -373,15 +374,18 @@ function projectExecutionOutcome<WireOutput, Problem, Value>(
outcome: HttpExecutionOutcome<WireOutput, Problem>,
): Result<Value, AppFailure> {
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 }),
}),
});
}
+14 -2
View File
@@ -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<Input, WireOutput, Problem>(
// 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<Problem>;
let problemMetadata = metadata;
let backendEffect: "NOT_APPLIED" | "MAYBE_APPLIED" | undefined;
let refusalReason: IdempotencyRefusalReason | undefined;
let keyedResend = false;
@@ -1702,6 +1708,12 @@ async function admitProblem<Input, WireOutput, Problem>(
? 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<Input, WireOutput, Problem>(
: "PROBLEM_SCHEMA_INVALID",
"VALIDATION",
postDispatchEffect(isCommand),
metadata,
problemMetadata,
),
certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED",
retryHint: retryable,
@@ -1752,7 +1764,7 @@ async function admitProblem<Input, WireOutput, Problem>(
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",
@@ -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)],