docs(contracts): rate-limit 503 뒤 IDEMPOTENT 쓰기의 자동 재전송을 계약에 적는다

문제: 계약 문서 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
This commit is contained in:
DongHyeonka
2026-11-06 05:37:11 +09:00
parent 116cbf3d06
commit 8156d85fdd
2 changed files with 63 additions and 2 deletions
@@ -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 전송뿐).
@@ -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.