Files
clean-architecture-backend-…/docs/redis/support-matrix.md
T
DongHyeonka 630f9b860a docs(records): 설계서와 기록 문서를 docs/design·docs/history로 옮긴다
문제: docs/ 바로 아래에 매뉴얼·운영 문서와 쓴 때의 기록(계획서·설계서·
납품 패키지·증거·학습)이 같은 층에 섞여 있다. 기록이라는 표시도 없어
읽는 사람이 지금 동작을 설명하는 문서와 구분하지 못한다.

고른 방법: 2026-11-07 소유자가 승인한 수명 기준 분리를 따른다.
- docs/superpowers/specs → docs/design/
- docs/superpowers/plans → docs/history/plans/
- docs/superpowers/packages/* → docs/history/packages/*
- docs/{graphql,web,websocket}-superpowers-package
  → docs/history/packages/<같은 이름>/ (packages/graphql과 겹치지 않게
  원래 폴더 이름을 둔다)
- docs/evidence → docs/history/evidence/, docs/study → docs/history/study/
- git에 들어가 있던 __pycache__ .pyc를 지우고 .gitignore에 더한다.

옮긴 경로를 가리키는 줄을 같은 커밋에서 고쳤다: 살아 있는 문서의 인라인
경로, AGENTS.md·CLAUDE.md, 빌드 스크립트·테스트 주석, docs/README.md 위치
표, 파생 서비스용 docs/upgrade/2026-11-docs-records.md. 기록 본문은
고치지 않고, 이동으로 깨진 마크다운 상대 링크 32개의 대상만 고쳤다(lychee와
check-work-docs.py --links가 docs/** 전체를 본다). 이동만 따로 두면 그
커밋에서 링크 검사가 실패하므로 한 커밋으로 묶었다. 대부분 R100이라 이름
바뀜은 그대로 보인다.

위험·한계: 기록 본문과 docs/reviews/** 안의 인라인 코드 경로는 옛 경로로
남는다(기록은 고치지 않는다). 실험용 Flyway 파일
db/experimental-rls/V1__tenant_rls.sql의 주석은 체크섬이 바뀌므로 두었다.
납품 패키지 셋의 MANIFEST.sha256과 validate_*.py는 패키지 안 상대 경로라
이동 뒤에도 그대로다.

검증: python3 scripts/check-work-docs.py rc=0, --links(gates.md 범위 +
CLAUDE.md·AGENTS.md) 581개 파일 깨진 링크 0, --history docs/manual rc=0.
2026-11-07 12:15:45 +09:00

160 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Redis SDK support matrix
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.
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`.
## Modules
| Module | Minimum Redis | Topology | Risk exposure | Sync | Reactive | Known limitations |
| --- | --- | --- | --- | --- | --- | --- |
| `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 |
## Capabilities
| Capability | Minimum Redis | Gate | Bean when absent |
| --- | --- | --- | --- |
| `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 |
## 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.
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.
| 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 |
### What the standalone ACL run established
`RedisTopologyContractTest` runs the four accounts in `infra/redis-sdk/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:
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`.
6. The admin account was missing twelve read-only diagnostics the catalog exposes — the `OBJECT`,
`PUBSUB`, `XINFO`, `FUNCTION LIST`/`STATS`, and `CLUSTER KEYSLOT` subcommands.
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.
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.
### What the standalone guardrail run established
`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.
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.
### What the Sentinel promotion run established
`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.
It found the most serious defect in this delivery, and it is not in the SDK's code:
> **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.
`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.
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.
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.
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.
### What the Cluster run established
`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.