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
+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 {