Files
clean-architecture-backend-…/docs/redis/upgrade-guide.md
T
DongHyeonkaandClaude Opus 5.5 6d27356e2b refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 12:49:07 +09:00

3.2 KiB

Redis and client upgrade gate

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.

1. Command 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).

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.

2. ACL regression

Re-run ACL DRYRUN for every account against every command the SDK can issue, using RedisAdminOperations.aclDryRun.

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.

3. Serializer golden bytes

Compare the encoded form of every registered codec against the stored golden bytes.

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.

4. Support matrix

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.

5. Topology suite

Run the standalone, Sentinel, and Cluster lanes declared in infra/redis-sdk/. A version is certified by the lane passing, not by the version number being newer.

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.

6. Rollback

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.

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.

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.