From 8156d85fddd41c69f41f2ab29e20ffb04f0528a3 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 6 Nov 2026 05:37:11 +0900 Subject: [PATCH] =?UTF-8?q?docs(contracts):=20rate-limit=20503=20=EB=92=A4?= =?UTF-8?q?=20IDEMPOTENT=20=EC=93=B0=EA=B8=B0=EC=9D=98=20=EC=9E=90?= =?UTF-8?q?=EB=8F=99=20=EC=9E=AC=EC=A0=84=EC=86=A1=EC=9D=84=20=EA=B3=84?= =?UTF-8?q?=EC=95=BD=EC=97=90=20=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 계약 문서 6.1절은 §4의 503 RATE_LIMIT_UNAVAILABLE·RATE_LIMIT_INCOMPATIBLE에 "자동 재전송은 없다(KEYED도 같다)"고 적는다. 코드는 다르다. 표가 NOT_APPLIED로 정하면 retryHint는 503의 재시도 status 여부이고, 실행기는 NOT_APPLIED인 SAFE·IDEMPOTENT 요청을 retryBudget 안에서 다시 보낸다. 조립은 쓰기의 IDEMPOTENT와 retryBudget > 0을 받는다. CHANGELOG(1105/03-02 행)와 커밋 c6c37f3 본문은 코드와 같다. 그 경로를 보는 테스트가 없다. 고른 방법: 6.1절 문장을 "KEYED·NEVER는 자동 재전송이 없다. IDEMPOTENT 쓰기는 retryBudget 안에서 Retry-After(5초 이하) 뒤 다시 보낸다. status로 판단하므로 retryable: false인 RATE_LIMIT_INCOMPATIBLE도 다시 보낸다"로 고친다. 통합 테스트가 IDEMPOTENT PUT(retryBudget 1)의 503 두 code → 200을 fetch 2회, 키 없음, SUCCESS로 고정한다. 버린 대안: INCOMPATIBLE을 다시 보내지 않게 표에 "재시도 안 함"을 싣기(리뷰가 선택으로 둔 별도 동작 변경이다. 쓰기 전 거절이라 중복은 없다). 위험·한계: 동작은 바꾸지 않았다. INCOMPATIBLE은 같은 답을 한 번 더 받는다. 템플릿 안에는 IDEMPOTENT 쓰기가 없다. 이 테스트는 부모 커밋에서도 통과한다 (문서 결함이라 RED가 없다). 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/integration/http-execution-v3-envelope.test.ts, corepack pnpm verify:documentation Refs: 1106/03-02 --- .../backend-api-and-server-state-contract.md | 7 ++- .../http-execution-v3-envelope.test.ts | 58 +++++++++++++++++++ 2 files changed, 63 insertions(+), 2 deletions(-) diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index 200015ea..6845ad83 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -339,8 +339,11 @@ mutation이 400·409·422로 실패하면 프론트는 그 요청이 적용됐 함께 맞으면 기능 분류기와 상관없이 `NOT_APPLIED`다(1105/03-02, `backend-envelope.ts` `REFUSED_BEFORE_WRITE`). 백엔드 `RateLimitInterceptor.java`의 `preHandle`이 컨트롤러 전에 `false`를 돌려주며 낸다. `45d2a478`의 main 소스에서 이 두 code를 내는 곳은 그 두 - 줄뿐이다. 자동 재전송은 없다(KEYED도 같다). 남은 위험(추론, 실행 확인 안 함): Spring MVC는 - 비동기 처리(`Callable`·`DeferredResult`)가 끝난 뒤의 ASYNC 재디스패치에서도 interceptor의 + 줄뿐이다. KEYED·NEVER는 자동 재전송이 없다. IDEMPOTENT 쓰기는 `retryBudget` 안에서 + `Retry-After`(5초 이하) 뒤 다시 보낸다. 실행기는 status로 판단하므로 백엔드가 + `retryable: false`로 보내는 `RATE_LIMIT_INCOMPATIBLE`도 다시 보낸다 + (`tests/integration/http-execution-v3-envelope.test.ts`, 1106/03-02). + 남은 위험(추론, 실행 확인 안 함): Spring MVC는 비동기 처리(`Callable`·`DeferredResult`)가 끝난 뒤의 ASYNC 재디스패치에서도 interceptor의 `preHandle`을 다시 부른다. 그 interceptor는 dispatcher 종류를 보지 않으므로 비동기 쓰기 컨트롤러라면 이 503(그리고 429)이 쓰기 뒤에도 나올 수 있다. `45d2a478`에는 Envelope을 돌려주는 비동기 쓰기 컨트롤러가 없다(web-advanced 스트리밍과 fileserver 전송뿐). diff --git a/tests/integration/http-execution-v3-envelope.test.ts b/tests/integration/http-execution-v3-envelope.test.ts index e5037d0e..c98f6bf6 100644 --- a/tests/integration/http-execution-v3-envelope.test.ts +++ b/tests/integration/http-execution-v3-envelope.test.ts @@ -983,6 +983,64 @@ describe("KEYED resend on the backend's pre-execution refusal", () => { }); }); +// 1106/03-02. The edge rate limiter's 503 is refused before the write, so +// an IDEMPOTENT write, which the executor may send again after dispatch, is +// resent within its retryBudget after Retry-After (contract 6.1). The status +// decides, so the INCOMPATIBLE answer the backend marks not retryable is +// resent too. KEYED and NEVER are not (above). +describe("IDEMPOTENT write on the edge's rate-limit 503", () => { + const RENAME_CONTRACT = Object.freeze({ + contract: Object.freeze({ + ...CREATE_CONTRACT.contract, + operationId: "ENVELOPE_RENAME_ITEM", + method: "PUT" as const, + pathTemplate: "/api/envelope-items/item-1", + acceptedStatuses: Object.freeze([200]), + retrySemantics: "IDEMPOTENT" as const, + commandRecovery: null, + }), + frontend: Object.freeze({ + ...CREATE_CONTRACT.frontend, + policyId: "ENVELOPE_RENAME_V1", + retryBudget: 1 as const, + diagnosticsOperation: "envelope.rename", + }), + }); + + it.each([ + ["RATE_LIMIT_UNAVAILABLE", "TRANSIENT_DEPENDENCY", true], + ["RATE_LIMIT_INCOMPATIBLE", "INTERNAL", false], + ] as const)("sends the write again after 503 %s", async (code, category, retryable) => { + const keys: (string | null)[] = []; + server.use( + http.put(`${BASE_URL}/api/envelope-items/item-1`, ({ request }) => { + keys.push(request.headers.get("idempotency-key")); + return keys.length === 1 + ? HttpResponse.json(failure(code, category, retryable), { + status: 503, + headers: { "Retry-After": "1" }, + }) + : HttpResponse.json(success({ id: "item-1", name: "Renamed" })); + }), + ); + const executor = createContractHttpExecutor({ + baseUrl: BASE_URL, + maxRetryAttempts: 2, + attachCredentials: () => ({ kind: "READY" as const, headers: {} }), + sleep: async () => {}, + random: () => 0, + }); + + const outcome = await executor.execute(RENAME_CONTRACT, Object.freeze({}), { + routeId: "ENVELOPE_ROUTE", + scope: scope(), + }); + + expect(outcome).toMatchObject({ kind: "SUCCESS", effect: "APPLIED_CONFIRMED" }); + expect(keys).toEqual([null, null]); + }); +}); + // 1103/10-02. A failure Envelope is read under the operation's own response // limit and media type, not only the problem ceiling. Native Responses: MSW // never settles a cancel() on a body it is still streaming.