Files
clean-architecture-frontend…/tests/features/reference-feature/reference-http-problem-mapping.test.ts
DongHyeonka 47fec5c27c fix(query): 처리 중 409의 Retry-After 전 재전송은 그 시각까지 기다린다 (백엔드 1101/02-01)
문제
짝 백엔드는 같은 키의 첫 요청이 아직 실행 중이면 409
IDEMPOTENT_IN_FLIGHT, retryable=true, Retry-After: 2를 준다(백엔드
docs/web/http-contract.md §2). 클라이언트 행동은 "같은 키로 Retry-After 뒤
재전송"이다.
- 같은 키: 0929/03-01이 이 409를 MAYBE_APPLIED로 두어 코디네이터가 intent를
  붙든다. 재전송은 같은 키를 쓴다(기존 vertical 테스트가 [K, K, K]를
  고정). 이 부분은 이미 맞다.
- Retry-After: 지키지 않는다. V3는 응답 metadata에 retryAfterMs를 읽지만
  feature binding이 PROBLEM을 AppFailure로 옮길 때 버린다. V2는 409의
  Retry-After를 읽지 않는다. 그래서 결과 불명 화면의 "같은 요청으로 다시
  보내기"(또는 같은 입력 다시 저장)를 바로 누르면 즉시 나가서 같은 409를
  한 번 더 받는다.

고른 방법
재전송이 그 시각 전이면 기다렸다 보낸다.
- feature binding이 PROBLEM의 metadata.retryAfterMs를 AppFailure에 싣는다.
  V2는 409의 Retry-After도 읽는다(409는 여전히 자동 재시도하지 않는다).
- mutation 코디네이터(application-query.ts)가 MAYBE_APPLIED로 남기는
  admission에 resendNotBefore = 지금 + min(retryAfterMs, 5초)를 적는다.
  같은 intent를 다시 쓰는 submit(재전송 버튼, 같은 입력 저장)이 그 시각까지
  기다린 뒤 보낸다. 기다리는 동안 admission이 ACTIVE라 화면은 pending이다.
  scope가 바뀌면 기존 mutationFn 검사가 NOT_STARTED로 막는다.
- 상한 5초는 V3 실행기의 Retry-After 상한(RETRY_AFTER_CEILING_MS)과 같다.
  더 일찍 보내도 같은 키라 서버가 다시 409를 줄 뿐 두 번 적용하지 않으므로,
  긴 Retry-After를 다 기다리게 하지 않는다.

버린 대안
- Retry-After 전에는 버튼을 막기: 화면과 시각 회귀 골든이 바뀌고, 다시
  열어 줄 타이머와 문구가 더 든다. 기다렸다 보내는 쪽이 변경이 작다.
- V3 실행기가 키별 "이 시각 전 금지" 표를 들기: 실행기에 키를 기억하는
  상태와 정리 규칙이 생긴다. 재전송을 만드는 곳은 코디네이터 하나다.
- 그대로 두기(이른 재전송은 409를 한 번 더 받을 뿐): 서버 문서가 허용하는
  동작이지만 사용자는 같은 결과 불명 화면을 한 번 더 본다. 요구는
  Retry-After를 지키는 것이다.

위험·한계
- AppFailure.retryAfterMs가 V3 PROBLEM에도 실린다(추가 필드). 이 값을 읽는
  곳은 코디네이터뿐이다.
- 기다림은 MAYBE_APPLIED로 남은 admission을 다시 보낼 때만 생긴다. 다른
  상태(NOT_APPLIED 등)는 그대로다.
- 시계는 performance.now(), 대기는 setTimeout이다. 탭이 백그라운드면
  브라우저가 타이머를 늦출 수 있다(더 늦게 보낼 뿐이다).

검증
- RED: 4행 실패.
  - tests/features/reference-feature/reference-production-vertical.test.tsx
    처리 중 409(Retry-After: 1) 뒤 재전송 간격 39.7ms(기대 990ms 이상)
  - tests/component/application-mutation-admission.test.tsx 재전송이
    retryAfterMs 300을 기다리지 않음
  - tests/features/reference-feature/reference-http-problem-mapping.test.ts
    retryAfterMs 없음
  - tests/integration/http-client.test.ts V2 409 retryAfterMs 없음
  상한 행은 수정 전에도 통과하고, 상한을 뺀 변이에서 시간 초과로 실패하는
  것을 확인했다.
- GREEN: 위 행 모두 통과. tests/component·features·contract/reusable-
  capability, tests/integration/http-client·http-diagnostics, tests/unit/
  http-execution-v3 62 files 491 tests 통과. tsc app·test 통과, 바꾼 파일
  eslint 통과.

Refs: clean-architecture-backend-template docs/reviews/2026-11-01-maturity-review/README.md 14.3, 15
2026-11-03 02:00:45 +09:00

250 lines
7.9 KiB
TypeScript

import { describe, expect, it } from "vitest";
import {
createFeatureHttpBinding,
type InstalledHttpOperationExecutor,
} from "../../../src/adapters/http/index.ts";
import {
createReferenceHttpGateway,
REFERENCE_HTTP_OPERATIONS,
} from "../../../src/features/reference-feature/adapters/reference-http-gateway.ts";
import { CREATE_REFERENCE_RESOURCE_CONTRACT } from "../../../src/features/reference-feature/contracts/reference-feature-contract-contribution.ts";
function executorReturning(
outcome: Readonly<Record<string, unknown>>,
): InstalledHttpOperationExecutor {
const execute = (async () => outcome) as unknown as
InstalledHttpOperationExecutor["execute"];
return Object.freeze({ execute });
}
describe("reference HTTP business problem mapping", () => {
// 백엔드 1101/02-01. The resend waits on this value.
it("carries the Retry-After of an in-flight 409 onto the unknown failure", async () => {
const executor = executorReturning(
Object.freeze({
kind: "PROBLEM",
problem: Object.freeze({
type: "https://api.test/problems/idempotent_in_flight",
title: "IDEMPOTENT_IN_FLIGHT",
status: 409,
code: "IDEMPOTENT_IN_FLIGHT",
}),
metadata: Object.freeze({ status: 409, retryAfterMs: 2_000 }),
effect: "MAYBE_APPLIED",
}),
);
const gateway = createReferenceHttpGateway(
createFeatureHttpBinding(executor, REFERENCE_HTTP_OPERATIONS),
);
await expect(gateway.create({ name: "n" })).resolves.toMatchObject({
ok: false,
error: {
code: "IDEMPOTENT_IN_FLIGHT",
effect: "MAYBE_APPLIED",
retryAfterMs: 2_000,
},
});
});
it("maps a typed 409 reference problem to the feature-owned business code", async () => {
const executor = executorReturning(
Object.freeze({
kind: "PROBLEM",
problem: Object.freeze({
type: "https://example.test/problems/reference-conflict",
title: "Reference conflict",
status: 409,
code: "REFERENCE_NAME_ALREADY_EXISTS",
}),
metadata: Object.freeze({ status: 409 }),
effect: "NOT_APPLIED",
}),
);
const gateway = createReferenceHttpGateway(
createFeatureHttpBinding(executor, REFERENCE_HTTP_OPERATIONS),
);
await expect(
gateway.create({ name: "duplicate" }),
).resolves.toMatchObject({
ok: false,
error: {
kind: "CONFLICT",
code: "REFERENCE_NAME_ALREADY_EXISTS",
httpStatus: 409,
},
});
});
it.each([
{
status: 409,
code: undefined,
expectedKind: "CONFLICT",
expectedCode: "REFERENCE_RESOURCE_CONFLICT",
},
{
status: 422,
code: "REFERENCE_NAME_REJECTED",
expectedKind: "VALIDATION_REJECTED",
expectedCode: "REFERENCE_NAME_REJECTED",
},
{
status: 422,
code: undefined,
expectedKind: "VALIDATION_REJECTED",
expectedCode: "REFERENCE_RESOURCE_REJECTED",
},
{
status: 400,
code: "REFERENCE_BAD_REQUEST",
expectedKind: "UNKNOWN_CLIENT_FAILURE",
expectedCode: "CONTRACT_PROBLEM",
},
] as const)(
"projects create problem status $status through the feature-owned mapper/fallback",
async ({ status, code, expectedKind, expectedCode }) => {
const executor = executorReturning(
Object.freeze({
kind: "PROBLEM",
problem: Object.freeze({
type: "https://example.test/problems/reference-" + status,
title: "Reference request rejected",
status,
...(code === undefined ? {} : { code }),
}),
metadata: Object.freeze({ status }),
effect: "NOT_APPLIED",
}),
);
const gateway = createReferenceHttpGateway(
createFeatureHttpBinding(executor, REFERENCE_HTTP_OPERATIONS),
);
await expect(
gateway.create({ name: "rejected" }),
).resolves.toMatchObject({
ok: false,
error: {
kind: expectedKind,
code: expectedCode,
httpStatus: status,
},
});
},
);
// 백엔드 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({
kind: "PROBLEM",
problem: Object.freeze({
type: "https://example.test/problems/not-found",
title: "Not found",
status: 404,
}),
metadata: Object.freeze({ status: 404 }),
effect: "NOT_APPLIED",
}),
);
const gateway = createReferenceHttpGateway(
createFeatureHttpBinding(executor, REFERENCE_HTTP_OPERATIONS),
);
await expect(gateway.get("missing")).resolves.toMatchObject({
ok: false,
error: {
kind: "NOT_FOUND",
code: "CONTRACT_PROBLEM",
httpStatus: 404,
},
});
});
});
describe("reference create problem effect classification (0929/03-01)", () => {
const classify = (status: number, code?: string) =>
CREATE_REFERENCE_RESOURCE_CONTRACT.contract.commandEffect.classifyProblem({
status,
problem: Object.freeze({
type: "https://api.test/problems/reference",
title: "Reference problem",
status,
...(code === undefined ? {} : { code }),
}),
});
it.each([
// The first attempt with this key still runs: the key must stay bound.
{ status: 409, code: "IDEMPOTENT_IN_FLIGHT", effect: "MAYBE_APPLIED" },
// An undeclared 409 may hide a running attempt: safe side.
{ status: 409, code: "SOMETHING_NEW", effect: "MAYBE_APPLIED" },
{ status: 409, code: undefined, effect: "MAYBE_APPLIED" },
// The fixture's declared semantic conflict is the only refused 409.
{ 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)(
"classifies status $status code $code as $effect",
({ status, code, effect }) => {
expect(classify(status, code)).toBe(effect);
},
);
});