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:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user