Files
clean-architecture-backend-…/docs/redis/support-matrix.md
T
DongHyeonka 50cd7154d0 refactor(compose)!: compose 파일을 개발 환경 하나와 lane fixture로 나눈다
문제:
- 루트 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.
2026-11-07 12:52:36 +09:00

10 KiB
Raw Blame History

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.