refactor(ratelimit): policyId 문법과 기간 검사를 shared-contract 한 곳에 둔다 #93

Merged
donghyeon.kang merged 4 commits from refactor/ratelimit-shared-bounds into main 2026-11-22 00:51:34 +00:00
Owner

무엇을, 왜

커밋 셋이다. 첫 커밋이 사본을 지우고, 둘째가 시험 하나를 더하고, 셋째가 Javadoc을 고친다.

  • 문제 (REV-BE-0040): policyId 정규식 [a-z][a-z0-9-]{0,62}가 rate-limit main 코드에 네 벌 있다.
    • shared-contract RateLimitBounds(정본), cache-redis RateLimitPolicyBounds, web EdgeRateLimitTransportBridge·EdgeRateLimitTransportSettings다.
    • redis 사본은 policyRevision 문법과 기간 검사(null·음수·0·상한·toMillis·whole-ms, 순서와 메시지까지)도 줄 단위로 베꼈다.
    • 정본 RateLimitBounds가 package-private이라 다른 패키지에서 부를 수 없어서 생긴 사본이다.
    • 한 곳만 문법을 바꾸면 web 설정이 받아들인 id를 RateLimitRequest가 실행 중에 거절하는 엇갈림이 생긴다. 지금 시험은 이 엇갈림을 잡지 못한다(아래 RED의 pre 행).
  • refactor(ratelimit) 9df5cad4: 사본을 지우고 정본 한 곳을 부른다.
    • RateLimitBounds를 public으로 열고 policyId·policyRevision·positiveDuration·nonNegativeDuration을 public으로 둔다.
    • 자기 말로 거절을 알리는 쪽을 위해 isPolicyId(null이면 false)를 더한다.
    • subjectDigest·optionalEvaluationId와 상수는 그대로 package-private이다.
    • redis RateLimitPolicy·RateLimitEvaluationDedupPolicy는 정본을 부른다. RateLimitPolicyBounds에는 redis만의 상한 상수 둘만 남는다.
    • web 둘은 isPolicyId를 부르고 자기 오류 메시지(policyId|defaultPolicyId must be a bounded policy identifier)와 null 처리(IAE)를 그대로 둔다.
    • 시험: shared-contract RateLimitBoundsTest(isPolicyId 표), redis RateLimitPolicyTest·web EdgeRateLimitTransportSettingsTest에 문법 밖 id 네 행(대문자, 밑줄, 숫자로 시작, 64자) 거절. redis에는 policyId 거절 시험이 없었다.
  • test(ratelimit) b64518f9 (리뷰 반영): web Bridge 시험이 정상 id 하나만 봐서, Bridge의 policyId 검사를 지워도 통과했다.
    • EdgeRateLimitTransportBridgeTest.refusesAPolicyIdOutsideTheSharedGrammar: @NullSource + 같은 네 행. 예외 타입과 메시지를 함께 단언한다.
    • RateLimitBoundsTest 설명을 시험이 실제로 보는 것(「isPolicyId가 문법에 답한다」)으로 줄였다.
  • docs(ratelimit) bb1f32d7 (리뷰 반영): 주석만 바뀐다.
    • isPolicyId의 @return에 true 조건을 적는다.
    • RateLimitPolicyBounds 설명의 이유를 둘로 나눈다: 문법은 요청이 같은 id로 policy를 부르기 때문이고, 기간 검사는 양수·상한·whole-ms 규칙을 한 벌만 두려는 것이다. dedup 상한의 위치(RateLimitEvaluationDedupPolicy)도 적는다.

고른 방법과 버린 대안

  • 정본을 public으로 연다. 정본이 이미 shared-contract에 있고, web·redis 둘 다 shared-contract에 기대고 있다(registry 허용 의존 그대로). 새 의존 edge가 없다.
  • web은 policyId() 대신 isPolicyId predicate를 쓴다(카드와 다르게 한 것). policyId()는 null에 NPE, 문법 밖에 policyId has an invalid bounded representation을 던진다. web은 null도 IAE로, 메시지도 자기 것으로 내 왔다. 카드 「바꾸지 말 것」(정규식 문법과 오류 메시지)을 지키려면 판정만 빌리고 거절은 web이 한다.
  • 버린 안:
    • 사본 사이에 같은 값을 보는 대조 시험. 사본을 두는 비용(문법을 네 곳에서 고치는 것)이 그대로 남는다.
    • RateLimitPolicyId 값 타입. 공개 타입과 호출부가 더 많이 바뀐다.
    • RateLimitPolicyBounds의 상수 둘을 RateLimitPolicy로 옮기고 클래스를 지우기(리뷰 선택안). diff가 넓어지는 데 비해 얻는 동작이 없다.
    • web EdgeRateLimitTransportBridge.positiveBoundedBudget(:72-84)을 positiveDuration으로 합치기. 검사는 같지만 메시지가 달라 카드 「메시지 바꾸지 말 것」에 걸린다. 그대로 두고 넘긴다.

위험과 영향

  • 동작: 정규식 문법과 오류 메시지는 바뀌지 않는다. redis가 정본을 부르게 됐지만, 지운 사본은 정본과 같은 순서·같은 메시지였다. 기존 redis·web 시험이 그대로 통과한다(아래 검증).
  • 공개 API가 늘어난다: shared-contract에 public 클래스 하나(RateLimitBounds)와 public 메서드 다섯(isPolicyId·policyId·policyRevision·positiveDuration·nonNegativeDuration)이 생긴다.
    • 깨지는 변경이 아니다. 더하기만 한다. 지운 redis 메서드 넷은 base에서 package-private 클래스(final class RateLimitPolicyBounds)의 package-private 멤버라 파생 서비스가 부를 수 없었다.
    • 그래서 제목에 !·BREAKING CHANGE를 달지 않고 docs/upgrade/ 행도 더하지 않는다. 기준: docs/work/operate.md:114(파생 서비스가 따라 고쳐야 하는 변경만 안내와 !), commit-and-pr.md 3.2 「호환을 깨는 변경」.
    • 한 번 열면 다시 닫는 것이 깨지는 변경이 된다. shared-contract에는 API surface 스냅숏이 없어 이 공개를 기계가 지키지는 않는다.
  • 범위 밖으로 둔 것: application-core LeaseValidation.java:30에 같은 정규식이 있다. lease 식별자라 rate-limit 문법과 같은 규칙인지 따로 정할 일이다(아래 「관련」).

검증

RED·GREEN은 desktop 드라이버(red.sh)로 돌렸다. 로그는 desktop ~/be-lane-n8-red-logs/다.

  • 명령: flock /tmp/claude-gates/heavy.lock ./gradlew <task> --tests <class>… --continue --no-daemon --console=plain --no-build-cache. task는 :shared-contract:test(RateLimitBoundsTest), :adapter:outbound:cache-redis:test(RateLimitPolicyTest), :adapter:inbound:web:test(EdgeRateLimitTransportSettingsTest·EdgeRateLimitTransportBridgeTest)다.
  • pre(고치기 전 코드): base 92ae78f8에 이 PR의 redis·web 시험 셋만 얹은 트리 5facb917f2ace2dddbb0a4ad69e27c8a34715f85다. RateLimitBoundsTest는 base에 없는 isPolicyId를 불러 뺐다. 변이는 base 정본 RateLimitBounds.java:13에 넣었다.
  • head: bb1f32d7(트리 ce8263ab73c6e9f089253b3f2e3edd6ea194b30c, 노트북 HEAD 트리와 같음). 변이는 정본 RateLimitBounds.java:21에 넣었다.
실행 변이(정본 정규식 한 줄) 트리 rc 결과
pre-green 없음 5facb917 0 redis 12·web 6+6 통과
pre-m1 {0,62} → {0,63} ec994507 0 모두 통과(redis·web는 자기 사본을 본다)
pre-m2 [a-z0-9-] → [a-z0-9_-] 95c051fa 0 모두 통과
pre-m3 첫 글자 [a-z] → [a-z0-9] 708137db 0 모두 통과
green 없음 ce8263ab 0 shared 8·redis 12·web 6+6 통과
m1 {0,62} → {0,63} bd0a5d4b 1 네 클래스 모두 64자 행 실패
m2 [a-z0-9-] → [a-z0-9_-] a946cd0a 1 네 클래스 모두 under_score 행 실패
m3 첫 글자 [a-z] → [a-z0-9] 9320c355 1 네 클래스 모두 9-digit-first 행 실패
  • m 행의 실패 시험: RateLimitBoundsTest.isPolicyIdAnswersThePolicyIdGrammar, RateLimitPolicyTest.rejectsAPolicyIdOutsideTheSharedGrammar, EdgeRateLimitTransportSettingsTest.rejectsADefaultPolicyIdOutsideTheSharedGrammar, EdgeRateLimitTransportBridgeTest.refusesAPolicyIdOutsideTheSharedGrammar. 변이마다 클래스당 1건이다.
  • 변이 로그 여덟 개 모두 error: 0줄이다. 실패는 컴파일 오류가 아니라 단언 실패다.
  • pre와 m을 같이 보면: 고치기 전에는 정본 문법을 바꿔도 redis·web이 모른다. 고친 뒤에는 세 모듈이 함께 실패한다.

gate(노트북 깨끗한 detached worktree, 트리 ce8263ab73c6, HEAD 트리와 같음):

  • desktop scripts/verify.sh leaf :shared-contract --no-cache --log be-lane-n9-p3-shared: rc=0, tests=280 failures=0 errors=0 skipped=0, FROM-CACHE 0
  • desktop scripts/verify.sh leaf :adapter:outbound:cache-redis --no-cache --log be-lane-n9-p3-redis: rc=0, tests=238 failures=0 errors=0 skipped=0, FROM-CACHE 0
  • desktop scripts/verify.sh leaf :adapter:inbound:web --no-cache --log be-lane-n9-p3-web: rc=0, tests=385 failures=0 errors=0 skipped=0, FROM-CACHE 0
  • desktop scripts/verify.sh pr --no-cache --log be-lane-n9-p3-pr: rc=0, tests=7374 failures=0 errors=0 skipped=35, FROM-CACHE 0
  • 노트북 scripts/verify.sh docs: rc=0
  • main 전용 lane(docs/work/reference/gates.md 1절). 바꾼 main 소스가 두 lane의 입력에 들어가서 desktop에서 같은 커밋으로 돌렸다(flock /tmp/claude-gates/heavy.lock ./gradlew <task> --no-daemon --console=plain --no-build-cache, Docker 사용).
    • :adapter:outbound:cache-redis:redisContainerContractTest: rc=0, BUILD SUCCESSFUL in 2m 21s, tests=103 failures=0
    • :adapter:inbound:web:systemTestLaneCheck(systemTest + webJettyCompatTest): rc=0, BUILD SUCCESSFUL in 42s, systemTest tests=19·webJettyCompatTest tests=16 failures=0
    • lane 근거: src/adapter/outbound/cache-redis/build.gradle:79-98, src/adapter/inbound/web/build.gradle:151-180, 루트 build.gradle:104-136. performance lane은 nightly라 돌리지 않았다.
  • C1: git grep -n -E '\[a-z\]\[a-z0-9-\]\{0,62\}' -- 'src/**/main/**.java'는 rate-limit 쪽에서 RateLimitBounds.java:21 한 곳만 낸다. 나머지 한 줄은 lease LeaseValidation.java:30이다(아래 「관련」). base에서는 rate-limit 쪽 넷이었다.
  • 열기 전 origin/main은 8f182faa(#91)다. git merge-tree --write-tree origin/main HEAD는 충돌 없이 트리 f3ccc620을 냈다. base 뒤 main 변경에 ratelimit 파일은 없다. 위 gate는 base 92ae78f8 위의 이 브랜치 트리에서 돌렸다.
  • PR run pr / done: run 550(head bb1f32d7) success

리뷰어가 볼 곳

  • RateLimitBounds.java: 공개한 범위. public 다섯과 package-private로 남긴 것(subjectDigest·optionalEvaluationId·상수)의 경계.
  • EdgeRateLimitTransportBridge.java:47·EdgeRateLimitTransportSettings.java:24: isPolicyId로 바꾼 줄. 메시지와 null 처리가 base와 같은지.
  • 세 모듈 시험의 문법 밖 네 행이 같은 값인지(RateLimitBoundsTest·RateLimitPolicyTest·EdgeRateLimitTransportSettingsTest·EdgeRateLimitTransportBridgeTest). 같아야 정본 변이에 셋이 함께 실패한다.

리뷰 반영

  • 종류 B, 리뷰 1회(세션 기본 모델 Opus 5.5, 병렬 둘): reviewer(렌즈 be-api-contract·be-testing) Low 2, arch-reviewer(be-domain) HARD-STOP 위반 없음·Low 4. Medium 이상 0이라 확인 리뷰 0회.
    • reviewer Low1(Bridge 검사를 지워도 시험 통과): b64518f9.
    • reviewer Low2(RateLimitBoundsTest 설명이 시험보다 넓다): b64518f9.
    • arch Low2·3(RateLimitPolicyBounds 설명의 이유·dedup 상한 위치), Low4(isPolicyId @return): bb1f32d7.
    • arch Low1(src/shared-contract/AGENTS.md:42-43 ratelimit 줄에 공용 문법 정본이라는 말이 없다): 지침 파일이라 이 PR에서 고치지 않고 넘긴다.

관련

  • 리뷰 항목 REV-BE-0040(묶음 REV-BE-0047 be4-core의 PR 3)
  • 넘긴 것(이 diff 밖):
    • src/application/core/src/main/java/dev/caskeleton/application/lease/LeaseValidation.java:30(같은 정규식)과 :43-70(양수·상한·whole-ms 기간 검사 한 벌, 메시지 다름). lease 식별자가 같은 규칙인지 be-domain이 정할 일이다. lease가 ratelimit.RateLimitBounds를 부르는 방향은 피한다.
    • src/shared-contract/AGENTS.md:42-43: ratelimit 줄에 RateLimitBounds가 공용 문법 정본이라는 말 더하기(지침 파일).
    • docs/capability-status.md:501이 RateLimitBounds.MAXIMUM_CLEANUP_GRACE라 적지만 그 상수는 redis RateLimitPolicyBounds에 있다.
    • web EdgeRateLimitTransportBridge.java:72-84 positiveBoundedBudget이 positiveDuration과 같은 검사를 다른 메시지로 한다.
    • EdgeRateLimitTransportSettingsTest.java:27 rejectsUnboundedPolicyAndDeadlineValues(기존 시험)가 when 셋과 hasMessageContaining을 쓴다(.claude/rules/java-tests.md 3·5).
## 무엇을, 왜 커밋 셋이다. 첫 커밋이 사본을 지우고, 둘째가 시험 하나를 더하고, 셋째가 Javadoc을 고친다. - **문제 (REV-BE-0040):** policyId 정규식 `[a-z][a-z0-9-]{0,62}`가 rate-limit main 코드에 네 벌 있다. - shared-contract `RateLimitBounds`(정본), cache-redis `RateLimitPolicyBounds`, web `EdgeRateLimitTransportBridge`·`EdgeRateLimitTransportSettings`다. - redis 사본은 policyRevision 문법과 기간 검사(null·음수·0·상한·`toMillis`·whole-ms, 순서와 메시지까지)도 줄 단위로 베꼈다. - 정본 `RateLimitBounds`가 package-private이라 다른 패키지에서 부를 수 없어서 생긴 사본이다. - 한 곳만 문법을 바꾸면 web 설정이 받아들인 id를 `RateLimitRequest`가 실행 중에 거절하는 엇갈림이 생긴다. 지금 시험은 이 엇갈림을 잡지 못한다(아래 RED의 pre 행). - **`refactor(ratelimit)` 9df5cad4:** 사본을 지우고 정본 한 곳을 부른다. - `RateLimitBounds`를 public으로 열고 `policyId`·`policyRevision`·`positiveDuration`·`nonNegativeDuration`을 public으로 둔다. - 자기 말로 거절을 알리는 쪽을 위해 `isPolicyId`(null이면 false)를 더한다. - `subjectDigest`·`optionalEvaluationId`와 상수는 그대로 package-private이다. - redis `RateLimitPolicy`·`RateLimitEvaluationDedupPolicy`는 정본을 부른다. `RateLimitPolicyBounds`에는 redis만의 상한 상수 둘만 남는다. - web 둘은 `isPolicyId`를 부르고 자기 오류 메시지(`policyId|defaultPolicyId must be a bounded policy identifier`)와 null 처리(IAE)를 그대로 둔다. - 시험: shared-contract `RateLimitBoundsTest`(`isPolicyId` 표), redis `RateLimitPolicyTest`·web `EdgeRateLimitTransportSettingsTest`에 문법 밖 id 네 행(대문자, 밑줄, 숫자로 시작, 64자) 거절. redis에는 policyId 거절 시험이 없었다. - **`test(ratelimit)` b64518f9 (리뷰 반영):** web Bridge 시험이 정상 id 하나만 봐서, Bridge의 policyId 검사를 지워도 통과했다. - `EdgeRateLimitTransportBridgeTest.refusesAPolicyIdOutsideTheSharedGrammar`: `@NullSource` + 같은 네 행. 예외 타입과 메시지를 함께 단언한다. - `RateLimitBoundsTest` 설명을 시험이 실제로 보는 것(「`isPolicyId`가 문법에 답한다」)으로 줄였다. - **`docs(ratelimit)` bb1f32d7 (리뷰 반영):** 주석만 바뀐다. - `isPolicyId`의 `@return`에 true 조건을 적는다. - `RateLimitPolicyBounds` 설명의 이유를 둘로 나눈다: 문법은 요청이 같은 id로 policy를 부르기 때문이고, 기간 검사는 양수·상한·whole-ms 규칙을 한 벌만 두려는 것이다. dedup 상한의 위치(`RateLimitEvaluationDedupPolicy`)도 적는다. ## 고른 방법과 버린 대안 - **정본을 public으로 연다.** 정본이 이미 shared-contract에 있고, web·redis 둘 다 shared-contract에 기대고 있다(registry 허용 의존 그대로). 새 의존 edge가 없다. - **web은 `policyId()` 대신 `isPolicyId` predicate를 쓴다(카드와 다르게 한 것).** `policyId()`는 null에 NPE, 문법 밖에 `policyId has an invalid bounded representation`을 던진다. web은 null도 IAE로, 메시지도 자기 것으로 내 왔다. 카드 「바꾸지 말 것」(정규식 문법과 오류 메시지)을 지키려면 판정만 빌리고 거절은 web이 한다. - 버린 안: - 사본 사이에 같은 값을 보는 대조 시험. 사본을 두는 비용(문법을 네 곳에서 고치는 것)이 그대로 남는다. - `RateLimitPolicyId` 값 타입. 공개 타입과 호출부가 더 많이 바뀐다. - `RateLimitPolicyBounds`의 상수 둘을 `RateLimitPolicy`로 옮기고 클래스를 지우기(리뷰 선택안). diff가 넓어지는 데 비해 얻는 동작이 없다. - web `EdgeRateLimitTransportBridge.positiveBoundedBudget`(`:72-84`)을 `positiveDuration`으로 합치기. 검사는 같지만 메시지가 달라 카드 「메시지 바꾸지 말 것」에 걸린다. 그대로 두고 넘긴다. ## 위험과 영향 - **동작:** 정규식 문법과 오류 메시지는 바뀌지 않는다. redis가 정본을 부르게 됐지만, 지운 사본은 정본과 같은 순서·같은 메시지였다. 기존 redis·web 시험이 그대로 통과한다(아래 검증). - **공개 API가 늘어난다:** shared-contract에 public 클래스 하나(`RateLimitBounds`)와 public 메서드 다섯(`isPolicyId`·`policyId`·`policyRevision`·`positiveDuration`·`nonNegativeDuration`)이 생긴다. - 깨지는 변경이 아니다. 더하기만 한다. 지운 redis 메서드 넷은 base에서 package-private 클래스(`final class RateLimitPolicyBounds`)의 package-private 멤버라 파생 서비스가 부를 수 없었다. - 그래서 제목에 `!`·`BREAKING CHANGE`를 달지 않고 `docs/upgrade/` 행도 더하지 않는다. 기준: `docs/work/operate.md:114`(파생 서비스가 따라 고쳐야 하는 변경만 안내와 `!`), commit-and-pr.md 3.2 「호환을 깨는 변경」. - 한 번 열면 다시 닫는 것이 깨지는 변경이 된다. shared-contract에는 API surface 스냅숏이 없어 이 공개를 기계가 지키지는 않는다. - **범위 밖으로 둔 것:** application-core `LeaseValidation.java:30`에 같은 정규식이 있다. lease 식별자라 rate-limit 문법과 같은 규칙인지 따로 정할 일이다(아래 「관련」). ## 검증 RED·GREEN은 desktop 드라이버(`red.sh`)로 돌렸다. 로그는 desktop `~/be-lane-n8-red-logs/`다. - 명령: `flock /tmp/claude-gates/heavy.lock ./gradlew <task> --tests <class>… --continue --no-daemon --console=plain --no-build-cache`. task는 `:shared-contract:test`(`RateLimitBoundsTest`), `:adapter:outbound:cache-redis:test`(`RateLimitPolicyTest`), `:adapter:inbound:web:test`(`EdgeRateLimitTransportSettingsTest`·`EdgeRateLimitTransportBridgeTest`)다. - **pre**(고치기 전 코드): base 92ae78f8에 이 PR의 redis·web 시험 셋만 얹은 트리 `5facb917f2ace2dddbb0a4ad69e27c8a34715f85`다. `RateLimitBoundsTest`는 base에 없는 `isPolicyId`를 불러 뺐다. 변이는 base 정본 `RateLimitBounds.java:13`에 넣었다. - **head**: bb1f32d7(트리 `ce8263ab73c6e9f089253b3f2e3edd6ea194b30c`, 노트북 HEAD 트리와 같음). 변이는 정본 `RateLimitBounds.java:21`에 넣었다. | 실행 | 변이(정본 정규식 한 줄) | 트리 | rc | 결과 | |---|---|---|---|---| | pre-green | 없음 | `5facb917` | 0 | redis 12·web 6+6 통과 | | pre-m1 | `{0,62}` → `{0,63}` | `ec994507` | 0 | 모두 통과(redis·web는 자기 사본을 본다) | | pre-m2 | `[a-z0-9-]` → `[a-z0-9_-]` | `95c051fa` | 0 | 모두 통과 | | pre-m3 | 첫 글자 `[a-z]` → `[a-z0-9]` | `708137db` | 0 | 모두 통과 | | green | 없음 | `ce8263ab` | 0 | shared 8·redis 12·web 6+6 통과 | | m1 | `{0,62}` → `{0,63}` | `bd0a5d4b` | 1 | 네 클래스 모두 64자 행 실패 | | m2 | `[a-z0-9-]` → `[a-z0-9_-]` | `a946cd0a` | 1 | 네 클래스 모두 `under_score` 행 실패 | | m3 | 첫 글자 `[a-z]` → `[a-z0-9]` | `9320c355` | 1 | 네 클래스 모두 `9-digit-first` 행 실패 | - m 행의 실패 시험: `RateLimitBoundsTest.isPolicyIdAnswersThePolicyIdGrammar`, `RateLimitPolicyTest.rejectsAPolicyIdOutsideTheSharedGrammar`, `EdgeRateLimitTransportSettingsTest.rejectsADefaultPolicyIdOutsideTheSharedGrammar`, `EdgeRateLimitTransportBridgeTest.refusesAPolicyIdOutsideTheSharedGrammar`. 변이마다 클래스당 1건이다. - 변이 로그 여덟 개 모두 `error:` 0줄이다. 실패는 컴파일 오류가 아니라 단언 실패다. - pre와 m을 같이 보면: 고치기 전에는 정본 문법을 바꿔도 redis·web이 모른다. 고친 뒤에는 세 모듈이 함께 실패한다. gate(노트북 깨끗한 detached worktree, 트리 `ce8263ab73c6`, HEAD 트리와 같음): - desktop `scripts/verify.sh leaf :shared-contract --no-cache --log be-lane-n9-p3-shared`: rc=0, tests=280 failures=0 errors=0 skipped=0, FROM-CACHE 0 - desktop `scripts/verify.sh leaf :adapter:outbound:cache-redis --no-cache --log be-lane-n9-p3-redis`: rc=0, tests=238 failures=0 errors=0 skipped=0, FROM-CACHE 0 - desktop `scripts/verify.sh leaf :adapter:inbound:web --no-cache --log be-lane-n9-p3-web`: rc=0, tests=385 failures=0 errors=0 skipped=0, FROM-CACHE 0 - desktop `scripts/verify.sh pr --no-cache --log be-lane-n9-p3-pr`: rc=0, tests=7374 failures=0 errors=0 skipped=35, FROM-CACHE 0 - 노트북 `scripts/verify.sh docs`: rc=0 - main 전용 lane(`docs/work/reference/gates.md` 1절). 바꾼 main 소스가 두 lane의 입력에 들어가서 desktop에서 같은 커밋으로 돌렸다(`flock /tmp/claude-gates/heavy.lock ./gradlew <task> --no-daemon --console=plain --no-build-cache`, Docker 사용). - `:adapter:outbound:cache-redis:redisContainerContractTest`: rc=0, `BUILD SUCCESSFUL in 2m 21s`, tests=103 failures=0 - `:adapter:inbound:web:systemTestLaneCheck`(`systemTest` + `webJettyCompatTest`): rc=0, `BUILD SUCCESSFUL in 42s`, systemTest tests=19·webJettyCompatTest tests=16 failures=0 - lane 근거: `src/adapter/outbound/cache-redis/build.gradle:79-98`, `src/adapter/inbound/web/build.gradle:151-180`, 루트 `build.gradle:104-136`. performance lane은 nightly라 돌리지 않았다. - C1: `git grep -n -E '\[a-z\]\[a-z0-9-\]\{0,62\}' -- 'src/**/main/**.java'`는 rate-limit 쪽에서 `RateLimitBounds.java:21` 한 곳만 낸다. 나머지 한 줄은 lease `LeaseValidation.java:30`이다(아래 「관련」). base에서는 rate-limit 쪽 넷이었다. - 열기 전 origin/main은 8f182faa(#91)다. `git merge-tree --write-tree origin/main HEAD`는 충돌 없이 트리 `f3ccc620`을 냈다. base 뒤 main 변경에 ratelimit 파일은 없다. 위 gate는 base 92ae78f8 위의 이 브랜치 트리에서 돌렸다. - PR run `pr / done`: run 550(head bb1f32d7) success ## 리뷰어가 볼 곳 - `RateLimitBounds.java`: 공개한 범위. public 다섯과 package-private로 남긴 것(`subjectDigest`·`optionalEvaluationId`·상수)의 경계. - `EdgeRateLimitTransportBridge.java:47`·`EdgeRateLimitTransportSettings.java:24`: `isPolicyId`로 바꾼 줄. 메시지와 null 처리가 base와 같은지. - 세 모듈 시험의 문법 밖 네 행이 같은 값인지(`RateLimitBoundsTest`·`RateLimitPolicyTest`·`EdgeRateLimitTransportSettingsTest`·`EdgeRateLimitTransportBridgeTest`). 같아야 정본 변이에 셋이 함께 실패한다. ## 리뷰 반영 - 종류 B, 리뷰 1회(세션 기본 모델 Opus 5.5, 병렬 둘): `reviewer`(렌즈 be-api-contract·be-testing) Low 2, `arch-reviewer`(be-domain) HARD-STOP 위반 없음·Low 4. Medium 이상 0이라 확인 리뷰 0회. - reviewer Low1(Bridge 검사를 지워도 시험 통과): b64518f9. - reviewer Low2(`RateLimitBoundsTest` 설명이 시험보다 넓다): b64518f9. - arch Low2·3(`RateLimitPolicyBounds` 설명의 이유·dedup 상한 위치), Low4(`isPolicyId` `@return`): bb1f32d7. - arch Low1(`src/shared-contract/AGENTS.md:42-43` ratelimit 줄에 공용 문법 정본이라는 말이 없다): 지침 파일이라 이 PR에서 고치지 않고 넘긴다. ## 관련 - 리뷰 항목 REV-BE-0040(묶음 REV-BE-0047 be4-core의 PR 3) - 넘긴 것(이 diff 밖): - `src/application/core/src/main/java/dev/caskeleton/application/lease/LeaseValidation.java:30`(같은 정규식)과 `:43-70`(양수·상한·whole-ms 기간 검사 한 벌, 메시지 다름). lease 식별자가 같은 규칙인지 be-domain이 정할 일이다. lease가 `ratelimit.RateLimitBounds`를 부르는 방향은 피한다. - `src/shared-contract/AGENTS.md:42-43`: ratelimit 줄에 `RateLimitBounds`가 공용 문법 정본이라는 말 더하기(지침 파일). - `docs/capability-status.md:501`이 `RateLimitBounds.MAXIMUM_CLEANUP_GRACE`라 적지만 그 상수는 redis `RateLimitPolicyBounds`에 있다. - web `EdgeRateLimitTransportBridge.java:72-84` `positiveBoundedBudget`이 `positiveDuration`과 같은 검사를 다른 메시지로 한다. - `EdgeRateLimitTransportSettingsTest.java:27` `rejectsUnboundedPolicyAndDeadlineValues`(기존 시험)가 when 셋과 `hasMessageContaining`을 쓴다(`.claude/rules/java-tests.md` 3·5).
donghyeon.kang added 3 commits 2026-11-21 23:27:47 +00:00
policyId 정규식([a-z][a-z0-9-]{0,62})이 rate-limit main에 네 벌
있었다. shared-contract RateLimitBounds, cache-redis
RateLimitPolicyBounds, web EdgeRateLimitTransportBridge·
EdgeRateLimitTransportSettings다. redis 사본은 policyRevision과
duration 검사(null·음수·0·상한·toMillis·whole-ms 순서와 메시지)도
줄 단위로 베꼈다. 정본 RateLimitBounds가 package-private이라 다른
패키지에서 부를 수 없어서다. 한 곳만 문법을 바꾸면 web 설정이 받아들인
id를 RateLimitRequest가 실행 중에 거절하는 엇갈림이 생긴다.

- RateLimitBounds를 public으로 열고 policyId·policyRevision·
  positiveDuration·nonNegativeDuration을 public으로 둔다. 자기 말로
  거절을 알리는 쪽을 위해 isPolicyId(null이면 false)를 더한다.
  subjectDigest·optionalEvaluationId와 상수는 그대로 package-private이다.
- redis RateLimitPolicy·RateLimitEvaluationDedupPolicy는 정본을 부르고,
  RateLimitPolicyBounds에는 redis만의 상한 상수 둘만 남긴다.
- web 둘은 isPolicyId를 부르고 자기 오류 메시지("policyId|defaultPolicyId
  must be a bounded policy identifier")와 null 처리(IAE)를 그대로 둔다.
- 시험: shared-contract RateLimitBoundsTest(isPolicyId 표), redis
  RateLimitPolicyTest·web EdgeRateLimitTransportSettingsTest에 문법 밖
  id 네 행(대문자, 밑줄, 숫자로 시작, 64자) 거절. redis에는 policyId
  거절 시험이 없었다.

정규식 문법과 오류 메시지는 바꾸지 않았다. 버린 안: 사본 사이에 같은
값을 보는 대조 시험(사본을 두는 비용이 그대로다), RateLimitPolicyId 값
타입(공개 타입과 호출부가 더 바뀐다).

위험·한계: shared-contract 공개 API가 public 클래스 하나·메서드 다섯
늘어난다. application-core LeaseValidation의 같은 정규식은 lease
식별자라 이 변경 밖이다.

검증: desktop RED·GREEN은 PR 본문에 둔다.

Refs: REV-BE-0040
앞 커밋이 EdgeRateLimitTransportBridge의 policyId 검사를
RateLimitBounds.isPolicyId로 바꾸면서 null·문법 밖 id를 자기 메시지의
IllegalArgumentException으로 거절한다고 약속했다. 그런데 Bridge 시험은
정상 id 하나만 보고 있어서 이 검사를 지워도 모두 통과한다. 잘못된 id는
나중에 evaluate에서 RateLimitRequest가 다른 메시지로 거절할 뿐이다.

Bridge 시험에 null과 문법 밖 네 행(대문자, 밑줄, 숫자 첫 글자, 64자)을
ParameterizedTest로 넣고 예외 타입과 메시지를 함께 단언한다. 행은 settings
·redis 시험과 같아서, 정본 정규식을 느슨하게 바꾸면 이 시험도 함께
실패한다. RateLimitBoundsTest의 설명은 시험이 실제로 보는 것
(isPolicyId가 문법에 답한다)만 말하게 줄인다.

위험·한계: 시험만 바뀐다. 운영 코드와 메시지는 그대로다.

검증: 커밋 전에는 돌리지 않았다. 최종 트리의 desktop leaf·pr 결과와 RED는
PR 본문에 있다.

Refs: REV-BE-0040
RateLimitBounds.isPolicyId의 @return은 null일 때 false라는 것만 적고
true가 되는 조건을 적지 않는다. redis RateLimitPolicyBounds의 설명은
식별자 문법과 기간 검사를 정본에서 받는 이유를 하나(요청이 같은 id로
policy를 부른다)로 묶는데, 그 이유는 문법에만 맞는다.

@return에 「문법과 맞으면 true, null이면 false」를 적는다.
RateLimitPolicyBounds는 이유를 둘로 나누고(문법은 같은 id라서, 기간 검사는
양수·상한·whole-ms 규칙을 한 벌만 두려고), 같은 패키지의 dedup 상한은
RateLimitEvaluationDedupPolicy에 있다고 적는다. 상수 둘을
RateLimitPolicy로 옮기고 클래스를 지우는 안은 diff를 넓히는 데 비해 얻는
동작이 없어 버렸다.

위험·한계: 주석만 바뀐다.

검증: 커밋 전에는 돌리지 않았다. 최종 트리의 desktop leaf·pr 결과는 PR
본문에 있다.

Refs: REV-BE-0040
donghyeon.kang added 1 commit 2026-11-22 00:08:42 +00:00
donghyeon.kang merged commit fd14ea428d into main 2026-11-22 00:51:34 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/clean-architecture-backend-template#93