Files
clean-architecture-frontend…/tests/integration/http-execution-v3-observability.test.ts
T
DongHyeonka 5d0f8454c6 test(http): Envelope 판정 경계와 처리 중 409 무재전송을 고정한다
문제
Envelope 실패 판정 표(backend-envelope.ts)와 실행기의 실패 Envelope
처리는 커버리지가 100%인데 경계 다섯 곳이 테스트에 걸리지 않는다. 표의
code를 다른 status로 보내는 행, 표 밖 422, 게이트웨이 408·425, 응답
한도보다 크고 64 KiB보다 작은 실패 본문, JSON이 아닌 실패 본문이 없다.
그래서 변이 H14(=M6, status 대조 제거)·H45(표 밖 422를 분류기로)·H15
(408·425 제거)·H23(실패 한도를 64 KiB 고정)·H10b(실패 media type 검사
제거)가 살아남았다. 처리 중 409를 자동 재전송하게 바꾼 변이 M7도
살아남았다. Envelope 표 테스트는 재시도 예산이 0이라 재전송을 볼 수
없었다. 같은 문서의 이월 항목 둘도 그대로다. 결과 불명 동안 입력
identity를 잡는 네 줄(M1, 0929/03-06)과 반사 correlation 문법 검사(M3,
1101/03-06)를 지워도 테스트가 통과한다.

고른 방법
- tests/unit/backend-envelope.test.ts: envelopeFailureEffect·
  idempotencyRefusalReason·envelopeFailureReading을 status × code 표로
  직접 부른다.
- envelope 통합 테스트: LENIENT 묶음에 422 INTEGRITY_MISMATCH 한 행,
  한도를 넘는 실패 Envelope와 text/plain 실패 본문(네이티브 Response),
  retryBudget 1인 KEYED가 409 IDEMPOTENT_IN_FLIGHT에 한 번만 보내는 행.
- 결과 불명 입력이 두 칸짜리 identity 레지스트리에서 밀려나지 않는지,
  문법 밖 반사 id가 보낸 id로 바뀌는지를 각각 한 건씩 더한다.

위험·한계
테스트만 더했다. 동작은 바꾸지 않았다.

검증
- 변이 8종(H14·H45·H15·H23·H10b·M7·M1·M3)을 하나씩 넣고 관련 테스트를
  돌렸다. 모두 새 테스트에서 실패하고, 되돌리면 통과한다.
- check:types, lint 통과. 바뀐 4파일 83건 통과.

Refs: docs/reviews/2026-11-03-maturity-review/10-tests-fast-layers.md 10-02
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-08
2026-11-04 20:24:09 +09:00

562 lines
18 KiB
TypeScript

import { describe, expect, it, vi } from "vitest";
import { createContractHttpExecutor } from "../../src/adapters/http/http-execution-v3.ts";
import type {
HttpExecutionObservation,
} from "../../src/adapters/http/http-execution-v3.ts";
import { createHttpObservationProjector } from "../../src/bootstrap/runtime-adapters.ts";
import {
DIAGNOSTIC_CONTEXT_ALLOWLIST,
projectDiagnosticRecord,
type DiagnosticRecordInput,
} from "../../src/contracts/diagnostics.ts";
import {
projectTelemetryEvent,
type TelemetryEventName,
} from "../../src/contracts/telemetry.ts";
import {
TEST_CREATE_HTTP_CONTRACT,
TEST_LIST_HTTP_CONTRACT,
} from "../helpers/external-contract-fixture.ts";
const ROUTE_ID = "TEST_ROUTE";
function scopeSnapshot(isCurrent: () => boolean = () => true) {
return Object.freeze({
generation: 1,
fingerprint: "scope-1",
identities: Object.freeze({}) as never,
signal: new AbortController().signal,
isCurrent,
});
}
type RecordedDiagnostic = DiagnosticRecordInput;
type RecordedTelemetry = Readonly<{
eventName: TelemetryEventName;
attributes: Readonly<Record<string, unknown>>;
}>;
function recordingSinks() {
const diagnostics: RecordedDiagnostic[] = [];
const telemetry: RecordedTelemetry[] = [];
return {
diagnostics,
telemetry,
projector: createHttpObservationProjector({
diagnostics: {
record(input: DiagnosticRecordInput) {
diagnostics.push(input);
},
},
telemetry: {
emit(
eventName: TelemetryEventName,
attributes: Record<string, unknown>,
) {
telemetry.push(Object.freeze({ eventName, attributes }));
},
},
}),
};
}
describe("V3 HTTP observability projection", () => {
it("projects every V3 terminal outcome through the closed diagnostics allowlist", async () => {
const sinks = recordingSinks();
const cases: readonly Readonly<{
label: string;
fetcher: typeof fetch;
}>[] = [
{
label: "SUCCESS",
fetcher: (async () =>
Response.json([{ id: "a", name: "A" }])) as unknown as typeof fetch,
},
{
label: "PROBLEM",
fetcher: (async () =>
Response.json(
{ type: "about:blank", title: "nope", status: 400 },
{ status: 400 },
)) as unknown as typeof fetch,
},
{
label: "TRANSPORT_FAILURE",
fetcher: (async () => {
throw new TypeError("network down");
}) as unknown as typeof fetch,
},
{
label: "CONTRACT_VIOLATION",
fetcher: (async () =>
new Response("<html/>", {
status: 200,
headers: { "content-type": "text/html" },
})) as unknown as typeof fetch,
},
];
for (const testCase of cases) {
const executor = createContractHttpExecutor({
baseUrl: "https://api.example/",
maxRetryAttempts: 0,
attachCredentials: () => ({
kind: "READY" as const,
headers: {},
}),
fetcher: testCase.fetcher,
observe: sinks.projector,
});
await executor.execute(
TEST_LIST_HTTP_CONTRACT,
{ limit: 5 },
{ routeId: ROUTE_ID, scope: scopeSnapshot() },
);
}
expect(sinks.diagnostics).toHaveLength(cases.length);
for (const recorded of sinks.diagnostics) {
expect(recorded.eventId).toBe("http.request.completed");
const contextKeys = Object.keys(recorded.context ?? {});
expect(contextKeys).toEqual(
expect.arrayContaining([
"route_id",
"operation_id",
"operation",
"outcome",
"error_kind",
"http_status_group",
"attempt_count_bucket",
"duration_bucket",
]),
);
for (const key of contextKeys) {
expect(DIAGNOSTIC_CONTEXT_ALLOWLIST).toContain(key);
}
expect(contextKeys).not.toContain("attempts");
expect(contextKeys).not.toContain("certainty");
const projection = projectDiagnosticRecord(recorded);
expect(projection.success).toBe(true);
}
});
it("emits one failure telemetry event for a non-abort terminal failure", async () => {
const sinks = recordingSinks();
const executor = createContractHttpExecutor({
baseUrl: "https://api.example/",
maxRetryAttempts: 0,
attachCredentials: () => ({
kind: "READY" as const,
headers: {},
}),
fetcher: (async () => {
throw new TypeError("network down");
}) as unknown as typeof fetch,
observe: sinks.projector,
});
const outcome = await executor.execute(
TEST_LIST_HTTP_CONTRACT,
{ limit: 5 },
{ routeId: ROUTE_ID, scope: scopeSnapshot() },
);
expect(outcome.kind).toBe("TRANSPORT_FAILURE");
expect(sinks.telemetry).toHaveLength(1);
const emitted = sinks.telemetry[0];
expect(emitted?.eventName).toBe("api.request.failed");
expect(emitted?.attributes).toMatchObject({
route_id: ROUTE_ID,
operation_id: "TEST_LIST_ENTITIES",
error_kind: "NETWORK_FAILURE",
http_status_group: "none",
attempt_count_bucket: "1",
});
const projected = projectTelemetryEvent(
emitted?.eventName ?? "api.request.failed",
emitted?.attributes ?? {},
);
expect(projected.success).toBe(true);
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");
});
// 1101/03-06. A reflected id outside the request id grammar (a proxy's
// text, an overlong value) is not what the server logged: the sent id
// stands in for it, in the outcome and in diagnostics.
it.each([
["a value with spaces and markup", "<b>proxy ref</b>"],
["an overlong value", "r".repeat(129)],
])("drops a reflected correlation id that is %s", async (_label, reflected) => {
const sinks = recordingSinks();
const outcome = await createContractHttpExecutor({
baseUrl: "https://api.example/",
maxRetryAttempts: 0,
attachCredentials: () => ({ kind: "READY" as const, headers: {} }),
createRequestId: () => "sent-request-1",
fetcher: (async () =>
new Response(null, {
status: 503,
headers: { "x-correlation-id": reflected },
})) as unknown as typeof fetch,
observe: sinks.projector,
}).execute(
TEST_LIST_HTTP_CONTRACT,
{ limit: 5 },
{ routeId: ROUTE_ID, scope: scopeSnapshot() },
);
expect("metadata" in outcome ? outcome.metadata : undefined).not.toHaveProperty(
"correlationReference",
);
expect(outcome.sentRequestId).toBe("sent-request-1");
expect(sinks.diagnostics[0]?.context).toMatchObject({
correlation_id: "sent-request-1",
});
expect(JSON.stringify(sinks.diagnostics)).not.toContain(reflected);
});
/**
* 03-05. A package problem classifier that throws, or answers outside the
* closed set, fails safe to MAYBE_APPLIED. Diagnostics must still tell that
* apart from a classifier that really answered MAYBE_APPLIED; telemetry stays
* on `error_kind` alone.
*/
it("keeps MAYBE_APPLIED and records a failed problem classifier in diagnostics only (03-05)", async () => {
async function runWithClassifier(classifyProblem: () => unknown) {
const sinks = recordingSinks();
const contract = {
...TEST_CREATE_HTTP_CONTRACT,
contract: {
...TEST_CREATE_HTTP_CONTRACT.contract,
commandEffect: {
...TEST_CREATE_HTTP_CONTRACT.contract.commandEffect!,
classifyProblem,
} as NonNullable<
typeof TEST_CREATE_HTTP_CONTRACT.contract.commandEffect
>,
},
};
const outcome = await createContractHttpExecutor({
baseUrl: "https://api.example/",
maxRetryAttempts: 0,
attachCredentials: () => ({ kind: "READY" as const, headers: {} }),
fetcher: (async () =>
Response.json(
{ type: "about:blank", title: "conflict", status: 409 },
{ status: 409 },
)) as unknown as typeof fetch,
observe: sinks.projector,
}).execute(
contract,
{ name: "Created" },
{
routeId: ROUTE_ID,
scope: scopeSnapshot(),
intent: Object.freeze({
intentId: "intent-1",
operationId: "TEST_CREATE_ENTITY",
canonicalInputIdentity: "opaque-input-identity",
idempotencyKey: "key-1",
createdAtMonotonicMs: 1,
}),
},
);
expect(sinks.diagnostics).toHaveLength(1);
expect(projectDiagnosticRecord(sinks.diagnostics[0]!).success).toBe(true);
expect(sinks.telemetry).toHaveLength(1);
return {
kind: outcome.kind,
effect: outcome.effect,
reason: sinks.diagnostics[0]?.context?.reason,
telemetryKeys: Object.keys(sinks.telemetry[0]?.attributes ?? {}),
};
}
const answered = await runWithClassifier(() => "MAYBE_APPLIED");
const thrown = await runWithClassifier(() => {
throw new Error("package classifier defect");
});
const unknownAnswer = await runWithClassifier(() => "NOT_STARTED");
expect(answered).toMatchObject({
kind: "PROBLEM",
effect: "MAYBE_APPLIED",
reason: undefined,
});
for (const failed of [thrown, unknownAnswer]) {
expect(failed).toMatchObject({
kind: "PROBLEM",
effect: "MAYBE_APPLIED",
reason: "CLASSIFIER_FAILED",
});
expect(failed.telemetryKeys).toEqual(answered.telemetryKeys);
}
});
/**
* 03-02 (E6c). A path template and a `projectRequest` that disagree are
* refused before dispatch. The cause reaches diagnostics, not telemetry.
*/
it("names a refused request's assembly cause in diagnostics only (03-02)", async () => {
const sinks = recordingSinks();
const fetcher = vi.fn();
const mismatched = {
...TEST_LIST_HTTP_CONTRACT,
contract: {
...TEST_LIST_HTTP_CONTRACT.contract,
pathTemplate: "/api/test-entities/{id}",
projectRequest: () =>
Object.freeze({
pathValues: Object.freeze({ entityId: "entity-1" }),
queryEntries: Object.freeze([]),
body: null,
}),
},
};
const outcome = await createContractHttpExecutor({
baseUrl: "https://api.example/",
maxRetryAttempts: 0,
attachCredentials: () => ({ kind: "READY" as const, headers: {} }),
fetcher: fetcher as unknown as typeof fetch,
observe: sinks.projector,
}).execute(
mismatched,
{ limit: 5 },
{ routeId: ROUTE_ID, scope: scopeSnapshot() },
);
expect(fetcher).not.toHaveBeenCalled();
expect(outcome).toMatchObject({
kind: "CONTRACT_VIOLATION",
effect: "NOT_APPLICABLE",
violation: {
kind: "FINAL_REQUEST_INVARIANT_FAILED",
reason: "PATH_PLACEHOLDER_MISSING",
},
});
expect(sinks.diagnostics).toHaveLength(1);
expect(sinks.diagnostics[0]?.context).toMatchObject({
error_kind: "FINAL_REQUEST_INVARIANT_FAILED",
reason: "PATH_PLACEHOLDER_MISSING",
});
expect(projectDiagnosticRecord(sinks.diagnostics[0]!).success).toBe(true);
expect(JSON.stringify(sinks.telemetry)).not.toContain(
"PATH_PLACEHOLDER_MISSING",
);
});
/**
* 03-02 / P-03-05 (E3). The deadline can run out between the attempt's
* budget read and the final invariant check. Nothing was sent and nothing is
* wrong with the request: it is a timeout, like the budget read itself.
*/
it("ends a deadline that expires at the final invariant check as a timeout (P-03-05)", async () => {
let clockReads = 0;
let jumpAtRead = Number.POSITIVE_INFINITY;
const monotonicNow = () => {
clockReads += 1;
return clockReads >= jumpAtRead ? 1_000_000 : 0;
};
const run = (fetcher: typeof fetch) =>
createContractHttpExecutor({
baseUrl: "https://api.example/",
maxRetryAttempts: 0,
attachCredentials: () => ({ kind: "READY" as const, headers: {} }),
fetcher,
monotonicNow,
}).execute(
TEST_LIST_HTTP_CONTRACT,
{ limit: 5 },
{ routeId: ROUTE_ID, scope: scopeSnapshot() },
);
// Probe: the last clock read before fetch is the final invariant check's
// deadline read, because nothing else reads the clock in between.
let readsBeforeFetch = 0;
await run((async () => {
readsBeforeFetch = clockReads;
return Response.json([]);
}) as unknown as typeof fetch);
clockReads = 0;
jumpAtRead = readsBeforeFetch;
const fetcher = vi.fn();
const outcome = await run(fetcher as unknown as typeof fetch);
expect(fetcher).not.toHaveBeenCalled();
expect(outcome).toMatchObject({
kind: "TRANSPORT_FAILURE",
failure: { kind: "TIMEOUT" },
});
});
it("keeps a never-sent unauthenticated request out of telemetry (03-07)", async () => {
const sinks = recordingSinks();
const fetcher = vi.fn();
const executor = createContractHttpExecutor({
baseUrl: "https://api.example/",
maxRetryAttempts: 0,
attachCredentials: () => ({ kind: "UNAUTHENTICATED" as const }),
fetcher: fetcher as unknown as typeof fetch,
observe: sinks.projector,
});
const outcome = await executor.execute(
TEST_LIST_HTTP_CONTRACT,
{ limit: 5 },
{ routeId: ROUTE_ID, scope: scopeSnapshot() },
);
expect(outcome.kind).toBe("UNAUTHENTICATED");
expect(fetcher).not.toHaveBeenCalled();
expect(sinks.diagnostics).toHaveLength(1);
expect(sinks.telemetry).toHaveLength(0);
// A server 401 is still an API failure.
const answered = recordingSinks();
await createContractHttpExecutor({
baseUrl: "https://api.example/",
maxRetryAttempts: 0,
attachCredentials: () => ({ kind: "READY" as const, headers: {} }),
fetcher: (async () => new Response(null, { status: 401 })) as unknown as typeof fetch,
observe: answered.projector,
}).execute(
TEST_LIST_HTTP_CONTRACT,
{ limit: 5 },
{ routeId: ROUTE_ID, scope: scopeSnapshot() },
);
expect(answered.telemetry).toHaveLength(1);
});
it("does not emit failure telemetry for caller cancellation or scope fencing", async () => {
const cancelled = recordingSinks();
const callerController = new AbortController();
callerController.abort();
const cancelledExecutor = createContractHttpExecutor({
baseUrl: "https://api.example/",
maxRetryAttempts: 0,
attachCredentials: () => ({
kind: "READY" as const,
headers: {},
}),
fetcher: (async () =>
Response.json([{ id: "a", name: "A" }])) as unknown as typeof fetch,
observe: cancelled.projector,
});
const cancelledOutcome = await cancelledExecutor.execute(
TEST_LIST_HTTP_CONTRACT,
{ limit: 5 },
{
routeId: ROUTE_ID,
scope: scopeSnapshot(),
signal: callerController.signal,
},
);
expect(cancelledOutcome.kind).toBe("CANCELLED");
expect(cancelled.diagnostics).toHaveLength(1);
expect(cancelled.telemetry).toHaveLength(0);
const fenced = recordingSinks();
const fencedExecutor = createContractHttpExecutor({
baseUrl: "https://api.example/",
maxRetryAttempts: 0,
attachCredentials: () => ({
kind: "READY" as const,
headers: {},
}),
fetcher: (async () =>
Response.json([{ id: "a", name: "A" }])) as unknown as typeof fetch,
observe: fenced.projector,
});
const fencedOutcome = await fencedExecutor.execute(
TEST_LIST_HTTP_CONTRACT,
{ limit: 5 },
{ routeId: ROUTE_ID, scope: scopeSnapshot(() => false) },
);
expect(fencedOutcome.kind).toBe("CONTRACT_VIOLATION");
expect(fenced.diagnostics).toHaveLength(1);
expect(fenced.telemetry).toHaveLength(0);
});
it("cannot change the HTTP result when diagnostics or telemetry throws", async () => {
const projector = createHttpObservationProjector({
diagnostics: {
record() {
throw new Error("diagnostics sink exploded");
},
},
telemetry: {
emit() {
throw new Error("telemetry sink exploded");
},
},
});
const observe = vi.fn((observation: HttpExecutionObservation) => {
projector(observation);
});
const executor = createContractHttpExecutor({
baseUrl: "https://api.example/",
maxRetryAttempts: 0,
attachCredentials: () => ({
kind: "READY" as const,
headers: {},
}),
fetcher: (async () =>
Response.json({ id: "created", name: "Created" }, {
status: 201,
})) as unknown as typeof fetch,
observe,
});
const outcome = await executor.execute(
TEST_CREATE_HTTP_CONTRACT,
{ name: "Created" },
{
routeId: ROUTE_ID,
scope: scopeSnapshot(),
intent: Object.freeze({
intentId: "intent-1",
operationId: "TEST_CREATE_ENTITY",
canonicalInputIdentity: "opaque-input-identity",
idempotencyKey: "key-1",
createdAtMonotonicMs: 1,
}),
},
);
expect(outcome.kind).toBe("SUCCESS");
expect(observe).toHaveBeenCalledTimes(1);
});
});