문제:
- 루트 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.
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 src/adapter/outbound/redis-sdk/compose/. 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.