From 47fec5c27c00d7ebd96bc1759ab327c69970231e Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 3 Nov 2026 01:54:36 +0900 Subject: [PATCH] =?UTF-8?q?fix(query):=20=EC=B2=98=EB=A6=AC=20=EC=A4=91=20?= =?UTF-8?q?409=EC=9D=98=20Retry-After=20=EC=A0=84=20=EC=9E=AC=EC=A0=84?= =?UTF-8?q?=EC=86=A1=EC=9D=80=20=EA=B7=B8=20=EC=8B=9C=EA=B0=81=EA=B9=8C?= =?UTF-8?q?=EC=A7=80=20=EA=B8=B0=EB=8B=A4=EB=A6=B0=EB=8B=A4=20(=EB=B0=B1?= =?UTF-8?q?=EC=97=94=EB=93=9C=201101/02-01)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 짝 백엔드는 같은 키의 첫 요청이 아직 실행 중이면 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 --- src/adapters/http/client.ts | 5 +- src/adapters/http/feature-http-binding.ts | 4 ++ .../adapters/query/application-query.ts | 24 +++++++++ .../application-mutation-admission.test.tsx | 50 ++++++++++++++++++- .../reference-http-problem-mapping.test.ts | 29 +++++++++++ .../reference-production-vertical.test.tsx | 17 +++++-- tests/integration/http-client.test.ts | 42 ++++++++++++++++ 7 files changed, 165 insertions(+), 6 deletions(-) diff --git a/src/adapters/http/client.ts b/src/adapters/http/client.ts index 45eebf80..209f9c7b 100644 --- a/src/adapters/http/client.ts +++ b/src/adapters/http/client.ts @@ -873,8 +873,9 @@ async function parseResponse( now: number, ): Promise { // 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; diff --git a/src/adapters/http/feature-http-binding.ts b/src/adapters/http/feature-http-binding.ts index f91b10e7..7f967c9e 100644 --- a/src/adapters/http/feature-http-binding.ts +++ b/src/adapters/http/feature-http-binding.ts @@ -375,6 +375,10 @@ function projectOutcome( 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 ? {} diff --git a/src/presentation/adapters/query/application-query.ts b/src/presentation/adapters/query/application-query.ts index 49ca0c1a..081f240b 100644 --- a/src/presentation/adapters/query/application-query.ts +++ b/src/presentation/adapters/query/application-query.ts @@ -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, intent: null, identityLease: null, + resendNotBefore: 0, scope: scope ?? null, optimisticLayer: null, optimisticQueryKey: optimistic?.queryKey ?? null, @@ -601,6 +615,13 @@ export function useApplicationMutation( admission.optimisticLayer = optimisticLayer; } + const resendWaitMs = + (replayed?.resendNotBefore ?? 0) - performance.now(); + if (resendWaitMs > 0) { + await new Promise((resolve) => { + setTimeout(resolve, resendWaitMs); + }); + } let value: Value; try { value = await mutation.mutateAsync(execution); @@ -634,6 +655,9 @@ export function useApplicationMutation( 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; diff --git a/tests/component/application-mutation-admission.test.tsx b/tests/component/application-mutation-admission.test.tsx index 2ddfabfa..5f386dc6 100644 --- a/tests/component/application-mutation-admission.test.tsx +++ b/tests/component/application-mutation-admission.test.tsx @@ -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> => { 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 = { @@ -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 = { + 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 = { + 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(); + } + }); }); }); diff --git a/tests/features/reference-feature/reference-http-problem-mapping.test.ts b/tests/features/reference-feature/reference-http-problem-mapping.test.ts index 2330d1e8..6ead51b4 100644 --- a/tests/features/reference-feature/reference-http-problem-mapping.test.ts +++ b/tests/features/reference-feature/reference-http-problem-mapping.test.ts @@ -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({ diff --git a/tests/features/reference-feature/reference-production-vertical.test.tsx b/tests/features/reference-feature/reference-production-vertical.test.tsx index 65534958..685119e4 100644 --- a/tests/features/reference-feature/reference-production-vertical.test.tsx +++ b/tests/features/reference-feature/reference-production-vertical.test.tsx @@ -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>(); 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(); }); diff --git a/tests/integration/http-client.test.ts b/tests/integration/http-client.test.ts index 44243efe..d1a993f6 100644 --- a/tests/integration/http-client.test.ts +++ b/tests/integration/http-client.test.ts @@ -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.