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.