merge: PR #25을 합친 검사 브랜치에 넣는다

This commit is contained in:
DongHyeonka
2026-11-13 07:16:01 +09:00
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);
});
});