review-followup Wave 3 라운드 3(P22): Redis runtime·SDK 분리, 좁은 semantic 포트, startup rule, lease fencing 계약

- pub/sub 표면 삭제(G-6b·G-4i — 소비자 0, capability 규칙 3): SDK pub/sub·runtime gateway·PUBSUB lane·env 키 2개
- runtime을 `…cache.redis.runtime`으로(split package 해소), runtime은 소비자가 쓰는 8개 명령(`SemanticRedisCommands`)만,
  118개 메서드 gateway는 redis-sdk가 확장. SDK의 blocking·transaction·admin lane은 코드로 조립(env 키 4개 삭제)
- EVALSHA+NOSCRIPT 재로드 헬퍼 하나(메시지에만 NOSCRIPT가 온 경우도 재로드 — `LeaseScriptsTest` FAIL→PASS)
- startup rule 목록 + runner 하나(환경 검사 8개, exit code·문구 유지), Redis secret 요구는 모듈이 기여,
  ratelimit 정책을 cache-redis 밖으로, lease fencing 계약 테스트(fake·어댑터·실제 Redis)
- 통합: redis-sdk 테스트 2개가 옛 split package 경로를 보던 것 수정(ORCH-new-4)

검증: ./gradlew check architectureCheck verifyDependencyLocks :app-bootstrap:verifyEnvKeys configContractCheck
:app-bootstrap:integrationTest :sample-portfolio:integrationTest :sample-portfolio:systemTest --continue 통과(682 task),
Redis 7.4 standalone topology lane: runtime 7 · sdk 14 · cache-redis 19, 실패·skip 0

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
donghyeon-ka
2026-09-29 13:39:24 +09:00
co-authored by Claude Opus 5.5
parent 486d85a603
commit 4f4bd1fd34
283 changed files with 5499 additions and 5120 deletions
+4 -3
View File
@@ -20,9 +20,10 @@ persistence·outbound)이 프레임워크 충돌 없이 이 타입들을 공유
경계다. Business quota나 entitlement policy를 담는 application use case가 아니며, 이미
pseudonymized된 subject digest와 bounded policy ID/cost/deadline만 받는다.
`RateLimitPolicy`는 fixed window, sliding-window counter, token bucket 중 하나의 exact parameter
subtype을 고정하고 Lua의 `2^53-1` 안전 정수, 1일 window/refill/cleanup, 1시간 clock regression,
`FAIL_CLOSED`만 허용한다. 결과는 evaluated, known pre-send unavailable, post-dispatch
`RateParameters`는 fixed window, sliding-window counter, token bucket의 exact parameter와 Lua의
`2^53-1` 안전 정수, 1일 window/refill 한도를 고정한다. 정책 자체(`RateLimitPolicy`, 알고리즘·
실패 정책·evaluation dedup)는 그것을 쓰는 유일한 곳인 `adapter:outbound:cache-redis`의 설정이라
그 leaf에 있다. 결과는 evaluated, known pre-send unavailable, post-dispatch
indeterminate, schema/program/reply incompatible로 분리하므로 adapter가 장애를 allow나 평범한
deny로 숨길 수 없다. 이 패키지는 Java 표준 라이브러리만 사용하며 Redis key, command, Lua,
Spring/Lettuce 타입을 노출하지 않는다.
@@ -1,7 +0,0 @@
package dev.caskeleton.shared.ratelimit;
public enum RateLimitAlgorithm {
FIXED_WINDOW,
SLIDING_COUNTER,
TOKEN_BUCKET
}
@@ -7,8 +7,6 @@ import java.util.regex.Pattern;
final class RateLimitBounds {
static final Duration MAXIMUM_WINDOW = Duration.ofDays(1);
static final Duration MAXIMUM_CLEANUP_GRACE = Duration.ofDays(1);
static final Duration MAXIMUM_CLOCK_REGRESSION = Duration.ofHours(1);
static final Duration MAXIMUM_RETRY_AFTER =
Duration.ofMillis(RateParameters.MAXIMUM_EXACT_INTEGER);
@@ -1,54 +0,0 @@
package dev.caskeleton.shared.ratelimit;
import java.time.Duration;
import java.util.Objects;
/**
* Bounded response-loss replay policy for one rate-limit policy.
*
* <p>The byte limit covers the logical evaluation-ID and decision payload retained by the Redis
* program. Redis allocator overhead remains deployment/version evidence, not a portable byte
* contract.
*/
public record RateLimitEvaluationDedupPolicy(
boolean enabled, Duration timeToLive, int maximumEntries, int maximumStoredBytes) {
public static final int MAXIMUM_EVALUATION_ID_BYTES = 71;
public static final int MAXIMUM_DECISION_BYTES = 128;
public static final int MAXIMUM_ENTRIES = 1024;
public static final int MAXIMUM_STORED_BYTES = 262_144;
public static final Duration MAXIMUM_TIME_TO_LIVE = Duration.ofMinutes(5);
public RateLimitEvaluationDedupPolicy {
Objects.requireNonNull(timeToLive, "timeToLive must not be null");
if (!enabled) {
if (!timeToLive.isZero() || maximumEntries != 0 || maximumStoredBytes != 0) {
throw new IllegalArgumentException(
"disabled evaluation dedup must not allocate TTL, entries, or stored bytes");
}
} else {
RateLimitBounds.positiveDuration(timeToLive, "timeToLive", MAXIMUM_TIME_TO_LIVE);
if (maximumEntries < 1 || maximumEntries > MAXIMUM_ENTRIES) {
throw new IllegalArgumentException("maximumEntries must be in 1.." + MAXIMUM_ENTRIES);
}
if (maximumStoredBytes < 1 || maximumStoredBytes > MAXIMUM_STORED_BYTES) {
throw new IllegalArgumentException(
"maximumStoredBytes must be in 1.." + MAXIMUM_STORED_BYTES);
}
long requiredLogicalBytes =
(long) maximumEntries * (MAXIMUM_EVALUATION_ID_BYTES + MAXIMUM_DECISION_BYTES);
if (requiredLogicalBytes > maximumStoredBytes) {
throw new IllegalArgumentException(
"maximumStoredBytes cannot bound every configured evaluation entry");
}
}
}
public static RateLimitEvaluationDedupPolicy enabledDefaults() {
return new RateLimitEvaluationDedupPolicy(true, Duration.ofSeconds(5), 256, 65_536);
}
public static RateLimitEvaluationDedupPolicy disabled() {
return new RateLimitEvaluationDedupPolicy(false, Duration.ZERO, 0, 0);
}
}
@@ -1,6 +0,0 @@
package dev.caskeleton.shared.ratelimit;
/** V1 deliberately does not claim fail-open or local fallback semantics. */
public enum RateLimitFailurePolicy {
FAIL_CLOSED
}
@@ -1,155 +0,0 @@
package dev.caskeleton.shared.ratelimit;
import java.time.Duration;
import java.util.Objects;
public record RateLimitPolicy(
String policyId,
String policyRevision,
RateLimitAlgorithm algorithm,
RateParameters parameters,
long maximumCost,
Duration cleanupGrace,
Duration maximumClockRegression,
RateLimitFailurePolicy failurePolicy,
RateLimitEvaluationDedupPolicy evaluationDedupPolicy) {
public RateLimitPolicy(
String policyId,
String policyRevision,
RateLimitAlgorithm algorithm,
RateParameters parameters,
long maximumCost,
Duration cleanupGrace,
Duration maximumClockRegression,
RateLimitFailurePolicy failurePolicy) {
this(
policyId,
policyRevision,
algorithm,
parameters,
maximumCost,
cleanupGrace,
maximumClockRegression,
failurePolicy,
RateLimitEvaluationDedupPolicy.enabledDefaults());
}
public RateLimitPolicy {
RateLimitBounds.policyId(policyId);
RateLimitBounds.policyRevision(policyRevision);
Objects.requireNonNull(algorithm, "algorithm must not be null");
Objects.requireNonNull(parameters, "parameters must not be null");
if (maximumCost <= 0 || maximumCost > RateParameters.MAXIMUM_EXACT_INTEGER) {
throw new IllegalArgumentException(
"maximumCost must be positive and within Lua's exact integer range");
}
RateLimitBounds.positiveDuration(
cleanupGrace, "cleanupGrace", RateLimitBounds.MAXIMUM_CLEANUP_GRACE);
RateLimitBounds.nonNegativeDuration(
maximumClockRegression, "maximumClockRegression", RateLimitBounds.MAXIMUM_CLOCK_REGRESSION);
Objects.requireNonNull(failurePolicy, "failurePolicy must not be null");
Objects.requireNonNull(evaluationDedupPolicy, "evaluationDedupPolicy must not be null");
if (failurePolicy != RateLimitFailurePolicy.FAIL_CLOSED) {
throw new IllegalArgumentException("only FAIL_CLOSED is supported in v1");
}
switch (algorithm) {
case FIXED_WINDOW -> validateFixedWindow(parameters, maximumCost, cleanupGrace);
case SLIDING_COUNTER -> validateSlidingCounter(parameters, maximumCost, cleanupGrace);
case TOKEN_BUCKET -> validateTokenBucket(parameters, maximumCost, cleanupGrace);
default -> throw new IllegalArgumentException("unsupported rate-limit algorithm");
}
}
private static void validateFixedWindow(
RateParameters parameters, long maximumCost, Duration cleanupGrace) {
if (!(parameters instanceof RateParameters.FixedWindow fixedWindow)) {
throw algorithmMismatch(RateLimitAlgorithm.FIXED_WINDOW, parameters);
}
requireMaximumCost(maximumCost, fixedWindow.limit());
RateParameters.exactSum(
"fixed-window consumed plus maximumCost", fixedWindow.limit(), maximumCost);
RateParameters.exactSum(
"fixed-window state TTL", fixedWindow.window().toMillis(), cleanupGrace.toMillis());
}
private static void validateSlidingCounter(
RateParameters parameters, long maximumCost, Duration cleanupGrace) {
if (!(parameters instanceof RateParameters.SlidingCounter slidingCounter)) {
throw algorithmMismatch(RateLimitAlgorithm.SLIDING_COUNTER, parameters);
}
requireMaximumCost(maximumCost, slidingCounter.limit());
long maximumUnscaledConsumption =
RateParameters.exactSum(
"sliding-counter previous/current consumption",
slidingCounter.limit(),
slidingCounter.limit(),
maximumCost);
RateParameters.exactProduct(
"sliding-counter weighted consumption", maximumUnscaledConsumption, RateParameters.SCALE);
RateParameters.exactProduct(
"sliding-counter window weight", slidingCounter.window().toMillis(), RateParameters.SCALE);
long twoWindows =
RateParameters.exactProduct(
"sliding-counter state TTL", slidingCounter.window().toMillis(), 2);
RateParameters.exactSum("sliding-counter state TTL", twoWindows, cleanupGrace.toMillis());
}
private static void validateTokenBucket(
RateParameters parameters, long maximumCost, Duration cleanupGrace) {
if (!(parameters instanceof RateParameters.TokenBucket tokenBucket)) {
throw algorithmMismatch(RateLimitAlgorithm.TOKEN_BUCKET, parameters);
}
requireMaximumCost(maximumCost, tokenBucket.capacity());
if (tokenBucket.refillTokens() > tokenBucket.capacity()) {
throw new IllegalArgumentException("refillTokens must not exceed token-bucket capacity");
}
long scaledCapacity =
RateParameters.exactProduct(
"token-bucket capacity scale", tokenBucket.capacity(), RateParameters.SCALE);
long scaledMaximumCost =
RateParameters.exactProduct(
"token-bucket maximumCost scale", maximumCost, RateParameters.SCALE);
RateParameters.exactSum(
"token-bucket tokens plus maximumCost", scaledCapacity, scaledMaximumCost);
RateParameters.exactProduct(
"token-bucket refill time product", scaledCapacity, tokenBucket.refillPeriod().toMillis());
long scaledRefill =
RateParameters.exactProduct(
"token-bucket refill scale", tokenBucket.refillTokens(), RateParameters.SCALE);
long fullRefillPeriods = ceilingDivide(scaledCapacity, scaledRefill);
RateParameters.exactProduct(
"token-bucket full-refill horizon",
fullRefillPeriods,
tokenBucket.refillPeriod().toMillis());
RateParameters.exactSum(
"token-bucket state TTL",
RateParameters.exactProduct(
"token-bucket state TTL", fullRefillPeriods, tokenBucket.refillPeriod().toMillis()),
cleanupGrace.toMillis());
}
private static void requireMaximumCost(long maximumCost, long algorithmLimit) {
if (maximumCost > algorithmLimit) {
throw new IllegalArgumentException(
"maximumCost must not exceed the algorithm limit or capacity");
}
}
private static long ceilingDivide(long dividend, long divisor) {
return dividend / divisor + (dividend % divisor == 0 ? 0 : 1);
}
private static IllegalArgumentException algorithmMismatch(
RateLimitAlgorithm expected, RateParameters actual) {
return new IllegalArgumentException(
"algorithm "
+ expected
+ " does not match parameter type "
+ actual.getClass().getSimpleName());
}
}
@@ -3,39 +3,11 @@ package dev.caskeleton.shared.ratelimit;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import java.time.Duration;
import java.time.Instant;
import java.util.List;
import org.junit.jupiter.api.Test;
class EdgeRateLimitProviderNeutralContractTest {
@Test
void allPortableAlgorithmsHaveBoundedProviderNeutralPolicies() {
List<RateLimitPolicy> policies =
List.of(
policy(
RateLimitAlgorithm.FIXED_WINDOW,
new RateParameters.FixedWindow(100, Duration.ofMinutes(1))),
policy(
RateLimitAlgorithm.SLIDING_COUNTER,
new RateParameters.SlidingCounter(100, Duration.ofMinutes(1))),
policy(
RateLimitAlgorithm.TOKEN_BUCKET,
new RateParameters.TokenBucket(100, 10, Duration.ofSeconds(1))));
assertThat(policies)
.extracting(RateLimitPolicy::algorithm)
.containsExactlyElementsOf(List.of(RateLimitAlgorithm.values()));
assertThat(policies)
.allSatisfy(
policy -> {
assertThat(policy.failurePolicy()).isEqualTo(RateLimitFailurePolicy.FAIL_CLOSED);
assertThat(policy.evaluationDedupPolicy().maximumEntries())
.isLessThanOrEqualTo(RateLimitEvaluationDedupPolicy.MAXIMUM_ENTRIES);
});
}
@Test
void requestAcceptsOnlyPseudonymousSubjectAndBoundedEvaluationIdentity() {
RateLimitSubjectDigest digest = new RateLimitSubjectDigest("v1:" + "a".repeat(64));
@@ -59,17 +31,4 @@ class EdgeRateLimitProviderNeutralContractTest {
Instant.parse("2026-07-29T00:00:01Z")))
.isInstanceOf(IllegalArgumentException.class);
}
private static RateLimitPolicy policy(RateLimitAlgorithm algorithm, RateParameters parameters) {
return new RateLimitPolicy(
"edge-default",
"policy-v1",
algorithm,
parameters,
10,
Duration.ofSeconds(5),
Duration.ofSeconds(1),
RateLimitFailurePolicy.FAIL_CLOSED,
RateLimitEvaluationDedupPolicy.enabledDefaults());
}
}
@@ -1,39 +0,0 @@
package dev.caskeleton.shared.ratelimit;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import java.time.Duration;
import org.junit.jupiter.api.Test;
class RateLimitEvaluationDedupPolicyTest {
@Test
void enabledPolicyBoundsTtlEntriesAndStoredDataBytes() {
RateLimitEvaluationDedupPolicy policy =
new RateLimitEvaluationDedupPolicy(true, Duration.ofSeconds(5), 256, 65_536);
assertThat(policy.enabled()).isTrue();
assertThat(policy.timeToLive()).isEqualTo(Duration.ofSeconds(5));
assertThat(policy.maximumEntries()).isEqualTo(256);
assertThat(policy.maximumStoredBytes()).isEqualTo(65_536);
}
@Test
void disabledPolicyHasNoDedupStateAndEnabledPolicyRejectsUnsafeBounds() {
assertThat(RateLimitEvaluationDedupPolicy.disabled())
.isEqualTo(new RateLimitEvaluationDedupPolicy(false, Duration.ZERO, 0, 0));
assertThatThrownBy(
() -> new RateLimitEvaluationDedupPolicy(true, Duration.ofMinutes(6), 256, 65_536))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("timeToLive");
assertThatThrownBy(
() -> new RateLimitEvaluationDedupPolicy(true, Duration.ofSeconds(5), 1025, 262_144))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("maximumEntries");
assertThatThrownBy(
() -> new RateLimitEvaluationDedupPolicy(true, Duration.ofSeconds(5), 256, 4096))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("maximumStoredBytes");
}
}
@@ -1,159 +0,0 @@
package dev.caskeleton.shared.ratelimit;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import java.time.Duration;
import org.junit.jupiter.api.Test;
class RateLimitPolicyTest {
@Test
void acceptsEachV1AlgorithmWithItsExactParameterSubtype() {
RateLimitPolicy fixed =
policy(
RateLimitAlgorithm.FIXED_WINDOW,
new RateParameters.FixedWindow(100, Duration.ofMinutes(1)),
10);
RateLimitPolicy sliding =
policy(
RateLimitAlgorithm.SLIDING_COUNTER,
new RateParameters.SlidingCounter(100, Duration.ofMinutes(1)),
10);
RateLimitPolicy token =
policy(
RateLimitAlgorithm.TOKEN_BUCKET,
new RateParameters.TokenBucket(100, 10, Duration.ofSeconds(1)),
10);
assertThat(fixed.parameters()).isInstanceOf(RateParameters.FixedWindow.class);
assertThat(sliding.parameters()).isInstanceOf(RateParameters.SlidingCounter.class);
assertThat(token.parameters()).isInstanceOf(RateParameters.TokenBucket.class);
assertThat(fixed.failurePolicy()).isEqualTo(RateLimitFailurePolicy.FAIL_CLOSED);
}
@Test
void rejectsAlgorithmParameterMismatchAndUnsupportedRequestCost() {
assertThatThrownBy(
() ->
policy(
RateLimitAlgorithm.FIXED_WINDOW,
new RateParameters.TokenBucket(100, 10, Duration.ofSeconds(1)),
10))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("algorithm");
assertThatThrownBy(
() ->
policy(
RateLimitAlgorithm.FIXED_WINDOW,
new RateParameters.FixedWindow(10, Duration.ofSeconds(1)),
11))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("maximumCost");
}
@Test
void rejectsSlidingCounterIntermediatesBeyondLuaExactIntegerRange() {
long unsafeLimit = (RateParameters.MAXIMUM_EXACT_INTEGER / RateParameters.SCALE) / 2;
assertThatThrownBy(
() ->
policy(
RateLimitAlgorithm.SLIDING_COUNTER,
new RateParameters.SlidingCounter(unsafeLimit, Duration.ofSeconds(1)),
unsafeLimit))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("exact integer");
}
@Test
void rejectsTokenBucketFixedPointTimeProductsBeyondLuaExactIntegerRange() {
assertThatThrownBy(
() ->
policy(
RateLimitAlgorithm.TOKEN_BUCKET,
new RateParameters.TokenBucket(10_000_000, 1, Duration.ofDays(1)),
1))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("exact integer");
}
@Test
void rejectsFixedWindowAdmissionSumBeyondLuaExactIntegerRange() {
assertThatThrownBy(
() ->
policy(
RateLimitAlgorithm.FIXED_WINDOW,
new RateParameters.FixedWindow(
RateParameters.MAXIMUM_EXACT_INTEGER, Duration.ofSeconds(1)),
1))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("exact integer");
}
@Test
void rejectsSubMillisecondAndOverlongDurations() {
assertThatThrownBy(() -> new RateParameters.FixedWindow(10, Duration.ofNanos(1)))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("milliseconds");
assertThatThrownBy(() -> new RateParameters.FixedWindow(10, Duration.ofDays(2)))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("PT24H");
assertThatThrownBy(
() ->
new RateLimitPolicy(
"login",
"v3",
RateLimitAlgorithm.FIXED_WINDOW,
new RateParameters.FixedWindow(10, Duration.ofSeconds(1)),
1,
Duration.ofNanos(1),
Duration.ofSeconds(1),
RateLimitFailurePolicy.FAIL_CLOSED))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("milliseconds");
}
@Test
void rejectsZeroGraceAndClockRegressionBeyondTheLuaProgramBounds() {
assertThatThrownBy(
() ->
new RateLimitPolicy(
"login",
"v3",
RateLimitAlgorithm.FIXED_WINDOW,
new RateParameters.FixedWindow(10, Duration.ofSeconds(1)),
1,
Duration.ZERO,
Duration.ofSeconds(1),
RateLimitFailurePolicy.FAIL_CLOSED))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("cleanupGrace");
assertThatThrownBy(
() ->
new RateLimitPolicy(
"login",
"v3",
RateLimitAlgorithm.FIXED_WINDOW,
new RateParameters.FixedWindow(10, Duration.ofSeconds(1)),
1,
Duration.ofSeconds(1),
Duration.ofHours(1).plusMillis(1),
RateLimitFailurePolicy.FAIL_CLOSED))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("maximumClockRegression");
}
private static RateLimitPolicy policy(
RateLimitAlgorithm algorithm, RateParameters parameters, long maximumCost) {
return new RateLimitPolicy(
"login",
"v3",
algorithm,
parameters,
maximumCost,
Duration.ofSeconds(5),
Duration.ofSeconds(1),
RateLimitFailurePolicy.FAIL_CLOSED);
}
}