문제: outbound 어댑터 leaf의 CLAUDE.md 열세 개와 README 아홉 개가 영어이거나 영어 절이 섞여 있다. 열 CLAUDE.md는 Spring Boot 버전 (4.0.0, 4.0.8)을 복사해 두었고 실제 버전(libs.versions.toml)과 다르다. 방법: 뜻을 그대로 옮기고 코드·명령·경로·식별자·설정 키·로그 문자열· 표 구조는 원문으로 둔다. 버전은 `src/gradle/libs.versions.toml`을 가리키게 고친다. 번역하며 본 코드와 어긋난 주장은 코드에 맞춘다: identifier CLAUDE.md의 `.claude/hooks/ca_import_gate.py`(저장소에 없는 hook)를 registry 방향 게이트로, cache-redis README의 「app-bootstrap `IdempotencySettings`」를 실제 위치 `composition:idempotency`로, redis-sdk compose README의 ACL 파일 위치 `acl/`을 lane이 실제로 mount하는 `compose/redis/acl/`로 고친다. persistence-mongo 문서에는 지운 namespace(`spring.data.mongodb.`)를 쓰지 않는다 (MongoNamespaceContractTest가 본다). 다른 영역 문서의 절 제목을 인용한 곳(`docs/jpa/migration-guide.md` "Bound the lock wait" 등)은 그 문서가 아직 영어라 원문 제목으로 둔다. 위험: 인용한 docs/jpa 절 제목은 그 문서를 번역하는 쪽이 제목을 바꾸면 낡는다. 통합 단계에서 맞춰야 한다. ArchUnit 규칙 이름의 대소문자는 다음 커밋에서 맞춘다. 검증: python3 scripts/check-docs.py rc=0(language 줄 19개, number 줄 10개 지움, src/** number 줄 0), check-work-docs.py rc=0, --links(gates.md 범위) 깨진 링크 0.
16 KiB
adapter:outbound:cache-redis — cache와 Redis 어댑터
등록 정보
- 모듈 ID:
adapter-outbound-cache-redis - Gradle 경로:
:adapter:outbound:cache-redis - 이 모듈만 시험(Gradle 경로에서 나온 명령):
./gradlew :adapter:outbound:cache-redis:test --console=plain - 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은
src/gradle/libs.versions.toml이 정한다. - registry 정본:
src/config/architecture/modules.json.
패키지 루트: dev.caskeleton.adapter.outbound.cache.
책임
application-core의 semantic cache 포트를 구현하고, Redis 개념을 core에 드러내지 않는다.- 정해진 물리 키, digest, codec·envelope, program catalog, 타입 있는 Redis 원자 창구, runtime client 연결, capability별 실패 뜻을 가진다.
- semantic cache 포트(
CacheRegionPort) 뒤에서 절대 soft·hard 만료, 쓰기 조건, 키 무효화 표지를 구현한다. TTL jitter도 stampede 보호도 없다. single-flight는 호출자의 몫이다. revision 순서는 포트의CacheSourceRevisionOrder다. Lua 사본은CacheRegionContract(application-core testFixtures)가 그 순서에 맞추고,RedisCacheRegionContractTest와LiveRedisCacheRegionContractTest가 그 계약을 상속한다. - provider 중립
EdgeRateLimitPort를 전용 조율 Redis 설정, 연결·admission, 전용 키, 버전 있는 원자 program으로 구현한다. - 쓰는 쪽이 semantic 포트로 옮기는 동안 옛 cache router를 떼어 둔다.
- 공용 outbound 관심사는
adapter:outbound:support를 다시 쓴다. - semantic 어댑터가 쓰는 공용 topology client, 연결 lifecycle,
SemanticRedisCommands여덟 개, 조건부 Redis runtime 조립은:adapter:outbound:redis-runtime에 의존한다. - 범용 typed SDK는 따로 둔 라이브러리 leaf
:adapter:outbound:redis-sdk에 둔다(그README.md를 본다). 이 leaf는 시험을 포함해 어떤 설정에서도 그것에 의존하지 않는다. SDK의 시험과 lane은 그 leaf에 있다.
Redis 런타임과 골라 쓰는 typed SDK (…cache.redis.runtime, …cache.redis.sdk)
등록된 leaf 둘, 패키지 둘, 방향 하나: SDK는 runtime 위에 서고, runtime은 SDK를 모른다(runtime 안의
RedisRuntimePackageBoundaryTest가 그 방향을 지킨다).
:adapter:outbound:redis-runtime은 운영 기반이다:RedisRuntimeSettings바인딩, credential 해석, topology client, runtime 자신의 lane(RedisConnectionKind.REGULAR,SCRIPT)을 가진RedisRuntimeOwner,SemanticRedisCommands(이 leaf와 health contributor가 보내는 명령 여덟 개), health.cache-redis가 이 leaf에 의존한다.:adapter:outbound:redis-sdk는 골라 쓰는 범용 typed API를 가진다:RedisCommandGateway(SemanticRedisCommands를 상속), 명령 catalog·정책, operation 예산, 명령 guard, raw·admin surface, programmability, extension — 그리고 자기 lane(RedisSdkLane: blocking, transaction, admin)과 admin 계정. 서비스가 그것을RedisLaneContribution/RedisAccountContributionbean으로 runtime에 기여한다(RedisSdkComposition).cache-redis는 운영에서도 시험에서도 그것에 의존하지 않는다.- 이 leaf의 semantic cache·멱등성·rate-limit·lease 어댑터는 runtime의
SemanticRedisCommands를 자기의 닫힌 semantic program(RegisteredLuaScript)으로 보낸다.CommandPolicyGuard를 지나지 않고,redis-command-policy.yml이 그것을 다루지 않는다. - 정확성을 위해 어떤 role에 Redis가 필요한지는 이 leaf의
RedisCorrectnessRoleSelectors가 정하고,META-INF/spring.factories에 runtime의RedisCorrectnessRequirement로 등록한다.
docs/design/2026-08-07-redis-wrapper-typed-api-design.md가 설명하는 typed SDK는 출하하는 semantic Redis 어댑터의
일부가 아니라 골라 쓰는 라이브러리로 남는다. 전달 상태와 맞춘 이력은
docs/history/plans/2026-08-07-redis-wrapper-typed-api-status.md에 있다.
sdk.api..는 공개 계약이다. Spring, Lettuce, Micrometer, SDK 구현 패키지를 import하지 않는다. Reactor는sdk.api.reactive안에만 둔다.sdk.lettuce..가 계약을 구현한다.sdk.config는 속성, capability probe, 허가 정본을 가진다.:adapter:outbound:redis-sdk/src/main/resources/redis-sdk/redis-command-policy.yml이 골라 쓰는 typed SDK의 명령 정책 정본이다. 거기 분류되지 않은 typed SDK 명령은 거절한다. 이 leaf의 semantic capability 어댑터를 위한 정책 파일이 아니다.sdk.lettuce.operations가 타입 있는 operation을 구현한다. 거기 있는 모든 것은 Lettuce에 닿는 유일한 이음매인RedisCommandGateway를 거치고, 모든 호출은 돌기 전에CommandPolicyGuard의 허가를 받는다. operation에서 driver를 직접 부르지 않는다.sdk.cluster는 client 쪽 slot 계산과 cluster 관찰을 가진다.sdk.api에만 의존하고 Lettuce를 import하지 않는다: slot을 명령을 만들기 전에 계산하므로CommandPolicyGuard가 서버 redirect로 알게 되기 전에 cross-slot 요청을 거절할 수 있다.sdk.programmability는 트랜잭션, 등록된 Lua script, 배포된 function 호출을 가진다. 호출 때 script 본문을 받지 않는다: catalog가EVAL을 막고RedisScriptRegistrydigest의EVALSHA만 닿을 수 있다.FUNCTION LOAD는 애플리케이션이 아니라 admin plane이다.- 트랜잭션은
WATCH/MULTI/EXEC이고 절대 롤백하지 않는다.TransactionResult는 「실행됨」이나 「감시한 키가 바뀌어서 아무것도 돌지 않음」만 알리고, 이 패키지의 어떤 타입도 다른 뜻을 비치는 말을 주지 않는다. 줄 세운 명령은QueuedReply를 돌려주고, 커밋 전에 읽으면 던진다. 그 창 안에서 서버는+QUEUED만 답했기 때문이다. 줄 세운 명령도 보통 명령과 같은CommandPolicyGuard허가를 지난다 — 트랜잭션은 guard를 피하는 길이 아니다 — 그리고 창은 던진 callback을 포함해 모든 출구에서 닫는다.MULTI상태로 버려진 연결은 다음 호출자의 명령을 소리 없이 줄 세우기 때문이다. queue는 일부러 쓰기 전용이다: 창 안의 읽기로는 분기할 수 없으니, 트랜잭션이 기대는 읽기는 그 앞에서WATCH아래에 둔다. sdk.raw는 승인된 raw 명령 gateway다. catalog가RAW_ONLY로 표시했고 그리고 배포가 그 명령에ApprovedRawCommand를 등록했을 때만 닿을 수 있다. 보내기 전에 인자에서 키를 다시 파싱해 namespace를 검사한다. 명령 이름을 문자열로 받는 메서드를 여기 더하지 않는다.sdk.admin은 읽기 전용 진단 plane이다. 자기 gateway(admin ACL 계정, 자기 연결)를 받고, catalog가ADMIN_ONLY이자 읽기 전용으로 분류하지 않은 명령은 모두 거절하며, slow log나 client 목록이 인자·상대 주소·연결 이름을 싣지 않게 응답을 걸러 낸다.sdk.extensions.*는 Redis 8 모듈(JSON, Search, Time Series, Probabilistic)을 담는다. 모든 bean은ifSupported(...)로 만든다 — capability probe가 정하고, catalog 최소값은 앞 걸러내기일 뿐이다 — 그리고 모두ExtensionCommandRunner로 명령을 만들어 guard가 그 키를 본다. Search는 이것을 보여 주는 예외다: index는 키가 아니라서 그 이름은LettuceRedisSearchOperations가 직접 namespace를 붙인다.RedisSdkModuleBoundaryTest(redis-sdk안)가redis-sdk소스 루트를 scan해 내부 패키지 그래프, driver 가두기, 아무 문자열 명령 surface 없음, 설계한 모듈 목록을 강제한다.- 설계를 다시 보지 않고 바꾸면 안 되는 결정: 한계 없는
entries,members,rangeAll,keys없음. 선택 사항인 R2 허가·예산 없음. 아무 명령 문자열을 받는 overload 없음. timeout 뒤 멱등이 아닌 쓰기의 자동 재시도 없음. metric이나 trace tag에 실제 키 없음.
경계
- 허용 의존 edge는 이 모듈의
src/config/architecture/modules.json항목에서만 온다. - inbound 전송, 영속 엔티티·repository, bootstrap, 샘플 의존이 없다.
- cache 어댑터는 업무상 신선도, 자격, 도메인 대체 규칙을 정하지 않는다.
- Redis 물리 TTL은 인코딩한 hard 만료와 같아야 한다. 미래·손상 schema가 보통 miss로 뭉개지면 안 된다.
- application·domain 코드는 raw Redis 키, 명령, Lua·Function 이름, SDK 객체, topology, 연결 타입을 받으면 안 된다.
- cache의 fail-open 동작을 session, 멱등성, 엄격한 quota, lease, fencing에 다시 쓰면 안 된다.
- rate-limit 조립은
app.cache.redis, 그 연결, 외부 client 모드, 실패하면 열리는 뜻을 다시 쓰면 안 된다. v1은 조율 role이고 실패하면 닫히는 것뿐이다. - standalone runtime·cache 서비스 lane은 R1 증거일 뿐이다. Sentinel·Cluster, TLS·ACL, 영속·재시작, eviction, 장애 증거는 R2를 위해 따로 필요하다.
테스트
이 모듈만 보는 시험은 semantic 어댑터를 testFixtures(project(':adapter:outbound:redis-runtime'))의
InMemorySemanticRedisCommands에 대고 돌린다. SemanticRedisCommands의 유일한 fake이고, StubRedisRuntimeClient를
거쳐 쓴다. R1·R2 승격에는 따로 실제 Redis 서비스 lane이 필요하다. 그 lane을 골랐으면 소리 없이 건너뛰면 안 된다.
실제 서버 lane이 둘 있다. redisContainerContractTest(integration category, integrationCheck에만 있다 — 이 leaf의
mainCheck에도 있었을 때는 main push마다 두 번 돌았다)는 Testcontainers로 자기 Redis를 띄운다 —
config/testing/container-images.properties의 redis image이고 compose/redis/acl/lane-fixture-accounts.acl을
읽어 들인다 — 그리고 LiveRedisCacheRegionContractTest, LiveRedisDistributedLeaseContractTest,
LiveRedisIdempotencyStoreContractTest(메모리 fake도 통과하는 application-core 포트 계약),
LiveRedisSemanticPortsTest, LiveRedisSemanticScriptAclProbeTest를 돌린다. 건너뛰기가 있으면 실패한다
(2026-11-01부터). 멱등성 계약은 2026-11-03까지 명시할 때만 도는 topology lane에만 있었다. 그래서 Lua 상태 기계의
낡은 handle, 갱신 거절, 재시도 경우가 어느 게이트에서도 실제 서버에 닿지 않았다. RedisTestContainer는 그 lane이
ACL 파일을 이름으로 댈 때만 서버를 띄운다.
redisTopologyTest는 외부 topology lane이고 ca.redis-topology-lane으로 선언한다. 이 leaf는 standalone과
cluster(LiveRedisSemanticPortsTest, LiveRedisSemanticScriptAclProbeTest)를 선언한다. redis-runtime과
redis-sdk는 자기 클래스에 대해 자기 lane을 선언한다. 고를 때만 돌고 실패하면 닫힌다: 모드는 standalone,
sentinel, cluster, tls 중 이 leaf가 선언한 것이어야 하고, endpoint 속성이 있어야 하며(sentinel은
redis.topology.master가, tls는 redis.topology.trust-material이 더 필요하다), 시험을 하나도 찾지 못하거나
돌리지 않은 실행은 실패하고(그것은 이 leaf가 아니라 규약이 가진다), leaf가 redisTopologyLane에 적은 클래스가
실제로 돌았어야 하며, 건너뛴 시험은 실행한 것으로 세지 않고 실행을 실패시킨다. tls는 배포 모드가 아니라
lane이다 — 모양은 standalone이고 태스크가 그렇게 대응시킨다. 검증하는 것이 전송이기 때문이다.
예전 검사 둘은 없어졌다. 시험 소스에서 글자 그대로 @Tag("redis-topology")를 찾는 scan은
failOnNoDiscoveredTests가 이미 내는 실패의 메시지를 낫게 할 뿐이었고, 같은 글을 담은 주석으로도 만족됐다. 손으로
관리하던 모드별 실행 수 하한(20/20/24/4)은 경우를 더하거나 뺄 때마다 고쳐야 했고, 그것이 잡는 「덮는 범위가
줄었다」는 런타임·배포·데이터·보안·컴파일 실패가 아니다.
조립
RedisRuntimeAutoConfiguration은 이제 :adapter:outbound:redis-runtime의 것이다. Redis 설정과 공용 runtime 기반이
생기는 유일한 곳이고, app.redis.enabled(env APP_REDIS_ENABLED, 기본 true — 모듈이 있으면 켜진다)가 true인
동안에만 있다. topology client, 연결 owner, health contributor를 만든다. 이 leaf의 RedisCapabilityConfig(자기
AutoConfiguration.imports)가 그 runtime 위에 semantic 포트를 조립한다.
골라 쓰는 :adapter:outbound:redis-sdk는 출하하는 애플리케이션이 자동으로 조립하지 않는다. 그
RedisStartupProbe는 라이브러리 API이고 숨은 운영 guard가 아니다. 특히 APP_REDIS_ACKNOWLEDGED_WRITE_LOSS_ACCEPTED
스위치는 없다: 그 거래를 받아들이는 것은 운영 호출자가 없는 공개 설정이 아니라 probe를 부르는 곳의 명시한 인자여야
한다.
모든 capability는 CapabilityKeyspace를 거쳐 app.redis.namespace의 namespace 하나 —
{environment}:{service}:{domain} — 아래에 키를 만든다. capability에 자기 접두어 token을 주지 않는다: capability 넷이
각자 자유 문자열 둘을 이어 붙였더니 키 모양이 넷이 됐고, 배포의 ACL pattern은 그중 어느 것과도 맞지 않았다.
lane은 서로 다른 계정으로 인증한다. RedisLane.account()가 lane의 RedisAccount를 이름으로 대고, topology factory는
설정한 계정마다 client를 하나 만든다 — 그래서 계정이 하나인 배포는 여전히 client 하나와 event loop 하나만 가진다.
SCRIPT lane이 그것이 있는 이유다: SCRIPT LOAD와 EVALSHA는 advanced 계정의 것이라서, cache 항목을 읽는 계정은
script를 실행할 수 없다.
cache의 조건부 쓰기는 같은 계정이지만 자기 lane CacheScriptLane.CACHE_SCRIPT에서 돈다
(app.capabilities.cache.maximum-script-connections, RedisCacheConfig가 RedisLaneContribution으로 기여한다).
SCRIPT로 되돌리지 않는다: 그 lane은 멱등성·rate-limit·lease의 예산이고, 부하를 받는 cache가 그것을 가져가면
안 된다(2026-11-03에 정함). lane마다 기다림, 거절, 재연결은 redis-runtime의 meter(RedisLaneMetrics, redis.lane.*,
tag lane)이다. 그래서 cache가 SCRIPT를 쓰지 않는지는 짐작이 아니라 조회로 안다. DEGRADED health 순서는
redis-runtime과 함께 나가고, 그 leaf가 상태를 알린다(config/module-defaults/redis-runtime.yml).
Cluster 트랜잭션은 노드 하나에서 돈다. 그래서 SDK의 RedisTransactionRunner는 감시한 키(또는 명시한
RedisSlotTag)에서 routing 키를 끌어내고, 그 slot을 가진 노드에서 키의 주인에 고정된 RedisSdkLane.TRANSACTION을
빌린다. route된 lease는 pool에 두지 않는다: pool에 둔 연결은 앞 호출자의 노드에 고정되어 있다.
설정 바인딩은 capability 기준 4(접두어 하나, StrictSettingsBinder)의 기록된 예외다(2026-11-03에 정함):
app.redis.*는 redis-runtime이 setter와 validate()로 바인딩한다. 그 leaf는 프로젝트 의존이 없어서
StrictSettingsBinder(support)에 닿을 수 없기 때문이다. app.capabilities.*(cache, lease, rate-limit provider)는 이
leaf가 공용 capability 선택 루트 아래에서 엄격하게 바인딩한다. app.rate-limit.*은 이 leaf가 읽기만 하는 HTTP
경계의 스위치다. 키 이름을 바꾸면 동작 이득 없이 모든 배포의 환경이 깨지니 세 트리를 그대로 둔다. 새 Redis 설정은
그중 하나에 넣고, 네 번째 트리를 만들지 않는다.
RedisRuntimeSettings에는 클래스 수준 @ConfigurationProperties를 달면 안 된다: RedisRuntimeAutoConfiguration이
그것을 바인딩하므로 APP_REDIS_ENABLED=false이면 Redis 설정을 하나도 바인딩하지 않는다. 이 패키지에 닿는
properties scan은 그래도 그것을 바인딩하게 된다(bootstrap의 @ConfigurationPropertiesScan은
dev.caskeleton.bootstrap.* 패키지만 적는다). role 선택자(cache 바인딩, session 인증 모드, 멱등성·lease·rate-limit
provider)는 어떤 capability를 조립할지 고른다. 그중 어느 것도 Redis를 켜지 않고, 전역 스위치가 꺼져 있으면 이
모듈은 bean을 하나도 기여하지 않는다.