docs(redis): Redis SDK 운영 문서를 한국어로 옮긴다

문제: docs/redis 아래 살아 있는 문서 4개가 영어였다(language 예외).

고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·표 구조는 원문으로 둔다.
support-matrix.md의 표 첫 칸(package·capability·토폴로지 이름)과 증거 칸의 테스트 클래스
이름은 RedisSupportMatrixTest가 그대로 읽으므로 바꾸지 않았다. 번역하며 고친 것:
- 「pinned to Lettuce 6.8.2」: build.gradle은 버전 없이 Boot BOM을 따른다. 숫자 대신
  BOM과 leaf gradle.lockfile을 가리킨다.
- 「five defects」 뒤 목록이 일곱 항목이라 「결함 일곱」으로 고쳤다.

위험·한계: 내용 감사는 하지 않았다.

검증: python3 scripts/check-docs.py에서 이 폴더 예외 줄 0. RedisSupportMatrixTest의 세
단언(package·capability가 첫 칸에 있음, 토폴로지 행이 있는 테스트 클래스를 댐)을 같은
규칙으로 문서에 돌려 보았다(빠진 것 0).
This commit is contained in:
DongHyeonka
2026-11-07 17:29:57 +09:00
parent 9d6c67c14e
commit 4e2f08a687
5 changed files with 222 additions and 267 deletions
+38 -39
View File
@@ -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` | 어디에도 없음 |
+41 -51
View File
@@ -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)이므로 멱등한 소비자가 필요하다.
+107 -127
View File
@@ -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를 처음 상태 그대로 남긴다.
+36 -46
View File
@@ -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.
데이터 마이그레이션. 여기의 어떤 것도 저장된 값을 옮기거나 모양을 바꾸지 않는다. 주소 잡는 방식이 아니라 저장하는 것을
바꾸는 변경에는 따로 계획이 필요하다.
-4
View File
@@ -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