diff --git a/docs/redis/command-policy.md b/docs/redis/command-policy.md index 2aa5c325..10cba411 100644 --- a/docs/redis/command-policy.md +++ b/docs/redis/command-policy.md @@ -1,49 +1,48 @@ -# Command policy +# 명령 정책 -`src/adapter/outbound/redis-sdk/src/main/resources/redis-sdk/redis-command-policy.yml` is the -single source of truth for what this SDK is willing to do with each Redis command. Official server -metadata decides what a command *is*; this file decides what we allow. +`src/adapter/outbound/redis-sdk/src/main/resources/redis-sdk/redis-command-policy.yml`이 이 SDK가 Redis 명령마다 +무엇을 해도 되는지 정하는 유일한 정본이다. 명령이 *무엇인지*는 공식 서버 metadata가 정하고, 무엇을 허락할지는 이 +파일이 정한다. -A command that is not classified there is refused. Adding a command therefore means editing that -file, not writing code — and the edit is where the risk decision is made and reviewed. +거기에 분류되지 않은 명령은 거부한다. 그래서 명령을 더하는 것은 코드를 쓰는 일이 아니라 그 파일을 고치는 일이고, 위험 +판단을 내리고 검토하는 곳이 그 수정이다. -## Fields +## 필드 -| Field | Default | Meaning | +| 필드 | 기본값 | 뜻 | | --- | --- | --- | -| `risk` | required | `R1` routine, `R2` needs an explicit permit, `R3` administrative, `R4` never allowed | -| `support` | required | `TYPED`, `ADVANCED_TYPED`, `RAW_ONLY`, `ADMIN_ONLY`, `VERSION_GATED`, `BLOCKED` | -| `minimum-version` | `7.2` | lowest server version that carries the command | -| `access` | derived from `support` | which ACL account may issue it | -| `blocking` | `false` | occupies its connection until the server replies | -| `optional-block` | `false` | the command also has a non-blocking form; only `XREAD` and `XREADGROUP` carry it | -| `read-only` | `false` | never mutates the dataset | -| `retry-safe` | `read-only` | may be retried after a failure that could have reached the server | -| `may-be-ambiguous` | `!read-only` | a failure may leave the outcome unknown | -| `timeout-profile` | derived | `FAST`, `COLLECTION`, `ADMIN`, `BLOCKING` | -| `key-spec` | `1 1 1` | where the keys are, or `none`, or `movable` | -| `required-policy` | – | the permit policy an R2 command demands | +| `risk` | 필수 | `R1` 일상, `R2` 명시적 허가 필요, `R3` 관리, `R4` 절대 허락 안 함 | +| `support` | 필수 | `TYPED`, `ADVANCED_TYPED`, `RAW_ONLY`, `ADMIN_ONLY`, `VERSION_GATED`, `BLOCKED` | +| `minimum-version` | `7.2` | 그 명령이 있는 가장 낮은 서버 버전 | +| `access` | `support`에서 정함 | 어느 ACL 계정이 보낼 수 있는지 | +| `blocking` | `false` | 서버가 답할 때까지 connection을 잡는다 | +| `optional-block` | `false` | 그 명령에 blocking 아닌 형태도 있다. `XREAD`와 `XREADGROUP`만 가진다 | +| `read-only` | `false` | 데이터를 절대 바꾸지 않는다 | +| `retry-safe` | `read-only` | 서버에 닿았을 수 있는 실패 뒤에도 재시도해도 된다 | +| `may-be-ambiguous` | `!read-only` | 실패가 결과를 모르는 상태로 남길 수 있다 | +| `timeout-profile` | 정함 | `FAST`, `COLLECTION`, `ADMIN`, `BLOCKING` | +| `key-spec` | `1 1 1` | key가 있는 곳. 또는 `none`, `movable` | +| `required-policy` | – | R2 명령이 요구하는 허가 정책 | -## Rules the catalog enforces +## 목록이 강제하는 규칙 -- An R2 `ADVANCED_TYPED` command must name the permit policy it requires. There is no R2 command - that anyone may issue without an issued permit. -- An R4 command must be `BLOCKED`, and an R3 command must be `ADMIN_ONLY`. The type system refuses - the other combinations at load time. -- A `BLOCKED` command carries no ACL account, so no path in the SDK can reach it. -- A blocking command must use the `BLOCKING` timeout profile, and its request must declare a bounded - server block — unless it also declares `optional-block`, which only the two stream reads do. -- Deprecated command names stay `BLOCKED` even when the SDK offers their behaviour. The typed - sorted-set ranges issue `ZRANGE ... BYSCORE|BYLEX|REV`, not `ZRANGEBYSCORE`, so what the guard was - told and what reaches the wire are the same command. +- R2 `ADVANCED_TYPED` 명령은 요구하는 허가 정책의 이름을 대야 한다. 발급한 허가 없이 누구나 보낼 수 있는 R2 명령은 + 없다. +- R4 명령은 `BLOCKED`여야 하고, R3 명령은 `ADMIN_ONLY`여야 한다. 그 밖의 조합은 불러올 때 타입 체계가 거부한다. +- `BLOCKED` 명령에는 ACL 계정이 없다. 그래서 SDK의 어떤 경로도 그것에 닿을 수 없다. +- blocking 명령은 `BLOCKING` timeout profile을 써야 하고, 그 요청은 상한 있는 서버 block을 선언해야 한다. + `optional-block`도 선언하면 예외인데, stream 읽기 둘만 그렇다. +- 폐기된 명령 이름은 SDK가 그 동작을 제공하더라도 `BLOCKED`로 남는다. 타입 있는 sorted-set 범위 조회는 + `ZRANGEBYSCORE`가 아니라 `ZRANGE ... BYSCORE|BYLEX|REV`를 보낸다. 그래서 guard가 들은 명령과 wire에 닿는 명령이 + 같다. -## Where each support level is reachable from +## 지원 등급마다 닿는 곳 -| Support | Reachable from | +| 지원 | 닿는 곳 | | --- | --- | -| `TYPED` | the typed operations, no permit | -| `ADVANCED_TYPED` | the typed operations, with the named permit | -| `VERSION_GATED` | a capability bean that exists only when the probe found the feature | -| `RAW_ONLY` | `sdk.raw`, and only with a deployment-registered approval | -| `ADMIN_ONLY` | `sdk.admin`, read-only diagnostics only | -| `BLOCKED` | nowhere | +| `TYPED` | 타입 있는 연산, 허가 없이 | +| `ADVANCED_TYPED` | 타입 있는 연산, 이름 댄 허가와 함께 | +| `VERSION_GATED` | probe가 그 기능을 찾았을 때만 있는 capability bean | +| `RAW_ONLY` | `sdk.raw`, 그리고 배포가 등록한 승인이 있을 때만 | +| `ADMIN_ONLY` | `sdk.admin`, 읽기 전용 진단만 | +| `BLOCKED` | 어디에도 없음 | diff --git a/docs/redis/operations.md b/docs/redis/operations.md index d0cbd6ef..11276dfa 100644 --- a/docs/redis/operations.md +++ b/docs/redis/operations.md @@ -1,75 +1,65 @@ -# Operating the Redis SDK +# Redis SDK 운영 -## What the metrics can and cannot tell you +## metric이 알려 줄 수 있는 것과 없는 것 -Every observation carries the command family, the deployment mode, and latency. None carries a key, -a field, a member, or a value — not because they would be large, but because a metric dimension -built from caller data is unbounded cardinality and, for most deployments, tenant identity in a -dashboard. +모든 관측은 명령 계열, 배포 방식, 지연을 담는다. key, field, member, value는 담지 않는다. 값이 커서가 아니라, 호출자 +데이터로 만든 metric 차원은 가짓수에 상한이 없고 대부분의 배포에서 dashboard에 tenant 식별자를 띄우기 때문이다. -That means you can answer "which command family is slow" and "which one is failing", and you cannot -answer "which key is hot" from metrics. Use the admin plane's `SLOWLOG` projection for the first -question and `MEMORY USAGE` on a specific key for the second. +그래서 metric으로 「어느 명령 계열이 느린가」와 「어느 것이 실패하나」에는 답할 수 있지만 「어느 key가 뜨거운가」에는 +답할 수 없다. 앞의 질문에는 admin plane의 `SLOWLOG` 투영을, 뒤의 질문에는 특정 key에 대한 `MEMORY USAGE`를 쓴다. -## The failures worth alerting on +## 경보를 걸 만한 실패 -| Signal | What it means | What to do | +| 신호 | 뜻 | 할 일 | | --- | --- | --- | -| `RedisCommandRejectedException` | the SDK refused before sending | a caller exceeded a declared bound; the reason names which one | -| `RedisCrossSlotException` | a multi-key command spans slots | the keys need a shared hash tag | -| `RedisAmbiguousExecutionException` | a write may or may not have applied | reconcile; the SDK will not retry it | -| `RedisCapabilityUnavailableException` | the server lacks the feature | a capability bean was constructed by hand, or the probe result changed | -| `SentinelFailoverObserver.ambiguousWriteCount` | non-idempotent writes lost to a promotion | each one needs reconciling; the count is the workload | -| `ClusterTopologyObserver.reshardingObserved` | `ASK`/`TRYAGAIN` seen | a slot migration is in progress; latency will be uneven until it ends | +| `RedisCommandRejectedException` | SDK가 보내기 전에 거부했다 | 호출자가 선언한 상한을 넘었다. 이유가 어느 것인지 이름을 댄다 | +| `RedisCrossSlotException` | 여러 key 명령이 slot을 넘는다 | key들이 같은 hash tag를 가져야 한다 | +| `RedisAmbiguousExecutionException` | 쓰기가 적용됐을 수도, 아닐 수도 있다 | 맞춰 본다. SDK는 재시도하지 않는다 | +| `RedisCapabilityUnavailableException` | 서버에 그 기능이 없다 | capability bean을 손으로 만들었거나 probe 결과가 바뀌었다 | +| `SentinelFailoverObserver.ambiguousWriteCount` | 승격 때문에 잃은 멱등이 아닌 쓰기 | 하나하나 맞춰 봐야 한다. 그 수가 일의 양이다 | +| `ClusterTopologyObserver.reshardingObserved` | `ASK`/`TRYAGAIN`을 봤다 | slot 이동이 진행 중이다. 끝날 때까지 지연이 고르지 않다 | -## Things the SDK will never do for you +## SDK가 절대 대신해 주지 않는 것 -- Retry a non-idempotent write after a timeout. `ExecutionCertainty.AMBIGUOUS_FAILURE` is reported, - not resolved. -- Follow a cross-slot multi-key command by splitting it. It is refused instead. -- Read a whole collection, stream, or index. Every read declares a bound. -- Load a Lua script or a function library at request time. Both are deployment actions. -- Send a command it cannot classify. -- Tell you that an acknowledged write was lost. See below — this one is not a limitation you can - work around in application code. +- 시간 초과 뒤 멱등이 아닌 쓰기를 재시도하기. `ExecutionCertainty.AMBIGUOUS_FAILURE`를 보고할 뿐 풀지 않는다. +- slot을 넘는 여러 key 명령을 나눠서 따라가기. 대신 거부한다. +- collection, stream, index 전체를 읽기. 모든 읽기는 상한을 선언한다. +- 요청 시점에 Lua script나 function library를 불러오기. 둘 다 배포 작업이다. +- 분류할 수 없는 명령 보내기. +- 확인 응답을 받은 쓰기를 잃었다고 알려 주기. 아래를 본다. 애플리케이션 코드로 돌아갈 수 있는 한계가 아니다. -## The write loss the client cannot see +## client가 볼 수 없는 쓰기 손실 -Set these on every Redis node that can ever be a primary: +primary가 될 수 있는 모든 Redis 노드에 이것을 둔다. ``` min-replicas-to-write 1 min-replicas-max-lag 1 ``` -Without them a Sentinel promotion silently destroys acknowledged writes, and this is measured, not -theoretical. In `LiveRedisSentinelPromotionTest` on the 7.4 lane, Sentinel promoted the replica and -did not demote the old primary for **eleven seconds**. The client stayed connected to a primary that -had already been replaced, wrote, and was told `+OK` **2,086 times**. Every one of those writes was -discarded when the old primary resynced. Exactly one command failed. +이것이 없으면 Sentinel 승격이 확인 응답을 받은 쓰기를 조용히 없앤다. 이론이 아니라 잰 것이다. 7.4 lane의 +`LiveRedisSentinelPromotionTest`에서 Sentinel은 replica를 승격하고 옛 primary를 **11초** 동안 내리지 않았다. client는 +이미 교체된 primary에 연결된 채 썼고, `+OK`를 **2,086번** 받았다. 옛 primary가 다시 동기화할 때 그 쓰기는 모두 버려졌다. +실패한 명령은 정확히 하나였다. -Nothing on the client can detect this. The server answered, so the driver recorded a success, the -SDK recorded `CONFIRMED_SUCCESS`, and the caller was told the write landed. No metric here counts -it, `SentinelFailoverObserver` cannot count it, and no retry policy helps — there was no failure to -react to. A second run of the same promotion produced sixteen thousand writes, **zero** exceptions, -and the same silent loss. +client 쪽에서는 아무것도 이것을 알아챌 수 없다. 서버가 답했으니 driver는 성공을 기록했고, SDK는 +`CONFIRMED_SUCCESS`를 기록했고, 호출자는 쓰기가 들어갔다고 들었다. 여기의 어떤 metric도 그것을 세지 않고, +`SentinelFailoverObserver`도 셀 수 없고, 어떤 재시도 정책도 돕지 못한다. 반응할 실패가 없었다. 같은 승격을 두 번째로 +돌렸을 때는 쓰기 만 육천 개, 예외 **0**개, 그리고 같은 조용한 손실이 나왔다. -With the two settings, the identical promotion lost **one** write and refused 2,020 with -`NOREPLICAS`, which the SDK reports as a definite, non-ambiguous failure the caller can act on. That -is the whole difference: an outage you can see instead of data you cannot. +두 설정을 두자 똑같은 승격에서 잃은 쓰기는 **하나**였고, 2,020개는 `NOREPLICAS`로 거부됐다. SDK는 그것을 호출자가 +대응할 수 있는, 결과가 분명한 실패로 보고한다. 차이는 그것이 전부다. 볼 수 없는 데이터 대신 볼 수 있는 장애다. -The residual window is `min-replicas-max-lag` wide and cannot be closed by configuration alone. A -write that must survive a promotion under any circumstances needs `WAIT` after it, at the cost of a -round trip to the replica — decide that per write, not globally. +남은 구간은 `min-replicas-max-lag`만큼이고 설정만으로는 닫을 수 없다. 어떤 경우에도 승격을 견뎌야 하는 쓰기는 그 뒤에 +`WAIT`가 필요하고, replica까지 왕복하는 비용이 든다. 전역이 아니라 쓰기마다 정한다. -## Blocking work +## Blocking 작업 -Blocking pops and blocking stream reads run on a dedicated connection lane. If those saturate, the -symptom is blocking calls timing out while ordinary traffic is healthy — that is the lane doing its -job, not a fault. Size the blocking pool to the number of concurrent consumers, not to request rate. +blocking pop과 blocking stream 읽기는 전용 connection lane에서 돈다. 그것이 가득 차면 보통 트래픽은 건강한데 blocking +호출만 시간 초과가 나는 증상이 보인다. lane이 제 일을 하는 것이지 결함이 아니다. blocking pool은 요청률이 아니라 동시 +소비자 수에 맞춘다. ## Pub/Sub -At-most-once. A subscriber that reconnects misses whatever arrived while it was gone, and there is -no replay. Durable business events belong in a stream with a consumer group, which is at-least-once -and therefore requires idempotent consumers. +많아야 한 번(at-most-once)이다. 다시 연결한 구독자는 떠나 있던 동안 온 것을 놓치고, 다시 받을 길이 없다. 지속돼야 하는 +업무 이벤트는 consumer group이 있는 stream에 둔다. 그것은 적어도 한 번(at-least-once)이므로 멱등한 소비자가 필요하다. diff --git a/docs/redis/support-matrix.md b/docs/redis/support-matrix.md index 9a7bb58a..9702db78 100644 --- a/docs/redis/support-matrix.md +++ b/docs/redis/support-matrix.md @@ -1,159 +1,139 @@ -# Redis SDK support matrix +# Redis SDK 지원 매트릭스 -This file is a gate, not a summary. `RedisSupportMatrixTest` parses the tables below and fails when -the SDK grows a package or a capability that is not listed, so a module cannot ship without someone -stating its minimum version, its topology support, and what it does not do. +이 파일은 요약이 아니라 관문이다. `RedisSupportMatrixTest`가 아래 표를 파싱하고, SDK에 표에 없는 package나 +capability가 생기면 실패한다. 그래서 누군가 최소 버전, 토폴로지 지원, 하지 않는 것을 밝히기 전에는 모듈을 내보낼 수 +없다. 표의 첫 칸(package 이름, capability 이름, 토폴로지 이름)은 테스트가 그대로 읽으므로 원문으로 둔다. -Design: `docs/design/2026-08-07-redis-wrapper-typed-api-design.md`. -Delivery status and the decisions behind each module: `docs/history/plans/2026-08-07-redis-wrapper-typed-api-status.md`. +설계서: `docs/design/2026-08-07-redis-wrapper-typed-api-design.md`. +납품 상태와 모듈마다의 결정: `docs/history/plans/2026-08-07-redis-wrapper-typed-api-status.md`. -## Modules +## 모듈 -| Module | Minimum Redis | Topology | Risk exposure | Sync | Reactive | Known limitations | +| 모듈 | 최소 Redis | 토폴로지 | 위험 노출 | Sync | Reactive | 알려진 한계 | | --- | --- | --- | --- | --- | --- | --- | -| `api` | 7.2 | all | none | n/a | n/a | contract only; no driver types | -| `api/key` | 7.2 | all | none | n/a | n/a | slot tags must be low-cardinality | -| `api/codec` | 7.2 | all | none | n/a | n/a | no Java native serialization | -| `api/command` | 7.2 | all | none | n/a | n/a | permits never widen the ACL account | -| `api/error` | 7.2 | all | none | n/a | n/a | failure metadata carries no key or value | -| `api/operations` | 7.2 | all | none | n/a | n/a | contract only | -| `api/reactive` | 7.2 | all | none | n/a | n/a | Reactor confined to this package | -| `lettuce` | 7.2 | all | R1–R2 | yes | yes | pinned to Lettuce 6.8.2 | -| `lettuce/codec` | 7.2 | all | none | yes | yes | UTF-8 and byte array codecs only | -| `lettuce/command` | 7.2 | all | R1–R2 | yes | yes | policy catalog is the only command authority | -| `lettuce/connection` | 7.2 | all | none | yes | yes | five lanes; blocking work never shares the regular lane | -| `lettuce/observability` | 7.2 | all | none | yes | yes | command family only, never a key | -| `lettuce/operations` | 7.2 | all | R1–R2 | yes | yes | hash field TTL needs 7.4; sharded pub/sub needs 7.0; stream deletion needs 8.2 | -| `config` | 7.2 | all | none | n/a | n/a | permit provenance is HMAC-signed per process | -| `cluster` | 7.2 | cluster | none | n/a | n/a | slot arithmetic only; no redirect following | -| `programmability` | 7.2 | all | R2 | yes | no | transactions never roll back; scripts return one bulk reply; `FUNCTION LOAD` is admin-plane | -| `raw` | 7.2 | all | R2 | yes | no | `RAW_ONLY` commands only; movable key specs unapprovable | -| `admin` | 7.2 | all | R3 read-only | yes | no | replies are projected; no destructive command exists | -| `extensions` | 8.0 | all | none | yes | no | shared command runner; every extension declares its key | -| `extensions/json` | 8.0 | all | R1–R2 | yes | no | narrow JSONPath grammar; documents exchanged as text | -| `extensions/search` | 8.0 | all | R2 | yes | no | index names namespaced by the SDK; no drop index | -| `extensions/timeseries` | 8.0 | all | R1–R2 | yes | no | retention mandatory at creation | -| `extensions/probabilistic` | 8.0 | all | R1–R2 | yes | no | every answer is approximate by construction | +| `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 | 됨 | 안 됨 | 모든 답은 만든 방식상 근사값이다 | -## Capabilities +## Capability -| Capability | Minimum Redis | Gate | Bean when absent | +| Capability | 최소 Redis | 관문 | 없을 때의 bean | | --- | --- | --- | --- | -| `SHARDED_PUBSUB` | 7.0 | probe and catalog minimum | none | -| `FUNCTIONS` | 7.0 | probe and catalog minimum | none | -| `HASH_FIELD_EXPIRATION` | 7.4 | probe and catalog minimum | none | -| `HASH_FIELD_EXPIRATION_COMBINED` | 8.0 | probe and catalog minimum | none | -| `STREAM_ACKNOWLEDGE_DELETE` | 8.2 | probe and catalog minimum | none | -| `STREAM_NEGATIVE_ACKNOWLEDGE` | 8.8 | probe and catalog minimum | none, and no bean exists yet | -| `JSON` | 8.0 | probe is authoritative | none | -| `SEARCH` | 8.0 | probe is authoritative | none | -| `TIME_SERIES` | 8.0 | probe is authoritative | none | -| `PROBABILISTIC` | 8.0 | probe is authoritative | none | +| `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가 정한다 | 없음 | -## Certified versions +## 인증한 버전 -A version is certified by its lane producing evidence, not by the version number being newer. An -evidence claim here must name the test class that produced it; `RedisSupportMatrixTest` fails the -build on a row that claims anything else, so "verified" cannot be written into this table without a -test behind it. +버전은 숫자가 더 새것이라서가 아니라 그 lane이 증거를 만들어서 인증된다. 여기의 증거 주장은 그것을 만든 테스트 +클래스의 이름을 대야 한다. 다른 것을 주장하는 행이 있으면 `RedisSupportMatrixTest`가 빌드를 실패시킨다. 그래서 뒤에 +테스트 없이 이 표에 「확인함」을 쓸 수 없다. -All three lanes have now run on 7.4. The other declared versions are declared, not certified: -nothing in this repository has executed against 7.2 or 8.2. +세 lane 모두 7.4에서 돌았다. 다른 선언 버전은 선언만 했고 인증하지 않았다. 이 저장소의 어떤 것도 7.2나 8.2에 대해 돈 +적이 없다. -| Topology | Versions declared | Evidence status | +| 토폴로지 | 선언한 버전 | 증거 상태 | | --- | --- | --- | -| Standalone | 7.2, 7.4, 8.2 | `RedisTopologyContractTest`, `LiveRedisGuardrailTest` on 7.4 | -| Sentinel | 7.4, 8.2 | `RedisTopologyContractTest`, `LiveRedisSentinelPromotionTest` on 7.4 | -| Cluster | 7.4, 8.2 | `RedisTopologyContractTest`, `LiveRedisClusterTest` on 7.4 | +| 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` | -### What the standalone ACL run established +### standalone ACL 실행이 밝힌 것 -`RedisTopologyContractTest` runs the four accounts in `compose/redis/acl` against a live server and -asserts that each `CommandAccess` level grants exactly what the command policy catalog says it may -issue. Writing it found five defects that no amount of reading the files would have surfaced: +`RedisTopologyContractTest`는 `compose/redis/acl`의 계정 넷을 실제 서버에 대고 돌려, 각 `CommandAccess` 등급이 명령 정책 +목록이 허락한 것을 정확히 주는지 단언한다. 이 테스트를 쓰면서 파일을 아무리 읽어도 드러나지 않았을 결함 일곱을 찾았다. -1. A Redis ACL file accepts neither comments nor line continuations — the original files did not load - at all, and the server refused to start. -2. The advanced account granted `SMEMBERS` and `SORT`, both `RAW_ONLY` and therefore the raw gateway - account's alone. -3. The ordinary account granted `SORT_RO` for the same reason. -4. The ordinary account could not run `PUBLISH`, `SUBSCRIBE`, or `PING`, all classified `TYPED`. -5. The ordinary account could not run `MULTI`, `EXEC`, `UNWATCH`, or `DISCARD`, also `TYPED`. +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가 맞는 답을 거부했다. -6. The admin account was missing twelve read-only diagnostics the catalog exposes — the `OBJECT`, - `PUBSUB`, `XINFO`, `FUNCTION LIST`/`STATS`, and `CLUSTER KEYSLOT` subcommands. +중요한 것은 2와 3이다. 계정이 마지막 강제 경계라서, 목록보다 넓은 계정은 설계가 기대는 두 번째 통제를 조용히 없앤다. -7. The cursor-scan reply budget was sized to the requested `COUNT`, which Redis treats as a hint — - a real `HSCAN COUNT 500` came back with 501 entries and the SDK refused a correct reply. +### standalone guardrail 실행이 밝힌 것 -Points 2 and 3 are the ones that matter: the account is the last enforcement boundary, so an account -wider than the catalog silently removes the second control the design relies on. +`LiveRedisGuardrailTest`는 실제 guard, 목록, 타입 있는 연산을 실제 서버에 잇는다. 명령을 인코딩하는 유일한 클래스인 +`LettuceRedisCommandGateway`가 메모리 안 대역이 아니라 SDK 자신의 계약 아래에서 처음 돈 것이다. 계획서의 데이터셋을 +싣는다: 1 MiB 상한의 값, field 십만 개짜리 hash, member 십만 개짜리 set과 sorted set, 원소 이만 개짜리 list, 항목 이만 +개를 덧붙이는 동안 1,000으로 잘리는 stream, 명령 오백 개짜리 batch. -### What the standalone guardrail run established +단언은 처리량이 아니라 한도가 지켜지는지에 관한 것이다. 절대 속도를 재는 guardrail 테스트는 부하 걸린 노트북에서 +실패하고 아무것도 가르쳐 주지 않는다. -`LiveRedisGuardrailTest` wires the real guard, catalog, and typed operations to a live server — -the first time `LettuceRedisCommandGateway`, the one class that encodes commands, runs under the -SDK's own contracts rather than against the in-memory stand-in. It carries the plan's datasets: a -value at the 1 MiB ceiling, a hundred-thousand-field hash, hundred-thousand-member set and sorted -set, a twenty-thousand-element list, a stream trimmed to 1,000 while twenty thousand entries are -appended, and a five-hundred-command batch. +### Sentinel 승격 실행이 밝힌 것 -The assertions are about limits holding, not throughput. A guardrail test that measured absolute -speed would fail on a loaded laptop and teach nobody anything. +`LiveRedisSentinelPromotionTest`는 실제 승격을 한 번 일으키고, 그에 대한 독립된 주장 여럿을 단언한다. 모든 쓰기는 그 +실행에만 있는 token을 싣는다. 그래서 승격된 primary의 list가 일어난 일을 글자 그대로 기록하고, 호출마다의 판정을 그것과 +대조할 수 있다. -### What the Sentinel promotion run established +이 납품에서 가장 심각한 결함을 찾았는데, SDK 코드에 있지 않다. -`LiveRedisSentinelPromotionTest` forces one real promotion and asserts several independent claims -about it. Every write carries a token unique to the run, so the list on the promoted primary is a -verbatim record of what happened and each per-call verdict can be checked against it. +> **교체된 primary가 계속 쓰기를 확인한다.** Sentinel은 `05:56:12.503`에 replica를 승격하고 `05:56:23.529`까지 옛 +> primary를 내리지 않았다. 그 11초 동안 아직 연결된 client가 썼고 `+OK`를 **2,086번** 받았다. 옛 primary가 새 primary에서 +> 다시 동기화할 때 그 쓰기는 모두 버려졌다. 실패한 명령은 정확히 **하나**였다. client 쪽 신호는 없다. 서버가 답했으니 +> driver, SDK, 호출자 모두 성공을 맞게 기록했다. -It found the most serious defect in this delivery, and it is not in the SDK's code: +`SentinelFailoverObserver`는 *결과를 모르는* 쓰기를 센다. 그 문서는 예전에 그것을 「운영자가 맞춰 봐야 하는 것」이라고 +불렀다. 세 자릿수만큼 틀렸고, 지금은 클래스가 그렇다고 말한다. -> **A superseded primary keeps acknowledging writes.** Sentinel promoted the replica at -> `05:56:12.503` and did not demote the old primary until `05:56:23.529` — eleven seconds in which -> the client, still connected, wrote and was told `+OK` **2,086 times**. Every one of those writes -> was discarded when the old primary resynced from the new one. Exactly **one** command failed. No -> client-side signal exists for this: the server answered, so the driver, the SDK, and the caller -> all correctly recorded a success. +구간을 닫는 것은 client가 아니라 서버에 있다. `min-replicas-to-write 1`과 `min-replicas-max-lag 1`을 설정하고 똑같은 +승격을 다시 돌리자, 확인했다가 버려진 쓰기가 **2,086개에서 1개**로 줄었다. 외톨이가 된 primary가 2,020개를 +`NOREPLICAS`로 거부했고, SDK는 그것을 호출자가 대응할 수 있는 결과가 분명한 실패로 바꾼다. 두 설정은 이제 lane에 있고, +`acknowledgedWriteLossIsBounded`가 허용하는 손실을 설정한 lag 구간에 묶는다. 그래서 설정을 빼면 수가 한 자릿수 이상 뛰고 +테스트가 실패한다. -`SentinelFailoverObserver` counts *ambiguous* writes, and its documentation used to call those "the -ones an operator has to reconcile". That was wrong by three orders of magnitude, and the class now -says so. +그 단언은 쓴 지 하루 만에 같은 실수의 두 번째 판을 잡았다. 첫 보호 실행은 통과했는데 둘째는 버려진 쓰기 2,099개로 +실패했다. 설정을 lane의 `primary` 서비스에만 썼기 때문이다. 두 데이터 노드는 failover마다 역할을 바꾼다. 그래서 마침 +primary로 시작한 쪽에만 건 보호 장치는 lane이 존재 이유인 일을 하는 순간 적용되지 않는다. 이제 두 노드 모두 정의 하나에서 +설정 전체를 받는다. 그 뒤로 양쪽 방향의 연속 승격 세 번에서 확인했다가 잃은 쓰기는 0, 0, 1개였다. -What closes the window is on the server, not the client. Re-running the identical promotion with -`min-replicas-to-write 1` and `min-replicas-max-lag 1` configured cut acknowledged-and-discarded -writes from **2,086 to 1**: the orphaned primary refused 2,020 writes with `NOREPLICAS`, which the -SDK translates to a definite, non-ambiguous failure the caller can act on. Both settings are now in -the lane, and `acknowledgedWriteLossIsBounded` ties the tolerated loss to the configured lag window, -so removing them makes the count jump by an order of magnitude and fails the test. +이 실행은 변환기 결함도 찾았다. 승격이 진행 중인 `RPUSH` 아래의 channel을 닫았고, driver는 맨 `RedisException`을 +던졌다. 그것은 어느 분기에도 맞지 않아 *확실히 실행되지 않음*으로 보고하는 일반 실패로 떨어졌다. 알아보지 못한 실패는 +그 주장을 뒷받침하지 않고, 그것을 믿는 호출자는 멱등이 아닌 쓰기를 재시도한다. 지금은 분류하지 못한 쓰기 실패를 결과 +모름으로 다룬다. -That assertion then caught a second version of the same mistake within a day of being written. The -first guarded run passed; the second failed with 2,099 lost writes, because the setting had been -written into the lane's `primary` service only. The two data nodes swap roles on every failover, so -a guardrail applied to whichever one happens to start as primary stops applying the moment the lane -does the thing it exists to do. Both nodes now take their whole configuration from one definition. -Three consecutive promotions in both directions since: 0, 0, and 1 acknowledged write lost. +### Cluster 실행이 밝힌 것 -The run also found a translator defect. A promotion closed the channel under an in-flight `RPUSH` -and the driver raised a bare `RedisException`, which matched no branch and fell through to a generic -failure reported as *definitely did not run*. Nothing about an unrecognised failure supports that -claim, and a caller who believes it retries a non-idempotent write. The fallback now treats an -unclassified write failure as ambiguous. +`LiveRedisClusterTest`는 `sdk.cluster` 중 순수한 client 쪽 산수인 부분을 마지막 결정권을 가진 서버와 대조한다. 손으로 +쓴 구현이 틀리는 중괄호 규칙으로 만든 묶음 — 빈 tag `{}`, `foo{}{bar}`, `foo{{bar}}zap`, 닫히지 않은 중괄호, `}{`, +빈 key, ASCII가 아닌 key — 의 모든 항목에서 계산기가 `CLUSTER KEYSLOT`과 같은 답을 냈다. 그리고 그린 key 불변식이 +지켜진다. SDK가 tag만으로 계산한 slot이 서버가 그린 key 전체로 계산한 slot과 같다. -### What the Cluster run established +slot을 넘는 거부는 양쪽 방향으로 확인했다. cluster보다 엄격한 guard는 이유 없이 가용성을 깎고, 느슨한 guard는 성공할 +수 없는 요청을 보낸다. guard가 거부하는 key 쌍이 서버가 `CROSSSLOT`으로 답하는 쌍과 같다. -`LiveRedisClusterTest` checks the part of `sdk.cluster` that is pure client-side arithmetic against -the server that has the last word. The calculator agreed with `CLUSTER KEYSLOT` on every entry of a -corpus built from the brace rules a hand-written implementation gets wrong — an empty tag `{}`, -`foo{}{bar}`, `foo{{bar}}zap`, an unclosed brace, `}{`, the empty key, and non-ASCII keys — and the -rendered-key invariant holds: the slot the SDK computes from a tag alone equals the slot the server -computes from the whole rendered key. - -Cross-slot refusal was checked in both directions, because a guard stricter than the cluster costs -availability for no reason and a looser one sends requests that cannot succeed. The same key pair -the guard refuses is the pair the server answers `CROSSSLOT` for. - -Redirects were observed rather than assumed: a `MOVED` names the slot the client computed, and a -slot put into a real `MIGRATING`/`IMPORTING` state answers `ASK` for an absent key and `TRYAGAIN` -for a multi-key request that straddles the migration. The lane restores the slot to `STABLE` -afterwards, so a run leaves the cluster as it found it. +redirect는 가정하지 않고 관측했다. `MOVED`는 client가 계산한 slot을 이름 댄다. 실제 `MIGRATING`/`IMPORTING` 상태로 둔 +slot은 없는 key에 `ASK`로, 이동에 걸친 여러 key 요청에 `TRYAGAIN`으로 답한다. lane은 그 뒤 slot을 `STABLE`로 되돌린다. +그래서 실행이 cluster를 처음 상태 그대로 남긴다. diff --git a/docs/redis/upgrade-guide.md b/docs/redis/upgrade-guide.md index 07144bd0..184aed94 100644 --- a/docs/redis/upgrade-guide.md +++ b/docs/redis/upgrade-guide.md @@ -1,66 +1,56 @@ -# Redis and client upgrade gate +# Redis와 client 업그레이드 관문 -Changing the Redis server version or the Lettuce version is not a dependency bump. Both change what -commands exist, what they reply, and what an ACL account is allowed to do — all three are things this -SDK encodes as fixed decisions. The checks below must pass before either version moves, and each one -exists because skipping it produces a specific failure that only shows up in production. +Redis 서버 버전이나 Lettuce 버전을 바꾸는 것은 의존성 올리기가 아니다. 둘 다 어떤 명령이 있는지, 무엇을 답하는지, +ACL 계정이 무엇을 해도 되는지를 바꾼다. 셋 모두 이 SDK가 고정된 결정으로 담고 있는 것이다. 어느 버전이든 움직이기 전에 +아래 검사를 통과해야 하고, 각 검사를 건너뛰면 운영에서만 드러나는 특정한 실패가 생긴다. -## 1. Command metadata diff +## 1. 명령 metadata diff -Compare `COMMAND DOCS` / `COMMAND INFO` from the new server with the policy by hand: every command -the server reports must be classified in -`src/adapter/outbound/redis-sdk/src/main/resources/redis-sdk/redis-command-policy.yml`, and every -key specification, ACL category and deprecation the policy relies on must still match. There is no -automated diff: `RedisCommandMetadataDiff` compared against server metadata nothing ever fetched, -and was removed (see `docs/capability-status.md`). +새 서버의 `COMMAND DOCS` / `COMMAND INFO`를 정책과 손으로 비교한다. 서버가 보고하는 모든 명령이 +`src/adapter/outbound/redis-sdk/src/main/resources/redis-sdk/redis-command-policy.yml`에 분류돼 있어야 하고, 정책이 +기대는 모든 key 명세, ACL 분류, 폐기 표시가 여전히 맞아야 한다. 자동 diff는 없다. `RedisCommandMetadataDiff`는 아무도 +가져온 적 없는 서버 metadata와 비교했고, 지웠다(`docs/capability-status.md`). -*Why:* an unclassified command is refused by `CommandPolicyGuard`, so a server that grew a command -does not create a hole — but a command whose **risk changed upstream** and is still classified R1 -here does. The comparison is what surfaces that. +*이유:* 분류하지 않은 명령은 `CommandPolicyGuard`가 거부한다. 그래서 명령이 늘어난 서버는 구멍을 만들지 않는다. 다만 +**상위에서 위험도가 바뀌었는데** 여기서 아직 R1로 분류된 명령은 구멍을 만든다. 그것을 드러내는 것이 비교다. -## 2. ACL regression +## 2. ACL 회귀 -Re-run `ACL DRYRUN` for every account against every command the SDK can issue, using -`RedisAdminOperations.aclDryRun`. +`RedisAdminOperations.aclDryRun`으로, SDK가 보낼 수 있는 모든 명령에 대해 모든 계정의 `ACL DRYRUN`을 다시 돌린다. -*Why:* a permit never widens an ACL account, so the account is the last boundary. A new server -version that moved a command into a different ACL category silently turns a working call into a -runtime refusal on the first request that needs it. +*이유:* 허가는 ACL 계정을 절대 넓히지 않는다. 그래서 계정이 마지막 경계다. 새 서버 버전이 명령을 다른 ACL 분류로 +옮기면, 되던 호출이 그것이 필요한 첫 요청에서 실행 중 거부로 조용히 바뀐다. -## 3. Serializer golden bytes +## 3. Serializer golden byte -Compare the encoded form of every registered codec against the stored golden bytes. +등록한 모든 codec의 인코딩 결과를 저장해 둔 golden byte와 비교한다. -*Why:* a value written by the old version must still decode after the upgrade. A codec change that -looks harmless in a round-trip test is not harmless against data already in the instance. +*이유:* 옛 버전이 쓴 값이 업그레이드 뒤에도 디코딩돼야 한다. 왕복 테스트에서 해롭지 않아 보이는 codec 변경도 이미 +인스턴스에 있는 데이터에 대해서는 해롭다. -## 4. Support matrix +## 4. 지원 매트릭스 -Update `docs/redis/support-matrix.md`. `RedisSupportMatrixTest` fails when a module or capability is -missing, and the certified-version table must not claim a version until its topology lane has -actually run. +`docs/redis/support-matrix.md`를 고친다. `RedisSupportMatrixTest`는 모듈이나 capability가 빠지면 실패한다. 인증 버전 +표는 그 토폴로지 lane이 실제로 돌기 전까지 버전을 주장하면 안 된다. -## 5. Topology suite +## 5. 토폴로지 suite -Run the standalone, Sentinel, and Cluster lanes declared in `src/adapter/outbound/redis-sdk/compose/`. A version is -certified by the lane passing, not by the version number being newer. +`src/adapter/outbound/redis-sdk/compose/`에 선언한 standalone, Sentinel, Cluster lane을 돌린다. 버전은 숫자가 더 새것이라서가 +아니라 lane이 통과해서 인증된다. -*Why:* failover certainty and cross-slot behaviour are the two things the in-memory fixture cannot -prove. `ExecutionCertainty` and `RedisSlotCalculator` are classification and arithmetic; whether the -driver actually behaves that way during a promotion or a resharding is only observable on a real -topology. +*이유:* failover 확실성과 slot을 넘는 동작은 메모리 안 fixture가 증명할 수 없는 두 가지다. `ExecutionCertainty`와 +`RedisSlotCalculator`는 분류와 산수다. 승격이나 재분배 중에 driver가 정말 그렇게 동작하는지는 실제 토폴로지에서만 볼 수 +있다. -## 6. Rollback +## 6. 되돌리기 -Before the upgrade, record the previous server version, the previous Lettuce version, and the -`SCRIPT LOAD` digests of every registered script. A rollback is not complete until the digests -resolve again on the restored version. +업그레이드 전에 앞 서버 버전, 앞 Lettuce 버전, 등록한 모든 script의 `SCRIPT LOAD` digest를 적어 둔다. 되돌린 버전에서 +digest가 다시 풀릴 때까지 되돌리기는 끝나지 않은 것이다. -*Why:* digests are cached per process and invalidated by `SCRIPT FLUSH` and by restarts. A rollback -that leaves a process holding digests the restored server does not know produces `NOSCRIPT` on -every scripted call until the cache is dropped. +*이유:* digest는 프로세스마다 cache되고 `SCRIPT FLUSH`와 재시작으로 무효가 된다. 되돌린 서버가 모르는 digest를 쥔 +프로세스가 남으면, cache를 버릴 때까지 script를 쓰는 모든 호출에서 `NOSCRIPT`가 난다. -## What this gate does not cover +## 이 관문이 다루지 않는 것 -Data migration. Nothing here moves or reshapes stored values; a change that alters what is stored, -rather than how it is addressed, needs its own plan. +데이터 마이그레이션. 여기의 어떤 것도 저장된 값을 옮기거나 모양을 바꾸지 않는다. 주소 잡는 방식이 아니라 저장하는 것을 +바꾸는 변경에는 따로 계획이 필요하다. diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt index e4b0e803..30ff1f9a 100644 --- a/scripts/check-docs-exceptions.txt +++ b/scripts/check-docs-exceptions.txt @@ -64,10 +64,6 @@ language docs/notification/provider-runbooks.md language docs/notification/security-privacy.md language docs/notification/support-matrix.md language docs/observability/log-fields.md -language docs/redis/command-policy.md -language docs/redis/operations.md -language docs/redis/support-matrix.md -language docs/redis/upgrade-guide.md language docs/runbooks/adapter-adapter-disabled.md language docs/runbooks/auth-audience-mismatch.md language docs/runbooks/auth-claim-mapping-failed.md