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
+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
);
}