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:
@@ -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
|
||||
|
||||
@@ -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 }),
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -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 }),
|
||||
}),
|
||||
});
|
||||
}
|
||||
|
||||
|
||||
@@ -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)],
|
||||
|
||||
Reference in New Issue
Block a user