문제:
- 루트 compose 6개와 infra/ 아래 12개가 개발 환경, 테스트 lane fixture,
보조 파일을 가리지 않고 섞여 있다. 이름 모양도 셋이다.
- README 빠른 시작 scripts/bootstrap-local.sh는 docker-compose.yml과
.local.yml만 합친 뒤, 둘 어디에도 없는 db 서비스를 띄우려다 멈춘다.
- compose smoke all-adapters lane은 앱이 mem_limit 512m를 넘어 커널에
죽고(OOM), restart: unless-stopped로 다시 떠서 죽는 때가 smoke 요청과
겹칠 때만 실패한다. smoke는 재시작을 보지 않아 나머지 실행은 거짓 통과다.
고른 방법(소유자 결정 2026-11-07):
- 루트에 개발용 compose.yaml 하나. app(local 런타임)과 뒷단 서비스를
capability profile(jpa, redis, kafka, mongo, objectstorage, auth, mail)로
고른다. 마운트하는 보조 파일은 compose/(keycloak, minio init, Redis ACL,
mailpit 인증서 폴더).
- lane fixture는 lane을 가진 leaf로: dev·prod-smoke·tls overlay, fileserver
overlay, smoke·스키마 적용 서비스(lane-services.yaml)와 스크립트, lane
계약 JSON → src/app-bootstrap/compose-lanes/. Redis topology →
redis-sdk/compose/, NFS → fileserver/compose/nfs/. infra/는 없어진다.
- 계약의 composeProfile(문자열)을 composeProfiles(목록)로 바꾼다. lane이
backing profile과 lane profile을 함께 켠다. 18 lane의 서비스 집합은
전과 같다(verify-compose-profile-contracts.sh가 정확히 대조).
- smoke: lane이 끝나기 전에 그 project의 모든 컨테이너가 재시작 0,
OOMKilled false인지 보고 아니면 실패한다. 앱의 memory.peak를 증거로
남긴다. all-adapters만 appMemoryLimit 1g(계약 칸, smoke가 overlay에 씀).
- bootstrap-local.sh는 compose.yaml로 db와 app을 띄운다(인자 없음).
- 개발 compose와 lane 바탕이 같은 파일이라, app healthcheck는 모든
런타임에서 답하는 관리 포트 readiness로 둔다.
버린 대안: lane을 Testcontainers로 옮기기(설계 다-2, 별도 판단), lane마다
기본 메모리를 올리기(배포 기본값 512m 계약을 흐림).
위험·한계:
- 개발 compose의 app이 src/.env를 읽으므로, 개발자 src/.env가 dev·prod
lane에도 들어간다. lane 값은 생성 overlay의 environment가 이기고, CI에는
src/.env가 없다.
- MinIO 이미지 기본값이 compose.yaml과 lane-services.yaml 두 곳에 있다
(YAML anchor는 파일을 넘지 못한다). ComposeMinioImageMatchesEvidenceTest가
둘 다 evidence digest와 대조한다.
- env 키 검사(verifyEnvKeys)는 compose.yaml과 lane overlay를 읽고
lane-services.yaml(smoke client 변수)은 뺀다.
검증(desktop, 트리 6d1e9f9d → 주석·문서만 고친 d0703901, ~/t1-layout-logs/):
- verify-compose-profile-contracts.sh rc=0 (18 lane 정확히 일치)
- :app-bootstrap:check :app-bootstrap:documentContractTest
:app-bootstrap:verifyEnvKeys와 objectstorage·cache-redis·redis-sdk·
redis-runtime·fileserver·composition:fileserver-platform check rc=0
- :app-bootstrap:integrationTest(ComposeMergeCharacterizationTest 포함),
:adapter:outbound:cache-redis:redisContainerContractTest rc=0
- -p build-logic check rc=0, :verifyStrictLaneStages --dry-run rc=0
- scripts/run-compose-runtime-smoke.sh --matrix(18 lane) rc=0, 794초.
모든 lane 컨테이너 재시작 0·OOMKilled false. 앱 memory.peak 최고
all-adapters 532MiB(512m 한도를 넘는 값이라 1g의 근거), 나머지 244~422MiB
- scripts/bootstrap-local.sh rc=0(db·app 기동, /api/healthcheck 200 UP).
기준 ac03192d의 base+local 조합은 config --services가 app뿐이고
up --wait db가 "no such service: db"로 rc=1
- 정리할 때 `docker compose down`은 profile 서비스(db)를 남겨
README·compose.yaml 안내를 `--profile '*' down`으로 고치고 다시 확인
- 주석·문서 수정 뒤 :app-bootstrap:repositoryContractTest
:app-bootstrap:documentContractTest, verify-compose rc=0
Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.3
BREAKING CHANGE: 루트 docker-compose*.yml과 infra/가 없어지고 compose.yaml(profile)·compose/·leaf 안 lane fixture로 옮겨졌다. lane 계약은 src/app-bootstrap/compose-lanes/compose-profile-contracts.json, composeProfile → composeProfiles. docs/upgrade/2026-11-maturity-review.md B-51.
160 lines
10 KiB
Markdown
160 lines
10 KiB
Markdown
# 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/superpowers/specs/2026-08-07-redis-wrapper-typed-api-design.md`.
|
||
Delivery status and the decisions behind each module: `docs/superpowers/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 `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:
|
||
|
||
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.
|