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:
co-authored by
Claude Opus 5.5
parent
9894a70f04
commit
c5da3cf001
@@ -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.
|
||||
|
||||
@@ -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),
|
||||
});
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user