diff --git a/src/adapters/http/client.ts b/src/adapters/http/client.ts index 2db6b5ad..45eebf80 100644 --- a/src/adapters/http/client.ts +++ b/src/adapters/http/client.ts @@ -222,6 +222,8 @@ export function createHttpClient( outcomeKind: "success" | "recovered" | "failed" | "aborted", ): HttpResult { const error = outcome.ok ? undefined : outcome.error; + const reason = + error && idempotencyRefusalReason(error.code, error.httpStatus); const context = { route_id: input.routeId, operation_id: input.operationId, @@ -241,7 +243,8 @@ export function createHttpClient( diagnostics?.record({ level: error ? "warn" : "info", eventId: "http.request.completed", - context, + // Diagnostics only: telemetry below keeps its fixed attribute set. + context: reason ? { ...context, reason } : context, }); } catch { // Diagnostics cannot change the HTTP result. @@ -1005,10 +1008,14 @@ async function parseResponse( envelopeRecord.error && typeof envelopeRecord.error === "object" ? (envelopeRecord.error as Record) : {}; + const code = safeBackendCode(envelope); return { ok: false, error: failure(kind, operation.operationId, attempt, { - code: safeBackendCode(envelope), + code, + ...(idempotencyRefusalReason(code, response.status) === undefined + ? {} + : { effect: "NOT_APPLIED" as const }), httpStatus: response.status, requestId: safeMeta(envelopeRecord.meta).requestId, traceId: safeMeta(envelopeRecord.meta).traceId, @@ -1073,6 +1080,41 @@ async function recoverSession( }; } +/** + * 백엔드 1101/02-01. Refusals the paired backend answers before it runs the + * command (clean-architecture-backend-template docs/web/http-contract.md §2): + * the request was not applied and sending it again unchanged gets the same + * answer. Only the documented status and code together count. The value is + * the diagnostics `reason`, named for what is wrong on this side. + */ +const IDEMPOTENCY_REFUSALS: Readonly< + Record> +> = Object.freeze({ + // The same key went out with another body. + IDEMPOTENT_REQUEST_MISMATCH: Object.freeze({ + status: 422, + reason: "IDEMPOTENT_REQUEST_MISMATCH", + }), + // `isValidIdempotencyKey` passed the key before sending, so the client and + // server key rules disagree. + IDEMPOTENCY_KEY_INVALID: Object.freeze({ + status: 400, + reason: "IDEMPOTENCY_KEY_RULE_MISMATCH", + }), +}); + +function idempotencyRefusalReason( + code: string, + status: number | undefined, +): string | undefined { + const refusal = Object.hasOwn(IDEMPOTENCY_REFUSALS, code) + ? IDEMPOTENCY_REFUSALS[code] + : undefined; + return refusal !== undefined && refusal.status === status + ? refusal.reason + : undefined; +} + function safeBackendCode(envelope: unknown): string { if (!envelope || typeof envelope !== "object") return "HTTP_FAILURE"; const error = (envelope as Record).error; diff --git a/src/features/reference-feature/adapters/reference-http-gateway.ts b/src/features/reference-feature/adapters/reference-http-gateway.ts index 12ebc8f4..152be19c 100644 --- a/src/features/reference-feature/adapters/reference-http-gateway.ts +++ b/src/features/reference-feature/adapters/reference-http-gateway.ts @@ -41,6 +41,15 @@ export const REFERENCE_HTTP_OPERATIONS = Object.freeze({ code: problem.code ?? "REFERENCE_RESOURCE_CONFLICT", }); } + // 백엔드 1101/02-01. The paired backend's answer to a key outside its + // rule. The executor checked the key before sending, so this names a + // rule mismatch between the two sides: keep the code for diagnostics. + if (metadata.status === 400 && problem.code === "IDEMPOTENCY_KEY_INVALID") { + return Object.freeze({ + kind: "UNKNOWN_CLIENT_FAILURE" as const, + code: problem.code, + }); + } if (metadata.status === 422) { return Object.freeze({ kind: "VALIDATION_REJECTED" as const, diff --git a/tests/features/reference-feature/reference-http-problem-mapping.test.ts b/tests/features/reference-feature/reference-http-problem-mapping.test.ts index 972e68a2..2330d1e8 100644 --- a/tests/features/reference-feature/reference-http-problem-mapping.test.ts +++ b/tests/features/reference-feature/reference-http-problem-mapping.test.ts @@ -107,6 +107,54 @@ describe("reference HTTP business problem mapping", () => { }, ); + // 백엔드 1101/02-01. The paired backend refuses both before it runs the + // command (its docs/web/http-contract.md §2). The failure keeps the cause + // code and does not invite a resend. + it.each([ + { + status: 422, + code: "IDEMPOTENT_REQUEST_MISMATCH", + expectedKind: "VALIDATION_REJECTED", + }, + { + // The executor checked the key before sending: the two rules disagree. + status: 400, + code: "IDEMPOTENCY_KEY_INVALID", + expectedKind: "UNKNOWN_CLIENT_FAILURE", + }, + ] as const)( + "keeps the paired backend's $status $code as a not-applied failure", + async ({ status, code, expectedKind }) => { + const executor = executorReturning( + Object.freeze({ + kind: "PROBLEM", + problem: Object.freeze({ + type: "https://api.test/problems/" + code.toLowerCase(), + title: code, + status, + code, + }), + metadata: Object.freeze({ status }), + effect: "NOT_APPLIED", + }), + ); + const gateway = createReferenceHttpGateway( + createFeatureHttpBinding(executor, REFERENCE_HTTP_OPERATIONS), + ); + + await expect(gateway.create({ name: "n" })).resolves.toMatchObject({ + ok: false, + error: { + kind: expectedKind, + code, + httpStatus: status, + effect: "NOT_APPLIED", + retryable: false, + }, + }); + }, + ); + it("keeps the platform status fallback when the operation has no problem mapper", async () => { const executor = executorReturning( Object.freeze({ @@ -157,6 +205,10 @@ describe("reference create problem effect classification (0929/03-01)", () => { { status: 409, code: "CONFLICT", effect: "NOT_APPLIED" }, { status: 400, code: undefined, effect: "NOT_APPLIED" }, { status: 422, code: "VALIDATION_REJECTED", effect: "NOT_APPLIED" }, + // 백엔드 1101/02-01. Refused before the command ran: this request was + // not applied, so the next save may mint a new key. + { status: 422, code: "IDEMPOTENT_REQUEST_MISMATCH", effect: "NOT_APPLIED" }, + { status: 400, code: "IDEMPOTENCY_KEY_INVALID", effect: "NOT_APPLIED" }, { status: 404, code: "NOT_FOUND", effect: "MAYBE_APPLIED" }, { status: 503, code: "SERVER_FAILURE", effect: "MAYBE_APPLIED" }, ] as const)( diff --git a/tests/integration/http-diagnostics.test.ts b/tests/integration/http-diagnostics.test.ts index 7c361a3d..96a33996 100644 --- a/tests/integration/http-diagnostics.test.ts +++ b/tests/integration/http-diagnostics.test.ts @@ -190,4 +190,91 @@ describe("HTTP diagnostics and terminal telemetry", () => { }); expect(emitted).toEqual([]); }); + + // 백엔드 1101/02-01. The paired backend refuses these before it runs the + // command (its docs/web/http-contract.md §2): not applied, not resent, and + // diagnostics name the cause. + it.each([ + { + status: 422, + code: "IDEMPOTENT_REQUEST_MISMATCH", + kind: "VALIDATION_REJECTED", + details: undefined, + reason: "IDEMPOTENT_REQUEST_MISMATCH", + }, + { + status: 400, + code: "IDEMPOTENCY_KEY_INVALID", + kind: "UNKNOWN_CLIENT_FAILURE", + details: { reason: "MALFORMED" }, + // This client checked the key before sending, so the two rules disagree. + reason: "IDEMPOTENCY_KEY_RULE_MISMATCH", + }, + ])( + "reports a $status $code as not applied, sent once, with reason $reason", + async ({ status, code, kind, details, reason }) => { + const fetcher = vi.fn(async () => + Response.json( + { + success: false, + error: { + code, + category: "VALIDATION", + message: "요청을 처리할 수 없습니다.", + retryable: false, + ...(details === undefined ? {} : { details }), + }, + meta: { requestId: "request-1", traceId: "trace-1" }, + }, + { status }, + ), + ); + const { client, records } = harness(fetcher); + + await expect( + client.execute({ + operationId: "CREATE_ENTITY", + routeId: "TEST_ROUTE", + body: { name: "n" }, + idempotencyKey: "key-1", + }), + ).resolves.toMatchObject({ + ok: false, + error: { + kind, + code, + httpStatus: status, + retryable: false, + effect: "NOT_APPLIED", + }, + }); + expect(fetcher).toHaveBeenCalledTimes(1); + expect(records).toMatchObject([ + { context: { outcome: "failed", error_kind: kind, reason } }, + ]); + }, + ); + + it("keeps an unrelated 422 effect-free and reason-free", async () => { + const fetcher = vi.fn(async () => + Response.json( + { + success: false, + error: { code: "INVALID_INPUT" }, + meta: { requestId: "request-1", traceId: "trace-1" }, + }, + { status: 422 }, + ), + ); + const { client, records } = harness(fetcher); + + const result = await client.execute({ + operationId: "CREATE_ENTITY", + routeId: "TEST_ROUTE", + body: { name: "n" }, + }); + + expect(result.ok ? undefined : result.error.effect).toBeUndefined(); + expect(records[0]?.context).not.toHaveProperty("reason"); + }); }); diff --git a/tests/unit/legacy-and-optional-network-remediation.test.ts b/tests/unit/legacy-and-optional-network-remediation.test.ts index 723da17a..886c8abb 100644 --- a/tests/unit/legacy-and-optional-network-remediation.test.ts +++ b/tests/unit/legacy-and-optional-network-remediation.test.ts @@ -142,8 +142,12 @@ describe("OPT-NET-02 shared idempotency key validation", () => { } }); + // 백엔드 1101/02-01. The paired backend's IdempotencyKeyHeader grammar is + // the same: [\x21-\x7E]{1,256}, never trimmed. A key it refuses with + // 400 IDEMPOTENCY_KEY_INVALID never left this client. it("accepts the bounded visible-ASCII values both sides allow", () => { for (const value of [ + "k", "key-1", "a".repeat(256), "0f8fad5b-d9cb-469f-a165-70867728950e",