문제 기능 패키지의 classifyProblem이 throw하거나 집합 밖 값을 돌려주면 classifyProblemEffect는 MAYBE_APPLIED + contractRuntimeFailure: true를 돌려준다. 주석과 설계서(closed-deep-design.md:650)는 이것을 "contract runtime failure로 기록한다"고 적지만, 실행기는 .effect만 쓰고 플래그를 버린다. 그래서 분류기가 throw한 409와 분류기가 정말 MAYBE_APPLIED라고 답한 409의 관측 기록·진단이 요청 id 말고 똑같다. 또 이 안전 기본값을 NOT_APPLIED로 바꿔도(변이 M5) 영역 테스트가 하나도 실패하지 않는다. 고른 방법 - HttpExecutionObservation에 선택 필드 diagnosticReason을 더한다. 타입은 닫힌 집합 HttpDiagnosticReason이고 지금 값은 CLASSIFIER_FAILED 하나다. 문제 응답 admission이 명령의 contractRuntimeFailure를 이 값으로 바꾸고, finish()가 관측 기록에 싣는다. - 조립 지점의 projector는 이 값을 diagnostics에만 reason으로 더한다 (reason은 이미 허용 목록의 taxonomy 키). telemetry 속성은 그대로다. - 효과는 계속 MAYBE_APPLIED다. 재시도 판단에 쓰는 certainty는 건드리지 않았다. 버린 대안 - 리뷰 문서 문구대로 terminalReason을 CLASSIFIER_FAILED로 바꾸기: terminalReason은 "sink로 나가지 않는 내부 라벨"(VD-07 5-1)이고, 문제 응답에서는 certainty 값이 그대로 terminalReason이 되며 재시도 차단 조건(certainty !== "MAYBE_APPLIED")에도 쓰인다. 값을 바꾸면 그 이중 차단이 하나로 줄고, projector가 문자열을 걸러 내야 한다. 별도 닫힌 타입 필드가 의도가 더 잘 보인다. - 플래그와 주석 문장을 지우기(리뷰의 두 번째 안): 운영자가 "결과 불명"이 분류기 결함 때문인지 구분할 수단이 계속 없다. 위험·한계 - classifyStatus(401·403·429) 분류기의 throw는 지금처럼 MAYBE_APPLIED만 내고 reason을 남기지 않는다. 그 함수는 기록을 주장하지 않아 이번 범위에서 뺐다. - 공개 타입은 추가만 했다(관측 선택 필드 1개, 배럴 type export 1개). - VD-07 5-1에 reason 전달 규칙을 적었다. 검증 - RED(수정 전): tests/integration/http-execution-v3-observability.test.ts "keeps MAYBE_APPLIED and records a failed problem classifier in diagnostics only (03-05)" 실패. 기대 reason "CLASSIFIER_FAILED", 실제 undefined. - GREEN: 같은 파일 7/7 통과. 변이 M5(catch를 NOT_APPLIED로)를 다시 넣으면 이 테스트가 실패하는 것을 확인하고 원복했다. - 회귀: run-vitest tests/integration tests/features/reference-feature tests/unit/http-execution-v3.test.ts 30 files / 302 tests 통과. tsc app/test/node rc=0. 바꾼 파일 eslint rc=0. check-adapter-inventory PASS. - 미실행: check:architecture(pnpm 스크립트 필요). Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
429 lines
13 KiB
TypeScript
429 lines
13 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");
|
|
});
|
|
|
|
/**
|
|
* 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);
|
|
}
|
|
});
|
|
|
|
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);
|
|
});
|
|
});
|