# Redis SDK 지원 매트릭스 이 파일은 요약이 아니라 관문이다. `RedisSupportMatrixTest`가 아래 표를 파싱하고, SDK에 표에 없는 package나 capability가 생기면 실패한다. 그래서 누군가 최소 버전, 토폴로지 지원, 하지 않는 것을 밝히기 전에는 모듈을 내보낼 수 없다. 표의 첫 칸(package 이름, capability 이름, 토폴로지 이름)은 테스트가 그대로 읽으므로 원문으로 둔다. 설계서: `docs/design/2026-08-07-redis-wrapper-typed-api-design.md`. 납품 상태와 모듈마다의 결정: `docs/history/plans/2026-08-07-redis-wrapper-typed-api-status.md`. ## 모듈 | 모듈 | 최소 Redis | 토폴로지 | 위험 노출 | Sync | Reactive | 알려진 한계 | | --- | --- | --- | --- | --- | --- | --- | | `api` | 7.2 | 전부 | 없음 | 해당 없음 | 해당 없음 | 계약만. driver 타입 없음 | | `api/key` | 7.2 | 전부 | 없음 | 해당 없음 | 해당 없음 | slot tag는 가짓수가 적어야 한다 | | `api/codec` | 7.2 | 전부 | 없음 | 해당 없음 | 해당 없음 | Java native 직렬화 없음 | | `api/command` | 7.2 | 전부 | 없음 | 해당 없음 | 해당 없음 | 허가는 ACL 계정을 절대 넓히지 않는다 | | `api/error` | 7.2 | 전부 | 없음 | 해당 없음 | 해당 없음 | 실패 metadata에 key나 value가 없다 | | `api/operations` | 7.2 | 전부 | 없음 | 해당 없음 | 해당 없음 | 계약만 | | `api/reactive` | 7.2 | 전부 | 없음 | 해당 없음 | 해당 없음 | Reactor는 이 package 안에만 | | `lettuce` | 7.2 | 전부 | R1–R2 | 됨 | 됨 | Lettuce 버전은 Boot BOM이 정한다(실제 버전은 leaf `gradle.lockfile`) | | `lettuce/codec` | 7.2 | 전부 | 없음 | 됨 | 됨 | UTF-8과 byte array codec만 | | `lettuce/command` | 7.2 | 전부 | R1–R2 | 됨 | 됨 | 정책 목록이 유일한 명령 권한이다 | | `lettuce/connection` | 7.2 | 전부 | 없음 | 됨 | 됨 | lane 다섯. blocking 작업은 보통 lane을 절대 같이 쓰지 않는다 | | `lettuce/observability` | 7.2 | 전부 | 없음 | 됨 | 됨 | 명령 계열만. key는 절대 없다 | | `lettuce/operations` | 7.2 | 전부 | R1–R2 | 됨 | 됨 | hash field TTL은 7.4, sharded pub/sub은 7.0, stream 삭제는 8.2가 필요하다 | | `config` | 7.2 | 전부 | 없음 | 해당 없음 | 해당 없음 | 허가 출처는 프로세스마다 HMAC 서명한다 | | `cluster` | 7.2 | cluster | 없음 | 해당 없음 | 해당 없음 | slot 산수만. redirect를 따라가지 않는다 | | `programmability` | 7.2 | 전부 | R2 | 됨 | 안 됨 | transaction은 절대 되돌리지 않는다. script는 bulk 답 하나를 돌려준다. `FUNCTION LOAD`는 admin plane이다 | | `raw` | 7.2 | 전부 | R2 | 됨 | 안 됨 | `RAW_ONLY` 명령만. movable key 명세는 승인할 수 없다 | | `admin` | 7.2 | 전부 | R3 읽기 전용 | 됨 | 안 됨 | 답은 투영한다. 파괴적인 명령은 없다 | | `extensions` | 8.0 | 전부 | 없음 | 됨 | 안 됨 | 공용 명령 실행기. extension마다 자기 key를 선언한다 | | `extensions/json` | 8.0 | 전부 | R1–R2 | 됨 | 안 됨 | 좁은 JSONPath 문법. 문서는 text로 주고받는다 | | `extensions/search` | 8.0 | 전부 | R2 | 됨 | 안 됨 | index 이름은 SDK가 namespace를 붙인다. index 지우기 없음 | | `extensions/timeseries` | 8.0 | 전부 | R1–R2 | 됨 | 안 됨 | 만들 때 보존 기간이 필수다 | | `extensions/probabilistic` | 8.0 | 전부 | R1–R2 | 됨 | 안 됨 | 모든 답은 만든 방식상 근사값이다 | ## Capability | Capability | 최소 Redis | 관문 | 없을 때의 bean | | --- | --- | --- | --- | | `SHARDED_PUBSUB` | 7.0 | probe와 목록 최소 버전 | 없음 | | `FUNCTIONS` | 7.0 | probe와 목록 최소 버전 | 없음 | | `HASH_FIELD_EXPIRATION` | 7.4 | probe와 목록 최소 버전 | 없음 | | `HASH_FIELD_EXPIRATION_COMBINED` | 8.0 | probe와 목록 최소 버전 | 없음 | | `STREAM_ACKNOWLEDGE_DELETE` | 8.2 | probe와 목록 최소 버전 | 없음 | | `STREAM_NEGATIVE_ACKNOWLEDGE` | 8.8 | probe와 목록 최소 버전 | 없음. 아직 bean 자체가 없다 | | `JSON` | 8.0 | probe가 정한다 | 없음 | | `SEARCH` | 8.0 | probe가 정한다 | 없음 | | `TIME_SERIES` | 8.0 | probe가 정한다 | 없음 | | `PROBABILISTIC` | 8.0 | probe가 정한다 | 없음 | ## 인증한 버전 버전은 숫자가 더 새것이라서가 아니라 그 lane이 증거를 만들어서 인증된다. 여기의 증거 주장은 그것을 만든 테스트 클래스의 이름을 대야 한다. 다른 것을 주장하는 행이 있으면 `RedisSupportMatrixTest`가 빌드를 실패시킨다. 그래서 뒤에 테스트 없이 이 표에 「확인함」을 쓸 수 없다. 세 lane 모두 7.4에서 돌았다. 다른 선언 버전은 선언만 했고 인증하지 않았다. 이 저장소의 어떤 것도 7.2나 8.2에 대해 돈 적이 없다. | 토폴로지 | 선언한 버전 | 증거 상태 | | --- | --- | --- | | Standalone | 7.2, 7.4, 8.2 | 7.4에서 `RedisTopologyContractTest`, `LiveRedisGuardrailTest` | | Sentinel | 7.4, 8.2 | 7.4에서 `RedisTopologyContractTest`, `LiveRedisSentinelPromotionTest` | | Cluster | 7.4, 8.2 | 7.4에서 `RedisTopologyContractTest`, `LiveRedisClusterTest` | ### standalone ACL 실행이 밝힌 것 `RedisTopologyContractTest`는 `compose/redis/acl`의 계정 넷을 실제 서버에 대고 돌려, 각 `CommandAccess` 등급이 명령 정책 목록이 허락한 것을 정확히 주는지 단언한다. 이 테스트를 쓰면서 파일을 아무리 읽어도 드러나지 않았을 결함 일곱을 찾았다. 1. Redis ACL 파일은 주석도 줄 이음도 받지 않는다. 원래 파일은 아예 불러와지지 않았고 서버가 시작을 거부했다. 2. advanced 계정이 `SMEMBERS`와 `SORT`를 허락했다. 둘 다 `RAW_ONLY`라서 raw gateway 계정만 가져야 한다. 3. 보통 계정이 같은 이유로 `SORT_RO`를 허락했다. 4. 보통 계정이 `TYPED`로 분류된 `PUBLISH`, `SUBSCRIBE`, `PING`을 실행할 수 없었다. 5. 보통 계정이 역시 `TYPED`인 `MULTI`, `EXEC`, `UNWATCH`, `DISCARD`를 실행할 수 없었다. 6. admin 계정에 목록이 내놓는 읽기 전용 진단 열두 개가 빠져 있었다. `OBJECT`, `PUBSUB`, `XINFO`, `FUNCTION LIST`/`STATS`, `CLUSTER KEYSLOT` 하위 명령이다. 7. cursor scan 답 예산을 요청한 `COUNT`에 맞췄는데, Redis는 그것을 힌트로만 본다. 실제 `HSCAN COUNT 500`이 항목 501개로 돌아왔고 SDK가 맞는 답을 거부했다. 중요한 것은 2와 3이다. 계정이 마지막 강제 경계라서, 목록보다 넓은 계정은 설계가 기대는 두 번째 통제를 조용히 없앤다. ### standalone guardrail 실행이 밝힌 것 `LiveRedisGuardrailTest`는 실제 guard, 목록, 타입 있는 연산을 실제 서버에 잇는다. 명령을 인코딩하는 유일한 클래스인 `LettuceRedisCommandGateway`가 메모리 안 대역이 아니라 SDK 자신의 계약 아래에서 처음 돈 것이다. 계획서의 데이터셋을 싣는다: 1 MiB 상한의 값, field 십만 개짜리 hash, member 십만 개짜리 set과 sorted set, 원소 이만 개짜리 list, 항목 이만 개를 덧붙이는 동안 1,000으로 잘리는 stream, 명령 오백 개짜리 batch. 단언은 처리량이 아니라 한도가 지켜지는지에 관한 것이다. 절대 속도를 재는 guardrail 테스트는 부하 걸린 노트북에서 실패하고 아무것도 가르쳐 주지 않는다. ### Sentinel 승격 실행이 밝힌 것 `LiveRedisSentinelPromotionTest`는 실제 승격을 한 번 일으키고, 그에 대한 독립된 주장 여럿을 단언한다. 모든 쓰기는 그 실행에만 있는 token을 싣는다. 그래서 승격된 primary의 list가 일어난 일을 글자 그대로 기록하고, 호출마다의 판정을 그것과 대조할 수 있다. 이 납품에서 가장 심각한 결함을 찾았는데, SDK 코드에 있지 않다. > **교체된 primary가 계속 쓰기를 확인한다.** Sentinel은 `05:56:12.503`에 replica를 승격하고 `05:56:23.529`까지 옛 > primary를 내리지 않았다. 그 11초 동안 아직 연결된 client가 썼고 `+OK`를 **2,086번** 받았다. 옛 primary가 새 primary에서 > 다시 동기화할 때 그 쓰기는 모두 버려졌다. 실패한 명령은 정확히 **하나**였다. client 쪽 신호는 없다. 서버가 답했으니 > driver, SDK, 호출자 모두 성공을 맞게 기록했다. `SentinelFailoverObserver`는 *결과를 모르는* 쓰기를 센다. 그 문서는 예전에 그것을 「운영자가 맞춰 봐야 하는 것」이라고 불렀다. 세 자릿수만큼 틀렸고, 지금은 클래스가 그렇다고 말한다. 구간을 닫는 것은 client가 아니라 서버에 있다. `min-replicas-to-write 1`과 `min-replicas-max-lag 1`을 설정하고 똑같은 승격을 다시 돌리자, 확인했다가 버려진 쓰기가 **2,086개에서 1개**로 줄었다. 외톨이가 된 primary가 2,020개를 `NOREPLICAS`로 거부했고, SDK는 그것을 호출자가 대응할 수 있는 결과가 분명한 실패로 바꾼다. 두 설정은 이제 lane에 있고, `acknowledgedWriteLossIsBounded`가 허용하는 손실을 설정한 lag 구간에 묶는다. 그래서 설정을 빼면 수가 한 자릿수 이상 뛰고 테스트가 실패한다. 그 단언은 쓴 지 하루 만에 같은 실수의 두 번째 판을 잡았다. 첫 보호 실행은 통과했는데 둘째는 버려진 쓰기 2,099개로 실패했다. 설정을 lane의 `primary` 서비스에만 썼기 때문이다. 두 데이터 노드는 failover마다 역할을 바꾼다. 그래서 마침 primary로 시작한 쪽에만 건 보호 장치는 lane이 존재 이유인 일을 하는 순간 적용되지 않는다. 이제 두 노드 모두 정의 하나에서 설정 전체를 받는다. 그 뒤로 양쪽 방향의 연속 승격 세 번에서 확인했다가 잃은 쓰기는 0, 0, 1개였다. 이 실행은 변환기 결함도 찾았다. 승격이 진행 중인 `RPUSH` 아래의 channel을 닫았고, driver는 맨 `RedisException`을 던졌다. 그것은 어느 분기에도 맞지 않아 *확실히 실행되지 않음*으로 보고하는 일반 실패로 떨어졌다. 알아보지 못한 실패는 그 주장을 뒷받침하지 않고, 그것을 믿는 호출자는 멱등이 아닌 쓰기를 재시도한다. 지금은 분류하지 못한 쓰기 실패를 결과 모름으로 다룬다. ### Cluster 실행이 밝힌 것 `LiveRedisClusterTest`는 `sdk.cluster` 중 순수한 client 쪽 산수인 부분을 마지막 결정권을 가진 서버와 대조한다. 손으로 쓴 구현이 틀리는 중괄호 규칙으로 만든 묶음 — 빈 tag `{}`, `foo{}{bar}`, `foo{{bar}}zap`, 닫히지 않은 중괄호, `}{`, 빈 key, ASCII가 아닌 key — 의 모든 항목에서 계산기가 `CLUSTER KEYSLOT`과 같은 답을 냈다. 그리고 그린 key 불변식이 지켜진다. SDK가 tag만으로 계산한 slot이 서버가 그린 key 전체로 계산한 slot과 같다. slot을 넘는 거부는 양쪽 방향으로 확인했다. cluster보다 엄격한 guard는 이유 없이 가용성을 깎고, 느슨한 guard는 성공할 수 없는 요청을 보낸다. guard가 거부하는 key 쌍이 서버가 `CROSSSLOT`으로 답하는 쌍과 같다. redirect는 가정하지 않고 관측했다. `MOVED`는 client가 계산한 slot을 이름 댄다. 실제 `MIGRATING`/`IMPORTING` 상태로 둔 slot은 없는 key에 `ASK`로, 이동에 걸친 여러 key 요청에 `TRYAGAIN`으로 답한다. lane은 그 뒤 slot을 `STABLE`로 되돌린다. 그래서 실행이 cluster를 처음 상태 그대로 남긴다.