fix(errors): 재전송이 결과 불명을 푸는지는 백엔드가 보낸 code로 정한다
frontend-quality-gates / merge / static checks (pull_request) Successful in 2m56s
frontend-quality-gates / merge / tests (pull_request) Failing after 14m26s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 9m20s
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped

isRefusedOnEveryAttempt는 failure.code를 읽는데, 그 값은 기능의 mapProblem이
정한다(1112/01-06). 그래서 둘이 틀린다.

- 기능이 백엔드 400 VALIDATION_FAILED를 자기 code로 바꾸면 모든 시도가 받는
  거절인데도 결과 불명이 풀리지 않는다.
- 기능이 시각·데이터베이스를 읽는 자기 거절(400)을 VALIDATION_FAILED로 바꾸면
  첫 요청이 반영됐을 수 있는데도 결과 불명이 풀린다.

AppFailure에 backendCode를 더한다(선택 칸, 추가만). HTTP 바인딩이 ENVELOPE_V1
operation의 PROBLEM에서 백엔드 error.code를 그대로 싣고, 판정은 이 칸과
status만 읽는다. Envelope가 없는 operation의 실패에는 싣지 않아 결과 불명이
풀리지 않는다(안전한 쪽). 버린 대안: 판정 표를 기능 code에 맞춰 늘리기(기능이
code를 바꿀 때마다 표가 어긋난다).

위험·한계: createFailure로 실패를 직접 만들어 재전송 거절을 흉내 내던 코드는
backendCode를 함께 줘야 결과 불명이 풀린다. 템플릿 안에서는 코디네이터 시험
넷뿐이고 고쳤다. 다운스트림 시험이 같은 방식이면 CHANGELOG [계약]에 적는다.
mapProblem이 예외를 던져 MAPPING_CONTRACT_VIOLATION이 된 실패에는 싣지 않는다.

Refs: 1112/01-06, 1106/03-01
This commit is contained in:
DongHyeonka
2026-11-12 23:31:50 +09:00
parent 5250ff950e
commit 42aa93d4c7
6 changed files with 127 additions and 7 deletions
@@ -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`
+25 -3
View File
@@ -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<Record<string, unknown>>;
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<Record<string, unknown>>;
const { code } = problem as Readonly<Record<string, unknown>>;
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<WireOutput, Problem, Value>(
operationId: string,
@@ -372,8 +383,15 @@ function projectExecutionOutcome<WireOutput, Problem, Value>(
) => FeatureHttpProblemMapping | undefined)
| undefined,
outcome: HttpExecutionOutcome<WireOutput, Problem>,
enveloped: boolean,
): Result<Value, AppFailure> {
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<WireOutput, Problem, Value>(
) => FeatureHttpProblemMapping | undefined)
| undefined,
outcome: HttpExecutionOutcome<WireOutput, Problem>,
enveloped: boolean,
): Result<Value, AppFailure> {
// 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<WireOutput, Problem, Value>(
} 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;
+18 -3
View File
@@ -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<Record<string, number>> =
* 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
);
}
@@ -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",
}),
@@ -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<ResourceWire, ResourceProblem>(
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<ResourceWire, ResourceProblem>(
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();
});
});
+19 -1
View File
@@ -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);
});
});