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
This commit is contained in:
@@ -873,8 +873,9 @@ async function parseResponse(
|
||||
now: number,
|
||||
): Promise<HttpResult> {
|
||||
// R3-1. Retry-After is read only where the retry policy honors it; 502/504
|
||||
// keep the local backoff.
|
||||
const retryAfterMs = [408, 425, 429, 503].includes(response.status)
|
||||
// keep the local backoff. 백엔드 1101/02-01: a 409 is never retried here,
|
||||
// but a same-key resend after it waits on its Retry-After.
|
||||
const retryAfterMs = [408, 409, 425, 429, 503].includes(response.status)
|
||||
? (parseRetryAfterDelay(response.headers.get("retry-after"), now) ??
|
||||
undefined)
|
||||
: undefined;
|
||||
|
||||
@@ -375,6 +375,10 @@ function projectOutcome<WireOutput, Problem, Value>(
|
||||
mapped?.code ?? "CONTRACT_PROBLEM",
|
||||
{
|
||||
httpStatus: outcome.metadata.status,
|
||||
// 백엔드 1101/02-01. A resend of an unknown answer waits on it.
|
||||
...(outcome.metadata.retryAfterMs === undefined
|
||||
? {}
|
||||
: { retryAfterMs: outcome.metadata.retryAfterMs }),
|
||||
effect: outcome.effect,
|
||||
...(mapped?.validationIssues === undefined
|
||||
? {}
|
||||
|
||||
@@ -271,6 +271,8 @@ type MutationAdmission = {
|
||||
intent: MutationIntent | null;
|
||||
/** Held while UNKNOWN so the same input keeps the same identity token. */
|
||||
identityLease: Readonly<{ release(): void }> | null;
|
||||
/** `performance.now()` before which a resend waits (see RESEND_WAIT_CEILING_MS). */
|
||||
resendNotBefore: number;
|
||||
scope: CacheScopeSnapshot | null;
|
||||
optimisticLayer: OptimisticLayerLease | null;
|
||||
optimisticQueryKey: readonly unknown[] | null;
|
||||
@@ -296,6 +298,17 @@ type UnknownEffectRegistry = {
|
||||
activeAdmissions: number;
|
||||
};
|
||||
|
||||
/**
|
||||
* 백엔드 1101/02-01. An unknown answer may say when to ask again: the paired
|
||||
* backend answers a same-key request while the first still runs with
|
||||
* `409 IDEMPOTENT_IN_FLIGHT` and `Retry-After: 2`. A resend (the resend
|
||||
* button, or saving the same input) before then only meets the same 409, so
|
||||
* it waits, shown as pending. The wait is capped: an early resend carries the
|
||||
* same key, so the server answers it again and never applies it twice.
|
||||
* Same ceiling as the V3 executor's own Retry-After retries.
|
||||
*/
|
||||
const RESEND_WAIT_CEILING_MS = 5_000;
|
||||
|
||||
const LEGACY_OPTIMISTIC_SCOPE = Object.freeze({
|
||||
isCurrent: () => true,
|
||||
});
|
||||
@@ -544,6 +557,7 @@ export function useApplicationMutation<Input, Value>(
|
||||
input,
|
||||
intent: null,
|
||||
identityLease: null,
|
||||
resendNotBefore: 0,
|
||||
scope: scope ?? null,
|
||||
optimisticLayer: null,
|
||||
optimisticQueryKey: optimistic?.queryKey ?? null,
|
||||
@@ -601,6 +615,13 @@ export function useApplicationMutation<Input, Value>(
|
||||
admission.optimisticLayer = optimisticLayer;
|
||||
}
|
||||
|
||||
const resendWaitMs =
|
||||
(replayed?.resendNotBefore ?? 0) - performance.now();
|
||||
if (resendWaitMs > 0) {
|
||||
await new Promise<void>((resolve) => {
|
||||
setTimeout(resolve, resendWaitMs);
|
||||
});
|
||||
}
|
||||
let value: Value;
|
||||
try {
|
||||
value = await mutation.mutateAsync(execution);
|
||||
@@ -634,6 +655,9 @@ export function useApplicationMutation<Input, Value>(
|
||||
optimisticLayer?.markUncertain();
|
||||
if (!scope || scope.isCurrent()) {
|
||||
admission.state = "UNKNOWN";
|
||||
admission.resendNotBefore =
|
||||
performance.now() +
|
||||
Math.min(failure.retryAfterMs ?? 0, RESEND_WAIT_CEILING_MS);
|
||||
if (identityLease) {
|
||||
identityLease.acquire();
|
||||
admission.identityLease = identityLease;
|
||||
|
||||
@@ -408,12 +408,14 @@ describe("application mutation intent admission", () => {
|
||||
) {
|
||||
const client = queryClient();
|
||||
const intents: MutationIntent[] = [];
|
||||
const sentAt: number[] = [];
|
||||
const execute = vi.fn(
|
||||
async (
|
||||
input: string,
|
||||
context: Readonly<{ signal: AbortSignal; intent: MutationIntent }>,
|
||||
): Promise<ApplicationResult<string>> => {
|
||||
intents.push(context.intent);
|
||||
sentAt.push(performance.now());
|
||||
return outcomes.shift() ?? { ok: true, value: input };
|
||||
},
|
||||
);
|
||||
@@ -433,7 +435,7 @@ describe("application mutation intent admission", () => {
|
||||
}),
|
||||
{ wrapper: wrapper(client) },
|
||||
);
|
||||
return { hook, intents, execute };
|
||||
return { hook, intents, execute, sentAt };
|
||||
}
|
||||
|
||||
const unknown: ApplicationResult<string> = {
|
||||
@@ -511,5 +513,51 @@ describe("application mutation intent admission", () => {
|
||||
expect(resent).toBeNull();
|
||||
expect(execute).toHaveBeenCalledTimes(3);
|
||||
});
|
||||
|
||||
// 백엔드 1101/02-01. The paired backend answers a same-key request while
|
||||
// the first still runs with 409 IDEMPOTENT_IN_FLIGHT and Retry-After.
|
||||
it("holds a resend until the Retry-After of the unknown answer", async () => {
|
||||
const inFlight: ApplicationResult<string> = {
|
||||
ok: false,
|
||||
error: createFailure("CONFLICT", "CREATE_REPLAYED", 0, {
|
||||
code: "IDEMPOTENT_IN_FLIGHT",
|
||||
effect: "MAYBE_APPLIED",
|
||||
retryAfterMs: 300,
|
||||
}),
|
||||
};
|
||||
const { hook, intents, sentAt } = renderKeyedCreate([inFlight]);
|
||||
await act(() => hook.result.current.submit("same-input"));
|
||||
|
||||
await act(async () => {
|
||||
await hook.result.current.resendUnknownEffect();
|
||||
});
|
||||
|
||||
expect(intents[1]).toBe(intents[0]);
|
||||
expect((sentAt[1] ?? 0) - (sentAt[0] ?? 0)).toBeGreaterThanOrEqual(290);
|
||||
});
|
||||
|
||||
it("waits at most the resend ceiling for a long Retry-After", async () => {
|
||||
const inFlight: ApplicationResult<string> = {
|
||||
ok: false,
|
||||
error: createFailure("CONFLICT", "CREATE_REPLAYED", 0, {
|
||||
code: "IDEMPOTENT_IN_FLIGHT",
|
||||
effect: "MAYBE_APPLIED",
|
||||
retryAfterMs: 3_600_000,
|
||||
}),
|
||||
};
|
||||
const { hook, sentAt } = renderKeyedCreate([inFlight]);
|
||||
await act(() => hook.result.current.submit("same-input"));
|
||||
vi.useFakeTimers({ toFake: ["setTimeout"] });
|
||||
try {
|
||||
await act(async () => {
|
||||
const resent = hook.result.current.resendUnknownEffect();
|
||||
await vi.advanceTimersByTimeAsync(5_000);
|
||||
await resent;
|
||||
});
|
||||
expect(sentAt).toHaveLength(2);
|
||||
} finally {
|
||||
vi.useRealTimers();
|
||||
}
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@@ -19,6 +19,35 @@ function executorReturning(
|
||||
}
|
||||
|
||||
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({
|
||||
|
||||
@@ -211,6 +211,7 @@ describe("reference feature production vertical path", () => {
|
||||
it("keeps the key when the resend meets the first attempt still in flight (0929/03-01)", async () => {
|
||||
const user = userEvent.setup();
|
||||
const idempotencyKeys: (string | null)[] = [];
|
||||
const sentAt: number[] = [];
|
||||
// A server that deduplicates by key: one receipt per created resource.
|
||||
const receipts = new Map<string, Record<string, string>>();
|
||||
let firstAttemptRunning = true;
|
||||
@@ -218,11 +219,13 @@ describe("reference feature production vertical path", () => {
|
||||
http.post("https://api.test/api/reference-resources", async ({ request }) => {
|
||||
const key = request.headers.get("idempotency-key") ?? "";
|
||||
idempotencyKeys.push(key);
|
||||
sentAt.push(performance.now());
|
||||
const receipt = receipts.get(key);
|
||||
if (receipt) {
|
||||
if (firstAttemptRunning) {
|
||||
// The paired backend answers a same-key request while the first
|
||||
// attempt still runs with 409 IDEMPOTENT_IN_FLIGHT.
|
||||
// attempt still runs with 409 IDEMPOTENT_IN_FLIGHT and
|
||||
// Retry-After (2 there; 1 here to keep the test short).
|
||||
firstAttemptRunning = false;
|
||||
return HttpResponse.json(
|
||||
{
|
||||
@@ -233,7 +236,10 @@ describe("reference feature production vertical path", () => {
|
||||
},
|
||||
{
|
||||
status: 409,
|
||||
headers: { "content-type": "application/problem+json" },
|
||||
headers: {
|
||||
"content-type": "application/problem+json",
|
||||
"retry-after": "1",
|
||||
},
|
||||
},
|
||||
);
|
||||
}
|
||||
@@ -286,12 +292,17 @@ describe("reference feature production vertical path", () => {
|
||||
conflict: screen.queryAllByText(/충돌/).length > 0,
|
||||
};
|
||||
await user.click(next);
|
||||
await waitFor(() => expect(idempotencyKeys).toHaveLength(3));
|
||||
await waitFor(() => expect(idempotencyKeys).toHaveLength(3), {
|
||||
timeout: 3_000,
|
||||
});
|
||||
|
||||
const [first] = idempotencyKeys;
|
||||
expect(idempotencyKeys).toEqual([first, first, first]);
|
||||
expect(receipts.size).toBe(1);
|
||||
expect(shownAfterInFlight).toEqual({ unknown: true, conflict: false });
|
||||
// 백엔드 1101/02-01. The click came right after the 409; the resend
|
||||
// waited out its Retry-After instead of meeting the same 409 again.
|
||||
expect((sentAt[2] ?? 0) - (sentAt[1] ?? 0)).toBeGreaterThanOrEqual(990);
|
||||
expect(await screen.findByText("저장했습니다.")).toBeVisible();
|
||||
});
|
||||
|
||||
|
||||
@@ -511,6 +511,48 @@ describe("shared HTTP client", () => {
|
||||
});
|
||||
});
|
||||
|
||||
// 백엔드 1101/02-01. The paired backend answers a same-key request while the
|
||||
// first still runs with 409 IDEMPOTENT_IN_FLIGHT, retryable and Retry-After 2.
|
||||
// The client does not resend it itself (the result is unknown); it hands the
|
||||
// Retry-After to whoever resends with the same key.
|
||||
it("keeps the Retry-After of an in-flight 409 without resending", async () => {
|
||||
let fetched = 0;
|
||||
server.use(
|
||||
http.post("https://api.test/api/entities", () => {
|
||||
fetched += 1;
|
||||
return HttpResponse.json(
|
||||
{
|
||||
success: false,
|
||||
error: {
|
||||
code: "IDEMPOTENT_IN_FLIGHT",
|
||||
category: "CONFLICT",
|
||||
message: "같은 요청을 처리하고 있습니다.",
|
||||
retryable: true,
|
||||
},
|
||||
meta: { requestId: "request-1", traceId: "trace-1" },
|
||||
},
|
||||
{ status: 409, headers: { "Retry-After": "2" } },
|
||||
);
|
||||
}),
|
||||
);
|
||||
const client = testClient({ baseUrl: "https://api.test", clock });
|
||||
|
||||
await expect(
|
||||
client.execute("CREATE_ENTITY", {
|
||||
body: { name: "n" },
|
||||
idempotencyKey: "key-1",
|
||||
}),
|
||||
).resolves.toMatchObject({
|
||||
ok: false,
|
||||
error: {
|
||||
kind: "CONFLICT",
|
||||
code: "IDEMPOTENT_IN_FLIGHT",
|
||||
retryAfterMs: 2_000,
|
||||
},
|
||||
});
|
||||
expect(fetched).toBe(1);
|
||||
});
|
||||
|
||||
// 백엔드 1101/02-02. The paired backend drops a null field together with its
|
||||
// key (its docs/web/http-contract.md §1). A missing key must read as the null
|
||||
// it stands for.
|
||||
|
||||
Reference in New Issue
Block a user