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
+10
View File
@@ -487,3 +487,13 @@ web 경로의 `W/`는 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adap
| untyped `DefaultDeliveryProcessor(Function<MessageEnvelope<EncodedMessage>, HandleResult>, …)` 생성자 | `src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultDeliveryProcessor.java` | `423a29c4` | typed `MessageHandler` 목록을 받는 형태로 교체(S7-#2) |
| `CapabilityTier` (→ `ApiTier`로 개명), `CompatibilityMatrix.Tier` (→ `SupportGrade`) | `src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/CapabilityTier.java`, `src/messaging/messaging-testkit/src/main/java/dev/caskeleton/messaging/testkit/CompatibilityMatrix.java` | `423a29c4` | 등급 용어 정리(S7-#14) |
| `api 'io.projectreactor:reactor-core'`, `testImplementation 'io.projectreactor:reactor-test'` | `src/messaging/messaging-spring-boot-starter/build.gradle` | `423a29c4` | reactive facade 삭제로 노출 이유 소멸(S7-#9c) |
| SDK pub/sub 연산 표면(`RedisPubSubOperations`, `RedisShardedPubSubOperations`, `ReactiveRedisPubSubOperations`, `ReactiveRedisShardedPubSubOperations`, `PubSubChannel`, `PubSubPattern`, `ShardedPubSubChannel`, `Subscription`, `LettuceRedisPubSubOperations`, `LettuceRedisShardedPubSubOperations`, `LettuceReactiveRedisPubSubOperations`, `LettuceReactiveRedisShardedPubSubOperations`, `LiveSubscription`, `PubSubCodecs`, `PubSubOperationRequests`, `SubscriptionFlux`)과 테스트 `InMemoryRedisPubSubGateway`·`RedisPubSubOperationsContractTest` | `src/adapter/outbound/redis-sdk/src/{main,test}/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/{api/operations,api/reactive,lettuce/operations}/` | `423a29c4` | 전송(`RedisPubSubGateway`) main 구현이 없어 동작 불가(G-6b) |
| `RedisPubSubGateway`, `RedisConnectionKind.PUBSUB`, `RedisCredentialRole.PUBSUB` | `src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/lettuce/{operations,connection}/` | `423a29c4` | 위와 같음 |
| `RedisSdkSettings.PubSub`·`Authentication.pubsubCredentialReference`, env 키 `APP_REDIS_PUBSUB_BUFFER_CAPACITY`·`APP_REDIS_AUTHENTICATION_PUBSUB_CREDENTIAL_REFERENCE` | `src/adapter/outbound/redis-runtime/.../sdk/config/RedisSdkSettings.java`, `docs/registries/env-keys.yaml`, `src/.env.example` | `423a29c4` | 동작하지 않는 옵션은 키를 두지 않는다(G-4i) |
| `RedisCapability.SHARDED_PUBSUB`, `RedisOperationContext.PATTERN_SUBSCRIBE` | `src/adapter/outbound/redis-sdk/.../sdk/api/RedisCapability.java`, `.../sdk/lettuce/operations/RedisOperationContext.java` | `423a29c4` | 사용처(pub/sub 연산) 삭제 |
| `RedisCredentialRole`(enum) | `src/adapter/outbound/redis-runtime/.../sdk/lettuce/connection/RedisCredentialRole.java` | `423a29c4` | 열린 `RedisAccount` 값으로 대체 — runtime은 자기 계정 2개만 알고 SDK가 admin 계정을 기여(G-7c) |
| `RedisSdkSettings.Blocking`·`Transaction`·`Admin`과 env 키 `APP_REDIS_ADMIN_ENABLED`·`APP_REDIS_ADMIN_CREDENTIAL_REFERENCE`·`APP_REDIS_BLOCKING_MAX_CONNECTIONS`·`APP_REDIS_TRANSACTION_MAX_CONNECTIONS` | `src/adapter/outbound/redis-runtime/.../sdk/config/RedisSdkSettings.java`, `docs/registries/env-keys.yaml`, `src/.env.example` | `423a29c4` | SDK 전용 lane·계정. SDK `RedisSdkComposition` 코드 설정으로 이동(G-7c, S3-#3b) |
| `InMemoryGatewayAccess` | `src/adapter/outbound/redis-runtime/src/testFixtures/.../sdk/lettuce/operations/InMemoryGatewayAccess.java` | `423a29c4` | cache-redis 테스트는 runtime testFixtures `InMemorySemanticRedisCommands`를 직접 쓴다. semantic 스크립트 에뮬레이션은 그 fake로 이동(SDK의 `InMemoryRedisCommandGateway`에서는 제거) |
| `IdempotencyScriptsConcurrencyContractTest` | `src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/` | `423a29c4` | reflection으로 `digests` Map 구조를 고정하던 테스트. 슬롯이 `RegisteredLuaScript` final 필드가 되어 대상이 없음; 동작은 `RegisteredLuaScriptTest`가 검증 |
| `SecretSourceValidator.REDIS_ENABLED_PROPERTY`와 Redis 역할 prefix 분기(`isRedisMaterial`, `isRedisRoleSelected`, `isRedisCacheBound`, `isSelected`), `REQUIRED_PROD_SECRETS`의 Redis 8개 | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/SecretSourceValidator.java` | `423a29c4` | cache-redis `RedisProductionSecrets`가 기여(S6-#2c) |
| shared `RateLimitBounds.MAXIMUM_CLEANUP_GRACE`·`MAXIMUM_CLOCK_REGRESSION`, `EdgeRateLimitProviderNeutralContractTest.allPortableAlgorithmsHaveBoundedProviderNeutralPolicies` | `src/shared-contract/src/{main,test}/java/dev/caskeleton/shared/ratelimit/` | `423a29c4` | 정책 타입이 cache-redis로 이동(S1-#15c). 정책 검증 테스트는 이동한 `RateLimitPolicyTest`에 있음 |
+12 -103
View File
@@ -1207,7 +1207,7 @@ env_keys:
# APP_SERVER_FORWARD_HEADERS_STRATEGY=native and server.tomcat.remoteip.internal-proxies.
- name: APP_RATE_LIMIT_REDIS_ENABLED
# DEPRECATED 2026-08-10: the rate limiter no longer owns a Redis client of its own. One client, built by RedisSdkAutoConfiguration, serves every capability, so a second endpoint and a second set of ceilings could only ever disagree with it.
# DEPRECATED 2026-08-10: the rate limiter no longer owns a Redis client of its own. One client, built by RedisRuntimeAutoConfiguration, serves every capability, so a second endpoint and a second set of ceilings could only ever disagree with it.
# Replaced by: app.redis.enabled (APP_REDIS_ENABLED).
deprecated_orphaned: true
removal_deadline: 2026-11-30
@@ -1295,7 +1295,7 @@ env_keys:
required_test: rate-limit-contract:key-version-bounded
- name: APP_RATE_LIMIT_REDIS_HOST
# DEPRECATED 2026-08-10: the rate limiter no longer owns a Redis client of its own. One client, built by RedisSdkAutoConfiguration, serves every capability, so a second endpoint and a second set of ceilings could only ever disagree with it.
# DEPRECATED 2026-08-10: the rate limiter no longer owns a Redis client of its own. One client, built by RedisRuntimeAutoConfiguration, serves every capability, so a second endpoint and a second set of ceilings could only ever disagree with it.
# Replaced by: app.redis.nodes (APP_REDIS_NODES).
deprecated_orphaned: true
removal_deadline: 2026-11-30
@@ -1311,7 +1311,7 @@ env_keys:
required_test: rate-limit-contract:redis-host-required
- name: APP_RATE_LIMIT_REDIS_PORT
# DEPRECATED 2026-08-10: the rate limiter no longer owns a Redis client of its own. One client, built by RedisSdkAutoConfiguration, serves every capability, so a second endpoint and a second set of ceilings could only ever disagree with it.
# DEPRECATED 2026-08-10: the rate limiter no longer owns a Redis client of its own. One client, built by RedisRuntimeAutoConfiguration, serves every capability, so a second endpoint and a second set of ceilings could only ever disagree with it.
# Replaced by: app.redis.nodes (APP_REDIS_NODES).
deprecated_orphaned: true
removal_deadline: 2026-11-30
@@ -1339,7 +1339,7 @@ env_keys:
required_test: rate-limit-contract:redis-password-no-leak
- name: APP_RATE_LIMIT_REDIS_TRUST_PEM
# DEPRECATED 2026-08-10: the rate limiter no longer owns a Redis client of its own. One client, built by RedisSdkAutoConfiguration, serves every capability, so a second endpoint and a second set of ceilings could only ever disagree with it.
# DEPRECATED 2026-08-10: the rate limiter no longer owns a Redis client of its own. One client, built by RedisRuntimeAutoConfiguration, serves every capability, so a second endpoint and a second set of ceilings could only ever disagree with it.
# Replaced by: app.redis.tls.trust-material-resource.
deprecated_orphaned: true
removal_deadline: 2026-11-30
@@ -1424,7 +1424,7 @@ env_keys:
required_test: rate-limit-contract:redis-timeout-bounded
- name: APP_RATE_LIMIT_REDIS_MAXIMUM_COMMAND_BYTES
# DEPRECATED 2026-08-10: the rate limiter no longer owns a Redis client of its own. One client, built by RedisSdkAutoConfiguration, serves every capability, so a second endpoint and a second set of ceilings could only ever disagree with it.
# DEPRECATED 2026-08-10: the rate limiter no longer owns a Redis client of its own. One client, built by RedisRuntimeAutoConfiguration, serves every capability, so a second endpoint and a second set of ceilings could only ever disagree with it.
# Replaced by: app.redis.limits.max-batch-request-bytes.
deprecated_orphaned: true
removal_deadline: 2026-11-30
@@ -1440,7 +1440,7 @@ env_keys:
required_test: rate-limit-contract:redis-command-bytes-bounded
- name: APP_RATE_LIMIT_REDIS_MAXIMUM_QUEUED_COMMANDS
# DEPRECATED 2026-08-10: the rate limiter no longer owns a Redis client of its own. One client, built by RedisSdkAutoConfiguration, serves every capability, so a second endpoint and a second set of ceilings could only ever disagree with it.
# DEPRECATED 2026-08-10: the rate limiter no longer owns a Redis client of its own. One client, built by RedisRuntimeAutoConfiguration, serves every capability, so a second endpoint and a second set of ceilings could only ever disagree with it.
# Replaced by: app.redis.capacity.maximum-in-flight-commands.
deprecated_orphaned: true
removal_deadline: 2026-11-30
@@ -1456,7 +1456,7 @@ env_keys:
required_test: rate-limit-contract:redis-queue-bounded
- name: APP_RATE_LIMIT_REDIS_MAXIMUM_IN_FLIGHT_BYTES
# DEPRECATED 2026-08-10: the rate limiter no longer owns a Redis client of its own. One client, built by RedisSdkAutoConfiguration, serves every capability, so a second endpoint and a second set of ceilings could only ever disagree with it.
# DEPRECATED 2026-08-10: the rate limiter no longer owns a Redis client of its own. One client, built by RedisRuntimeAutoConfiguration, serves every capability, so a second endpoint and a second set of ceilings could only ever disagree with it.
# Replaced by: app.redis.capacity.maximum-in-flight-bytes.
deprecated_orphaned: true
removal_deadline: 2026-11-30
@@ -1842,57 +1842,12 @@ env_keys:
compatibility_impact: additive
required_test: redis-capability:lease-composition
# --- Redis SDK typed settings (app.redis.*) -------------------------------
# Bound only by RedisSdkAutoConfiguration in adapter-outbound-redis-runtime while
# --- Redis runtime settings (app.redis.*) ----------------------------------
# Bound only by RedisRuntimeAutoConfiguration in adapter-outbound-redis-runtime while
# APP_REDIS_ENABLED is true. application.yml does not force these values into Redis-free
# deployments; src/.env.example merely documents explicit operator inputs. verifyEnvKeys checks
# the registry against the runtime module's configuration metadata.
- name: APP_REDIS_ADMIN_CREDENTIAL_REFERENCE
property: app.redis.admin.credential-reference
owner_module: adapter-outbound-redis-runtime
type: string
default: null
allowed_values: null
classification: sensitive-config
required: false
required_when: app.redis.admin.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: nonblank_when_required
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_ADMIN_ENABLED
property: app.redis.admin.enabled
owner_module: adapter-outbound-redis-runtime
type: boolean
default: false
allowed_values: [true, false]
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: boolean_strict
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_BLOCKING_MAX_CONNECTIONS
property: app.redis.blocking.max-connections
owner_module: adapter-outbound-redis-runtime
type: integer
default: 32
allowed_values: null
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: positive_integer
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_DATABASE
# Cluster supports database 0 only; a non-zero value fails startup there.
property: app.redis.database
@@ -2032,24 +1987,8 @@ env_keys:
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
- name: APP_REDIS_TRANSACTION_MAX_CONNECTIONS
property: app.redis.transaction.max-connections
owner_module: adapter-outbound-redis-runtime
type: integer
default: 16
allowed_values: null
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: positive_integer
compatibility_impact: additive
required_test: redis-sdk:typed-settings-bound-and-validated
# --- Redis runtime composition settings (app.redis.*) ----------------------
# Authentication, Sentinel discovery, TLS, lifecycle, Cluster routing, capacity and
# subscription delivery. Same rule as the rest of app.redis.*: bound only while
# Authentication, Sentinel discovery, TLS, lifecycle, Cluster routing and capacity. Same rule as the rest of app.redis.*: bound only while
# APP_REDIS_ENABLED is true, and deliberately absent from application.yml and .env.
- name: APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE
@@ -2103,21 +2042,6 @@ env_keys:
compatibility_impact: additive
required_test: redis-sdk:runtime-composition-binds-and-validates
- name: APP_REDIS_AUTHENTICATION_PUBSUB_CREDENTIAL_REFERENCE
property: app.redis.authentication.pubsub-credential-reference
owner_module: adapter-outbound-cache-redis
type: string
default: null
allowed_values: null
classification: sensitive-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: nonblank_when_required
compatibility_impact: additive
required_test: redis-sdk:runtime-composition-binds-and-validates
- name: APP_REDIS_CAPACITY_MAXIMUM_IN_FLIGHT_COMMANDS
property: app.redis.capacity.maximum-in-flight-commands
owner_module: adapter-outbound-cache-redis
@@ -2287,21 +2211,6 @@ env_keys:
compatibility_impact: additive
required_test: redis-sdk:runtime-composition-binds-and-validates
- name: APP_REDIS_PUBSUB_BUFFER_CAPACITY
property: app.redis.pubsub.buffer-capacity
owner_module: adapter-outbound-cache-redis
type: integer
default: 1024
allowed_values: null
classification: public-config
required: false
required_when: app.redis.enabled=true
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
validation: positive_integer
compatibility_impact: additive
required_test: redis-sdk:runtime-composition-binds-and-validates
- name: APP_REDIS_SENTINEL_CREDENTIAL_REFERENCE
property: app.redis.sentinel.credential-reference
owner_module: adapter-outbound-cache-redis
@@ -2379,8 +2288,8 @@ env_keys:
classification: sensitive-config
required: false
# A relationship between two settings rather than a switch: a client certificate without its
# key cannot build a key manager. Enforced in RedisSdkSettings.validate and covered by
# RedisSdkSettingsTest, which is where the registry's prose conditions are proven.
# key cannot build a key manager. Enforced in RedisRuntimeSettings.validate and covered by
# RedisRuntimeSettingsTest, which is where the registry's prose conditions are proven.
required_when: app.redis.tls.client-certificate-resource is configured
reload_policy: restart-only
owner_branch: redis-optionality-and-composition
@@ -54,6 +54,8 @@ secrets:
source: secret-manager
rotation_policy: restart-only
prod_default: null
# Required with app.redis.enabled=true and this role selected; checked by adapter-outbound-cache-redis RedisProductionSecrets.
required_when: ca-skeleton.capabilities.cache.bindings.default=redis
dev_sentinel_prefix: __LOCAL_DEV_
owner_branch: feature-secrets-config-source-contract
masking_rule: full
@@ -78,6 +80,8 @@ secrets:
source: secret-manager
rotation_policy: dual-read-restart-only
prod_default: null
# Required with app.redis.enabled=true and this role selected; checked by adapter-outbound-cache-redis RedisProductionSecrets.
required_when: ca-skeleton.capabilities.cache.bindings.default=redis
dev_sentinel_prefix: __LOCAL_DEV_
owner_branch: codex-phase-a-ci-recovery
masking_rule: full
@@ -90,6 +94,8 @@ secrets:
source: secret-manager
rotation_policy: restart-only
prod_default: null
# Required with app.redis.enabled=true and this role selected; checked by adapter-outbound-cache-redis RedisProductionSecrets.
required_when: ca-skeleton.capabilities.rate-limit.provider=redis
dev_sentinel_prefix: __LOCAL_DEV_
owner_branch: redis-distributed-rate-limit
masking_rule: full
@@ -114,6 +120,8 @@ secrets:
source: secret-manager
rotation_policy: dual-read-restart-only
prod_default: null
# Required with app.redis.enabled=true and this role selected; checked by adapter-outbound-cache-redis RedisProductionSecrets.
required_when: ca-skeleton.capabilities.rate-limit.provider=redis
dev_sentinel_prefix: __LOCAL_DEV_
owner_branch: redis-distributed-rate-limit
masking_rule: full
@@ -126,6 +134,8 @@ secrets:
source: secret-manager
rotation_policy: restart-only
prod_default: null
# Required with app.redis.enabled=true and this role selected; checked by adapter-outbound-cache-redis RedisProductionSecrets.
required_when: ca-skeleton.security.auth-mode=redis-session
dev_sentinel_prefix: __LOCAL_DEV_
owner_branch: redis-production-capability
masking_rule: full
@@ -150,6 +160,8 @@ secrets:
source: secret-manager
rotation_policy: dual-read-restart-only
prod_default: null
# Required with app.redis.enabled=true and this role selected; checked by adapter-outbound-cache-redis RedisProductionSecrets.
required_when: ca-skeleton.security.auth-mode=redis-session
dev_sentinel_prefix: __LOCAL_DEV_
owner_branch: redis-production-capability
masking_rule: full
@@ -162,6 +174,8 @@ secrets:
source: secret-manager
rotation_policy: cold-cutover-restart-only
prod_default: null
# Required with app.redis.enabled=true and this role selected; checked by adapter-outbound-cache-redis RedisProductionSecrets.
required_when: ca-skeleton.capabilities.idempotency.provider=redis
dev_sentinel_prefix: __LOCAL_DEV_
owner_branch: redis-production-capability-completion
masking_rule: full
@@ -174,6 +188,8 @@ secrets:
source: secret-manager
rotation_policy: cold-cutover-restart-only
prod_default: null
# Required with app.redis.enabled=true and this role selected; checked by adapter-outbound-cache-redis RedisProductionSecrets.
required_when: ca-skeleton.capabilities.lease.provider=redis
dev_sentinel_prefix: __LOCAL_DEV_
owner_branch: redis-production-capability-completion
masking_rule: full
@@ -0,0 +1,38 @@
## 행 결과
| ID | 결과 | 근거 |
|---|---|---|
| G-4i | 해당 없음(코드 삭제) | P22 D `1b3138cb`: `RedisSdkSettings.PubSub`·`Authentication.pubsubCredentialReference`, env 키 `APP_REDIS_PUBSUB_BUFFER_CAPACITY`·`APP_REDIS_AUTHENTICATION_PUBSUB_CREDENTIAL_REFERENCE`(`docs/registries/env-keys.yaml`·`src/.env.example`) 삭제. `:app-bootstrap:verifyEnvKeys` 통과 |
| G-6b | 해당 없음(코드 삭제) | P22 D `1b3138cb`. **구현 대신 삭제를 택함**: 구현하려면 Lettuce pub/sub 연결 수명·버퍼 한도·재구독·sharded 라우팅·실제 벤더 lane을 새로 만들어야 하고(capability 규칙 3 "켜면 완전히 동작"), main 소비자가 0이다. 삭제는 SDK 파일 18개와 runtime 인터페이스 1개로 끝난다. 카탈로그 `redis-sdk/src/main/resources/redis-sdk/redis-command-policy.yml:745-780`의 PUBLISH/SUBSCRIBE/PSUBSCRIBE/SPUBLISH… 8개는 `BLOCKED`(카탈로그는 서버의 모든 명령을 판정해야 하므로 행은 남김), `RedisCapability.SHARDED_PUBSUB`·`pattern-subscribe` permit 정책 삭제, `redis-sdk/README.md` 표에서 pub/sub 제거 |
| G-7a | 완료 | P22 W1 `bd0e0bc6`. runtime 계약은 `redis-runtime/.../runtime/command/SemanticRedisCommands.java:19`(get·set(Duration)·getAndDelete·incrementBy·ping·loadScript·evaluateRegisteredForList/Long 8개)와 구현 `LettuceSemanticRedisCommands`. 118개 메서드 `RedisCommandGateway`와 `LettuceRedisCommandGateway`는 redis-sdk로 이동해 `redis-sdk/.../sdk/lettuce/operations/RedisCommandGateway.java:48`에서 `SemanticRedisCommands`를 확장하고, 빌린 연결의 `RedisLease.driver()`로 `LettuceRedisCommandGateway.over(...)`를 만든다. `api.command`·`api.error`·`api.operations`·`RedisVersion`·페이지 타입도 SDK로. cache-redis·health는 8개만 사용 |
| G-7c | 완료 | P22 W1 `bd0e0bc6`. runtime lane은 `RedisConnectionKind.java:12-16` REGULAR·SCRIPT만. BLOCKING·TRANSACTION·ADMIN은 `redis-sdk/.../sdk/lettuce/connection/RedisSdkLane.java:19`, admin 계정과 lane 한도는 `RedisSdkComposition.java`(서비스가 `RedisLaneContribution`·`RedisAccountContribution` 빈으로 기여, runtime `RedisRuntimeAutoConfiguration`이 모아 풀·자격 증명을 만든다). `app.redis.admin.*`·`app.redis.blocking.max-connections`·`app.redis.transaction.max-connections` 설정과 env 키 4개 삭제 — SDK의 다른 설정처럼 코드 설정(README "configuration that is code")으로. 테스트 `RedisRuntimeAutoConfigurationTest.configuredAccountsAreResolvedPerRole`(기여 계정 해석)·`aLaneAnotherModuleContributesIsPooledByTheOwner`·`aLaneComposedTwiceFailsTheContext` |
| G-7d | 완료 | P22 W1 `bd0e0bc6`. redis-runtime 전 파일이 `dev.caskeleton.adapter.outbound.cache.redis.runtime.*`(`RedisDeploymentMode`, `key`, `cluster`, `command`, `connection`, `config`). split package 해소. `RedisRuntimePackageBoundaryTest.noRuntimeSourceReferencesTheTypedSdkPackage`. SDK 쪽 `RedisSdkModuleBoundaryTest`는 SDK root만 스캔 |
| G-7e | 완료 | P22 W1 `bd0e0bc6`. selector 표는 `cache-redis/.../capability/RedisCorrectnessRoleSelectors.java:48`(W2에서 역할별 secret까지 한 표로)로 옮기고 cache-redis `META-INF/spring.factories`에 `RedisCorrectnessRequirement`로 등록. runtime `RedisCorrectnessRoles.java:44`는 등록된 요구에 "required 여부"만 묻는다. `RedisRuntimeAutoConfigurationTest.withoutARequirementTheRuntimeCreatesNoRequiredContributor`(runtime은 selector를 모른다)·`aModuleThatNeedsRedisForCorrectnessGetsTheRequiredContributor`, `RedisReadinessGroupPostProcessorTest.eachCorrectnessSelectorAppendsRedisReadiness`, live `LiveRedisCompositionTest` 스크립트 role 2건 통과 |
| G-8 | 완료 | P22 W1 `bd0e0bc6`: `cache-redis/.../RegisteredLuaScript.java:29`(digest 캐시·NOSCRIPT 판별 `:114`·재로드 1회·응답 디코딩)을 Cache/RateLimit/Lease/IdempotencyScripts 4곳이 사용. `LeaseScriptsTest.aProgramTheServerForgotIsReloadedEvenWhenOnlyTheMessageSaysNoScript` FAIL(`CompletionException` caused by `RedisCommandExecutionException` — 메시지로만 온 NOSCRIPT를 lease가 재로드하지 않음)→PASS. `RegisteredLuaScriptTest` 4건 |
| X1-지도-lock / lease / fencing | 완료 | 소유자 결정 8대로 lock·lease 포트 유지. claim executor·`CacheRefreshCoordinationPort`·`LeaseWatchdog`는 이미 `208077fd`에서 삭제돼 남은 미사용 포트 없음. fencing은 contract kit로(P22 W2 `7f39bfda`): `application-core/src/testFixtures/.../lease/testkit/DistributedLeaseContract.java`(밀려난 holder의 renew·release는 NotOwner이고 후임의 lease를 건드리지 않는다, 같은 attempt 재acquire는 replay, 이중 release는 AlreadyAbsent — 7건)를 fake `InMemoryDistributedLease`(`InMemoryDistributedLeaseContractTest`), Redis 어댑터+in-memory 명령(`RedisDistributedLeaseContractTest`), 실제 Redis(`LiveRedisDistributedLeaseContractTest`, standalone lane)가 모두 통과. lock 포트의 공통 계약(JDBC 어댑터 포함)은 Wave 4 범위로 남김 |
| S1-#15c | 완료 | P22 W2 `7f39bfda`: `RateLimitPolicy`·`RateLimitAlgorithm`·`RateLimitEvaluationDedupPolicy`(+ 이들만 쓰는 `RateLimitFailurePolicy`)와 테스트 2개를 `cache-redis/.../ratelimit/`로 이동, 정책 검증 bounds는 `RateLimitPolicyBounds`(package-private). shared에는 `EdgeRateLimitPort`·`RateLimitRequest`·`RateLimitOutcome`·`RateLimitDecision`·`RateParameters`·subject 계열만 남음. `:shared-contract:check`·`:adapter:inbound:web:check` 통과 |
| S3-#3a | 완료 | = G-7a·G-7c. runtime 계약 8개, 나머지는 SDK 확장 인터페이스, lane은 REGULAR·SCRIPT, `forCommand(RedisCommandDescriptor)`는 SDK `RedisSdkLane.forCommand`로 |
| S3-#3b | 완료 | = G-7d. `RedisSdkSettings`→`RedisRuntimeSettings`, `RedisSdkAutoConfiguration`→`RedisRuntimeAutoConfiguration`, SDK 전용 섹션(blocking·transaction·admin)은 runtime 설정에서 빠지고 SDK 코드 설정으로. `RedisRuntimePackageBoundaryTest.noRuntimeTypeIsNamedAfterTheSdk` |
| S3-#4b | 완료 | P22 W1 `bd0e0bc6`: `cache-redis/.../SemanticRedisCall.java:35` — 빌림·bounded wait·not-sent/unknown 판정 한 곳(`effect`: 스크립트, `run`+`markSent`: cache). 네 어댑터의 `catch (InterruptedException` 15곳이 사라지고 cache-redis main에는 `SemanticRedisCall`과 시작 probe만 남음. Lua 응답 디코딩은 `RegisteredLuaScript.number/text/requireShape`. 기존 어댑터 테스트(`RedisIdempotencyStoreAdapterTest`·`RedisDistributedLeaseAdapterTest`·`RedisEdgeRateLimitAdapterTest`·`RedisCacheRegionAdapterTest`)와 live `LiveRedisSemanticPortsTest` 10건 통과 |
| S3-#5 | 완료 | P22 W1 `bd0e0bc6`: `IdempotencyScripts.ScriptStatus`(`IdempotencyScripts.java:228`)로 한 번 파싱, switch는 enum, `transition(...)`은 `Transition` record + `Map<ScriptStatus, O>`(`RedisIdempotencyStoreAdapter.java:428`) — 인자 16개→7개 |
| S3-#9 | 완료 | P22 W1 `bd0e0bc6`: `RedisTopologyClientFactory` 662→371줄. `StandaloneRuntimeClient`·`ClusterRuntimeClient`·`AccountRoutingRuntimeClient`·`SharedClientResources`·`LaneConnection`·`ShutdownBudget`를 package-private top-level로 |
| S6-#2c | 완료 | P22 W2 `7f39bfda`: Redis 역할별 secret 판정은 `cache-redis/.../capability/RedisProductionSecrets.java`가 `RedisCorrectnessRoleSelectors.ROLES`(역할·selector·required·scripted·secret 한 표)에서 파생해 `support.startup.RequiredProductionSecrets` 빈으로 기여(Redis가 켜졌을 때만 존재). `SecretSourceValidator`는 `REQUIRED_PROD_SECRETS`(datasource·pseudonymization salt) + 모듈 기여 목록만 검사하고 `REDIS_ENABLED_PROPERTY`·역할 prefix 분기 삭제. 레지스트리 `secrets-classification.yaml`의 Redis secret 8행에 `required_when`. 테스트 `RedisProductionSecretsTest`(역할별 5 + 비선택 2), `SecretSourceValidatorTest.aSecretAModuleContributedIsRequiredInProd` 외 2건, `SecretsClassificationRegistryTest` 통과 |
| S6-#3a | 완료 | P22 W2 `7f39bfda`: `support.startup.StartupRule { phase(); summary(); remedy(); List<String> violations(Environment) }` + 러너 하나 `StartupRuleRunner`(`StartupRuleAutoConfiguration`, support `AutoConfiguration.imports`). 환경만 읽는 검사 8개를 규칙으로: bootstrap `RuntimeNumericBoundsValidator`·`ErrorDetailExposureSafetyValidator`, persistence-jpa `RequiredEnvironmentValidator`·`FlywayProdSafetyValidator`·`OpenInViewSafetyValidator`·`PostgreSqlTransportSecurityValidator`·`PersistenceVendorProdSafetyValidator`·`HikariPoolConstraintValidator`. phase·종료 코드와 위반 문구는 유지(메시지 앞머리에 규칙 summary가 붙는 형태만 통일). bean이 필요한 검사(`SecretSourceValidator`, `StartupSafetyValidator`, `JpaDataSourceProfileValidator`, `JpaDangerousConfigurationGuard`)는 bean으로 유지, 부팅 전 EPP(`RuntimeEnvironmentProfileValidator`, `JpaActivationEnvironmentPostProcessor`, `TracingSamplingEnvironmentPostProcessor`, `RedisReadinessGroupPostProcessor`)는 EPP로 유지. `StartupRuleRunnerTest` 3건, 기존 검증기 테스트 전부 통과 |
## 제거된 코드
| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 |
|---|---|---|---|
| SDK pub/sub 연산 표면(`RedisPubSubOperations`, `RedisShardedPubSubOperations`, `ReactiveRedisPubSubOperations`, `ReactiveRedisShardedPubSubOperations`, `PubSubChannel`, `PubSubPattern`, `ShardedPubSubChannel`, `Subscription`, `LettuceRedisPubSubOperations`, `LettuceRedisShardedPubSubOperations`, `LettuceReactiveRedisPubSubOperations`, `LettuceReactiveRedisShardedPubSubOperations`, `LiveSubscription`, `PubSubCodecs`, `PubSubOperationRequests`, `SubscriptionFlux`)과 테스트 `InMemoryRedisPubSubGateway`·`RedisPubSubOperationsContractTest` | `src/adapter/outbound/redis-sdk/src/{main,test}/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/{api/operations,api/reactive,lettuce/operations}/` | `423a29c4` | 전송(`RedisPubSubGateway`) main 구현이 없어 동작 불가(G-6b) |
| `RedisPubSubGateway`, `RedisConnectionKind.PUBSUB`, `RedisCredentialRole.PUBSUB` | `src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/lettuce/{operations,connection}/` | `423a29c4` | 위와 같음 |
| `RedisSdkSettings.PubSub`·`Authentication.pubsubCredentialReference`, env 키 `APP_REDIS_PUBSUB_BUFFER_CAPACITY`·`APP_REDIS_AUTHENTICATION_PUBSUB_CREDENTIAL_REFERENCE` | `src/adapter/outbound/redis-runtime/.../sdk/config/RedisSdkSettings.java`, `docs/registries/env-keys.yaml`, `src/.env.example` | `423a29c4` | 동작하지 않는 옵션은 키를 두지 않는다(G-4i) |
| `RedisCapability.SHARDED_PUBSUB`, `RedisOperationContext.PATTERN_SUBSCRIBE` | `src/adapter/outbound/redis-sdk/.../sdk/api/RedisCapability.java`, `.../sdk/lettuce/operations/RedisOperationContext.java` | `423a29c4` | 사용처(pub/sub 연산) 삭제 |
| `RedisCredentialRole`(enum) | `src/adapter/outbound/redis-runtime/.../sdk/lettuce/connection/RedisCredentialRole.java` | `423a29c4` | 열린 `RedisAccount` 값으로 대체 — runtime은 자기 계정 2개만 알고 SDK가 admin 계정을 기여(G-7c) |
| `RedisSdkSettings.Blocking`·`Transaction`·`Admin`과 env 키 `APP_REDIS_ADMIN_ENABLED`·`APP_REDIS_ADMIN_CREDENTIAL_REFERENCE`·`APP_REDIS_BLOCKING_MAX_CONNECTIONS`·`APP_REDIS_TRANSACTION_MAX_CONNECTIONS` | `src/adapter/outbound/redis-runtime/.../sdk/config/RedisSdkSettings.java`, `docs/registries/env-keys.yaml`, `src/.env.example` | `423a29c4` | SDK 전용 lane·계정. SDK `RedisSdkComposition` 코드 설정으로 이동(G-7c, S3-#3b) |
| `InMemoryGatewayAccess` | `src/adapter/outbound/redis-runtime/src/testFixtures/.../sdk/lettuce/operations/InMemoryGatewayAccess.java` | `423a29c4` | cache-redis 테스트는 runtime testFixtures `InMemorySemanticRedisCommands`를 직접 쓴다. semantic 스크립트 에뮬레이션은 그 fake로 이동(SDK의 `InMemoryRedisCommandGateway`에서는 제거) |
| `IdempotencyScriptsConcurrencyContractTest` | `src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/` | `423a29c4` | reflection으로 `digests` Map 구조를 고정하던 테스트. 슬롯이 `RegisteredLuaScript` final 필드가 되어 대상이 없음; 동작은 `RegisteredLuaScriptTest`가 검증 |
| `SecretSourceValidator.REDIS_ENABLED_PROPERTY`와 Redis 역할 prefix 분기(`isRedisMaterial`, `isRedisRoleSelected`, `isRedisCacheBound`, `isSelected`), `REQUIRED_PROD_SECRETS`의 Redis 8개 | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/SecretSourceValidator.java` | `423a29c4` | cache-redis `RedisProductionSecrets`가 기여(S6-#2c) |
| shared `RateLimitBounds.MAXIMUM_CLEANUP_GRACE`·`MAXIMUM_CLOCK_REGRESSION`, `EdgeRateLimitProviderNeutralContractTest.allPortableAlgorithmsHaveBoundedProviderNeutralPolicies` | `src/shared-contract/src/{main,test}/java/dev/caskeleton/shared/ratelimit/` | `423a29c4` | 정책 타입이 cache-redis로 이동(S1-#15c). 정책 검증 테스트는 이동한 `RateLimitPolicyTest`에 있음 |
## 새로 발견한 결함
- `P22-new-1` — `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/SecretSourceValidator.java`: `APP_DATASOURCE_PASSWORD`를 요구할지 bootstrap이 persistence-jpa의 모듈 스위치(`ca-skeleton.persistence-jpa.enabled`)를 읽어 판정한다. S6-#2c가 Redis에 대해 없앤 것과 같은 모양(모듈 지식이 composition root에). 같은 `RequiredProductionSecrets` 기여로 옮길 수 있으나 이 묶음 범위(Redis) 밖이라 고치지 않음.
- `P22-new-2` — `infra/redis-sdk/acl/application.acl`·`all-accounts.acl`: pub/sub 표면이 사라졌는데 application 계정 ACL fixture가 여전히 `+@pubsub`와 채널 패턴 `&prod:*`를 준다(최소 권한 위반, fixture 한정). infra 파일이라 고치지 않음.
- `P22-new-3` — redis-sdk가 공개 API에 runtime 타입(`SemanticRedisCommands` 상위 인터페이스, `WritePresence`, `RedisLaneContribution`, `RedisDriverConnection`)을 노출하면서 runtime을 `implementation`으로만 의존한다. SDK를 쓰는 leaf는 README대로 runtime도 선언해야 컴파일된다(이전에도 `RedisRuntimeOwner` 때문에 같았음). `api`로 바꾸는 것은 build 변경이라 보류.
@@ -354,21 +354,21 @@ Wave 3 라운드 1 결과로 받은 4건(2026-09-28, desktop):
| G-4f | Required | `lifecycle.tls-handshake-timeout` 미적용 | 해당 없음(코드 삭제) | 같은 표 행 174 | - | - |
| G-4g | Required | `pubsub.overflow-policy` 미적용 | 해당 없음(코드 삭제) | 같은 표 행 174 | - | - |
| G-4h | Required | `lifecycle.acquire-timeout` 미적용 | 완료 | `src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisSdkAutoConfiguration.java:241` → `RedisRuntimeOwner.java:153` `tryAcquire(acquireTimeout)`. 테스트 `RedisScriptLaneAdmissionTest.aCallerStillWaitingWhenTheAcquireTimeoutRunsOutIsRefusedAsNotSent`. 커밋 `6d27356e` | - | - |
| G-4i | Required | 남은 `pubsub.buffer-capacity`(+`authentication.pubsub-credential-reference`)가 버퍼를 제한하지 않음. PUBSUB lane 연결 수(`/64`)로만 쓰이고 pub/sub 전송 구현이 없음 | 남음 | `src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisSdkAutoConfiguration.java:235-236`, `RedisSdkSettings.java:549-566`, `docs/registries/env-keys.yaml:2297`. main에 `implements RedisPubSubGateway` 0건 (= G-6b) | W3 | G-6b에서 pub/sub를 지우면 `RedisSdkSettings.PubSub`·env key `APP_REDIS_PUBSUB_BUFFER_CAPACITY`·`_PUBSUB_CREDENTIAL_REFERENCE`를 함께 삭제(AGENTS.md 완료 기준 3) |
| G-4i | Required | 남은 `pubsub.buffer-capacity`(+`authentication.pubsub-credential-reference`)가 버퍼를 제한하지 않음. PUBSUB lane 연결 수(`/64`)로만 쓰이고 pub/sub 전송 구현이 없음 | 해당 없음(코드 삭제) | Wave 3 W3-P22 (Wave 3 라운드 3 커밋): P22 D `1b3138cb`: `RedisSdkSettings.PubSub`·`Authentication.pubsubCredentialReference`, env 키 `APP_REDIS_PUBSUB_BUFFER_CAPACITY`·`APP_REDIS_AUTHENTICATION_PUBSUB_CREDENTIAL_REFERENCE`(`docs/registries/env-keys.yaml`·`src/.env.example`) 삭제. `:app-bootstrap:verifyEnvKeys` 통과 | - | G-6b에서 pub/sub를 지우면 `RedisSdkSettings.PubSub`·env key `APP_REDIS_PUBSUB_BUFFER_CAPACITY`·`_PUBSUB_CREDENTIAL_REFERENCE`를 함께 삭제(AGENTS.md 완료 기준 3) |
| G-4j | Nit | deprecated env key의 "Replaced by"가 삭제된 key를 가리킴 | 남음 | `docs/registries/env-keys.yaml:1435`(`app.redis.limits.max-batch-request-bytes`), `:1467`(`app.redis.capacity.maximum-in-flight-bytes`) | W5 | 두 행의 "Replaced by" 주석을 "대체 없음(2026-09-25 삭제)"로 수정 |
| G-5a | Required | redis-runtime·redis-sdk 테스트가 cache-redis에 있어 두 leaf focused test가 빈 초록불 | 완료 | redis-sdk `src/test` 51개(`RedisSdkModuleBoundaryTest`, `LiveRedisOperationsFixture` 등), redis-runtime `src/test` 10개(`RedisRuntimeOwnerTest` 등), fake는 `src/adapter/outbound/redis-runtime/build.gradle:4,18-20` testFixtures로 공유, `src/adapter/outbound/cache-redis/build.gradle:8-17`에 redis-sdk edge 없음. 커밋 `6d27356e` | - | - |
| G-5b | Required | redis-runtime leaf에 README·CLAUDE.md 없음 | 남음 | `src/adapter/outbound/redis-runtime/`에 `build.gradle`·`src`만 있음. redis-sdk는 `README.md` 추가됨. runtime 규칙은 `src/adapter/outbound/cache-redis/CLAUDE.md` "Redis runtime and optional typed SDK" 절에 섞여 있음 | W5 | `src/adapter/outbound/redis-runtime/README.md`를 만들어 제공하는 것·붙이는 방법·env 키(`app.redis.*` 소유)를 적고 cache-redis CLAUDE.md의 runtime 절을 옮김 |
| G-6a | Required | SDK 진입 facade `RedisOperations`·`ReactiveRedisOperations` 구현체 0 | 해당 없음(코드 삭제) | `docs/capability-status.md` 「제거된 코드」 행 170. `implements RedisOperations\|ReactiveRedisOperations` 0건 | - | - |
| G-6b | Required | pub/sub 전송(`RedisPubSubGateway`) main 구현이 없어 SDK의 pub/sub·sharded pub/sub 연산을 쓸 수 없음 | 남음 | `src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/lettuce/operations/RedisPubSubGateway.java`(인터페이스만), 구현은 test `InMemoryRedisPubSubGateway`뿐. `src/adapter/outbound/redis-sdk/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/lettuce/operations/LettuceRedisPubSubOperations.java` 외 3개가 이 gateway에 의존. `src/adapter/outbound/redis-sdk/README.md` 표는 pub/sub를 제공한다고 적음 | W3 | D1 기준으로 redis-sdk의 `*PubSub*Operations`·`LiveSubscription`·`PubSubOperationRequests`·api pub/sub 인터페이스와 runtime `RedisPubSubGateway`·PUBSUB role/lane을 삭제하고 README 표에서 제거 |
| G-6b | Required | pub/sub 전송(`RedisPubSubGateway`) main 구현이 없어 SDK의 pub/sub·sharded pub/sub 연산을 쓸 수 없음 | 해당 없음(코드 삭제) | Wave 3 W3-P22 (Wave 3 라운드 3 커밋): P22 D `1b3138cb`. **구현 대신 삭제를 택함**: 구현하려면 Lettuce pub/sub 연결 수명·버퍼 한도·재구독·sharded 라우팅·실제 벤더 lane을 새로 만들어야 하고(capability 규칙 3 "켜면 완전히 동작"), main 소비자가 0이다. 삭제는 SDK 파일 18개와 runtime 인터페이스 1개로 끝난다. 카탈로그 `redis-sdk/src/main/resources/redis-sdk/redis-command-policy.yml:745-780`의 PUBLISH/SUBSCRIBE/PSUBSCRIBE/SPUBLISH… 8개는 `BLOCKED`(카탈로그는 서버의 모든 명령을 판정해야 하므로 행은 남김), `RedisCapability.SHARDED_PUBSUB`·`pattern-subscribe` permit 정책 삭제, `redis-sdk/README.md` 표에서 pub/sub 제거 | - | D1 기준으로 redis-sdk의 `*PubSub*Operations`·`LiveSubscription`·`PubSubOperationRequests`·api pub/sub 인터페이스와 runtime `RedisPubSubGateway`·PUBSUB role/lane을 삭제하고 README 표에서 제거 |
| G-6c | Required | redis-sdk `RedisConnectionRegistry`가 호출자 0이고 `RedisRuntimeOwner` lane 한도 로직과 중복 | 해당 없음(코드 삭제) | 「제거된 코드」 행 173 | - | - |
| G-6d | Required | cache-redis realtime adapter(`RedisEphemeralFanoutAdapter`, `RedisConnectionRegistryAdapter`) 조립처 없음 | 해당 없음(코드 삭제) | 「제거된 코드」 행 156, 210. cache-redis main에 `realtime/` 패키지 없음 | - | - |
| G-6e | Required | SDK를 도입할 조립 코드·경로가 없음 | 완료 | `src/adapter/outbound/redis-sdk/README.md` "Adding it"(서비스 어댑터 leaf에서 `implementation` + `modules.json` edge, AGENTS.md 라이브러리형 예외), per-structure `Lettuce*Operations` 구현 36개, 조립 예시 `LiveRedisOperationsFixture`(test). 커밋 `6d27356e` | - | - |
| G-7a | Consider | runtime `RedisCommandGateway`가 SDK 표면 전체(약 118개 메서드)를 들고 있는데 cache-redis·health는 4개만 씀 | 남음 | `src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/lettuce/operations/RedisCommandGateway.java`(1227줄), `LettuceRedisCommandGateway.java`(1282줄). cache-redis main이 쓰는 것: `loadScript`·`evaluateRegisteredForList`·`evaluateRegisteredForLong`, health는 `ping` | W3 | runtime에는 이 4개만 가진 좁은 gateway를 두고 나머지 메서드와 `api.command`(RAW_ONLY 등)는 redis-sdk 소유 gateway로 이동 |
| G-7a | Consider | runtime `RedisCommandGateway`가 SDK 표면 전체(약 118개 메서드)를 들고 있는데 cache-redis·health는 4개만 씀 | 완료 | Wave 3 W3-P22 (Wave 3 라운드 3 커밋): P22 W1 `bd0e0bc6`. runtime 계약은 `redis-runtime/.../runtime/command/SemanticRedisCommands.java:19`(get·set(Duration)·getAndDelete·incrementBy·ping·loadScript·evaluateRegisteredForList/Long 8개)와 구현 `LettuceSemanticRedisCommands`. 118개 메서드 `RedisCommandGateway`와 `LettuceRedisCommandGateway`는 redis-sdk로 이동해 `redis-sdk/.../sdk/lettuce/operations/RedisCommandGateway.java:48`에서 `SemanticRedisCommands`를 확장하고, 빌린 연결의 `RedisLease.driver()`로 `LettuceRedisCommandGateway.over(...)`를 만든다. `api.command`·`api.error`·`api.operations`·`RedisVersion`·페이지 타입도 SDK로. cache-redis·health는 8개만 사용 | - | runtime에는 이 4개만 가진 좁은 gateway를 두고 나머지 메서드와 `api.command`(RAW_ONLY 등)는 redis-sdk 소유 gateway로 이동 |
| G-7b | Consider | raw 자격 증명·raw allowlist가 runtime에 있음 | 해당 없음(코드 삭제) | 「제거된 코드」 행 174(`raw.*`, `RedisCredentialRole.RAW`). `RedisCredentialRole.java:23-29`에 RAW 없음 | - | - |
| G-7c | Consider | SDK 전용 admin 자격 증명·ADMIN lane이 runtime에 있음 | 남음 | `src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisSdkAutoConfiguration.java:143-148,237`. 사용처는 redis-sdk `LettuceRedisAdminOperations`뿐 | W3 | G-7a 분리 때 admin 자격 증명 해석과 ADMIN lane 한도를 redis-sdk 쪽 조립으로 이동 |
| G-7d | Consider | runtime과 sdk가 같은 패키지 `…cache.redis.sdk.*`를 공유 | 남음 | redis-runtime main 전 파일이 `dev.caskeleton.adapter.outbound.cache.redis.sdk.*`(예: `.../sdk/lettuce/connection/RedisRuntimeOwner.java:1`) | W3 | redis-runtime 패키지를 `dev.caskeleton.adapter.outbound.cache.redis.runtime.*`로 이동 |
| G-7e | Consider | runtime `RedisCorrectnessRoles`가 소비자 selector 값(session·idempotency·rate-limit·lease)을 하드코딩 | 남음 | `src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisCorrectnessRoles.java:32-37` | W3 | selector 목록을 소비자인 cache-redis(`RedisCapabilitySettings`)로 옮기고 runtime은 "required 여부"만 받도록 변경 |
| G-8 | Consider | EVALSHA+NOSCRIPT 재로드 헬퍼가 4벌 복사, `CacheScripts`만 메시지 `startsWith("NOSCRIPT")` 폴백 | 남음 | `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/cache/CacheScripts.java:41-87`, `ratelimit/RateLimitScripts.java:209-263`, `lease/LeaseScripts.java:106-160`, `idempotency/IdempotencyScripts.java:213-271` | W3 | cache-redis에 `RegisteredLuaScript`(digest 캐시·NOSCRIPT 판별·재로드 1회) 하나를 두고 네 클래스가 사용 |
| G-7c | Consider | SDK 전용 admin 자격 증명·ADMIN lane이 runtime에 있음 | 완료 | Wave 3 W3-P22 (Wave 3 라운드 3 커밋): P22 W1 `bd0e0bc6`. runtime lane은 `RedisConnectionKind.java:12-16` REGULAR·SCRIPT만. BLOCKING·TRANSACTION·ADMIN은 `redis-sdk/.../sdk/lettuce/connection/RedisSdkLane.java:19`, admin 계정과 lane 한도는 `RedisSdkComposition.java`(서비스가 `RedisLaneContribution`·`RedisAccountContribution` 빈으로 기여, runtime `RedisRuntimeAutoConfiguration`이 모아 풀·자격 증명을 만든다). `app.redis.admin.*`·`app.redis.blocking.max-connections`·`app.redis.transaction.max-connections` 설정과 env 키 4개 삭제 — SDK의 다른 설정처럼 코드 설정(README "configuration that is code")으로. 테스트 `RedisRuntimeAutoConfigurationTest.configuredAccountsAreResolvedPerRole`(기여 계정 해석)·`aLaneAnotherModuleContributesIsPooledByTheOwner`·`aLaneComposedTwiceFailsTheContext` | - | G-7a 분리 때 admin 자격 증명 해석과 ADMIN lane 한도를 redis-sdk 쪽 조립으로 이동 |
| G-7d | Consider | runtime과 sdk가 같은 패키지 `…cache.redis.sdk.*`를 공유 | 완료 | Wave 3 W3-P22 (Wave 3 라운드 3 커밋): P22 W1 `bd0e0bc6`. redis-runtime 전 파일이 `dev.caskeleton.adapter.outbound.cache.redis.runtime.*`(`RedisDeploymentMode`, `key`, `cluster`, `command`, `connection`, `config`). split package 해소. `RedisRuntimePackageBoundaryTest.noRuntimeSourceReferencesTheTypedSdkPackage`. SDK 쪽 `RedisSdkModuleBoundaryTest`는 SDK root만 스캔 | - | redis-runtime 패키지를 `dev.caskeleton.adapter.outbound.cache.redis.runtime.*`로 이동 |
| G-7e | Consider | runtime `RedisCorrectnessRoles`가 소비자 selector 값(session·idempotency·rate-limit·lease)을 하드코딩 | 완료 | Wave 3 W3-P22 (Wave 3 라운드 3 커밋): P22 W1 `bd0e0bc6`. selector 표는 `cache-redis/.../capability/RedisCorrectnessRoleSelectors.java:48`(W2에서 역할별 secret까지 한 표로)로 옮기고 cache-redis `META-INF/spring.factories`에 `RedisCorrectnessRequirement`로 등록. runtime `RedisCorrectnessRoles.java:44`는 등록된 요구에 "required 여부"만 묻는다. `RedisRuntimeAutoConfigurationTest.withoutARequirementTheRuntimeCreatesNoRequiredContributor`(runtime은 selector를 모른다)·`aModuleThatNeedsRedisForCorrectnessGetsTheRequiredContributor`, `RedisReadinessGroupPostProcessorTest.eachCorrectnessSelectorAppendsRedisReadiness`, live `LiveRedisCompositionTest` 스크립트 role 2건 통과 | - | selector 목록을 소비자인 cache-redis(`RedisCapabilitySettings`)로 옮기고 runtime은 "required 여부"만 받도록 변경 |
| G-8 | Consider | EVALSHA+NOSCRIPT 재로드 헬퍼가 4벌 복사, `CacheScripts`만 메시지 `startsWith("NOSCRIPT")` 폴백 | 완료 | Wave 3 W3-P22 (Wave 3 라운드 3 커밋): P22 W1 `bd0e0bc6`: `cache-redis/.../RegisteredLuaScript.java:29`(digest 캐시·NOSCRIPT 판별 `:114`·재로드 1회·응답 디코딩)을 Cache/RateLimit/Lease/IdempotencyScripts 4곳이 사용. `LeaseScriptsTest.aProgramTheServerForgotIsReloadedEvenWhenOnlyTheMessageSaysNoScript` FAIL(`CompletionException` caused by `RedisCommandExecutionException` — 메시지로만 온 NOSCRIPT를 lease가 재로드하지 않음)→PASS. `RegisteredLuaScriptTest` 4건 | - | cache-redis에 `RegisteredLuaScript`(digest 캐시·NOSCRIPT 판별·재로드 1회) 하나를 두고 네 클래스가 사용 |
| G-9a | Consider | 장애 WARN이 capability·operation·type 조합마다 JVM 수명 동안 한 번뿐(`WARNED` 비우지 않음) | 완료 | Wave 1–2 P6 (fcddab7e·Wave 2 커밋): `RedisSemanticFailureLogger.java:28,58`: once-per-JVM `Set` → key별 마지막 WARN 시각 맵, `WARN_INTERVAL`(1분)마다 다시 WARN. 테스트용 package-private `report(..., nowNanos)`. `RedisSemanticFailureLoggerTest.aContinuingFailureWarnsAgainOnceTheWindowHasPassed` FAIL(`Expected size: 2 but was: 1`)→PASS | - | `WARNED`를 key별 마지막 WARN 시각 맵으로 바꿔 시간 창(예: 1분)마다 다시 WARN |
| G-9b | Consider | `failureType`이 대부분 wrapper(`ExecutionException`) 이름 | 완료 | Wave 1–2 P6 (fcddab7e·Wave 2 커밋): `RedisSemanticFailureLogger.java:39`: `ExecutionException`/`CompletionException` cause를 풀어 기록. `aWrappedFailureIsReportedByItsCause` FAIL(`expected "IllegalStateException" but was "ExecutionException"`)→PASS | - | `report()`에서 `ExecutionException`·`CompletionException` cause를 풀고 기록 |
| G-10a | Consider | SCRIPT ACL probe가 `return {1}`이라 스크립트 내부 명령(`TIME`/`HSET`/`PEXPIRE`/`DEL`) 권한 부족을 기동 때 못 잡음 | 완료 | Wave 1–2 P6 (fcddab7e·Wave 2 커밋): `RedisSemanticScriptAclProbe.java:29-38`: probe key에서 `TIME`→`HSET`→`PEXPIRE`→`HGET`→`DEL`을 실행하고 읽은 값이 쓴 값과 같을 때만 `{1}`. `anAccountDeniedACommandTheScriptsCallFailsStartup`[HSET/PEXPIRE/HGET/DEL] FAIL→PASS. 실제 Redis standalone·cluster에서 `LiveRedisSemanticScriptAclProbeTest` 2건 PASS. 테스트 ACL `+time`은 NEW-5a(W1)에서 추가 | - | probe 스크립트를 probeKey에 `TIME`·`HSET`·`PEXPIRE`·`HGET`·`DEL`을 실제 실행하는 것으로 교체하고, 테스트 ACL에 `+time` 추가 |
@@ -686,7 +686,7 @@ Wave 3 라운드 1 결과로 받은 4건(2026-09-28, desktop):
| X1-지도-요청 멱등성 | 권고 | 계약 2개·store 3개·executor 조립 3곳·inbound ledger 3개 → V2 정본, 조립 1곳 | 완료 | Wave 3 W3-P18 (Wave 3 라운드 2 커밋): 조립이 한 곳이다(`composition:idempotency`). 두 root가 같은 모듈을 쓴다. | - | X1-#2b대로 `composition:idempotency` 신설 후 두 곳을 모듈 하나로 |
| X1-지도-자연키 생성-또는-반환 | 권고 | durable operation을 notification 방식(`ON CONFLICT`)으로, upsert executor 삭제 (= E-2) | 완료 | `DurableOperationJpaRepository.java:48` `ON CONFLICT … DO NOTHING`, `DurableOperationStoreAdapter.java:46-58` 삽입 후 재조회, upsert 실행기 7종 삭제(`docs/capability-status.md:158`), 커밋 `6d27356e` | - | - |
| X1-지도-Inbox / 소비자 dedup | 권고 | app-core inbox 삭제, 나머지(messaging inbox·notification ledger) 유지 | 완료 | `application/inbox/`·`PostgreSqlSameStoreInboxAdapter` 삭제(`docs/capability-status.md:155`), mongo change stream dedup 삭제(`:151`); application-core 패키지 목록에 `inbox` 없음, 커밋 `6d27356e` | - | - |
| X1-지도-lock / lease / fencing | 권고 | 미사용 포트·claim executor 삭제, fencing은 contract kit로 | 남음 | claim executor·`CacheRefreshCoordinationPort`·`LeaseWatchdog` 삭제(`docs/capability-status.md:152-153,157`). 남은 포트 2개 모두 비즈니스 소비자 0: `DistributedLockPort`(참조는 `StartupSafetyValidator.java:51` 존재 검사뿐), `DistributedLeasePort`(참조 0) | W3 | 결정(2026-09-25): lock·lease 유지, 쓰지 않는 claim executor만 삭제, fencing은 계약 테스트로 |
| X1-지도-lock / lease / fencing | 권고 | 미사용 포트·claim executor 삭제, fencing은 contract kit로 | 완료 | Wave 3 W3-P22 (Wave 3 라운드 3 커밋): 소유자 결정 8대로 lock·lease 포트 유지. claim executor·`CacheRefreshCoordinationPort`·`LeaseWatchdog`는 이미 `208077fd`에서 삭제돼 남은 미사용 포트 없음. fencing은 contract kit로(P22 W2 `7f39bfda`): `application-core/src/testFixtures/.../lease/testkit/DistributedLeaseContract.java`(밀려난 holder의 renew·release는 NotOwner이고 후임의 lease를 건드리지 않는다, 같은 attempt 재acquire는 replay, 이중 release는 AlreadyAbsent — 7건)를 fake `InMemoryDistributedLease`(`InMemoryDistributedLeaseContractTest`), Redis 어댑터+in-memory 명령(`RedisDistributedLeaseContractTest`), 실제 Redis(`LiveRedisDistributedLeaseContractTest`, standalone lane)가 모두 통과. lock 포트의 공통 계약(JDBC 어댑터 포함)은 Wave 4 범위로 남김 | - | 결정(2026-09-25): lock·lease 유지, 쓰지 않는 claim executor만 삭제, fencing은 계약 테스트로 |
| X1-지도-caller 트랜잭션 guard | 권고 | 9벌 복사 → persistence-jpa helper 1개 (= E-3) | 남음 | persistence-jpa 복사본 4벌 + guard 없는 곳 10개(세부 X1-#4) | W3 | X1-#4 |
| X1-지도-Backoff 계산식 | 권고 | 10개, "full jitter" 뜻 3가지 → shared-contract `Backoff` | 남음 | 앱 쪽 3개 남음(`OutboxBackoffPolicy.java:63-68`, `ExponentialFullJitterBackoff.java:78`, `RetryBackoff.java:42`), JPA 2개 삭제 | W3 | X1-#9 |
| X1-지도-Rate limit | 권고 | web 전용 병렬 타입 세트 삭제 (= I-8 일부) | 완료 | `WebRateLimiter`·web `RateLimitDecision`·`RateLimitFailurePolicy`·`WebMvcThrottleFilter` 삭제(`docs/capability-status.md:99`); 남은 경로 `RateLimitWebConfig.java:22` → `EdgeRateLimitTransportBridge` → shared `EdgeRateLimitPort`, 커밋 `6d27356e` | - | - |
@@ -792,7 +792,7 @@ Wave 3 라운드 1 결과로 받은 4건(2026-09-28, desktop):
| S1-#14 | Consider | notification platform 미사용 약 920줄(예외 12, security 3, sms/push/email/webpush) (= B-8) | 해당 없음(코드 삭제) | 「제거된 코드」 notification `sms`·`push`·`email`·`webpush` facade, throw 0 예외 12종, redaction 5종 행. 해당 디렉터리 없음 확인 | - | - |
| S1-#15a | Consider | shared-contract `activation/*`(bootstrap만 사용) | 해당 없음(코드 삭제) | 「제거된 코드」 `MasterSwitch`·`MasterSwitchParser`(shared-contract `activation` 전체) 행 | - | - |
| S1-#15b | Consider | shared-contract `opstore/*` 구현·소비자 0 | 해당 없음(코드 삭제) | Wave 3 W3-P25 (Wave 3 라운드 2 커밋): `d54909c4`(X1-#6f와 같은 삭제) | - | `opstore` 패키지 삭제 |
| S1-#15c | Consider | ratelimit 정책 타입이 cache-redis 전용 | 남음 | `shared-contract/.../ratelimit/RateLimitPolicy`·`RateLimitAlgorithm` main 소비자는 cache-redis뿐, `RateLimitEvaluationDedupPolicy`는 테스트만 참조 | W3 | 세 타입을 `adapter:outbound:cache-redis`로 이동(`EdgeRateLimitPort` 계열만 shared에 유지) |
| S1-#15c | Consider | ratelimit 정책 타입이 cache-redis 전용 | 완료 | Wave 3 W3-P22 (Wave 3 라운드 3 커밋): P22 W2 `7f39bfda`: `RateLimitPolicy`·`RateLimitAlgorithm`·`RateLimitEvaluationDedupPolicy`(+ 이들만 쓰는 `RateLimitFailurePolicy`)와 테스트 2개를 `cache-redis/.../ratelimit/`로 이동, 정책 검증 bounds는 `RateLimitPolicyBounds`(package-private). shared에는 `EdgeRateLimitPort`·`RateLimitRequest`·`RateLimitOutcome`·`RateLimitDecision`·`RateParameters`·subject 계열만 남음. `:shared-contract:check`·`:adapter:inbound:web:check` 통과 | - | 세 타입을 `adapter:outbound:cache-redis`로 이동(`EdgeRateLimitPort` 계열만 shared에 유지) |
| S1-#15d | Consider | shared-contract CLAUDE.md 책임 목록이 패키지 일부만 설명 | 남음 | `shared-contract/CLAUDE.md:17-30`은 response·error·request·health·tracing만, 실제 패키지 15개(annotation·concurrency·headers·metrics·operation·registry·runtime·security·ratelimit·opstore 누락) | W5 | 책임 목록을 현재 패키지 기준으로 갱신 |
| S1-#16 | Consider | 문서가 말하는 `application-core → domain-core` 의존이 빌드에 없음 | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): `src/application-core/build.gradle` `implementation project(':domain-core')` 복원(registry 허용 edge). `architectureCheck` PASS. 같은 행의 `NotificationIdGeneratorPort`·`UploadIdentifierFactory` → `IdFactory` 정리는 application-notification/fileserver·persistence-jpa·composition을 바꾸는 작업이라 하지 않음(P16-new-5) | - | `application-core/build.gradle`에 `implementation project(':domain-core')` 복원, `NotificationIdGeneratorPort`·`UploadIdentifierFactory`를 `IdFactory` 기반으로 정리 |
| S1-#17a | Consider | objectstorage 식별자 클래스 6개·가드 2개 복사 | 완료 | Wave 3 W3-P24 (Wave 3 라운드 2 커밋): `7a21c6e7`. `ObjectId`·`ObjectReference`·`ObjectStageHandle`·`ObjectVersionToken`을 compact constructor + `toString`(redacted) record로(`identity/ObjectId.java:4`). `DirectTransferSessionId`·`PartReceiptToken`은 D-7a에서 이미 삭제. 가드는 `ObjectModelSupport.requireBoundedToken`(`model/ObjectModelSupport.java:9`) 하나, `ObjectRequestSupport.boundedToken` 삭제. `:application-objectstorage:check`, control record 골든 digest(`ObjectControlRecordCodecTest`) PASS | - | 식별자를 record + `toString` 재정의로, 가드는 하나로 |
@@ -839,16 +839,16 @@ Wave 3 라운드 1 결과로 받은 4건(2026-09-28, desktop):
| S3-#1 | Required | httpclient blocking/reactive 병렬 스택이 이미 갈라짐 (= H-5, H-7) | 완료 | Wave 1–2 P11 (fcddab7e·Wave 2 커밋): D 커밋 `06764fcb`에서 reactive 스택(WebClient·Reactor Netty)과 webflux·reactor·reactor-netty·reactor-test·blockhound 의존 삭제. blocking(RestClient) 경로 하나만 남음. `clients[N].api` 설정 키·`ClientApiType`·`TransportType.REACTOR_NETTY` 삭제, env-fields.yaml 행 삭제, lockfile 재생성(httpclient·app-bootstrap). Jetty HTTP/3 실험 transport는 reactive SPI에 묶여 있어 blocking SPI(`JettyClientHttpRequestFactory`)로 옮김(자동 조립 안 됨은 그대로) `HC/http3/JettyHttp3TransportProvider.java:49` | - | 결정(2026-09-25): D4를 outbound에도 적용 — httpclient reactive(WebClient·Reactor Netty) 스택과 webflux·reactor 의존 삭제 |
| S3-#2a | Required | reactive streaming 요청이 admission·deadline·credential 없이 나감 | 해당 없음(코드 삭제) | Wave 1–2 P11 (fcddab7e·Wave 2 커밋): D `06764fcb`에서 `webclient/ReactiveStreamingGateway` 삭제. blocking 스트리밍은 deadline·credential·admission 적용 `HC/restclient/BlockingStreamingGateway.java:69,82,106` | - | S3-#1에서 reactive를 지우면 함께 삭제, 유지하면 blocking과 같은 credential·admission·deadline 단계 적용 + 동작 테스트 |
| S3-#2b | Required | 진입점 6개가 호출 파이프라인을 각자 조립 | 완료 | Wave 3 W3-P26 (Wave 3 라운드 2 커밋): `CallSetup.prepare(lease, operation)`이 blocking runtime·metadata·target policy·deadline(+guard)을 준비하고 `admit()`·`credentials()`·`credentialRequest()` 제공(`HC/restclient/CallSetup.java:49,79`). generic(`DefaultGenericHttpGateway.java:69`)과 streaming(`BlockingStreamingGateway.java:50`) 진입점이 사용. Dynamic Target은 target 준비(SSRF 핀)가 달라 `CallSetup.guardedDeadline`과 admission permit만 공유(`dynamic/DefaultDynamicTargetGateway.java:104`) — 이 과정에서 P26-new-1 발견·수정. reactive 진입점 3개는 결정 9로 이미 삭제. service(H1)는 generic gateway를 경유 | - | `CallSetup.prepare(lease, operation)`이 metadata/prepared/deadline/admission/credentials 반환, 진입점은 전송만 다르게 |
| S3-#3a | Required | 118개 메서드 `RedisCommandGateway`, runtime이 SDK 개념에 역의존 (= G-7) | 남음 | `redis-runtime/.../lettuce/operations/RedisCommandGateway.java`(1,227줄, 메서드 118), `:1107-1134` `sendApprovedRaw/sendAdminDiagnostic/sendExtension`, `lettuce/connection/RedisConnectionKind.java:25-33` BLOCKING·TRANSACTION·PUBSUB lane, `:64` `forCommand(RedisCommandDescriptor)` | W3 | runtime 계약은 semantic adapter가 쓰는 8개(`SemanticRedisCommands`)로, 나머지는 redis-sdk 확장 인터페이스로 이동(redis-sdk 유지 결정 반영), lane은 REGULAR·SCRIPT만 |
| S3-#3b | Required | runtime이 `Sdk` 이름·`...redis.sdk` 패키지를 쓰고 redis-sdk와 split package | 남음 | `redis-runtime/.../sdk/config/RedisSdkSettings.java`(670줄), `RedisSdkAutoConfiguration.java`, redis-runtime·redis-sdk 공유 패키지 9개 | W3 | `RedisRuntimeSettings`로 개명, runtime 패키지를 `...redis.runtime.*`로, SDK 전용 설정 섹션은 redis-sdk로 |
| S3-#3a | Required | 118개 메서드 `RedisCommandGateway`, runtime이 SDK 개념에 역의존 (= G-7) | 완료 | Wave 3 W3-P22 (Wave 3 라운드 3 커밋): = G-7a·G-7c. runtime 계약 8개, 나머지는 SDK 확장 인터페이스, lane은 REGULAR·SCRIPT, `forCommand(RedisCommandDescriptor)`는 SDK `RedisSdkLane.forCommand`로 | - | runtime 계약은 semantic adapter가 쓰는 8개(`SemanticRedisCommands`)로, 나머지는 redis-sdk 확장 인터페이스로 이동(redis-sdk 유지 결정 반영), lane은 REGULAR·SCRIPT만 |
| S3-#3b | Required | runtime이 `Sdk` 이름·`...redis.sdk` 패키지를 쓰고 redis-sdk와 split package | 완료 | Wave 3 W3-P22 (Wave 3 라운드 3 커밋): = G-7d. `RedisSdkSettings`→`RedisRuntimeSettings`, `RedisSdkAutoConfiguration`→`RedisRuntimeAutoConfiguration`, SDK 전용 섹션(blocking·transaction·admin)은 runtime 설정에서 빠지고 SDK 코드 설정으로. `RedisRuntimePackageBoundaryTest.noRuntimeTypeIsNamedAfterTheSdk` | - | `RedisRuntimeSettings`로 개명, runtime 패키지를 `...redis.runtime.*`로, SDK 전용 설정 섹션은 redis-sdk로 |
| S3-#4a | Required | cache-redis에서 "안 보냄/보냈는지 모름" 구분을 rate-limit만 함 | 완료 | Wave 1–2 P6 (fcddab7e·Wave 2 커밋): 멱등성·lease는 NEW-5c 수정. cache는 현황표 근거("lane 거절도 Indeterminate")가 사실과 다름: cache는 이미 lane 거절을 `DEGRADED_UNAVAILABLE`(=안 보냄)로 돌려준다. 빠진 쪽은 반대 방향이었다 — 보낸 뒤 응답을 잃은 쓰기도 `DEGRADED_UNAVAILABLE`였다. `RedisCacheRegionAdapter.java:241,294,314,328`에 `sent` 플래그를 두어 쓰기 명령을 보낸 뒤의 실패는 `INDETERMINATE`, 그 전(lane 거절·연결·generation 조회)은 `DEGRADED_UNAVAILABLE`. 테스트 `RedisCacheRegionAdapterTest.aWriteWhoseReplyWasLostIsIndeterminate`/`anInvalidationWhoseReplyWasLostIsIndeterminate`/`aRegionInvalidationWhoseReplyWasLostIsIndeterminate` FAIL(`expected: INDETERMINATE but was: DEGRADED_UNAVAILABLE`)→PASS, 가드 `aWriteThatFailedBeforeItsSetWasSentDegrades` PASS | - | 멱등성·lease·cache의 실패 분류에 `metadata().ambiguousExecution()`로 NOT_SENT/AMBIGUOUS 구분 추가 |
| S3-#4b | Required | "lease 빌림 → `.get(timeout)` → 예외 처리" 틀 복사, Lua 응답 디코더 3벌 | 남음 | `catch (InterruptedException` 16곳(멱등성 6·lease 4·cache 4·rate-limit 1·probe 1), 디코더 `idempotency/IdempotencyScripts.java:273`, `lease/LeaseScripts.java:162`, `ratelimit/RateLimitScripts.java:280` | W3 | `SemanticRedisCall.run(...)` 공통 틀 + 응답 디코딩을 등록 스크립트 쪽 한 곳으로 |
| S3-#5 | Consider | `RedisIdempotencyStoreAdapter.transition` 인자 14~15개, 상태 문자열 switch 반복 | 남음 | `cache-redis/.../idempotency/RedisIdempotencyStoreAdapter.java:164-180`(`transition` 호출 14개 인자), `:137-157` 등 문자열 switch | W3 | `IdempotencyScripts.Reply`에서 `enum ScriptStatus`로 한 번 파싱, 호출부는 `Map<ScriptStatus,O>` |
| S3-#4b | Required | "lease 빌림 → `.get(timeout)` → 예외 처리" 틀 복사, Lua 응답 디코더 3벌 | 완료 | Wave 3 W3-P22 (Wave 3 라운드 3 커밋): P22 W1 `bd0e0bc6`: `cache-redis/.../SemanticRedisCall.java:35` — 빌림·bounded wait·not-sent/unknown 판정 한 곳(`effect`: 스크립트, `run`+`markSent`: cache). 네 어댑터의 `catch (InterruptedException` 15곳이 사라지고 cache-redis main에는 `SemanticRedisCall`과 시작 probe만 남음. Lua 응답 디코딩은 `RegisteredLuaScript.number/text/requireShape`. 기존 어댑터 테스트(`RedisIdempotencyStoreAdapterTest`·`RedisDistributedLeaseAdapterTest`·`RedisEdgeRateLimitAdapterTest`·`RedisCacheRegionAdapterTest`)와 live `LiveRedisSemanticPortsTest` 10건 통과 | - | `SemanticRedisCall.run(...)` 공통 틀 + 응답 디코딩을 등록 스크립트 쪽 한 곳으로 |
| S3-#5 | Consider | `RedisIdempotencyStoreAdapter.transition` 인자 14~15개, 상태 문자열 switch 반복 | 완료 | Wave 3 W3-P22 (Wave 3 라운드 3 커밋): P22 W1 `bd0e0bc6`: `IdempotencyScripts.ScriptStatus`(`IdempotencyScripts.java:228`)로 한 번 파싱, switch는 enum, `transition(...)`은 `Transition` record + `Map<ScriptStatus, O>`(`RedisIdempotencyStoreAdapter.java:428`) — 인자 16개→7개 | - | `IdempotencyScripts.Reply`에서 `enum ScriptStatus`로 한 번 파싱, 호출부는 `Map<ScriptStatus,O>` |
| S3-#6 | Consider | 대체 불가능한 확장 지점(`HttpClientTagPolicy` bean) | 완료 | Wave 3 W3-P26 (Wave 3 라운드 2 커밋): `HttpClientObservationAutoConfiguration`의 `HttpClientTagPolicy` bean 삭제(소비처 0, private 생성자라 override 불가). `BlockingExecutionSupport` → `ExecutionSupport` 개명(`HC/restclient/ExecutionSupport.java`, bean `httpClientExecutionSupport` `HttpClientObservationAutoConfiguration.java:24`). 커밋 `93251e76` | - | bean 삭제, `BlockingExecutionSupport`는 `ExecutionSupport`로 개명 |
| S3-#7 | Consider | 구현 1개짜리 인터페이스 4개 | 완료 | Wave 3 W3-P26 (Wave 3 라운드 2 커밋): 삭제: `RetryCoordinator` 인터페이스(구현 `BlockingRetryCoordinator`를 `RetryCoordinator`로 개명, `HC/resilience/RetryCoordinator.java:20`, 테스트 `RetryCoordinatorTest`), `ExecutionEvidenceClassifier` 인터페이스(`DefaultExecutionEvidenceClassifier`를 그 이름으로, `HC/resilience/ExecutionEvidenceClassifier.java:12`). 유지(근거): `RetryEligibilityEngine` — `DefaultGenericHttpGatewayTest:287,311`이 lambda fake를 넣고 `TestGateways.forProfile(.., RetryEligibilityEngine)`이 교체 지점; `BackoffStrategy` — `RetryCoordinatorTest.ambiguousOutcomeIsRaisedRatherThanRetried`·`exhaustedBudgetStopsRetryingImmediately`가 `(a, r, d) -> Duration.ZERO` fake를 씀(삭제 시도 시 컴파일 실패로 확인) | - | 인터페이스 삭제, 구현체를 인터페이스 이름으로 개명 |
| S3-#8a | Consider | `BoundedErrorBody`·`spring7/*`·`migration/*` 도달 불가 | 해당 없음(코드 삭제) | 「제거된 코드」 httpclient `BoundedErrorBody`, Spring 7 service group·`RestTemplate` 이행 패키지 행 | - | - |
| S3-#8b | Consider | `MultipartReplayability`·`SafeHttpLogEvent`는 테스트만 참조 | 완료 | Wave 3 W3-P26 (Wave 3 라운드 2 커밋): `SafeHttpLogEvent`와 전용 테스트 메서드 `HttpClientTagPolicyTest.safeLogEventCarriesNoSecretOrExpandedUrl` 삭제. `MultipartReplayability`는 결정 9 reactive 삭제(`6d27356e` 이전 커밋)로 이미 없음. http3 유지 | - | 두 클래스와 전용 테스트 삭제(http3는 유지) |
| S3-#9 | Consider | `RedisTopologyClientFactory` 662줄 역할 과다 | 남음 | `redis-runtime/.../lettuce/connection/RedisTopologyClientFactory.java` 662줄(변화 없음) | W3 | `RuntimeClient` 구현 3개·`SharedClientResources`를 package-private top-level 클래스로 이동 |
| S3-#9 | Consider | `RedisTopologyClientFactory` 662줄 역할 과다 | 완료 | Wave 3 W3-P22 (Wave 3 라운드 3 커밋): P22 W1 `bd0e0bc6`: `RedisTopologyClientFactory` 662→371줄. `StandaloneRuntimeClient`·`ClusterRuntimeClient`·`AccountRoutingRuntimeClient`·`SharedClientResources`·`LaneConnection`·`ShutdownBudget`를 package-private top-level로 | - | `RuntimeClient` 구현 3개·`SharedClientResources`를 package-private top-level 클래스로 이동 |
| S3-#10 | Consider | settings → profile 필드 단위 복사, `valueOf(toUpperCase())` 반복 | 완료 | Wave 3 W3-P26 (Wave 3 라운드 2 커밋): `HttpClientPlatformSettings`의 enum 필드 7개(`mode`·`transport`·`protocols`·`authentication.type`·`retry.jitter`·`retry.retryAfter`·`proxy.type`)를 enum 타입으로 선언(`HC/autoconfigure/HttpClientPlatformSettings.java:127,131,134,212,225,226,255`), binder가 대소문자 변환. `HttpClientProfileFactory`의 `valueOf(toUpperCase())` 7곳 삭제, 복사 구조 유지. 동작 보존 리팩터라 새 FAIL 테스트 없음 — 기존 `HttpClientPlatformEnvManifestTest`·`UnsafeStartupConfigurationTest`(`SIMPLE`·`HTTP_3`)·`HttpClientPlatformActivationTest.detailSettingsAreNotBoundWhileTheCapabilityIsOff`(`NOT_A_TRANSPORT`) 통과. prefix·strict 바인딩(3-B, S3-lead-2)은 건드리지 않음 | - | settings 필드를 enum 타입으로 선언(binder가 대소문자 변환), 복사 구조는 유지 |
| S3-#11 | Nit | 이력 서술 주석·inline FQN | 남음 | 재측정 "used to/no longer": httpclient 27·redis-runtime 6·redis-sdk 9·cache-redis 7줄, `cache-redis/.../capability/RedisCapabilityConfig.java:30-32` "376 lines … (BOOT-007)", httpclient inline FQN 약 91줄 | W5 | 불변 조건만 남기고 이력은 git/ADR로, FQN은 import로(`HttpMethod`/`HttpStatus` 충돌만 예외) |
| S3-#12a | Nit | `CacheKeys`가 가변 generation 상태 보유, `KeyDigest`가 설정 패키지에 | 남음 | `cache-redis/.../cache/RedisCacheRegionAdapter.java:375,430`(`CacheKeys.observeGeneration`), `capability/RedisKeys.java:37` `KeyDigest` | W5 | `RegionGeneration` 분리, `KeyDigest`를 keyspace 패키지로 옮기고 `RedisNamespace.prefix()` 사용 |
@@ -964,9 +964,9 @@ Wave 3 라운드 1 결과로 받은 4건(2026-09-28, desktop):
| S6-#1c | Required | 조립되지 않는 websocket 플랫폼 라이브러리 약 9.7k줄 | 완료 | main 12,954 → 1,557줄(`stomp/` 491, `servlet`·`outbound`·`budget`·`core`·`protocol` 1,066). 나머지 패키지 삭제(`CS:185,187`). 남긴 라이브러리는 Wave 3 결정대로 README에 라이브러리 API로 명시(`src/adapter/inbound/websocket/README.md:6-13,56`), `6d27356e` | - | - |
| S6-#2a | Required | capability 의존 규칙이 6곳(CDV, DSR, `RedisActivationValidator`, ORBRV, `MasterSwitch`, endpoint)에 흩어짐 (= L-6) | 해당 없음(코드 삭제) | `CS:237`(DSR), `CS:241`(ORBRV), `CS:248`(`MasterSwitch`), `CS:249`(CDV·endpoint), `CS:252`(RAV). capability 의존은 build 줄로 표현(`src/app-bootstrap/build.gradle:139-153`) | - | - |
| S6-#2b | Required | `ca-skeleton.outbox.relay-enabled` 없을 때 기본값 해석이 여전히 갈림 | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): 기본값 불일치만 수정(조립 위치 이동은 X1-#1i, Wave 3 3-C). `OutboxSettingsTest.bindsAllSixDefaultsWhenFieldsAreNull` FAIL("Expecting value to be false but was true") → PASS, `OutboxConfigTest.withoutTheRelayKeyTheRelaySchedulerIsNotAssembled` FAIL(scheduler 조립됨) → PASS. `matchIfMissing` 삭제(`src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxConfig.java:69`), null 기본값 false(`OutboxSettings.java:37`), `src/app-bootstrap/README.md` 문구 | - | relay 조립을 `composition:*` 모듈로 옮길 때(소유자 결정) 기본값을 `false` 하나로: `matchIfMissing` 삭제, `OutboxSettings` null 기본값을 `false`로 |
| S6-#2c | Required | Redis 역할 표 2벌, bootstrap이 Redis 역할별 prod secret 규칙을 앎 | 남음 | `RedisCorrectnessRoles.java:32-37`(redis-runtime) vs `BS/runtime/SecretSourceValidator.java:137-158`(prefix 분기) + 모듈 키 사본 `REDIS_ENABLED_PROPERTY`(`:31`), secret 목록 `:38-48` | W3 | Redis secret 요구 판정을 cache-redis 모듈로 옮기고 `RedisCorrectnessRoles` 표에서 파생; `SecretSourceValidator`는 모듈이 기여한 필요 secret 목록만 검사 |
| S6-#2c | Required | Redis 역할 표 2벌, bootstrap이 Redis 역할별 prod secret 규칙을 앎 | 완료 | Wave 3 W3-P22 (Wave 3 라운드 3 커밋): P22 W2 `7f39bfda`: Redis 역할별 secret 판정은 `cache-redis/.../capability/RedisProductionSecrets.java`가 `RedisCorrectnessRoleSelectors.ROLES`(역할·selector·required·scripted·secret 한 표)에서 파생해 `support.startup.RequiredProductionSecrets` 빈으로 기여(Redis가 켜졌을 때만 존재). `SecretSourceValidator`는 `REQUIRED_PROD_SECRETS`(datasource·pseudonymization salt) + 모듈 기여 목록만 검사하고 `REDIS_ENABLED_PROPERTY`·역할 prefix 분기 삭제. 레지스트리 `secrets-classification.yaml`의 Redis secret 8행에 `required_when`. 테스트 `RedisProductionSecretsTest`(역할별 5 + 비선택 2), `SecretSourceValidatorTest.aSecretAModuleContributedIsRequiredInProd` 외 2건, `SecretsClassificationRegistryTest` 통과 | - | Redis secret 요구 판정을 cache-redis 모듈로 옮기고 `RedisCorrectnessRoles` 표에서 파생; `SecretSourceValidator`는 모듈이 기여한 필요 secret 목록만 검사 |
| S6-#2d | Required | `capabilities.idempotency.provider` 기본값이 `disabled`/`jdbc`로 갈림 | 완료 | 모두 `disabled`: `BS/runtime/SecretSourceValidator.java:151`, `BS/autoconfigure/idempotency/IdempotencyProviderSelectionConfig.java:34`, `SP/bootstrap/idempotency/SampleIdempotencyConfig.java:34`; `jdbc` 값 main 0건, `6d27356e` | - | - |
| S6-#3a | Required | startup validator가 3 lifecycle·여러 패키지에 흩어짐, `StartupRule` 목록 없음 | 남음 | 19 → 16개: bootstrap 7(`BS/runtime/*Validator` 5, `OutboxCanonicalTransportRequirementValidator`, `TracingSamplingEnvironmentPostProcessor`), persistence-jpa 8(`JS/*Validator` 7, `JpaActivationEnvironmentPostProcessor`), cache-redis 1(`RedisReadinessGroupPostProcessor`). EPP 4, `InitializingBean` 1, `SmartInitializingSingleton` 11. `StartupRule` 타입 없음 | W3 | 모듈마다 `StartupRule { List<String> violations(Environment) }` 목록 + runner 1개; bean이 필요한 검사만 bean으로 |
| S6-#3a | Required | startup validator가 3 lifecycle·여러 패키지에 흩어짐, `StartupRule` 목록 없음 | 완료 | Wave 3 W3-P22 (Wave 3 라운드 3 커밋): P22 W2 `7f39bfda`: `support.startup.StartupRule { phase(); summary(); remedy(); List<String> violations(Environment) }` + 러너 하나 `StartupRuleRunner`(`StartupRuleAutoConfiguration`, support `AutoConfiguration.imports`). 환경만 읽는 검사 8개를 규칙으로: bootstrap `RuntimeNumericBoundsValidator`·`ErrorDetailExposureSafetyValidator`, persistence-jpa `RequiredEnvironmentValidator`·`FlywayProdSafetyValidator`·`OpenInViewSafetyValidator`·`PostgreSqlTransportSecurityValidator`·`PersistenceVendorProdSafetyValidator`·`HikariPoolConstraintValidator`. phase·종료 코드와 위반 문구는 유지(메시지 앞머리에 규칙 summary가 붙는 형태만 통일). bean이 필요한 검사(`SecretSourceValidator`, `StartupSafetyValidator`, `JpaDataSourceProfileValidator`, `JpaDangerousConfigurationGuard`)는 bean으로 유지, 부팅 전 EPP(`RuntimeEnvironmentProfileValidator`, `JpaActivationEnvironmentPostProcessor`, `TracingSamplingEnvironmentPostProcessor`, `RedisReadinessGroupPostProcessor`)는 EPP로 유지. `StartupRuleRunnerTest` 3건, 기존 검증기 테스트 전부 통과 | - | 모듈마다 `StartupRule { List<String> violations(Environment) }` 목록 + runner 1개; bean이 필요한 검사만 bean으로 |
| S6-#3b | Required | OSIV 검사 2벌, 뒤 검사의 local 예외는 죽은 코드 | 완료 | Wave 1–2 P9 (fcddab7e·Wave 2 커밋): 행동 보존 정리(FAIL→PASS 대상 아님): `OpenInViewSafetyValidator`(모든 profile 거부)를 정본으로 두고 `JpaDangerousConfigurationGuard`의 OSIV 분기·`OPEN_IN_VIEW_KEY` 삭제(`.../startup/JpaDangerousConfigurationGuard.java`), `JpaPlatformReport`는 validator 상수 사용. `OpenInViewSafetyValidatorTest.openInViewTrueFailsStartupUnderALocalConvenienceProfileToo` 추가(수정 전후 모두 PASS = guard의 local 예외가 죽은 코드였다는 증거). guard 테스트는 ddl-auto만 검사하도록 재작성. 학습 문서 `docs/study/postgresql-jpa-walkthrough.ko.md` 표 갱신 | - | 하나로: local 예외를 정책으로 쓸지 정해 `OpenInViewSafetyValidator`를 삭제하거나 guard의 OSIV 분기를 삭제 |
| S6-#3c | Required | ddl-auto 검사 2벌 | 완료 | Wave 3 W3-P26 (Wave 3 라운드 2 커밋): `JpaSchemaSafetyValidator`(+테스트) 삭제, `JpaDangerousConfigurationGuard`가 유일한 ddl-auto 검사. 기존 validator 테스트의 성질(prod 거부·blank 거부·대소문자·local 허용·`APP_DATASOURCE_DDL_AUTO` 명시·`PROFILE_MISMATCH`)을 guard 테스트로 옮김. `JpaDangerousConfigurationGuardTest.productionRefusesASchemaMutatingDdlAutoAsAProfileMismatchNamingTheEnvironmentKey` 등 10건 FAIL(guard가 `IllegalStateException`을 던짐)→PASS. `persistence-jpa/.../startup/JpaDangerousConfigurationGuard.java:46-66`. README 3곳 갱신 | - | guard 한 곳으로 합치고 `JpaSchemaSafetyValidator` 삭제 |
| S6-#3d | Required | `isProdActive()` 5곳 복사 | 완료 | Wave 3 W3-P26 (Wave 3 라운드 2 커밋): 1줄 wrapper 삭제, 호출부에서 `RuntimeProfileSnapshot.from(environment).isProduction()` 직접 호출: `FlywayProdSafetyValidator`, `PersistenceVendorProdSafetyValidator`, `PostgreSqlTransportSecurityValidator`, `bootstrap/runtime/SecretSourceValidator`. `JpaSchemaSafetyValidator` 몫은 S6-#3c 삭제로 해소. `shared-contract` `RuntimeEnvironment.isProductionActive` 문서의 "isProdActive() copies" 언급은 역사 설명이라 유지. 동작 동일, 기존 테스트 통과 | - | 1줄 wrapper 삭제하고 호출부에서 직접 호출(S6-#3a와 함께) |
@@ -1212,3 +1212,7 @@ Wave 1–2 구현 묶음(`P1`–`P13`)이 작업 중 찾은 결함과 통합 검
| P21-new-1 | 발견 | handler가 `Retry`를 답하면 Kafka consumer가 시도 횟수를 세지 않아 partition이 영구히 멈췄다. | 완료 | Wave 3 P21: 예외와 같은 시도 예산·격리 사용 | - | - |
| P21-new-2 | 발견 | 다시 읽은 delivery가 항상 `deliveryAttempt=1`을 보고했다. | 완료 | Wave 3 P21 | - | - |
| P21-new-3 | 발견 | `src/messaging/CLAUDE.md`가 `MessagingPublicSurfaceContractTest`를 인용 — 테스트는 app-bootstrap에 있다(P21은 없다고 보고). 통합 때 이 테스트가 P21 변경(reactive facade 삭제, leaf 병합, starter-kafka 공개 consumer seam)을 반영하지 못해 실패 → 기대값 수정, starter-kafka에 `api kafka-clients` 선언. | 남음 | Wave 3 라운드 3 통합 | W5 | messaging CLAUDE.md의 테스트 위치 문구를 app-bootstrap 경로로 |
| P22-new-1 | 발견 | bootstrap `SecretSourceValidator`가 persistence-jpa의 모듈 스위치를 읽어 `APP_DATASOURCE_PASSWORD` 필요 여부를 판정(모듈 지식이 bootstrap에). | 남음 | Wave 3 P22 결과 파일 | W3 | Redis처럼 persistence-jpa가 secret 요구를 기여. P20 |
| P22-new-2 | 발견 | `infra/redis-sdk/acl/application.acl`·`all-accounts.acl`이 pub/sub 삭제 뒤에도 `+@pubsub`·`&prod:*`를 준다(최소 권한 위반, fixture). | 남음 | Wave 3 P22 결과 파일 | W3 | ACL fixture에서 제거 후 topology lane 재실행. P20 |
| P22-new-3 | 발견 | redis-sdk 공개 API가 runtime 타입을 노출하면서 runtime을 `implementation`으로만 의존. `ca.spring-library`에 `api` 구성이 없어 한 줄로 못 고침. | 남음 | Wave 3 P22 결과 파일, 통합 때 시도 | W3 | 컨벤션에 `java-library` 적용 또는 공개 표면에서 runtime 타입 제거. P29 |
| ORCH-new-4 | 발견 | redis-sdk `RedisSdkModuleBoundaryTest`·`RedisSupportMatrixTest`가 옛 split package(`redis-runtime/.../redis/sdk`)를 훑음 — P22 worktree에서 통과, main 통합에서 `NoSuchFileException`(ORCH-new-2와 같은 유형: 저장소 파일을 읽지만 test inputs 미선언). | 남음 | 경로는 통합 때 수정(`redis-sdk` 하나) | W4 | 읽는 파일을 test `inputs`로 선언 |
@@ -229,8 +229,8 @@ W1·W2 잔여 21행(Wave 2.5)은 P14로 1라운드에서 함께 처리한다. W1
| P23 | 3 | notification: SES → sesv2(결정 17), `persistence-notification` 추출, SRP | `S1-#4` `S1-#9` `S1-#10b` `S2-#1b` `S2-#6c` `S2-#8a` `S2-#13b` `S4-#3c` `S4-#4b` `S4-#9` `S4-#14b` `S4-#15` `S4-lead-3` `S4-lead-5` |
| P27 | 3 | 빌드 잔여(결정 28·29·31): O3-5 나머지(`ca.release-provenance`·auxiliary → `jvm-test-suite`), messaging 카드 검증 leaf 테스트로, cosign 서명, `INTERNAL_ERROR` retryable=false, persistence-fileserver `ca.api-surface` | `BUILD-결론-1` `BUILD-O3-5` `X1-#7a` `X1-지도-readiness…` `BUILD-계획-C` `P15-new-3` `P16-new-6` |
| P28 | 3 | 로컬 보안 파일시스템 primitive 공용화(보안 민감 재작성, P24에서 분리) + fileserver 잔여 | `S4-lead-2` `P24-new-2` `P25-new-2` `P24-new-3` `S6-#10a` `S1-#6b` `S1-#18b`(결정 32) `S2-#8a` `S2-#13b` `P23-new-1` `P23-new-2` |
| P29 | 4 | 빌드 잔여 2: auxiliary 레인 → Gradle `jvm-test-suite`(P27 중단분, WIP 패치 보관), build-logic 줄 수 판정 | `BUILD-O3-5` `BUILD-결론-1` |
| P20 | 4 | 3-B 설정 prefix `app.*`(결정 16), strict 바인딩 | `X2-P1-3c` `S3-lead-2` `S3-lead-4` `S6-#14` `P11-new-1` |
| P29 | 4 | 빌드 잔여 2: auxiliary 레인 → Gradle `jvm-test-suite`(P27 중단분, WIP 패치 보관), build-logic 줄 수 판정 | `BUILD-O3-5` `BUILD-결론-1` `P22-new-3` |
| P20 | 4 | 3-B 설정 prefix `app.*`(결정 16), strict 바인딩 | `X2-P1-3c` `S3-lead-2` `S3-lead-4` `S6-#14` `P11-new-1` `P22-new-1` `P22-new-2` |
- [x] 라운드 1: P14 · P15 · P16 · P17 → 통합·검증·커밋 (2026-09-28, `9fdb0af4`·`c4a066df`·라운드 1 마무리 커밋)
- [x] 라운드 2: P18 · P24 · P25 · P26 → 통합·검증·커밋 (2026-09-28~29, `4fb7943b`·`64a83918`·`25de288a`·`423a29c4`)
-6
View File
@@ -138,9 +138,6 @@ APP_CACHE_REDIS_NEGATIVE_TTL=10s
APP_IDEMPOTENCY_REDIS_COMMAND_TIMEOUT=200ms
APP_LEASE_REDIS_COMMAND_TIMEOUT=200ms
APP_LEASE_REDIS_CONTENTION_RETRY_AFTER=50ms
APP_REDIS_ADMIN_CREDENTIAL_REFERENCE=
APP_REDIS_ADMIN_ENABLED=false
APP_REDIS_BLOCKING_MAX_CONNECTIONS=32
APP_REDIS_DATABASE=0
APP_REDIS_MODE=standalone
APP_REDIS_NAMESPACE_DOMAIN=shared
@@ -150,11 +147,9 @@ APP_REDIS_NODES=localhost:6379
APP_REDIS_TIMEOUT_BATCH=2s
APP_REDIS_TIMEOUT_FAST=500ms
APP_REDIS_TIMEOUT_SCRIPT=1s
APP_REDIS_TRANSACTION_MAX_CONNECTIONS=16
APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE=
APP_REDIS_AUTHENTICATION_ANONYMOUS_ACCESS_ACCEPTED=false
APP_REDIS_AUTHENTICATION_CREDENTIAL_REFERENCE=
APP_REDIS_AUTHENTICATION_PUBSUB_CREDENTIAL_REFERENCE=
APP_REDIS_CAPACITY_MAXIMUM_IN_FLIGHT_COMMANDS=64
APP_REDIS_CAPACITY_MAXIMUM_SCRIPT_CONNECTIONS=8
APP_REDIS_CAPACITY_REJECT_WHEN_DISCONNECTED=true
@@ -166,7 +161,6 @@ APP_REDIS_LIFECYCLE_CONNECT_TIMEOUT=2s
APP_REDIS_LIFECYCLE_DRAIN_TIMEOUT=6s
APP_REDIS_LIFECYCLE_SHUTDOWN_QUIET_PERIOD=100ms
APP_REDIS_LIFECYCLE_SHUTDOWN_TIMEOUT=3s
APP_REDIS_PUBSUB_BUFFER_CAPACITY=1024
APP_REDIS_SENTINEL_CREDENTIAL_REFERENCE=
APP_REDIS_SENTINEL_MASTER_NAME=
APP_REDIS_SENTINEL_NODES=app.redis.nodes
+35 -28
View File
@@ -22,25 +22,32 @@ Package root: `dev.caskeleton.adapter.outbound.cache`.
- Keep the legacy cache router isolated while consumers migrate to semantic ports.
- Reuse `adapter:outbound:support` for shared outbound concerns.
- Depend on `:adapter:outbound:redis-runtime` for the shared topology client, connection lifecycle,
low-level gateway and conditional Redis runtime composition used by the semantic adapters.
the eight `SemanticRedisCommands` and conditional Redis runtime composition used by the semantic
adapters.
- Keep the general-purpose typed SDK in the separate library leaf `:adapter:outbound:redis-sdk`
(see its `README.md`). This leaf does not depend on it in any configuration, tests included; the
SDK's tests and lanes live in that leaf.
## Redis runtime and optional typed SDK (`…cache.redis.sdk`)
## Redis runtime (`…cache.redis.runtime`) and optional typed SDK (`…cache.redis.sdk`)
The package namespace is shared across two registered Gradle leaves, but their deployment roles are
different.
Two registered leaves, two packages, one direction: the SDK builds on the runtime, the runtime knows
nothing of the SDK (`RedisRuntimePackageBoundaryTest` in the runtime holds that direction).
- `:adapter:outbound:redis-runtime` is production substrate: settings binding, credential
resolution, topology clients, `RedisRuntimeOwner`, the low-level command gateway and health.
`cache-redis` depends on this leaf.
- `:adapter:outbound:redis-sdk` owns the optional general-purpose typed API, command catalog/policy,
operation budgets, command guard, raw/admin surfaces, programmability and extensions.
`cache-redis` does **not** depend on it, in production or in tests.
- The semantic cache/idempotency/rate-limit/lease/realtime adapters in this leaf intentionally call
the runtime gateway through their own closed semantic programs/contracts. They do not pass through
`CommandPolicyGuard`, and `redis-command-policy.yml` does not control those semantic adapters.
- `:adapter:outbound:redis-runtime` is production substrate: `RedisRuntimeSettings` binding,
credential resolution, topology clients, `RedisRuntimeOwner` with the runtime's own lanes
(`RedisConnectionKind.REGULAR`, `SCRIPT`), `SemanticRedisCommands` (the eight commands this leaf
and the health contributor send) and health. `cache-redis` depends on this leaf.
- `:adapter:outbound:redis-sdk` owns the optional general-purpose typed API: `RedisCommandGateway`
(extends `SemanticRedisCommands`), command catalog/policy, operation budgets, command guard,
raw/admin surfaces, programmability and extensions — and its own lanes (`RedisSdkLane`: blocking,
transaction, admin) and admin account, which a service contributes to the runtime as
`RedisLaneContribution`/`RedisAccountContribution` beans (`RedisSdkComposition`). `cache-redis`
does **not** depend on it, in production or in tests.
- The semantic cache/idempotency/rate-limit/lease adapters in this leaf send the runtime's
`SemanticRedisCommands` through their own closed semantic programs (`RegisteredLuaScript`). They
do not pass through `CommandPolicyGuard`, and `redis-command-policy.yml` does not control them.
- Which roles need Redis for correctness is this leaf's `RedisCorrectnessRoleSelectors`, registered
in `META-INF/spring.factories` as the runtime's `RedisCorrectnessRequirement`.
The typed SDK described in
`docs/superpowers/specs/2026-08-07-redis-wrapper-typed-api-design.md` remains an optional library
@@ -86,9 +93,9 @@ in `docs/superpowers/plans/2026-08-07-redis-wrapper-typed-api-status.md`.
only a pre-filter — and all of them build commands through `ExtensionCommandRunner` so the guard
sees their keys. Search is the exception that proves it: an index is not a key, so its name is
namespaced by `LettuceRedisSearchOperations` itself.
- `RedisSdkModuleBoundaryTest` (in `redis-sdk`) scans both `redis-runtime` and `redis-sdk` source
roots and enforces the internal package graph, driver containment, the absence of an arbitrary string
command surface, and the designed module list.
- `RedisSdkModuleBoundaryTest` (in `redis-sdk`) scans the `redis-sdk` source root and enforces the
internal package graph, driver containment, the absence of an arbitrary string command surface,
and the designed module list.
- Decisions that must not be changed without revisiting the design: no unbounded `entries`,
`members`, `rangeAll`, or `keys`; no optional R2 permit or budget; no arbitrary command string
overload; no automatic retry of a non-idempotent write after a timeout; no real key in a metric or
@@ -113,9 +120,9 @@ in `docs/superpowers/plans/2026-08-07-redis-wrapper-typed-api-status.md`.
## Tests
Focused tests drive the semantic adapters against the in-memory gateway from
`testFixtures(project(':adapter:outbound:redis-runtime'))` (`InMemoryGatewayAccess`), the one fake
of `RedisCommandGateway`. R1/R2 promotion requires a separate real Redis service lane; it may never
Focused tests drive the semantic adapters against `InMemorySemanticRedisCommands` from
`testFixtures(project(':adapter:outbound:redis-runtime'))`, the one fake of `SemanticRedisCommands`,
served through `StubRedisRuntimeClient`. R1/R2 promotion requires a separate real Redis service lane; it may never
be silently skipped when selected.
`redisTopologyTest` is the only real-server lane, declared through `ca.redis-topology-lane`. This
@@ -137,7 +144,7 @@ containing the same text satisfied it. A hand-maintained per-mode floor on the e
## Composition
`RedisSdkAutoConfiguration` now belongs to `:adapter:outbound:redis-runtime`. It is the only
`RedisRuntimeAutoConfiguration` now belongs to `:adapter:outbound:redis-runtime`. It is the only
place Redis settings and the shared runtime substrate come into existence, and it exists only while
`app.redis.enabled` (env `APP_REDIS_ENABLED`, default `true` — the module is on when present) is
true. It builds the topology client, connection owner and health contributors; `RedisCapabilityConfig`
@@ -153,19 +160,19 @@ Every capability renders its keys under the one namespace from `app.redis.namesp
prefix tokens: four capabilities each joining two free-form strings produced four different key
shapes, and the deployment's ACL pattern matched none of them.
Lanes authenticate as different accounts. `RedisConnectionKind.credentialRole()` maps the lane to a
`RedisCredentialRole`, and the topology factory builds one client per *configured* role — so a
single-account deployment still gets exactly one client and one event loop. The `SCRIPT` lane is
Lanes authenticate as different accounts. `RedisLane.account()` names the lane's `RedisAccount`,
and the topology factory builds one client per *configured* account — so a single-account
deployment still gets exactly one client and one event loop. The `SCRIPT` lane is
the reason it exists: `SCRIPT LOAD` and `EVALSHA` belong to the advanced account, so the account
that reads a cache entry cannot execute a script.
A Cluster transaction runs on one node, so `RedisTransactionRunner` derives a routing key from the
watched keys (or an explicit `RedisSlotTag`) and pins the `TRANSACTION` lane to the node that owns
that slot. Routed leases are never pooled: a pooled connection is pinned to the previous caller's
A Cluster transaction runs on one node, so the SDK's `RedisTransactionRunner` derives a routing key
from the watched keys (or an explicit `RedisSlotTag`) and borrows `RedisSdkLane.TRANSACTION`, which
is pinned to its key's owner, on the node that owns that slot. Routed leases are never pooled: a pooled connection is pinned to the previous caller's
node.
`RedisSdkSettings`
must never carry a class-level `@ConfigurationProperties`: `RedisSdkAutoConfiguration` binds it, so
`RedisRuntimeSettings`
must never carry a class-level `@ConfigurationProperties`: `RedisRuntimeAutoConfiguration` binds it, so
`APP_REDIS_ENABLED=false` binds no Redis configuration at all. A properties scan that reached this
package would bind it regardless (bootstrap's `@ConfigurationPropertiesScan` lists only
`dev.caskeleton.bootstrap.*` packages). Role selectors (cache binding, session auth-mode, idempotency/lease/rate-limit provider)
+10 -6
View File
@@ -4,15 +4,17 @@ This module is the **semantic Redis capability adapter**, not a general Redis SD
The Redis implementation is deliberately split into three Gradle leaves:
- `:adapter:outbound:redis-runtime` — shipped connection/topology/settings/gateway substrate.
- `:adapter:outbound:redis-runtime` (`dev.caskeleton.adapter.outbound.cache.redis.runtime`) —
shipped connection/topology/settings substrate: `RedisRuntimeSettings`, the lane owner, and the
eight `SemanticRedisCommands` this module sends. It knows nothing of the typed SDK.
- `:adapter:outbound:cache-redis` — shipped application-facing cache, rate-limit, lease and
idempotency adapters.
- `:adapter:outbound:redis-sdk` — optional typed/general-purpose SDK. It is not on the default
application runtime graph.
The default application therefore does not acquire the optional SDK's command policy merely by
selecting a semantic Redis capability. Semantic adapters call the runtime gateway directly and own
their own correctness rules.
selecting a semantic Redis capability. Semantic adapters call the runtime's `SemanticRedisCommands`
directly and own their own correctness rules.
## Using it as a capability module — what it provides, the one line, the env keys
@@ -29,12 +31,14 @@ runtimeOnly project(':adapter:outbound:cache-redis') // brings :adapter:outbou
- the port implementations the role selectors ask for — `CacheRegionPort` (cache),
`EdgeRateLimitPort` (rate limit), `DistributedLeasePort` (lease), `IdempotencyStorePort`
(idempotency; the application builds the executor over it);
- `RedisCapabilityConfig` (`AutoConfiguration.imports`, after `RedisSdkAutoConfiguration`). With
`APP_REDIS_ENABLED=false` neither it nor redis-runtime's `RedisSdkAutoConfiguration` contributes a
- `RedisCapabilityConfig` (`AutoConfiguration.imports`, after `RedisRuntimeAutoConfiguration`). With
`APP_REDIS_ENABLED=false` neither it nor redis-runtime's `RedisRuntimeAutoConfiguration` contributes a
bean — no settings, client, connection, thread or health contributor. The module pulls no Spring
Data Redis, so there is no Boot Redis auto-configuration to exclude;
- the readiness contribution `RedisReadinessGroupPostProcessor` (this module's `spring.factories`):
`redisRequired` joins the readiness group only when a correctness role selects Redis;
`redisRequired` joins the readiness group only when a correctness role selects Redis. Which roles
those are is this module's `RedisCorrectnessRoleSelectors`, registered in the same file as the
runtime's `RedisCorrectnessRequirement` — the runtime asks, it does not list selectors;
- the shipped settings `config/module-defaults/cache-redis.yml` — `app.redis.enabled`,
`app.rate-limit.*`, and the Redis parts of `ca-skeleton.capabilities.*` (cache, lease, rate-limit,
the Redis idempotency store's tuning). The support leaf's `ModuleDefaultsEnvironmentPostProcessor`
@@ -18,6 +18,8 @@ dependencies {
// The in-memory gateway and the topology endpoint the semantic adapter tests run against.
testImplementation testFixtures(project(':adapter:outbound:redis-runtime'))
// The lease port's ownership contract, which the Redis adapter runs like the in-memory fake.
testImplementation testFixtures(project(':application-core'))
// RedisReadinessGroupPostProcessorTest boots a real actuator health context: the readiness group
// and its membership validation are what the post-processor exists to keep bootable.
testImplementation 'org.springframework.boot:spring-boot-starter-actuator'
@@ -49,6 +51,8 @@ dependencies {
// validation, tag selection, TLS mapping and no-skip enforcement. The leaf names the classes each
// of its lanes exists to run. Sentinel and TLS are qualified by redis-runtime and redis-sdk.
redisTopologyLane {
requiredClasses 'standalone', 'LiveRedisSemanticPortsTest', 'LiveRedisSemanticScriptAclProbeTest'
requiredClasses 'cluster', 'LiveRedisSemanticPortsTest', 'LiveRedisSemanticScriptAclProbeTest'
requiredClasses 'standalone', 'LiveRedisSemanticPortsTest', 'LiveRedisSemanticScriptAclProbeTest',
'LiveRedisDistributedLeaseContractTest'
requiredClasses 'cluster', 'LiveRedisSemanticPortsTest', 'LiveRedisSemanticScriptAclProbeTest',
'LiveRedisDistributedLeaseContractTest'
}
@@ -0,0 +1,179 @@
package dev.caskeleton.adapter.outbound.cache.redis;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.Objects;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.atomic.AtomicReference;
import java.util.function.BiFunction;
/**
* One Lua program the semantic adapters run by digest: load once, {@code EVALSHA} after, and load
* again exactly once when the server says it no longer has it.
*
* <p>A server forgets its scripts on restart, on {@code SCRIPT FLUSH}, and on failover to a replica
* that never saw the load. The only signal is a {@code NOSCRIPT} reply, and it does not always
* arrive as Lettuce's {@code RedisNoScriptException}: through some proxies and wrapped driver paths
* it is a plain command failure whose message starts with {@code NOSCRIPT}. Four hand-written
* copies of this helper disagreed about that — one checked the message, three only the type — so a
* lease, a rate limit or an idempotency claim failed on a reply the cache recovered from.
*
* <p>The reply decoding the three array-returning programs share lives here too ({@link #number},
* {@link #text}): a Lua integer arrives as a {@code Long}, a status or a string as bytes, and each
* program used to carry its own copy of the conversion.
*/
public final class RegisteredLuaScript {
private final byte[] source;
private final AtomicReference<String> digest = new AtomicReference<>();
/**
* Creates the program.
*
* @param source the Lua source, which never changes for the life of this object
*/
public RegisteredLuaScript(String source) {
this.source =
Objects.requireNonNull(source, "source must be non-null").getBytes(StandardCharsets.UTF_8);
}
/**
* Runs the program on one key and returns its array reply.
*
* @param commands the commands of a borrowed SCRIPT lease
* @param key the single key the program touches
* @param arguments the program's arguments
* @return the reply values
*/
public CompletionStage<List<Object>> evaluateForList(
SemanticRedisCommands commands, byte[] key, List<byte[]> arguments) {
return run(
commands, (loaded, server) -> server.evaluateRegisteredForList(loaded, key, arguments));
}
/**
* Runs the program on one key and returns its integer reply.
*
* @param commands the commands of a borrowed lease
* @param key the single key the program touches
* @param arguments the program's arguments
* @return the integer reply
*/
public CompletionStage<Long> evaluateForLong(
SemanticRedisCommands commands, byte[] key, List<byte[]> arguments) {
return run(
commands, (loaded, server) -> server.evaluateRegisteredForLong(loaded, key, arguments));
}
private <R> CompletionStage<R> run(
SemanticRedisCommands commands,
BiFunction<String, SemanticRedisCommands, CompletionStage<R>> evaluation) {
return digest(commands)
.thenCompose(loaded -> evaluation.apply(loaded, commands))
.handle(
(reply, failure) -> {
if (failure == null) {
return CompletableFuture.completedFuture(reply);
}
if (!scriptMissing(failure)) {
return CompletableFuture.<R>failedFuture(failure);
}
// Once. A server that forgets a script it was just given is not going to remember it
// on the third try, and a loop here would hide that.
digest.set(null);
return digest(commands).thenCompose(loaded -> evaluation.apply(loaded, commands));
})
.thenCompose(stage -> stage);
}
private CompletionStage<String> digest(SemanticRedisCommands commands) {
String cached = digest.get();
if (cached != null) {
return CompletableFuture.completedFuture(cached);
}
return commands
.loadScript(source)
.thenApply(
loaded -> {
digest.set(loaded);
return loaded;
});
}
/**
* Reports whether a failure is the server saying it does not have the script.
*
* @param failure the failure, possibly wrapped by the future that carried it
* @return {@code true} for a {@code NOSCRIPT} reply, typed or not
*/
static boolean scriptMissing(Throwable failure) {
Throwable cause = failure;
while ((cause instanceof CompletionException || cause instanceof ExecutionException)
&& cause.getCause() != null) {
cause = cause.getCause();
}
return cause instanceof io.lettuce.core.RedisNoScriptException
|| (cause.getMessage() != null && cause.getMessage().startsWith("NOSCRIPT"));
}
/**
* Reads an integer element of a program's reply.
*
* @param value the element: a {@code Long}, or bytes carrying digits
* @return the number, {@code 0} for an empty element
* @throws IllegalStateException when the element is neither
*/
public static long number(Object value) {
if (value instanceof Number n) {
return n.longValue();
}
if (value instanceof byte[] bytes) {
String text = new String(bytes, StandardCharsets.UTF_8).strip();
return text.isEmpty() ? 0L : Long.parseLong(text);
}
throw new IllegalStateException(
"a registered program answered with an unexpected value type: "
+ (value == null ? "null" : value.getClass().getName()));
}
/**
* Reads a string element of a program's reply.
*
* @param value the element: bytes, or anything else printed as-is
* @return the text, empty for {@code null}
*/
public static String text(Object value) {
if (value instanceof byte[] bytes) {
return new String(bytes, StandardCharsets.UTF_8);
}
return value == null ? "" : String.valueOf(value);
}
/**
* Checks that a program's array reply has the shape it promises.
*
* @param reply the reply
* @param size the number of elements the program returns
* @param program the program's name, for the failure message
* @return the reply
* @throws IllegalStateException when the reply is absent or short
*/
public static List<Object> requireShape(List<Object> reply, int size, String program) {
if (reply == null || reply.size() < size) {
throw new IllegalStateException(
"the "
+ program
+ " program answered with "
+ (reply == null ? "nothing" : reply.size() + " values")
+ "; "
+ size
+ " were expected");
}
return reply;
}
}
@@ -0,0 +1,168 @@
package dev.caskeleton.adapter.outbound.cache.redis;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLane;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLaneUnavailableException;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLease;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import java.time.Duration;
import java.util.Objects;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.TimeUnit;
import java.util.function.Supplier;
/**
* One semantic adapter call on Redis: borrow a lane, send, wait a bounded time, and turn every way
* that can fail into one of two answers the caller can act on.
*
* <p>The two answers are the whole point, and they are not "success" and "failure":
*
* <ul>
* <li><b>not sent</b> — nothing can have happened: the runtime refused a lease before any command
* existed, or the call failed before it {@linkplain Session#markSent() marked} the write as
* handed to the driver. The caller may treat the operation as unavailable and retry it.
* <li><b>unknown</b> — the command may have run. A timeout, a lost reply, an interrupted wait:
* the caller must not be told "failed", because retrying an effect that already landed is how
* it happens twice.
* </ul>
*
* <p>Sixteen hand-written copies of this frame — borrow, {@code .get(timeout)}, catch {@code
* InterruptedException}, catch the runtime's refusal, catch everything else — lived in the four
* adapters, and the difference between their two answers was re-derived in each. Every failure is
* reported to {@link RedisSemanticFailureLogger} except an interrupt, which is the caller's own
* doing.
*/
public final class SemanticRedisCall {
private final RedisRuntimeOwner owner;
private final RedisLane lane;
private final Duration timeout;
private final String capability;
/**
* Creates the call frame for one capability.
*
* @param owner the runtime owner leases come from
* @param lane the lane this capability's calls run on
* @param timeout the ceiling on each awaited reply
* @param capability the capability name the failure log carries
*/
public SemanticRedisCall(
RedisRuntimeOwner owner, RedisLane lane, Duration timeout, String capability) {
this.owner = Objects.requireNonNull(owner, "runtime owner must be non-null");
this.lane = Objects.requireNonNull(lane, "lane must be non-null");
this.timeout = Objects.requireNonNull(timeout, "timeout must be non-null");
this.capability = Objects.requireNonNull(capability, "capability must be non-null");
}
/**
* Runs a call whose command may take effect as soon as it is sent.
*
* <p>For the registered programs: the call counts as sent from the start, so anything but the
* runtime's own refusal — a connection that could not be opened included — is an unknown outcome.
* A caller told "unavailable" after a failure it cannot rule out having reached the server would
* retry an effect that may already have landed.
*
* @param operation the semantic operation, for the failure log
* @param body what to send, and how to read the reply
* @param notSent the answer when nothing can have happened
* @param unknown the answer when the command may have run
* @param <R> the answer type
* @return the body's answer, or one of the two failure answers
*/
public <R> R effect(String operation, Body<R> body, Supplier<R> notSent, Supplier<R> unknown) {
return call(operation, body, notSent, unknown, true);
}
/**
* Runs a call that decides for itself when its effect was handed to the driver.
*
* @param operation the semantic operation, for the failure log
* @param body what to send, and how to read the reply; calls {@link Session#markSent()} before
* the command whose loss would leave the outcome unknown
* @param notSent the answer when nothing can have happened
* @param unknown the answer when the command may have run
* @param <R> the answer type
* @return the body's answer, or one of the two failure answers
*/
public <R> R run(String operation, Body<R> body, Supplier<R> notSent, Supplier<R> unknown) {
return call(operation, body, notSent, unknown, false);
}
private <R> R call(
String operation,
Body<R> body,
Supplier<R> notSent,
Supplier<R> unknown,
boolean sentFromStart) {
Session session = new Session();
session.sent = sentFromStart;
try (RedisLease lease = owner.borrow(lane)) {
session.lease = lease;
return body.apply(session);
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return session.sent ? unknown.get() : notSent.get();
} catch (RedisLaneUnavailableException refused) {
RedisSemanticFailureLogger.report(capability, operation, refused);
return notSent.get();
} catch (Exception failure) {
RedisSemanticFailureLogger.report(capability, operation, failure);
return session.sent ? unknown.get() : notSent.get();
}
}
/** What a call sends, given the borrowed connection. */
@FunctionalInterface
public interface Body<R> {
/**
* Sends and reads.
*
* @param session the borrowed connection and its bounded wait
* @return the answer
* @throws Exception any failure, classified by the frame
*/
R apply(Session session) throws Exception;
}
/** The borrowed connection, for the duration of one call. */
public final class Session {
private RedisLease lease;
private boolean sent;
private Session() {}
/**
* Returns the commands of the borrowed connection.
*
* @return the commands
*/
public SemanticRedisCommands commands() {
return lease.commands();
}
/**
* Waits for a reply, no longer than the call's timeout.
*
* @param reply the pending reply
* @param <V> the reply type
* @return the reply
* @throws Exception the reply's failure, a timeout, or an interrupt
*/
public <V> V await(CompletionStage<V> reply) throws Exception {
return reply.toCompletableFuture().get(timeout.toNanos(), TimeUnit.NANOSECONDS);
}
/**
* Records that the command whose loss leaves the outcome unknown is about to be sent.
*
* <p>A failure before this — a refused lease, a failed read that precedes the write — wrote
* nothing.
*/
public void markSent() {
sent = true;
}
}
}
@@ -1,13 +1,10 @@
package dev.caskeleton.adapter.outbound.cache.redis.cache;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.adapter.outbound.cache.redis.RegisteredLuaScript;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.atomic.AtomicReference;
/** Atomic cache mutations that cannot be expressed as one ordinary Redis command. */
final class CacheScripts {
@@ -25,10 +22,11 @@ final class CacheScripts {
return 1
""";
private final AtomicReference<String> replaceIfObservedDigest = new AtomicReference<>();
private final RegisteredLuaScript replaceIfObserved =
new RegisteredLuaScript(REPLACE_IF_OBSERVED);
CompletionStage<Boolean> replaceIfObserved(
RedisCommandGateway gateway,
SemanticRedisCommands commands,
byte[] key,
String observation,
byte[] replacement,
@@ -38,51 +36,8 @@ final class CacheScripts {
observation.getBytes(StandardCharsets.US_ASCII),
replacement,
Long.toString(ttlMillis).getBytes(StandardCharsets.US_ASCII));
return digest(gateway)
.thenCompose(
loaded ->
gateway
.evaluateRegisteredForLong(loaded, key, arguments)
.handle(
(reply, failure) ->
failure == null
? CompletableFuture.completedFuture(reply)
: reload(gateway, key, arguments, failure))
.thenCompose(stage -> stage))
return replaceIfObserved
.evaluateForLong(commands, key, arguments)
.thenApply(applied -> applied != null && applied == 1L);
}
private CompletionStage<String> digest(RedisCommandGateway gateway) {
String cached = replaceIfObservedDigest.get();
if (cached != null) {
return CompletableFuture.completedFuture(cached);
}
return gateway
.loadScript(REPLACE_IF_OBSERVED.getBytes(StandardCharsets.UTF_8))
.thenApply(
loaded -> {
replaceIfObservedDigest.set(loaded);
return loaded;
});
}
private CompletionStage<Long> reload(
RedisCommandGateway gateway, byte[] key, List<byte[]> arguments, Throwable failure) {
if (!scriptMissing(failure)) {
return CompletableFuture.failedFuture(failure);
}
replaceIfObservedDigest.set(null);
return digest(gateway)
.thenCompose(loaded -> gateway.evaluateRegisteredForLong(loaded, key, arguments));
}
private static boolean scriptMissing(Throwable failure) {
Throwable cause = failure;
while ((cause instanceof CompletionException || cause instanceof ExecutionException)
&& cause.getCause() != null) {
cause = cause.getCause();
}
return cause instanceof io.lettuce.core.RedisNoScriptException
|| (cause.getMessage() != null && cause.getMessage().startsWith("NOSCRIPT"));
}
}
@@ -1,11 +1,10 @@
package dev.caskeleton.adapter.outbound.cache.redis.cache;
import dev.caskeleton.adapter.outbound.cache.redis.RedisSemanticFailureLogger;
import dev.caskeleton.adapter.outbound.cache.redis.SemanticRedisCall;
import dev.caskeleton.adapter.outbound.cache.redis.keyspace.CapabilityKeyspace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisLease;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.application.cache.AuthoritativeAbsence;
import dev.caskeleton.application.cache.CacheInvalidationOutcome;
import dev.caskeleton.application.cache.CacheLookup;
@@ -19,7 +18,6 @@ import java.time.Clock;
import java.time.Duration;
import java.time.Instant;
import java.util.Objects;
import java.util.concurrent.TimeUnit;
import java.util.function.Function;
/**
@@ -54,7 +52,7 @@ import java.util.function.Function;
*/
public final class RedisCacheRegionAdapter<K, V> implements CacheRegionPort<K, V> {
private final RedisRuntimeOwner owner;
private final SemanticRedisCall call;
private final CacheKeys keys;
@@ -72,8 +70,6 @@ public final class RedisCacheRegionAdapter<K, V> implements CacheRegionPort<K, V
private final Duration negativeTtl;
private final Duration commandTimeout;
private final CacheScripts scripts = new CacheScripts();
/**
@@ -101,7 +97,12 @@ public final class RedisCacheRegionAdapter<K, V> implements CacheRegionPort<K, V
Duration hardTtl,
Duration negativeTtl,
Duration commandTimeout) {
this.owner = Objects.requireNonNull(owner, "runtime owner must be non-null");
this.call =
new SemanticRedisCall(
owner,
RedisConnectionKind.REGULAR,
Objects.requireNonNull(commandTimeout, "command timeout must be non-null"),
"cache");
this.keys = Objects.requireNonNull(keys, "keys must be non-null");
this.keyDigest = Objects.requireNonNull(keyDigest, "key digest must be non-null");
this.encoder = Objects.requireNonNull(encoder, "encoder must be non-null");
@@ -110,8 +111,6 @@ public final class RedisCacheRegionAdapter<K, V> implements CacheRegionPort<K, V
this.softTtl = Objects.requireNonNull(softTtl, "soft TTL must be non-null");
this.hardTtl = Objects.requireNonNull(hardTtl, "hard TTL must be non-null");
this.negativeTtl = Objects.requireNonNull(negativeTtl, "negative TTL must be non-null");
this.commandTimeout =
Objects.requireNonNull(commandTimeout, "command timeout must be non-null");
if (softTtl.compareTo(hardTtl) > 0) {
throw new IllegalArgumentException(
"the soft TTL must not exceed the hard TTL: an entry cannot stop being fresh after it has"
@@ -123,27 +122,23 @@ public final class RedisCacheRegionAdapter<K, V> implements CacheRegionPort<K, V
public CacheLookup<V> lookup(K key) {
Objects.requireNonNull(key, "key must be non-null");
Instant now = clock.instant();
try (RedisLease lease = owner.borrow(RedisConnectionKind.REGULAR)) {
resolveGeneration(lease, now);
byte[] stored =
lease
.gateway()
.get(keys.entryKey(keyDigest.apply(key)))
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
if (stored == null) {
return new CacheLookup.Miss<>(
CacheLookup.MissReason.ABSENT, CacheWriteCondition.unavailable());
}
return interpret(stored, now);
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return unavailable();
} catch (Exception failure) {
RedisSemanticFailureLogger.report("cache", "lookup", failure);
// Degraded, not broken. The caller loads from the source and carries on.
return unavailable();
}
// A read changed nothing, whether or not it reached the server: degraded, not broken. The
// caller
// loads from the source and carries on.
return call.run(
"lookup",
session -> {
resolveGeneration(session, now);
byte[] stored =
session.await(session.commands().get(keys.entryKey(keyDigest.apply(key))));
if (stored == null) {
return new CacheLookup.Miss<>(
CacheLookup.MissReason.ABSENT, CacheWriteCondition.unavailable());
}
return interpret(stored, now);
},
this::unavailable,
this::unavailable);
}
private CacheLookup<V> interpret(byte[] stored, Instant now) {
@@ -223,98 +218,70 @@ public final class RedisCacheRegionAdapter<K, V> implements CacheRegionPort<K, V
Instant now = clock.instant();
Duration effectiveSoft = softTtl.compareTo(ttl) > 0 ? ttl : softTtl;
byte[] physicalKey = keys.entryKey(keyDigest.apply(key));
// Whether the write command itself was handed to the driver. A failure before that point —
// lane refusal, connection, the generation read — wrote nothing.
boolean sent = false;
try (RedisLease lease = owner.borrow(RedisConnectionKind.REGULAR)) {
resolveGeneration(lease, now);
CacheEnvelope envelope =
new CacheEnvelope(
CacheEnvelope.CURRENT_SCHEMA_VERSION,
metadata.sourceRevision(),
keys.generation(),
now.plus(effectiveSoft),
now.plus(ttl),
absence,
payload);
Boolean applied;
sent = true;
if (metadata.intent() == CacheRecordIntent.ONLY_IF_OBSERVED) {
// Compare and replacement are one server-side execution. A GET followed by SET would let a
// concurrent writer land between them and then be overwritten by this stale source load.
applied =
scripts
.replaceIfObserved(
lease.gateway(),
physicalKey,
metadata.observedToken().value(),
envelope.encode(),
ttl.toMillis())
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
} else {
applied =
lease
.gateway()
.set(
physicalKey,
envelope.encode(),
presenceOf(metadata.intent()),
// The physical TTL is the hard expiry and nothing else.
new dev.caskeleton.adapter.outbound.cache.redis.sdk.api.operations.Expiration
.After(ttl))
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
}
return Boolean.TRUE.equals(applied)
? CacheRecordOutcome.RECORDED
: CacheRecordOutcome.NOT_RECORDED_CONDITION;
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return sent ? CacheRecordOutcome.INDETERMINATE : CacheRecordOutcome.DEGRADED_UNAVAILABLE;
} catch (Exception failure) {
RedisSemanticFailureLogger.report("cache", "record", failure);
return sent ? CacheRecordOutcome.INDETERMINATE : CacheRecordOutcome.DEGRADED_UNAVAILABLE;
}
// The write is marked sent only when the write command itself is handed to the driver. A
// failure before that point — lane refusal, connection, the generation read — wrote nothing.
return call.run(
"record",
session -> {
resolveGeneration(session, now);
CacheEnvelope envelope =
new CacheEnvelope(
CacheEnvelope.CURRENT_SCHEMA_VERSION,
metadata.sourceRevision(),
keys.generation(),
now.plus(effectiveSoft),
now.plus(ttl),
absence,
payload);
session.markSent();
Boolean applied =
metadata.intent() == CacheRecordIntent.ONLY_IF_OBSERVED
// Compare and replacement are one server-side execution. A GET followed by SET
// would let a concurrent writer land between them and then be overwritten by
// this stale source load.
? session.await(
scripts.replaceIfObserved(
session.commands(),
physicalKey,
metadata.observedToken().value(),
envelope.encode(),
ttl.toMillis()))
// The physical TTL is the hard expiry and nothing else.
: session.await(
session
.commands()
.set(physicalKey, envelope.encode(), presenceOf(metadata.intent()), ttl));
return Boolean.TRUE.equals(applied)
? CacheRecordOutcome.RECORDED
: CacheRecordOutcome.NOT_RECORDED_CONDITION;
},
() -> CacheRecordOutcome.DEGRADED_UNAVAILABLE,
() -> CacheRecordOutcome.INDETERMINATE);
}
private static dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.WritePresence
private static dev.caskeleton.adapter.outbound.cache.redis.runtime.command.WritePresence
presenceOf(CacheRecordIntent intent) {
return intent == CacheRecordIntent.ONLY_IF_ABSENT
? dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.WritePresence.IF_ABSENT
: dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.WritePresence.ALWAYS;
? dev.caskeleton.adapter.outbound.cache.redis.runtime.command.WritePresence.IF_ABSENT
: dev.caskeleton.adapter.outbound.cache.redis.runtime.command.WritePresence.ALWAYS;
}
@Override
public CacheInvalidationOutcome invalidate(K key) {
Objects.requireNonNull(key, "key must be non-null");
boolean sent = false;
try (RedisLease lease = owner.borrow(RedisConnectionKind.REGULAR)) {
byte[] physicalKey = keys.entryKey(keyDigest.apply(key));
sent = true;
byte[] removed =
lease
.gateway()
.getAndDelete(physicalKey)
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
return removed == null
? CacheInvalidationOutcome.ALREADY_ABSENT
: CacheInvalidationOutcome.INVALIDATED;
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return invalidationFailure(sent);
} catch (Exception failure) {
RedisSemanticFailureLogger.report("cache", "invalidate", failure);
return invalidationFailure(sent);
}
}
// A lost reply to a sent delete or generation bump may have applied it.
private static CacheInvalidationOutcome invalidationFailure(boolean sent) {
return sent
? CacheInvalidationOutcome.INDETERMINATE
: CacheInvalidationOutcome.DEGRADED_UNAVAILABLE;
return call.run(
"invalidate",
session -> {
byte[] physicalKey = keys.entryKey(keyDigest.apply(key));
session.markSent();
byte[] removed = session.await(session.commands().getAndDelete(physicalKey));
return removed == null
? CacheInvalidationOutcome.ALREADY_ABSENT
: CacheInvalidationOutcome.INVALIDATED;
},
() -> CacheInvalidationOutcome.DEGRADED_UNAVAILABLE,
// A lost reply to a sent delete may have applied it.
() -> CacheInvalidationOutcome.INDETERMINATE);
}
@Override
@@ -323,24 +290,17 @@ public final class RedisCacheRegionAdapter<K, V> implements CacheRegionPort<K, V
// a server that is answering everything else at the same time, and the SDK blocks KEYS for
// exactly that reason. Bumping the generation makes every older entry fail the generation
// check on read and expire on its own schedule.
boolean sent = false;
try (RedisLease lease = owner.borrow(RedisConnectionKind.REGULAR)) {
sent = true;
Long generation =
lease
.gateway()
.incrementBy(keys.generationKey(), 1)
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
keys.observeGeneration(generation, clock.instant());
return CacheInvalidationOutcome.INVALIDATED;
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return invalidationFailure(sent);
} catch (Exception failure) {
RedisSemanticFailureLogger.report("cache", "invalidate-region", failure);
return invalidationFailure(sent);
}
return call.run(
"invalidate-region",
session -> {
session.markSent();
Long generation = session.await(session.commands().incrementBy(keys.generationKey(), 1));
keys.observeGeneration(generation, clock.instant());
return CacheInvalidationOutcome.INVALIDATED;
},
() -> CacheInvalidationOutcome.DEGRADED_UNAVAILABLE,
// A lost reply to a sent generation bump may have applied it.
() -> CacheInvalidationOutcome.INDETERMINATE);
}
/**
@@ -352,16 +312,11 @@ public final class RedisCacheRegionAdapter<K, V> implements CacheRegionPort<K, V
* the current value and creates the counter at 0 if it is absent, which is both idempotent and
* the same operation on every instance.
*/
private void resolveGeneration(RedisLease lease, Instant now) throws Exception {
private void resolveGeneration(SemanticRedisCall.Session session, Instant now) throws Exception {
if (!keys.shouldRefreshGeneration(now, softTtl)) {
return;
}
Long current =
lease
.gateway()
.incrementBy(keys.generationKey(), 0)
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
Long current = session.await(session.commands().incrementBy(keys.generationKey(), 0));
keys.observeGeneration(current == null ? 0L : current, now);
}
@@ -1,8 +1,8 @@
package dev.caskeleton.adapter.outbound.cache.redis.capability;
import dev.caskeleton.adapter.outbound.cache.redis.cache.RedisCacheRegionAdapter;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkSettings;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeSettings;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.application.cache.CacheRegionPort;
import dev.caskeleton.application.outbound.SecretSourcePort;
import java.time.Clock;
@@ -24,7 +24,7 @@ class RedisCacheConfig {
* The semantic cache region for the default binding.
*
* @param owner the Redis runtime owner
* @param sdk the Redis SDK settings, which own the namespace
* @param redis the Redis runtime settings, which own the namespace
* @param capabilities the capability settings
* @param secretSource resolves the key-digest material
* @param clock the clock expiries are measured against
@@ -36,18 +36,18 @@ class RedisCacheConfig {
havingValue = "redis")
CacheRegionPort<String, byte[]> redisDefaultCacheRegion(
RedisRuntimeOwner owner,
RedisSdkSettings sdk,
RedisRuntimeSettings redis,
RedisCapabilitySettings capabilities,
SecretSourcePort secretSource,
Clock clock) {
RedisCapabilitySettings.Cache cache = capabilities.getCache();
cache.validate();
RedisKeys.KeyDigest digest =
RedisKeys.KeyDigest.of(secretSource, cache.getKeyHmacSecretReference(), "cache", sdk);
RedisKeys.KeyDigest.of(secretSource, cache.getKeyHmacSecretReference(), "cache", redis);
return new RedisCacheRegionAdapter<>(
owner,
new RedisCacheRegionAdapter.CacheKeys(
RedisKeys.namespaceOf(sdk), cache.getSemanticRegion(), cache.getKeyVersion()),
RedisKeys.namespaceOf(redis), cache.getSemanticRegion(), cache.getKeyVersion()),
digest::of,
value -> value,
stored -> stored,
@@ -1,8 +1,8 @@
package dev.caskeleton.adapter.outbound.cache.redis.capability;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkAutoConfiguration;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkSettings;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeAutoConfiguration;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeSettings;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.application.outbound.SecretSourcePort;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
@@ -26,16 +26,17 @@ import org.springframework.context.annotation.Import;
* itself. With the switch off this module contributes no bean at all.
*
* <p>This class is the composition point only: it holds the switch, binds the settings once,
* bridges the secret backend into the SDK, and imports one configuration per capability. It used to
* hold all four capabilities plus rate-limit policy compilation and the key digest — 376 lines, in
* a leaf whose Notification platform had already been split into nine focused configurations. The
* decomposition pattern existed; this was simply where it had not been applied (BOOT-007).
* bridges the secret backend into the Redis runtime, and imports one configuration per capability.
* It used to hold all four capabilities plus rate-limit policy compilation and the key digest — 376
* lines, in a leaf whose Notification platform had already been split into nine focused
* configurations. The decomposition pattern existed; this was simply where it had not been applied
* (BOOT-007).
*
* <p>The namespace comes from {@code app.redis.namespace} for every capability. That is the change
* that makes the ACL pattern meaningful: one prefix, {@code {environment}:{service}:{domain}}, that
* the deployment's {@code ~} pattern can actually fence.
*/
@AutoConfiguration(after = RedisSdkAutoConfiguration.class)
@AutoConfiguration(after = RedisRuntimeAutoConfiguration.class)
@EnableConfigurationProperties(RedisCapabilitySettings.class)
// The global switch, not a role selector. A role selector says which capability composes; it
// never says Redis exists.
@@ -52,29 +53,40 @@ import org.springframework.context.annotation.Import;
public class RedisCapabilityConfig {
/**
* Bridges the deployment's configured secret backend into the Redis SDK.
* Bridges the deployment's configured secret backend into the Redis runtime.
*
* <p>Without it the SDK falls back to reading the process environment directly, which quietly
* <p>Without it the runtime falls back to reading the process environment directly, which quietly
* bypasses whichever backend {@code ca-skeleton.secret-source.strategy} selected — so a
* deployment using a secret manager would resolve its Redis credential from an environment
* variable that is not supposed to hold it.
*
* @param secretSource the configured backend
* @return the SDK's view of it
* @return the runtime's view of it
*/
@Bean
RedisSdkAutoConfiguration.RedisSecretSource redisSdkSecretSource(SecretSourcePort secretSource) {
RedisRuntimeAutoConfiguration.RedisSecretSource redisSecretSource(SecretSourcePort secretSource) {
return secretSource::resolve;
}
/**
* The production secrets of the Redis roles this deployment selected, for the composition root's
* secret guard — which checks them without knowing which Redis roles exist.
*
* @return the contribution
*/
@Bean
RedisProductionSecrets redisProductionSecrets() {
return new RedisProductionSecrets();
}
@Bean
@ConditionalOnMissingBean(RedisSemanticScriptAclProbe.class)
RedisSemanticScriptAclProbe redisSemanticScriptAclProbe(
RedisRuntimeOwner owner, RedisCapabilitySettings capabilities, RedisSdkSettings sdk) {
RedisRuntimeOwner owner, RedisCapabilitySettings capabilities, RedisRuntimeSettings redis) {
byte[] probeKey =
(RedisKeys.namespaceOf(sdk).prefix() + ":probe:{semantic-script}:acl")
(RedisKeys.namespaceOf(redis).prefix() + ":probe:{semantic-script}:acl")
.getBytes(java.nio.charset.StandardCharsets.UTF_8);
return new RedisSemanticScriptAclProbe(
owner, capabilities, probeKey, sdk.getTimeout().getScript());
owner, capabilities, probeKey, redis.getTimeout().getScript());
}
}
@@ -0,0 +1,95 @@
package dev.caskeleton.adapter.outbound.cache.redis.capability;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisCorrectnessRequirement;
import java.util.List;
import org.springframework.core.env.Environment;
/**
* The Redis roles, their selectors, and what each one requires.
*
* <p>Session, idempotency, rate limiting and leases produce a wrong answer when Redis is gone, not
* a slow one: a replayed payment, an unenforced quota, two holders of a lease. A deployment that
* selected any of them gates its readiness on Redis. The cache is a role too, but not a correctness
* one — its outage is degradation — so it needs its production secrets and nothing else.
*
* <p>This table used to be two: the selectors in {@code redis-runtime}, which therefore hard-coded
* selector keys of a module built on top of it, and a prefix switch in the composition root's
* secret guard. It is one now, here, with the capabilities it describes. The runtime is told only
* whether Redis is required ({@link RedisCorrectnessRequirement}, {@code
* META-INF/spring.factories}), and the secret guard only which secrets ({@link
* RedisProductionSecrets}).
*/
public final class RedisCorrectnessRoleSelectors implements RedisCorrectnessRequirement {
/**
* One role.
*
* @param selector the property that selects the role's provider
* @param fallback the selector's value when the deployment set none
* @param selecting the value that selects Redis
* @param correctness whether serving without Redis would give wrong answers
* @param scripted whether the role runs registered programs on the SCRIPT lane
* @param productionSecrets the secrets the role needs under the {@code prod} profile
*/
record Role(
String selector,
String fallback,
String selecting,
boolean correctness,
boolean scripted,
List<String> productionSecrets) {
boolean selected(Environment environment) {
return selecting.equalsIgnoreCase(environment.getProperty(selector, fallback));
}
}
/** Every Redis role this module composes. */
static final List<Role> ROLES =
List.of(
new Role(
"ca-skeleton.capabilities.cache.bindings.default",
"disabled",
"redis",
false,
false,
List.of("APP_CACHE_REDIS_PASSWORD", "APP_CACHE_REDIS_KEY_HMAC_SECRET")),
new Role(
"ca-skeleton.security.auth-mode",
"jwt",
"redis-session",
true,
false,
List.of("APP_SESSION_REDIS_PASSWORD", "APP_SESSION_REDIS_KEY_HMAC_SECRET")),
new Role(
"ca-skeleton.capabilities.idempotency.provider",
"disabled",
"redis",
true,
true,
List.of("APP_IDEMPOTENCY_REDIS_KEY_HMAC_SECRET")),
new Role(
"ca-skeleton.capabilities.rate-limit.provider",
"disabled",
"redis",
true,
true,
List.of("APP_RATE_LIMIT_REDIS_PASSWORD", "APP_RATE_LIMIT_REDIS_KEY_HMAC_SECRET")),
new Role(
"ca-skeleton.capabilities.lease.provider",
"disabled",
"redis",
true,
true,
List.of("APP_LEASE_REDIS_KEY_HMAC_SECRET")));
@Override
public boolean required(Environment environment) {
return ROLES.stream().anyMatch(role -> role.correctness() && role.selected(environment));
}
@Override
public boolean requiresScriptLane(Environment environment) {
return ROLES.stream().anyMatch(role -> role.scripted() && role.selected(environment));
}
}
@@ -2,8 +2,8 @@ package dev.caskeleton.adapter.outbound.cache.redis.capability;
import dev.caskeleton.adapter.outbound.cache.redis.idempotency.IdempotencyScripts;
import dev.caskeleton.adapter.outbound.cache.redis.idempotency.RedisIdempotencyStoreAdapter;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkSettings;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeSettings;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.support.startup.StartupPhase;
import dev.caskeleton.adapter.outbound.support.startup.StartupValidationContext;
import dev.caskeleton.application.idempotency.IdempotencyStorePort;
@@ -23,7 +23,7 @@ class RedisIdempotencyConfig {
* The owner-safe request-replay store.
*
* @param owner the Redis runtime owner
* @param sdk the Redis SDK settings, which own the namespace
* @param redis the Redis runtime settings, which own the namespace
* @param capabilities the capability settings
* @param clock the clock lease deadlines are measured against
* @return the store port
@@ -34,7 +34,7 @@ class RedisIdempotencyConfig {
havingValue = "redis")
IdempotencyStorePort redisIdempotencyStore(
RedisRuntimeOwner owner,
RedisSdkSettings sdk,
RedisRuntimeSettings redis,
RedisCapabilitySettings capabilities,
Clock clock) {
RedisCapabilitySettings.Idempotency idempotency = capabilities.getIdempotency();
@@ -51,7 +51,7 @@ class RedisIdempotencyConfig {
return new RedisIdempotencyStoreAdapter(
owner,
new RedisIdempotencyStoreAdapter.IdempotencyKeys(
RedisKeys.namespaceOf(sdk), idempotency.getKeyVersion()),
RedisKeys.namespaceOf(redis), idempotency.getKeyVersion()),
new IdempotencyScripts(),
clock,
idempotency.getCommandTimeout());
@@ -1,7 +1,7 @@
package dev.caskeleton.adapter.outbound.cache.redis.capability;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkSettings;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeSettings;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.support.CapabilityStartupValidationException;
import dev.caskeleton.application.outbound.SecretReference;
import dev.caskeleton.application.outbound.SecretSourcePort;
@@ -20,7 +20,7 @@ final class RedisKeys {
private RedisKeys() {}
/** The deployment's key namespace: {@code {environment}:{service}:{domain}}. */
static RedisNamespace namespaceOf(RedisSdkSettings settings) {
static RedisNamespace namespaceOf(RedisRuntimeSettings settings) {
return new RedisNamespace(
settings.getNamespace().getEnvironment(),
settings.getNamespace().getService(),
@@ -38,7 +38,10 @@ final class RedisKeys {
record KeyDigest(javax.crypto.Mac prototype) {
static KeyDigest of(
SecretSourcePort secretSource, String reference, String capability, RedisSdkSettings sdk) {
SecretSourcePort secretSource,
String reference,
String capability,
RedisRuntimeSettings redis) {
String name = secretName(reference, capability);
String material =
secretSource
@@ -61,11 +64,11 @@ final class RedisKeys {
// one-for-one onto the harder one.
(material
+ '|'
+ sdk.getNamespace().getEnvironment()
+ redis.getNamespace().getEnvironment()
+ ':'
+ sdk.getNamespace().getService()
+ redis.getNamespace().getService()
+ ':'
+ sdk.getNamespace().getDomain())
+ redis.getNamespace().getDomain())
.getBytes(StandardCharsets.UTF_8),
"HmacSHA256"));
return new KeyDigest(mac);
@@ -2,8 +2,8 @@ package dev.caskeleton.adapter.outbound.cache.redis.capability;
import dev.caskeleton.adapter.outbound.cache.redis.lease.LeaseScripts;
import dev.caskeleton.adapter.outbound.cache.redis.lease.RedisDistributedLeaseAdapter;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkSettings;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeSettings;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.application.lease.DistributedLeasePort;
import java.time.Clock;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
@@ -18,7 +18,7 @@ class RedisLeaseConfig {
* The distributed lease port. Efficiency only — it never supplies fencing.
*
* @param owner the Redis runtime owner
* @param sdk the Redis SDK settings, which own the namespace
* @param redis the Redis runtime settings, which own the namespace
* @param capabilities the capability settings
* @param clock the wall clock used for reporting instants
* @return the lease port
@@ -27,14 +27,14 @@ class RedisLeaseConfig {
@ConditionalOnProperty(name = "ca-skeleton.capabilities.lease.provider", havingValue = "redis")
DistributedLeasePort redisDistributedLeasePort(
RedisRuntimeOwner owner,
RedisSdkSettings sdk,
RedisRuntimeSettings redis,
RedisCapabilitySettings capabilities,
Clock clock) {
RedisCapabilitySettings.Lease lease = capabilities.getLease();
return new RedisDistributedLeaseAdapter(
owner,
new RedisDistributedLeaseAdapter.LeaseKeys(
RedisKeys.namespaceOf(sdk), lease.getKeyVersion()),
RedisKeys.namespaceOf(redis), lease.getKeyVersion()),
new LeaseScripts(),
clock,
System::nanoTime,
@@ -0,0 +1,24 @@
package dev.caskeleton.adapter.outbound.cache.redis.capability;
import dev.caskeleton.adapter.outbound.support.startup.RequiredProductionSecrets;
import java.util.List;
import org.springframework.core.env.Environment;
/**
* The production secrets of the Redis roles this deployment selected.
*
* <p>A bean of this module's composition, so it exists only while {@code app.redis.enabled} is
* true: with Redis off nothing Redis-shaped is created, and demanding its credentials would fail a
* deployment over an adapter it never asked for. With Redis on, each selected role contributes its
* own secrets — a deployment that runs Redis for its cache owes nothing to the session store.
*/
public final class RedisProductionSecrets implements RequiredProductionSecrets {
@Override
public List<String> requiredSecrets(Environment environment) {
return RedisCorrectnessRoleSelectors.ROLES.stream()
.filter(role -> role.selected(environment))
.flatMap(role -> role.productionSecrets().stream())
.toList();
}
}
@@ -1,15 +1,15 @@
package dev.caskeleton.adapter.outbound.cache.redis.capability;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RateLimitAlgorithm;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RateLimitFailurePolicy;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RateLimitKeys;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RateLimitPolicy;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RateLimitScripts;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RedisEdgeRateLimitAdapter;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkSettings;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeSettings;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.support.CapabilityStartupValidationException;
import dev.caskeleton.shared.ratelimit.EdgeRateLimitPort;
import dev.caskeleton.shared.ratelimit.RateLimitAlgorithm;
import dev.caskeleton.shared.ratelimit.RateLimitFailurePolicy;
import dev.caskeleton.shared.ratelimit.RateLimitPolicy;
import dev.caskeleton.shared.ratelimit.RateParameters;
import java.time.Clock;
import java.time.Duration;
@@ -37,7 +37,7 @@ class RedisRateLimitConfig {
* The provider-neutral edge rate limiter, backed by Redis.
*
* @param owner the Redis runtime owner
* @param sdk the Redis SDK settings, which own the namespace
* @param redis the Redis runtime settings, which own the namespace
* @param capabilities the capability settings
* @param clock the local clock used for caller deadlines and response reset instants
* @param environment where the HTTP boundary's default policy id is read from
@@ -49,7 +49,7 @@ class RedisRateLimitConfig {
havingValue = "redis")
EdgeRateLimitPort redisEdgeRateLimitPort(
RedisRuntimeOwner owner,
RedisSdkSettings sdk,
RedisRuntimeSettings redis,
RedisCapabilitySettings capabilities,
Clock clock,
Environment environment) {
@@ -60,7 +60,7 @@ class RedisRateLimitConfig {
String defaultPolicyId = environment.getProperty(DEFAULT_POLICY_ID, "api-default");
return new RedisEdgeRateLimitAdapter(
owner,
new RateLimitKeys(RedisKeys.namespaceOf(sdk), rateLimit.getKeyVersion()),
new RateLimitKeys(RedisKeys.namespaceOf(redis), rateLimit.getKeyVersion()),
policiesOf(rateLimit, defaultPolicyId),
new RateLimitScripts(),
clock,
@@ -1,6 +1,6 @@
package dev.caskeleton.adapter.outbound.cache.redis.capability;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisCorrectnessRoles;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisCorrectnessRoles;
import dev.caskeleton.adapter.outbound.support.startup.ReadinessGroup;
import dev.caskeleton.adapter.outbound.support.startup.StartupOrder;
import org.springframework.boot.EnvironmentPostProcessor;
@@ -1,8 +1,8 @@
package dev.caskeleton.adapter.outbound.cache.redis.capability;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisLease;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLease;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.support.CapabilityStartupValidationException;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
@@ -63,13 +63,13 @@ final class RedisSemanticScriptAclProbe implements SmartInitializingSingleton {
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
String digest =
lease
.gateway()
.commands()
.loadScript(PROBE_SCRIPT)
.toCompletableFuture()
.get(timeout.toNanos(), TimeUnit.NANOSECONDS);
List<Object> reply =
lease
.gateway()
.commands()
.evaluateRegisteredForList(digest, probeKey, List.of())
.toCompletableFuture()
.get(timeout.toNanos(), TimeUnit.NANOSECONDS);
@@ -1,15 +1,11 @@
package dev.caskeleton.adapter.outbound.cache.redis.idempotency;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.adapter.outbound.cache.redis.RegisteredLuaScript;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.atomic.AtomicReference;
/**
* The idempotency record's state machine, one atomic program per transition.
@@ -186,122 +182,86 @@ public final class IdempotencyScripts {
mine .. '|' .. tostring(redis.call('PTTL', KEYS[1]))}
""";
private final Map<String, AtomicReference<String>> digests =
Map.of(
"claim", new AtomicReference<>(),
"transition", new AtomicReference<>(),
"release", new AtomicReference<>(),
"inspect", new AtomicReference<>());
private final RegisteredLuaScript claim = new RegisteredLuaScript(CLAIM);
private final RegisteredLuaScript transition = new RegisteredLuaScript(TRANSITION);
private final RegisteredLuaScript release = new RegisteredLuaScript(RELEASE);
private final RegisteredLuaScript inspect = new RegisteredLuaScript(INSPECT);
CompletionStage<Reply> claim(RedisCommandGateway gateway, byte[] key, List<String> arguments) {
return run(gateway, "claim", CLAIM, key, arguments);
CompletionStage<Reply> claim(SemanticRedisCommands commands, byte[] key, List<String> arguments) {
return run(claim, commands, key, arguments);
}
CompletionStage<Reply> transition(
RedisCommandGateway gateway, byte[] key, List<String> arguments) {
return run(gateway, "transition", TRANSITION, key, arguments);
SemanticRedisCommands commands, byte[] key, List<String> arguments) {
return run(transition, commands, key, arguments);
}
CompletionStage<Reply> release(RedisCommandGateway gateway, byte[] key, List<String> arguments) {
return run(gateway, "release", RELEASE, key, arguments);
CompletionStage<Reply> release(
SemanticRedisCommands commands, byte[] key, List<String> arguments) {
return run(release, commands, key, arguments);
}
CompletionStage<Reply> inspect(RedisCommandGateway gateway, byte[] key, List<String> arguments) {
return run(gateway, "inspect", INSPECT, key, arguments);
CompletionStage<Reply> inspect(
SemanticRedisCommands commands, byte[] key, List<String> arguments) {
return run(inspect, commands, key, arguments);
}
private CompletionStage<Reply> run(
RedisCommandGateway gateway, String name, String source, byte[] key, List<String> arguments) {
AtomicReference<String> cache = digests.get(name);
if (cache == null) {
throw new IllegalArgumentException("unknown idempotency script: " + name);
}
private static CompletionStage<Reply> run(
RegisteredLuaScript program,
SemanticRedisCommands commands,
byte[] key,
List<String> arguments) {
List<byte[]> encoded = new ArrayList<>(arguments.size());
for (String argument : arguments) {
encoded.add(argument.getBytes(StandardCharsets.UTF_8));
}
return digest(gateway, source, cache)
.thenCompose(digest -> gateway.evaluateRegisteredForList(digest, key, encoded))
.handle(
(reply, failure) ->
failure == null
? CompletableFuture.completedFuture(reply)
: reload(gateway, source, cache, key, encoded, failure))
.thenCompose(stage -> stage)
.thenApply(IdempotencyScripts::replyOf);
return program.evaluateForList(commands, key, encoded).thenApply(Reply::of);
}
private CompletionStage<List<Object>> reload(
RedisCommandGateway gateway,
String source,
AtomicReference<String> cache,
byte[] key,
List<byte[]> arguments,
Throwable failure) {
if (!scriptMissing(failure)) {
return CompletableFuture.failedFuture(failure);
}
cache.set(null);
return digest(gateway, source, cache)
.thenCompose(digest -> gateway.evaluateRegisteredForList(digest, key, arguments));
}
/**
* What a program answered, parsed once.
*
* <p>The transition verdicts and, for {@code INSPECT}, the record's state. The programs speak in
* strings; the adapter speaks in this enum, so a misspelt status is a compile error rather than a
* {@code default} branch that quietly turns it into "unavailable".
*/
enum ScriptStatus {
ACQUIRED,
REPLAYED_ACQUIRE,
TAKEN_OVER,
COMPLETED_REPLAY,
IN_PROGRESS,
RECOVERY_REQUIRED,
FINGERPRINT_MISMATCH,
OWNER_OPERATION_CONFLICT,
APPLIED,
ALREADY,
ABSENT,
NOT_OWNER,
OPERATION_CONFLICT,
WRONG_STATE,
CLAIMED,
EXECUTING,
COMPLETED,
FAILED_RETRYABLE,
ABANDONED,
/** A status this adapter does not know: a newer program, or a corrupted reply. */
UNRECOGNISED;
private static CompletionStage<String> digest(
RedisCommandGateway gateway, String source, AtomicReference<String> cache) {
String cached = cache.get();
if (cached != null) {
return CompletableFuture.completedFuture(cached);
static ScriptStatus of(String text) {
for (ScriptStatus status : values()) {
if (status != UNRECOGNISED && status.name().equals(text)) {
return status;
}
}
return UNRECOGNISED;
}
return gateway
.loadScript(source.getBytes(StandardCharsets.UTF_8))
.thenApply(
loaded -> {
cache.set(loaded);
return loaded;
});
}
private static boolean scriptMissing(Throwable failure) {
Throwable cause = failure;
while ((cause instanceof CompletionException || cause instanceof ExecutionException)
&& cause.getCause() != null) {
cause = cause.getCause();
}
return cause instanceof io.lettuce.core.RedisNoScriptException;
}
private static Reply replyOf(List<Object> reply) {
if (reply == null || reply.size() < 6) {
throw new IllegalStateException("the idempotency program answered with an unexpected shape");
}
return new Reply(
text(reply.get(0)),
number(reply.get(1)),
number(reply.get(2)),
text(reply.get(3)),
text(reply.get(4)),
text(reply.get(5)));
}
private static long number(Object value) {
if (value instanceof Number n) {
return n.longValue();
}
String text = text(value);
return text.isBlank() ? 0L : Long.parseLong(text.strip());
}
private static String text(Object value) {
if (value instanceof byte[] bytes) {
return new String(bytes, StandardCharsets.UTF_8);
}
return value == null ? "" : String.valueOf(value);
}
/**
* One program's answer.
*
* @param status the transition verdict
* @param status the transition verdict, or the record's state for an inspection
* @param attempt the record's attempt counter
* @param revision the record's state revision after the call
* @param owner the stored owner token
@@ -309,5 +269,22 @@ public final class IdempotencyScripts {
* @param detail verdict-specific detail: a lease deadline, a TTL, or the observed state
*/
record Reply(
String status, long attempt, long revision, String owner, String payload, String detail) {}
ScriptStatus status,
long attempt,
long revision,
String owner,
String payload,
String detail) {
static Reply of(List<Object> reply) {
RegisteredLuaScript.requireShape(reply, 6, "idempotency");
return new Reply(
ScriptStatus.of(RegisteredLuaScript.text(reply.get(0))),
RegisteredLuaScript.number(reply.get(1)),
RegisteredLuaScript.number(reply.get(2)),
RegisteredLuaScript.text(reply.get(3)),
RegisteredLuaScript.text(reply.get(4)),
RegisteredLuaScript.text(reply.get(5)));
}
}
}
@@ -1,12 +1,11 @@
package dev.caskeleton.adapter.outbound.cache.redis.idempotency;
import dev.caskeleton.adapter.outbound.cache.redis.RedisSemanticFailureLogger;
import dev.caskeleton.adapter.outbound.cache.redis.SemanticRedisCall;
import dev.caskeleton.adapter.outbound.cache.redis.idempotency.IdempotencyScripts.ScriptStatus;
import dev.caskeleton.adapter.outbound.cache.redis.keyspace.CapabilityKeyspace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.error.RedisOperationException;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisLease;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.application.idempotency.IdempotencyClaimAttempt;
import dev.caskeleton.application.idempotency.IdempotencyClaimOutcome;
import dev.caskeleton.application.idempotency.IdempotencyClaimRequest;
@@ -30,9 +29,10 @@ import java.time.Clock;
import java.time.Duration;
import java.time.Instant;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import java.util.concurrent.TimeUnit;
import java.util.function.Predicate;
/**
* The owner-safe request-replay store, on Redis.
@@ -57,7 +57,7 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
private static final SecureRandom RANDOM = new SecureRandom();
private final RedisRuntimeOwner owner;
private final SemanticRedisCall call;
private final IdempotencyKeys keys;
@@ -65,8 +65,6 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
private final Clock clock;
private final Duration commandTimeout;
/**
* Creates the adapter.
*
@@ -82,12 +80,15 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
IdempotencyScripts scripts,
Clock clock,
Duration commandTimeout) {
this.owner = Objects.requireNonNull(owner, "runtime owner must be non-null");
this.call =
new SemanticRedisCall(
owner,
RedisConnectionKind.SCRIPT,
Objects.requireNonNull(commandTimeout, "command timeout must be non-null"),
"idempotency");
this.keys = Objects.requireNonNull(keys, "keys must be non-null");
this.scripts = Objects.requireNonNull(scripts, "scripts must be non-null");
this.clock = Objects.requireNonNull(clock, "clock must be non-null");
this.commandTimeout =
Objects.requireNonNull(commandTimeout, "command timeout must be non-null");
}
@Override
@@ -109,61 +110,52 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
public IdempotencyClaimOutcome claim(IdempotencyClaimRequest request) {
Objects.requireNonNull(request, "request must be non-null");
Instant now = clock.instant();
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
IdempotencyScripts.Reply reply =
scripts
.claim(
lease.gateway(),
keys.recordKey(request.scope()),
List.of(
request.claimAttempt().ownerToken(),
request.claimAttempt().operationId().value(),
request.requestFingerprint().hex(),
request.responseCodecId(),
Integer.toString(request.policyRevision()),
Long.toString(request.processingLeaseTtl().toMillis()),
Long.toString(request.replayTtl().toMillis())))
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
return claimOutcomeOf(request, reply, now);
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return new IdempotencyClaimOutcome.Indeterminate(request.claimAttempt().operationId());
} catch (RedisOperationException failure) {
RedisSemanticFailureLogger.report("idempotency", "claim", failure);
// A refusal before the script was sent — a saturated or closing lane — claimed nothing, so
// the caller may treat it as unavailable. Only a call that may have run is indeterminate.
return notSent(failure)
? new IdempotencyClaimOutcome.Unavailable()
: new IdempotencyClaimOutcome.Indeterminate(request.claimAttempt().operationId());
} catch (Exception failure) {
RedisSemanticFailureLogger.report("idempotency", "claim", failure);
return new IdempotencyClaimOutcome.Indeterminate(request.claimAttempt().operationId());
}
// A refusal before the script was sent — a saturated or closing lane — claimed nothing, so the
// caller may treat it as unavailable. Only a call that may have run is indeterminate.
return call.effect(
"claim",
session ->
claimOutcomeOf(
request,
session.await(
scripts.claim(
session.commands(),
keys.recordKey(request.scope()),
List.of(
request.claimAttempt().ownerToken(),
request.claimAttempt().operationId().value(),
request.requestFingerprint().hex(),
request.responseCodecId(),
Integer.toString(request.policyRevision()),
Long.toString(request.processingLeaseTtl().toMillis()),
Long.toString(request.replayTtl().toMillis())))),
now),
IdempotencyClaimOutcome.Unavailable::new,
() -> new IdempotencyClaimOutcome.Indeterminate(request.claimAttempt().operationId()));
}
private IdempotencyClaimOutcome claimOutcomeOf(
IdempotencyClaimRequest request, IdempotencyScripts.Reply reply, Instant now) {
return switch (reply.status()) {
case "ACQUIRED" ->
case ACQUIRED ->
new IdempotencyClaimOutcome.Acquired(
ownerOf(request, reply), leaseUntil(reply, now, request));
case "REPLAYED_ACQUIRE" ->
case REPLAYED_ACQUIRE ->
new IdempotencyClaimOutcome.ReplayedAcquire(
ownerOf(request, reply), leaseUntil(reply, now, request));
case "TAKEN_OVER" ->
case TAKEN_OVER ->
new IdempotencyClaimOutcome.TakenOverClaimed(
ownerOf(request, reply), leaseUntil(reply, now, request));
case "COMPLETED_REPLAY" ->
case COMPLETED_REPLAY ->
new IdempotencyClaimOutcome.CompletedReplay(
new StoredResponse(reply.payload()),
now.plusMillis(Math.max(1, parseLong(reply.detail()))));
case "IN_PROGRESS" ->
case IN_PROGRESS ->
new IdempotencyClaimOutcome.InProgress(
Duration.ofMillis(Math.max(1, parseLong(reply.detail()))), reply.attempt());
case "RECOVERY_REQUIRED" -> new IdempotencyClaimOutcome.RecoveryRequired(reply.attempt());
case "FINGERPRINT_MISMATCH" -> new IdempotencyClaimOutcome.FingerprintMismatch();
case "OWNER_OPERATION_CONFLICT" -> new IdempotencyClaimOutcome.OwnerOperationConflict();
case RECOVERY_REQUIRED -> new IdempotencyClaimOutcome.RecoveryRequired(reply.attempt());
case FINGERPRINT_MISMATCH -> new IdempotencyClaimOutcome.FingerprintMismatch();
case OWNER_OPERATION_CONFLICT -> new IdempotencyClaimOutcome.OwnerOperationConflict();
default -> new IdempotencyClaimOutcome.Unavailable();
};
}
@@ -174,17 +166,14 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
return transition(
ownerHandle,
operationId,
"CLAIMED",
"EXECUTING",
"",
"",
"",
IdempotencyStartOutcome.STARTED,
IdempotencyStartOutcome.ALREADY_STARTED_SAME_OPERATION,
IdempotencyStartOutcome.ABSENT,
IdempotencyStartOutcome.NOT_OWNER,
IdempotencyStartOutcome.NOT_CLAIMED,
IdempotencyStartOutcome.OPERATION_CONFLICT,
new Transition("CLAIMED", "EXECUTING", "", "", ""),
Map.of(
ScriptStatus.APPLIED, IdempotencyStartOutcome.STARTED,
ScriptStatus.ALREADY, IdempotencyStartOutcome.ALREADY_STARTED_SAME_OPERATION,
ScriptStatus.ABSENT, IdempotencyStartOutcome.ABSENT,
ScriptStatus.NOT_OWNER, IdempotencyStartOutcome.NOT_OWNER,
ScriptStatus.WRONG_STATE, IdempotencyStartOutcome.NOT_CLAIMED,
ScriptStatus.OPERATION_CONFLICT, IdempotencyStartOutcome.OPERATION_CONFLICT),
IdempotencyStartOutcome.INDETERMINATE,
IdempotencyStartOutcome.UNAVAILABLE,
IdempotencyStartOutcome::carriesOwner);
@@ -197,17 +186,15 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
return transition(
ownerHandle,
operationId,
"EXECUTING",
"EXECUTING",
"",
Long.toString(processingLeaseTtl.toMillis()),
"",
IdempotencyRenewOutcome.RENEWED,
IdempotencyRenewOutcome.ALREADY_RENEWED_SAME_OPERATION,
IdempotencyRenewOutcome.ABSENT,
IdempotencyRenewOutcome.NOT_OWNER,
IdempotencyRenewOutcome.NOT_IN_PROGRESS,
IdempotencyRenewOutcome.OPERATION_CONFLICT,
new Transition(
"EXECUTING", "EXECUTING", "", Long.toString(processingLeaseTtl.toMillis()), ""),
Map.of(
ScriptStatus.APPLIED, IdempotencyRenewOutcome.RENEWED,
ScriptStatus.ALREADY, IdempotencyRenewOutcome.ALREADY_RENEWED_SAME_OPERATION,
ScriptStatus.ABSENT, IdempotencyRenewOutcome.ABSENT,
ScriptStatus.NOT_OWNER, IdempotencyRenewOutcome.NOT_OWNER,
ScriptStatus.WRONG_STATE, IdempotencyRenewOutcome.NOT_IN_PROGRESS,
ScriptStatus.OPERATION_CONFLICT, IdempotencyRenewOutcome.OPERATION_CONFLICT),
IdempotencyRenewOutcome.INDETERMINATE,
IdempotencyRenewOutcome.UNAVAILABLE,
IdempotencyRenewOutcome::carriesOwner);
@@ -221,51 +208,40 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
OperationId operationId) {
Objects.requireNonNull(response, "response must be non-null");
Objects.requireNonNull(replayTtl, "replay TTL must be non-null");
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
IdempotencyScripts.Reply reply =
scripts
.transition(
lease.gateway(),
keys.recordKey(ownerHandle.scope()),
List.of(
ownerHandle.ownerToken(),
Long.toString(ownerHandle.stateRevision()),
operationId.value(),
"EXECUTING",
"COMPLETED",
response.payload(),
"",
Long.toString(replayTtl.toMillis())))
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
return switch (reply.status()) {
case "APPLIED" -> IdempotencyCompleteOutcome.COMPLETED;
case "ALREADY" ->
// The same owner completing twice. Whether it is the same result decides whether this
// is an idempotent repeat or a contradiction the caller has to see.
reply.payload().equals(response.payload())
? IdempotencyCompleteOutcome.ALREADY_COMPLETED_SAME_RESULT
: IdempotencyCompleteOutcome.RESPONSE_CONFLICT;
case "ABSENT" -> IdempotencyCompleteOutcome.ABSENT;
case "NOT_OWNER" -> IdempotencyCompleteOutcome.NOT_OWNER;
case "OPERATION_CONFLICT" -> IdempotencyCompleteOutcome.OPERATION_CONFLICT;
case "WRONG_STATE" -> IdempotencyCompleteOutcome.NOT_IN_PROGRESS;
default -> IdempotencyCompleteOutcome.UNAVAILABLE;
};
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return IdempotencyCompleteOutcome.INDETERMINATE;
} catch (RedisOperationException failure) {
RedisSemanticFailureLogger.report("idempotency", "complete", failure);
return notSent(failure)
? IdempotencyCompleteOutcome.UNAVAILABLE
: IdempotencyCompleteOutcome.INDETERMINATE;
} catch (Exception failure) {
RedisSemanticFailureLogger.report("idempotency", "complete", failure);
// The effect may have been recorded. A caller told INDETERMINATE inspects; one told
// UNAVAILABLE might retry the whole operation and duplicate it.
return IdempotencyCompleteOutcome.INDETERMINATE;
}
return call.effect(
"complete",
session -> {
IdempotencyScripts.Reply reply =
session.await(
scripts.transition(
session.commands(),
keys.recordKey(ownerHandle.scope()),
new Transition(
"EXECUTING",
"COMPLETED",
response.payload(),
"",
Long.toString(replayTtl.toMillis()))
.arguments(ownerHandle, operationId)));
return switch (reply.status()) {
case APPLIED -> IdempotencyCompleteOutcome.COMPLETED;
case ALREADY ->
// The same owner completing twice. Whether it is the same result decides whether
// this is an idempotent repeat or a contradiction the caller has to see.
reply.payload().equals(response.payload())
? IdempotencyCompleteOutcome.ALREADY_COMPLETED_SAME_RESULT
: IdempotencyCompleteOutcome.RESPONSE_CONFLICT;
case ABSENT -> IdempotencyCompleteOutcome.ABSENT;
case NOT_OWNER -> IdempotencyCompleteOutcome.NOT_OWNER;
case OPERATION_CONFLICT -> IdempotencyCompleteOutcome.OPERATION_CONFLICT;
case WRONG_STATE -> IdempotencyCompleteOutcome.NOT_IN_PROGRESS;
default -> IdempotencyCompleteOutcome.UNAVAILABLE;
};
},
() -> IdempotencyCompleteOutcome.UNAVAILABLE,
// The effect may have been recorded. A caller told INDETERMINATE inspects; one told
// UNAVAILABLE might retry the whole operation and duplicate it.
() -> IdempotencyCompleteOutcome.INDETERMINATE);
}
@Override
@@ -280,122 +256,98 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
// whether anybody may retry. NO_EFFECT_RETRYABLE releases the operation for another attempt;
// EFFECT_UNKNOWN_ABANDONED does not, because retrying an unknown effect is how it happens
// twice.
String target =
disposition == IdempotencyFailureDisposition.NO_EFFECT_RETRYABLE
? "FAILED_RETRYABLE"
: "ABANDONED";
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
IdempotencyScripts.Reply reply =
scripts
.transition(
lease.gateway(),
keys.recordKey(ownerHandle.scope()),
List.of(
ownerHandle.ownerToken(),
Long.toString(ownerHandle.stateRevision()),
operationId.value(),
"EXECUTING",
target,
"",
"",
Long.toString(retention.toMillis())))
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
return switch (reply.status()) {
case "APPLIED" ->
disposition == IdempotencyFailureDisposition.NO_EFFECT_RETRYABLE
? IdempotencyFailOutcome.MARKED_RETRYABLE
: IdempotencyFailOutcome.MARKED_ABANDONED;
case "ALREADY" -> IdempotencyFailOutcome.ALREADY_MARKED_SAME_OPERATION;
case "ABSENT" -> IdempotencyFailOutcome.ABSENT;
case "NOT_OWNER" -> IdempotencyFailOutcome.NOT_OWNER;
case "OPERATION_CONFLICT" -> IdempotencyFailOutcome.OPERATION_CONFLICT;
case "WRONG_STATE" -> IdempotencyFailOutcome.NOT_IN_PROGRESS;
default -> IdempotencyFailOutcome.UNAVAILABLE;
};
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return IdempotencyFailOutcome.INDETERMINATE;
} catch (RedisOperationException failure) {
RedisSemanticFailureLogger.report("idempotency", "mark-failed", failure);
return notSent(failure)
? IdempotencyFailOutcome.UNAVAILABLE
: IdempotencyFailOutcome.INDETERMINATE;
} catch (Exception failure) {
RedisSemanticFailureLogger.report("idempotency", "mark-failed", failure);
return IdempotencyFailOutcome.INDETERMINATE;
}
boolean retryable = disposition == IdempotencyFailureDisposition.NO_EFFECT_RETRYABLE;
Transition transition =
new Transition(
"EXECUTING",
retryable ? "FAILED_RETRYABLE" : "ABANDONED",
"",
"",
Long.toString(retention.toMillis()));
return call.effect(
"mark-failed",
session -> {
IdempotencyScripts.Reply reply =
session.await(
scripts.transition(
session.commands(),
keys.recordKey(ownerHandle.scope()),
transition.arguments(ownerHandle, operationId)));
return switch (reply.status()) {
case APPLIED ->
retryable
? IdempotencyFailOutcome.MARKED_RETRYABLE
: IdempotencyFailOutcome.MARKED_ABANDONED;
case ALREADY -> IdempotencyFailOutcome.ALREADY_MARKED_SAME_OPERATION;
case ABSENT -> IdempotencyFailOutcome.ABSENT;
case NOT_OWNER -> IdempotencyFailOutcome.NOT_OWNER;
case OPERATION_CONFLICT -> IdempotencyFailOutcome.OPERATION_CONFLICT;
case WRONG_STATE -> IdempotencyFailOutcome.NOT_IN_PROGRESS;
default -> IdempotencyFailOutcome.UNAVAILABLE;
};
},
() -> IdempotencyFailOutcome.UNAVAILABLE,
() -> IdempotencyFailOutcome.INDETERMINATE);
}
@Override
public IdempotencyReleaseOutcome releaseBeforeExecution(
IdempotencyOwner ownerHandle, OperationId operationId) {
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
IdempotencyScripts.Reply reply =
scripts
.release(
lease.gateway(),
keys.recordKey(ownerHandle.scope()),
List.of(
ownerHandle.ownerToken(),
Long.toString(ownerHandle.stateRevision()),
operationId.value()))
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
return switch (reply.status()) {
case "APPLIED" -> IdempotencyReleaseOutcome.RELEASED_BEFORE_EXECUTION;
case "ABSENT" -> IdempotencyReleaseOutcome.ALREADY_RELEASED_SAME_OPERATION;
case "NOT_OWNER" -> IdempotencyReleaseOutcome.NOT_OWNER;
case "OPERATION_CONFLICT" -> IdempotencyReleaseOutcome.OPERATION_CONFLICT;
case "WRONG_STATE" -> IdempotencyReleaseOutcome.EXECUTION_ALREADY_STARTED;
default -> IdempotencyReleaseOutcome.UNAVAILABLE;
};
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return IdempotencyReleaseOutcome.INDETERMINATE;
} catch (RedisOperationException failure) {
RedisSemanticFailureLogger.report("idempotency", "release-before-execution", failure);
return notSent(failure)
? IdempotencyReleaseOutcome.UNAVAILABLE
: IdempotencyReleaseOutcome.INDETERMINATE;
} catch (Exception failure) {
RedisSemanticFailureLogger.report("idempotency", "release-before-execution", failure);
return IdempotencyReleaseOutcome.INDETERMINATE;
}
return call.effect(
"release-before-execution",
session -> {
IdempotencyScripts.Reply reply =
session.await(
scripts.release(
session.commands(),
keys.recordKey(ownerHandle.scope()),
List.of(
ownerHandle.ownerToken(),
Long.toString(ownerHandle.stateRevision()),
operationId.value())));
return switch (reply.status()) {
case APPLIED -> IdempotencyReleaseOutcome.RELEASED_BEFORE_EXECUTION;
case ABSENT -> IdempotencyReleaseOutcome.ALREADY_RELEASED_SAME_OPERATION;
case NOT_OWNER -> IdempotencyReleaseOutcome.NOT_OWNER;
case OPERATION_CONFLICT -> IdempotencyReleaseOutcome.OPERATION_CONFLICT;
case WRONG_STATE -> IdempotencyReleaseOutcome.EXECUTION_ALREADY_STARTED;
default -> IdempotencyReleaseOutcome.UNAVAILABLE;
};
},
() -> IdempotencyReleaseOutcome.UNAVAILABLE,
() -> IdempotencyReleaseOutcome.INDETERMINATE);
}
@Override
public IdempotencyInspection inspect(IdempotencyInspectionRequest request) {
Objects.requireNonNull(request, "request must be non-null");
Instant now = clock.instant();
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
IdempotencyScripts.Reply reply =
scripts
.inspect(
lease.gateway(),
keys.recordKey(request.scope()),
List.of(
request.claimAttempt().ownerToken(),
request.requestFingerprint().hex(),
request.claimAttempt().operationId().value()))
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
return inspectionOf(request, reply, now);
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return IdempotencyInspection.outcome(IdempotencyInspectionOutcome.UNAVAILABLE);
} catch (Exception failure) {
RedisSemanticFailureLogger.report("idempotency", "inspect", failure);
return IdempotencyInspection.outcome(IdempotencyInspectionOutcome.UNAVAILABLE);
}
// A read: whether or not it reached the server, it changed nothing, so every failure is the
// same "unavailable".
return call.effect(
"inspect",
session ->
inspectionOf(
request,
session.await(
scripts.inspect(
session.commands(),
keys.recordKey(request.scope()),
List.of(
request.claimAttempt().ownerToken(),
request.requestFingerprint().hex(),
request.claimAttempt().operationId().value()))),
now),
() -> IdempotencyInspection.outcome(IdempotencyInspectionOutcome.UNAVAILABLE),
() -> IdempotencyInspection.outcome(IdempotencyInspectionOutcome.UNAVAILABLE));
}
private IdempotencyInspection inspectionOf(
IdempotencyInspectionRequest request, IdempotencyScripts.Reply reply, Instant now) {
if ("ABSENT".equals(reply.status())) {
if (reply.status() == ScriptStatus.ABSENT) {
return IdempotencyInspection.outcome(IdempotencyInspectionOutcome.ABSENT);
}
if ("FINGERPRINT_MISMATCH".equals(reply.status())) {
if (reply.status() == ScriptStatus.FINGERPRINT_MISMATCH) {
return IdempotencyInspection.outcome(IdempotencyInspectionOutcome.FINGERPRINT_MISMATCH);
}
String[] detail = reply.detail().split("\\|", 2);
@@ -412,17 +364,17 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
reply.revision(),
request.claimAttempt().operationId());
return switch (reply.status()) {
case "COMPLETED" ->
case COMPLETED ->
new IdempotencyInspection(
IdempotencyInspectionOutcome.COMPLETED_REPLAY,
Optional.empty(),
Optional.empty(),
Optional.of(new StoredResponse(reply.payload())),
Optional.of(now.plusMillis(Math.max(1, ttlMillis))));
case "FAILED_RETRYABLE" ->
case FAILED_RETRYABLE ->
IdempotencyInspection.outcome(IdempotencyInspectionOutcome.FAILED_RETRYABLE);
case "ABANDONED" -> IdempotencyInspection.outcome(IdempotencyInspectionOutcome.ABANDONED);
case "CLAIMED" ->
case ABANDONED -> IdempotencyInspection.outcome(IdempotencyInspectionOutcome.ABANDONED);
case CLAIMED ->
"MINE".equals(ownership)
? new IdempotencyInspection(
IdempotencyInspectionOutcome.CLAIMED_SAME_OPERATION,
@@ -431,7 +383,7 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
Optional.empty(),
Optional.empty())
: IdempotencyInspection.outcome(IdempotencyInspectionOutcome.IN_PROGRESS_OTHER);
case "EXECUTING" ->
case EXECUTING ->
"MINE".equals(ownership)
? new IdempotencyInspection(
IdempotencyInspectionOutcome.EXECUTING_SAME_OPERATION,
@@ -444,77 +396,63 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
};
}
private <O extends Enum<O>> IdempotencyMutationResult<O> transition(
IdempotencyOwner ownerHandle,
OperationId operationId,
String fromState,
String toState,
String payload,
String leaseUntil,
String ttlMillis,
O applied,
O already,
O absent,
O notOwner,
O wrongState,
O operationConflict,
O indeterminate,
O unavailable,
java.util.function.Predicate<O> carriesOwner) {
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
IdempotencyScripts.Reply reply =
scripts
.transition(
lease.gateway(),
keys.recordKey(ownerHandle.scope()),
List.of(
ownerHandle.ownerToken(),
Long.toString(ownerHandle.stateRevision()),
operationId.value(),
fromState,
toState,
payload,
leaseUntil,
ttlMillis))
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
O outcome =
switch (reply.status()) {
case "APPLIED" -> applied;
case "ALREADY" -> already;
case "ABSENT" -> absent;
case "NOT_OWNER" -> notOwner;
case "OPERATION_CONFLICT" -> operationConflict;
case "WRONG_STATE" -> wrongState;
default -> indeterminate;
};
return new IdempotencyMutationResult<>(
outcome,
carriesOwner.test(outcome)
? new IdempotencyOwner(
ownerHandle.scope(),
ownerHandle.ownerToken(),
reply.attempt(),
reply.revision(),
ownerHandle.claimOperationId())
: null,
carriesOwner);
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return new IdempotencyMutationResult<>(indeterminate, null, carriesOwner);
} catch (RedisOperationException failure) {
RedisSemanticFailureLogger.report("idempotency", "transition", failure);
return new IdempotencyMutationResult<>(
notSent(failure) ? unavailable : indeterminate, null, carriesOwner);
} catch (Exception failure) {
RedisSemanticFailureLogger.report("idempotency", "transition", failure);
return new IdempotencyMutationResult<>(indeterminate, null, carriesOwner);
/**
* One owner+revision compare-and-set, as the transition program takes it.
*
* @param fromState the state the record must be in
* @param toState the state it moves to
* @param payload the response to store, empty for none
* @param leaseMillis a new processing lease, empty to keep the current one
* @param ttlMillis a new record TTL, empty to keep the current one
*/
private record Transition(
String fromState, String toState, String payload, String leaseMillis, String ttlMillis) {
List<String> arguments(IdempotencyOwner ownerHandle, OperationId operationId) {
return List.of(
ownerHandle.ownerToken(),
Long.toString(ownerHandle.stateRevision()),
operationId.value(),
fromState,
toState,
payload,
leaseMillis,
ttlMillis);
}
}
/** A typed runtime refusal raised before any command existed — nothing reached Redis. */
private static boolean notSent(RedisOperationException failure) {
return !failure.metadata().ambiguousExecution();
private <O extends Enum<O>> IdempotencyMutationResult<O> transition(
IdempotencyOwner ownerHandle,
OperationId operationId,
Transition transition,
Map<ScriptStatus, O> outcomes,
O indeterminate,
O unavailable,
Predicate<O> carriesOwner) {
return call.effect(
"transition",
session -> {
IdempotencyScripts.Reply reply =
session.await(
scripts.transition(
session.commands(),
keys.recordKey(ownerHandle.scope()),
transition.arguments(ownerHandle, operationId)));
O outcome = outcomes.getOrDefault(reply.status(), indeterminate);
return new IdempotencyMutationResult<>(
outcome,
carriesOwner.test(outcome)
? new IdempotencyOwner(
ownerHandle.scope(),
ownerHandle.ownerToken(),
reply.attempt(),
reply.revision(),
ownerHandle.claimOperationId())
: null,
carriesOwner);
},
() -> new IdempotencyMutationResult<>(unavailable, null, carriesOwner),
() -> new IdempotencyMutationResult<>(indeterminate, null, carriesOwner));
}
private static IdempotencyOwner ownerOf(
@@ -1,7 +1,7 @@
package dev.caskeleton.adapter.outbound.cache.redis.keyspace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisKeyRules;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisKeyRules;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import java.nio.charset.StandardCharsets;
import java.util.Objects;
@@ -1,13 +1,10 @@
package dev.caskeleton.adapter.outbound.cache.redis.lease;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.adapter.outbound.cache.redis.RegisteredLuaScript;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.atomic.AtomicReference;
/**
* The four owner-checked lease programs.
@@ -80,107 +77,27 @@ public final class LeaseScripts {
return {1, redis.call('PTTL', KEYS[1]), existing}
""";
private final AtomicReference<String> acquireDigest = new AtomicReference<>();
private final AtomicReference<String> renewDigest = new AtomicReference<>();
private final AtomicReference<String> releaseDigest = new AtomicReference<>();
private final AtomicReference<String> inspectDigest = new AtomicReference<>();
private final RegisteredLuaScript acquire = new RegisteredLuaScript(ACQUIRE);
private final RegisteredLuaScript renew = new RegisteredLuaScript(RENEW);
private final RegisteredLuaScript release = new RegisteredLuaScript(RELEASE);
private final RegisteredLuaScript inspect = new RegisteredLuaScript(INSPECT);
CompletionStage<Reply> acquire(
RedisCommandGateway gateway, byte[] key, String ownership, long ttlMillis) {
return run(gateway, ACQUIRE, acquireDigest, key, args(ownership, ttlMillis));
SemanticRedisCommands commands, byte[] key, String ownership, long ttlMillis) {
return acquire.evaluateForList(commands, key, args(ownership, ttlMillis)).thenApply(Reply::of);
}
CompletionStage<Reply> renew(
RedisCommandGateway gateway, byte[] key, String ownership, long ttlMillis) {
return run(gateway, RENEW, renewDigest, key, args(ownership, ttlMillis));
SemanticRedisCommands commands, byte[] key, String ownership, long ttlMillis) {
return renew.evaluateForList(commands, key, args(ownership, ttlMillis)).thenApply(Reply::of);
}
CompletionStage<Reply> release(RedisCommandGateway gateway, byte[] key, String ownership) {
return run(gateway, RELEASE, releaseDigest, key, args(ownership, 0));
CompletionStage<Reply> release(SemanticRedisCommands commands, byte[] key, String ownership) {
return release.evaluateForList(commands, key, args(ownership, 0)).thenApply(Reply::of);
}
CompletionStage<Reply> inspect(RedisCommandGateway gateway, byte[] key, String ownership) {
return run(gateway, INSPECT, inspectDigest, key, args(ownership, 0));
}
private CompletionStage<Reply> run(
RedisCommandGateway gateway,
String source,
AtomicReference<String> cache,
byte[] key,
List<byte[]> arguments) {
return digest(gateway, source, cache)
.thenCompose(digest -> gateway.evaluateRegisteredForList(digest, key, arguments))
.handle(
(reply, failure) ->
failure == null
? CompletableFuture.completedFuture(reply)
: reload(gateway, source, cache, key, arguments, failure))
.thenCompose(stage -> stage)
.thenApply(LeaseScripts::replyOf);
}
private CompletionStage<List<Object>> reload(
RedisCommandGateway gateway,
String source,
AtomicReference<String> cache,
byte[] key,
List<byte[]> arguments,
Throwable failure) {
if (!scriptMissing(failure)) {
return CompletableFuture.failedFuture(failure);
}
cache.set(null);
return digest(gateway, source, cache)
.thenCompose(digest -> gateway.evaluateRegisteredForList(digest, key, arguments));
}
private static CompletionStage<String> digest(
RedisCommandGateway gateway, String source, AtomicReference<String> cache) {
String cached = cache.get();
if (cached != null) {
return CompletableFuture.completedFuture(cached);
}
return gateway
.loadScript(source.getBytes(StandardCharsets.UTF_8))
.thenApply(
loaded -> {
cache.set(loaded);
return loaded;
});
}
private static boolean scriptMissing(Throwable failure) {
Throwable cause = failure;
while ((cause instanceof CompletionException || cause instanceof ExecutionException)
&& cause.getCause() != null) {
cause = cause.getCause();
}
return cause instanceof io.lettuce.core.RedisNoScriptException;
}
private static Reply replyOf(List<Object> reply) {
if (reply == null || reply.size() < 3) {
throw new IllegalStateException("the lease program answered with an unexpected shape");
}
return new Reply(asLong(reply.get(0)), asLong(reply.get(1)), asText(reply.get(2)));
}
private static long asLong(Object value) {
if (value instanceof Number number) {
return number.longValue();
}
if (value instanceof byte[] bytes) {
return Long.parseLong(new String(bytes, StandardCharsets.UTF_8).strip());
}
throw new IllegalStateException("the lease program answered with an unexpected value type");
}
private static String asText(Object value) {
if (value instanceof byte[] bytes) {
return new String(bytes, StandardCharsets.UTF_8);
}
return value == null ? "" : String.valueOf(value);
CompletionStage<Reply> inspect(SemanticRedisCommands commands, byte[] key, String ownership) {
return inspect.evaluateForList(commands, key, args(ownership, 0)).thenApply(Reply::of);
}
private static List<byte[]> args(String ownership, long ttlMillis) {
@@ -197,5 +114,14 @@ public final class LeaseScripts {
* @param remainingMillis the server's remaining TTL, diagnostic only
* @param holder the stored ownership string, empty when absent
*/
record Reply(long status, long remainingMillis, String holder) {}
record Reply(long status, long remainingMillis, String holder) {
static Reply of(List<Object> reply) {
RegisteredLuaScript.requireShape(reply, 3, "lease");
return new Reply(
RegisteredLuaScript.number(reply.get(0)),
RegisteredLuaScript.number(reply.get(1)),
RegisteredLuaScript.text(reply.get(2)));
}
}
}
@@ -1,12 +1,10 @@
package dev.caskeleton.adapter.outbound.cache.redis.lease;
import dev.caskeleton.adapter.outbound.cache.redis.RedisSemanticFailureLogger;
import dev.caskeleton.adapter.outbound.cache.redis.SemanticRedisCall;
import dev.caskeleton.adapter.outbound.cache.redis.keyspace.CapabilityKeyspace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.error.RedisOperationException;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisLease;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.application.lease.DistributedLeasePort;
import dev.caskeleton.application.lease.LeaseAcquireOutcome;
import dev.caskeleton.application.lease.LeaseAttempt;
@@ -24,7 +22,6 @@ import java.time.Duration;
import java.time.Instant;
import java.util.Base64;
import java.util.Objects;
import java.util.concurrent.TimeUnit;
import java.util.function.LongSupplier;
/**
@@ -47,7 +44,7 @@ public final class RedisDistributedLeaseAdapter implements DistributedLeasePort
private static final SecureRandom RANDOM = new SecureRandom();
private final RedisRuntimeOwner owner;
private final SemanticRedisCall call;
private final LeaseKeys keys;
@@ -57,8 +54,6 @@ public final class RedisDistributedLeaseAdapter implements DistributedLeasePort
private final LongSupplier nanoTime;
private final Duration commandTimeout;
private final Duration contentionRetryAfter;
private final Duration driftBudget;
@@ -84,13 +79,16 @@ public final class RedisDistributedLeaseAdapter implements DistributedLeasePort
Duration commandTimeout,
Duration contentionRetryAfter,
Duration driftBudget) {
this.owner = Objects.requireNonNull(owner, "runtime owner must be non-null");
this.call =
new SemanticRedisCall(
owner,
RedisConnectionKind.SCRIPT,
Objects.requireNonNull(commandTimeout, "command timeout must be non-null"),
"lease");
this.keys = Objects.requireNonNull(keys, "keys must be non-null");
this.scripts = Objects.requireNonNull(scripts, "scripts must be non-null");
this.clock = Objects.requireNonNull(clock, "clock must be non-null");
this.nanoTime = Objects.requireNonNull(nanoTime, "monotonic source must be non-null");
this.commandTimeout =
Objects.requireNonNull(commandTimeout, "command timeout must be non-null");
this.contentionRetryAfter =
Objects.requireNonNull(contentionRetryAfter, "contention retry-after must be non-null");
this.driftBudget = Objects.requireNonNull(driftBudget, "drift budget must be non-null");
@@ -148,43 +146,39 @@ public final class RedisDistributedLeaseAdapter implements DistributedLeasePort
Duration validity = localValidityOf(request.leaseTtl());
String ownership = ownershipOf(request.attempt());
long startedAt = nanoTime.getAsLong();
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
LeaseScripts.Reply reply =
scripts
.acquire(
lease.gateway(),
keys.leaseKey(request.purpose(), request.resourceDigest()),
ownership,
request.leaseTtl().toMillis())
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
return switch ((int) reply.status()) {
case 1 -> new LeaseAcquireOutcome.Acquired(handle(request, ownership, validity, startedAt));
case 2 ->
// The same owner and operation already hold it. This is a retry whose first reply was
// lost, not a second acquisition, and answering "contended" would make a caller back
// off from a lease it already owns. The server did not re-grant the TTL, so the
// handle gets what is left of it, not a fresh one.
new LeaseAcquireOutcome.ReplayedSameOperation(
handle(request, ownership, observedValidityOf(reply.remainingMillis()), startedAt));
default -> contendedOrConflicting(request, reply);
};
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return new LeaseAcquireOutcome.Indeterminate(request.attempt().operationId());
} catch (RedisOperationException failure) {
RedisSemanticFailureLogger.report("lease", "acquire", failure);
// Refused before anything was sent: nothing can have been taken.
return notSent(failure)
? new LeaseAcquireOutcome.Unavailable(LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND)
: new LeaseAcquireOutcome.Indeterminate(request.attempt().operationId());
} catch (Exception failure) {
RedisSemanticFailureLogger.report("lease", "acquire", failure);
// An acquire whose outcome is unknown may have taken the lease. Reporting it as a clean
// failure would let the caller retry under a new attempt and hold it twice; Indeterminate
// tells them to inspect with the same attempt instead.
return new LeaseAcquireOutcome.Indeterminate(request.attempt().operationId());
}
return call.effect(
"acquire",
session -> {
LeaseScripts.Reply reply =
session.await(
scripts.acquire(
session.commands(),
keys.leaseKey(request.purpose(), request.resourceDigest()),
ownership,
request.leaseTtl().toMillis()));
return switch ((int) reply.status()) {
case 1 ->
new LeaseAcquireOutcome.Acquired(handle(request, ownership, validity, startedAt));
case 2 ->
// The same owner and operation already hold it. This is a retry whose first reply
// was lost, not a second acquisition, and answering "contended" would make a caller
// back off from a lease it already owns. The server did not re-grant the TTL, so
// the handle gets what is left of it, not a fresh one.
new LeaseAcquireOutcome.ReplayedSameOperation(
handle(
request,
ownership,
observedValidityOf(reply.remainingMillis()),
startedAt));
default -> contendedOrConflicting(request, reply);
};
},
// Refused before anything was sent: nothing can have been taken.
() -> new LeaseAcquireOutcome.Unavailable(LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND),
// An acquire whose outcome is unknown may have taken the lease. Reporting it as a clean
// failure would let the caller retry under a new attempt and hold it twice; Indeterminate
// tells them to inspect with the same attempt instead.
() -> new LeaseAcquireOutcome.Indeterminate(request.attempt().operationId()));
}
private LeaseAcquireOutcome contendedOrConflicting(
@@ -208,43 +202,36 @@ public final class RedisDistributedLeaseAdapter implements DistributedLeasePort
Objects.requireNonNull(request, "request must be non-null");
String ownership = ownershipOf(request.attempt());
long startedAt = nanoTime.getAsLong();
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
LeaseScripts.Reply reply =
scripts
.inspect(
lease.gateway(),
keys.leaseKey(request.purpose(), request.resourceDigest()),
ownership)
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
if (reply.status() == 1) {
return new LeaseInspectionOutcome.Owned(
new RedisLeaseHandle(
request.purpose(),
request.resourceDigest(),
request.attempt(),
ownership,
observedValidityOf(reply.remainingMillis()),
startedAt));
}
if (reply.status() == 0) {
return new LeaseInspectionOutcome.Absent();
}
return reply.holder().startsWith(request.attempt().ownerToken() + ":")
? new LeaseInspectionOutcome.OwnerOperationConflict()
: new LeaseInspectionOutcome.NotOwner();
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return new LeaseInspectionOutcome.Indeterminate(request.attempt().operationId());
} catch (RedisOperationException failure) {
RedisSemanticFailureLogger.report("lease", "inspect", failure);
return notSent(failure)
? new LeaseInspectionOutcome.Unavailable(LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND)
: new LeaseInspectionOutcome.Indeterminate(request.attempt().operationId());
} catch (Exception failure) {
RedisSemanticFailureLogger.report("lease", "inspect", failure);
return new LeaseInspectionOutcome.Indeterminate(request.attempt().operationId());
}
return call.effect(
"inspect",
session -> {
LeaseScripts.Reply reply =
session.await(
scripts.inspect(
session.commands(),
keys.leaseKey(request.purpose(), request.resourceDigest()),
ownership));
if (reply.status() == 1) {
return new LeaseInspectionOutcome.Owned(
new RedisLeaseHandle(
request.purpose(),
request.resourceDigest(),
request.attempt(),
ownership,
observedValidityOf(reply.remainingMillis()),
startedAt));
}
if (reply.status() == 0) {
return new LeaseInspectionOutcome.Absent();
}
return reply.holder().startsWith(request.attempt().ownerToken() + ":")
? new LeaseInspectionOutcome.OwnerOperationConflict()
: new LeaseInspectionOutcome.NotOwner();
},
() ->
new LeaseInspectionOutcome.Unavailable(
LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND),
() -> new LeaseInspectionOutcome.Indeterminate(request.attempt().operationId()));
}
private RedisLeaseHandle handle(
@@ -262,11 +249,6 @@ public final class RedisDistributedLeaseAdapter implements DistributedLeasePort
return attempt.ownerToken() + ":" + attempt.operationId();
}
/** A typed runtime refusal raised before any command existed — nothing reached Redis. */
private static boolean notSent(RedisOperationException failure) {
return !failure.metadata().ambiguousExecution();
}
/** A held lease, whose validity is its own to track. */
private final class RedisLeaseHandle implements LeaseHandle {
@@ -340,85 +322,65 @@ public final class RedisDistributedLeaseAdapter implements DistributedLeasePort
// Before the round trip, for the reason tryAcquire gives.
Duration validity = localValidityOf(leaseTtl);
long startedAt = nanoTime.getAsLong();
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
LeaseScripts.Reply reply =
scripts
.renew(
lease.gateway(),
keys.leaseKey(purpose, resourceDigest),
ownership,
leaseTtl.toMillis())
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
if (reply.status() == 1) {
// The renewed budget is shortened by the drift allowance for the same reason the first
// one was: a renew does not make the two clocks agree.
grantedValidity = validity;
grantedAtNanos = startedAt;
return new LeaseRenewOutcome.Renewed(remainingValidity());
}
state = LeaseState.LOST;
return reply.status() == 0
? new LeaseRenewOutcome.Absent()
: new LeaseRenewOutcome.NotOwner();
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
state = LeaseState.UNKNOWN;
return new LeaseRenewOutcome.Indeterminate(attempt.operationId());
} catch (RedisOperationException failure) {
RedisSemanticFailureLogger.report("lease", "renew", failure);
if (notSent(failure)) {
return call.effect(
"renew",
session -> {
LeaseScripts.Reply reply =
session.await(
scripts.renew(
session.commands(),
keys.leaseKey(purpose, resourceDigest),
ownership,
leaseTtl.toMillis()));
if (reply.status() == 1) {
// The renewed budget is shortened by the drift allowance for the same reason the
// first one was: a renew does not make the two clocks agree.
grantedValidity = validity;
grantedAtNanos = startedAt;
return new LeaseRenewOutcome.Renewed(remainingValidity());
}
state = LeaseState.LOST;
return reply.status() == 0
? new LeaseRenewOutcome.Absent()
: new LeaseRenewOutcome.NotOwner();
},
// Nothing reached the server, so the lease is exactly what it was: still held, on the
// budget it already had.
return new LeaseRenewOutcome.Unavailable(
LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND);
}
state = LeaseState.UNKNOWN;
return new LeaseRenewOutcome.Indeterminate(attempt.operationId());
} catch (Exception failure) {
RedisSemanticFailureLogger.report("lease", "renew", failure);
// A renew whose outcome is unknown must not extend the local budget. Leaving the handle in
// UNKNOWN is what keeps a caller from acting on validity it cannot demonstrate.
state = LeaseState.UNKNOWN;
return new LeaseRenewOutcome.Indeterminate(attempt.operationId());
}
() -> new LeaseRenewOutcome.Unavailable(LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND),
() -> {
// A renew whose outcome is unknown must not extend the local budget. Leaving the handle
// in UNKNOWN is what keeps a caller from acting on validity it cannot demonstrate.
state = LeaseState.UNKNOWN;
return new LeaseRenewOutcome.Indeterminate(attempt.operationId());
});
}
@Override
public LeaseReleaseOutcome release() {
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
LeaseScripts.Reply reply =
scripts
.release(lease.gateway(), keys.leaseKey(purpose, resourceDigest), ownership)
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
if (reply.status() == 1) {
state = LeaseState.RELEASED;
return new LeaseReleaseOutcome.Released();
}
if (reply.status() == 0) {
state = LeaseState.RELEASED;
return new LeaseReleaseOutcome.AlreadyAbsent();
}
state = LeaseState.LOST;
return new LeaseReleaseOutcome.NotOwner();
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
state = LeaseState.UNKNOWN;
return new LeaseReleaseOutcome.Indeterminate(attempt.operationId());
} catch (RedisOperationException failure) {
RedisSemanticFailureLogger.report("lease", "release", failure);
if (notSent(failure)) {
return new LeaseReleaseOutcome.Unavailable(
LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND);
}
state = LeaseState.UNKNOWN;
return new LeaseReleaseOutcome.Indeterminate(attempt.operationId());
} catch (Exception failure) {
RedisSemanticFailureLogger.report("lease", "release", failure);
state = LeaseState.UNKNOWN;
return new LeaseReleaseOutcome.Indeterminate(attempt.operationId());
}
return call.effect(
"release",
session -> {
LeaseScripts.Reply reply =
session.await(
scripts.release(
session.commands(), keys.leaseKey(purpose, resourceDigest), ownership));
if (reply.status() == 1) {
state = LeaseState.RELEASED;
return new LeaseReleaseOutcome.Released();
}
if (reply.status() == 0) {
state = LeaseState.RELEASED;
return new LeaseReleaseOutcome.AlreadyAbsent();
}
state = LeaseState.LOST;
return new LeaseReleaseOutcome.NotOwner();
},
() ->
new LeaseReleaseOutcome.Unavailable(LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND),
() -> {
state = LeaseState.UNKNOWN;
return new LeaseReleaseOutcome.Indeterminate(attempt.operationId());
});
}
}
@@ -1,4 +1,4 @@
package dev.caskeleton.shared.ratelimit;
package dev.caskeleton.adapter.outbound.cache.redis.ratelimit;
public enum RateLimitAlgorithm {
FIXED_WINDOW,
@@ -1,4 +1,4 @@
package dev.caskeleton.shared.ratelimit;
package dev.caskeleton.adapter.outbound.cache.redis.ratelimit;
import java.time.Duration;
import java.util.Objects;
@@ -27,7 +27,7 @@ public record RateLimitEvaluationDedupPolicy(
"disabled evaluation dedup must not allocate TTL, entries, or stored bytes");
}
} else {
RateLimitBounds.positiveDuration(timeToLive, "timeToLive", MAXIMUM_TIME_TO_LIVE);
RateLimitPolicyBounds.positiveDuration(timeToLive, "timeToLive", MAXIMUM_TIME_TO_LIVE);
if (maximumEntries < 1 || maximumEntries > MAXIMUM_ENTRIES) {
throw new IllegalArgumentException("maximumEntries must be in 1.." + MAXIMUM_ENTRIES);
}
@@ -1,4 +1,4 @@
package dev.caskeleton.shared.ratelimit;
package dev.caskeleton.adapter.outbound.cache.redis.ratelimit;
/** V1 deliberately does not claim fail-open or local fallback semantics. */
public enum RateLimitFailurePolicy {
@@ -1,8 +1,7 @@
package dev.caskeleton.adapter.outbound.cache.redis.ratelimit;
import dev.caskeleton.adapter.outbound.cache.redis.keyspace.CapabilityKeyspace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.shared.ratelimit.RateLimitPolicy;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import java.util.Objects;
/**
@@ -1,5 +1,6 @@
package dev.caskeleton.shared.ratelimit;
package dev.caskeleton.adapter.outbound.cache.redis.ratelimit;
import dev.caskeleton.shared.ratelimit.RateParameters;
import java.time.Duration;
import java.util.Objects;
@@ -36,18 +37,20 @@ public record RateLimitPolicy(
}
public RateLimitPolicy {
RateLimitBounds.policyId(policyId);
RateLimitBounds.policyRevision(policyRevision);
RateLimitPolicyBounds.policyId(policyId);
RateLimitPolicyBounds.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);
RateLimitPolicyBounds.positiveDuration(
cleanupGrace, "cleanupGrace", RateLimitPolicyBounds.MAXIMUM_CLEANUP_GRACE);
RateLimitPolicyBounds.nonNegativeDuration(
maximumClockRegression,
"maximumClockRegression",
RateLimitPolicyBounds.MAXIMUM_CLOCK_REGRESSION);
Objects.requireNonNull(failurePolicy, "failurePolicy must not be null");
Objects.requireNonNull(evaluationDedupPolicy, "evaluationDedupPolicy must not be null");
if (failurePolicy != RateLimitFailurePolicy.FAIL_CLOSED) {
@@ -0,0 +1,70 @@
package dev.caskeleton.adapter.outbound.cache.redis.ratelimit;
import java.time.Duration;
import java.util.Objects;
import java.util.regex.Pattern;
/**
* The bounds a Redis rate-limit policy is validated against.
*
* <p>The policy is this adapter's configuration, not a shared contract, so its bounds live with it.
* The identifier grammars match the ones {@code shared-contract} applies to a request, because a
* request names the policy by the same identifier.
*/
final class RateLimitPolicyBounds {
static final Duration MAXIMUM_CLEANUP_GRACE = Duration.ofDays(1);
static final Duration MAXIMUM_CLOCK_REGRESSION = Duration.ofHours(1);
private static final Pattern POLICY_ID = Pattern.compile("[a-z][a-z0-9-]{0,62}");
private static final Pattern POLICY_REVISION = Pattern.compile("[A-Za-z0-9][A-Za-z0-9._-]{0,63}");
private RateLimitPolicyBounds() {}
static String policyId(String value) {
return boundedIdentifier(value, "policyId", POLICY_ID);
}
static String policyRevision(String value) {
return boundedIdentifier(value, "policyRevision", POLICY_REVISION);
}
static Duration positiveDuration(Duration value, String field, Duration maximum) {
return duration(value, field, false, maximum);
}
static Duration nonNegativeDuration(Duration value, String field, Duration maximum) {
return duration(value, field, true, maximum);
}
private static String boundedIdentifier(String value, String field, Pattern pattern) {
Objects.requireNonNull(value, field + " must not be null");
if (!pattern.matcher(value).matches()) {
throw new IllegalArgumentException(field + " has an invalid bounded representation");
}
return value;
}
private static Duration duration(
Duration value, String field, boolean zeroAllowed, Duration maximum) {
Objects.requireNonNull(value, field + " must not be null");
if (value.isNegative() || (!zeroAllowed && value.isZero())) {
throw new IllegalArgumentException(
field + (zeroAllowed ? " must not be negative" : " must be positive"));
}
if (value.compareTo(maximum) > 0) {
throw new IllegalArgumentException(field + " exceeds its maximum duration of " + maximum);
}
long milliseconds;
try {
milliseconds = value.toMillis();
} catch (ArithmeticException exception) {
throw new IllegalArgumentException(
field + " exceeds the supported milliseconds range", exception);
}
if (!Duration.ofMillis(milliseconds).equals(value)) {
throw new IllegalArgumentException(field + " must use whole milliseconds");
}
return value;
}
}
@@ -1,16 +1,13 @@
package dev.caskeleton.adapter.outbound.cache.redis.ratelimit;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.shared.ratelimit.RateLimitPolicy;
import dev.caskeleton.adapter.outbound.cache.redis.RegisteredLuaScript;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import dev.caskeleton.shared.ratelimit.RateParameters;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.Objects;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.atomic.AtomicReference;
/**
* The atomic programs that make one rate-limit decision one round trip.
@@ -152,46 +149,43 @@ public final class RateLimitScripts {
return {1, math.floor(tokens), resetAfter}
""";
private final AtomicReference<String> fixedWindowDigest = new AtomicReference<>();
private final RegisteredLuaScript fixedWindow = new RegisteredLuaScript(FIXED_WINDOW);
private final AtomicReference<String> slidingCounterDigest = new AtomicReference<>();
private final RegisteredLuaScript slidingCounter = new RegisteredLuaScript(SLIDING_COUNTER);
private final AtomicReference<String> tokenBucketDigest = new AtomicReference<>();
private final RegisteredLuaScript tokenBucket = new RegisteredLuaScript(TOKEN_BUCKET);
/**
* Evaluates one request atomically.
*
* @param gateway the driver seam of a borrowed lease
* @param commands the commands of a borrowed SCRIPT lease
* @param key the rendered counter key
* @param policy the policy to apply
* @param cost the request's cost
* @return the evaluation
*/
public CompletionStage<Evaluation> evaluate(
RedisCommandGateway gateway, byte[] key, RateLimitPolicy policy, long cost) {
Objects.requireNonNull(gateway, "gateway must be non-null");
SemanticRedisCommands commands, byte[] key, RateLimitPolicy policy, long cost) {
Objects.requireNonNull(commands, "commands must be non-null");
Objects.requireNonNull(policy, "policy must be non-null");
long stateTtlMillis = stateTtlMillis(policy);
return switch (policy.parameters()) {
case RateParameters.FixedWindow window ->
run(
gateway,
FIXED_WINDOW,
fixedWindowDigest,
fixedWindow,
commands,
key,
arguments(window.limit(), window.window().toMillis(), cost, stateTtlMillis));
case RateParameters.SlidingCounter sliding ->
run(
gateway,
SLIDING_COUNTER,
slidingCounterDigest,
slidingCounter,
commands,
key,
arguments(sliding.limit(), sliding.window().toMillis(), cost, stateTtlMillis));
case RateParameters.TokenBucket bucket ->
run(
gateway,
TOKEN_BUCKET,
tokenBucketDigest,
tokenBucket,
commands,
key,
arguments(
bucket.capacity(),
@@ -222,82 +216,22 @@ public final class RateLimitScripts {
};
}
private CompletionStage<Evaluation> run(
RedisCommandGateway gateway,
String source,
AtomicReference<String> cache,
private static CompletionStage<Evaluation> run(
RegisteredLuaScript program,
SemanticRedisCommands commands,
byte[] key,
List<byte[]> arguments) {
return digest(gateway, source, cache)
.thenCompose(digest -> gateway.evaluateRegisteredForList(digest, key, arguments))
.handle(
(reply, failure) ->
failure == null
? CompletableFuture.completedFuture(reply)
: reload(gateway, source, cache, key, arguments, failure))
.thenCompose(stage -> stage)
return program
.evaluateForList(commands, key, arguments)
.thenApply(RateLimitScripts::evaluationOf);
}
private CompletionStage<List<Object>> reload(
RedisCommandGateway gateway,
String source,
AtomicReference<String> cache,
byte[] key,
List<byte[]> arguments,
Throwable failure) {
if (!scriptMissing(failure)) {
return CompletableFuture.failedFuture(failure);
}
cache.set(null);
return digest(gateway, source, cache)
.thenCompose(digest -> gateway.evaluateRegisteredForList(digest, key, arguments));
}
private static CompletionStage<String> digest(
RedisCommandGateway gateway, String source, AtomicReference<String> cache) {
String cached = cache.get();
if (cached != null) {
return CompletableFuture.completedFuture(cached);
}
return gateway
.loadScript(source.getBytes(StandardCharsets.UTF_8))
.thenApply(
loaded -> {
cache.set(loaded);
return loaded;
});
}
private static boolean scriptMissing(Throwable failure) {
Throwable cause = failure;
while ((cause instanceof CompletionException || cause instanceof ExecutionException)
&& cause.getCause() != null) {
cause = cause.getCause();
}
return cause instanceof io.lettuce.core.RedisNoScriptException;
}
private static Evaluation evaluationOf(List<Object> reply) {
if (reply == null || reply.size() < 3) {
throw new IllegalStateException(
"the rate limit program answered with "
+ (reply == null ? "nothing" : reply.size())
+ " values; three were expected");
}
return new Evaluation(asLong(reply.get(0)) == 1L, asLong(reply.get(1)), asLong(reply.get(2)));
}
private static long asLong(Object value) {
if (value instanceof Number number) {
return number.longValue();
}
if (value instanceof byte[] bytes) {
return Long.parseLong(new String(bytes, StandardCharsets.UTF_8).strip());
}
throw new IllegalStateException(
"the rate limit program answered with an unexpected value type: "
+ (value == null ? "null" : value.getClass().getName()));
RegisteredLuaScript.requireShape(reply, 3, "rate limit");
return new Evaluation(
RegisteredLuaScript.number(reply.get(0)) == 1L,
RegisteredLuaScript.number(reply.get(1)),
RegisteredLuaScript.number(reply.get(2)));
}
private static List<byte[]> arguments(long... values) {
@@ -1,14 +1,11 @@
package dev.caskeleton.adapter.outbound.cache.redis.ratelimit;
import dev.caskeleton.adapter.outbound.cache.redis.RedisSemanticFailureLogger;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.error.RedisOperationException;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisLease;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.SemanticRedisCall;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.shared.ratelimit.EdgeRateLimitPort;
import dev.caskeleton.shared.ratelimit.RateLimitDecision;
import dev.caskeleton.shared.ratelimit.RateLimitOutcome;
import dev.caskeleton.shared.ratelimit.RateLimitPolicy;
import dev.caskeleton.shared.ratelimit.RateLimitRequest;
import dev.caskeleton.shared.ratelimit.RateParameters;
import java.time.Clock;
@@ -17,7 +14,6 @@ import java.time.Instant;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.concurrent.TimeUnit;
/**
* The provider-neutral edge rate limit, on Redis.
@@ -38,7 +34,7 @@ import java.util.concurrent.TimeUnit;
*/
public final class RedisEdgeRateLimitAdapter implements EdgeRateLimitPort {
private final RedisRuntimeOwner owner;
private final SemanticRedisCall call;
private final RateLimitKeys keys;
@@ -48,8 +44,6 @@ public final class RedisEdgeRateLimitAdapter implements EdgeRateLimitPort {
private final Clock clock;
private final Duration commandTimeout;
private final Duration failureRetryAfter;
/**
@@ -71,13 +65,16 @@ public final class RedisEdgeRateLimitAdapter implements EdgeRateLimitPort {
Clock clock,
Duration commandTimeout,
Duration failureRetryAfter) {
this.owner = Objects.requireNonNull(owner, "runtime owner must be non-null");
this.call =
new SemanticRedisCall(
owner,
RedisConnectionKind.SCRIPT,
Objects.requireNonNull(commandTimeout, "command timeout must be non-null"),
"rate-limit");
this.keys = Objects.requireNonNull(keys, "keys must be non-null");
this.policies = Map.copyOf(Objects.requireNonNull(policies, "policies must be non-null"));
this.scripts = Objects.requireNonNull(scripts, "scripts must be non-null");
this.clock = Objects.requireNonNull(clock, "clock must be non-null");
this.commandTimeout =
Objects.requireNonNull(commandTimeout, "command timeout must be non-null");
this.failureRetryAfter =
Objects.requireNonNull(failureRetryAfter, "failure retry-after must be non-null");
}
@@ -106,34 +103,24 @@ public final class RedisEdgeRateLimitAdapter implements EdgeRateLimitPort {
RateLimitOutcome.UnavailableCategory.ADMISSION_REJECTED);
}
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
RateLimitScripts.Evaluation evaluation =
scripts
.evaluate(
lease.gateway(),
keys.counterKey(policy, request.subjectDigest()),
policy,
request.cost())
.toCompletableFuture()
.get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS);
return new RateLimitOutcome.Evaluated(decisionOf(policy, evaluation, now));
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
return unavailable(policy, RateLimitOutcome.UnavailableCategory.NO_MUTATION_CONFIRMED);
} catch (RedisOperationException failure) {
RedisSemanticFailureLogger.report("rate-limit", "evaluate", failure);
// The distinction that matters: a command the guard refused never reached Redis and consumed
// no budget, while a command that may have run has consumed one the caller will never know
// about. Reporting them the same way would make a retry either free or double-charged.
return unavailable(
policy,
failure.metadata().ambiguousExecution()
? RateLimitOutcome.UnavailableCategory.NO_MUTATION_CONFIRMED
: RateLimitOutcome.UnavailableCategory.UNAVAILABLE_BEFORE_SEND);
} catch (Exception failure) {
RedisSemanticFailureLogger.report("rate-limit", "evaluate", failure);
return unavailable(policy, RateLimitOutcome.UnavailableCategory.NO_MUTATION_CONFIRMED);
}
// The distinction that matters: a command refused before it was sent consumed no budget, while
// one that may have run has consumed one the caller will never know about. Reporting them the
// same way would make a retry either free or double-charged.
return call.effect(
"evaluate",
session ->
new RateLimitOutcome.Evaluated(
decisionOf(
policy,
session.await(
scripts.evaluate(
session.commands(),
keys.counterKey(policy, request.subjectDigest()),
policy,
request.cost())),
now)),
() -> unavailable(policy, RateLimitOutcome.UnavailableCategory.UNAVAILABLE_BEFORE_SEND),
() -> unavailable(policy, RateLimitOutcome.UnavailableCategory.NO_MUTATION_CONFIRMED));
}
private RateLimitOutcome unavailable(
@@ -1,2 +1,6 @@
org.springframework.boot.EnvironmentPostProcessor=\
dev.caskeleton.adapter.outbound.cache.redis.capability.RedisReadinessGroupPostProcessor
# Which roles need Redis for correctness. The runtime asks; this module owns the selectors.
dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisCorrectnessRequirement=\
dev.caskeleton.adapter.outbound.cache.redis.capability.RedisCorrectnessRoleSelectors
@@ -1,17 +1,17 @@
package dev.caskeleton.adapter.outbound.cache.redis;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.RedisTopologyEndpoint;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisCredentialResolver.RedisCredentials;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkSettings;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisCredentialRole;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisTopologyClientFactory;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisTopologyEndpoint;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisCredentialResolver.RedisCredentials;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeSettings;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisAccount;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLane;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisTopologyClientFactory;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import java.io.IOException;
import java.time.Duration;
import java.util.ArrayList;
import java.util.EnumMap;
import java.util.List;
import java.util.Map;
import java.util.Optional;
@@ -34,7 +34,7 @@ public final class LiveRedisRuntime {
*/
public static RedisRuntimeOwner open(RedisNamespace namespace, boolean separateScriptAccount) {
RedisTopologyEndpoint endpoint = RedisTopologyEndpoint.fromSystemProperties();
RedisSdkSettings settings = new RedisSdkSettings();
RedisRuntimeSettings settings = new RedisRuntimeSettings();
settings.setEnabled(true);
settings.setMode(endpoint.mode());
settings.setNodes(new ArrayList<>(List.of(endpoint.host() + ":" + endpoint.port())));
@@ -42,18 +42,18 @@ public final class LiveRedisRuntime {
settings.getNamespace().setService(namespace.service());
settings.getNamespace().setDomain(namespace.domain());
Map<RedisCredentialRole, RedisCredentials> accounts = new EnumMap<>(RedisCredentialRole.class);
Map<RedisAccount, RedisCredentials> accounts = new java.util.LinkedHashMap<>();
accounts.put(
RedisCredentialRole.APPLICATION,
RedisAccount.APPLICATION,
new RedisCredentials(
endpoint.username(),
endpoint.password().isBlank() ? "fixture-application" : endpoint.password()));
if (separateScriptAccount) {
accounts.put(
RedisCredentialRole.ADVANCED,
RedisAccount.ADVANCED,
new RedisCredentials("ca-skeleton-application-advanced", "fixture-advanced"));
}
Map<RedisConnectionKind, Integer> limits = new EnumMap<>(RedisConnectionKind.class);
Map<RedisLane, Integer> limits = new java.util.LinkedHashMap<>();
for (RedisConnectionKind kind : RedisConnectionKind.values()) {
limits.put(kind, 4);
}
@@ -7,15 +7,18 @@ import dev.caskeleton.adapter.outbound.cache.redis.idempotency.IdempotencyScript
import dev.caskeleton.adapter.outbound.cache.redis.idempotency.RedisIdempotencyStoreAdapter;
import dev.caskeleton.adapter.outbound.cache.redis.lease.LeaseScripts;
import dev.caskeleton.adapter.outbound.cache.redis.lease.RedisDistributedLeaseAdapter;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RateLimitAlgorithm;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RateLimitFailurePolicy;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RateLimitKeys;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RateLimitPolicy;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RateLimitScripts;
import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RedisEdgeRateLimitAdapter;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.RedisTopologyEndpoint;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisLease;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisTopologyEndpoint;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLease;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.application.cache.CacheLookup;
import dev.caskeleton.application.cache.CacheRecordIntent;
import dev.caskeleton.application.cache.CacheRecordMetadata;
@@ -30,10 +33,7 @@ import dev.caskeleton.application.lease.LeaseAcquireOutcome;
import dev.caskeleton.application.lease.LeaseAttempt;
import dev.caskeleton.application.lease.LeaseRequest;
import dev.caskeleton.application.transaction.OperationId;
import dev.caskeleton.shared.ratelimit.RateLimitAlgorithm;
import dev.caskeleton.shared.ratelimit.RateLimitFailurePolicy;
import dev.caskeleton.shared.ratelimit.RateLimitOutcome;
import dev.caskeleton.shared.ratelimit.RateLimitPolicy;
import dev.caskeleton.shared.ratelimit.RateLimitRequest;
import dev.caskeleton.shared.ratelimit.RateParameters;
import java.nio.charset.StandardCharsets;
@@ -254,7 +254,7 @@ class LiveRedisSemanticPortsTest {
private static long fieldCount(RedisRuntimeOwner runtime, byte[] key) throws Exception {
try (RedisLease lease = runtime.borrow(RedisConnectionKind.REGULAR)) {
return lease.gateway().hashSize(key).toCompletableFuture().get(2, TimeUnit.SECONDS);
return lease.driver().commands().hlen(key).toCompletableFuture().get(2, TimeUnit.SECONDS);
}
}
@@ -0,0 +1,118 @@
package dev.caskeleton.adapter.outbound.cache.redis;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.catchThrowable;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import java.lang.reflect.Proxy;
import java.nio.charset.StandardCharsets;
import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Deque;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
class RegisteredLuaScriptTest {
private static final byte[] KEY = "prod:svc:shared:probe".getBytes(StandardCharsets.UTF_8);
@Test
void aProgramIsLoadedOnceAndThenRunByDigest() {
// given
ScriptedServer server = new ScriptedServer();
RegisteredLuaScript program = new RegisteredLuaScript("return 1");
// when
program.evaluateForLong(server.commands(), KEY, List.of()).toCompletableFuture().join();
program.evaluateForLong(server.commands(), KEY, List.of()).toCompletableFuture().join();
// then
assertThat(server.calls).containsExactly("load", "eval:digest-1", "eval:digest-1");
}
@Test
@DisplayName("NOSCRIPT 타입 응답이면 다시 올린 뒤 정확히 한 번만 재실행한다")
void aForgottenProgramIsReloadedAndRetriedExactlyOnce() {
// given
ScriptedServer server = new ScriptedServer();
server.failNext(new io.lettuce.core.RedisNoScriptException("NOSCRIPT No matching script"));
RegisteredLuaScript program = new RegisteredLuaScript("return 1");
// when
program.evaluateForLong(server.commands(), KEY, List.of()).toCompletableFuture().join();
// then
assertThat(server.calls).containsExactly("load", "eval:digest-1", "load", "eval:digest-2");
}
@Test
void aFailureThatIsNotNoScriptIsNeitherReloadedNorRetried() {
// given
ScriptedServer server = new ScriptedServer();
server.failNext(new io.lettuce.core.RedisCommandExecutionException("NOPERM denied"));
RegisteredLuaScript program = new RegisteredLuaScript("return 1");
// when
Throwable failure =
catchThrowable(
() ->
program
.evaluateForLong(server.commands(), KEY, List.of())
.toCompletableFuture()
.join());
// then
assertThat(failure)
.hasRootCauseInstanceOf(io.lettuce.core.RedisCommandExecutionException.class)
.hasRootCauseMessage("NOPERM denied");
}
@Test
void aShortReplyIsRefusedWithTheProgramsName() {
// when
Throwable failure =
catchThrowable(() -> RegisteredLuaScript.requireShape(List.of(1L), 3, "lease"));
// then
assertThat(failure)
.isInstanceOf(IllegalStateException.class)
.hasMessage("the lease program answered with 1 values; 3 were expected");
}
/** Counts loads and evaluations, and fails an evaluation on request. */
private static final class ScriptedServer {
private final List<String> calls = new ArrayList<>();
private final Deque<RuntimeException> failures = new ArrayDeque<>();
private int loads;
void failNext(RuntimeException failure) {
failures.add(failure);
}
SemanticRedisCommands commands() {
return (SemanticRedisCommands)
Proxy.newProxyInstance(
SemanticRedisCommands.class.getClassLoader(),
new Class<?>[] {SemanticRedisCommands.class},
(proxy, method, arguments) ->
switch (method.getName()) {
case "loadScript" -> {
calls.add("load");
loads++;
yield CompletableFuture.completedFuture("digest-" + loads);
}
case "evaluateRegisteredForLong" -> {
calls.add("eval:" + arguments[0]);
RuntimeException failure = failures.poll();
yield failure == null
? CompletableFuture.completedFuture(1L)
: CompletableFuture.failedFuture(failure);
}
default -> throw new UnsupportedOperationException(method.getName());
});
}
}
}
@@ -2,13 +2,15 @@ package dev.caskeleton.adapter.outbound.cache.redis.cache;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.InMemoryGatewayAccess;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.InMemorySemanticRedisCommands;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLane;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.StubRedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.application.cache.AuthoritativeAbsence;
import dev.caskeleton.application.cache.CacheInvalidationOutcome;
import dev.caskeleton.application.cache.CacheLookup;
@@ -21,7 +23,6 @@ import java.time.Clock;
import java.time.Duration;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.EnumMap;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import org.junit.jupiter.api.DisplayName;
@@ -39,14 +40,14 @@ class RedisCacheRegionAdapterTest {
private static final Instant T0 = Instant.parse("2026-08-10T12:00:00Z");
private final InMemoryGatewayAccess gateway = InMemoryGatewayAccess.create();
private final InMemorySemanticRedisCommands gateway = new InMemorySemanticRedisCommands();
private final RedisCacheRegionAdapter.CacheKeys keys =
new RedisCacheRegionAdapter.CacheKeys(
new RedisNamespace("prod", "ca-skeleton", "shared"), "orders", 1);
private RedisCacheRegionAdapter<String, String> cache(Instant now) {
return cache(now, new StubClient(gateway.gateway()));
return cache(now, StubRedisRuntimeClient.serving(gateway));
}
private RedisCacheRegionAdapter<String, String> cache(Instant now, RedisRuntimeClient client) {
@@ -55,7 +56,7 @@ class RedisCacheRegionAdapterTest {
private RedisCacheRegionAdapter<String, String> cache(
Instant now, RedisRuntimeClient client, RedisCacheRegionAdapter.CacheKeys cacheKeys) {
Map<RedisConnectionKind, Integer> limits = new EnumMap<>(RedisConnectionKind.class);
Map<RedisLane, Integer> limits = new java.util.LinkedHashMap<>();
for (RedisConnectionKind kind : RedisConnectionKind.values()) {
limits.put(kind, 4);
}
@@ -224,9 +225,9 @@ class RedisCacheRegionAdapterTest {
new RedisNamespace("prod", "ca-skeleton", "shared"), "orders-shared", 1);
RedisCacheRegionAdapter<String, String> first =
cache(T0, new StubClient(gateway.gateway()), firstKeys);
cache(T0, StubRedisRuntimeClient.serving(gateway), firstKeys);
RedisCacheRegionAdapter<String, String> second =
cache(T0, new StubClient(gateway.gateway()), secondKeys);
cache(T0, StubRedisRuntimeClient.serving(gateway), secondKeys);
second.record("order-1", "payload", upsert());
assertThat(second.lookup("order-1")).isInstanceOf(CacheLookup.Hit.class);
@@ -240,7 +241,7 @@ class RedisCacheRegionAdapterTest {
// The same process state (secondKeys) is reused with a later clock. Once the positive soft TTL
// elapses it must sample the server generation again and stop serving the old region entry.
RedisCacheRegionAdapter<String, String> secondAfterRecheck =
cache(T0.plusSeconds(31), new StubClient(gateway.gateway()), secondKeys);
cache(T0.plusSeconds(31), StubRedisRuntimeClient.serving(gateway), secondKeys);
CacheLookup<String> lookup = secondAfterRecheck.lookup("order-1");
assertThat(lookup).isInstanceOf(CacheLookup.Miss.class);
@@ -329,7 +330,8 @@ class RedisCacheRegionAdapterTest {
@DisplayName("보낸 뒤 응답을 잃은 SET은 적용됐을 수 있으므로 INDETERMINATE다")
void aWriteWhoseReplyWasLostIsIndeterminate() {
// given
RedisCacheRegionAdapter<String, String> cache = cache(T0, new StubClient(losingReplyOf("set")));
RedisCacheRegionAdapter<String, String> cache =
cache(T0, StubRedisRuntimeClient.serving(losingReplyOf("set")));
// when
CacheRecordOutcome outcome = cache.record("order-1", "payload", upsert());
@@ -343,7 +345,7 @@ class RedisCacheRegionAdapterTest {
void aWriteThatFailedBeforeItsSetWasSentDegrades() {
// given
RedisCacheRegionAdapter<String, String> cache =
cache(T0, new StubClient(losingReplyOf("incrementBy")));
cache(T0, StubRedisRuntimeClient.serving(losingReplyOf("incrementBy")));
// when
CacheRecordOutcome outcome = cache.record("order-1", "payload", upsert());
@@ -357,7 +359,7 @@ class RedisCacheRegionAdapterTest {
void anInvalidationWhoseReplyWasLostIsIndeterminate() {
// given
RedisCacheRegionAdapter<String, String> cache =
cache(T0, new StubClient(losingReplyOf("getAndDelete")));
cache(T0, StubRedisRuntimeClient.serving(losingReplyOf("getAndDelete")));
// when
CacheInvalidationOutcome outcome = cache.invalidate("order-1");
@@ -371,7 +373,7 @@ class RedisCacheRegionAdapterTest {
void aRegionInvalidationWhoseReplyWasLostIsIndeterminate() {
// given
RedisCacheRegionAdapter<String, String> cache =
cache(T0, new StubClient(losingReplyOf("incrementBy")));
cache(T0, StubRedisRuntimeClient.serving(losingReplyOf("incrementBy")));
// when
CacheInvalidationOutcome outcome = cache.invalidateRegion();
@@ -381,12 +383,12 @@ class RedisCacheRegionAdapterTest {
}
/** The in-memory gateway, except that one command's reply is lost after it was sent. */
private RedisCommandGateway losingReplyOf(String command) {
RedisCommandGateway real = gateway.gateway();
return (RedisCommandGateway)
private SemanticRedisCommands losingReplyOf(String command) {
SemanticRedisCommands real = gateway;
return (SemanticRedisCommands)
Proxy.newProxyInstance(
RedisCommandGateway.class.getClassLoader(),
new Class<?>[] {RedisCommandGateway.class},
SemanticRedisCommands.class.getClassLoader(),
new Class<?>[] {SemanticRedisCommands.class},
(proxy, method, arguments) ->
method.getName().equals(command)
? CompletableFuture.failedFuture(new RuntimeException("reply lost"))
@@ -410,14 +412,11 @@ class RedisCacheRegionAdapterTest {
private void writeRaw(String key, byte[] stored) {
try {
gateway
.gateway()
.set(
keys.entryKey("digest-" + key),
stored,
dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.WritePresence
.ALWAYS,
new dev.caskeleton.adapter.outbound.cache.redis.sdk.api.operations.Expiration.After(
Duration.ofMinutes(10)))
dev.caskeleton.adapter.outbound.cache.redis.runtime.command.WritePresence.ALWAYS,
Duration.ofMinutes(10))
.toCompletableFuture()
.join();
} catch (RuntimeException failure) {
@@ -425,36 +424,6 @@ class RedisCacheRegionAdapterTest {
}
}
private record StubClient(RedisCommandGateway gateway) implements RedisRuntimeClient {
@Override
public RedisDeploymentMode mode() {
return RedisDeploymentMode.STANDALONE;
}
@Override
public RedisLaneConnection openLane(
RedisConnectionKind kind, java.util.Optional<byte[]> routingKey) {
return new RedisLaneConnection() {
@Override
public RedisCommandGateway gateway() {
return gateway;
}
@Override
public boolean open() {
return true;
}
@Override
public void close() {}
};
}
@Override
public void close() {}
}
private static final class BrokenClient implements RedisRuntimeClient {
@Override
@@ -463,8 +432,7 @@ class RedisCacheRegionAdapterTest {
}
@Override
public RedisLaneConnection openLane(
RedisConnectionKind kind, java.util.Optional<byte[]> routingKey) {
public RedisLaneConnection openLane(RedisLane kind, java.util.Optional<byte[]> routingKey) {
throw new IllegalStateException("the server is unreachable");
}
@@ -5,8 +5,8 @@ import static org.assertj.core.api.Assertions.assertThatCode;
import static org.assertj.core.api.Assertions.catchThrowable;
import dev.caskeleton.adapter.outbound.cache.redis.LiveRedisRuntime;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.support.CapabilityStartupValidationException;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
@@ -2,7 +2,7 @@ package dev.caskeleton.adapter.outbound.cache.redis.capability;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.application.outbound.SecretSourcePort;
import java.time.Clock;
import java.util.ArrayList;
@@ -3,8 +3,8 @@ package dev.caskeleton.adapter.outbound.cache.redis.capability;
import static org.assertj.core.api.Assertions.assertThat;
import static org.mockito.Mockito.mock;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkAutoConfiguration;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeAutoConfiguration;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailureException;
import dev.caskeleton.application.cache.CacheRegionPort;
import dev.caskeleton.application.idempotency.IdempotencyStorePort;
@@ -40,7 +40,7 @@ class RedisCapabilityCompositionTest {
private final ApplicationContextRunner runner =
new ApplicationContextRunner()
.withConfiguration(AutoConfigurations.of(RedisSdkAutoConfiguration.class))
.withConfiguration(AutoConfigurations.of(RedisRuntimeAutoConfiguration.class))
.withBean(
"compositionOnlyRedisSemanticScriptAclProbe",
RedisSemanticScriptAclProbe.class,
@@ -100,7 +100,7 @@ class RedisCapabilityCompositionTest {
// Every call would answer "unknown policy", which the port reports as a deployment error per
// request rather than once, at the only moment anybody is looking.
new ApplicationContextRunner()
.withConfiguration(AutoConfigurations.of(RedisSdkAutoConfiguration.class))
.withConfiguration(AutoConfigurations.of(RedisRuntimeAutoConfiguration.class))
.withUserConfiguration(RedisCapabilityConfig.class, Support.class)
.withPropertyValues(
"app.redis.enabled=true",
@@ -170,7 +170,7 @@ class RedisCapabilityCompositionTest {
void theSwitchOffLeavesNoRedisBeanWhateverTheRolesSay() {
new ApplicationContextRunner()
.withConfiguration(
AutoConfigurations.of(RedisSdkAutoConfiguration.class, RedisCapabilityConfig.class))
AutoConfigurations.of(RedisRuntimeAutoConfiguration.class, RedisCapabilityConfig.class))
.withUserConfiguration(Support.class)
.withPropertyValues(
"app.redis.enabled=false",
@@ -0,0 +1,80 @@
package dev.caskeleton.adapter.outbound.cache.redis.capability;
import static org.assertj.core.api.Assertions.assertThat;
import java.util.List;
import java.util.stream.Stream;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.Arguments;
import org.junit.jupiter.params.provider.MethodSource;
import org.springframework.mock.env.MockEnvironment;
/**
* Which production secrets each selected Redis role needs — the rule the composition root's secret
* guard used to spell out itself, one Redis role prefix at a time.
*/
class RedisProductionSecretsTest {
private final RedisProductionSecrets secrets = new RedisProductionSecrets();
static Stream<Arguments> selectedRoles() {
return Stream.of(
Arguments.of(
"ca-skeleton.capabilities.cache.bindings.default",
"redis",
List.of("APP_CACHE_REDIS_PASSWORD", "APP_CACHE_REDIS_KEY_HMAC_SECRET")),
Arguments.of(
"ca-skeleton.security.auth-mode",
"redis-session",
List.of("APP_SESSION_REDIS_PASSWORD", "APP_SESSION_REDIS_KEY_HMAC_SECRET")),
Arguments.of(
"ca-skeleton.capabilities.idempotency.provider",
"redis",
List.of("APP_IDEMPOTENCY_REDIS_KEY_HMAC_SECRET")),
Arguments.of(
"ca-skeleton.capabilities.rate-limit.provider",
"redis",
List.of("APP_RATE_LIMIT_REDIS_PASSWORD", "APP_RATE_LIMIT_REDIS_KEY_HMAC_SECRET")),
Arguments.of(
"ca-skeleton.capabilities.lease.provider",
"redis",
List.of("APP_LEASE_REDIS_KEY_HMAC_SECRET")));
}
@ParameterizedTest(name = "{0}={1}")
@MethodSource("selectedRoles")
@DisplayName("선택된 Redis 역할은 자기 production secret만 요구한다")
void aSelectedRoleRequiresExactlyItsOwnSecrets(
String selector, String value, List<String> expected) {
// given
MockEnvironment environment = new MockEnvironment().withProperty(selector, value);
// when
List<String> required = secrets.requiredSecrets(environment);
// then
assertThat(required).containsExactlyElementsOf(expected);
}
@Test
@DisplayName("Redis가 켜져 있어도 역할이 선택되지 않았으면 역할 secret을 요구하지 않는다")
void noSelectedRoleRequiresNoRoleSecret() {
assertThat(secrets.requiredSecrets(new MockEnvironment())).isEmpty();
}
@Test
void aRoleSelectingAnotherProviderRequiresNothingOfRedis() {
// given
MockEnvironment environment =
new MockEnvironment()
.withProperty("ca-skeleton.capabilities.rate-limit.provider", "disabled");
// when
List<String> required = secrets.requiredSecrets(environment);
// then
assertThat(required).isEmpty();
}
}
@@ -2,7 +2,7 @@ package dev.caskeleton.adapter.outbound.cache.redis.capability;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisCorrectnessRoles;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisCorrectnessRoles;
import dev.caskeleton.adapter.outbound.support.startup.ReadinessGroup;
import java.io.IOException;
import java.util.ArrayList;
@@ -148,7 +148,10 @@ class RedisReadinessGroupPostProcessorTest {
@Test
@DisplayName("every correctness selector makes the post-processor append Redis readiness")
void eachCorrectnessSelectorAppendsRedisReadiness() throws IOException {
for (Map.Entry<String, String> selector : RedisCorrectnessRoles.selectors().entrySet()) {
for (RedisCorrectnessRoleSelectors.Role role :
RedisCorrectnessRoleSelectors.ROLES.stream()
.filter(RedisCorrectnessRoleSelectors.Role::correctness)
.toList()) {
StandardEnvironment environment = new StandardEnvironment();
environment
.getPropertySources()
@@ -160,14 +163,14 @@ class RedisReadinessGroupPostProcessorTest {
shippedReadinessInclude(),
"app.redis.enabled",
"true",
selector.getKey(),
selector.getValue())));
role.selector(),
role.selecting())));
new RedisReadinessGroupPostProcessor()
.postProcessEnvironment(environment, new SpringApplication());
assertThat(environment.getProperty(ReadinessGroup.INCLUDE_PROPERTY))
.as("%s=%s", selector.getKey(), selector.getValue())
.as("%s=%s", role.selector(), role.selecting())
.contains("readinessState", RedisCorrectnessRoles.REQUIRED_HEALTH_CONTRIBUTOR);
}
}
@@ -180,7 +183,7 @@ class RedisReadinessGroupPostProcessorTest {
HealthContributorAutoConfiguration.class,
AvailabilityHealthContributorAutoConfiguration.class,
HealthEndpointAutoConfiguration.class,
dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkAutoConfiguration.class
dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeAutoConfiguration.class
})
static class HealthContext {
@@ -190,7 +193,7 @@ class RedisReadinessGroupPostProcessorTest {
}
@Bean
dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkAutoConfiguration
dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeAutoConfiguration
.RedisSecretSource
stubSecretSource() {
// Supplies the credential the enabled cases require, without putting one in the process
@@ -5,17 +5,18 @@ import static org.assertj.core.api.Assertions.assertThatCode;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import static org.assertj.core.api.Assertions.catchThrowable;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLane;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.support.CapabilityStartupValidationException;
import java.lang.reflect.Proxy;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.EnumMap;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.atomic.AtomicInteger;
@@ -104,7 +105,7 @@ class RedisSemanticScriptAclProbeTest {
.hasMessageContaining("SCRIPT LOAD/EVALSHA is unavailable");
}
private static RedisRuntimeOwner owner(RedisCommandGateway gateway, AtomicInteger opened) {
private static RedisRuntimeOwner owner(SemanticRedisCommands gateway, AtomicInteger opened) {
RedisRuntimeClient client =
new RedisRuntimeClient() {
@Override
@@ -113,15 +114,21 @@ class RedisSemanticScriptAclProbeTest {
}
@Override
public RedisLaneConnection openLane(
RedisConnectionKind kind, Optional<byte[]> routingKey) {
public RedisLaneConnection openLane(RedisLane kind, Optional<byte[]> routingKey) {
opened.incrementAndGet();
return new RedisLaneConnection() {
@Override
public RedisCommandGateway gateway() {
public SemanticRedisCommands commands() {
return gateway;
}
@Override
public dev.caskeleton.adapter.outbound.cache.redis.runtime.connection
.RedisDriverConnection
driver() {
throw new UnsupportedOperationException();
}
@Override
public boolean open() {
return true;
@@ -135,18 +142,18 @@ class RedisSemanticScriptAclProbeTest {
@Override
public void close() {}
};
EnumMap<RedisConnectionKind, Integer> limits = new EnumMap<>(RedisConnectionKind.class);
Map<RedisLane, Integer> limits = new java.util.LinkedHashMap<>();
for (RedisConnectionKind kind : RedisConnectionKind.values()) {
limits.put(kind, 1);
}
return new RedisRuntimeOwner(client, limits, Duration.ofSeconds(1), Duration.ofSeconds(1));
}
private static RedisCommandGateway gateway(boolean denyScripts) {
return (RedisCommandGateway)
private static SemanticRedisCommands gateway(boolean denyScripts) {
return (SemanticRedisCommands)
Proxy.newProxyInstance(
RedisCommandGateway.class.getClassLoader(),
new Class<?>[] {RedisCommandGateway.class},
SemanticRedisCommands.class.getClassLoader(),
new Class<?>[] {SemanticRedisCommands.class},
(proxy, method, arguments) ->
switch (method.getName()) {
case "loadScript" ->
@@ -169,12 +176,12 @@ class RedisSemanticScriptAclProbeTest {
* <p>Redis checks a script's inner commands against the caller's ACL when they run, so a program
* that calls the denied command fails with {@code NOPERM} and one that does not call it succeeds.
*/
private static RedisCommandGateway gatewayDenying(String command) {
private static SemanticRedisCommands gatewayDenying(String command) {
AtomicReference<String> loaded = new AtomicReference<>("");
return (RedisCommandGateway)
return (SemanticRedisCommands)
Proxy.newProxyInstance(
RedisCommandGateway.class.getClassLoader(),
new Class<?>[] {RedisCommandGateway.class},
SemanticRedisCommands.class.getClassLoader(),
new Class<?>[] {SemanticRedisCommands.class},
(proxy, method, arguments) ->
switch (method.getName()) {
case "loadScript" -> {
@@ -1,29 +0,0 @@
package dev.caskeleton.adapter.outbound.cache.redis.idempotency;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import java.lang.reflect.Field;
import java.util.Map;
import java.util.concurrent.atomic.AtomicReference;
import org.junit.jupiter.api.Test;
/** Pins the script-digest cache so request threads never mutate a shared map structure. */
class IdempotencyScriptsConcurrencyContractTest {
@Test
void digestSlotsArePreallocatedAndStructurallyImmutable() throws Exception {
IdempotencyScripts scripts = new IdempotencyScripts();
Field field = IdempotencyScripts.class.getDeclaredField("digests");
field.setAccessible(true);
@SuppressWarnings("unchecked")
Map<String, AtomicReference<String>> digests =
(Map<String, AtomicReference<String>>) field.get(scripts);
assertThat(digests).containsOnlyKeys("claim", "transition", "release", "inspect");
assertThat(digests.values()).allSatisfy(slot -> assertThat(slot.get()).isNull());
assertThatThrownBy(() -> digests.put("runtime-added", new AtomicReference<>()))
.isInstanceOf(UnsupportedOperationException.class);
}
}
@@ -2,13 +2,14 @@ package dev.caskeleton.adapter.outbound.cache.redis.idempotency;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.InMemoryGatewayAccess;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.InMemorySemanticRedisCommands;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLane;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.StubRedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.application.idempotency.IdempotencyClaimAttempt;
import dev.caskeleton.application.idempotency.IdempotencyClaimOutcome;
import dev.caskeleton.application.idempotency.IdempotencyClaimRequest;
@@ -29,7 +30,6 @@ import java.time.Clock;
import java.time.Duration;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.EnumMap;
import java.util.Map;
import java.util.stream.Stream;
import org.junit.jupiter.api.DisplayName;
@@ -62,9 +62,10 @@ class RedisIdempotencyStoreAdapterTest {
private static final OperationId OTHER_OPERATION = new OperationId("operation-bbbbbbbbbb");
private final InMemoryGatewayAccess gateway = InMemoryGatewayAccess.create();
private final InMemorySemanticRedisCommands gateway = new InMemorySemanticRedisCommands();
private final RedisIdempotencyStoreAdapter store = store(T0, new StubClient(gateway.gateway()));
private final RedisIdempotencyStoreAdapter store =
store(T0, StubRedisRuntimeClient.serving(gateway));
private RedisIdempotencyStoreAdapter store(Instant now, RedisRuntimeClient client) {
return store(now, owner(client, 4, Duration.ofSeconds(1)));
@@ -72,7 +73,7 @@ class RedisIdempotencyStoreAdapterTest {
private static RedisRuntimeOwner owner(
RedisRuntimeClient client, int connectionsPerLane, Duration acquireTimeout) {
Map<RedisConnectionKind, Integer> limits = new EnumMap<>(RedisConnectionKind.class);
Map<RedisLane, Integer> limits = new java.util.LinkedHashMap<>();
for (RedisConnectionKind kind : RedisConnectionKind.values()) {
limits.put(kind, connectionsPerLane);
}
@@ -83,7 +84,7 @@ class RedisIdempotencyStoreAdapterTest {
* An owner with one script connection and almost no patience, so holding it saturates the lane.
*/
private RedisRuntimeOwner narrowOwner() {
return owner(new StubClient(gateway.gateway()), 1, Duration.ofMillis(10));
return owner(StubRedisRuntimeClient.serving(gateway), 1, Duration.ofMillis(10));
}
private RedisIdempotencyStoreAdapter store(Instant now, RedisRuntimeOwner owner) {
@@ -264,7 +265,7 @@ class RedisIdempotencyStoreAdapterTest {
// The first holder went away. Advancing the Redis fixture clock, not the caller JVM clock,
// expires the distributed processing lease.
gateway.advance(Duration.ofSeconds(60));
RedisIdempotencyStoreAdapter later = store(T0, new StubClient(gateway.gateway()));
RedisIdempotencyStoreAdapter later = store(T0, StubRedisRuntimeClient.serving(gateway));
IdempotencyClaimOutcome outcome =
later.claim(
new IdempotencyClaimRequest(
@@ -394,36 +395,6 @@ class RedisIdempotencyStoreAdapterTest {
return store.markExecutionStarted(owner, OPERATION).owner().orElseThrow();
}
private record StubClient(RedisCommandGateway gateway) implements RedisRuntimeClient {
@Override
public RedisDeploymentMode mode() {
return RedisDeploymentMode.STANDALONE;
}
@Override
public RedisLaneConnection openLane(
RedisConnectionKind kind, java.util.Optional<byte[]> routingKey) {
return new RedisLaneConnection() {
@Override
public RedisCommandGateway gateway() {
return gateway;
}
@Override
public boolean open() {
return true;
}
@Override
public void close() {}
};
}
@Override
public void close() {}
}
private static final class BrokenClient implements RedisRuntimeClient {
@Override
@@ -432,8 +403,7 @@ class RedisIdempotencyStoreAdapterTest {
}
@Override
public RedisLaneConnection openLane(
RedisConnectionKind kind, java.util.Optional<byte[]> routingKey) {
public RedisLaneConnection openLane(RedisLane kind, java.util.Optional<byte[]> routingKey) {
throw new IllegalStateException("the server is unreachable");
}
@@ -0,0 +1,53 @@
package dev.caskeleton.adapter.outbound.cache.redis.lease;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.InMemorySemanticRedisCommands;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import java.lang.reflect.Proxy;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.atomic.AtomicBoolean;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
class LeaseScriptsTest {
private static final byte[] KEY = "prod:svc:shared:lease:v1:p:r".getBytes(StandardCharsets.UTF_8);
@Test
@DisplayName("NOSCRIPT가 예외 타입이 아니라 메시지로만 와도 lease 프로그램을 다시 올리고 한 번 재실행한다")
void aProgramTheServerForgotIsReloadedEvenWhenOnlyTheMessageSaysNoScript() {
// given
SemanticRedisCommands server = forgettingOnce(new InMemorySemanticRedisCommands());
LeaseScripts scripts = new LeaseScripts();
// when
LeaseScripts.Reply reply =
scripts.acquire(server, KEY, "owner:operation", 30_000).toCompletableFuture().join();
// then
assertThat(reply.status()).isEqualTo(1L);
}
/**
* A server that has lost every loaded script once, and says so the way a proxy or a wrapped
* driver error does: a generic command failure whose message starts with {@code NOSCRIPT}.
*/
private static SemanticRedisCommands forgettingOnce(SemanticRedisCommands delegate) {
AtomicBoolean forgotten = new AtomicBoolean();
return (SemanticRedisCommands)
Proxy.newProxyInstance(
SemanticRedisCommands.class.getClassLoader(),
new Class<?>[] {SemanticRedisCommands.class},
(proxy, method, arguments) -> {
if (method.getName().startsWith("evaluateRegistered")
&& forgotten.compareAndSet(false, true)) {
return CompletableFuture.failedFuture(
new io.lettuce.core.RedisCommandExecutionException(
"NOSCRIPT No matching script. Please use EVAL."));
}
return method.invoke(delegate, arguments);
});
}
}
@@ -0,0 +1,65 @@
package dev.caskeleton.adapter.outbound.cache.redis.lease;
import dev.caskeleton.adapter.outbound.cache.redis.LiveRedisRuntime;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.application.lease.DistributedLeasePort;
import dev.caskeleton.application.lease.testkit.DistributedLeaseContract;
import java.time.Clock;
import java.time.Duration;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.Tag;
/**
* The Redis adapter, against a real server under the deployment's advanced account, held to the
* same ownership contract as the fake.
*
* <p>The owner check is Lua on the server; only a real server proves the programs compare what the
* fake's emulation says they compare. Time passes for real here, so the lease is short.
*/
@Tag("redis-topology")
@Tag("lane-standalone")
@Tag("lane-cluster")
class LiveRedisDistributedLeaseContractTest extends DistributedLeaseContract {
private static final RedisNamespace NAMESPACE = new RedisNamespace("prod", "order", "shared");
private RedisRuntimeOwner owner;
@AfterEach
void closeOwner() {
if (owner != null) {
owner.close();
owner = null;
}
}
@Override
protected DistributedLeasePort newPort() {
owner = LiveRedisRuntime.open(NAMESPACE, true);
return new RedisDistributedLeaseAdapter(
owner,
new RedisDistributedLeaseAdapter.LeaseKeys(NAMESPACE, 1),
new LeaseScripts(),
Clock.systemUTC(),
System::nanoTime,
Duration.ofSeconds(2),
Duration.ofMillis(50),
Duration.ZERO);
}
@Override
protected Duration leaseTtl() {
return Duration.ofMillis(400);
}
@Override
protected void elapse(Duration duration) {
try {
Thread.sleep(duration.toMillis());
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
throw new IllegalStateException("interrupted while letting the lease expire", interrupted);
}
}
}
@@ -3,13 +3,14 @@ package dev.caskeleton.adapter.outbound.cache.redis.lease;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.catchThrowable;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.InMemoryGatewayAccess;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.InMemorySemanticRedisCommands;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLane;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.StubRedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.application.lease.LeaseAcquireOutcome;
import dev.caskeleton.application.lease.LeaseAttempt;
import dev.caskeleton.application.lease.LeaseHandle;
@@ -24,7 +25,6 @@ import java.time.Clock;
import java.time.Duration;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.EnumMap;
import java.util.List;
import java.util.Map;
import java.util.concurrent.atomic.AtomicLong;
@@ -56,11 +56,12 @@ class RedisDistributedLeaseAdapterTest {
private static final String OPERATION_B = "operation-bbbbbbbbbb";
private final InMemoryGatewayAccess gateway = InMemoryGatewayAccess.create();
private final InMemorySemanticRedisCommands gateway = new InMemorySemanticRedisCommands();
private final AtomicLong nanos = new AtomicLong();
private final RedisDistributedLeaseAdapter adapter = adapter(new StubClient(gateway.gateway()));
private final RedisDistributedLeaseAdapter adapter =
adapter(StubRedisRuntimeClient.serving(gateway));
private RedisDistributedLeaseAdapter adapter(RedisRuntimeClient client) {
return adapter(client, Duration.ZERO);
@@ -72,7 +73,7 @@ class RedisDistributedLeaseAdapterTest {
private static RedisRuntimeOwner owner(
RedisRuntimeClient client, int connectionsPerLane, Duration acquireTimeout) {
Map<RedisConnectionKind, Integer> limits = new EnumMap<>(RedisConnectionKind.class);
Map<RedisLane, Integer> limits = new java.util.LinkedHashMap<>();
for (RedisConnectionKind kind : RedisConnectionKind.values()) {
limits.put(kind, connectionsPerLane);
}
@@ -83,7 +84,7 @@ class RedisDistributedLeaseAdapterTest {
* An owner with one script connection and almost no patience, so holding it saturates the lane.
*/
private RedisRuntimeOwner narrowOwner() {
return owner(new StubClient(gateway.gateway()), 1, Duration.ofMillis(10));
return owner(StubRedisRuntimeClient.serving(gateway), 1, Duration.ofMillis(10));
}
private RedisDistributedLeaseAdapter adapter(RedisRuntimeOwner owner, Duration driftBudget) {
@@ -179,7 +180,7 @@ class RedisDistributedLeaseAdapterTest {
assertThat(acquired).isInstanceOf(LeaseAcquireOutcome.Acquired.class);
RedisDistributedLeaseAdapter recovering =
adapter(new StubClient(gateway.gateway()), Duration.ofSeconds(2));
adapter(StubRedisRuntimeClient.serving(gateway), Duration.ofSeconds(2));
LeaseInspectionOutcome inspection =
recovering.inspect(new LeaseInspectionRequest(PURPOSE, RESOURCE, attempt));
@@ -374,7 +375,7 @@ class RedisDistributedLeaseAdapterTest {
void aTtlWithinTheDriftBudgetIsRejectedBeforeReachingRedis() {
// given
RedisDistributedLeaseAdapter drifted =
adapter(new StubClient(gateway.gateway()), Duration.ofSeconds(2));
adapter(StubRedisRuntimeClient.serving(gateway), Duration.ofSeconds(2));
LeaseAttempt attempt = drifted.newAttempt(OPERATION_A);
// when
@@ -392,7 +393,7 @@ class RedisDistributedLeaseAdapterTest {
void aTtlWithinTheDriftBudgetLeavesTheResourceFree() {
// given
RedisDistributedLeaseAdapter drifted =
adapter(new StubClient(gateway.gateway()), Duration.ofSeconds(2));
adapter(StubRedisRuntimeClient.serving(gateway), Duration.ofSeconds(2));
LeaseAttempt attempt = drifted.newAttempt(OPERATION_A);
// when
@@ -409,7 +410,7 @@ class RedisDistributedLeaseAdapterTest {
void aRenewTtlWithinTheDriftBudgetIsRejectedBeforeReachingRedis() {
// given
RedisDistributedLeaseAdapter drifted =
adapter(new StubClient(gateway.gateway()), Duration.ofSeconds(2));
adapter(StubRedisRuntimeClient.serving(gateway), Duration.ofSeconds(2));
LeaseHandle handle =
((LeaseAcquireOutcome.Acquired)
drifted.tryAcquire(
@@ -436,36 +437,6 @@ class RedisDistributedLeaseAdapterTest {
assertThat(first.ownerToken()).hasSizeGreaterThanOrEqualTo(16);
}
private record StubClient(RedisCommandGateway gateway) implements RedisRuntimeClient {
@Override
public RedisDeploymentMode mode() {
return RedisDeploymentMode.STANDALONE;
}
@Override
public RedisLaneConnection openLane(
RedisConnectionKind kind, java.util.Optional<byte[]> routingKey) {
return new RedisLaneConnection() {
@Override
public RedisCommandGateway gateway() {
return gateway;
}
@Override
public boolean open() {
return true;
}
@Override
public void close() {}
};
}
@Override
public void close() {}
}
private static final class BrokenClient implements RedisRuntimeClient {
@Override
@@ -474,8 +445,7 @@ class RedisDistributedLeaseAdapterTest {
}
@Override
public RedisLaneConnection openLane(
RedisConnectionKind kind, java.util.Optional<byte[]> routingKey) {
public RedisLaneConnection openLane(RedisLane kind, java.util.Optional<byte[]> routingKey) {
throw new IllegalStateException("the server is unreachable");
}
@@ -0,0 +1,45 @@
package dev.caskeleton.adapter.outbound.cache.redis.lease;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.InMemorySemanticRedisCommands;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.StubRedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.application.lease.DistributedLeasePort;
import dev.caskeleton.application.lease.testkit.DistributedLeaseContract;
import java.time.Clock;
import java.time.Duration;
import java.util.Map;
import java.util.concurrent.atomic.AtomicLong;
/** The Redis adapter, over the runtime's in-memory commands, held to the port's contract. */
class RedisDistributedLeaseContractTest extends DistributedLeaseContract {
private final InMemorySemanticRedisCommands server = new InMemorySemanticRedisCommands();
private final AtomicLong nanos = new AtomicLong();
@Override
protected DistributedLeasePort newPort() {
return new RedisDistributedLeaseAdapter(
new RedisRuntimeOwner(
StubRedisRuntimeClient.serving(server),
Map.of(RedisConnectionKind.REGULAR, 4, RedisConnectionKind.SCRIPT, 4),
Duration.ofSeconds(1),
Duration.ofSeconds(1)),
new RedisDistributedLeaseAdapter.LeaseKeys(
new RedisNamespace("prod", "ca-skeleton", "shared"), 1),
new LeaseScripts(),
Clock.systemUTC(),
nanos::get,
Duration.ofSeconds(2),
Duration.ofMillis(50),
Duration.ZERO);
}
@Override
protected void elapse(Duration duration) {
server.advance(duration);
nanos.addAndGet(duration.toNanos());
}
}
@@ -1,4 +1,4 @@
package dev.caskeleton.shared.ratelimit;
package dev.caskeleton.adapter.outbound.cache.redis.ratelimit;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
@@ -1,8 +1,9 @@
package dev.caskeleton.shared.ratelimit;
package dev.caskeleton.adapter.outbound.cache.redis.ratelimit;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.shared.ratelimit.RateParameters;
import java.time.Duration;
import org.junit.jupiter.api.Test;
@@ -2,26 +2,22 @@ package dev.caskeleton.adapter.outbound.cache.redis.ratelimit;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.InMemoryGatewayAccess;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.shared.ratelimit.RateLimitAlgorithm;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.InMemorySemanticRedisCommands;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLane;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.StubRedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import dev.caskeleton.shared.ratelimit.RateLimitDecision;
import dev.caskeleton.shared.ratelimit.RateLimitEvaluationDedupPolicy;
import dev.caskeleton.shared.ratelimit.RateLimitFailurePolicy;
import dev.caskeleton.shared.ratelimit.RateLimitOutcome;
import dev.caskeleton.shared.ratelimit.RateLimitPolicy;
import dev.caskeleton.shared.ratelimit.RateLimitRequest;
import dev.caskeleton.shared.ratelimit.RateParameters;
import java.time.Clock;
import java.time.Duration;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.EnumMap;
import java.util.Map;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
@@ -47,18 +43,18 @@ class RedisEdgeRateLimitAdapterTest {
private static final String EVALUATION_ID = "ev1:AAAAAAAAAAAAAAAAAAAAAA";
private final InMemoryGatewayAccess gateway = InMemoryGatewayAccess.create();
private final InMemorySemanticRedisCommands gateway = new InMemorySemanticRedisCommands();
private final RateLimitKeys keys =
new RateLimitKeys(new RedisNamespace("prod", "ca-skeleton", "shared"), 1);
private RedisEdgeRateLimitAdapter adapter(RateLimitPolicy policy, Clock clock) {
return adapter(policy, clock, new StubClient(gateway.gateway()));
return adapter(policy, clock, StubRedisRuntimeClient.serving(gateway));
}
private RedisEdgeRateLimitAdapter adapter(
RateLimitPolicy policy, Clock clock, RedisRuntimeClient client) {
Map<RedisConnectionKind, Integer> limits = new EnumMap<>(RedisConnectionKind.class);
Map<RedisLane, Integer> limits = new java.util.LinkedHashMap<>();
for (RedisConnectionKind kind : RedisConnectionKind.values()) {
limits.put(kind, 4);
}
@@ -269,35 +265,6 @@ class RedisEdgeRateLimitAdapterTest {
}
/** Hands out the shared in-memory gateway; the owner's pooling makes it one logical server. */
private record StubClient(RedisCommandGateway gateway) implements RedisRuntimeClient {
@Override
public RedisDeploymentMode mode() {
return RedisDeploymentMode.STANDALONE;
}
@Override
public RedisLaneConnection openLane(
RedisConnectionKind kind, java.util.Optional<byte[]> routingKey) {
return new RedisLaneConnection() {
@Override
public RedisCommandGateway gateway() {
return gateway;
}
@Override
public boolean open() {
return true;
}
@Override
public void close() {}
};
}
@Override
public void close() {}
}
/** A server that cannot be reached at all. */
private static final class BrokenClient implements RedisRuntimeClient {
@@ -308,8 +275,7 @@ class RedisEdgeRateLimitAdapterTest {
}
@Override
public RedisLaneConnection openLane(
RedisConnectionKind kind, java.util.Optional<byte[]> routingKey) {
public RedisLaneConnection openLane(RedisLane kind, java.util.Optional<byte[]> routingKey) {
throw new IllegalStateException("the server is unreachable");
}
@@ -580,8 +580,8 @@ holder 가 락을 잡을 수 있다.
`spring.jpa.open-in-view`가 암묵 기본값일 때 WARN 만 찍을 뿐 명시적으로 `true`로 설정한 배포는
막지 못한다. WARN 은 놓치기 쉬우므로, resolved 값이 `true`면 운영자가 실제 설정한
`APP_DATASOURCE_OPEN_IN_VIEW` 키를 메시지에 담아 부팅을 실패시킨다.
- **읽기만 하고 re-bind 하지 않으며, 부재 값은 Spring 기본에 맡긴다.** `SmartInitializingSingleton`
으로 한 번만 검사하고, 값이 *없으면* Spring Boot 기본(이 스켈레톤은 `application.yml`에서 OSIV off
- **읽기만 하고 re-bind 하지 않으며, 부재 값은 Spring 기본에 맡긴다.** `StartupRule`로 위반만
돌려주고 support의 `StartupRuleRunner`가 모든 싱글톤 생성 후 한 번 실행하며, 값이 *없으면* Spring Boot 기본(이 스켈레톤은 `application.yml`에서 OSIV off
가 기본)에 맡기며 *있는 `true`*만 거부한다.
### JpaDangerousConfigurationGuard (ddl-auto)
@@ -2,55 +2,53 @@ package dev.caskeleton.adapter.outbound.persistence.startup;
import dev.caskeleton.adapter.outbound.support.runtime.RuntimeProfileSnapshot;
import dev.caskeleton.adapter.outbound.support.startup.StartupPhase;
import dev.caskeleton.adapter.outbound.support.startup.StartupValidationContext;
import org.springframework.beans.factory.SmartInitializingSingleton;
import dev.caskeleton.adapter.outbound.support.startup.StartupRule;
import java.util.ArrayList;
import java.util.List;
import org.springframework.core.env.Environment;
/**
* Keeps the Flyway prod safety nets on; raises PROFILE_MISMATCH (exit 71) when an override
* re-enables a forbidden option. See README for the design rationale.
*/
class FlywayProdSafetyValidator implements SmartInitializingSingleton {
class FlywayProdSafetyValidator implements StartupRule {
static final String BASELINE_ON_MIGRATE_KEY = "spring.flyway.baseline-on-migrate";
static final String OUT_OF_ORDER_KEY = "spring.flyway.out-of-order";
static final String CLEAN_DISABLED_KEY = "spring.flyway.clean-disabled";
private final Environment environment;
public FlywayProdSafetyValidator(Environment environment) {
this.environment = environment;
@Override
public StartupPhase phase() {
return StartupPhase.PROFILE_CHECK;
}
@Override
public void afterSingletonsInstantiated() {
public String summary() {
return "prod profile forbids these Flyway options (feature-migration-startup-contract D2/D4)";
}
@Override
public String remedy() {
return "partial-schema recovery goes through runbook://migration/manual-recovery, never an"
+ " in-prod Flyway repair.";
}
@Override
public List<String> violations(Environment environment) {
if (!RuntimeProfileSnapshot.from(environment).isProduction()) {
return;
return List.of();
}
StartupValidationContext violations =
StartupValidationContext.forPhase(StartupPhase.PROFILE_CHECK);
if (isTrue(BASELINE_ON_MIGRATE_KEY)) {
violations.reject(
BASELINE_ON_MIGRATE_KEY + "=true (removes the missing-migration safety net)");
List<String> violations = new ArrayList<>();
if (Boolean.parseBoolean(environment.getProperty(BASELINE_ON_MIGRATE_KEY))) {
violations.add(BASELINE_ON_MIGRATE_KEY + "=true (removes the missing-migration safety net)");
}
if (isTrue(OUT_OF_ORDER_KEY)) {
violations.reject(OUT_OF_ORDER_KEY + "=true (breaks migration ordering consistency)");
if (Boolean.parseBoolean(environment.getProperty(OUT_OF_ORDER_KEY))) {
violations.add(OUT_OF_ORDER_KEY + "=true (breaks migration ordering consistency)");
}
if (isFalse(CLEAN_DISABLED_KEY)) {
violations.reject(CLEAN_DISABLED_KEY + "=false (re-arms destructive Flyway clean)");
String cleanDisabled = environment.getProperty(CLEAN_DISABLED_KEY);
if (cleanDisabled != null && "false".equalsIgnoreCase(cleanDisabled.trim())) {
violations.add(CLEAN_DISABLED_KEY + "=false (re-arms destructive Flyway clean)");
}
violations.failIfViolated(
"prod profile forbids these Flyway options (feature-migration-startup-contract D2/D4)",
"partial-schema recovery goes through runbook://migration/manual-recovery, never an"
+ " in-prod Flyway repair.");
}
private boolean isTrue(String key) {
return Boolean.parseBoolean(environment.getProperty(key));
}
private boolean isFalse(String key) {
String value = environment.getProperty(key);
return value != null && "false".equalsIgnoreCase(value.trim());
return violations;
}
}
@@ -1,19 +1,19 @@
package dev.caskeleton.adapter.outbound.persistence.startup;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailures;
import dev.caskeleton.adapter.outbound.support.startup.StartupPhase;
import dev.caskeleton.adapter.outbound.support.startup.StartupRule;
import dev.caskeleton.adapter.outbound.support.startup.StartupValidationContext;
import java.time.temporal.ChronoUnit;
import org.springframework.beans.factory.SmartInitializingSingleton;
import java.util.List;
import org.springframework.boot.convert.DurationStyle;
import org.springframework.core.env.Environment;
/**
* Fail-fast startup guard for HikariCP inter-knob constraints. Reads (never re-binds) resolved
* Spring properties as a {@link SmartInitializingSingleton}; an absent property is skipped. See
* README for the design rationale.
* Spring properties as a {@link StartupRule}; an absent property is skipped. See README for the
* design rationale.
*/
class HikariPoolConstraintValidator implements SmartInitializingSingleton {
class HikariPoolConstraintValidator implements StartupRule {
static final String CONNECTION_TIMEOUT_KEY = "spring.datasource.hikari.connection-timeout";
static final String VALIDATION_TIMEOUT_KEY = "spring.datasource.hikari.validation-timeout";
@@ -29,14 +29,18 @@ class HikariPoolConstraintValidator implements SmartInitializingSingleton {
static final String MAX_LIFETIME_ENV_KEY = "APP_DATASOURCE_POOL_MAX_LIFETIME";
static final String ENV_KEY_PENDING = "env key pending feature-env-driven-runtime-configuration";
private final Environment environment;
public HikariPoolConstraintValidator(Environment environment) {
this.environment = environment;
@Override
public StartupPhase phase() {
return StartupPhase.ENV_VALIDATION;
}
@Override
public void afterSingletonsInstantiated() {
public String summary() {
return "invalid HikariCP configuration (feature-database-connection-pool-contract D2/D4/D5/D7)";
}
@Override
public List<String> violations(Environment environment) {
StartupValidationContext violations =
StartupValidationContext.forPhase(StartupPhase.ENV_VALIDATION);
@@ -56,14 +60,17 @@ class HikariPoolConstraintValidator implements SmartInitializingSingleton {
}
Long connectionTimeout =
parseMillis(CONNECTION_TIMEOUT_KEY, environment.getProperty(CONNECTION_TIMEOUT_KEY));
parseMillis(
CONNECTION_TIMEOUT_KEY, environment.getProperty(CONNECTION_TIMEOUT_KEY), violations);
Long validationTimeout =
parseMillis(VALIDATION_TIMEOUT_KEY, environment.getProperty(VALIDATION_TIMEOUT_KEY));
parseMillis(
VALIDATION_TIMEOUT_KEY, environment.getProperty(VALIDATION_TIMEOUT_KEY), violations);
Long keepaliveTime =
parseMillis(KEEPALIVE_TIME_KEY, environment.getProperty(KEEPALIVE_TIME_KEY));
Long maxLifetime = parseMillis(MAX_LIFETIME_KEY, environment.getProperty(MAX_LIFETIME_KEY));
parseMillis(KEEPALIVE_TIME_KEY, environment.getProperty(KEEPALIVE_TIME_KEY), violations);
Long maxLifetime =
parseMillis(MAX_LIFETIME_KEY, environment.getProperty(MAX_LIFETIME_KEY), violations);
Long leakDetection =
parseMillis(LEAK_DETECTION_KEY, environment.getProperty(LEAK_DETECTION_KEY));
parseMillis(LEAK_DETECTION_KEY, environment.getProperty(LEAK_DETECTION_KEY), violations);
if (connectionTimeout != null && connectionTimeout < 250L) {
violations.reject(
@@ -120,28 +127,30 @@ class HikariPoolConstraintValidator implements SmartInitializingSingleton {
+ leakDetection);
}
violations.failIfViolated(
"invalid HikariCP configuration (feature-database-connection-pool-contract D2/D4/D5/D7)");
return violations.violations();
}
/**
* Parses the same plain-millisecond, simple Duration ({@code 5s}) and ISO-8601 ({@code PT5S})
* syntax that Spring Boot accepts for Duration-bound properties. A present invalid value is a
* startup error, never an absent-property fallback.
* startup error, never an absent-property fallback: it is recorded as a violation, and the
* constraints that would read it are skipped.
*
* @return the parsed milliseconds, or {@code null} when absent
*/
private static Long parseMillis(String propertyKey, String raw) {
private static Long parseMillis(
String propertyKey, String raw, StartupValidationContext violations) {
if (raw == null || raw.isBlank()) {
return null;
}
try {
return DurationStyle.detectAndParse(raw.trim(), ChronoUnit.MILLIS).toMillis();
} catch (IllegalArgumentException | ArithmeticException e) {
throw StartupFailures.envValidation(
violations.reject(
propertyKey
+ " must be a valid duration (plain milliseconds, simple duration such as 5s, "
+ "or ISO-8601 such as PT5S)");
return null;
}
}
}
@@ -58,36 +58,34 @@ class JpaStartupAutoConfiguration {
/** Env-validation (exit 78): datasource connection env present before migration runs. */
@Bean
RequiredEnvironmentValidator requiredEnvironmentValidator(Environment environment) {
return new RequiredEnvironmentValidator(environment);
RequiredEnvironmentValidator requiredEnvironmentValidator() {
return new RequiredEnvironmentValidator();
}
/** Profile check (exit 71): forbidden Flyway options stay off under the prod profile. */
@Bean
FlywayProdSafetyValidator flywayProdSafetyValidator(Environment environment) {
return new FlywayProdSafetyValidator(environment);
FlywayProdSafetyValidator flywayProdSafetyValidator() {
return new FlywayProdSafetyValidator();
}
@Bean
OpenInViewSafetyValidator openInViewSafetyValidator(Environment environment) {
return new OpenInViewSafetyValidator(environment);
OpenInViewSafetyValidator openInViewSafetyValidator() {
return new OpenInViewSafetyValidator();
}
@Bean
PostgreSqlTransportSecurityValidator postgreSqlTransportSecurityValidator(
Environment environment) {
return new PostgreSqlTransportSecurityValidator(environment);
PostgreSqlTransportSecurityValidator postgreSqlTransportSecurityValidator() {
return new PostgreSqlTransportSecurityValidator();
}
@Bean
PersistenceVendorProdSafetyValidator persistenceVendorProdSafetyValidator(
Environment environment) {
return new PersistenceVendorProdSafetyValidator(environment);
PersistenceVendorProdSafetyValidator persistenceVendorProdSafetyValidator() {
return new PersistenceVendorProdSafetyValidator();
}
@Bean
HikariPoolConstraintValidator hikariPoolConstraintValidator(Environment environment) {
return new HikariPoolConstraintValidator(environment);
HikariPoolConstraintValidator hikariPoolConstraintValidator() {
return new HikariPoolConstraintValidator();
}
/** The datasource product and version validator. */
@@ -1,7 +1,8 @@
package dev.caskeleton.adapter.outbound.persistence.startup;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailures;
import org.springframework.beans.factory.SmartInitializingSingleton;
import dev.caskeleton.adapter.outbound.support.startup.StartupPhase;
import dev.caskeleton.adapter.outbound.support.startup.StartupRule;
import java.util.List;
import org.springframework.core.env.Environment;
/**
@@ -10,32 +11,35 @@ import org.springframework.core.env.Environment;
* to Spring Boot's default and only a present {@code true} is rejected. See README for the design
* rationale.
*/
class OpenInViewSafetyValidator implements SmartInitializingSingleton {
class OpenInViewSafetyValidator implements StartupRule {
static final String OPEN_IN_VIEW_KEY = "spring.jpa.open-in-view";
static final String ENV_KEY = "APP_DATASOURCE_OPEN_IN_VIEW";
private final Environment environment;
public OpenInViewSafetyValidator(Environment environment) {
this.environment = environment;
@Override
public StartupPhase phase() {
return StartupPhase.ENV_VALIDATION;
}
@Override
public void afterSingletonsInstantiated() {
public String summary() {
return ENV_KEY
+ " ("
+ OPEN_IN_VIEW_KEY
+ ") must be false (feature-persistence-failure-baseline D2 — OSIV off baseline)";
}
@Override
public List<String> violations(Environment environment) {
Boolean openInView = environment.getProperty(OPEN_IN_VIEW_KEY, Boolean.class);
if (Boolean.TRUE.equals(openInView)) {
throw StartupFailures.envValidation(
ENV_KEY
+ " ("
+ OPEN_IN_VIEW_KEY
+ ") must be false "
+ "(feature-persistence-failure-baseline D2 — OSIV off baseline): "
+ "open-in-view keeps the Hibernate session open through view rendering, "
+ "so a lazy association touched in the presentation layer issues a DB query "
+ "there, violating the layer boundary. Set "
+ ENV_KEY
+ "=false.");
if (!Boolean.TRUE.equals(openInView)) {
return List.of();
}
return List.of(
"open-in-view keeps the Hibernate session open through view rendering, "
+ "so a lazy association touched in the presentation layer issues a DB query "
+ "there, violating the layer boundary. Set "
+ ENV_KEY
+ "=false.");
}
}
@@ -1,9 +1,10 @@
package dev.caskeleton.adapter.outbound.persistence.startup;
import dev.caskeleton.adapter.outbound.support.runtime.RuntimeProfileSnapshot;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailures;
import dev.caskeleton.adapter.outbound.support.startup.StartupPhase;
import dev.caskeleton.adapter.outbound.support.startup.StartupRule;
import java.util.List;
import java.util.Locale;
import org.springframework.beans.factory.SmartInitializingSingleton;
import org.springframework.core.env.Environment;
/**
@@ -30,7 +31,7 @@ import org.springframework.core.env.Environment;
* <p>Scoped to H2 by name rather than asserting "must be PostgreSQL", so a fork that adds a third
* production-grade vendor is not blocked by this validator.
*/
final class PersistenceVendorProdSafetyValidator implements SmartInitializingSingleton {
final class PersistenceVendorProdSafetyValidator implements StartupRule {
static final String VENDOR_KEY = "ca-skeleton.persistence.vendor";
static final String JDBC_URL_KEY = "spring.datasource.url";
@@ -39,32 +40,34 @@ final class PersistenceVendorProdSafetyValidator implements SmartInitializingSin
private static final String H2_VENDOR = "h2";
private static final String H2_URL_PREFIX = "jdbc:h2:";
private final Environment environment;
public PersistenceVendorProdSafetyValidator(Environment environment) {
this.environment = environment;
@Override
public StartupPhase phase() {
return StartupPhase.PROFILE_CHECK;
}
@Override
public void afterSingletonsInstantiated() {
if (!RuntimeProfileSnapshot.from(environment).isProduction()) {
return;
}
public String summary() {
return "prod profile forbids the in-memory local datastore";
}
@Override
public List<String> violations(Environment environment) {
if (!RuntimeProfileSnapshot.from(environment).isProduction()) {
return List.of();
}
String vendor = normalized(environment.getProperty(VENDOR_KEY));
if (H2_VENDOR.equals(vendor)) {
throw StartupFailures.profileMismatch(
return List.of(
"prod profile forbids "
+ VENDOR_KEY
+ "=h2: the H2 composition is the in-memory local datastore and loses every write"
+ " when the process restarts");
}
String jdbcUrl = normalized(environment.getProperty(JDBC_URL_KEY));
// The URL is never echoed back — it can carry credentials, endpoints and database names
// (same reason as PostgreSqlTransportSecurityValidator).
if (jdbcUrl != null && jdbcUrl.startsWith(H2_URL_PREFIX)) {
throw StartupFailures.profileMismatch(
return List.of(
"prod profile forbids an H2 datasource: "
+ JDBC_URL_ENV_KEY
+ " ("
@@ -72,6 +75,7 @@ final class PersistenceVendorProdSafetyValidator implements SmartInitializingSin
+ ") resolves to a jdbc:h2: URL, which is the in-memory local datastore and also"
+ " bypasses the prod PostgreSQL TLS check");
}
return List.of();
}
private static String normalized(String value) {
@@ -1,13 +1,13 @@
package dev.caskeleton.adapter.outbound.persistence.startup;
import dev.caskeleton.adapter.outbound.support.runtime.RuntimeProfileSnapshot;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailures;
import dev.caskeleton.adapter.outbound.support.startup.StartupPhase;
import dev.caskeleton.adapter.outbound.support.startup.StartupRule;
import java.util.ArrayList;
import java.util.List;
import java.util.Locale;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import org.springframework.beans.factory.SmartInitializingSingleton;
import org.springframework.core.env.Environment;
/**
@@ -16,7 +16,7 @@ import org.springframework.core.env.Environment;
* <p>The validator never includes a JDBC URL in its failure because URLs can carry credentials,
* endpoints, and database names.
*/
final class PostgreSqlTransportSecurityValidator implements SmartInitializingSingleton {
final class PostgreSqlTransportSecurityValidator implements StartupRule {
static final String JDBC_URL_KEY = "spring.datasource.url";
static final String JDBC_URL_ENV_KEY = "APP_DATASOURCE_URL";
@@ -27,36 +27,38 @@ final class PostgreSqlTransportSecurityValidator implements SmartInitializingSin
private static final String VERIFY_FULL = "verify-full";
private static final Pattern URL_SSLMODE = Pattern.compile("(?i)(?:[?&])sslmode=([^&]*)");
private final Environment environment;
public PostgreSqlTransportSecurityValidator(Environment environment) {
this.environment = environment;
@Override
public StartupPhase phase() {
return StartupPhase.PROFILE_CHECK;
}
@Override
public void afterSingletonsInstantiated() {
if (!RuntimeProfileSnapshot.from(environment).isProduction()) {
return;
}
public String summary() {
return "prod PostgreSQL transport security is not verified";
}
@Override
public List<String> violations(Environment environment) {
if (!RuntimeProfileSnapshot.from(environment).isProduction()) {
return List.of();
}
String jdbcUrl = environment.getProperty(JDBC_URL_KEY);
if (jdbcUrl == null || !jdbcUrl.trim().toLowerCase(Locale.ROOT).startsWith(POSTGRESQL_PREFIX)) {
return;
return List.of();
}
List<String> urlModes = urlSslModes(jdbcUrl);
String propertyMode = normalized(environment.getProperty(HIKARI_SSLMODE_KEY));
// The first finding only, as before: each one makes the next meaningless.
if (urlModes.size() > 1) {
reject("prod PostgreSQL transport has ambiguous duplicate sslmode declarations");
return List.of("prod PostgreSQL transport has ambiguous duplicate sslmode declarations");
}
String urlMode = urlModes.isEmpty() ? null : urlModes.getFirst();
if (urlMode != null && propertyMode != null && !urlMode.equals(propertyMode)) {
reject("prod PostgreSQL transport has conflicting sslmode declarations");
return List.of("prod PostgreSQL transport has conflicting sslmode declarations");
}
String effectiveMode = propertyMode != null ? propertyMode : urlMode;
if (!VERIFY_FULL.equals(effectiveMode)) {
reject(
return List.of(
"prod PostgreSQL transport requires pgJDBC sslmode=verify-full through "
+ JDBC_URL_ENV_KEY
+ " ("
@@ -64,6 +66,7 @@ final class PostgreSqlTransportSecurityValidator implements SmartInitializingSin
+ ") or "
+ HIKARI_SSLMODE_KEY);
}
return List.of();
}
private static List<String> urlSslModes(String jdbcUrl) {
@@ -78,8 +81,4 @@ final class PostgreSqlTransportSecurityValidator implements SmartInitializingSin
private static String normalized(String value) {
return value == null ? null : value.trim().toLowerCase(Locale.ROOT);
}
private static void reject(String message) {
throw StartupFailures.profileMismatch(message);
}
}
@@ -1,9 +1,9 @@
package dev.caskeleton.adapter.outbound.persistence.startup;
import dev.caskeleton.adapter.outbound.support.startup.StartupPhase;
import dev.caskeleton.adapter.outbound.support.startup.StartupValidationContext;
import dev.caskeleton.adapter.outbound.support.startup.StartupRule;
import java.util.List;
import java.util.Map;
import org.springframework.beans.factory.SmartInitializingSingleton;
import org.springframework.core.env.Environment;
/**
@@ -11,37 +11,36 @@ import org.springframework.core.env.Environment;
* migration fails with an opaque driver error. Absent or blank counts as missing. See README for
* the design rationale.
*/
class RequiredEnvironmentValidator implements SmartInitializingSingleton {
class RequiredEnvironmentValidator implements StartupRule {
/** Spring property key → operator-facing env key (named in the failure message). */
static final Map<String, String> REQUIRED_DATASOURCE_ENV =
Map.of(
"spring.datasource.url", "APP_DATASOURCE_URL",
"spring.datasource.username", "APP_DATASOURCE_USERNAME",
"spring.datasource.driver-class-name", "APP_DATASOURCE_DRIVER");
private final Environment environment;
public RequiredEnvironmentValidator(Environment environment) {
this.environment = environment;
@Override
public StartupPhase phase() {
return StartupPhase.ENV_VALIDATION;
}
@Override
public void afterSingletonsInstantiated() {
StartupValidationContext missing =
StartupValidationContext.forPhase(StartupPhase.ENV_VALIDATION);
public String summary() {
return "required datasource environment is missing or blank — a Flyway migration"
+ " cannot run without it";
}
@Override
public List<String> violations(Environment environment) {
// Sorted for a stable, deterministic message regardless of map iteration order.
REQUIRED_DATASOURCE_ENV.entrySet().stream()
return REQUIRED_DATASOURCE_ENV.entrySet().stream()
.sorted(Map.Entry.comparingByValue())
.forEach(
.filter(
entry -> {
String value = environment.getProperty(entry.getKey());
if (value == null || value.isBlank()) {
missing.reject(entry.getValue() + " (" + entry.getKey() + ")");
}
});
missing.failIfViolated(
"required datasource environment is missing or blank — a Flyway migration"
+ " cannot run without it");
return value == null || value.isBlank();
})
.map(entry -> entry.getValue() + " (" + entry.getKey() + ")")
.toList();
}
}
@@ -4,6 +4,7 @@ import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.support.startup.StartupErrorCode;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailureException;
import dev.caskeleton.adapter.outbound.support.startup.StartupRuleAutoConfiguration;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.assertj.AssertableApplicationContext;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
@@ -21,7 +22,8 @@ import org.springframework.core.env.Environment;
class FlywayProdSafetyValidatorTest {
private final ApplicationContextRunner runner =
new ApplicationContextRunner().withUserConfiguration(ValidatorConfig.class);
new ApplicationContextRunner()
.withUserConfiguration(StartupRuleAutoConfiguration.class, ValidatorConfig.class);
@Test
void prodProfileWithPinnedSafeDefaultsStartsCleanly() {
@@ -110,7 +112,7 @@ class FlywayProdSafetyValidatorTest {
static class ValidatorConfig {
@Bean
FlywayProdSafetyValidator flywayProdSafetyValidator(Environment environment) {
return new FlywayProdSafetyValidator(environment);
return new FlywayProdSafetyValidator();
}
}
}
@@ -4,6 +4,7 @@ import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.support.startup.StartupErrorCode;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailureException;
import dev.caskeleton.adapter.outbound.support.startup.StartupRuleAutoConfiguration;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
import org.springframework.context.annotation.Bean;
@@ -18,7 +19,8 @@ import org.springframework.core.env.Environment;
class HikariPoolConstraintValidatorTest {
private final ApplicationContextRunner runner =
new ApplicationContextRunner().withUserConfiguration(ValidatorConfig.class);
new ApplicationContextRunner()
.withUserConfiguration(StartupRuleAutoConfiguration.class, ValidatorConfig.class);
// --- D2 / HIKARI-CFG-C1: connection-timeout >= 250 ---
@@ -265,7 +267,7 @@ class HikariPoolConstraintValidatorTest {
static class ValidatorConfig {
@Bean
HikariPoolConstraintValidator hikariPoolConstraintValidator(Environment environment) {
return new HikariPoolConstraintValidator(environment);
return new HikariPoolConstraintValidator();
}
}
}
@@ -4,6 +4,7 @@ import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.support.startup.StartupErrorCode;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailureException;
import dev.caskeleton.adapter.outbound.support.startup.StartupRuleAutoConfiguration;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
import org.springframework.context.annotation.Bean;
@@ -19,7 +20,8 @@ import org.springframework.core.env.Environment;
class OpenInViewSafetyValidatorTest {
private final ApplicationContextRunner runner =
new ApplicationContextRunner().withUserConfiguration(ValidatorConfig.class);
new ApplicationContextRunner()
.withUserConfiguration(StartupRuleAutoConfiguration.class, ValidatorConfig.class);
@Test
void openInViewTrueFailsStartupNamingTheAppKey() {
@@ -71,7 +73,7 @@ class OpenInViewSafetyValidatorTest {
static class ValidatorConfig {
@Bean
OpenInViewSafetyValidator openInViewSafetyValidator(Environment environment) {
return new OpenInViewSafetyValidator(environment);
return new OpenInViewSafetyValidator();
}
}
}
@@ -4,6 +4,7 @@ import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.support.startup.StartupErrorCode;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailureException;
import dev.caskeleton.adapter.outbound.support.startup.StartupRuleAutoConfiguration;
import java.io.PrintWriter;
import java.io.StringWriter;
import org.junit.jupiter.api.Test;
@@ -20,7 +21,8 @@ class PersistenceVendorProdSafetyValidatorTest {
private static final String H2_URL = "jdbc:h2:mem:ca_skeleton;MODE=PostgreSQL";
private final ApplicationContextRunner runner =
new ApplicationContextRunner().withUserConfiguration(ValidatorConfig.class);
new ApplicationContextRunner()
.withUserConfiguration(StartupRuleAutoConfiguration.class, ValidatorConfig.class);
@ParameterizedTest
@ValueSource(strings = {"h2", "H2", " h2 "})
@@ -100,7 +102,7 @@ class PersistenceVendorProdSafetyValidatorTest {
@Bean
PersistenceVendorProdSafetyValidator validator(Environment environment) {
return new PersistenceVendorProdSafetyValidator(environment);
return new PersistenceVendorProdSafetyValidator();
}
}
}
@@ -4,6 +4,7 @@ import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.support.startup.StartupErrorCode;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailureException;
import dev.caskeleton.adapter.outbound.support.startup.StartupRuleAutoConfiguration;
import java.io.PrintWriter;
import java.io.StringWriter;
import org.junit.jupiter.api.Test;
@@ -17,7 +18,8 @@ import org.springframework.core.env.Environment;
class PostgreSqlTransportSecurityValidatorTest {
private final ApplicationContextRunner runner =
new ApplicationContextRunner().withUserConfiguration(ValidatorConfig.class);
new ApplicationContextRunner()
.withUserConfiguration(StartupRuleAutoConfiguration.class, ValidatorConfig.class);
@ParameterizedTest
@ValueSource(
@@ -102,7 +104,7 @@ class PostgreSqlTransportSecurityValidatorTest {
@Bean
PostgreSqlTransportSecurityValidator postgreSqlTransportSecurityValidator(
Environment environment) {
return new PostgreSqlTransportSecurityValidator(environment);
return new PostgreSqlTransportSecurityValidator();
}
}
}
@@ -4,6 +4,7 @@ import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.support.startup.StartupErrorCode;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailureException;
import dev.caskeleton.adapter.outbound.support.startup.StartupRuleAutoConfiguration;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.assertj.AssertableApplicationContext;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
@@ -20,7 +21,8 @@ import org.springframework.core.env.Environment;
class RequiredEnvironmentValidatorTest {
private final ApplicationContextRunner runner =
new ApplicationContextRunner().withUserConfiguration(ValidatorConfig.class);
new ApplicationContextRunner()
.withUserConfiguration(StartupRuleAutoConfiguration.class, ValidatorConfig.class);
@Test
void allDatasourceEnvPresentStartsCleanly() {
@@ -80,7 +82,7 @@ class RequiredEnvironmentValidatorTest {
static class ValidatorConfig {
@Bean
RequiredEnvironmentValidator requiredEnvironmentValidator(Environment environment) {
return new RequiredEnvironmentValidator(environment);
return new RequiredEnvironmentValidator();
}
}
}
@@ -1,6 +1,6 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.api;
package dev.caskeleton.adapter.outbound.cache.redis.runtime;
/** Redis deployment topology the SDK is bound to. */
/** Redis deployment topology the runtime's client is bound to. */
public enum RedisDeploymentMode {
/** Single primary, optional replicas, any database index. */
STANDALONE,
@@ -1,4 +1,4 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.cluster;
package dev.caskeleton.adapter.outbound.cache.redis.runtime.cluster;
import java.nio.charset.StandardCharsets;
import java.util.Objects;
@@ -0,0 +1,91 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.command;
import io.lettuce.core.RedisFuture;
import io.lettuce.core.ScriptOutputType;
import io.lettuce.core.SetArgs;
import io.lettuce.core.cluster.api.async.RedisClusterAsyncCommands;
import java.time.Duration;
import java.util.List;
import java.util.Objects;
import java.util.concurrent.CompletionStage;
/**
* {@link SemanticRedisCommands} on a Lettuce connection.
*
* <p>Bound to {@code byte[]} keys and values: rendering and encoding happened in the caller, so
* nothing here can reinterpret a key or pick a codec.
*/
public final class LettuceSemanticRedisCommands implements SemanticRedisCommands {
private static final String OK = "OK";
private final RedisClusterAsyncCommands<byte[], byte[]> commands;
/**
* Creates the commands over a connection's asynchronous surface.
*
* @param commands the standalone or slot-routing asynchronous commands of one connection
*/
public LettuceSemanticRedisCommands(RedisClusterAsyncCommands<byte[], byte[]> commands) {
this.commands = Objects.requireNonNull(commands, "commands must be non-null");
}
@Override
public CompletionStage<byte[]> get(byte[] key) {
return commands.get(key);
}
@Override
public CompletionStage<Boolean> set(
byte[] key, byte[] value, WritePresence presence, Duration ttl) {
Objects.requireNonNull(ttl, "ttl must be non-null");
if (ttl.isZero() || ttl.isNegative()) {
throw new IllegalArgumentException("ttl must be positive");
}
SetArgs arguments =
switch (presence) {
case IF_ABSENT -> new SetArgs().nx();
case IF_PRESENT -> new SetArgs().xx();
case ALWAYS -> new SetArgs();
};
return commands.set(key, value, arguments.px(ttl)).thenApply(OK::equals);
}
@Override
public CompletionStage<byte[]> getAndDelete(byte[] key) {
return commands.getdel(key);
}
@Override
public CompletionStage<Long> incrementBy(byte[] key, long delta) {
return commands.incrby(key, delta);
}
@Override
public CompletionStage<String> ping() {
return commands.ping();
}
@Override
public CompletionStage<String> loadScript(byte[] source) {
return commands.scriptLoad(source);
}
@Override
public CompletionStage<List<Object>> evaluateRegisteredForList(
String digest, byte[] key, List<byte[]> arguments) {
return commands
.<List<Object>>evalsha(
digest, ScriptOutputType.MULTI, new byte[][] {key}, arguments.toArray(byte[][]::new))
.thenApply(reply -> reply == null ? List.of() : reply);
}
@Override
public CompletionStage<Long> evaluateRegisteredForLong(
String digest, byte[] key, List<byte[]> arguments) {
RedisFuture<Long> reply =
commands.evalsha(
digest, ScriptOutputType.INTEGER, new byte[][] {key}, arguments.toArray(byte[][]::new));
return reply;
}
}
@@ -0,0 +1,96 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.command;
import java.time.Duration;
import java.util.List;
import java.util.concurrent.CompletionStage;
/**
* The commands the runtime's own consumers send: the semantic adapters in {@code cache-redis} and
* the health contributor.
*
* <p>Eight commands and no more. The runtime used to hand every lane a gateway carrying the typed
* SDK's whole surface — about 118 commands, raw and admin paths included — so a leaf that needed a
* cache read and a script call compiled against streams, geo and cluster admin. The rest of that
* surface is the typed SDK's own ({@code redis-sdk}), which extends this interface rather than the
* runtime carrying it on the SDK's behalf.
*
* <p>Keys and values are already rendered and encoded. Nothing here picks a codec or a key.
*/
public interface SemanticRedisCommands {
/**
* Reads a value.
*
* @param key the rendered key
* @return the stored bytes, {@code null} when the key does not exist
*/
CompletionStage<byte[]> get(byte[] key);
/**
* Writes a value with an existence condition and a relative expiry, as one command.
*
* @param key the rendered key
* @param value the encoded value
* @param presence the existence condition
* @param ttl the positive time to live the write carries
* @return whether the write was applied
*/
CompletionStage<Boolean> set(byte[] key, byte[] value, WritePresence presence, Duration ttl);
/**
* Reads and removes a value as one command.
*
* @param key the rendered key
* @return the removed bytes, {@code null} when the key did not exist
*/
CompletionStage<byte[]> getAndDelete(byte[] key);
/**
* Increments an integer counter without touching its expiry.
*
* @param key the rendered key
* @param delta the increment
* @return the value after the increment
*/
CompletionStage<Long> incrementBy(byte[] key, long delta);
/**
* Sends a keyless liveness round trip.
*
* <p>Keyless on purpose: a probe that touched a key would be subject to the ACL key pattern and
* report "unhealthy" for reasons that have nothing to do with reachability.
*
* @return the server's reply
*/
CompletionStage<String> ping();
/**
* Registers a script and returns its digest.
*
* @param source the script source
* @return the digest the server assigned
*/
CompletionStage<String> loadScript(byte[] source);
/**
* Evaluates a registered single-key script whose reply is an array.
*
* @param digest the loaded script digest
* @param key the single key the script touches
* @param arguments the script arguments
* @return the reply values
*/
CompletionStage<List<Object>> evaluateRegisteredForList(
String digest, byte[] key, List<byte[]> arguments);
/**
* Evaluates a registered single-key script whose reply is an integer.
*
* @param digest the loaded script digest
* @param key the single key the script touches
* @param arguments the script arguments
* @return the integer reply
*/
CompletionStage<Long> evaluateRegisteredForLong(
String digest, byte[] key, List<byte[]> arguments);
}
@@ -1,4 +1,4 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations;
package dev.caskeleton.adapter.outbound.cache.redis.runtime.command;
/**
* The existence condition a {@code SET} carries.
@@ -0,0 +1,30 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.config;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisAccount;
import java.util.Objects;
/**
* An account another module's lanes authenticate as, and where its credential comes from.
*
* <p>Declared as a bean by the module (or the service) that composes the lanes. {@link
* RedisRuntimeAutoConfiguration} resolves the reference through the same secret source as its own
* accounts, before any client exists, and builds a client authenticated as it. A reference that
* does not resolve fails startup rather than the first command.
*
* @param account the account
* @param credentialReference the credential reference, in the runtime's {@code secret://} form
*/
public record RedisAccountContribution(RedisAccount account, String credentialReference) {
public RedisAccountContribution {
Objects.requireNonNull(account, "account must be non-null");
if (RedisAccount.APPLICATION.equals(account) || RedisAccount.ADVANCED.equals(account)) {
throw new IllegalArgumentException(
"the " + account + " account is the runtime's own and is configured in app.redis");
}
if (credentialReference == null || credentialReference.isBlank()) {
throw new IllegalArgumentException(
"the " + account + " account needs a credential reference");
}
}
}
@@ -0,0 +1,30 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.config;
import org.springframework.core.env.Environment;
/**
* A module's answer to "does this deployment need Redis for correctness?".
*
* <p>Registered under this interface's name in {@code META-INF/spring.factories} by the module that
* owns the roles, and read through {@link RedisCorrectnessRoles}. Implementations need a public
* no-argument constructor and must decide from the environment alone: they run before any bean
* exists.
*/
public interface RedisCorrectnessRequirement {
/**
* Reports whether a role this module owns selected Redis for correctness.
*
* @param environment the resolved environment
* @return {@code true} when readiness must gate on Redis
*/
boolean required(Environment environment);
/**
* Reports whether such a role runs registered scripts on the SCRIPT lane.
*
* @param environment the resolved environment
* @return {@code true} when the SCRIPT lane carries a correctness role
*/
boolean requiresScriptLane(Environment environment);
}
@@ -0,0 +1,65 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.config;
import java.util.List;
import org.springframework.core.env.Environment;
import org.springframework.core.io.support.SpringFactoriesLoader;
/**
* Whether this deployment needs Redis for <em>correctness</em> rather than for speed.
*
* <p>A role such as idempotency or rate limiting produces a wrong answer when Redis is gone, not a
* slow one, so a deployment that selected one gates its readiness on Redis. A cache does not — its
* outage is degradation.
*
* <p>The runtime does not know which roles exist or how they are selected: that belongs to the
* modules that implement them (for the semantic ports, {@code cache-redis}). Each such module
* registers a {@link RedisCorrectnessRequirement} in {@code META-INF/spring.factories}, and this
* class only asks them. Environment post-processors run before any bean exists, and the readiness
* group must be decided there, so a factories entry rather than a bean is the one mechanism both
* readers can use.
*
* <p>The question is asked in two places that must never disagree: the condition that creates the
* {@code redisRequired} contributor, and the post-processor that lets the readiness group name it.
* When those drifted apart every Redis-off deployment failed at startup with {@code Included health
* contributor 'redisRequired' in group 'readiness' does not exist}. One predicate, two readers.
*/
public final class RedisCorrectnessRoles {
/** The bean name of the readiness-gating health contributor. */
public static final String REQUIRED_HEALTH_CONTRIBUTOR = "redisRequired";
/** The bean name of the degradation-only health contributor. */
public static final String OPTIONAL_HEALTH_CONTRIBUTOR = "redisOptional";
private RedisCorrectnessRoles() {
throw new AssertionError("RedisCorrectnessRoles is a constant holder");
}
/**
* Reports whether any registered module needs Redis for correctness in this environment.
*
* @param environment the resolved environment
* @return {@code true} when readiness must gate on Redis
*/
public static boolean anySelected(Environment environment) {
return requirements().stream().anyMatch(requirement -> requirement.required(environment));
}
/**
* Reports whether a correctness role that runs registered scripts is selected, so the SCRIPT lane
* — which authenticates as the advanced account — has to be probed as well.
*
* @param environment the resolved environment
* @return {@code true} when the SCRIPT lane carries a correctness role
*/
public static boolean anyScriptRoleSelected(Environment environment) {
return requirements().stream()
.anyMatch(requirement -> requirement.requiresScriptLane(environment));
}
private static List<RedisCorrectnessRequirement> requirements() {
return SpringFactoriesLoader.forDefaultResourceLocation(
RedisCorrectnessRoles.class.getClassLoader())
.load(RedisCorrectnessRequirement.class);
}
}
@@ -1,4 +1,4 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.config;
package dev.caskeleton.adapter.outbound.cache.redis.runtime.config;
import java.util.Objects;
import java.util.Optional;
@@ -1,9 +1,9 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.config;
package dev.caskeleton.adapter.outbound.cache.redis.runtime.config;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.error.RedisCommandRejectedException;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisLease;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLaneUnavailableException;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLease;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.LinkedHashMap;
@@ -87,25 +87,25 @@ public final class RedisHealthContributor {
// A round trip, not a flag. `isOpen()` on a driver connection reports what the client
// believes, which stays true for as long as it takes TCP to notice — the window in which a
// health check is most likely to be wrong is exactly the window it exists to catch.
reply = lease.gateway().ping().toCompletableFuture().get(nanos(), TimeUnit.NANOSECONDS);
reply = lease.commands().ping().toCompletableFuture().get(nanos(), TimeUnit.NANOSECONDS);
}
if (scriptProbeKey.isPresent()) {
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
String digest =
lease
.gateway()
.commands()
.loadScript(SCRIPT_PROBE)
.toCompletableFuture()
.get(nanos(), TimeUnit.NANOSECONDS);
lease
.gateway()
.commands()
.evaluateRegisteredForLong(digest, scriptProbeKey.get(), List.of())
.toCompletableFuture()
.get(nanos(), TimeUnit.NANOSECONDS);
}
}
return new RedisHealth(true, detail("reachable", String.valueOf(reply)));
} catch (RedisCommandRejectedException refused) {
} catch (RedisLaneUnavailableException refused) {
// A refusal is raised before any command exists: either shutdown began, or the lane is full.
return owner.state() != RedisRuntimeOwner.State.OPEN
? shuttingDown()
@@ -0,0 +1,25 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.config;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLane;
import java.util.Objects;
/**
* A lane another module composes on the runtime, and its connection ceiling.
*
* <p>Declared as a bean by the module (or the service) that uses the lane; {@link
* RedisRuntimeAutoConfiguration} pools and drains it with the runtime's own lanes. The runtime
* knows nothing about a contributed lane beyond its account and ceiling.
*
* @param lane the lane
* @param maximumConnections how many connections the lane may hold at once
*/
public record RedisLaneContribution(RedisLane lane, int maximumConnections) {
public RedisLaneContribution {
Objects.requireNonNull(lane, "lane must be non-null");
if (maximumConnections < 1) {
throw new IllegalArgumentException(
"connection lane " + lane.name() + " needs a positive ceiling");
}
}
}
@@ -1,13 +1,14 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.config;
package dev.caskeleton.adapter.outbound.cache.redis.runtime.config;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisCredentialRole;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisTopologyClientFactory;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisAccount;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLane;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeClient;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisTopologyClientFactory;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
import java.nio.charset.StandardCharsets;
import java.util.EnumMap;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Optional;
@@ -34,7 +35,7 @@ import org.springframework.core.type.AnnotatedTypeMetadata;
* The Redis composition root, and the only place Redis settings come into existence.
*
* <p>{@code app.redis.enabled} is the whole switch. While it is false this class contributes
* nothing, and because {@link RedisSdkSettings} is registered here rather than by the
* nothing, and because {@link RedisRuntimeSettings} is registered here rather than by the
* application-wide {@code @ConfigurationPropertiesScan}, "contributes nothing" is literal: the
* properties are not bound, the cross-field rules are not run, no credential is resolved, and no
* policy resource, TLS material, client, connection or thread is created. A deployment that does
@@ -43,7 +44,7 @@ import org.springframework.core.type.AnnotatedTypeMetadata;
*
* <p>While it is true the order is fixed and entirely local: bind, validate, then build. Validation
* runs at context refresh, before anything can reach the network, which is what makes {@link
* RedisSdkSettings#validate()} the fail-fast its own documentation claims — until this class
* RedisRuntimeSettings#validate()} the fail-fast its own documentation claims — until this class
* existed the method had no production caller at all.
*
* <p>Roles — cache, session, idempotency, rate limiting, leases — select <em>which</em> Redis
@@ -56,9 +57,9 @@ import org.springframework.core.type.AnnotatedTypeMetadata;
// Without it the bean is created and silently left at its defaults, which is worse than not
// binding at all: validation would pass on settings nobody configured.
@EnableConfigurationProperties
public class RedisSdkAutoConfiguration {
public class RedisRuntimeAutoConfiguration {
private static final Logger LOG = LoggerFactory.getLogger(RedisSdkAutoConfiguration.class);
private static final Logger LOG = LoggerFactory.getLogger(RedisRuntimeAutoConfiguration.class);
/**
* The status an optional Redis reports when it is unreachable.
@@ -82,15 +83,15 @@ public class RedisSdkAutoConfiguration {
*/
@Bean
@ConfigurationProperties(prefix = "app.redis")
public RedisSdkSettings redisSdkSettings() {
return new RedisSdkSettings();
public RedisRuntimeSettings redisRuntimeSettings() {
return new RedisRuntimeSettings();
}
/**
* Runs the cross-field rules once the binder has populated the settings.
*
* <p>Spring binds {@code @ConfigurationProperties} after the factory method returns, so the
* validation cannot live inside {@link #redisSdkSettings()}. A {@code
* validation cannot live inside {@link #redisRuntimeSettings()}. A {@code
* ConfigurationPropertiesBindHandlerAdvisor}-free way to get the same fail-fast is a bean that
* depends on the settings: it is created during refresh, before any Redis client would be, and an
* exception here stops the context.
@@ -99,10 +100,11 @@ public class RedisSdkAutoConfiguration {
* @return the validation outcome, kept as a bean so warnings are inspectable in tests
*/
@Bean
public RedisSdkSettingsValidation redisSdkSettingsValidation(RedisSdkSettings settings) {
public RedisRuntimeSettingsValidation redisRuntimeSettingsValidation(
RedisRuntimeSettings settings) {
List<String> warnings = settings.validate();
warnings.forEach(warning -> LOG.warn("Redis SDK configuration warning: {}", warning));
return new RedisSdkSettingsValidation(warnings);
warnings.forEach(warning -> LOG.warn("Redis configuration warning: {}", warning));
return new RedisRuntimeSettingsValidation(warnings);
}
/**
@@ -114,58 +116,60 @@ public class RedisSdkAutoConfiguration {
*
* @param settings the validated settings
* @param secretSource resolves a secret name to its value
* @param contributedAccounts accounts a module composing lanes on the runtime asked for
* @param validation ordered after validation so a malformed setting is reported first
* @return the resolved credentials
*/
@Bean
public RedisResolvedCredentials redisResolvedCredentials(
RedisSdkSettings settings,
RedisRuntimeSettings settings,
ObjectProvider<RedisSecretSource> secretSource,
RedisSdkSettingsValidation validation) {
ObjectProvider<RedisAccountContribution> contributedAccounts,
RedisRuntimeSettingsValidation validation) {
RedisCredentialResolver resolver =
new RedisCredentialResolver(
name -> secretSource.getIfAvailable(() -> environmentSecretSource()).resolve(name));
Map<RedisCredentialRole, RedisCredentialResolver.RedisCredentials> accounts =
new EnumMap<>(RedisCredentialRole.class);
// Every configured role is resolved, not only the application one. A deployment that named an
// advanced or pub/sub account and got a client that silently authenticated as the application
// account has the privilege separation it configured on paper and nowhere else.
Map<RedisAccount, RedisCredentialResolver.RedisCredentials> accounts = new LinkedHashMap<>();
// Every configured account is resolved, not only the application one. A deployment that named
// an advanced account and got a client that silently authenticated as the application account
// has the privilege separation it configured on paper and nowhere else.
put(
accounts,
RedisCredentialRole.APPLICATION,
RedisAccount.APPLICATION,
resolver.resolve("application", settings.getAuthentication().getCredentialReference()));
put(
accounts,
RedisCredentialRole.ADVANCED,
RedisAccount.ADVANCED,
resolver.resolve(
"advanced", settings.getAuthentication().getAdvancedCredentialReference()));
put(
accounts,
RedisCredentialRole.PUBSUB,
resolver.resolve("pub/sub", settings.getAuthentication().getPubsubCredentialReference()));
if (settings.getAdmin().isEnabled()) {
put(
accounts,
RedisCredentialRole.ADMIN,
resolver.resolve("admin", settings.getAdmin().getCredentialReference()));
}
// A module that composes lanes on the runtime (the typed SDK's admin plane) names its own
// account; the runtime resolves it exactly like its own, before any client exists.
contributedAccounts
.orderedStream()
.forEach(
contribution ->
put(
accounts,
contribution.account(),
resolver.resolve(
contribution.account().name(), contribution.credentialReference())));
Optional<RedisCredentialResolver.RedisCredentials> sentinel =
settings.getMode()
== dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode.SENTINEL
== dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode.SENTINEL
? resolver.resolve("sentinel", settings.getSentinel().getCredentialReference())
: Optional.empty();
LOG.info(
"Redis accounts resolved for roles {}{}",
"Redis accounts resolved: {}{}",
accounts.keySet(),
sentinel.isPresent() ? " plus the Sentinel control account" : "");
return new RedisResolvedCredentials(accounts, sentinel);
}
private static void put(
Map<RedisCredentialRole, RedisCredentialResolver.RedisCredentials> accounts,
RedisCredentialRole role,
Map<RedisAccount, RedisCredentialResolver.RedisCredentials> accounts,
RedisAccount account,
Optional<RedisCredentialResolver.RedisCredentials> resolved) {
resolved.ifPresent(credentials -> accounts.put(role, credentials));
resolved.ifPresent(credentials -> accounts.put(account, credentials));
}
private static RedisSecretSource environmentSecretSource() {
@@ -183,7 +187,7 @@ public class RedisSdkAutoConfiguration {
*/
@Bean
public RedisRuntimeClient redisRuntimeClient(
RedisSdkSettings settings,
RedisRuntimeSettings settings,
RedisResolvedCredentials credentials,
ResourceLoader resourceLoader) {
return new RedisTopologyClientFactory(
@@ -224,20 +228,33 @@ public class RedisSdkAutoConfiguration {
* <p>Destroyed by Spring, and destroyed before the client bean it wraps because it depends on it
* — which is the order shutdown needs: connections drain and close, then the event loop stops.
*
* <p>The runtime's own lanes take their ceilings from the settings. A module that composes
* further lanes on the runtime contributes their ceilings as {@link RedisLaneContribution} beans;
* the runtime pools and drains those exactly like its own, and knows nothing else about them.
*
* @param client the runtime client
* @param settings the validated settings
* @param contributedLanes lanes other modules compose on the runtime
* @return the lifecycle owner
*/
@Bean(destroyMethod = "close")
public RedisRuntimeOwner redisRuntimeOwner(RedisRuntimeClient client, RedisSdkSettings settings) {
Map<RedisConnectionKind, Integer> limits = new EnumMap<>(RedisConnectionKind.class);
public RedisRuntimeOwner redisRuntimeOwner(
RedisRuntimeClient client,
RedisRuntimeSettings settings,
ObjectProvider<RedisLaneContribution> contributedLanes) {
Map<RedisLane, Integer> limits = new LinkedHashMap<>();
limits.put(RedisConnectionKind.REGULAR, settings.getCapacity().getMaximumInFlightCommands());
limits.put(RedisConnectionKind.BLOCKING, settings.getBlocking().getMaxConnections());
limits.put(RedisConnectionKind.TRANSACTION, settings.getTransaction().getMaxConnections());
limits.put(RedisConnectionKind.SCRIPT, settings.getCapacity().getMaximumScriptConnections());
limits.put(
RedisConnectionKind.PUBSUB, Math.max(1, settings.getPubsub().getBufferCapacity() / 64));
limits.put(RedisConnectionKind.ADMIN, settings.getAdmin().isEnabled() ? 2 : 1);
contributedLanes
.orderedStream()
.forEach(
contribution -> {
if (limits.putIfAbsent(contribution.lane(), contribution.maximumConnections())
!= null) {
throw new IllegalStateException(
"Redis lane " + contribution.lane().name() + " was composed twice");
}
});
return new RedisRuntimeOwner(
client,
limits,
@@ -257,7 +274,7 @@ public class RedisSdkAutoConfiguration {
* @return the contributor
*/
@Bean(RedisCorrectnessRoles.OPTIONAL_HEALTH_CONTRIBUTOR)
public HealthIndicator redisOptional(RedisRuntimeOwner owner, RedisSdkSettings settings) {
public HealthIndicator redisOptional(RedisRuntimeOwner owner, RedisRuntimeSettings settings) {
RedisHealthContributor contributor =
new RedisHealthContributor(owner, settings.getTimeout().getFast());
return () -> {
@@ -291,7 +308,7 @@ public class RedisSdkAutoConfiguration {
@Bean(RedisCorrectnessRoles.REQUIRED_HEALTH_CONTRIBUTOR)
@Conditional(RedisCorrectnessRoleBound.class)
public HealthIndicator redisRequired(
RedisRuntimeOwner owner, RedisSdkSettings settings, Environment environment) {
RedisRuntimeOwner owner, RedisRuntimeSettings settings, Environment environment) {
Optional<byte[]> scriptProbeKey =
RedisCorrectnessRoles.anyScriptRoleSelected(environment)
? Optional.of(
@@ -331,17 +348,17 @@ public class RedisSdkAutoConfiguration {
}
/**
* The account resolved for each role the configuration named.
* The credentials resolved for each account the configuration named.
*
* <p>A role that is absent from {@code accounts} has no account of its own and runs on the
* application client. That is a deployment decision, taken by not configuring one, rather than a
* default the SDK picks.
* <p>An account that is absent from {@code accounts} has no credentials of its own and its lanes
* run on the application client. That is a deployment decision, taken by not configuring one,
* rather than a default the runtime picks.
*
* @param accounts the resolved account per configured role
* @param accounts the resolved credentials per configured account
* @param sentinel the Sentinel control account, on a Sentinel deployment
*/
public record RedisResolvedCredentials(
Map<RedisCredentialRole, RedisCredentialResolver.RedisCredentials> accounts,
Map<RedisAccount, RedisCredentialResolver.RedisCredentials> accounts,
Optional<RedisCredentialResolver.RedisCredentials> sentinel) {
public RedisResolvedCredentials {
@@ -367,9 +384,9 @@ public class RedisSdkAutoConfiguration {
*
* @param warnings settings that are within the guardrails but worth an operator's attention
*/
public record RedisSdkSettingsValidation(List<String> warnings) {
public record RedisRuntimeSettingsValidation(List<String> warnings) {
public RedisSdkSettingsValidation {
public RedisRuntimeSettingsValidation {
warnings = List.copyOf(warnings);
}
}
@@ -1,13 +1,17 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.config;
package dev.caskeleton.adapter.outbound.cache.redis.runtime.config;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisKeyRules;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisKeyRules;
import java.time.Duration;
import java.util.ArrayList;
import java.util.List;
/**
* Typed configuration for the Redis SDK, bound from {@code app.redis.*}.
* Typed configuration for the Redis runtime, bound from {@code app.redis.*}.
*
* <p>Topology, accounts, TLS, lifecycle and the ceilings of the runtime's own lanes. The typed
* SDK's lanes (blocking, transaction, admin) are not configured here: a module that composes lanes
* on the runtime brings their limits and accounts with it.
*
* <p>Defaults are the skeleton guardrails from the design. Validation is fail-closed and runs at
* startup: a setting that would make a guardrail meaningless — a non-zero database on Cluster, an
@@ -15,12 +19,12 @@ import java.util.List;
* degrading quietly at the first request.
*
* <p>This class carries no {@code @ConfigurationProperties} annotation on purpose. It is registered
* and bound only by {@link RedisSdkAutoConfiguration}, which exists only while {@code
* and bound only by {@link RedisRuntimeAutoConfiguration}, which exists only while {@code
* app.redis.enabled} is true. Annotating the class would put it back inside the application-wide
* {@code @ConfigurationPropertiesScan}, and a Redis-free deployment would once again bind Redis
* configuration — the exact defect this arrangement removes.
*/
public class RedisSdkSettings {
public class RedisRuntimeSettings {
/** Hard ceiling above which a configured timeout is a startup failure. */
public static final Duration MAXIMUM_TIMEOUT = Duration.ofSeconds(30);
@@ -34,16 +38,12 @@ public class RedisSdkSettings {
private int database;
private final Namespace namespace = new Namespace();
private final Timeouts timeout = new Timeouts();
private final Blocking blocking = new Blocking();
private final Transaction transaction = new Transaction();
private final Authentication authentication = new Authentication();
private final Sentinel sentinel = new Sentinel();
private final Tls tls = new Tls();
private final Lifecycle lifecycle = new Lifecycle();
private final Cluster cluster = new Cluster();
private final Capacity capacity = new Capacity();
private final PubSub pubsub = new PubSub();
private final Admin admin = new Admin();
/**
* Validates every cross-field rule.
@@ -66,9 +66,6 @@ public class RedisSdkSettings {
validateTimeout("fast", timeout.getFast(), warnings);
validateTimeout("script", timeout.getScript(), warnings);
validateTimeout("batch", timeout.getBatch(), warnings);
if (blocking.getMaxConnections() < 1 || transaction.getMaxConnections() < 1) {
throw new IllegalStateException("dedicated connection lanes need a positive ceiling");
}
if (mode == RedisDeploymentMode.SENTINEL
&& (sentinel.getMasterName() == null || sentinel.getMasterName().isBlank())) {
throw new IllegalStateException(
@@ -95,13 +92,6 @@ public class RedisSdkSettings {
lifecycle.validate();
capacity.validate();
cluster.validate();
pubsub.validate();
if (admin.isEnabled()
&& (admin.getCredentialReference() == null || admin.getCredentialReference().isBlank())) {
throw new IllegalStateException(
"app.redis.admin.credential-reference is required when app.redis.admin.enabled=true: the"
+ " admin plane authenticates as its own account");
}
// Last, deliberately. A deployment with both a structural mistake and a missing credential
// should be told about the structural one first: it is the cheaper thing to be wrong about,
// and reporting "no credential" for a configuration that could never have connected anyway
@@ -194,40 +184,11 @@ public class RedisSdkSettings {
}
}
/** Blocking lane ceilings. */
public static class Blocking {
private int maxConnections = 32;
public int getMaxConnections() {
return maxConnections;
}
public void setMaxConnections(int maxConnections) {
this.maxConnections = maxConnections;
}
}
/** Transaction lane ceilings. */
public static class Transaction {
private int maxConnections = 16;
public int getMaxConnections() {
return maxConnections;
}
public void setMaxConnections(int maxConnections) {
this.maxConnections = maxConnections;
}
}
/** Application authentication material, carried as references rather than values. */
public static class Authentication {
private String credentialReference;
private String advancedCredentialReference;
private String pubsubCredentialReference;
private boolean anonymousAccessAccepted;
void validate(List<String> warnings) {
@@ -289,14 +250,6 @@ public class RedisSdkSettings {
public void setAdvancedCredentialReference(String advancedCredentialReference) {
this.advancedCredentialReference = advancedCredentialReference;
}
public String getPubsubCredentialReference() {
return pubsubCredentialReference;
}
public void setPubsubCredentialReference(String pubsubCredentialReference) {
this.pubsubCredentialReference = pubsubCredentialReference;
}
}
/** Sentinel discovery. */
@@ -545,49 +498,6 @@ public class RedisSdkSettings {
}
}
/** Subscription delivery. */
public static class PubSub {
private int bufferCapacity = 1_024;
void validate() {
if (bufferCapacity < 1) {
throw new IllegalStateException("the pub/sub buffer capacity must be positive");
}
}
public int getBufferCapacity() {
return bufferCapacity;
}
public void setBufferCapacity(int bufferCapacity) {
this.bufferCapacity = bufferCapacity;
}
}
/** Isolated admin plane exposure. */
public static class Admin {
private boolean enabled;
private String credentialReference;
public boolean isEnabled() {
return enabled;
}
public void setEnabled(boolean enabled) {
this.enabled = enabled;
}
public String getCredentialReference() {
return credentialReference;
}
public void setCredentialReference(String credentialReference) {
this.credentialReference = credentialReference;
}
}
public boolean isEnabled() {
return enabled;
}
@@ -628,18 +538,6 @@ public class RedisSdkSettings {
return timeout;
}
public Blocking getBlocking() {
return blocking;
}
public Transaction getTransaction() {
return transaction;
}
public Admin getAdmin() {
return admin;
}
public Authentication getAuthentication() {
return authentication;
}
@@ -663,8 +561,4 @@ public class RedisSdkSettings {
public Capacity getCapacity() {
return capacity;
}
public PubSub getPubsub() {
return pubsub;
}
}
@@ -0,0 +1,66 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import java.util.LinkedHashMap;
import java.util.LinkedHashSet;
import java.util.Map;
import java.util.Optional;
import java.util.Set;
/**
* Routes each lane to the client that authenticated as the lane's account.
*
* <p>Only created when a deployment configured more than one account. Its whole behaviour is a
* lookup: the accounts were decided at composition, and a lane cannot change the account it runs as
* after the connection exists.
*/
final class AccountRoutingRuntimeClient implements RedisRuntimeClient {
private final Map<RedisAccount, RedisRuntimeClient> byAccount;
AccountRoutingRuntimeClient(Map<RedisAccount, RedisRuntimeClient> byAccount) {
this.byAccount = new LinkedHashMap<>(byAccount);
}
@Override
public RedisDeploymentMode mode() {
return byAccount.get(RedisAccount.APPLICATION).mode();
}
@Override
public RedisLaneConnection openLane(RedisLane lane, Optional<byte[]> routingKey) {
return delegate(lane).openLane(lane, routingKey);
}
private RedisRuntimeClient delegate(RedisLane lane) {
RedisRuntimeClient client = byAccount.get(lane.account());
// Falling back to the application account is the documented behaviour of an unconfigured
// account, not a failure: a deployment with one account is the common case.
return client == null ? byAccount.get(RedisAccount.APPLICATION) : client;
}
@Override
public void close() {
// Distinct instances only, and the application client last: it is the one every unconfigured
// account fell back to, so closing it first would tear out lanes still being drained.
Set<RedisRuntimeClient> remaining = new LinkedHashSet<>(byAccount.values());
RedisRuntimeClient application = byAccount.get(RedisAccount.APPLICATION);
remaining.remove(application);
RuntimeException first = null;
for (RedisRuntimeClient client : remaining) {
try {
client.close();
} catch (RuntimeException failure) {
first = first == null ? failure : first;
}
}
try {
application.close();
} catch (RuntimeException failure) {
first = first == null ? failure : first;
}
if (first != null) {
throw first;
}
}
}
@@ -0,0 +1,84 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import static java.util.concurrent.TimeUnit.MILLISECONDS;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.cluster.RedisSlotCalculator;
import io.lettuce.core.api.StatefulRedisConnection;
import io.lettuce.core.cluster.RedisClusterClient;
import io.lettuce.core.cluster.api.StatefulRedisClusterConnection;
import io.lettuce.core.cluster.models.partitions.RedisClusterNode;
import io.lettuce.core.codec.ByteArrayCodec;
import java.nio.charset.StandardCharsets;
import java.util.Optional;
/** Cluster: lanes route by slot, a lane pinned to its key's owner runs on that node alone. */
final class ClusterRuntimeClient implements RedisRuntimeClient {
private static final RedisSlotCalculator SLOTS = new RedisSlotCalculator();
private final RedisClusterClient client;
private final SharedClientResources resources;
private final ShutdownBudget shutdown;
ClusterRuntimeClient(
RedisClusterClient client, SharedClientResources resources, ShutdownBudget shutdown) {
this.client = client;
this.resources = resources;
this.shutdown = shutdown;
}
@Override
public RedisDeploymentMode mode() {
return RedisDeploymentMode.CLUSTER;
}
@Override
public RedisLaneConnection openLane(RedisLane lane, Optional<byte[]> routingKey) {
StatefulRedisClusterConnection<byte[], byte[]> connection =
client.connect(ByteArrayCodec.INSTANCE);
if (!lane.pinnedToKeyOwner()) {
return new LaneConnection(
connection, RedisDriverConnection.slotRouting(connection.async()), connection::isOpen);
}
try {
// A Cluster transaction runs on one node. The slot-routing connection cannot own the window
// — its queued commands would be spread across nodes — so the lane is pinned to the node
// that owns the routing key's slot, and every key in the window is proved to share that slot
// before anything is queued.
byte[] key =
routingKey.orElseThrow(
() ->
new IllegalStateException(
"a Cluster lane pinned to its key's owner needs a routing key: the window"
+ " runs on one node, and which node that is can only be decided from a"
+ " key or an explicit slot tag."));
int slot = SLOTS.applyAsInt(new String(key, StandardCharsets.UTF_8));
RedisClusterNode owner = client.getPartitions().getMasterBySlot(slot);
if (owner == null) {
throw new IllegalStateException(
"no Cluster node currently owns slot "
+ slot
+ "; the topology is incomplete and a transaction opened against it would run"
+ " somewhere the keys do not live");
}
StatefulRedisConnection<byte[], byte[]> node = connection.getConnection(owner.getNodeId());
// The parent is closed on release; closing it releases the node connection with it.
return new LaneConnection(
connection, RedisDriverConnection.singleNode(node.async()), node::isOpen);
} catch (RuntimeException failure) {
connection.close();
throw failure;
}
}
@Override
public void close() {
try {
client.shutdown(
shutdown.quietPeriod().toMillis(), shutdown.timeout().toMillis(), MILLISECONDS);
} finally {
resources.release(shutdown);
}
}
}
@@ -0,0 +1,37 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.LettuceSemanticRedisCommands;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import java.util.function.BooleanSupplier;
/**
* One open connection: what closes it, what runs over it, and how to ask whether it still works.
*
* @param connection what {@link #close()} closes — on a pinned Cluster lane the parent connection,
* which releases the node connection with it
* @param driver the driver surface commands are sent on
* @param openCheck whether the driver still reports the connection open
*/
record LaneConnection(
AutoCloseable connection, RedisDriverConnection driver, BooleanSupplier openCheck)
implements RedisRuntimeClient.RedisLaneConnection {
@Override
public SemanticRedisCommands commands() {
return new LettuceSemanticRedisCommands(driver.commands());
}
@Override
public boolean open() {
return openCheck.getAsBoolean();
}
@Override
public void close() {
try {
connection.close();
} catch (Exception failure) {
throw new IllegalStateException("a Redis lane connection could not be closed", failure);
}
}
}
@@ -0,0 +1,46 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import java.util.Objects;
import java.util.regex.Pattern;
/**
* The Redis account a connection authenticates as.
*
* <p>Redis ACLs authenticate a named user, and the privileges that user carries are the only
* privileges the connection has for its whole life. So "which account" is a property of the
* connection, not of the command: a client authenticated as one account cannot run some commands as
* a less privileged one. A deployment that grants its application account {@code EVALSHA} so that
* the rate limiter works has granted it to every code path that can reach a regular connection;
* separate accounts keep the scripting grant on the connections that run scripts.
*
* <p>The runtime names the two accounts its own lanes use. A module that composes further lanes on
* top of the runtime — the typed SDK's admin plane — names its own account and contributes it
* through {@code RedisAccountContribution}; the runtime does not need to know it exists. An account
* with no configured credential is served by the application client, which collapses to the
* single-account deployment most services start from.
*
* @param name a short lowercase identifier, used in logs
*/
public record RedisAccount(String name) {
// First: the constants below are built by the constructor that reads it.
private static final Pattern NAME = Pattern.compile("[a-z][a-z0-9-]{0,31}");
/** Ordinary data commands. The one account every deployment configures. */
public static final RedisAccount APPLICATION = new RedisAccount("application");
/** Registered-script execution: {@code SCRIPT LOAD} and {@code EVALSHA}. */
public static final RedisAccount ADVANCED = new RedisAccount("advanced");
public RedisAccount {
Objects.requireNonNull(name, "account name must be non-null");
if (!NAME.matcher(name).matches()) {
throw new IllegalArgumentException("account name must be a short lowercase identifier");
}
}
@Override
public String toString() {
return name;
}
}
@@ -0,0 +1,29 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
/**
* The runtime's own lanes: the ones its semantic consumers and its health contributor use.
*
* <p>Two, because the runtime's consumers need two account/behaviour combinations: ordinary
* commands on the application account, and registered scripts on the advanced account. Blocking,
* transaction and admin lanes belong to the typed SDK, which contributes them itself.
*/
public enum RedisConnectionKind implements RedisLane {
/** Ordinary non-blocking commands on a shared, thread-safe connection. */
REGULAR(RedisAccount.APPLICATION.name()),
/**
* Registered-script execution, which needs the scripting grants ordinary traffic must not have.
*/
SCRIPT(RedisAccount.ADVANCED.name());
// The name rather than the record: an enum constant's state must be deeply immutable.
private final String account;
RedisConnectionKind(String account) {
this.account = account;
}
@Override
public RedisAccount account() {
return new RedisAccount(account);
}
}
@@ -0,0 +1,49 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import io.lettuce.core.api.async.RedisAsyncCommands;
import io.lettuce.core.cluster.api.async.RedisClusterAsyncCommands;
import java.util.Objects;
import java.util.Optional;
/**
* The driver surface of one borrowed connection, for a module that speaks more of Redis than the
* runtime's semantic commands.
*
* <p>The typed SDK builds its own gateway over this. The runtime does not carry the SDK's command
* surface; it carries the connection, and the SDK brings the commands.
*
* @param commands the asynchronous commands every data command lives on: standalone, or
* slot-routing on Cluster
* @param transactional the same connection's single-node surface, which is the only one that can
* own a {@code MULTI}/{@code EXEC} window; empty on a slot-routing Cluster connection
*/
public record RedisDriverConnection(
RedisClusterAsyncCommands<byte[], byte[]> commands,
Optional<RedisAsyncCommands<byte[], byte[]>> transactional) {
public RedisDriverConnection {
Objects.requireNonNull(commands, "commands must be non-null");
Objects.requireNonNull(transactional, "transactional must be non-null");
}
/**
* A single-node connection, which can own a transaction window.
*
* @param commands the node's asynchronous commands
* @return the driver connection
*/
public static RedisDriverConnection singleNode(RedisAsyncCommands<byte[], byte[]> commands) {
return new RedisDriverConnection(commands, Optional.of(commands));
}
/**
* A slot-routing Cluster connection, which cannot own a transaction window.
*
* @param commands the slot-routing asynchronous commands
* @return the driver connection
*/
public static RedisDriverConnection slotRouting(
RedisClusterAsyncCommands<byte[], byte[]> commands) {
return new RedisDriverConnection(commands, Optional.empty());
}
}
@@ -0,0 +1,45 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
/**
* A bounded pool of connections that share an account and a connection behaviour.
*
* <p>Lanes exist because their failure modes are incompatible. A script needs grants ordinary
* traffic must not have; a blocking command holds its connection for the whole block; a transaction
* owns its connection between {@code MULTI} and {@code EXEC}. Sharing one pool turns any of these
* into a stall of everything else.
*
* <p>The runtime defines the lanes its own consumers use ({@link RedisConnectionKind}). A module
* that needs another — the typed SDK's blocking, transaction and admin lanes — implements this
* interface and contributes a limit for it; the runtime pools and drains it like its own.
* Implementations must be singletons with value identity (an enum constant), because the lane is
* the pool's key.
*/
public interface RedisLane {
/**
* Returns the lane's name, for logs and refusals.
*
* @return the name
*/
String name();
/**
* Returns the account this lane's connections authenticate as.
*
* @return the account
*/
RedisAccount account();
/**
* Reports whether a connection must be pinned to the node that owns the caller's routing key.
*
* <p>Only meaningful on Cluster, where a transaction runs entirely on one node: the slot-routing
* connection every other lane uses cannot own the window. Topologies with a single owner ignore
* it.
*
* @return {@code true} when a connection is opened against the routing key's owning node
*/
default boolean pinnedToKeyOwner() {
return false;
}
}
@@ -0,0 +1,38 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import java.util.Objects;
/**
* No connection could be lent: the lane stayed full for the acquire timeout, the wait was
* interrupted, or the runtime is shutting down.
*
* <p>Always raised before any command exists, so nothing reached Redis. A caller may treat it as
* "unavailable" rather than as a write that might have landed — the distinction every semantic
* adapter reports to its own callers.
*/
public final class RedisLaneUnavailableException extends RuntimeException {
private static final long serialVersionUID = 1L;
private final String lane;
/**
* Creates the failure.
*
* @param lane the lane that could not lend a connection
* @param reason a fixed, payload-free reason
*/
public RedisLaneUnavailableException(String lane, String reason) {
super(Objects.requireNonNull(reason, "reason must be non-null"));
this.lane = Objects.requireNonNull(lane, "lane must be non-null");
}
/**
* Returns the lane that refused.
*
* @return the lane name
*/
public String lane() {
return lane;
}
}
@@ -1,13 +1,9 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection;
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
/**
* A borrowed connection, typed by what the caller actually needs.
*
* <p>The predecessor handed out {@code Object} and left the caller to cast. That is not only
* awkward — it meant the type system could not tell a caller holding a live connection from one
* holding a returned lease, and returning was a counter decrement that never closed anything.
* A borrowed connection.
*
* <p>Two things a caller must know how to do. Returning is mandatory, which is why this is {@link
* AutoCloseable} and every lane is bounded. Invalidating is for the case a pooled connection cannot
@@ -21,21 +17,29 @@ public interface RedisLease extends AutoCloseable {
*
* @return the lane
*/
RedisConnectionKind kind();
RedisLane lane();
/**
* Returns the gateway bound to this connection.
* Returns the runtime's semantic commands over this connection.
*
* @return the driver seam
* @return the commands
* @throws IllegalStateException when the lease has already been returned
*/
RedisCommandGateway gateway();
SemanticRedisCommands commands();
/**
* Returns the driver surface of this connection, for a module that brings its own commands.
*
* @return the driver connection
* @throws IllegalStateException when the lease has already been returned
*/
RedisDriverConnection driver();
/**
* Marks the connection unfit for reuse, so returning it closes it instead of pooling it.
*
* <p>Call this whenever cleanup did not complete: a failed {@code DISCARD}, an abandoned
* subscription, any path that leaves connection-scoped state behind.
* <p>Call this whenever cleanup did not complete: a failed {@code DISCARD}, a window that may
* still be open, any path that leaves connection-scoped state behind.
*/
void invalidate();
@@ -0,0 +1,85 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import java.util.Optional;
/**
* The driver client for one deployment, and the only thing that knows which topology it is.
*
* <p>Everything above this interface is topology-agnostic: a caller asks for a lane and gets a
* connection. Which client produced it — standalone, Sentinel-resolving, or slot-routing — is
* settled once, at composition, by the strategy that matched the configured mode.
*
* <p>Opening a lane is separate from borrowing one. This creates a connection; the owner decides
* whether the caller is allowed to hold one.
*/
public interface RedisRuntimeClient extends AutoCloseable {
/**
* Returns the deployment mode this client was built for.
*
* @return the bound mode
*/
RedisDeploymentMode mode();
/**
* Opens a connection for a lane that needs no routing decision.
*
* @param lane the lane
* @return the open lane
*/
default RedisLaneConnection openLane(RedisLane lane) {
return openLane(lane, Optional.empty());
}
/**
* Opens a connection for a lane.
*
* <p>The routing key exists for a lane {@linkplain RedisLane#pinnedToKeyOwner() pinned to its
* key's owner}: on Cluster such a connection is opened against the node that owns the key rather
* than the slot-routing connection every other lane uses. Topologies with a single owner ignore
* it.
*
* @param lane the lane
* @param routingKey a key whose slot decides which node the lane is pinned to
* @return the open lane
*/
RedisLaneConnection openLane(RedisLane lane, Optional<byte[]> routingKey);
/**
* Shuts the client and its event loop down, after every lane has been closed.
*
* <p>Shutting the client down first would abort in-flight commands the drain was waiting for.
*/
@Override
void close();
/** One open connection and what can be sent over it. */
interface RedisLaneConnection extends AutoCloseable {
/**
* Returns the runtime's semantic commands over this connection.
*
* @return the commands
*/
SemanticRedisCommands commands();
/**
* Returns the driver surface of this connection, for a module that brings its own commands.
*
* @return the driver connection
*/
RedisDriverConnection driver();
/**
* Reports whether the connection is currently usable.
*
* @return {@code true} while the driver reports it open
*/
boolean open();
@Override
void close();
}
}
@@ -1,15 +1,12 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection;
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.command.CommandAccess;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.error.RedisCommandRejectedException;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.error.RedisFailureMetadata;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import java.time.Duration;
import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Deque;
import java.util.EnumMap;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
@@ -52,10 +49,10 @@ public final class RedisRuntimeOwner implements AutoCloseable {
}
private final RedisRuntimeClient client;
private final Map<RedisConnectionKind, Integer> limits;
private final Map<RedisConnectionKind, Deque<RedisRuntimeClient.RedisLaneConnection>> idle;
private final Map<RedisConnectionKind, Integer> outstanding;
private final Map<RedisConnectionKind, Semaphore> permits;
private final Map<RedisLane, Integer> limits;
private final Map<RedisLane, Deque<RedisRuntimeClient.RedisLaneConnection>> idle;
private final Map<RedisLane, Integer> outstanding;
private final Map<RedisLane, Semaphore> permits;
private final Duration acquireTimeout;
private final Duration drainTimeout;
private final AtomicReference<State> state = new AtomicReference<>(State.OPEN);
@@ -65,13 +62,15 @@ public final class RedisRuntimeOwner implements AutoCloseable {
* Creates the owner.
*
* @param client the topology client whose connections this owns
* @param limits per-lane maximum connections, each held by at most one lease at a time
* @param limits per-lane maximum connections, each held by at most one lease at a time. Every
* lane a caller may borrow is named here; the runtime's own {@link RedisConnectionKind} lanes
* are required, and a module that composes further lanes contributes their limits
* @param acquireTimeout how long a borrow waits for a returned connection when its lane is full
* @param drainTimeout how long shutdown waits for outstanding leases
*/
public RedisRuntimeOwner(
RedisRuntimeClient client,
Map<RedisConnectionKind, Integer> limits,
Map<? extends RedisLane, Integer> limits,
Duration acquireTimeout,
Duration drainTimeout) {
this.client = Objects.requireNonNull(client, "client must be non-null");
@@ -79,21 +78,27 @@ public final class RedisRuntimeOwner implements AutoCloseable {
Objects.requireNonNull(acquireTimeout, "acquire timeout must be non-null");
this.drainTimeout = Objects.requireNonNull(drainTimeout, "drain timeout must be non-null");
Objects.requireNonNull(limits, "limits must be non-null");
Map<RedisConnectionKind, Integer> configured = new EnumMap<>(RedisConnectionKind.class);
Map<RedisConnectionKind, Deque<RedisRuntimeClient.RedisLaneConnection>> pools =
new EnumMap<>(RedisConnectionKind.class);
Map<RedisConnectionKind, Integer> counters = new EnumMap<>(RedisConnectionKind.class);
Map<RedisConnectionKind, Semaphore> lanes = new EnumMap<>(RedisConnectionKind.class);
for (RedisConnectionKind kind : RedisConnectionKind.values()) {
Integer limit = limits.get(kind);
if (limit == null || limit < 1) {
if (!limits.containsKey(kind)) {
throw new IllegalArgumentException("connection lane " + kind + " needs a positive limit");
}
configured.put(kind, limit);
pools.put(kind, new ArrayDeque<>());
counters.put(kind, 0);
}
Map<RedisLane, Integer> configured = new LinkedHashMap<>();
Map<RedisLane, Deque<RedisRuntimeClient.RedisLaneConnection>> pools = new LinkedHashMap<>();
Map<RedisLane, Integer> counters = new LinkedHashMap<>();
Map<RedisLane, Semaphore> lanes = new LinkedHashMap<>();
for (Map.Entry<? extends RedisLane, Integer> entry : limits.entrySet()) {
RedisLane lane = Objects.requireNonNull(entry.getKey(), "lane must be non-null");
Integer limit = entry.getValue();
if (limit == null || limit < 1) {
throw new IllegalArgumentException(
"connection lane " + lane.name() + " needs a positive limit");
}
configured.put(lane, limit);
pools.put(lane, new ArrayDeque<>());
counters.put(lane, 0);
// Fair, so a burst is served in arrival order rather than starving the earliest waiter.
lanes.put(kind, new Semaphore(limit, true));
lanes.put(lane, new Semaphore(limit, true));
}
this.limits = Map.copyOf(configured);
this.idle = pools;
@@ -115,10 +120,10 @@ public final class RedisRuntimeOwner implements AutoCloseable {
*
* @param kind the lane
* @return the lease, which must be closed
* @throws RedisCommandRejectedException when the lane stayed full for the acquire timeout or the
* @throws RedisLaneUnavailableException when the lane stayed full for the acquire timeout or the
* owner is closing
*/
public RedisLease borrow(RedisConnectionKind kind) {
public RedisLease borrow(RedisLane kind) {
return borrow(kind, Optional.empty());
}
@@ -133,14 +138,21 @@ public final class RedisRuntimeOwner implements AutoCloseable {
* @param kind the lane
* @param routingKey a key whose slot decides the node, on topologies that have more than one
* @return the lease, which must be closed
* @throws RedisCommandRejectedException when the lane stayed full for the acquire timeout or the
* @throws RedisLaneUnavailableException when the lane stayed full for the acquire timeout or the
* owner is closing
* @throws IllegalArgumentException when no limit was configured for the lane
*/
public RedisLease borrow(RedisConnectionKind kind, Optional<byte[]> routingKey) {
public RedisLease borrow(RedisLane kind, Optional<byte[]> routingKey) {
Objects.requireNonNull(kind, "connection kind must be non-null");
Objects.requireNonNull(routingKey, "routing key must be non-null");
if (!permits.containsKey(kind)) {
throw new IllegalArgumentException(
"connection lane "
+ kind.name()
+ " was never composed; the module that uses it contributes its limit");
}
if (state.get() != State.OPEN) {
throw notAccepting();
throw notAccepting(kind);
}
// The limit is the lane's connection count: a lease holds one connection for one round trip,
// so a burst above it waits for a returned connection instead of being refused against a
@@ -153,12 +165,13 @@ public final class RedisRuntimeOwner implements AutoCloseable {
admitted = lane.tryAcquire(acquireTimeout.toNanos(), TimeUnit.NANOSECONDS);
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
throw reject("interrupted while waiting for a connection on lane " + kind);
throw reject(kind, "interrupted while waiting for a connection on lane " + kind.name());
}
if (!admitted) {
throw reject(
kind,
"connection lane "
+ kind
+ kind.name()
+ " reached its limit of "
+ limits.get(kind)
+ " and no connection was returned within "
@@ -167,7 +180,7 @@ public final class RedisRuntimeOwner implements AutoCloseable {
synchronized (monitor) {
if (state.get() != State.OPEN) {
lane.release();
throw notAccepting();
throw notAccepting(kind);
}
outstanding.put(kind, outstanding.get(kind) + 1);
}
@@ -198,9 +211,7 @@ public final class RedisRuntimeOwner implements AutoCloseable {
}
private void release(
RedisConnectionKind kind,
RedisRuntimeClient.RedisLaneConnection connection,
boolean reusable) {
RedisLane kind, RedisRuntimeClient.RedisLaneConnection connection, boolean reusable) {
boolean drained;
synchronized (monitor) {
outstanding.put(kind, outstanding.get(kind) - 1);
@@ -273,8 +284,9 @@ public final class RedisRuntimeOwner implements AutoCloseable {
}
}
private RedisCommandRejectedException notAccepting() {
private RedisLaneUnavailableException notAccepting(RedisLane lane) {
return reject(
lane,
"the Redis runtime is "
+ state.get()
+ " and is not accepting new work; a lease taken during shutdown would either be"
@@ -283,10 +295,8 @@ public final class RedisRuntimeOwner implements AutoCloseable {
// Every refusal here happens before a command exists, so it is always "not sent": a caller may
// treat it as unavailable rather than as a write that might have landed.
private RedisCommandRejectedException reject(String reason) {
return new RedisCommandRejectedException(
reason,
RedisFailureMetadata.notSent("CONNECTION", CommandAccess.NONE, false, client.mode()));
private static RedisLaneUnavailableException reject(RedisLane lane, String reason) {
return new RedisLaneUnavailableException(lane.name(), reason);
}
/**
@@ -295,7 +305,7 @@ public final class RedisRuntimeOwner implements AutoCloseable {
* @param kind the lane
* @return the outstanding count
*/
public int outstanding(RedisConnectionKind kind) {
public int outstanding(RedisLane kind) {
synchronized (monitor) {
return outstanding.get(Objects.requireNonNull(kind, "connection kind must be non-null"));
}
@@ -313,31 +323,39 @@ public final class RedisRuntimeOwner implements AutoCloseable {
/** A borrowed connection, typed, returned once, and invalidatable. */
public final class Lease implements RedisLease {
private final RedisConnectionKind kind;
private final RedisLane kind;
private final RedisRuntimeClient.RedisLaneConnection connection;
private boolean reusable;
private boolean closed;
private Lease(
RedisConnectionKind kind,
RedisRuntimeClient.RedisLaneConnection connection,
boolean reusable) {
RedisLane kind, RedisRuntimeClient.RedisLaneConnection connection, boolean reusable) {
this.kind = kind;
this.connection = connection;
this.reusable = reusable;
}
@Override
public RedisConnectionKind kind() {
public RedisLane lane() {
return kind;
}
@Override
public RedisCommandGateway gateway() {
public SemanticRedisCommands commands() {
requireOpen();
return connection.commands();
}
@Override
public RedisDriverConnection driver() {
requireOpen();
return connection.driver();
}
private void requireOpen() {
if (closed) {
throw new IllegalStateException("this Redis lease was already returned");
}
return connection.gateway();
}
@Override
@@ -1,13 +1,8 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection;
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import static java.util.concurrent.TimeUnit.MILLISECONDS;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.cluster.RedisSlotCalculator;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisCredentialResolver.RedisCredentials;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.config.RedisSdkSettings;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.LettuceRedisCommandGateway;
import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisCredentialResolver.RedisCredentials;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.config.RedisRuntimeSettings;
import io.lettuce.core.ClientOptions;
import io.lettuce.core.RedisClient;
import io.lettuce.core.RedisCredentialsProvider;
@@ -15,29 +10,20 @@ import io.lettuce.core.RedisURI;
import io.lettuce.core.SocketOptions;
import io.lettuce.core.SslOptions;
import io.lettuce.core.TimeoutOptions;
import io.lettuce.core.api.StatefulRedisConnection;
import io.lettuce.core.cluster.ClusterClientOptions;
import io.lettuce.core.cluster.ClusterTopologyRefreshOptions;
import io.lettuce.core.cluster.RedisClusterClient;
import io.lettuce.core.cluster.api.StatefulRedisClusterConnection;
import io.lettuce.core.cluster.models.partitions.RedisClusterNode;
import io.lettuce.core.codec.ByteArrayCodec;
import io.lettuce.core.resource.ClientResources;
import io.lettuce.core.resource.DefaultClientResources;
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.ArrayList;
import java.util.EnumMap;
import java.util.LinkedHashSet;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import java.util.Set;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.concurrent.atomic.AtomicInteger;
/**
* Builds the clients the configured topology and the configured accounts call for.
@@ -46,7 +32,7 @@ import java.util.concurrent.atomic.AtomicInteger;
* them. A deployment that declares Sentinel and gets a standalone client would work — until the
* first promotion, at which point it would keep writing to a server that is no longer the primary.
* So the mode picks the strategy and a mode whose prerequisites are missing fails at {@link
* RedisSdkSettings#validate()}, before this class is ever reached.
* RedisRuntimeSettings#validate()}, before this class is ever reached.
*
* <p>Orthogonally to the topology, a deployment may authenticate different lanes as different Redis
* accounts. That cannot be expressed on one client: an ACL user is bound at authentication and
@@ -62,11 +48,9 @@ import java.util.concurrent.atomic.AtomicInteger;
*/
public final class RedisTopologyClientFactory {
private static final RedisSlotCalculator SLOTS = new RedisSlotCalculator();
private final RedisRuntimeSettings settings;
private final RedisSdkSettings settings;
private final Map<RedisCredentialRole, RedisCredentials> credentials;
private final Map<RedisAccount, RedisCredentials> credentials;
private final Optional<RedisCredentials> sentinelCredentials;
@@ -98,13 +82,14 @@ public final class RedisTopologyClientFactory {
* Creates the factory.
*
* @param settings the validated settings
* @param credentials the resolved account for each configured role
* @param credentials the resolved credentials of each configured account; the application
* account's may be absent (anonymous access), every other account named here gets a client
* @param sentinelCredentials the resolved Sentinel control account, when one is configured
* @param tlsMaterial opens configured TLS material
*/
public RedisTopologyClientFactory(
RedisSdkSettings settings,
Map<RedisCredentialRole, RedisCredentials> credentials,
RedisRuntimeSettings settings,
Map<RedisAccount, RedisCredentials> credentials,
Optional<RedisCredentials> sentinelCredentials,
TlsMaterialSource tlsMaterial) {
this.settings = Objects.requireNonNull(settings, "settings must be non-null");
@@ -123,24 +108,24 @@ public final class RedisTopologyClientFactory {
public RedisRuntimeClient create() {
// One event-loop group for every account, not one per account. `ClientResources` carries
// `max(2, cores)` IO threads plus a computation pool and a timer; a deployment with an
// application, an advanced and a pub/sub account used to get three of each, so an eight-core
// application, an advanced and an admin account used to get three of each, so an eight-core
// pod ran twenty-four IO threads to talk to one Redis. The accounts differ in who they
// authenticate as, which is a property of the connection, not of the threads that carry it.
SharedClientResources shared = new SharedClientResources(resources());
Map<RedisCredentialRole, RedisRuntimeClient> byRole = new EnumMap<>(RedisCredentialRole.class);
Map<RedisAccount, RedisRuntimeClient> byAccount = new LinkedHashMap<>();
List<RedisRuntimeClient> created = new ArrayList<>();
try {
RedisRuntimeClient application =
clientFor(Optional.ofNullable(credentials.get(RedisCredentialRole.APPLICATION)), shared);
byRole.put(RedisCredentialRole.APPLICATION, application);
clientFor(Optional.ofNullable(credentials.get(RedisAccount.APPLICATION)), shared);
byAccount.put(RedisAccount.APPLICATION, application);
created.add(application);
for (RedisCredentialRole role : RedisCredentialRole.values()) {
if (role == RedisCredentialRole.APPLICATION || !credentials.containsKey(role)) {
for (Map.Entry<RedisAccount, RedisCredentials> account : credentials.entrySet()) {
if (account.getKey().equals(RedisAccount.APPLICATION)) {
continue;
}
RedisRuntimeClient client = clientFor(Optional.of(credentials.get(role)), shared);
RedisRuntimeClient client = clientFor(Optional.of(account.getValue()), shared);
created.add(client);
byRole.put(role, client);
byAccount.put(account.getKey(), client);
}
} catch (RuntimeException failure) {
// A half-built set would leak the event loops of the clients that did get created. Closing
@@ -149,9 +134,9 @@ public final class RedisTopologyClientFactory {
shared.shutdownAfterFailedBuild(shutdown());
throw failure;
}
return byRole.size() == 1
? byRole.get(RedisCredentialRole.APPLICATION)
: new RoleRoutingRuntimeClient(byRole);
return byAccount.size() == 1
? byAccount.get(RedisAccount.APPLICATION)
: new AccountRoutingRuntimeClient(byAccount);
}
private static void closeQuietly(RedisRuntimeClient client) {
@@ -326,7 +311,7 @@ public final class RedisTopologyClientFactory {
private SslOptions sslOptions() {
SslOptions.Builder ssl = SslOptions.builder().jdkSslProvider();
RedisSdkSettings.Tls tls = settings.getTls();
RedisRuntimeSettings.Tls tls = settings.getTls();
if (tls.getTrustMaterialResource() != null && !tls.getTrustMaterialResource().isBlank()) {
ssl.trustManager(material("trust material", tls.getTrustMaterialResource()));
}
@@ -370,288 +355,12 @@ public final class RedisTopologyClientFactory {
return () -> tlsMaterial.open(location);
}
/**
* One {@link ClientResources} shared by every account, stopped by the last client to let go.
*
* <p>Lettuce treats whoever passes resources to {@code RedisClient.create} as their owner and
* {@code client.shutdown()} deliberately leaves them running, so somebody has to stop them. With
* one group per account that owner was obvious and wasteful; with one group for all of them the
* ownership is shared, and a hold count is the smallest thing that still guarantees the loops are
* stopped exactly once, after the last client that was using them.
*/
private static final class SharedClientResources {
private final ClientResources resources;
private final AtomicInteger holds = new AtomicInteger();
private final AtomicBoolean stopped = new AtomicBoolean();
private SharedClientResources(ClientResources resources) {
this.resources = resources;
}
/** Takes a hold and returns the group to hand to a driver client. */
private ClientResources acquire() {
holds.incrementAndGet();
return resources;
}
/** Releases one hold, stopping the loops when it was the last one. */
private void release(ShutdownBudget shutdown) {
if (holds.decrementAndGet() == 0) {
stop(shutdown);
}
}
/**
* Stops the loops after a build that did not finish.
*
* <p>Unconditional, not "when nothing holds it": a hold is taken before the driver client that
* would release it exists, so a failure between those two points leaves a hold nobody can give
* back. {@link #stop} is idempotent, so the clients that were built and closed normally having
* already stopped the group costs nothing here.
*/
private void shutdownAfterFailedBuild(ShutdownBudget shutdown) {
stop(shutdown);
}
private void stop(ShutdownBudget shutdown) {
if (stopped.compareAndSet(false, true)) {
shutdown.await(
resources.shutdown(
shutdown.quietPeriod().toMillis(), shutdown.timeout().toMillis(), MILLISECONDS));
}
}
}
/** Standalone and Sentinel share a client type; only how the URI resolves differs. */
private static final class StandaloneRuntimeClient implements RedisRuntimeClient {
private final RedisClient client;
private final SharedClientResources resources;
private final RedisDeploymentMode mode;
private final ShutdownBudget shutdown;
private StandaloneRuntimeClient(
RedisClient client,
SharedClientResources resources,
ShutdownBudget shutdown,
RedisDeploymentMode mode) {
this.client = client;
this.resources = resources;
this.shutdown = shutdown;
this.mode = mode;
}
@Override
public RedisDeploymentMode mode() {
return mode;
}
@Override
public RedisLaneConnection openLane(RedisConnectionKind kind, Optional<byte[]> routingKey) {
// A single server owns every key, so a routing key carries no information here.
StatefulRedisConnection<byte[], byte[]> connection = client.connect(ByteArrayCodec.INSTANCE);
return new LaneConnection(
connection, new LettuceRedisCommandGateway(connection.async()), connection::isOpen);
}
@Override
public void close() {
try {
client.shutdown(
shutdown.quietPeriod().toMillis(), shutdown.timeout().toMillis(), MILLISECONDS);
} finally {
// After the client, never before: the resources are the threads the shutdown runs on. And
// awaited, not fired — shutdown() returns a future, so ignoring it means returning while
// the event loop is still running and reporting a clean stop that has not happened. The
// group is shared across accounts, so only the last client to release actually stops it.
resources.release(shutdown);
}
}
}
/** Cluster: data lanes route by slot, the transaction lane is pinned to the slot's owner. */
private static final class ClusterRuntimeClient implements RedisRuntimeClient {
private final RedisClusterClient client;
private final SharedClientResources resources;
private final ShutdownBudget shutdown;
private ClusterRuntimeClient(
RedisClusterClient client, SharedClientResources resources, ShutdownBudget shutdown) {
this.client = client;
this.resources = resources;
this.shutdown = shutdown;
}
@Override
public RedisDeploymentMode mode() {
return RedisDeploymentMode.CLUSTER;
}
@Override
public RedisLaneConnection openLane(RedisConnectionKind kind, Optional<byte[]> routingKey) {
StatefulRedisClusterConnection<byte[], byte[]> connection =
client.connect(ByteArrayCodec.INSTANCE);
if (kind != RedisConnectionKind.TRANSACTION) {
return new LaneConnection(
connection, new LettuceRedisCommandGateway(connection.async()), connection::isOpen);
}
try {
// A Cluster transaction runs on one node. The slot-routing connection cannot own the
// window — its queued commands would be spread across nodes — so the lane is pinned to the
// node that owns the routing key's slot, and every key in the window is proved to share
// that slot before anything is queued.
byte[] key =
routingKey.orElseThrow(
() ->
new IllegalStateException(
"a Cluster transaction lane needs a routing key: the window runs on one"
+ " node, and which node that is can only be decided from a key or an"
+ " explicit slot tag."));
int slot = SLOTS.applyAsInt(new String(key, StandardCharsets.UTF_8));
RedisClusterNode owner = client.getPartitions().getMasterBySlot(slot);
if (owner == null) {
throw new IllegalStateException(
"no Cluster node currently owns slot "
+ slot
+ "; the topology is incomplete and a transaction opened against it would run"
+ " somewhere the keys do not live");
}
StatefulRedisConnection<byte[], byte[]> node = connection.getConnection(owner.getNodeId());
// The parent is closed on release; closing it releases the node connection with it.
return new LaneConnection(
connection, new LettuceRedisCommandGateway(node.async()), node::isOpen);
} catch (RuntimeException failure) {
connection.close();
throw failure;
}
}
@Override
public void close() {
try {
client.shutdown(
shutdown.quietPeriod().toMillis(), shutdown.timeout().toMillis(), MILLISECONDS);
} finally {
resources.release(shutdown);
}
}
}
/**
* Routes each lane to the client that authenticated as the lane's account.
*
* <p>Only created when a deployment configured more than one account. Its whole behaviour is a
* lookup: the roles were decided at composition, and a lane cannot change the account it runs as
* after the connection exists.
*/
private static final class RoleRoutingRuntimeClient implements RedisRuntimeClient {
private final Map<RedisCredentialRole, RedisRuntimeClient> byRole;
private RoleRoutingRuntimeClient(Map<RedisCredentialRole, RedisRuntimeClient> byRole) {
this.byRole = new EnumMap<>(byRole);
}
@Override
public RedisDeploymentMode mode() {
return byRole.get(RedisCredentialRole.APPLICATION).mode();
}
@Override
public RedisLaneConnection openLane(RedisConnectionKind kind, Optional<byte[]> routingKey) {
return delegate(kind).openLane(kind, routingKey);
}
private RedisRuntimeClient delegate(RedisConnectionKind kind) {
RedisRuntimeClient client = byRole.get(kind.credentialRole());
// Falling back to the application account is the documented behaviour of an unconfigured
// role, not a failure: a deployment with one account is the common case.
return client == null ? byRole.get(RedisCredentialRole.APPLICATION) : client;
}
@Override
public void close() {
// Distinct instances only, and the application client last: it is the one every unconfigured
// role fell back to, so closing it first would tear out lanes still being drained.
Set<RedisRuntimeClient> remaining = new LinkedHashSet<>(byRole.values());
RedisRuntimeClient application = byRole.get(RedisCredentialRole.APPLICATION);
remaining.remove(application);
RuntimeException first = null;
for (RedisRuntimeClient client : remaining) {
try {
client.close();
} catch (RuntimeException failure) {
first = first == null ? failure : first;
}
}
try {
application.close();
} catch (RuntimeException failure) {
first = first == null ? failure : first;
}
if (first != null) {
throw first;
}
}
}
private record LaneConnection(
AutoCloseable connection,
RedisCommandGateway gateway,
java.util.function.BooleanSupplier openCheck)
implements RedisRuntimeClient.RedisLaneConnection {
@Override
public RedisCommandGateway gateway() {
return gateway;
}
@Override
public boolean open() {
return openCheck.getAsBoolean();
}
@Override
public void close() {
try {
connection.close();
} catch (Exception failure) {
throw new IllegalStateException("a Redis lane connection could not be closed", failure);
}
}
}
private ShutdownBudget shutdown() {
return new ShutdownBudget(
settings.getLifecycle().getShutdownQuietPeriod(),
settings.getLifecycle().getShutdownTimeout());
}
/**
* How long a client is given to stop, and the wait that makes stopping observable.
*
* @param quietPeriod the window in which new work must stop arriving
* @param timeout the total budget
*/
private record ShutdownBudget(Duration quietPeriod, Duration timeout) {
void await(java.util.concurrent.Future<?> pending) {
try {
pending.get(timeout.toMillis() + quietPeriod.toMillis(), MILLISECONDS);
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
} catch (java.util.concurrent.ExecutionException
| java.util.concurrent.TimeoutException failure) {
// Shutdown is best effort past its own budget; what it must not do is claim to be done.
LOG.warn("Redis client resources did not shut down within {}", timeout, failure);
}
}
}
private static final org.slf4j.Logger LOG =
org.slf4j.LoggerFactory.getLogger(RedisTopologyClientFactory.class);
@@ -0,0 +1,60 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import static java.util.concurrent.TimeUnit.MILLISECONDS;
import io.lettuce.core.resource.ClientResources;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.concurrent.atomic.AtomicInteger;
/**
* One {@link ClientResources} shared by every account, stopped by the last client to let go.
*
* <p>Lettuce treats whoever passes resources to {@code RedisClient.create} as their owner and
* {@code client.shutdown()} deliberately leaves them running, so somebody has to stop them. With
* one group per account that owner was obvious and wasteful; with one group for all of them the
* ownership is shared, and a hold count is the smallest thing that still guarantees the loops are
* stopped exactly once, after the last client that was using them.
*/
final class SharedClientResources {
private final ClientResources resources;
private final AtomicInteger holds = new AtomicInteger();
private final AtomicBoolean stopped = new AtomicBoolean();
SharedClientResources(ClientResources resources) {
this.resources = resources;
}
/** Takes a hold and returns the group to hand to a driver client. */
ClientResources acquire() {
holds.incrementAndGet();
return resources;
}
/** Releases one hold, stopping the loops when it was the last one. */
void release(ShutdownBudget shutdown) {
if (holds.decrementAndGet() == 0) {
stop(shutdown);
}
}
/**
* Stops the loops after a build that did not finish.
*
* <p>Unconditional, not "when nothing holds it": a hold is taken before the driver client that
* would release it exists, so a failure between those two points leaves a hold nobody can give
* back. {@link #stop} is idempotent, so the clients that were built and closed normally having
* already stopped the group costs nothing here.
*/
void shutdownAfterFailedBuild(ShutdownBudget shutdown) {
stop(shutdown);
}
private void stop(ShutdownBudget shutdown) {
if (stopped.compareAndSet(false, true)) {
shutdown.await(
resources.shutdown(
shutdown.quietPeriod().toMillis(), shutdown.timeout().toMillis(), MILLISECONDS));
}
}
}
@@ -0,0 +1,32 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import static java.util.concurrent.TimeUnit.MILLISECONDS;
import java.time.Duration;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import java.util.concurrent.TimeoutException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
* How long a client is given to stop, and the wait that makes stopping observable.
*
* @param quietPeriod the window in which new work must stop arriving
* @param timeout the total budget
*/
record ShutdownBudget(Duration quietPeriod, Duration timeout) {
private static final Logger LOG = LoggerFactory.getLogger(ShutdownBudget.class);
void await(Future<?> pending) {
try {
pending.get(timeout.toMillis() + quietPeriod.toMillis(), MILLISECONDS);
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
} catch (ExecutionException | TimeoutException failure) {
// Shutdown is best effort past its own budget; what it must not do is claim to be done.
LOG.warn("Redis client resources did not shut down within {}", timeout, failure);
}
}
}
@@ -0,0 +1,56 @@
package dev.caskeleton.adapter.outbound.cache.redis.runtime.connection;
import static java.util.concurrent.TimeUnit.MILLISECONDS;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.RedisDeploymentMode;
import io.lettuce.core.RedisClient;
import io.lettuce.core.api.StatefulRedisConnection;
import io.lettuce.core.codec.ByteArrayCodec;
import java.util.Optional;
/** Standalone and Sentinel share a client type; only how the URI resolves differs. */
final class StandaloneRuntimeClient implements RedisRuntimeClient {
private final RedisClient client;
private final SharedClientResources resources;
private final ShutdownBudget shutdown;
private final RedisDeploymentMode mode;
StandaloneRuntimeClient(
RedisClient client,
SharedClientResources resources,
ShutdownBudget shutdown,
RedisDeploymentMode mode) {
this.client = client;
this.resources = resources;
this.shutdown = shutdown;
this.mode = mode;
}
@Override
public RedisDeploymentMode mode() {
return mode;
}
@Override
public RedisLaneConnection openLane(RedisLane lane, Optional<byte[]> routingKey) {
// A single server owns every key, so a routing key carries no information here.
StatefulRedisConnection<byte[], byte[]> connection = client.connect(ByteArrayCodec.INSTANCE);
return new LaneConnection(
connection, RedisDriverConnection.singleNode(connection.async()), connection::isOpen);
}
@Override
public void close() {
try {
client.shutdown(
shutdown.quietPeriod().toMillis(), shutdown.timeout().toMillis(), MILLISECONDS);
} finally {
// After the client, never before: the resources are the threads the shutdown runs on. And
// awaited, not fired — shutdown() returns a future, so ignoring it means returning while the
// event loop is still running and reporting a clean stop that has not happened. The group is
// shared across accounts, so only the last client to release actually stops it.
resources.release(shutdown);
}
}
}
@@ -1,4 +1,4 @@
package dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key;
package dev.caskeleton.adapter.outbound.cache.redis.runtime.key;
import java.util.Locale;
import java.util.Objects;

Some files were not shown because too many files have changed in this diff Show More