fix(http): send a request id and carry the server correlation id to failures (03-03)

V3 read the response x-correlation-id and dropped it, and untraced requests
sent no id, so a support reference could not be matched to a server log.
Each logical execution now sends one x-correlation-id; failures carry the
echoed value as requestId and diagnostics record it as correlation_id.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 22:27:42 +09:00
co-authored by Claude Opus 5.5
parent 9894a70f04
commit c5da3cf001
6 changed files with 189 additions and 2 deletions
@@ -168,6 +168,14 @@ target 점검:
3. cross-origin allow-origin/credentials/method/header/expose가 exact한지 확인한다.
4. wildcard credential, redirect와 unexpected origin을 복구한다.
5. CSRF token/header 값을 ticket에 기록하지 않는다.
6. V3 요청은 논리 실행마다 `x-correlation-id` 하나를 보낸다(재시도도 같은 값,
`src/adapters/http/http-execution-v3.ts` `createRequestId`). cross-origin API면
preflight `Access-Control-Allow-Headers`에 `x-correlation-id`가 있어야 요청이
나간다. 응답의 `x-correlation-id`를 `AppFailure.requestId`와 diagnostics
`correlation_id`로 쓰려면 `Access-Control-Expose-Headers`에도 넣는다
(`src/adapters/http/feature-http-binding.ts` `projectExecutionOutcome`,
`src/bootstrap/runtime-adapters.ts` `createHttpObservationProjector`). telemetry에는
넣지 않는다.
## 6. REST incident
+28
View File
@@ -284,6 +284,10 @@ export function createFeatureHttpBinding<
});
}
/**
* 03-03. A failure carries the server's echoed correlation id as `requestId`,
* so the support reference a user reports points at one server log entry.
*/
function projectExecutionOutcome<WireOutput, Problem, Value>(
operationId: string,
mapSuccess: (value: WireOutput) => MappingResult<Value>,
@@ -294,6 +298,30 @@ function projectExecutionOutcome<WireOutput, Problem, Value>(
) => FeatureHttpProblemMapping | undefined)
| undefined,
outcome: HttpExecutionOutcome<WireOutput, Problem>,
): Result<Value, ApiFailure> {
const projected = projectOutcome(operationId, mapSuccess, mapProblem, outcome);
const requestId =
"metadata" in outcome
? outcome.metadata?.correlationReference
: undefined;
return projected.ok || requestId === undefined
? projected
: Object.freeze({
ok: false as const,
error: Object.freeze({ ...projected.error, requestId }),
});
}
function projectOutcome<WireOutput, Problem, Value>(
operationId: string,
mapSuccess: (value: WireOutput) => MappingResult<Value>,
mapProblem:
| ((
problem: Problem,
metadata: SafeResponseMetadata,
) => FeatureHttpProblemMapping | undefined)
| undefined,
outcome: HttpExecutionOutcome<WireOutput, Problem>,
): Result<Value, ApiFailure> {
// A throwing feature mapper is a mapping defect, not a transport failure: it
// must not reject and lose the effect the server already confirmed.
+37 -2
View File
@@ -53,7 +53,10 @@ import {
} from "../../platform/traffic/concurrency-budget.ts";
import type { TrafficBudget } from "../../platform/traffic/traffic-budget.ts";
import { checkJsonStructure } from "../../platform/validation/bounded-json.ts";
import { buildTraceHeaders } from "../../platform/telemetry/trace-context.ts";
import {
buildTraceHeaders,
CORRELATION_ID_HEADER,
} from "../../platform/telemetry/trace-context.ts";
import { responseValidationBudget } from "../../platform/validation/validation-budget.ts";
import {
canRetryTransport,
@@ -144,11 +147,13 @@ export type HttpExecutionOutcome<Value, Problem> =
}>
| Readonly<{
kind: "FORBIDDEN";
metadata?: SafeResponseMetadata;
effect: "NOT_APPLICABLE" | "NOT_APPLIED" | "MAYBE_APPLIED";
}>
| Readonly<{
kind: "RATE_LIMITED";
retryAfterMs?: number;
metadata?: SafeResponseMetadata;
effect: "NOT_APPLICABLE" | "NOT_APPLIED" | "MAYBE_APPLIED";
}>
| Readonly<{
@@ -267,6 +272,11 @@ export type HttpExecutionObservation = Readonly<{
durationMs: number;
effect: HttpEffectCertainty;
cancellationOwner?: CancellationOwner;
/**
* 03-03. The server's echoed `x-correlation-id`, else the request id this
* execution sent. Diagnostics only; never telemetry.
*/
correlationId?: string;
/**
* The internal terminal-reason label recorded by the execution site. It is
* evidence for the HTTP scenario catalog only; the composition-root
@@ -314,6 +324,14 @@ function observationStatus(
return "metadata" in outcome ? outcome.metadata?.status : undefined;
}
function responseCorrelation(
outcome: HttpExecutionOutcome<unknown, unknown>,
): string | undefined {
return "metadata" in outcome
? outcome.metadata?.correlationReference
: undefined;
}
export type ContractHttpExecutorDependencies = Readonly<{
baseUrl: string;
/** §8.2. `MAX_RETRY_ATTEMPTS` from Runtime Config; the ceiling is still 2. */
@@ -345,6 +363,8 @@ export type ContractHttpExecutorDependencies = Readonly<{
monotonicNow?: () => number;
sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
random?: () => number;
/** 03-03. One id per logical execution, sent as `x-correlation-id`. */
createRequestId?: () => string;
observe?: (observation: HttpExecutionObservation) => void;
}>;
@@ -425,6 +445,8 @@ export function createContractHttpExecutor(
dependencies.readBoundedResponseBytes ?? readBoundedBytes;
const now = dependencies.monotonicNow ?? (() => performance.now());
const random = dependencies.random ?? Math.random;
const createRequestId =
dependencies.createRequestId ?? (() => globalThis.crypto.randomUUID());
const deadlineCeilingMs = dependencies.requestDeadlineCeilingMs;
const effectiveDeadlineMs = (contractDeadlineMs: number): number =>
typeof deadlineCeilingMs === "number" &&
@@ -564,6 +586,7 @@ export function createContractHttpExecutor(
lifetimeController.abort();
};
let sentRequestId: string | undefined;
const finish = (
outcome: HttpExecutionOutcome<WireOutput, Problem>,
terminalReason: string,
@@ -571,6 +594,7 @@ export function createContractHttpExecutor(
disposeLifetime();
try {
const status = observationStatus(outcome);
const correlationId = responseCorrelation(outcome) ?? sentRequestId;
dependencies.observe?.(
Object.freeze({
routeId: context.routeId,
@@ -586,6 +610,7 @@ export function createContractHttpExecutor(
...(terminalCancellation === null
? {}
: { cancellationOwner: terminalCancellation }),
...(correlationId === undefined ? {} : { correlationId }),
}),
);
} catch {
@@ -789,6 +814,10 @@ export function createContractHttpExecutor(
if (context.execution?.trace !== undefined) {
Object.assign(headers, buildTraceHeaders(context.execution));
}
// 03-03. Every other logical execution still sends its own request id,
// shared by its retries, so a failure can be found in the server log.
headers[CORRELATION_ID_HEADER] ??= createRequestId();
sentRequestId = headers[CORRELATION_ID_HEADER];
const retryCeiling = Math.min(
policy.retryBudget,
@@ -1160,7 +1189,10 @@ async function admitResponse<Input, WireOutput, Problem>(
}
if (status === 403) {
await response.body?.cancel().catch(() => {});
return settled(forbidden(statusEffect(403), isCommand), "FORBIDDEN");
return settled(
forbidden(statusEffect(403), isCommand, metadata),
"FORBIDDEN",
);
}
if (status === 429) {
await response.body?.cancel().catch(() => {});
@@ -1168,6 +1200,7 @@ async function admitResponse<Input, WireOutput, Problem>(
result: Object.freeze({
kind: "RATE_LIMITED" as const,
...(retryAfterMs === null ? {} : { retryAfterMs }),
metadata,
effect: normalizeOptionalEffect(statusEffect(429), isCommand),
}),
certainty: "RATE_LIMITED",
@@ -1661,9 +1694,11 @@ function unauthenticated<Value, Problem>(
function forbidden<Value, Problem>(
effect: string,
isCommand: boolean,
metadata: SafeResponseMetadata,
): HttpExecutionOutcome<Value, Problem> {
return Object.freeze({
kind: "FORBIDDEN" as const,
metadata,
effect: normalizeOptionalEffect(effect, isCommand),
});
}
+4
View File
@@ -246,6 +246,10 @@ export function createHttpObservationProjector(
...safeAttributes,
operation: observation.diagnosticsOperation,
outcome: observation.outcome,
// 03-03. Request-scoped: diagnostics may carry it, telemetry never.
...(observation.correlationId === undefined
? {}
: { correlation_id: observation.correlationId }),
},
});
} catch {
@@ -182,6 +182,34 @@ describe("V3 HTTP observability projection", () => {
expect(sinks.diagnostics).toHaveLength(1);
});
it("records the correlation id in diagnostics only (03-03)", async () => {
const sinks = recordingSinks();
const executor = createContractHttpExecutor({
baseUrl: "https://api.example/",
maxRetryAttempts: 0,
attachCredentials: () => ({ kind: "READY" as const, headers: {} }),
fetcher: (async () =>
new Response(null, {
status: 503,
headers: { "x-correlation-id": "server-ref-7" },
})) as unknown as typeof fetch,
observe: sinks.projector,
});
await executor.execute(
TEST_LIST_HTTP_CONTRACT,
{ limit: 5 },
{ routeId: ROUTE_ID, scope: scopeSnapshot() },
);
expect(sinks.diagnostics[0]?.context).toMatchObject({
correlation_id: "server-ref-7",
});
expect(projectDiagnosticRecord(sinks.diagnostics[0]!).success).toBe(true);
expect(sinks.telemetry).toHaveLength(1);
expect(JSON.stringify(sinks.telemetry)).not.toContain("server-ref-7");
});
it("does not emit failure telemetry for caller cancellation or scope fencing", async () => {
const cancelled = recordingSinks();
const callerController = new AbortController();
+84
View File
@@ -992,6 +992,90 @@ describe("terminal owner classification at every wait", () => {
);
});
/**
* 03-03. A support reference must reach the server log: every logical
* execution sends one request id, and a failure carries the server's echoed
* `x-correlation-id` as `requestId`.
*/
describe("request correlation", () => {
it("sends one request id per logical execution, shared by its retries", async () => {
const sent: (string | null)[] = [];
const fetcher = vi.fn<typeof fetch>(async (_input, init) => {
sent.push(new Headers(init?.headers).get("x-correlation-id"));
return sent.length === 1
? new Response(null, { status: 503 })
: Response.json([{ id: "a", name: "A" }]);
});
const executor = createContractHttpExecutor({
baseUrl: "https://api.example/",
maxRetryAttempts: 2,
attachCredentials: () => ({ kind: "READY", headers: {} }),
fetcher,
sleep: async () => {},
random: () => 0,
});
const retried = {
...installed,
frontend: { ...installed.frontend, retryBudget: 1 as const },
};
await executor.execute(retried, { limit: 20 }, { routeId: ROUTE_ID, scope });
await executor.execute(retried, { limit: 20 }, { routeId: ROUTE_ID, scope });
expect(sent).toHaveLength(3);
expect(sent[0]).toMatch(/^[A-Za-z0-9._:-]{1,128}$/u);
expect(sent[1]).toBe(sent[0]);
expect(sent[2]).not.toBe(sent[0]);
});
it.each([
["a problem", 400, { type: "about:blank", title: "rejected", status: 400 }],
["an unauthenticated answer", 401, null],
["a forbidden answer", 403, null],
["a rate limit", 429, null],
["a gateway outage", 504, null],
] as const)("carries the server correlation id on %s", async (_label, status, body) => {
const observations: HttpExecutionObservation[] = [];
const executor = createContractHttpExecutor({
baseUrl: "https://api.example/",
maxRetryAttempts: 0,
attachCredentials: () => ({ kind: "READY", headers: {} }),
fetcher: vi.fn(async () =>
body === null
? new Response(null, {
status,
headers: { "x-correlation-id": "server-ref-42" },
})
: Response.json(body, {
status,
headers: { "x-correlation-id": "server-ref-42" },
}),
),
observe: (observation) => observations.push(observation),
});
const list = defineFeatureHttpOperation({
contract: TEST_LIST_HTTP_CONTRACT,
routeId: ROUTE_ID,
mapSuccess: (value) => mappingSuccess(value),
});
const binding = createFeatureHttpBinding(
{
execute: (contract, input, context) =>
executor.execute(contract, input, { ...context, scope }),
},
{ [list.operationId]: list },
);
const result = await binding.execute(list.operationId, { limit: 20 });
expect(result).toMatchObject({
ok: false,
error: { requestId: "server-ref-42" },
});
expect(observations.at(-1)?.correlationId).toBe("server-ref-42");
});
});
/**
* D-2 (03-02). 401, 403 and 429 are admitted before any problem body is read.
* The package may classify them by status; without a classifier, or when it