diff --git a/docs/architecture/decisions/VD-07-diagnostics-and-telemetry-exporter.md b/docs/architecture/decisions/VD-07-diagnostics-and-telemetry-exporter.md index d46e64bb..8b09f220 100644 --- a/docs/architecture/decisions/VD-07-diagnostics-and-telemetry-exporter.md +++ b/docs/architecture/decisions/VD-07-diagnostics-and-telemetry-exporter.md @@ -43,21 +43,27 @@ vendor 결정 전에는 안전한 기본값이 아니다. `createHttpObservationProjector`가 유일한 projection authority다. observation은 arbitrary context map이 아니며 projector는 `route_id`, `operation_id`, `operation`, `outcome`, `error_kind`, `http_status_group`, - `attempt_count_bucket`, `duration_bucket`만 사용한다. diagnostics에만 + `attempt_count_bucket`, `duration_bucket`, `effect_certainty`만 사용한다. + `effect_certainty`는 V3 `HttpEffectCertainty` 다섯 값(`NOT_APPLICABLE`, + `NOT_STARTED`, `NOT_APPLIED`, `APPLIED_CONFIRMED`, `MAYBE_APPLIED`)만 받는 닫힌 + value policy(`isEffectCertainty`)를 두 sink가 함께 쓴다. 결과 불명 쓰기의 수를 + 세기 위해서다(1103/03-05). diagnostics에만 `correlation_id`(서버가 돌려준 `x-correlation-id`, 없으면 실행이 보낸 요청 ID)를 더한다. telemetry에는 넣지 않는다(03-03, `createHttpObservationProjector`). 실행이 observation의 `diagnosticReason`(닫힌 집합 `HttpDiagnosticReason`)을 - 남기면 diagnostics에만 `reason`으로 더한다. 값은 둘 중 하나다. 기능 패키지의 + 남기면 diagnostics에만 `reason`으로 더한다. 값은 넷 중 하나다. 기능 패키지의 `classifyProblem`이 throw하거나 집합 밖 값을 돌려줘 효과를 `MAYBE_APPLIED`로 - 떨어뜨린 `CLASSIFIER_FAILED`(03-05), 그리고 전송 전에 거절한 요청의 원인 + 떨어뜨린 `CLASSIFIER_FAILED`(03-05), 전송 전에 거절한 요청의 원인 `HttpRequestRejectionReason`(입력 검증 실패, 요청 조립 실패, 최종 불변식 실패, - 미설치 계약 `CONTRACT_NOT_INSTALLED`, 03-02)이다. 미설치 계약은 실행기를 + 미설치 계약 `CONTRACT_NOT_INSTALLED`, 03-02), Envelope 백엔드가 멱등 키를 + 거절한 `IdempotencyRefusalReason`, 그리고 Envelope 명령의 결과를 모르게 된 + 원인 `UnknownEffectReason`(`IN_FLIGHT`, `IDEMPOTENCY_UNAVAILABLE`, + `COMPLETION_UNKNOWN`, `RECOVERY_REQUIRED`, `SERVER_TIMEOUT`, `STAGE_UNKNOWN`, + 1103/03-05)이다. 백엔드 `error.code` 원문은 싣지 않는다. 미설치 계약은 실행기를 거치지 않으므로 조립 지점이 같은 projector로 관측 1건을 직접 남긴다. raw attempt count, duration, status, URL, intent, key, input identity와 내부 `terminalReason`은 - sink로 나가지 않는다. effect certainty가 운영상 필요해지면 `effect_certainty` - key와 닫힌 value policy를 contract·fixture·이 ADR에 동시에 추가한 뒤에만 - 전달한다. + sink로 나가지 않는다. 5-2. caller cancellation과 scope fence는 API failure가 아니다. diagnostics는 한 번 남기고 `api.request.failed`는 발행하지 않는다. 자격증명이 없어 한 번도 보내지 않은 `UNAUTHENTICATED`(응답 status 없음)도 같다(03-07, diff --git a/src/adapters/http/backend-envelope.ts b/src/adapters/http/backend-envelope.ts index 10b55e55..186cc004 100644 --- a/src/adapters/http/backend-envelope.ts +++ b/src/adapters/http/backend-envelope.ts @@ -205,29 +205,75 @@ export function isFieldValidationFailure( Array.isArray(error.details); } +/** + * 1103/03-05. Why a backend answer left a command's result unknown, a closed + * set for diagnostics `reason`: the key is still running (`IN_FLIGHT`), one of + * the backend's own 5xx answers below, or a 400, 409 or 422 whose code does + * not say whether it came before or after the write (`STAGE_UNKNOWN`). + */ +export type UnknownEffectReason = + | "IN_FLIGHT" + | "IDEMPOTENCY_UNAVAILABLE" + | "COMPLETION_UNKNOWN" + | "RECOVERY_REQUIRED" + | "SERVER_TIMEOUT" + | "STAGE_UNKNOWN"; + /** * 1103/03-04. The backend's answers outside 400, 409 and 422 that it defines * itself (§2, §4), each with its status. None of them lets a client say the * command did not run, and none takes a new key. */ -const MAYBE_APPLIED_ANSWERS: Readonly> = Object.freeze({ +const MAYBE_APPLIED_ANSWERS: Readonly< + Record> +> = Object.freeze({ // §2. Refused before the action, but to be resent with the same key, which // only an unknown result keeps. - IDEMPOTENCY_UNAVAILABLE: 503, + IDEMPOTENCY_UNAVAILABLE: Object.freeze({ + status: 503, + reason: "IDEMPOTENCY_UNAVAILABLE", + }), // §2. The action ran and recording its result failed: same key later, // never a new one. - IDEMPOTENCY_COMPLETION_UNKNOWN: 503, + IDEMPOTENCY_COMPLETION_UNKNOWN: Object.freeze({ + status: 503, + reason: "COMPLETION_UNKNOWN", + }), // §2. An earlier attempt's effect cannot be proven. Not resent on its own; // the user checks the data. - IDEMPOTENCY_RECOVERY_REQUIRED: 500, + IDEMPOTENCY_RECOVERY_REQUIRED: Object.freeze({ + status: 500, + reason: "RECOVERY_REQUIRED", + }), // §4. An async request ran past its time; the work may still go on. - REQUEST_TIMEOUT: 503, + REQUEST_TIMEOUT: Object.freeze({ status: 503, reason: "SERVER_TIMEOUT" }), }); +function maybeAppliedAnswer(code: string, status: number) { + const answer = Object.hasOwn(MAYBE_APPLIED_ANSWERS, code) + ? MAYBE_APPLIED_ANSWERS[code] + : undefined; + return answer !== undefined && answer.status === status ? answer : undefined; +} + function mayHaveApplied(code: string, status: number): boolean { - return Object.hasOwn(MAYBE_APPLIED_ANSWERS, code) - ? MAYBE_APPLIED_ANSWERS[code] === status - : false; + return maybeAppliedAnswer(code, status) !== undefined; +} + +/** + * 1103/03-05. The cause behind a `MAYBE_APPLIED` the table gave, or + * `undefined` when the answer did not leave the result unknown. + */ +export function unknownEffectReason( + status: number, + error: EnvelopeError, + declaredRefusals?: readonly string[], +): UnknownEffectReason | undefined { + if (envelopeFailureEffect(status, error, declaredRefusals) !== "MAYBE_APPLIED") { + return undefined; + } + if (status === 409 && error.code === "IDEMPOTENT_IN_FLIGHT") return "IN_FLIGHT"; + return maybeAppliedAnswer(error.code, status)?.reason ?? "STAGE_UNKNOWN"; } /** diff --git a/src/adapters/http/http-execution-v3.ts b/src/adapters/http/http-execution-v3.ts index 1c5a0e3a..5687d05a 100644 --- a/src/adapters/http/http-execution-v3.ts +++ b/src/adapters/http/http-execution-v3.ts @@ -51,8 +51,10 @@ import { invitesKeyedResend, readFailureEnvelope, readSuccessEnvelope, + unknownEffectReason, type EnvelopePage, type IdempotencyRefusalReason, + type UnknownEffectReason, } from "./backend-envelope.ts"; import { createExecutionContext, @@ -351,13 +353,16 @@ export type HttpExecutionObservation = Readonly<{ * - an `HttpRequestRejectionReason`: copied from the refused request's * violation (03-02). * - an `IdempotencyRefusalReason`: an Envelope operation's backend refused - * the idempotency key (1101 README 14.4). No other backend code reaches - * diagnostics; the failure's code carries it. + * the idempotency key (1101 README 14.4). + * - an `UnknownEffectReason`: why an Envelope command's answer left its + * result unknown (1103/03-05). + * No backend code itself reaches diagnostics; the failure's code carries it. */ export type HttpDiagnosticReason = | "CLASSIFIER_FAILED" | HttpRequestRejectionReason - | IdempotencyRefusalReason; + | IdempotencyRefusalReason + | UnknownEffectReason; /** * The outcome is the single authority for the observed error kind. The terminal @@ -1700,7 +1705,7 @@ async function admitProblem( let validated: ValidatorInvocation; let problemMetadata = metadata; let backendEffect: "NOT_APPLIED" | "MAYBE_APPLIED" | undefined; - let refusalReason: IdempotencyRefusalReason | undefined; + let backendReason: IdempotencyRefusalReason | UnknownEffectReason | undefined; let keyedResend = false; if (enveloped) { const framed = readFailureEnvelope(decoded.value); @@ -1720,7 +1725,15 @@ async function admitProblem( framed.value, contract.commandEffect?.refusedBeforeWrite, ); - refusalReason = idempotencyRefusalReason(framed.value.code, status); + backendReason = + idempotencyRefusalReason(framed.value.code, status) ?? + (isCommand + ? unknownEffectReason( + status, + framed.value, + contract.commandEffect?.refusedBeforeWrite, + ) + : undefined); keyedResend = isCommand && contract.retrySemantics === "KEYED" && @@ -1774,9 +1787,9 @@ async function admitProblem( retryAfterMs: metadata.retryAfterMs ?? null, ...(isCommand && classification.contractRuntimeFailure ? { diagnosticReason: "CLASSIFIER_FAILED" as const } - : refusalReason === undefined + : backendReason === undefined ? {} - : { diagnosticReason: refusalReason }), + : { diagnosticReason: backendReason }), ...(keyedResend ? { keyedResend: true as const } : {}), }); } diff --git a/src/bootstrap/runtime-adapters.ts b/src/bootstrap/runtime-adapters.ts index d419621b..7de9c77f 100644 --- a/src/bootstrap/runtime-adapters.ts +++ b/src/bootstrap/runtime-adapters.ts @@ -200,6 +200,9 @@ export function createHttpObservationProjector( http_status_group: statusGroup(observation.status), attempt_count_bucket: attemptBucket(observation.attemptCount), duration_bucket: durationBucket(observation.durationMs), + // 1103/03-05. Five closed values: counts unknown-result writes apart + // from refused ones without any request-scoped value. + effect_certainty: observation.effect, }; try { sinks.diagnostics.record({ diff --git a/src/contracts/diagnostics.ts b/src/contracts/diagnostics.ts index 8bd9a9af..45e7a4bd 100644 --- a/src/contracts/diagnostics.ts +++ b/src/contracts/diagnostics.ts @@ -43,6 +43,7 @@ export const DIAGNOSTIC_CONTEXT_ALLOWLIST = Object.freeze([ "reason", "queue_size_bucket", "feature_override_key", + "effect_certainty", ] as const); export type DiagnosticContextKey = (typeof DIAGNOSTIC_CONTEXT_ALLOWLIST)[number]; @@ -87,6 +88,8 @@ export const DIAGNOSTIC_CONTEXT_CARDINALITY = Object.freeze({ // 09-09. A key from the deployed runtime document; it changes with a config // deployment, not with traffic. feature_override_key: "deployment", + // 1103/03-05. The V3 effect certainty, five values. + effect_certainty: "bounded", } satisfies Readonly>); export type DiagnosticContext = Readonly< @@ -114,8 +117,22 @@ const BOUNDED_CONTEXT_VALUE_POLICIES: Readonly< typeof value === "string" && /^(?:route|feature|boot)$/.test(value), queue_size_bucket: (value) => typeof value === "string" && /^(?:0|1-10|11-50|51\+)$/.test(value), + effect_certainty: isEffectCertainty, }); +/** + * 1103/03-05. Exactly the V3 `HttpEffectCertainty` values. Telemetry and + * diagnostics both validate `effect_certainty` with it. + */ +export function isEffectCertainty(value: unknown): value is string { + return ( + typeof value === "string" && + /^(?:NOT_APPLICABLE|NOT_STARTED|NOT_APPLIED|APPLIED_CONFIRMED|MAYBE_APPLIED)$/.test( + value, + ) + ); +} + export type DiagnosticRecordInput = Readonly<{ level: DiagnosticLevel; eventId: DiagnosticEventId; diff --git a/src/contracts/telemetry.ts b/src/contracts/telemetry.ts index 6b2cfdcb..73e00737 100644 --- a/src/contracts/telemetry.ts +++ b/src/contracts/telemetry.ts @@ -1,4 +1,4 @@ -import { isHttpStatusGroup } from "./diagnostics.ts"; +import { isEffectCertainty, isHttpStatusGroup } from "./diagnostics.ts"; import { isOperationId } from "./operation-id.ts"; export const TELEMETRY_ATTRIBUTE_ALLOWLIST = Object.freeze([ @@ -18,6 +18,7 @@ export const TELEMETRY_ATTRIBUTE_ALLOWLIST = Object.freeze([ "mismatch_kind", "reason", "queue_size_bucket", + "effect_certainty", ] as const); export const TELEMETRY_FORBIDDEN_ATTRIBUTES = Object.freeze([ @@ -74,7 +75,7 @@ export const TELEMETRY_REGISTRY = Object.freeze({ "http_status_group", "attempt_count_bucket", "route_id", - ], ["operation_id", "duration_bucket"]), + ], ["operation_id", "duration_bucket", "effect_certainty"]), "ui.render.failed": event("ui.render.failed", "React boundary catch", [ "route_id", "build_id", @@ -136,6 +137,8 @@ const ATTRIBUTE_VALUE_POLICIES: Readonly< ), queue_size_bucket: (value) => /^(?:0|1-10|11-50|51\+)$/.test(value), + // 1103/03-05. Shared with diagnostics. + effect_certainty: isEffectCertainty, }); function validAttributeValue(key: string, value: unknown): value is string { diff --git a/tests/integration/http-execution-v3-envelope.test.ts b/tests/integration/http-execution-v3-envelope.test.ts index a747ee29..a8d35785 100644 --- a/tests/integration/http-execution-v3-envelope.test.ts +++ b/tests/integration/http-execution-v3-envelope.test.ts @@ -11,7 +11,10 @@ import { type InstalledHttpOperationExecutor, } from "../../src/adapters/http/index.ts"; import { createHttpObservationProjector } from "../../src/bootstrap/runtime-adapters.ts"; -import type { DiagnosticRecordInput } from "../../src/contracts/diagnostics.ts"; +import { + projectDiagnosticRecord, + type DiagnosticRecordInput, +} from "../../src/contracts/diagnostics.ts"; import { mappingSuccess } from "../../src/contracts/boundary-mapper.ts"; import type { AppFailure } from "../../src/contracts/errors.ts"; import { @@ -796,12 +799,20 @@ describe("an operation's declared pre-write refusals", () => { // and names an idempotency refusal in diagnostics (`reason`, a closed // taxonomy); any other code stays out of diagnostics. describe("V3 Envelope diagnostics name idempotency refusals", () => { + // 1103/03-05. An unknown result names its cause too, and every record + // carries the effect, so an in-flight 409 and a business 409 no longer + // read the same. it.each([ - ["422 IDEMPOTENT_REQUEST_MISMATCH", 422, "IDEMPOTENT_REQUEST_MISMATCH", "IDEMPOTENT_REQUEST_MISMATCH"], - ["400 IDEMPOTENCY_KEY_INVALID", 400, "IDEMPOTENCY_KEY_INVALID", "IDEMPOTENCY_KEY_RULE_MISMATCH"], - ["409 IDEMPOTENT_IN_FLIGHT", 409, "IDEMPOTENT_IN_FLIGHT", undefined], - ["409 domain conflict", 409, "RESOURCE_CONFLICT", undefined], - ] as const)("%s", async (_label, status, code, reason) => { + ["422 IDEMPOTENT_REQUEST_MISMATCH", 422, "IDEMPOTENT_REQUEST_MISMATCH", "IDEMPOTENT_REQUEST_MISMATCH", "NOT_APPLIED"], + ["400 IDEMPOTENCY_KEY_INVALID", 400, "IDEMPOTENCY_KEY_INVALID", "IDEMPOTENCY_KEY_RULE_MISMATCH", "NOT_APPLIED"], + ["400 VALIDATION_FAILED", 400, "VALIDATION_FAILED", undefined, "NOT_APPLIED"], + ["409 IDEMPOTENT_IN_FLIGHT", 409, "IDEMPOTENT_IN_FLIGHT", "IN_FLIGHT", "MAYBE_APPLIED"], + ["409 domain conflict", 409, "RESOURCE_CONFLICT", "STAGE_UNKNOWN", "MAYBE_APPLIED"], + ["503 IDEMPOTENCY_UNAVAILABLE", 503, "IDEMPOTENCY_UNAVAILABLE", "IDEMPOTENCY_UNAVAILABLE", "MAYBE_APPLIED"], + ["503 IDEMPOTENCY_COMPLETION_UNKNOWN", 503, "IDEMPOTENCY_COMPLETION_UNKNOWN", "COMPLETION_UNKNOWN", "MAYBE_APPLIED"], + ["500 IDEMPOTENCY_RECOVERY_REQUIRED", 500, "IDEMPOTENCY_RECOVERY_REQUIRED", "RECOVERY_REQUIRED", "MAYBE_APPLIED"], + ["503 REQUEST_TIMEOUT", 503, "REQUEST_TIMEOUT", "SERVER_TIMEOUT", "MAYBE_APPLIED"], + ] as const)("%s", async (_label, status, code, reason, effect) => { answer("post", "/api/envelope-items", failure(code, "VALIDATION", false), { status }); const records: DiagnosticRecordInput[] = []; const project = createHttpObservationProjector({ @@ -815,6 +826,8 @@ describe("V3 Envelope diagnostics name idempotency refusals", () => { expect(records).toHaveLength(1); expect(records[0]?.context?.reason).toBe(reason); + expect(records[0]?.context?.effect_certainty).toBe(effect); + expect(projectDiagnosticRecord(records[0]!).success).toBe(true); }); }); diff --git a/tests/integration/http-execution-v3-observability.test.ts b/tests/integration/http-execution-v3-observability.test.ts index 4f95fc14..17ec0c77 100644 --- a/tests/integration/http-execution-v3-observability.test.ts +++ b/tests/integration/http-execution-v3-observability.test.ts @@ -130,6 +130,7 @@ describe("V3 HTTP observability projection", () => { "http_status_group", "attempt_count_bucket", "duration_bucket", + "effect_certainty", ]), ); for (const key of contextKeys) { diff --git a/tests/unit/observability-cardinality.test.ts b/tests/unit/observability-cardinality.test.ts index 3de676c0..91c5de07 100644 --- a/tests/unit/observability-cardinality.test.ts +++ b/tests/unit/observability-cardinality.test.ts @@ -44,6 +44,53 @@ describe("observability cardinality policy", () => { ).toEqual({ success: false, reason: "invalid-context" }); }); + // 1103/03-05. The effect certainty is a closed five-value dimension in + // both sinks. + it.each(["NOT_APPLICABLE", "NOT_STARTED", "NOT_APPLIED", "APPLIED_CONFIRMED", "MAYBE_APPLIED"])( + "admits effect_certainty %s in diagnostics and failure telemetry", + (effect) => { + expect(DIAGNOSTIC_CONTEXT_CARDINALITY.effect_certainty).toBe("bounded"); + expect( + projectDiagnosticRecord({ + level: "warn", + eventId: "http.request.completed", + context: { effect_certainty: effect }, + }).success, + ).toBe(true); + expect( + projectTelemetryEvent("api.request.failed", { + error_kind: "PROBLEM", + http_status_group: "4xx", + attempt_count_bucket: "1", + route_id: "TEST_ROUTE", + effect_certainty: effect, + }).success, + ).toBe(true); + }, + ); + + it.each(["maybe", "UNKNOWN", "MAYBE_APPLIED_ON_RETRY"])( + "rejects effect_certainty %j in both sinks", + (effect) => { + expect( + projectDiagnosticRecord({ + level: "warn", + eventId: "http.request.completed", + context: { effect_certainty: effect }, + }), + ).toEqual({ success: false, reason: "invalid-context" }); + expect( + projectTelemetryEvent("api.request.failed", { + error_kind: "PROBLEM", + http_status_group: "4xx", + attempt_count_bucket: "1", + route_id: "TEST_ROUTE", + effect_certainty: effect, + }), + ).toEqual({ success: false, reason: "invalid-attribute-value" }); + }, + ); + it("allows request correlation only in bounded diagnostics evidence", () => { const projected = projectDiagnosticRecord({ level: "info",