From c6c37f395b6b2c05240b44caa73181f0bdfc0b65 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:18:20 +0900 Subject: [PATCH] =?UTF-8?q?fix(http):=20=EB=B0=B1=EC=97=94=EB=93=9C=20rate?= =?UTF-8?q?-limit=20503=20=EB=91=90=20code=EB=A5=BC=20=EC=93=B0=EA=B8=B0?= =?UTF-8?q?=20=EC=A0=84=20=EA=B1=B0=EC=A0=88=EB=A1=9C=20=EC=9D=BD=EB=8A=94?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 짝 백엔드 http-contract.md §4는 web 전용 code 넷을 적는다. 그중 503 RATE_LIMIT_UNAVAILABLE(저장소 응답 없음, retryable, Retry-After 있음)과 503 RATE_LIMIT_INCOMPATIBLE(제공자 불일치)이 답 표 사본에도 프론트 판정 표에도 없다. 그래서 이 503은 기능 분류기가 정하고, create:feature가 만든 쓰기의 분류기는 늘 MAYBE_APPLIED다. 아무 일도 일어나지 않은 저장이 결과 불명이 되고, NEVER 쓰기는 사실과 다른 "변경됨으로 확인"을 눌러야 폼이 풀린다(리뷰 실험 X4: 429는 NOT_APPLIED, 503 둘은 SERVER_FAILURE/MAYBE_APPLIED). pin은 §4를 대조했다고 적었지만 사본에는 REQUEST_TIMEOUT 한 행만 있었다. 고른 방법 백엔드 45d2a478을 읽기만 해서 code마다 판정했다. 두 code는 RateLimitInterceptor.preHandle이 false를 돌려주며 쓰고(Unavailable· Indeterminate → RATE_LIMIT_UNAVAILABLE, Incompatible → RATE_LIMIT_INCOMPATIBLE), main 소스에서 두 code를 내는 곳은 그 두 줄뿐이다. preHandle이 false면 handler를 부르지 않으므로 둘 다 쓰기 전이다. 백엔드는 같은 키 재전송을 요구하지 않는다(멱등성 executor 전). 그래서 답 표 사본에 refusedBeforeWrite: true, sameKeyResend: false로 두 행을 더하고, 프론트 거절 표 REFUSED_BEFORE_WRITE에 status 503과 함께 더했다. pin 테스트의 "답 표대로 읽는다" 규칙이 그대로 NOT_APPLIED를 요구하고 양방향 대조가 두 표를 함께 지킨다. kind는 지금처럼 SERVER_FAILURE(action retry)이고, KEYED도 자동 재전송은 없다(같은 키를 요구하는 답은 503 IDEMPOTENCY_UNAVAILABLE 하나다). pin의 comparedOn을 §4를 다시 대조한 날짜로 올렸다. 계약 문서 4.1·6.1절과 매뉴얼 01·02의 5xx 행 수를 고쳤다. 버린 대안 생성기 분류기가 503을 code별로 보게 한다: 생성 기능에만 고쳐지고 손으로 쓴 Envelope operation은 그대로 남는다. 판정은 백엔드 답 표 한 곳이 정한다는 지금 규칙을 따랐다. 위험·한계 - 추론(실행 확인 안 함): Spring MVC는 비동기 처리(Callable·DeferredResult) 뒤 ASYNC 재디스패치에서도 interceptor의 preHandle을 다시 부르고, 이 interceptor는 dispatcher 종류를 보지 않는다. 비동기 쓰기 컨트롤러라면 이 503(그리고 429)이 쓰기 뒤에도 나올 수 있다. 45d2a478에는 Envelope을 돌려주는 비동기 쓰기 컨트롤러가 없다(web-advanced 스트리밍과 fileserver 전송뿐). 계약 6.1절에 적었다. 백엔드에 넘길 요청: RateLimitInterceptor가 DispatcherType.REQUEST에서만 평가하게 한다. - fileserver-upload.ts는 같은 백엔드 답을 자기 표로 따로 판정한다(01 영역). 여기서는 바꾸지 않았다. - NOT_APPLIED가 되면서 IDEMPOTENT 쓰기는 이 503에 retryBudget 안에서 자동으로 다시 보낼 수 있게 됐다(503은 재시도 status다). 쓰기 전 거절이라 중복은 없다. RATE_LIMIT_INCOMPATIBLE은 백엔드가 retryable false로 보내지만 실행기는 status로 판단하므로 같은 답을 한 번 더 받을 수 있다. KEYED·NEVER는 자동 재전송이 없다. 검증 desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/backend-envelope.test.ts tests/unit/backend-contract-pin.test.ts tests/integration/http-execution-v3-envelope.test.ts Refs: 1105/03-02 --- config/contracts/backend-contract-pin.json | 2 +- .../backend-idempotency-answers.json | 14 +++++++ .../backend-api-and-server-state-contract.md | 13 ++++++- docs/manual/01-add-a-feature.md | 2 +- docs/manual/02-decision-tables.md | 4 +- src/adapters/http/backend-envelope.ts | 9 +++++ .../http-execution-v3-envelope.test.ts | 37 +++++++++++++++++++ tests/unit/backend-envelope.test.ts | 13 +++++++ 8 files changed, 89 insertions(+), 5 deletions(-) diff --git a/config/contracts/backend-contract-pin.json b/config/contracts/backend-contract-pin.json index e7a57933..0ae2d8bc 100644 --- a/config/contracts/backend-contract-pin.json +++ b/config/contracts/backend-contract-pin.json @@ -15,5 +15,5 @@ "idempotencyAnswers": "config/contracts/backend-idempotency-answers.json" }, "owner": "frontend-platform", - "comparedOn": "2026-11-04" + "comparedOn": "2026-11-05" } diff --git a/config/contracts/backend-idempotency-answers.json b/config/contracts/backend-idempotency-answers.json index 23c7c23e..57130d0e 100644 --- a/config/contracts/backend-idempotency-answers.json +++ b/config/contracts/backend-idempotency-answers.json @@ -54,6 +54,20 @@ "status": 503, "refusedBeforeWrite": false, "sameKeyResend": false + }, + { + "section": "4", + "code": "RATE_LIMIT_UNAVAILABLE", + "status": 503, + "refusedBeforeWrite": true, + "sameKeyResend": false + }, + { + "section": "4", + "code": "RATE_LIMIT_INCOMPATIBLE", + "status": 503, + "refusedBeforeWrite": true, + "sameKeyResend": false } ] } diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index b3a57096..13411fa9 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -167,7 +167,8 @@ Envelope의 모양과 키 존재 규칙은 짝 백엔드 템플릿 문서가 정 1절 "Envelope 키 존재 규칙" - 기준 커밋: 백엔드 `45d2a478`. 기계가 읽는 정본은 `config/contracts/backend-contract-pin.json`(repo, 전체 SHA, 대조한 절 §1·§2·§4, - 담당)이다. 백엔드 §2 표와 §4 `REQUEST_TIMEOUT`은 + 담당)이다. 백엔드 §2 표와 §4의 503 셋(`REQUEST_TIMEOUT`, `RATE_LIMIT_UNAVAILABLE`, + `RATE_LIMIT_INCOMPATIBLE`)은 `config/contracts/backend-idempotency-answers.json`에 code·status·쓰기 전 거절·같은 키 재전송 열로 옮겨 두었다. `tests/unit/backend-contract-pin.test.ts`가 그 표와 `backend-envelope.ts`의 판정을 양방향으로 대조한다. 값이 null인 필드는 키째 @@ -317,6 +318,16 @@ mutation이 400·409·422로 실패하면 프론트는 그 요청이 적용됐 `IDEMPOTENCY_RECOVERY_REQUIRED`, §4의 503 `REQUEST_TIMEOUT`이다. 실행기가 자동으로 다시 보내는 것은 KEYED 명령의 503 `IDEMPOTENCY_UNAVAILABLE`뿐이다. 나머지는 결과 불명 화면에서 사용자가 같은 키로 다시 보낸다. +- §4의 503 `RATE_LIMIT_UNAVAILABLE`(rate-limit 저장소 응답 없음, `Retry-After` 있음)과 + 503 `RATE_LIMIT_INCOMPATIBLE`(rate-limit 제공자가 계약과 맞지 않음)은 status와 code가 + 함께 맞으면 기능 분류기와 상관없이 `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의 + `preHandle`을 다시 부른다. 그 interceptor는 dispatcher 종류를 보지 않으므로 비동기 쓰기 + 컨트롤러라면 이 503(그리고 429)이 쓰기 뒤에도 나올 수 있다. `45d2a478`에는 Envelope을 + 돌려주는 비동기 쓰기 컨트롤러가 없다(web-advanced 스트리밍과 fileserver 전송뿐). - 파일 위치(백엔드 repo `clean-architecture-backend-template` 기준): - `GlobalExceptionHandler.java`, `HttpStatusErrorCodes.java`: `clean-architecture-backend-template/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/` - `PageParams.java`, `SortParam.java`: 같은 모듈 `.../web/pagination/` diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index 6128b020..f9285207 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -219,7 +219,7 @@ FE-REG-API 행은 descriptor에서 자동으로 만든다(`src/contracts/api-ope - 백엔드는 값이 null인 필드를 키째 뺀다. `data` 키가 없으면 `null`로 읽는다. DTO 안에서 null일 수 있는 필드는 스키마에서 `.optional()`로 받는다. - problem 스키마(`-schemas.ts`의 `ProblemSchema`)는 Envelope의 `error` 객체다. 분기는 `code`로 한다. `message`는 버린다. -- 400·409·422와 백엔드가 정한 5xx 넷이 적용됐는지는 실행기가 백엔드 기준 표로 정한다. 목록은 [02 결정표 4절](02-decision-tables.md#4-결과-불명)이다. +- 400·409·422와 백엔드가 정한 5xx 여섯이 적용됐는지는 실행기가 백엔드 기준 표로 정한다. 목록은 [02 결정표 4절](02-decision-tables.md#4-결과-불명)이다. - 업무 규칙 거절(`_INVALID`, `*_ALREADY_EXISTS` 등)은 표에 없어 결과 불명이 된다. 그 엔드포인트가 쓰기 전에만 내는 code면 `commandEffect.refusedBeforeWrite`에 적는다. 적어야 사용자가 값을 고쳐 다시 저장할 수 있다(02 결정표 4절). - `mapProblem`이 없거나 `undefined`를 돌려주면 백엔드 code·필드 오류·status별 kind로 읽는다(`src/adapters/http/backend-envelope.ts`). - 바이트 상한(`responseByteLimit`)과 구조 예산은 Envelope 전체에 걸린다. diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index 55c30c46..058309cc 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -172,8 +172,8 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 - 같은 status라도 code로 나뉠 수 있다. 예: 409 중 "처리 중"은 `MAYBE_APPLIED`여야 한다. `NOT_APPLIED`로 보면 다음 저장이 새 키를 만들어 같은 작업이 두 번 적용된다. - 401·403·429는 문제 응답 본문을 읽기 전에 status로 나뉜다. 서버가 상태를 안 바꾼다고 보장하면 `classifyStatus`로 `NOT_APPLIED`를 돌려준다. 없으면 `MAYBE_APPLIED`다. - 문제 응답 본문이 기능의 problem 스키마를 통과하지 못하면 `classifyProblem`을 부르지 않는다. 쓰기는 `MAYBE_APPLIED`가 된다(`src/adapters/http/http-execution-v3.ts`). -- `responseEnvelope: "ENVELOPE_V1"`인 operation은 400·409·422와 백엔드가 직접 정한 5xx 네 가지의 판정을 실행기가 백엔드 기준 표로 정한다(`src/adapters/http/backend-envelope.ts`의 `REFUSED_BEFORE_WRITE`, `MAYBE_APPLIED_ANSWERS`). 표의 근거는 [계약 문서](../architecture/backend-api-and-server-state-contract.md) 6.1절이다(백엔드 코드에서 code마다 쓰기 전·후를 읽은 결과). `classifyProblem`은 그 밖의 status만 받고, 다르게 답해도 표의 판정은 바뀌지 않는다. - - `NOT_APPLIED`(쓰기 전 거절): 400 `VALIDATION_FAILED`(details 모양과 상관없음), 400 `IDEMPOTENCY_KEY_INVALID`, 422 `IDEMPOTENT_REQUEST_MISMATCH` +- `responseEnvelope: "ENVELOPE_V1"`인 operation은 400·409·422와 백엔드가 직접 정한 5xx 여섯 가지의 판정을 실행기가 백엔드 기준 표로 정한다(`src/adapters/http/backend-envelope.ts`의 `REFUSED_BEFORE_WRITE`, `MAYBE_APPLIED_ANSWERS`). 표의 근거는 [계약 문서](../architecture/backend-api-and-server-state-contract.md) 6.1절이다(백엔드 코드에서 code마다 쓰기 전·후를 읽은 결과). `classifyProblem`은 그 밖의 status만 받고, 다르게 답해도 표의 판정은 바뀌지 않는다. + - `NOT_APPLIED`(쓰기 전 거절): 400 `VALIDATION_FAILED`(details 모양과 상관없음), 400 `IDEMPOTENCY_KEY_INVALID`, 422 `IDEMPOTENT_REQUEST_MISMATCH`, 503 `RATE_LIMIT_UNAVAILABLE`·`RATE_LIMIT_INCOMPATIBLE`(rate-limit 저장소 장애·제공자 불일치. 컨트롤러 전에 거절한다) - `MAYBE_APPLIED`: 그 밖의 400·409·422. 409 `IDEMPOTENT_IN_FLIGHT`, `BAD_PARAMETER`, 도메인 code, fileserver의 422가 여기 든다. 그리고 status와 code가 함께 맞는 5xx 넷: 503 `IDEMPOTENCY_UNAVAILABLE`, 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`(실행 뒤 결과 기록 실패, 새 키 금지), 500 `IDEMPOTENCY_RECOVERY_REQUIRED`(이전 시도 효과를 증명 못 함), 503 `REQUEST_TIMEOUT`(비동기 요청 시간 초과, 처리가 계속될 수 있음) - 이 넷은 실행기가 자동으로 다시 보내지 않는다. 결과 불명 화면에서 같은 키로 다시 보낸다. 예외는 KEYED 명령의 503 `IDEMPOTENCY_UNAVAILABLE` 하나다(아래) - 짝 백엔드가 모든 엔드포인트에서 쓰기 전에 거절하는 code를 새로 만들면 계약 문서 6.1절과 이 표를 함께 고친다. 표에 없으면 `MAYBE_APPLIED`다 diff --git a/src/adapters/http/backend-envelope.ts b/src/adapters/http/backend-envelope.ts index 7d9d28f8..b9e0c971 100644 --- a/src/adapters/http/backend-envelope.ts +++ b/src/adapters/http/backend-envelope.ts @@ -145,6 +145,10 @@ export function readFailureEnvelope( * answer table. Only the status and code together count. `reason` is the * diagnostics name of an idempotency refusal, named for what is wrong on * this side. + * + * 1105/03-02. And the edge rate limiter's two 503s (§4): its interceptor + * answers in `preHandle`, before the controller runs, so the command did not + * run whatever the operation's own classifier says. */ export type IdempotencyRefusalReason = | "IDEMPOTENT_REQUEST_MISMATCH" @@ -170,6 +174,11 @@ const REFUSED_BEFORE_WRITE: Readonly< status: 422, reason: "IDEMPOTENT_REQUEST_MISMATCH", }), + // §4. The rate-limit store did not answer (retryable, with Retry-After), + // or the rate-limit provider does not match the contract. Both come from + // RateLimitInterceptor.preHandle, before any handler. + RATE_LIMIT_UNAVAILABLE: Object.freeze({ status: 503 }), + RATE_LIMIT_INCOMPATIBLE: Object.freeze({ status: 503 }), }); /** diff --git a/tests/integration/http-execution-v3-envelope.test.ts b/tests/integration/http-execution-v3-envelope.test.ts index a8d35785..e5037d0e 100644 --- a/tests/integration/http-execution-v3-envelope.test.ts +++ b/tests/integration/http-execution-v3-envelope.test.ts @@ -703,6 +703,27 @@ describe("V3 Envelope verdicts follow the backend's refusal table", () => { effect: "NOT_APPLIED", }); }); + + // 1105/03-02. The edge rate limiter answers in its interceptor's preHandle, + // before the controller (http-contract.md §4). The create's own classifier + // reads every problem as maybe applied, as create:feature writes it; the + // table still says the command did not run. + it.each([ + ["RATE_LIMIT_UNAVAILABLE", "TRANSIENT_DEPENDENCY"], + ["RATE_LIMIT_INCOMPATIBLE", "INTERNAL"], + ] as const)("reads the edge's 503 %s as not applied, whatever the package says", async (code, category) => { + answer("post", "/api/envelope-items", failure(code, category, false), { + status: 503, + headers: { "Retry-After": "1" }, + }); + + await expect(v3CreateFailure().then(verdict)).resolves.toMatchObject({ + kind: "SERVER_FAILURE", + code, + httpStatus: 503, + effect: "NOT_APPLIED", + }); + }); }); // 1103/03-01. The paired backend scaffold's create checks the name before @@ -932,6 +953,22 @@ describe("KEYED resend on the backend's pre-execution refusal", () => { expect(keys).toEqual([KEY]); }); + // 1105/03-02. Not applied, but not the one answer that asks for the same + // key again: a KEYED command is not resent on its own. + it("does not resend the edge's 503 RATE_LIMIT_UNAVAILABLE on its own", async () => { + const { outcome, keys } = await run([ + () => + HttpResponse.json(failure("RATE_LIMIT_UNAVAILABLE", "TRANSIENT_DEPENDENCY", true), { + status: 503, + headers: { "Retry-After": "1" }, + }), + created, + ]); + + expect(outcome).toMatchObject({ kind: "PROBLEM", effect: "NOT_APPLIED" }); + expect(keys).toEqual([KEY]); + }); + it("does not resend a 503 the backend did not mark as a pre-execution refusal", async () => { const { outcome, keys } = await run([ () => diff --git a/tests/unit/backend-envelope.test.ts b/tests/unit/backend-envelope.test.ts index 6e2f6344..742c24af 100644 --- a/tests/unit/backend-envelope.test.ts +++ b/tests/unit/backend-envelope.test.ts @@ -48,6 +48,19 @@ describe("backend Envelope failure table", () => { expect(envelopeFailureEffect(status, { code })).toBe("MAYBE_APPLIED"); }); + // 1105/03-02. http-contract.md §4: the edge rate limiter answers before the + // controller runs. Status and code together, like the other rows. + it.each(["RATE_LIMIT_UNAVAILABLE", "RATE_LIMIT_INCOMPATIBLE"])( + "reads the edge's 503 %s as refused before the write", + (code) => { + expect(envelopeFailureEffect(503, { code })).toBe("NOT_APPLIED"); + expect(invitesKeyedResend(503, { code })).toBe(false); + expect(idempotencyRefusalReason(code, 503)).toBeUndefined(); + expect(envelopeFailureReading(503, { code }).kind).toBe("SERVER_FAILURE"); + expect(envelopeFailureEffect(500, { code })).toBeUndefined(); + }, + ); + // 1103/03-04. http-contract.md §2 and §4: the command may have run. it.each([ [503, "IDEMPOTENCY_UNAVAILABLE", true],