diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index 86dd5aeb..8ed8bead 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -328,6 +328,10 @@ mutation이 400·409·422로 실패하면 프론트는 그 요청이 적용됐 불명을 풀므로(1106/03-01, `src/contracts/errors.ts` `isRefusedOnEveryAttempt`), `VALIDATION_FAILED`는 요청 내용만 보는 검사여야 하고, 시각이나 데이터베이스를 읽는 규칙은 기능이 선언한 code로 내며 그 code는 결과 불명을 풀지 않는다. + 판정은 실패의 `code`가 아니라 `backendCode`(Envelope operation의 백엔드 + `error.code`를 바인딩이 그대로 실은 값)를 읽는다(1112/01-06). 기능 `mapProblem`이 + code를 바꾸거나 다른 code를 `VALIDATION_FAILED`로 바꿔도 판정은 같고, Envelope가 없는 + operation의 실패는 결과 불명을 풀지 않는다. - §4의 503 `RATE_LIMIT_UNAVAILABLE`(rate-limit 저장소 응답 없음, `Retry-After` 있음)과 503 `RATE_LIMIT_INCOMPATIBLE`(rate-limit 제공자가 계약과 맞지 않음)은 status와 code가 함께 맞으면 기능 분류기와 상관없이 `NOT_APPLIED`다(1105/03-02, `backend-envelope.ts` diff --git a/src/adapters/http/feature-http-binding.ts b/src/adapters/http/feature-http-binding.ts index f4370851..faa877d9 100644 --- a/src/adapters/http/feature-http-binding.ts +++ b/src/adapters/http/feature-http-binding.ts @@ -311,6 +311,7 @@ export function createFeatureHttpBinding< contract.contract.responseEnvelope === "ENVELOPE_V1", ), outcome, + contract.contract.responseEnvelope === "ENVELOPE_V1", ); }, }); @@ -345,10 +346,18 @@ function envelopeProblemMapping( problem: unknown, status: number, ): FeatureHttpProblemMapping | undefined { + const code = envelopeCode(problem); + if (code === undefined) return undefined; + const { details } = problem as Readonly>; + return envelopeFailureReading(status, { code, details }); +} + +/** The backend `error.code` of an Envelope problem, when it is well formed. */ +function envelopeCode(problem: unknown): string | undefined { if (!problem || typeof problem !== "object") return undefined; - const { code, details } = problem as Readonly>; + const { code } = problem as Readonly>; return typeof code === "string" && /^[A-Z0-9_]{1,64}$/u.test(code) - ? envelopeFailureReading(status, { code, details }) + ? code : undefined; } @@ -358,6 +367,8 @@ function envelopeProblemMapping( * 0929/03-04. Without an echo (timeout, lost connection, a gateway that drops * the header) it is the id the request carried. * 1103/03-06. A failure Envelope's `meta.traceId` becomes `traceId`. + * 1112/01-06. An Envelope operation's problem keeps the backend's own code as + * `backendCode`, whatever code the feature mapped it to. */ function projectExecutionOutcome( operationId: string, @@ -372,8 +383,15 @@ function projectExecutionOutcome( ) => FeatureHttpProblemMapping | undefined) | undefined, outcome: HttpExecutionOutcome, + enveloped: boolean, ): Result { - const projected = projectOutcome(operationId, mapSuccess, mapProblem, outcome); + const projected = projectOutcome( + operationId, + mapSuccess, + mapProblem, + outcome, + enveloped, + ); const metadata = "metadata" in outcome ? outcome.metadata : undefined; const requestId = metadata?.correlationReference ?? outcome.sentRequestId; const traceId = metadata?.traceReference; @@ -402,6 +420,7 @@ function projectOutcome( ) => FeatureHttpProblemMapping | undefined) | undefined, outcome: HttpExecutionOutcome, + enveloped: boolean, ): Result { // A throwing feature mapper is a mapping defect, not a transport failure: it // must not reject and lose the effect the server already confirmed. @@ -444,11 +463,13 @@ function projectOutcome( } catch { return mapperThrew(outcome.effect, outcome.metadata.status); } + const backendCode = enveloped ? envelopeCode(outcome.problem) : undefined; return failure( mapped?.kind ?? kindForStatus(outcome.metadata.status), operationId, mapped?.code ?? "CONTRACT_PROBLEM", { + ...(backendCode === undefined ? {} : { backendCode }), httpStatus: outcome.metadata.status, // 백엔드 1101/02-01. A resend of an unknown answer waits on it. ...(outcome.metadata.retryAfterMs === undefined @@ -578,6 +599,7 @@ function failure( operationId: string, code: string, details: Readonly<{ + backendCode?: string; httpStatus?: number; retryAfterMs?: number; effect?: FailureEffectCertainty; diff --git a/src/contracts/errors.ts b/src/contracts/errors.ts index f6b98b62..262642b6 100644 --- a/src/contracts/errors.ts +++ b/src/contracts/errors.ts @@ -130,6 +130,13 @@ export type FailureEffectCertainty = export type AppFailure = Readonly<{ kind: FailureKind; code: string; + /** + * 1112/01-06. The code the paired backend's Envelope carried, as it came: + * a feature's `mapProblem` may change `code`, never this. Only the HTTP + * binding sets it, for an `ENVELOPE_V1` operation's problem; elsewhere it + * is absent. + */ + backendCode?: string; httpStatus?: number; /** * Whether sending the same operation again is safe as far as this failure @@ -164,6 +171,7 @@ export type ApiFailure = AppFailure; export type FailureDetails = Readonly<{ code?: string; + backendCode?: string; httpStatus?: number; requestId?: string; traceId?: string; @@ -183,6 +191,9 @@ export function createFailure( return Object.freeze({ kind: definition.kind, code: typeof details.code === "string" ? details.code : definition.kind, + ...(typeof details.backendCode === "string" + ? { backendCode: details.backendCode } + : {}), retryable: details.effect === "MAYBE_APPLIED" || details.effect === "APPLIED_CONFIRMED" @@ -268,13 +279,17 @@ export const REFUSALS_OF_EVERY_ATTEMPT: Readonly> = * 403, 503 RATE_LIMIT_*), a code a feature declared refused before its * write (it may be a rule on changing state), any other code, and * `NOT_STARTED`. The kind is not read: a feature's `mapProblem` sets it, and - * it maps its own codes, or every 422, to `VALIDATION_REJECTED`. + * it maps its own codes, or every 422, to `VALIDATION_REJECTED`. 1112/01-06. + * Nor is `code`, for the same reason: the answer is `backendCode`, the code + * the backend's Envelope carried. A failure without it is not settled. */ export function isRefusedOnEveryAttempt(failure: AppFailure): boolean { if (failure.effect !== "NOT_APPLIED") return false; + const code = failure.backendCode; return ( - Object.hasOwn(REFUSALS_OF_EVERY_ATTEMPT, failure.code) && - REFUSALS_OF_EVERY_ATTEMPT[failure.code] === failure.httpStatus + code !== undefined && + Object.hasOwn(REFUSALS_OF_EVERY_ATTEMPT, code) && + REFUSALS_OF_EVERY_ATTEMPT[code] === failure.httpStatus ); } diff --git a/tests/component/application-mutation-admission.test.tsx b/tests/component/application-mutation-admission.test.tsx index 944c8a9a..12ee366f 100644 --- a/tests/component/application-mutation-admission.test.tsx +++ b/tests/component/application-mutation-admission.test.tsx @@ -818,6 +818,7 @@ describe("application mutation intent admission", () => { "400 VALIDATION_FAILED with its field list", createFailure("VALIDATION_REJECTED", "CREATE_REPLAYED", 0, { code: "VALIDATION_FAILED", + backendCode: "VALIDATION_FAILED", httpStatus: 400, effect: "NOT_APPLIED", }), @@ -826,6 +827,7 @@ describe("application mutation intent admission", () => { "400 VALIDATION_FAILED whose body did not parse", createFailure("UNKNOWN_CLIENT_FAILURE", "CREATE_REPLAYED", 0, { code: "VALIDATION_FAILED", + backendCode: "VALIDATION_FAILED", httpStatus: 400, effect: "NOT_APPLIED", }), @@ -834,6 +836,7 @@ describe("application mutation intent admission", () => { "400 IDEMPOTENCY_KEY_INVALID", createFailure("UNKNOWN_CLIENT_FAILURE", "CREATE_REPLAYED", 0, { code: "IDEMPOTENCY_KEY_INVALID", + backendCode: "IDEMPOTENCY_KEY_INVALID", httpStatus: 400, effect: "NOT_APPLIED", }), @@ -883,6 +886,7 @@ describe("application mutation intent admission", () => { "refused with 400 VALIDATION_FAILED", createFailure("VALIDATION_REJECTED", "CREATE_REPLAYED", 0, { code: "VALIDATION_FAILED", + backendCode: "VALIDATION_FAILED", httpStatus: 400, effect: "NOT_APPLIED", }), diff --git a/tests/contract/reusable-capability/feature-http-binding.test.ts b/tests/contract/reusable-capability/feature-http-binding.test.ts index b96600b5..13dfab8a 100644 --- a/tests/contract/reusable-capability/feature-http-binding.test.ts +++ b/tests/contract/reusable-capability/feature-http-binding.test.ts @@ -309,4 +309,61 @@ describe("feature HTTP binding", () => { }, }); }); + + // 1112/01-06. An Envelope operation's failure keeps the backend's own code + // next to the one the feature mapped, so the resend decision reads the + // answer the backend gave. + it("keeps the backend's Envelope code when the feature maps it to another", async () => { + const enveloped = Object.freeze({ + LOAD_RESOURCE: defineFeatureHttpOperation({ + contract: Object.freeze({ + ...LOAD_RESOURCE_CONTRACT, + contract: Object.freeze({ + ...LOAD_RESOURCE_CONTRACT.contract, + responseEnvelope: "ENVELOPE_V1" as const, + }), + }), + routeId: "RESOURCE_DETAIL", + mapSuccess: (value: ResourceWire) => mappingSuccess(value), + mapProblem: () => Object.freeze({ kind: "VALIDATION_REJECTED" as const, code: "VALIDATION_FAILED" }), + }), + } as const); + const scripted = scriptedExecutor( + Object.freeze({ + kind: "PROBLEM" as const, + problem: Object.freeze({ code: "WORKLOG_INVALID" }), + metadata: Object.freeze({ status: 400 }), + effect: "NOT_APPLIED" as const, + }), + ); + + const result = await createFeatureHttpBinding(scripted.executor, enveloped).execute( + "LOAD_RESOURCE", + { resourceId: "resource-1" }, + ); + + expect(result).toMatchObject({ + ok: false, + error: { code: "VALIDATION_FAILED", backendCode: "WORKLOG_INVALID" }, + }); + }); + + it("gives no backend code to an operation without an Envelope", async () => { + const scripted = scriptedExecutor( + Object.freeze({ + kind: "PROBLEM" as const, + problem: Object.freeze({ code: "RESOURCE_NAME_EXISTS" }), + metadata: Object.freeze({ status: 409 }), + effect: "NOT_APPLIED" as const, + }), + ); + + const result = await createFeatureHttpBinding(scripted.executor, OPERATIONS).execute( + "LOAD_RESOURCE", + { resourceId: "resource-1" }, + ); + + expect(result.ok).toBe(false); + expect(result.ok ? undefined : result.error.backendCode).toBeUndefined(); + }); }); diff --git a/tests/unit/backend-envelope.test.ts b/tests/unit/backend-envelope.test.ts index 0ccfa487..0ad69bd3 100644 --- a/tests/unit/backend-envelope.test.ts +++ b/tests/unit/backend-envelope.test.ts @@ -224,9 +224,27 @@ describe("refusals every attempt of a request gets", () => { envelopeFailureReading(status, error).kind, "ENVELOPE_OPERATION", 0, - { code, httpStatus: status, effect: "NOT_APPLIED" }, + { code, backendCode: code, httpStatus: status, effect: "NOT_APPLIED" }, ); expect(isRefusedOnEveryAttempt(failure)).toBe(expected); }); + + // 1112/01-06. The decision reads the paired backend's own code. A feature's + // mapProblem may rename the code it shows (to a declared one, or to + // VALIDATION_FAILED), and that rename must change neither answer. + it.each([ + ["a backend VALIDATION_FAILED a feature renamed", "WORKLOG_RENAMED", "VALIDATION_FAILED", true], + ["a declared code a feature renamed to VALIDATION_FAILED", "VALIDATION_FAILED", "WORKLOG_INVALID", false], + ["a code with no backend code (no Envelope)", "VALIDATION_FAILED", undefined, false], + ] as const)("reads the backend's code for %s", (_label, code, backendCode, expected) => { + const failure = createFailure("VALIDATION_REJECTED", "ENVELOPE_OPERATION", 0, { + code, + ...(backendCode === undefined ? {} : { backendCode }), + httpStatus: 400, + effect: "NOT_APPLIED", + }); + + expect(isRefusedOnEveryAttempt(failure)).toBe(expected); + }); });