This commit is contained in:
+1
-1
@@ -192,7 +192,7 @@ leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것
|
||||
| --- | --- |
|
||||
| `language` | 살아 있는 문서와 ADR 본문이 한국어인가(코드·명령·경로·인용은 세지 않는다) |
|
||||
| `head` | 기록과 ADR 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 있는지 |
|
||||
| `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`, `.gitea/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 |
|
||||
| `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`, `.gitea/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. `docs/registries/*.yaml`은 값과 주석에 적은 repo 경로를 본다(행의 `source`·`registered_by`가 옮긴 파일을 가리키면 PR에서 걸린다). 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 |
|
||||
| `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가. Spring Boot 버전은 이름 바로 뒤(「Spring Boot」나 「Boot」 뒤의 세 자리 버전), `Spring Boot` 칸이 있는 표 행의 세 자리 버전, 정본(`gradle/libs.versions.toml`의 `springBoot`)과 같은 버전 문자열(굵은 글씨·표 칸·코드 안 포함)을 잡는다. 결정 기록, 제거 표, `upgrade/`는 보지 않는다 |
|
||||
| `map` | 이 README의 「문서 지도」가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 |
|
||||
| `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 |
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
# root yet.
|
||||
# Update only after review with:
|
||||
# ./gradlew :adapter:outbound:persistence-jpa:updateJpaApiSurface -PapproveJpaApiSurfaceChange
|
||||
# types: 165
|
||||
# types: 168
|
||||
dev.caskeleton.adapter.outbound.persistence.api.PersistenceOperationName
|
||||
dev.caskeleton.adapter.outbound.persistence.api.capability.CapabilitySupport
|
||||
dev.caskeleton.adapter.outbound.persistence.api.capability.JpaCapability
|
||||
@@ -104,6 +104,8 @@ dev.caskeleton.adapter.outbound.persistence.idempotency.postgresql.IdempotencySc
|
||||
dev.caskeleton.adapter.outbound.persistence.idempotency.postgresql.PostgreSqlIdempotencyStore
|
||||
dev.caskeleton.adapter.outbound.persistence.liveevent.JpaLiveEventReplay
|
||||
dev.caskeleton.adapter.outbound.persistence.liveevent.LiveEventJpaRepository
|
||||
dev.caskeleton.adapter.outbound.persistence.liveevent.LiveEventReaper
|
||||
dev.caskeleton.adapter.outbound.persistence.liveevent.LiveEventReplaySettings
|
||||
dev.caskeleton.adapter.outbound.persistence.liveevent.entity.LiveEventEntity
|
||||
dev.caskeleton.adapter.outbound.persistence.lock.DistributedLockPersistenceConfig
|
||||
dev.caskeleton.adapter.outbound.persistence.lock.LockRegistryDistributedLock
|
||||
@@ -169,5 +171,6 @@ dev.caskeleton.adapter.outbound.persistence.springdata.SafeSortField
|
||||
dev.caskeleton.adapter.outbound.persistence.springdata.SafeSortMapper
|
||||
dev.caskeleton.adapter.outbound.persistence.springdata.SafeSortRegistry
|
||||
dev.caskeleton.adapter.outbound.persistence.springdata.ScrollPolicy
|
||||
dev.caskeleton.adapter.outbound.persistence.transaction.BatchedDeletes
|
||||
dev.caskeleton.adapter.outbound.persistence.transaction.CallerTransaction
|
||||
dev.caskeleton.adapter.outbound.persistence.transaction.SpringTransaction
|
||||
|
||||
@@ -211,7 +211,7 @@ web 경로의 `W/`는 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adap
|
||||
| cache 정책 카탈로그 (`WebCachePolicyCatalog`, `WebCachePolicy`, `WebVaryPolicy`, `WebCacheHeaders`)와 테스트 | `W/cache/` (W3-2에서 web-advanced로 옮긴 뒤 삭제) | `208077fd` | 한 기능에 한 세대: 운영은 `CacheControlFilter` |
|
||||
| JSON mapper factory (`WebObjectMapperFactory`, `WebJsonProfile`, `BoundedJsonFactory`)와 테스트 | `W/json/` (W3-2에서 web-advanced로 옮긴 뒤 삭제) | `208077fd` | 한 기능에 한 세대: 운영은 Boot `JsonMapper` + `spring.jackson.*`. 스트리밍 encoder는 Boot `JsonMapper` bean을 받도록 변경 |
|
||||
| OpenAPI customizer (`WebOpenApiCustomizer`, `WebOpenApiProfile`, `CursorSchemaContributor`)와 `WebOpenApiSnapshotTest` | `W/openapi/` 의 해당 3개 파일 (W3-2에서 web-advanced로 옮긴 뒤 삭제) | `208077fd` | 한 기능에 한 세대: 운영은 springdoc + `OpenApiContractConfig`. `CursorPage` 스키마는 이미 삭제된 커서 페이지네이션을 설명 |
|
||||
| realtime 포트 (`ConnectionRegistryPort`, `DurableFanoutPort` 외 7개 타입)와 Redis 연결 레지스트리 (`RedisConnectionRegistryAdapter`) | `src/application-core/src/main/java/dev/caskeleton/application/realtime/`, `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/realtime/` | `208077fd` | 소비자 0 (websocket 정리 후 호출자 없음, bean 없음). `LiveEventReplayPort` 계열은 유지 |
|
||||
| realtime 포트 (`ConnectionRegistryPort`, `DurableFanoutPort` 외 7개 타입)와 Redis 연결 레지스트리 (`RedisConnectionRegistryAdapter`) | `src/application-core/src/main/java/dev/caskeleton/application/realtime/`, `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/realtime/` | `208077fd` | 소비자 0 (websocket 정리 후 호출자 없음, bean 없음). `LiveEventReplayQueryPort` 계열은 유지 |
|
||||
| graphql `advanced/**` 전체 (15개 패키지, 130개, ~5,600줄) + 테스트 | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/advanced/` | `208077fd` | 모든 진입점이 `GraphQlAdvancedModuleGuard`를 거치는데 그 플래그(`GraphQlAdvancedFeatureFlags`)를 바인딩하는 코드가 없다. Spring GraphQL/graphql-java SPI를 구현한 타입이 없어 SSE·RSocket·federation·incremental·GET·chaining은 이름만 있는 모델. `GraphQlReplaySource`·`GraphQlPersistedOperationAdminPort`는 구현체 없는 인터페이스, persisted 레지스트리가 기대는 `OperationalRecordStorePort`도 구현체 0. composition/incremental/bootstrap은 gate·등급 코드 |
|
||||
| `backend.graphql.unsupported.*` 6개 키 (`GraphQlPlatformSettings.Unsupported`, `withUnsupportedCapability`, 검증기 분기) | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/autoconfigure/GraphQlPlatformSettings.java`, `GraphQlPlatformStartupValidator.java` | `208077fd` | 켜면 부팅 실패만 한다. 구현하지 않은 기능에는 설정 키를 두지 않는다(AGENTS 기준 3) |
|
||||
| `backend.graphql.cursor.key-ids` (`GraphQlPlatformSettings.Cursor`, `withCursorKeyIds`) | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/autoconfigure/GraphQlPlatformSettings.java` | `208077fd` | 읽는 곳이 등록되지 않은 actuator 보고서뿐. 커서 서명은 라이브러리(`HmacGraphQlCursorCodec`)를 서비스가 직접 조립한다 |
|
||||
|
||||
@@ -193,9 +193,16 @@ transport가 닿는 모든 연산은 `application.fileserver.port.in`의 메서
|
||||
`BlockingTransferExecutor`가 요청의 context를 worker로 옮긴다(`BlockingTransferExecutorSecurityContextTest`).
|
||||
이것이 없으면 인증한 append가 익명으로 거부됐다.
|
||||
|
||||
use case가 아닌 것은 어떤 transport도 부르지 않는 것이다. `CleanupService`와 `FileReconciliationService`는
|
||||
호출자 신원이 없는 백그라운드 worker가 돌린다. 상태를 바꾸는 use case는 scheduler가 가질 수 없는 권한을
|
||||
선언해야 한다. `FileserverUseCaseContractDeviationTest`가 그 목록을 고정한다.
|
||||
백그라운드 worker가 하는 쓰기도 use case다. 다만 사용자 것과 따로다. `FileserverCleanupWorker`는 호출자 신원이 없는
|
||||
scheduler 스레드에서 돌므로 `@SystemInvoked` use case 둘(`RunScheduledCleanupUseCase`,
|
||||
`ReconcileRecoverableFilesUseCase`)을 `new`로 만들어 쥔다. bean이 아니어서 transport가 닿지 못한다. 운영자가 같은
|
||||
cleanup을 돌리는 길은 `file:admin`을 선언한 `CleanupUploadsUseCase`다(2026-11-13).
|
||||
|
||||
use case가 아닌 것은 그 use case들이 쥔 협력 객체다. `CleanupService`(`DefaultCleanupService`),
|
||||
`FileReconciliationService`(`DefaultFileReconciliationService`), `WriterLeaseCoordinator`다. 이 서비스들은
|
||||
`composition:fileserver-platform`이 bean으로 조립한다. 권한 검사 없이 쓰는 bean이라, inbound adapter가 interface로라도
|
||||
쥐면 `INBOUND_ADAPTERS_DEPEND_ON_PORTS_NOT_APPLICATION_SERVICES`가 빌드를 실패시킨다(2026-11-13부터 interface와
|
||||
coordinator도 본다). `FileserverUseCaseContractDeviationTest`가 그 목록을 고정한다.
|
||||
|
||||
`FileserverErrorCode`의 HTTP 상태 어휘는 애플리케이션 계층에 남는다. 이 절이 예전에 든 이유 그대로다:
|
||||
servlet transport와 Nginx 위임 경로가 같은 실패에 다른 상태로 답하면 안 된다.
|
||||
|
||||
@@ -167,8 +167,8 @@ profile에는 `connect`와 `response-header`를 가장 짧은 호출자 예산
|
||||
| `redirect.max-hops` | `0` | redirect를 켜고 hop을 0으로 두면 설정 오류다 |
|
||||
| `redirect.allow-cross-origin` | `false` | 켜면 hop에서 credential을 지운다 |
|
||||
| `request.max-body-bytes` | `0` | 운영에서 필수 |
|
||||
| `request.compression` | `false` | |
|
||||
| `response.max-wire-bytes` | `5242880` | wire 위의 바이트 |
|
||||
| `request.compression` | `false` | 켜면 transport와 상관없이 `Accept-Encoding: gzip, deflate`를 보낸다. 받은 본문은 엔진이 아니라 이 플랫폼이 wire 바이트를 센 뒤 푼다(버퍼 본문과 스트리밍 다운로드 모두) |
|
||||
| `response.max-wire-bytes` | `5242880` | wire 위의 바이트. 압축을 켜도 압축된 크기로 센다 |
|
||||
| `response.max-decoded-bytes` | `10485760` | 디코딩한 뒤의 바이트. 넘을 수 없는 최대는 64 MiB |
|
||||
| `response.allowed-content-types` | JSON + problem+json | 비어 있으면 「아무것이나」 |
|
||||
|
||||
@@ -212,7 +212,7 @@ profile에는 `connect`와 `response-header`를 가장 짧은 호출자 예산
|
||||
| 속성 | 기본값 | 뜻 |
|
||||
|---|---|---|
|
||||
| `proxy.enabled` | `false` | |
|
||||
| `proxy.host` / `proxy.port` / `proxy.type` | — / `0` / `HTTP` | |
|
||||
| `proxy.host` / `proxy.port` / `proxy.type` | — / `0` / `HTTP` | 지금 transport는 모두 HTTP forward proxy만 한다. `type`의 값은 `HTTP` 하나이고, `SOCKS`는 바인딩이 거부한다 |
|
||||
| `proxy.credential-provider` | — | proxy 인증은 대상 인증과 따로다 |
|
||||
| `proxy.import-ambient-no-proxy` | `false` | 환경의 `NO_PROXY`는 검증한 profile을 넓히지 않는다 |
|
||||
| `observability.full-url-recording` | `false` | |
|
||||
|
||||
@@ -50,9 +50,9 @@
|
||||
|
||||
| 상태 | 판정 |
|
||||
|---|---|
|
||||
| 408 | 기한과 예산 안에서 재시도 |
|
||||
| 425 | 첫 시도에서만, 많아야 한 번 재시도 |
|
||||
| 429 | `Retry-After`, 기한, 예산 안에서 재시도 |
|
||||
| 408 | 안전하게 멱등인 연산만 기한과 예산 안에서 재시도. 아니면 결과 모름(upstream이 받은 뒤 답한 것일 수 있다) |
|
||||
| 425 | 안전하게 멱등인 연산만, 첫 시도에서만, 많아야 한 번 재시도. 아니면 결과 모름 |
|
||||
| 429 | 안전하게 멱등인 연산만 `Retry-After`, 기한, 예산 안에서 재시도. 아니면 거부(`notRetryableStatus`). 429는 일정 신호이지 "아무 일도 없었다"는 말이 아니다 |
|
||||
| 401 | 안전하고 재전송 가능한 연산에서만 갱신 후 재전송 한 번. credential은 재시도를 허락받은 뒤에만 갱신한다. 재전송하지 않을 401(시도 한 번, 예산 없음, 기한 없음)은 token cache를 건드리지 않는다 |
|
||||
| 500 | upstream이 일시적이라고 등록했고 **그리고** 연산이 안전하게 멱등일 때만 허락. 아니면 거부 |
|
||||
| 502, 503, 504 | 안전하게 멱등인 연산은 재시도. 아니면 결과 모름 |
|
||||
|
||||
@@ -7,7 +7,13 @@
|
||||
검증한다. 그래서 실패한 다운로드가 호출자가 따져야 하는 반쯤 읽힌 stream이 되지 않는다.
|
||||
|
||||
wire 바이트와 디코딩한 바이트는 따로 제한한다. 압축한 payload는 wire 검사를 통과한 뒤 늘어나기 때문이다. 한도는
|
||||
버퍼링한 뒤가 아니라 읽는 동안 강제한다.
|
||||
버퍼링한 뒤가 아니라 읽는 동안 강제한다. 압축(`Content-Encoding: gzip`·`deflate`)은 엔진이 아니라 응답 reader가
|
||||
푼다. 도착한 바이트를 wire 한도로 세고, 푼 바이트를 조각마다 디코딩 한도로 센다. 엔진이 먼저 풀면 wire 계수가 푼
|
||||
크기를 세게 되어, 잘 압축된 응답이 wire 위에는 없던 크기로 거부됐다(round9 리뷰 2026-11-12, RR9-01-30). 부탁하지 않은
|
||||
압축(`br` 등)과 겹친 coding은 거부한다. 스트리밍 다운로드도 같은 곳(`ContentDecoding`)을 거친다. 호출자는 푼 바이트를
|
||||
읽고, 응답 헤더에는 `Content-Encoding`·`Content-Length`가 없다. 풀기는 호출자가 읽을 때 시작하므로, 본문이 빈 gzip
|
||||
응답(HEAD·204·304)은 빈 본문이다. 어느 transport도 스스로 풀지 않는다. Apache는 압축 처리를 끄고, 실험 transport인
|
||||
Jetty HTTP/3은 시작할 때 classpath에서 등록한 decoder를 지운다.
|
||||
|
||||
## 첫 바이트 경계
|
||||
|
||||
|
||||
+10
-2
@@ -1,4 +1,13 @@
|
||||
# 예측·실측 장부
|
||||
# 장부
|
||||
|
||||
이 폴더에는 줄을 더하기만 하는 JSON Lines 장부가 둘 있다.
|
||||
|
||||
- `estimates.jsonl`: 작업의 예측·실측(아래 절).
|
||||
- `flaky-tests.jsonl`: 흔들린 시험. 흔들림 하나가 한 줄이다. 칸(`date`·`test`·`category`·`first_run`·`verdict`·`quarantined_until`·`fixed_by`)과 범주의 정본은 design-docs `ci/manual.md` 8.5절이고, 판정·처리 절차는 그 문서 8.3절이다. 고친 PR이 병합되면 그 줄의 `fixed_by`를 채운다.
|
||||
|
||||
두 파일 모두 `.gitattributes`가 `merge=union`을 준다. 여러 브랜치가 끝에 줄을 더해도 병합이 멈추지 않는다.
|
||||
|
||||
## 예측·실측 장부
|
||||
|
||||
작업마다 착수할 때의 예측과 끝날 때의 실측을 한 줄씩 쌓는다. 틀린 예측에서 하네스(아키텍처 → 게이트 → 지침 → 사용자 행동 순서)를 고칠 곳을 찾는 것이 목적이다. 질타가 아니라 측정이다(소유자 결정 2026-11-07).
|
||||
|
||||
@@ -9,7 +18,6 @@
|
||||
```
|
||||
|
||||
- 파일은 `docs/ledger/estimates.jsonl` 하나다. 한 줄이 JSON 하나다(JSON Lines). 줄을 고치거나 지우지 않고 더하기만 한다. 고칠 일이 있으면 같은 `task`로 `"correction": true` 줄을 더한다.
|
||||
- 여러 브랜치가 끝에 줄을 더해도 병합이 멈추지 않게 `.gitattributes`가 이 파일에 `merge=union`을 준다.
|
||||
- p30·p50·p80은 그 값 안에 끝날 확률이 30%·50%·80%라고 보는 세 값이다. p30이 도전값, p80이 안전값이다.
|
||||
- 시간의 기준은 작업 중 시간이다. 끝 보고 뒤 다음 지시를 기다린 시간은 넣지 않는다. 배수는 근거(바꿀 파일 수, 검증 대기)가 있을 때만 쓴다.
|
||||
- 위임 대조용 장부(design-docs `delegation-loop/ledger.jsonl`)는 그대로 둔다. 그 줄의 예측·실측 칸은 이 파일의 `task`를 가리킨다.
|
||||
|
||||
@@ -15,4 +15,5 @@
|
||||
{"schema": 1, "kind": "actual", "task": "w2-be-ci-perf", "transcript": "a6b6b25f-a4f7-46c2-a746-5ab20a588c78", "minutes": 663, "active_minutes": 417, "calls": 464, "output_tokens": 438927, "cache_read_tokens": 256417797, "max_context": 911512, "within": "over", "result": "partial", "commits": ["ecc14004", "6325b518", "86488256", "c7aff0f4", "7054d179", "575aa1f7", "deeb1126", "96caf997", "cfc80ae8", "000a59ed", "5a95db45", "d237bacc", "7284b581", "14053060", "7dbf11ca", "2c180b90", "24dde586", "aeb60339", "083c6910"], "why": "시간이 p80을 넘었다: desktop 공유 잠금 대기자 10여 개(flock이 순서 없이 깨움)로 측정·검증이 2시간 넘게 밀렸고, runner 1대 대기열에서 늦게 풀린 job이 맨 뒤로 가 수동 실행 결과가 몇 시간씩 늦었다. 예측에 없던 결정: Gitea needs+if Blocked 재현(일회용 workflow 셋), Trivy가 처음 읽은 lockfile 라이선스와 이미지가 jar 라이선스를 못 읽는 것에 맞춘 판정 재설계. 결과는 partial: runner 초록은 NFS(소유자 sudo)·compose(수정 뒤 runner 미확인) 빼고 달성, 속도 목표 넷은 미달(캐시 효과는 병합 뒤, PG 컨테이너 159개 공유는 후속).", "recorded_at": "2026-11-12T08:34+09:00"}
|
||||
{"schema": 1, "kind": "actual", "task": "w2-be-ci-perf", "correction": true, "transcript": "a6b6b25f-a4f7-46c2-a746-5ab20a588c78", "minutes": 1266, "active_minutes": 555, "calls": 556, "output_tokens": 534063, "cache_read_tokens": 301335415, "max_context": 963079, "within": "over", "result": "partial", "commits": ["ecc14004", "6325b518", "86488256", "c7aff0f4", "7054d179", "575aa1f7", "deeb1126", "96caf997", "cfc80ae8", "000a59ed", "5a95db45", "d237bacc", "7284b581", "14053060", "7dbf11ca", "2c180b90", "24dde586", "aeb60339", "083c6910", "335fc967", "9682c52c", "3e06a809", "d17f8bcf", "7db40c9b"], "why": "앞 actual 줄을 고친다. 그 뒤 총괄 지시 둘(새 main 위로, main.yml concurrency와 취소 증거)과 main 두 번 병합으로 작업 중 138분·호출 92가 더 들었다. 대부분 runner 대기열(PR run이 한 번에 2~4시간 뒤로 밀림)과 desktop 공유 잠금 대기였다. 결과는 여전히 partial: runner PR 130 초록·release gate 125 초록, NFS는 소유자 sudo, 속도 목표 넷은 미달(PR 13.5→12.0분/목표 8, release gate 45.6→32.5분/목표 35는 이미지 job 포함), 캐시 효과는 병합 뒤 측정.", "recorded_at": "2026-11-12T18:36+09:00"}
|
||||
{"schema": 1, "kind": "estimate", "task": "w2-be-ci-perf-2", "transcript": "a6b6b25f-a4f7-46c2-a746-5ab20a588c78", "started_at": "2026-11-12T18:45+09:00", "base": "e7be517e", "task_kind": "improve", "size": "large", "minutes": {"p30": 150, "p50": 240, "p80": 400}, "calls": {"p30": 120, "p50": 200, "p80": 320}, "output_tokens": {"p30": 100000, "p50": 170000, "p80": 280000}, "basis": "직전 라운드 w2-be-ci-perf 실측 555분(p50 144의 3.9배, 대부분 runner·desktop 잠금 대기). 이번 판단 5개(B2·NFS·C2·job 합치기·main 줄 순서), desktop main 측정 1회(30분)+pr 1회, runner nightly 1회(2시간)+release 1회+PR 2회. 대기가 시간을 정한다", "recorded_at": "2026-11-12T18:58+09:00"}
|
||||
{"schema": 1, "kind": "estimate", "task": "r9-group-b", "transcript": "0ef672ab-db3e-427a-9f53-b2e918462534", "started_at": "2026-11-13T07:00:00+09:00", "base": "d3a90479", "task_kind": "improve", "size": "large", "minutes": {"p30": 190, "p50": 286, "p80": 424}, "calls": {"p30": 378, "p50": 567, "p80": 819}, "output_tokens": {"p30": 348000, "p50": 522000, "p80": 754000}, "basis": "발견 42건·PR 3·결정 약 15·desktop 실행 약 20회(Testcontainers lane)·코드 약 3000줄; 원값 360/540/800분·600/900/1300호출·600k/900k/1300k에 보정 0.53/0.63/0.58 곱함; 선례 w2-be-ci-perf 555분", "recorded_at": "2026-11-13T06:52+09:00"}
|
||||
{"schema": 1, "kind": "estimate", "task": "r9-group-a", "transcript": "70449164-6ab3-49a9-9bcd-a4281e2a0759", "started_at": "2026-11-13T07:00+09:00", "base": "d3a90479", "task_kind": "improve", "size": "large", "minutes": {"p30": 160, "p50": 240, "p80": 370}, "calls": {"p30": 250, "p50": 380, "p80": 570}, "output_tokens": {"p30": 200000, "p50": 320000, "p80": 490000}, "basis": "발견 31건·PR 3개, 손 판단 결정 약 8(전송별 인가 전달, graphql 하위 좌표, test profile 기동 거부, broadcaster 목적지, metrics registry 맞추기 등), desktop 검증 약 8회(leaf·pr 단계); 원값 300/450/700분·400/600/900호출·350k/550k/850k에 보정 0.53·0.63·0.58을 곱함", "recorded_at": "2026-11-13T06:52+09:00"}
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
{"date": "2026-11-12", "test": "compose smoke local-messaging (scripts/run-compose-runtime-smoke.sh)", "category": "concurrency-order", "first_run": "100", "verdict": "runner nightly 구성 1회 실패: 앱이 기반 서비스가 healthy가 되기 전에 떴다. 고친 뒤 desktop matrix 18/18 통과", "quarantined_until": "", "fixed_by": "백엔드 #13"}
|
||||
{"date": "2026-11-13", "test": "GrpcP1BoundaryWireTest#aSlowCallWithoutAClientDeadlineEndsAtTheServerDefaultDeadline", "category": "fixed-time", "first_run": "221", "verdict": "runner main push 4회 중 1회 실패(152·164·183 통과). desktop 1코어 고정 15회, CPU 부하 아래 24회 통과", "quarantined_until": "", "fixed_by": "백엔드 #34"}
|
||||
{"date": "2026-11-13", "test": "FailureInjectionContractTest#aSlowDripThroughToxiproxyEndsAtTheTotalDeadline[JDK]", "category": "fixed-time", "first_run": "228", "verdict": "runner 1회 실패(1.92초, 상한 1.5초). desktop 부하 6.5~8에서 10회 통과(호출 1,010~1,021ms)", "quarantined_until": "", "fixed_by": "백엔드 #34"}
|
||||
{"date": "2026-11-13", "test": "LiveEventLogContractTest#concurrentWritersAllocateDistinctPositions", "category": "concurrency-order", "first_run": "260", "verdict": "replay 순서를 writer 제출 순서로 단언했다. 둘째 writer를 먼저 돌린 탐침에서 재현. 고침 PR 백엔드 #39(열림)", "quarantined_until": "", "fixed_by": ""}
|
||||
{"date": "2026-11-13", "test": "JettyAttemptDeadlineTest#aSlowDripExchangeIsAbortedAtTheAttemptDeadline", "category": "fixed-time", "first_run": "desktop ~/w2-reloc-logs/w2-reloc-a.log (main c7a18ec7, prCheck, 시작 부하 11~15)", "verdict": "desktop 1회 실패(1.68초, 상한 1.5초). PR 단계 test라 runner PR run에서도 날 수 있다", "quarantined_until": "", "fixed_by": ""}
|
||||
@@ -91,6 +91,17 @@ store는 자기 트랜잭션을 열지 않는다. 유스케이스가 연 트랜
|
||||
예: `DurableOperationStoreContract`(`InMemoryDurableOperationStore`, `JpaDurableOperationStoreContractTest`).
|
||||
- 여러 인스턴스가 집는 작업 → `FOR UPDATE SKIP LOCKED`는 **트랜잭션 안에서**, 그리고 lease(만료 시각)와
|
||||
fence 값을 함께 저장한다. 예: `ReconciliationJobStorePort.claimDue`(application-notification).
|
||||
- 연장·완료·되돌리기는 그 claim의 owner와 fence를 `WHERE`에 넣은 조건부 UPDATE 하나다. fence는 claim마다
|
||||
오르므로 같은 worker id가 다시 claim해도 앞 실행의 쓰기는 0행이다(예: `DurableOperationClaim`).
|
||||
- `WHERE id IN (SELECT … LIMIT n)`으로 고른 행을 바꿀 때는 subquery를 `FOR UPDATE SKIP LOCKED`로 잠가 남이 쥔 행을
|
||||
고르지 않는다. 상태 조건도 바깥 `UPDATE … WHERE`에 한 번 더 둔다. 잠금 절이 빠지면 READ COMMITTED는 잠금을 기다린
|
||||
행에 바깥 조건만 다시 보고 subquery 안 조건은 보지 않기 때문이다(예: `RecipientClaimSql.EXPIRE_OVERDUE`). 잠그지 않는
|
||||
subquery라면 바깥 조건이 유일한 방어다(예: inbox `markAllRead`).
|
||||
- 만료는 그 시각을 쓴 시계로 본다. row lease(outbox, 알림 수신자, durable operation, fileserver cleanup,
|
||||
Mongo migration lock)는 앱 `Clock`으로 쓰고 앱 `Clock`으로 비교한다. 시험이 시계를 옮길 수 있게 하려는
|
||||
것이고, 대신 인스턴스 사이 시계 차이가 가장 짧은 lease보다 훨씬 작아야 한다(NTP 동기화가 배포 조건이다).
|
||||
DB가 쓴 시각은 DB 시계로(멱등성 `expires_at`은 `clock_timestamp()`로 쓰고 `now()`로 지운다), Redis가 쓴
|
||||
시각은 Redis `TIME`으로 본다. 한 저장소 안에서 두 시계를 섞지 않는다.
|
||||
- 수정 충돌 → 버전 열(낙관적 잠금). 예: `DurableOperationEntity`(persistence-jpa)의 `@Version` 열 `row_version`.
|
||||
- **예외**: DB가 볼 수 없는 규칙(외부 시스템 상태)은 분산 락(`DistributedLockPort`)이나 멱등성 키(05장).
|
||||
- 동시성 테스트는 실 DB lane에서 동시 요청 N개 → 행 1개를 단언한다.
|
||||
|
||||
@@ -44,6 +44,27 @@ DB 커밋 중 연결 끊김 ─────────────────
|
||||
executor 조립과 실제 PostgreSQL 저장소 왕복은 `PostgreSqlIdempotencyProviderIntegrationTest`(app-bootstrap
|
||||
`integrationTest`)다. KEYED 유스케이스를 HTTP부터 끝까지 이은 업무 기능 예는 템플릿에 없다.
|
||||
|
||||
### executor를 쓰지 않는 중복 판정 둘 (2026-11-13 결정)
|
||||
|
||||
템플릿에는 `IdempotencyExecutor` 말고 중복을 판정하는 곳이 둘 더 있다. 둘 다 일부러 executor로 옮기지 않는다.
|
||||
executor는 **응답을 다시 돌려주는 기록**이다: HTTP `Idempotency-Key` 헤더로 들어오고, 원본 키 대신 scope digest만
|
||||
저장하고, 기록은 TTL이 지나면 지운다. 아래 둘은 **업무 행 자체의 정체성**이라 수명과 판정 대상이 다르다.
|
||||
|
||||
| 어디 | 키 | 같은 키·같은 요청 | 같은 키·다른 요청 | 수명 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| executor(KEYED 유스케이스) | `Idempotency-Key` 헤더의 scope digest | 저장된 응답 재생 | 422 `IDEMPOTENT_REQUEST_MISMATCH` | TTL |
|
||||
| 알림 받기(`AcceptNotificationApplicationUseCase`) | 본문의 `idempotencyKey`. 없으면 알림 plan 지문 | 처음 만든 알림의 receipt | `IDEMPOTENCY_CONFLICT`(요청 지문 비교) | 알림 행과 같다 |
|
||||
| durable operation 제출(`SubmitDurableOperationUseCase`) | 제출 scope(tenant·principal·operation 이름)와 payload 지문 | 처음 받은 operation | 지문이 키에 들어 있어 다른 키다. 새 operation | operation 보존 기간 |
|
||||
|
||||
- 알림: 키는 tenant 안에서 같은 알림을 한 번만 만드는 업무 키다. 저장소의 유일 제약이 동시 제출을 막고, 진 쪽은 이긴 행을
|
||||
읽어 같은 receipt로 수렴한다. 키를 주지 않은 호출자도 중복을 막도록 plan 지문으로 키를 만든다. executor로 옮기면 TTL
|
||||
뒤 같은 알림을 다시 만들고, 키 없는 호출은 중복을 막지 못한다. 저장한 키 값을 어떻게 다룰지(원본 저장)는 보안 검토
|
||||
항목이다.
|
||||
- durable operation: 결정 15·26(서버가 id를 만들고 payload 지문으로 재제출을 판정)이 정한다. capability의 `KEYED`는
|
||||
"같은 scope·같은 payload로 다시 보내면 같은 작업"이라는 뜻이고, 그 판정은 operation 저장소의 scope 유일성이 한다.
|
||||
- 새 기능이 이 둘을 따라 할 일은 거의 없다. 클라이언트가 응답을 못 받아 다시 보내는 쓰기는 위 순서대로 executor를 쓴다.
|
||||
업무 행 자체가 영구히 하나여야 하면(04장 유일 제약) 그 행의 키로 판정한다.
|
||||
|
||||
## 클라이언트에게 무엇을 약속하나
|
||||
|
||||
| 응답 | 의미 | 클라이언트 행동 |
|
||||
@@ -57,7 +78,10 @@ executor 조립과 실제 PostgreSQL 저장소 왕복은 `PostgreSqlIdempotencyP
|
||||
|
||||
같은 키 재전송이 무엇을 막는지는 저장소마다 다르다(정본
|
||||
`docs/web/http-contract.md` 2절). Redis 저장소에서 같은 키 재전송은 효과가 있었을 수 있는 작업을 다시 돌리지
|
||||
않는다. PostgreSQL 저장소를 템플릿처럼 쓰기 트랜잭션 하나로 쓰면 실패한 요청의 기록은 롤백되어 다음 같은 키
|
||||
않는다. 단, 그 기록이 Redis에 남아 있는 동안만이다. Sentinel·Cluster failover는 비동기 복제라 primary가 받고
|
||||
replica에 아직 넘기지 못한 기록을 잃을 수 있고, 그러면 같은 키 요청은 처음 보는 키로 다시 실행된다
|
||||
(`docs/runbooks/redis-capability-incident.md` 「Topology and persistence」). 이 창이 업무상 받아들일 수 없는
|
||||
작업은 PostgreSQL 저장소를 쓰거나 업무 데이터의 유일 제약으로 따로 막는다. PostgreSQL 저장소를 템플릿처럼 쓰기 트랜잭션 하나로 쓰면 실패한 요청의 기록은 롤백되어 다음 같은 키
|
||||
요청이 다시 실행한다. 그래서 트랜잭션 밖 효과는 따로 멱등하게 만든다. 첫 시도가 processing lease(기본 30s)보다
|
||||
오래 걸릴 때 보이는 모습도 저장소마다 다르다.
|
||||
|
||||
|
||||
@@ -91,7 +91,7 @@ client가 같은 이름의 역할을 정의해도 이 서비스 권한이 되지
|
||||
|
||||
| 경로 | 어디에 두나 | 유스케이스는 누가 만드나 |
|
||||
| --- | --- | --- |
|
||||
| 조립 모듈의 스케줄러 | `composition:*` leaf. 예: outbox relay(`src/bootstrap/outbox-relay`) | 조립 모듈의 `@Bean` 메서드가 `new`로 만들어 스케줄러에 넘긴다 |
|
||||
| 조립 모듈의 스케줄러 | `composition:*` leaf. 예: outbox relay(`src/bootstrap/outbox-relay`), 알림 worker(`NotificationWorkerConfiguration`), fileserver cleanup worker(`FileserverCleanupWorker`) | 조립 모듈의 `@Bean` 메서드가 `new`로 만들어 스케줄러에 넘긴다. worker 생성자가 받은 서비스로 만들어도 같다 |
|
||||
| 메시지 handler | `adapter:inbound:messaging` leaf, 또는 서비스 leaf의 `..adapter.inbound.messaging..` 패키지 | handler 생성자가 port를 받아 `new`로 만든다. handler에 `@SystemCaller`. 작업 순서는 09장 「소비」 4단계 |
|
||||
| 예약 작업 | 서비스 자기 leaf의 `..adapter.inbound.scheduler..` 패키지. 등록된 scheduler leaf는 없다 | 작업 클래스 생성자가 port를 받아 `new`로 만든다. 작업 클래스에 `@SystemCaller`. 모양은 메시지 handler와 같고, 깨우는 것이 `@Scheduled` 메서드다. `Runnable`·`ApplicationRunner` 같은 프로젝트 밖 타입을 구현하지 않는다. task scheduler에 직접 등록하면 그 자리에서 `job::run`을 넘긴다 |
|
||||
|
||||
@@ -105,6 +105,7 @@ client가 같은 이름의 역할을 정의해도 이 서비스 권한이 되지
|
||||
| bean 금지 | `@SystemInvoked` 유스케이스가 bean이면 기동 실패. 호출자가 `new`로 만들어 혼자 들고 있는 것만 허용한다 | `src/bootstrap/service-runtime/src/main/java/dev/caskeleton/composition/runtime/authorization/PermissionEnforcementGuard.java` |
|
||||
| 시스템 호출자만 | inbound adapter가 그 클래스에 의존하면 빌드 실패. `@SystemCaller(reason = "...")`를 단 클래스와 그 안에 중첩된 클래스만 예외. inbound 밖 사용자 전송과 중간 클래스를 거친 길은 아래 「전송 → 시스템 호출자 금지」가 잡는다 | `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`(`ApplicationBoundaryArchitectureTest`) |
|
||||
| controller 위치 | Spring controller는 `..adapter.inbound..`에만 둔다. 조립 루트나 조립 모듈에 둔 controller는 빌드 실패 | `CONTROLLERS_LIVE_IN_INBOUND_ADAPTERS`(`AdapterBoundaryArchitectureTest`) |
|
||||
| 감싼 서비스 금지 | inbound adapter가 application의 `*Service`·`*Orchestrator`·`*Coordinator`에 의존하면 빌드 실패. interface도 든다. 유스케이스를 구현한 타입은 빠진다. `@SystemInvoked` 유스케이스가 감싸는 서비스(fileserver `CleanupService`, 알림 `ReconciliationService` 등)는 bean이고 권한 검사 없이 쓰기 때문이다 | `INBOUND_ADAPTERS_DEPEND_ON_PORTS_NOT_APPLICATION_SERVICES`(`AdapterBoundaryArchitectureTest`) |
|
||||
| 표시 검사 | `@SystemCaller` 클래스와 그 안에 중첩된 클래스는 `..adapter.inbound.messaging..`·`..adapter.inbound.scheduler..`에만 있고, 사용자 전송 타입(controller·JAX-RS·GraphQL·STOMP mapping과 channel interceptor·gRPC·servlet)에 의존하지 않는다 | `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`(같은 파일) |
|
||||
| 전송 → 시스템 호출자 금지 | 사용자 전송 클래스가 `@SystemCaller`나, 그 클래스가 구현·상속하는 프로젝트 타입(작업의 인터페이스 등), 또는 `@SystemInvoked` 유스케이스 자신에 의존하면 빌드 실패. 중간 클래스를 거쳐도 잡는다. 사용자 전송 타입에는 Spring Security의 요청 경로 확장점(`org.springframework.security.web`·`.config.annotation.web`·`.oauth2.server.resource`·`.oauth2.jwt` 패키지, `AuthenticationProvider`, `AuthorizationManager`)이 든다. 그래서 web 패키지 밖에 둔 JWT converter나 authorization manager도 사용자 전송이다. 사용자 전송 클래스는 넷이다. ① 사용자 전송 패키지에 있는 클래스. ② 설정(`@Configuration`·`@AutoConfiguration`) 클래스 자신이 요청 처리기 타입(함수형 `RouterFunction`·`HandlerFunction`, `@RestController`·`@RequestMapping`, servlet·`Filter`·`HandlerInterceptor`, `WebSocketHandler`, GraphQL `DataFetcher`·`RuntimeWiringConfigurer`, gRPC `BindableService`·`ServerInterceptor`, STOMP `ChannelInterceptor`·`ExecutorChannelInterceptor` 등)에 의존하는 것. 요청 처리 코드를 설정에 직접 쓴 경우와 등록만 한 경우가 모두 든다. 요청 처리기 타입을 구현·상속한 프로젝트 클래스(예: `ChannelInterceptor`를 구현한 interceptor)를 필드·생성자 인자·`new`로 쥔 설정도 든다. `registration.interceptors(frameCounter)`는 클래스 의존으로 `ChannelRegistration`만 남기므로 그 필드의 타입이 설정을 사용자 전송으로 만든다. channel interceptor를 구현한 설정은 프레임마다 자기 메서드가 돈다. interceptor를 `@Bean`으로 내놓는 설정은 route를 등록하는 설정과 같다. 함수형 route나 data fetcher를 람다로 쓰면 그 코드가 설정 클래스의 메서드로 컴파일되어 설정이 곧 endpoint다. 처리 코드를 다른 클래스에 두고 메서드 참조로 등록만 해도(`route().GET("/orders", orders::list)`) 설정은 route builder에 의존한다. 클래스 의존으로는 등록과 처리 코드를 가를 수 없어서 둘 다 사용자 전송으로 센다. ③ 설정 안에 중첩된 클래스 가운데 사용자 전송 타입에 의존하는 것. 중첩된 JAX-RS 자원·`@ServerEndpoint`, `configureClientInboundChannel`에서 등록하는 STOMP channel interceptor(익명 클래스여도, STOMP 헤더를 읽지 않아도)도 여기서 잡힌다. 설정용 타입(`WebMvcConfigurer`·`WebSocketConfigurer`·STOMP broker 설정과 그 registry, CORS 설정, `RequestMethod`)에만 의존하는 중첩 클래스는 설정의 일부로 본다. inbound channel의 thread 수만 정하는 설정도 설정용이다. ④ 그 밖의 클래스 가운데 사용자 전송 타입에 의존하는 것. 사용자 전송 패키지 밖에 둔 channel interceptor가 여기에 든다. 그래서 handler를 bean으로 등록하는 설정은 같은 클래스에서 `WebMvcConfigurer`(설정 필드를 읽는 익명 클래스여도)·CORS 설정·controller bean을 함께 만들어도 걸리지 않는다. 같은 클래스에 "지금 실행" route·data fetcher·interceptor를 쓰거나, route를 등록하거나, 안에 중첩한 endpoint가 작업을 부르면(설정의 메서드를 거쳐 불러도) 걸린다. route·data fetcher·interceptor 등록은 handler bean을 만드는 설정과 다른 설정에 둔다. 설정이 만드는 controller는 controller 자신이 검사받는다 | `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`(같은 파일) |
|
||||
| 프로젝트 밖 상위 타입 금지 | `@SystemCaller` 클래스와 그 안에 중첩된 클래스(익명·지역 클래스와 예외 제외)는 프로젝트(`dev.caskeleton..`와 소유자의 별도 repo 라이브러리 `dev.cakit..`) 밖의 클래스·인터페이스를 상속·구현하지 않는다. `Runnable`은 누구나 의존하는 타입이라, endpoint가 작업을 `Runnable`로 주입받아도 위 규칙이 다른 사용과 구별하지 못하기 때문이다. 메시지 handler의 `MessageHandler<T>`(메시징 라이브러리 `dev.cakit.messaging`)는 프로젝트 타입으로 쳐서 된다. record·enum은 언어가 붙이는 상위 타입(`Record`, `Enum`과 `Enum`이 구현하는 `Comparable`·`Serializable`·`Constable`)만은 가져도 된다. 그래서 handler 안의 파싱 결과 record, 결과 enum, 독(poison) 메시지 예외, record로 쓴 handler는 통과하고, `Runnable`을 구현한 record는 걸린다 | `SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`(같은 파일) |
|
||||
@@ -165,7 +166,7 @@ web이 빠진 조립(gRPC 전용·배치 전용)에는 `@RequiresPermission`을
|
||||
- 쓰기 = `@RequiresPermission` + non-final + bean + 역할 매핑.
|
||||
- 시스템만 부르는 쓰기 = `@SystemInvoked` + bean 아님 + 사용자 전송에서 안 닿음. 부르는 쪽은 셋뿐이다:
|
||||
조립 모듈의 스케줄러, `@SystemCaller` 메시지 handler, `@SystemCaller` 예약 작업. 사용자 전송은
|
||||
`@SystemCaller`에도, 그 작업의 인터페이스에도 닿지 못한다. 타입 이름이 남지 않는 길(이름으로 찾기,
|
||||
설정이 넘기는 함수)은 빌드가 못 보니 리뷰가 막는다.
|
||||
`@SystemCaller`에도, 그 작업의 인터페이스에도, 유스케이스가 감싸는 서비스에도 닿지 못한다. 타입 이름이
|
||||
남지 않는 길(이름으로 찾기, 설정이 넘기는 함수)은 빌드가 못 보니 리뷰가 막는다.
|
||||
- 객체 판정은 유스케이스 안, 남의 것은 404.
|
||||
- 역할은 자기 client 것만 읽는다.
|
||||
|
||||
@@ -41,7 +41,10 @@ email을 모든 tenant에 걸쳐 유일하게 만든다. 그러면 tenant A가
|
||||
## 2. tenant마다 database (Experimental)
|
||||
|
||||
`MongoTenantClientRegistry`는 tenant마다 client를 하나 둔다. 개수 상한이 있고 쓰지 않는 client는
|
||||
내보낸다. tenant를 어느 database에 대응시킬지는 도입하는 쪽의 코드가 정한다.
|
||||
내보낸다. tenant를 어느 database에 대응시킬지는 도입하는 쪽의 코드가 정한다. `acquire`는 `Lease`를 돌려주고,
|
||||
그 client는 lease를 모두 닫을 때까지 쓰는 중이다. 쓰는 중인 client는 얼마나 오래전에 받았든 내보내지 않는다.
|
||||
내보낸 client를 닫다가 실패하면 그 tenant 대신 `evictionCloseFailures()`가 센다. 닫기를 부른 다른 tenant의
|
||||
`acquire`는 실패하지 않는다(round9 리뷰 2026-11-12, RR9-01-27).
|
||||
|
||||
Experimental인 이유가 분명하다. 작을 때는 맞고, 클 때는 한계가 없다. tenant database마다 connection,
|
||||
file handle, 모니터링 가짓수가 든다. tenant 20개에서는 잘 돌고 2,000개에서는 쓰러진다. 기능 테스트로는
|
||||
|
||||
@@ -39,9 +39,15 @@ regex는 index를 쓰는 척하는 collection 전체 scan이고, 사용자가
|
||||
| 상한 | 이유 |
|
||||
|---|---|
|
||||
| `maxTimeMS` | 아무도 기다리지 않는 query를 서버가 멈춘다. |
|
||||
| 결과 개수 상한 | 상한 없는 결과는 단계가 몇 개 더 붙은 OOM이다. |
|
||||
| batch 크기 | 왕복 한 번의 메모리를 제한한다. |
|
||||
| 검사한 문서 수 상한 | 빠른 날에는 시간 상한만으로 숨겨지는 index 회귀를 잡는다. |
|
||||
| 결과 개수 상한(`maxResults`) | 상한 없는 결과는 단계가 몇 개 더 붙은 OOM이다. |
|
||||
| 결과 바이트 상한(`maxResultBytes`) | 문서 하나하나가 크면 개수 상한 안에서도 heap이 찬다. |
|
||||
| batch 크기(`cursorBatchSize`) | 왕복 한 번의 메모리를 제한한다. |
|
||||
|
||||
개수·시간·batch는 서버에 보내는 요청에 실린다(`PolicyAwareMongoQueryBuilder.build`가 만든 `Query`, aggregation의
|
||||
`$limit`과 옵션). 바이트는 결과를 읽는 쪽만 셀 수 있다. aggregation은 `PolicyAwareMongoAggregationExecutor`가
|
||||
cursor에서 문서를 하나씩 읽으며 encode한 크기를 더하고 넘으면 거부한다(5절). query builder는 `Query`만 돌려주므로
|
||||
query의 바이트 상한을 집행하는 템플릿 코드는 없다. 그 `Query`로 결과를 읽는 서비스의 adapter가 `maxResultBytes`를
|
||||
직접 센다. 세지 않으면 그 상한은 선언일 뿐이다.
|
||||
|
||||
`MongoBudgetPolicyRegistry`가 예산을 연산 이름에 묶는다. `MongoBudgetEnforcer`가 그것을 적용한다. 요청이
|
||||
예산을 넘으면 실행 전에 `MongoOperationRejectedException`을 던지고, 서버가 상한을 집행하면
|
||||
@@ -86,6 +92,11 @@ regex는 index를 쓰는 척하는 collection 전체 scan이고, 사용자가
|
||||
| high | `$lookup`, `$graphLookup`, `$facet`, index 없는 `$sort` | profile의 명시적 승인이 필요하다. |
|
||||
| forbidden | admin plane 밖의 `$out`·`$merge`, `$function`, `$accumulator` | 거부한다. |
|
||||
|
||||
실행은 예산 둘을 결과가 오는 동안 본다. pipeline 끝에 `$limit(maxResults + 1)`을 붙여 서버가 예산보다 한 개 넘게는
|
||||
만들지 않게 하고, 결과를 cursor에서 한 문서씩 읽으며 개수와 encode한 바이트를 더한다. 둘 중 하나라도 넘으면
|
||||
`MongoOperationRejectedException`(`aggregation.result`)이다. 예전에는 결과를 전부 메모리에 올린 뒤 개수만 셌고 바이트
|
||||
상한은 선언만 있었다(round9 리뷰 2026-11-12, RR9-01-20).
|
||||
|
||||
`allowDiskUse`는 실행 중 flag가 아니라 plan에 선언하는 속성이다. 디스크가 필요한 pipeline은 모양을 검토해야
|
||||
하는 pipeline이다.
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
# Every top-level public type under the platform packages. Growth is a reviewed change.
|
||||
# Update only after review with:
|
||||
# ./gradlew :adapter:outbound:notification:updateNotificationApiSurface -PapproveNotificationApiSurfaceChange
|
||||
# types: 364
|
||||
# types: 375
|
||||
dev.caskeleton.adapter.outbound.notification.NotificationConfig
|
||||
dev.caskeleton.adapter.outbound.notification.NotificationRoutesSettings
|
||||
dev.caskeleton.adapter.outbound.notification.core.FailOpenNotificationProvider
|
||||
@@ -35,14 +35,10 @@ dev.caskeleton.adapter.outbound.notification.platform.dispatch.CapabilityReconci
|
||||
dev.caskeleton.adapter.outbound.notification.platform.dispatch.ConfiguredProfileCatalog
|
||||
dev.caskeleton.adapter.outbound.notification.platform.dispatch.JacksonRoutingPlanCodec
|
||||
dev.caskeleton.adapter.outbound.notification.platform.dispatch.LoggingInboxSignalPublisher
|
||||
dev.caskeleton.adapter.outbound.notification.platform.dispatch.NotificationBackgroundWorkers
|
||||
dev.caskeleton.adapter.outbound.notification.platform.dispatch.NotificationDispatchProperties
|
||||
dev.caskeleton.adapter.outbound.notification.platform.dispatch.NotificationSchedulerWorker
|
||||
dev.caskeleton.adapter.outbound.notification.platform.dispatch.ProviderAttemptLimiter
|
||||
dev.caskeleton.adapter.outbound.notification.platform.dispatch.ProviderEventReplayWorker
|
||||
dev.caskeleton.adapter.outbound.notification.platform.dispatch.ProviderRuntime
|
||||
dev.caskeleton.adapter.outbound.notification.platform.dispatch.ProviderRuntimeRegistry
|
||||
dev.caskeleton.adapter.outbound.notification.platform.dispatch.ReconciliationJobWorker
|
||||
dev.caskeleton.adapter.outbound.notification.platform.dispatch.RegistryProviderDispatchGateway
|
||||
dev.caskeleton.adapter.outbound.notification.platform.dispatch.RegistryProviderRuntimeControl
|
||||
dev.caskeleton.adapter.outbound.notification.platform.dispatch.SingleTenantContext
|
||||
@@ -104,16 +100,23 @@ dev.caskeleton.application.notification.platform.admin.AdminAuthorizationGuard
|
||||
dev.caskeleton.application.notification.platform.admin.AdminOperationClaim
|
||||
dev.caskeleton.application.notification.platform.admin.AdminOperationResult
|
||||
dev.caskeleton.application.notification.platform.admin.AdminOperationStorePort
|
||||
dev.caskeleton.application.notification.platform.admin.ChangeProviderStateCommand
|
||||
dev.caskeleton.application.notification.platform.admin.ChangeProviderStateUseCase
|
||||
dev.caskeleton.application.notification.platform.admin.ChangeSuppressionCommand
|
||||
dev.caskeleton.application.notification.platform.admin.ChangeSuppressionUseCase
|
||||
dev.caskeleton.application.notification.platform.admin.DuplicateRiskApprovalRequiredException
|
||||
dev.caskeleton.application.notification.platform.admin.DuplicateRiskGuard
|
||||
dev.caskeleton.application.notification.platform.admin.NotificationAdminApplicationService
|
||||
dev.caskeleton.application.notification.platform.admin.NotificationAdminAuthority
|
||||
dev.caskeleton.application.notification.platform.admin.NotificationAdminService
|
||||
dev.caskeleton.application.notification.platform.admin.NotificationAdminPermissions
|
||||
dev.caskeleton.application.notification.platform.admin.ProviderRuntimeControlPort
|
||||
dev.caskeleton.application.notification.platform.admin.ReconcileCommand
|
||||
dev.caskeleton.application.notification.platform.admin.RedriveCommand
|
||||
dev.caskeleton.application.notification.platform.admin.SetProviderStateCommand
|
||||
dev.caskeleton.application.notification.platform.admin.SuppressCommand
|
||||
dev.caskeleton.application.notification.platform.admin.ProviderStateRequest
|
||||
dev.caskeleton.application.notification.platform.admin.ReconcileDeliveriesCommand
|
||||
dev.caskeleton.application.notification.platform.admin.ReconcileDeliveriesUseCase
|
||||
dev.caskeleton.application.notification.platform.admin.ReconcileRequest
|
||||
dev.caskeleton.application.notification.platform.admin.RedriveDeliveryCommand
|
||||
dev.caskeleton.application.notification.platform.admin.RedriveDeliveryUseCase
|
||||
dev.caskeleton.application.notification.platform.admin.RedriveRequest
|
||||
dev.caskeleton.application.notification.platform.admin.SuppressionRequest
|
||||
dev.caskeleton.application.notification.platform.api.CallbackIngestionResult
|
||||
dev.caskeleton.application.notification.platform.api.CancelCommand
|
||||
dev.caskeleton.application.notification.platform.api.CancelResult
|
||||
@@ -136,7 +139,6 @@ dev.caskeleton.application.notification.platform.api.NotificationPlan
|
||||
dev.caskeleton.application.notification.platform.api.NotificationReceipt
|
||||
dev.caskeleton.application.notification.platform.api.NotificationSnapshot
|
||||
dev.caskeleton.application.notification.platform.api.NotificationVariable
|
||||
dev.caskeleton.application.notification.platform.api.ProviderEventId
|
||||
dev.caskeleton.application.notification.platform.api.ProviderId
|
||||
dev.caskeleton.application.notification.platform.api.ProviderProfileId
|
||||
dev.caskeleton.application.notification.platform.api.RecipientDeliveryId
|
||||
@@ -168,7 +170,6 @@ dev.caskeleton.application.notification.platform.api.error.CallbackValidationExc
|
||||
dev.caskeleton.application.notification.platform.api.error.FailureCategory
|
||||
dev.caskeleton.application.notification.platform.api.error.IdempotencyConflictException
|
||||
dev.caskeleton.application.notification.platform.api.error.NotificationException
|
||||
dev.caskeleton.application.notification.platform.api.error.NotificationExpiredException
|
||||
dev.caskeleton.application.notification.platform.api.error.NotificationFailureCode
|
||||
dev.caskeleton.application.notification.platform.api.error.NotificationFailureDescriptor
|
||||
dev.caskeleton.application.notification.platform.api.error.NotificationValidationException
|
||||
@@ -200,6 +201,8 @@ dev.caskeleton.application.notification.platform.callback.ProviderEventRecord
|
||||
dev.caskeleton.application.notification.platform.callback.ProviderEventRecordId
|
||||
dev.caskeleton.application.notification.platform.callback.ProviderEventSource
|
||||
dev.caskeleton.application.notification.platform.callback.ProviderRequestIdHash
|
||||
dev.caskeleton.application.notification.platform.callback.ReplayProviderEventsCommand
|
||||
dev.caskeleton.application.notification.platform.callback.ReplayProviderEventsUseCase
|
||||
dev.caskeleton.application.notification.platform.callback.StandardDeliveryProjector
|
||||
dev.caskeleton.application.notification.platform.callback.SuppressionFacts
|
||||
dev.caskeleton.application.notification.platform.callback.VerifiedProviderEvent
|
||||
@@ -220,11 +223,15 @@ dev.caskeleton.application.notification.platform.dispatch.AttachmentIntegrityGua
|
||||
dev.caskeleton.application.notification.platform.dispatch.CancelNotificationApplicationUseCase
|
||||
dev.caskeleton.application.notification.platform.dispatch.CanonicalNotificationPlanEncoder
|
||||
dev.caskeleton.application.notification.platform.dispatch.CanonicalNotificationPlanWriter
|
||||
dev.caskeleton.application.notification.platform.dispatch.ClaimDueDeliveriesCommand
|
||||
dev.caskeleton.application.notification.platform.dispatch.ClaimDueDeliveriesUseCase
|
||||
dev.caskeleton.application.notification.platform.dispatch.ContactPointRecord
|
||||
dev.caskeleton.application.notification.platform.dispatch.ContactPointStorePort
|
||||
dev.caskeleton.application.notification.platform.dispatch.DeliveryAttemptFactory
|
||||
dev.caskeleton.application.notification.platform.dispatch.DeliveryAttemptRecord
|
||||
dev.caskeleton.application.notification.platform.dispatch.DeliveryAttemptStorePort
|
||||
dev.caskeleton.application.notification.platform.dispatch.DispatchClaimedDeliveryCommand
|
||||
dev.caskeleton.application.notification.platform.dispatch.DispatchClaimedDeliveryUseCase
|
||||
dev.caskeleton.application.notification.platform.dispatch.DispatchGuardOutcome
|
||||
dev.caskeleton.application.notification.platform.dispatch.DispatchOutcomeRecorder
|
||||
dev.caskeleton.application.notification.platform.dispatch.DispatchPipeline
|
||||
@@ -251,10 +258,14 @@ dev.caskeleton.application.notification.platform.dispatch.RecipientDeliveryRecor
|
||||
dev.caskeleton.application.notification.platform.dispatch.RecipientDeliveryStorePort
|
||||
dev.caskeleton.application.notification.platform.dispatch.RecipientLease
|
||||
dev.caskeleton.application.notification.platform.dispatch.RecipientLeaseStorePort
|
||||
dev.caskeleton.application.notification.platform.dispatch.ReconcileOutstandingAttemptsCommand
|
||||
dev.caskeleton.application.notification.platform.dispatch.ReconcileOutstandingAttemptsUseCase
|
||||
dev.caskeleton.application.notification.platform.dispatch.ReconciliationGatewayPort
|
||||
dev.caskeleton.application.notification.platform.dispatch.ReconciliationJob
|
||||
dev.caskeleton.application.notification.platform.dispatch.ReconciliationJobStorePort
|
||||
dev.caskeleton.application.notification.platform.dispatch.ReconciliationService
|
||||
dev.caskeleton.application.notification.platform.dispatch.RecoverAbandonedDeliveriesCommand
|
||||
dev.caskeleton.application.notification.platform.dispatch.RecoverAbandonedDeliveriesUseCase
|
||||
dev.caskeleton.application.notification.platform.dispatch.ScheduleNotificationApplicationUseCase
|
||||
dev.caskeleton.application.notification.platform.dispatch.SubmitNotificationApplicationUseCase
|
||||
dev.caskeleton.application.notification.platform.dispatch.SuppressionSideEffect
|
||||
@@ -276,6 +287,8 @@ dev.caskeleton.application.notification.platform.inbox.NotificationInbox
|
||||
dev.caskeleton.application.notification.platform.inbox.NotificationInboxSignalPort
|
||||
dev.caskeleton.application.notification.platform.observation.CardinalityGuard
|
||||
dev.caskeleton.application.notification.platform.observation.IllegalMetricTagException
|
||||
dev.caskeleton.application.notification.platform.observation.MeasureDispatchBacklogQuery
|
||||
dev.caskeleton.application.notification.platform.observation.MeasureDispatchBacklogUseCase
|
||||
dev.caskeleton.application.notification.platform.observation.NotificationAuditEvent
|
||||
dev.caskeleton.application.notification.platform.observation.NotificationAuditPort
|
||||
dev.caskeleton.application.notification.platform.observation.NotificationMetricName
|
||||
@@ -303,6 +316,7 @@ dev.caskeleton.application.notification.platform.policy.RetryBackoff
|
||||
dev.caskeleton.application.notification.platform.policy.RetryBudget
|
||||
dev.caskeleton.application.notification.platform.policy.RetryContext
|
||||
dev.caskeleton.application.notification.platform.policy.RetryDecision
|
||||
dev.caskeleton.application.notification.platform.policy.RetryTiming
|
||||
dev.caskeleton.application.notification.platform.policy.RouteCandidate
|
||||
dev.caskeleton.application.notification.platform.policy.RoutingContext
|
||||
dev.caskeleton.application.notification.platform.policy.RoutingDecision
|
||||
@@ -329,14 +343,11 @@ dev.caskeleton.application.notification.platform.port.in.SubmitNotificationComma
|
||||
dev.caskeleton.application.notification.platform.port.in.SubmitNotificationUseCase
|
||||
dev.caskeleton.application.notification.platform.provider.AttachmentAccessContext
|
||||
dev.caskeleton.application.notification.platform.provider.AttachmentResolver
|
||||
dev.caskeleton.application.notification.platform.provider.BatchNotificationProviderAdapter
|
||||
dev.caskeleton.application.notification.platform.provider.CollapseCapability
|
||||
dev.caskeleton.application.notification.platform.provider.EvidenceCertainty
|
||||
dev.caskeleton.application.notification.platform.provider.EvidenceFact
|
||||
dev.caskeleton.application.notification.platform.provider.NotificationProviderAdapter
|
||||
dev.caskeleton.application.notification.platform.provider.ProviderCallNotStartedException
|
||||
dev.caskeleton.application.notification.platform.provider.ProviderCapabilities
|
||||
dev.caskeleton.application.notification.platform.provider.ProviderCollapseMapping
|
||||
dev.caskeleton.application.notification.platform.provider.ProviderExecutionEvidence
|
||||
dev.caskeleton.application.notification.platform.provider.ProviderFailure
|
||||
dev.caskeleton.application.notification.platform.provider.ProviderProfileSnapshot
|
||||
|
||||
@@ -26,7 +26,7 @@ support leaf의 `ModuleDefaultsEnvironmentPostProcessor`가 가장 낮은 우선
|
||||
| 속성 | 환경 변수 | 기본값 | 범위 |
|
||||
|---|---|---|---|
|
||||
| `dispatch.claim-batch-size` | `APP_NOTIFICATION_PLATFORM_CLAIM_BATCH_SIZE` | `50` | 1..1000 |
|
||||
| `dispatch.lease-duration` | `APP_NOTIFICATION_PLATFORM_LEASE_DURATION` | `2m` | 양수, 유한 |
|
||||
| `dispatch.lease-duration` | `APP_NOTIFICATION_PLATFORM_LEASE_DURATION` | `2m` | 양수, 유한. `poll-interval`과 켜진 provider profile의 `timeout`보다 길어야 기동한다. SMTP profile은 `timeout`의 두 배보다 길어야 한다(「SMTP relay」) |
|
||||
| `dispatch.poll-interval` | `APP_NOTIFICATION_PLATFORM_POLL_INTERVAL` | `1s` | 양수, 유한 |
|
||||
| `dispatch.max-global-concurrency` | `APP_NOTIFICATION_PLATFORM_MAX_CONCURRENCY` | `64` | 양수 |
|
||||
| `dispatch.max-additional-attempts` | `APP_NOTIFICATION_PLATFORM_MAX_ADDITIONAL_ATTEMPTS` | `4` | 0 이상 |
|
||||
@@ -35,8 +35,23 @@ support leaf의 `ModuleDefaultsEnvironmentPostProcessor`가 가장 낮은 우선
|
||||
|
||||
모든 값에 상한이 있다. 「무제한」은 받는 설정이 아니다.
|
||||
|
||||
lease는 provider 호출과 그 시간 상한보다 길어야 한다. 그보다 짧으면, 살아 있는 worker가 아직 기다리는 전달을 두 번째
|
||||
worker가 claim하고, 수신자는 알림을 두 번 받는다.
|
||||
lease는 provider 호출 한 번이 delivery를 쥐는 시간보다 길어야 한다. 그보다 짧으면 아직 기다리는 호출이 멈춘 lease로
|
||||
보인다. lease가 끝난 뒤 lease만큼 더 지나도 호출이 끝나지 않았으면, lease 복구가 그 delivery를 버려진 것으로 보고 맞추기로
|
||||
넘긴다. 기본 제공 provider(SES·SMTP)는 결과 조회가 없어 운영자 확인(`RECONCILIATION_REQUIRED`)으로 넘어간다. 그 뒤에
|
||||
끝난 호출도 자기 결과를 기록한다(owner와 fence가 그대로다). 두 번째 worker가 다시 보내지는 않는다. claim은
|
||||
`DISPATCHING`인 delivery를 가져가지 않는다.
|
||||
|
||||
## 재시도 시각
|
||||
|
||||
| 속성 | 환경 변수 | 기본값 | 범위 |
|
||||
|---|---|---|---|
|
||||
| `retry.backoff-base` | 없음 | `1s` | 양수. 첫 재시도의 상한이자 가장 짧은 대기 |
|
||||
| `retry.backoff-max` | 없음 | `5m` | `backoff-base` 이상. provider의 `Retry-After`도 이 값을 넘지 못한다 |
|
||||
| `retry.reconcile-delay` | 없음 | `1m` | 0 이상. 결과를 모르는 제출 뒤 provider에 처음 물어보기까지 |
|
||||
|
||||
대기는 `backoff-base`와 지수로 늘어난 상한 사이의 full jitter다. 세 값에는 env 자리표시자가 없다. 배포의 설정
|
||||
파일(`application-{profile}.yml`)에서 바꾼다. 값은 provider의 호출 한도에 맞춰 정한다. 템플릿이 정할 일이 아니어서
|
||||
상수가 아니라 설정이다(2026-11-13).
|
||||
|
||||
## 콜백
|
||||
|
||||
@@ -131,7 +146,7 @@ Spring이 이미 그것을 가지고 있고, 두 번째 표기는 맞춰 둘 것
|
||||
| `providers.smtp.primary-for-channel` | `APP_NOTIFICATION_PLATFORM_SMTP_PRIMARY` | `true` | boolean. 채널마다 primary는 정확히 하나 |
|
||||
| `providers.smtp.environment` | `APP_NOTIFICATION_PLATFORM_SMTP_ENVIRONMENT` | `local` | 켜면 필요하다 |
|
||||
| `providers.smtp.credential-profile` | `APP_NOTIFICATION_PLATFORM_SMTP_CREDENTIAL_PROFILE` | `default` | `SecretMaterialProvider`로 푼다. 값을 직접 적지 않는다 |
|
||||
| `providers.smtp.timeout` | `APP_NOTIFICATION_PLATFORM_SMTP_TIMEOUT` | `10s` | 양수, 유한 |
|
||||
| `providers.smtp.timeout` | `APP_NOTIFICATION_PLATFORM_SMTP_TIMEOUT` | `30s` | 양수, 유한. `mail.smtp.connectiontimeout`에 `mail.smtp.timeout`·`mail.smtp.writetimeout` 중 긴 것을 더한 값보다 길어야 기동한다 |
|
||||
| `providers.smtp.max-concurrency` | `APP_NOTIFICATION_PLATFORM_SMTP_MAX_CONCURRENCY` | `4` | 양수 |
|
||||
| `providers.smtp.rate-per-second` | `APP_NOTIFICATION_PLATFORM_SMTP_RATE_PER_SECOND` | `10` | 양수 |
|
||||
|
||||
@@ -140,11 +155,40 @@ Spring이 이미 그것을 가지고 있고, 두 번째 표기는 맞춰 둘 것
|
||||
| `smtp.sender-identity` | `APP_NOTIFICATION_PLATFORM_SMTP_SENDER_IDENTITY` | `no-reply@example.invalid` | 주소 |
|
||||
| `smtp.dispatch-concurrency` | `APP_NOTIFICATION_PLATFORM_SMTP_DISPATCH_CONCURRENCY` | `4` | 양수 |
|
||||
|
||||
`smtp.dispatch-concurrency`는 SMTP 발송 pool의 thread 수다. 첫 발송부터 그만큼 함께 돌고, 대기열은 그 네 배다. 모든 SMTP
|
||||
profile이 이 pool 하나를 같이 쓴다. 켜진 SMTP profile들의 `max-concurrency` 합이 thread와 대기열을 합친 것보다 크면 SMTP
|
||||
조립이 기동 때 실패한다. pool이 가득 차서 거절한 발송은 relay에 닿지 않은 것으로 기록되어 다시 시도된다(결과 불명이
|
||||
아니다).
|
||||
|
||||
SMTP 전송 설정의 소유자는 Spring Mail 하나다. 실제 `JavaMailSenderImpl`은 필수 STARTTLS
|
||||
(`mail.smtp.starttls.enable=true`와 `mail.smtp.starttls.required=true`)나 암묵적 TLS(`mail.smtp.ssl.enable=true`)를
|
||||
써야 한다. `mail.smtp.connectiontimeout`, `mail.smtp.timeout`, `mail.smtp.writetimeout`도 양수여야 한다. 이 속성이
|
||||
없거나 틀리면 SMTP 조립이 트래픽을 받기 전에 실패한다.
|
||||
|
||||
이 socket timeout은 SMTP 명령 하나씩을 묶을 뿐 대화 전체를 묶지 않는다. 발송 한 번 전체는 provider profile의 `timeout`이
|
||||
두 번 묶는다(2026-11-13).
|
||||
|
||||
- pool 대기: 발송이 send pool에서 `timeout`이 지나도록 시작하지 못하면 버려지고 relay에 가지 않는다. relay에 닿지 않은
|
||||
것(`PROVIDER_UNAVAILABLE`, `CAPACITY_REJECTED`)으로 기록되어 다시 시도된다.
|
||||
- 발송: pool thread가 잡은 때부터 `timeout`이 지나면 결과 불명(`PROVIDER_RESPONSE_LOST`)으로 기록되고 자동으로 다시 보내지
|
||||
않는다. DATA가 이미 넘어갔을 수 있기 때문이다.
|
||||
|
||||
그래서 한 발송이 delivery lease를 쓰는 시간은 많아야 `timeout`의 두 배다. 기동 때 두 가지를 본다.
|
||||
|
||||
- `dispatch.lease-duration`은 SMTP `timeout`의 두 배보다 길어야 한다. 모든 provider에 거는 조건(lease가 `timeout`보다
|
||||
길다)보다 엄격하다. 짧으면 생기는 일은 위 「발송」 절의 lease 문단과 같다. 기본값(lease 2분, timeout 30초)은 맞는다.
|
||||
- profile `timeout`은 connect timeout에 명령 timeout 하나를 더한 값보다 길어야 한다. 그보다 짧으면 인사말을 주지 않는
|
||||
relay처럼 아무것도 보내지 않은 실패가, socket timeout이 알려 주기 전에 결과 불명으로 기록된다. 기본값(30초, connect 5초 +
|
||||
명령 10초)은 맞는다.
|
||||
|
||||
`dispatch.shutdown-grace`(기본 20초)가 `timeout`의 두 배보다 짧으면, 종료하는 동안 끝나지 않은 발송은 attempt가
|
||||
`DISPATCHING`으로 남고, 위 「발송」 절의 lease 문단대로 운영자 확인으로 넘어간다(종료된 발송은 결과를 기록하지 못한다).
|
||||
느린 relay에서 이것 없이 끝내려면 pod 종료 유예와 함께 grace를 늘린다.
|
||||
|
||||
send pool(`notificationSmtpExecutor` bean)을 바꿔 끼우면 발송을 부른 thread에서 돌리지 않는 executor여야 한다
|
||||
(`CallerRunsPolicy`나 직접 실행 executor는 안 된다). 부른 thread에서 돌면 두 시한이 dispatch thread를 풀지 못한다.
|
||||
`ThreadPoolExecutor`가 아니면 위의 pool 합 검사도 하지 않는다.
|
||||
|
||||
환경 변수 계약은 Spring 그대로다. `SPRING_MAIL_HOST`, `SPRING_MAIL_PORT`, 선택인 `SPRING_MAIL_USERNAME`과 secret
|
||||
`SPRING_MAIL_PASSWORD`, 그리고 `.env.example`에 있는 `SPRING_MAIL_PROPERTIES_MAIL_SMTP_*` TLS·시간 상한 키다. Spring
|
||||
Boot 자신이 `spring.mail.*`를 가지고 읽으므로 이름을 Spring 그대로 둔다. 알림 모듈은 같은 relay에 두 번째 별칭을
|
||||
|
||||
@@ -37,6 +37,31 @@ redrive는 `NotificationId`와 `RecipientDeliveryId`를 유지하고, 새 `Deliv
|
||||
렌더링 digest를 다시 쓴다. 다른 내용을 보내는 것은 redrive가 아니라 새 알림이다. 모호한 attempt를 redrive하려면 중복
|
||||
위험 승인을 명시해야 한다. 첫 제출이 사용자에게 닿았는지 플랫폼이 정말로 알 수 없기 때문이다.
|
||||
|
||||
## 운영자 연산
|
||||
|
||||
운영자 연산은 넷이고, 연산마다 유스케이스 하나다(`application.notification.platform.admin`의 클래스, command는 그 옆의
|
||||
`*Command`). 조립은 `composition:notification-platform`의 `NotificationAdminConfiguration`이 bean으로 한다.
|
||||
|
||||
| 유스케이스 | 하는 일 | permission | 운영자 authority |
|
||||
|---|---|---|---|
|
||||
| `RedriveDeliveryUseCase` | delivery 하나를 다시 보낼 차례로 돌린다 | `notification-admin:redrive` | `REDRIVE` |
|
||||
| `ReconcileDeliveriesUseCase` | attempt 묶음(200개까지)을 provider에 다시 묻는다 | `notification-admin:reconcile` | `RECONCILE` |
|
||||
| `ChangeSuppressionUseCase` | 억제 항목 하나를 더하거나 푼다 | `notification-admin:suppress` | `SUPPRESS` |
|
||||
| `ChangeProviderStateUseCase` | provider profile을 켜고 끄거나 drain한다 | `notification-admin:provider-control` | `PROVIDER_CONTROL`, tenant 범위 없는 운영자만 |
|
||||
|
||||
- 확인은 두 겹이다. permission은 전송의 호출자가 이 연산을 부를 수 있는지다(`@RequiresPermission`). authority와
|
||||
tenant 범위는 command의 `AdminActor`가 쥐고, 연산이 건드리는 delivery의 tenant와 대조한다.
|
||||
- 모든 연산은 운영자가 준 operation id로 멱등이다. 같은 id·같은 요청은 저장된 결과를 돌려주고, 같은 id·다른 요청은
|
||||
충돌이다. 대상 확인(tenant·중복 위험)과 claim과 쓰기는 한 쓰기 트랜잭션에서 커밋한다. reconcile만 대상 확인을 읽기
|
||||
트랜잭션에서 하고, provider 호출은 트랜잭션 밖에서 하며, claim과 결과를 따로 커밋한다.
|
||||
- dry run은 보고만 하고 쓰지 않는다. redrive와 reconcile의 dry run은 대상을 읽기 트랜잭션에서 읽는다. suppression과 provider 상태의 dry run은 아무것도 읽지 않는다.
|
||||
- 템플릿은 이 연산을 부르는 전송을 싣지 않는다. 운영자 화면이나 endpoint를 여는 서비스가 전송을 만든다.
|
||||
- 모듈 기본값(`composition:notification-platform`의 `config/module-defaults/notification.yml`)이 role
|
||||
`notification-admin`에 넷을 모두 준다(`app.authz.role-permissions`). 이 기본값의 정본은 그 파일이다. 운영자 role
|
||||
이름이 다르면 배포의 설정 파일에서 `app.authz.role-permissions`에 그 role을 더한다. IdP가 `notification-admin` role을
|
||||
다른 뜻으로 쓰면 배포의 설정 파일에서 `app.authz.role-permissions.notification-admin`에 그 role이 가질 permission 목록을
|
||||
적는다. 출처마다 map 항목이 합쳐지고 같은 키는 배포의 값이 이긴다.
|
||||
|
||||
## actuator 표면
|
||||
|
||||
provider 런타임 상태와 세대, 큐 깊이와 나이, 콜백과 맞추기 상태. 주소와 자격 증명은 절대 싣지 않는다.
|
||||
|
||||
@@ -2688,10 +2688,8 @@ env_keys:
|
||||
required_test: cache-contract:redis-semantic-region-bound
|
||||
|
||||
- name: APP_CACHE_REDIS_MAXIMUM_VALUE_BYTES
|
||||
# 폐기 2026-08-10: 이 속성을 바인딩하던 settings class를 옛 Redis 세대와 함께 지워서 이 키는 어디에도
|
||||
# 닿지 않는다. 아직 이 키를 쓰는 배포에 무엇이 대신하는지 알려 주려고 행을 지우지 않고 둔다.
|
||||
deprecated_orphaned: true
|
||||
removal_deadline: 2026-11-30
|
||||
# 2026-08-10에 옛 Redis 세대와 함께 폐기했다가, 2026-11-13 cache-redis 모듈 기본 설정이
|
||||
# app.capabilities.cache.maximum-value-bytes에 다시 묶었다. 상한을 넘는 값은 기록하지 않는다(round9 리뷰 RR9-01-18).
|
||||
type: int
|
||||
default: 1048576
|
||||
allowed_values: null
|
||||
@@ -4780,9 +4778,10 @@ env_keys:
|
||||
required_test: adapter-contract:notification-smtp-provider-assembled
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_SMTP_TIMEOUT
|
||||
# source: NTF-INT-001 — 이 profile의 시도마다 provider timeout.
|
||||
# source: NTF-INT-001 — 이 profile의 발송 한 번 상한: pool 대기와 발송이 각각 이 시간을 넘지 않는다.
|
||||
# 2026-11-13 10s에서 30s로 올렸다. 기동 때 mail.smtp.connectiontimeout + 명령 timeout보다 길어야 한다.
|
||||
type: duration
|
||||
default: 10s
|
||||
default: 30s
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
@@ -5063,7 +5062,8 @@ env_keys:
|
||||
required_test: adapter-contract:notification-dispatch-bounds
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_LEASE_DURATION
|
||||
# source: NTF-025 — provider 호출과 그 timeout보다 길어야 한다. 아니면 살아 있는 worker의 전달을 다른 worker가 claim한다
|
||||
# source: NTF-025 — poll-interval과 켜진 provider profile의 timeout보다 길어야 기동한다(2026-11-13부터 검사).
|
||||
# 짧으면 살아 있는 worker의 전달을 다른 worker가 claim한다. 넉넉히 길게 둔다: lease는 claim 때 시작한다
|
||||
type: duration
|
||||
default: 2m
|
||||
allowed_values: null
|
||||
|
||||
@@ -875,7 +875,7 @@ metrics:
|
||||
required_test: contract-verification:metrics-cardinality
|
||||
source: "src/application/notification/src/main/java/dev/caskeleton/application/notification/platform/observation/NotificationMetricName.java"
|
||||
constant: NotificationMetricName.QUEUE_DEPTH
|
||||
registered_by: "src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/dispatch/NotificationSchedulerWorker.java"
|
||||
registered_by: "src/bootstrap/notification-platform/src/main/java/dev/caskeleton/composition/notification/NotificationSchedulerWorker.java"
|
||||
|
||||
# === outbound HTTP client (adapter:outbound:httpclient를 켤 때) ===
|
||||
# Spring의 RestClient observation은 끄고 이 이름으로 기록한다(tag 이름도 이 leaf 것이다). attempt의 outcome은
|
||||
|
||||
@@ -226,3 +226,31 @@
|
||||
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
|
||||
- 묶음: B18c 낡은 이름·leaf 안내
|
||||
- 내용: `NotificationCallbackMvcController`는 204·400·413·503을 본문 없이 답한다. `docs/web/http-contract.md` §1과 `docs/fileserver/http-contract.md` 「Envelope 규칙의 프로토콜 예외」는 Envelope가 아닌 응답을 fileserver 프로토콜 예외뿐인 것처럼 적는다. 고침: 동작은 그대로 두고(provider는 status만 읽고, 인증 전 경로라 이유를 싣지 않는다) 예외로 적는다. 6절 ⑦.
|
||||
|
||||
### RR9-03-33 · Medium · 불변 Set capability로 만든 objectstorage 요청이 NullPointerException을 낸다
|
||||
|
||||
- 출처: 고치며 찾음(B20 포트 계약 첫 실행, 2026-11-13)
|
||||
- 증거: E2(desktop 실행: 계약 시험이 fake·adapter 모두 `ObjectRequestSupport.immutableCapabilities`의 NPE로 실패) · 이전부터
|
||||
- 묶음: B20 objectstorage 포트 계약
|
||||
- 내용: `src/application/objectstorage/src/main/java/dev/caskeleton/application/objectstorage/request/ObjectRequestSupport.java`가 null 원소를 거르려고 `capabilities.contains(null)`을 불렀다. JDK 불변 Set(`Set.of`, `Set.copyOf`)은 `contains(null)`에서 false 대신 NPE를 던진다. 지금 호출자가 모두 `EnumSet`을 넘겨 드러나지 않았다. 고침: 원소를 하나씩 본다.
|
||||
|
||||
### RR9-03-34 · Medium · adapter 전용 예외가 objectstorage 포트 밖으로 나간다
|
||||
|
||||
- 출처: 고치며 찾음(B20 새 눈 리뷰, 2026-11-13)
|
||||
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
|
||||
- 묶음: B21 objectstorage 포트 예외
|
||||
- 내용: routing adapter(`RoutingObjectReadAdapter`, `RoutingObjectMutationAdapter`, `RoutingObjectScanMaintenanceAdapter`)가 운영 bean으로 그대로 노출되고, provider의 `ObjectStorageProviderException`(adapter 패키지)을 감싸지 않고 던진다(바이트 불일치, consumer 실패, IO 실패). 포트를 쓰는 유스케이스가 adapter 타입을 잡아야 하거나 RuntimeException으로만 다룬다. 포트 계약도 그 경우는 unchecked 예외까지만 단언한다. 겹친 managed 게시에서 `PUBLISHED`로 바꾸기 직전에 다른 호출에 진 쪽도 `REPLAYED`가 아니라 adapter의 `ObjectControlConflictException`을 받는다(B20 3차 리뷰). 고침: 포트 수준 예외 타입을 두고 routing adapter가 포트 경계에서 바꾼다.
|
||||
|
||||
### RR9-03-35 · Low · 실패 뒤 다시 한 managed 게시가 REPLAYED로 답한다
|
||||
|
||||
- 출처: 고치며 찾음(B20 새 눈 리뷰, 2026-11-13)
|
||||
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
|
||||
- 묶음: B20 objectstorage 포트 계약
|
||||
- 내용: `ManagedObjectPublicationKernel`이 예약 결과만 보고 REPLAYED를 정해, 실패한 시도를 이어 이번 호출이 게시해도 REPLAYED였다. stage 재시도는 APPLIED라 둘이 달랐다. 고침: PUBLISHED로 바꾼 호출 하나만 APPLIED(같은 key로 겹친 호출은 REPLAYED, `ManagedPublicationOutcomeTest`).
|
||||
|
||||
### RR9-03-36 · Medium · main 단계 lane의 벽시계 시험이 부하 아래에서 흔들린다
|
||||
|
||||
- 출처: 고치며 찾음(main 단계 실패 run 추적, 2026-11-13)
|
||||
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
|
||||
- 묶음: B22 벽시계 시험
|
||||
- 내용: 시간 한도를 재는 시험이 준비 시간까지 재거나, 한도와 거의 같은 상한을 두거나, `sleep`으로 서버 처리 시간을 흉내 냈다. CPU가 바쁜 runner에서는 원인과 상관없이 시간만 넘겨 실패한다. 대상은 httpclient `FailureInjectionContractTest`·`AttemptDeadlineTest`, gRPC `GrpcP1BoundaryWireTest`·`GrpcServerRunnerBootTest`, graphql `GraphQlRequestDeadlineTest`, persistence-jpa lock·migration 시험, cache-redis lease 시험이다. 고침: 원인(타입·SQLSTATE·`lock_timeout`)을 먼저 단언하고, 재는 구간에서 준비를 빼고, 상한은 주장을 가를 만큼 넉넉히 두고, 서버 쪽 대기는 latch gate로 바꾼다.
|
||||
|
||||
@@ -317,3 +317,17 @@
|
||||
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
|
||||
- 묶음: B18c 낡은 이름·leaf 안내
|
||||
- 내용: `src/adapter/outbound/objectstorage/README.md` 「env 키」가 「전용 `APP_*` 키는 없다」고 하지만 `docs/registries/env-keys.yaml`에 `APP_OBJECTSTORAGE_ENABLED`가 있다. 고침: 그 키 하나를 적는다.
|
||||
|
||||
### RR9-04-46 · Low · capability-status가 objectstorage를 MinIO로 조립한다고 적는다
|
||||
|
||||
- 출처: 고치며 찾음(B20 조사, 2026-11-13)
|
||||
- 증거: E1(현재 커밋 코드·문서 정적 확인) · 이전부터
|
||||
- 묶음: B20 objectstorage 포트 계약
|
||||
- 내용: `docs/capability-status.md` Object storage 증거 칸이 「`app-bootstrap:integrationTest` assembles it against digest-pinned MinIO」라고 적는다. 실제 시험(`ObjectStorageCompositionIntegrationTest`)은 local-dev provider로 조립하고 bootstrap 통합 시험에 MinIO는 없다. 고침: 실제 조립과 MinIO provider 계약 lane을 나눠 적는다.
|
||||
|
||||
### RR9-04-47 · Low · 순수성 검사가 순수 모듈의 testFixturesCompileOnly를 보지 않는다
|
||||
|
||||
- 출처: 고치며 찾음(B20 구조 리뷰, 2026-11-13)
|
||||
- 증거: E2(desktop 실행: 기준 플러그인에서 `testFixturesCompileOnly`에 Spring을 둔 functional fixture가 순수성 검사를 통과) · 이전부터
|
||||
- 묶음: B20 objectstorage 포트 계약
|
||||
- 내용: `build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/ArchitecturePlugin.java`가 순수 모듈의 compile·runtime·test classpath만 풀었다. testFixtures를 쓰는 순수 leaf 다섯 곳에서 fixtures에 framework를 compileOnly로 두면 통과했다. 고침: testFixtures classpath 둘도 같은 금지 group으로 본다.
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
## 1. 결론
|
||||
|
||||
main `a7e38c10`(Gradle 루트 재배치, gRPC·메시징 플랫폼 분리, 분야 전문가 스킬, CI 재편, red team 수정이 들어간 뒤)을
|
||||
새 눈으로 전체 리뷰했다. 발견 152건: Critical 0, High 2, Medium 72, Low 78. 고치며 6건(Medium 2, Low 4)을 더 찾아 모두 158건이다. 이 밖에 CI workflow·`build.gradle`·`gates.md`처럼
|
||||
새 눈으로 전체 리뷰했다. 발견 152건: Critical 0, High 2, Medium 72, Low 78. 고치며 12건(Medium 5, Low 7)을 더 찾아 모두 164건이다. 이 밖에 CI workflow·`build.gradle`·`gates.md`처럼
|
||||
백엔드 CI 세션이 고치는 중인 파일의 발견 9건은 그 세션에 넘겼다(5절).
|
||||
|
||||
- High 둘은 아키텍처 규칙의 사각지대다(HARD-STOP 2). controller가 domain repository 포트를 들어도, inbound 밖 사용자
|
||||
@@ -138,6 +138,10 @@ main `a7e38c10`(Gradle 루트 재배치, gRPC·메시징 플랫폼 분리, 분
|
||||
| RR9-03-30 | Medium | API 계약·시험 | compose 병합 특성 시험이 어느 lane에서도 돌지 않았다 | B19 compose·Docker 운영 |
|
||||
| RR9-03-31 | Medium | API 계약·시험 | application-objectstorage에 포트 계약 시험이 없다(manual 10 기준 5) | B20 objectstorage 포트 계약 |
|
||||
| RR9-03-32 | Low | API 계약·시험 | 알림 provider callback의 본문 없는 응답이 Envelope 예외로 적혀 있지 않다 | B18c 낡은 이름·leaf 안내 |
|
||||
| RR9-03-33 | Medium | API 계약·시험 | 불변 Set capability로 만든 objectstorage 요청이 NullPointerException을 낸다 | B20 objectstorage 포트 계약 |
|
||||
| RR9-03-34 | Medium | API 계약·시험 | adapter 전용 예외가 objectstorage 포트 밖으로 나간다 | B21 objectstorage 포트 예외 |
|
||||
| RR9-03-35 | Low | API 계약·시험 | 실패 뒤 다시 한 managed 게시가 REPLAYED로 답한다 | B20 objectstorage 포트 계약 |
|
||||
| RR9-03-36 | Medium | API 계약·시험 | main 단계 lane의 벽시계 시험이 부하 아래에서 흔들린다 | B22 벽시계 시험 |
|
||||
| RR9-04-01 | Medium | 빌드·문서 | #12가 줄 더해 151/150, check-work-docs rc=1 → verify.sh docs·라운드 끝 실패. 같은 줄 "(W4… | B1 문서·지침 |
|
||||
| RR9-04-02 | Medium | 빌드·문서 | `cd ~/workspace/<작업>/src` 뒤 ./gradlew(#10 뒤 src에 gradlew 없음). desktop-gates… | B1 문서·지침 |
|
||||
| RR9-04-03 | Medium | 빌드·문서 | "Gradle 루트가 src/라 두 단계 위", `--include-build ../../messaging-library` →… | B1 문서·지침 |
|
||||
@@ -183,6 +187,8 @@ main `a7e38c10`(Gradle 루트 재배치, gRPC·메시징 플랫폼 분리, 분
|
||||
| RR9-04-43 | Low | 빌드·문서 | persistence-jpa release registry가 아무도 읽지 않는 PostgreSQL tag를 적는다 | B17 빌드 정리 |
|
||||
| RR9-04-44 | Low | 빌드·문서 | web 한도 표가 아무도 막지 않는 칸을 「늘 애플리케이션」이라 적는다 | B18c 낡은 이름·leaf 안내 |
|
||||
| RR9-04-45 | Low | 빌드·문서 | objectstorage README가 registry에 있는 env 키를 「없다」고 한다 | B18c 낡은 이름·leaf 안내 |
|
||||
| RR9-04-46 | Low | 빌드·문서 | capability-status가 objectstorage를 MinIO로 조립한다고 적는다 | B20 objectstorage 포트 계약 |
|
||||
| RR9-04-47 | Low | 빌드·문서 | 순수성 검사가 순수 모듈의 testFixturesCompileOnly를 보지 않는다 | B20 objectstorage 포트 계약 |
|
||||
| RR9-05-01 | High | 계층·도메인·SRP | controller가 domain `<Aggregate>Repository` 포트를 주입해도 안 걸림(HARD-STOP 2). 생성 명령이… | B14 아키텍처 규칙 |
|
||||
| RR9-05-02 | High | 계층·도메인·SRP | inbound 밖 사용자 전송(bootstrap·composition controller, JWT converter)이… | B14 아키텍처 규칙 |
|
||||
| RR9-05-03 | Medium | 계층·도메인·SRP | web 밖 JWT… | B14 아키텍처 규칙 |
|
||||
@@ -209,6 +215,10 @@ main `a7e38c10`(Gradle 루트 재배치, gRPC·메시징 플랫폼 분리, 분
|
||||
|
||||
원인 묶음마다 브랜치 하나·PR 하나다. 묶음의 발견 목록은 위 색인의 「묶음」 칸이다.
|
||||
|
||||
runner 대기를 풀려고 PR #17·#19~#27은 main `d3a90479` 위에 차례로 합친 트리 하나(PR #28)로 한 번 검사하고
|
||||
#28로 함께 병합했다(2026-11-13, main `3d31896a`, run 218 `pr / done` 초록). 아래 PR 번호는 그 묶음의 원래 PR이고,
|
||||
각 PR은 「#28로 병합됨」 댓글을 달고 닫았다.
|
||||
|
||||
| 묶음 | 브랜치 | 상태 |
|
||||
| --- | --- | --- |
|
||||
| B1 문서·지침 | `claude/r9-docs-work` | PR #16 |
|
||||
@@ -218,10 +228,12 @@ main `a7e38c10`(Gradle 루트 재배치, gRPC·메시징 플랫폼 분리, 분
|
||||
| B14 아키텍처 규칙 | `claude/r9-arch-rules` | PR #19 |
|
||||
| B18c 낡은 이름(RR9-04-38~41) | `claude/r9-stale-names` | PR #22 |
|
||||
| B19 compose·Docker 운영(RR9-01-21, RR9-03-30) | `claude/r9-compose-ops` | PR #24 |
|
||||
| 그룹 A 보안·관측·전송: B4, B5, B6a, B6b, B7, B11b | 그룹 세션 | 대기 |
|
||||
| 그룹 B 영속성·outbound·application: B8, B9 나머지, B10a, B10b, B15a, B15b, B16 일부 | 그룹 세션 | 대기 |
|
||||
| 그룹 A 보안·관측·전송: B4, B5, B6a, B6b, B7, B11b | `claude/r9-a-runbooks`·`claude/r9-a-authz`·`claude/r9-a-obs-logs` | PR #30(B7, 병합 `e6c3b159`), #31(B4·B11b, 병합 `3e908c02`), #32(B5·B6a·B6b) |
|
||||
| 그룹 B 영속성·outbound·application: B8, B9 나머지, B10a, B10b, B15a, B15b, B16 일부 | `claude/r9-b-claim-tx`와 그 위에 쌓는 둘 | PR #33(B8·B9 나머지·B16 일부). B10a·B10b, B15a·B15b는 #33 위에 쌓아 연다 |
|
||||
| 그룹 C 계약·시험·빌드·문서: B11a, B12, B13, B16, B17, B18a, B18b, B18c 나머지(RR9-04-35·36·42) | `claude/r9-c-contracts`·`claude/r9-c-tests-build`·`claude/r9-c-docs-body` | PR #25(B11a·B12·B13), #27(B16·B17·B18a), #26(B18b·B18c 나머지, #23·#24·#25 뒤) |
|
||||
| B20 objectstorage 포트 계약(RR9-03-31) | `claude/r9-objstore-contract` | 진행 중 |
|
||||
| B20 objectstorage 포트 계약(RR9-03-31·33·35, RR9-04-46·47) | `claude/r9-objstore-contract` | PR #35 |
|
||||
| B21 objectstorage 포트 예외(RR9-03-34) | (B20 뒤) | 대기 |
|
||||
| B22 벽시계 시험(RR9-03-36) | `claude/r9-wallclock-tests` | PR #34 |
|
||||
|
||||
그룹은 서로 파일이 겹치지 않게 나눴다. 묶음과 경로는 위 색인의 「묶음」 칸과 같다.
|
||||
|
||||
@@ -229,6 +241,8 @@ main `a7e38c10`(Gradle 루트 재배치, gRPC·메시징 플랫폼 분리, 분
|
||||
|
||||
- RR9-03-30(Medium): 고치는 중에 찾은 발견이다. 색인과 `03-contract-testing.md`에 더했다.
|
||||
- RR9-03-31(Medium)·RR9-03-32·RR9-04-43~45(Low): 그룹 C 묶음의 새 눈 리뷰가 찾은 기존 결함이다(2026-11-13). 색인과 `03-contract-testing.md`·`04-build-docs.md`에 더했다. 묶음 PR이 만든 회귀는 그 PR에서 고쳤고 여기 세지 않는다.
|
||||
- RR9-03-33·34(Medium)·RR9-03-35·RR9-04-46·47(Low): B20(objectstorage 포트 계약)의 첫 실행과 새 눈 리뷰가 찾은 기존 결함이다(2026-11-13). RR9-03-34는 포트 수준 예외 타입을 새로 두는 일이라 B21로 나눴다. 겹친 managed 게시에서 진 호출이 adapter의 충돌 예외를 받는 것(B20 3차 리뷰)도 같은 부류라 RR9-03-34에 넣었다.
|
||||
- RR9-03-36(Medium): main 단계 run이 gRPC·httpclient 시험에서 빨갛게 된 것을 따라가 찾았다(2026-11-13). desktop에서 부하를 걸어도 다시 나지 않았다. 그래서 main 단계 lane의 벽시계 시험 모두를 원인 단언과 gate로 바꿨다(B22).
|
||||
|
||||
## 5. 다른 세션에 넘긴 것
|
||||
|
||||
@@ -261,10 +275,12 @@ compose README를 고치는 중)에 9건을 넘겼다(2026-11-12). 그 세션 PR
|
||||
| ⑤ | RR9-05-12 notification 멱등 판정이 executor와 다르다 | 근거를 보고 executor로 옮기거나 결정으로 기록 — 묶음이 고른다 |
|
||||
| ⑥ | env 이름 `SECURITY_PUBLIC_PATHS`·`PRESENTATION_API_BASE_PATH`의 `APP_` 접두 | 지금 이름 그대로 registry에 등록(바꾸면 파생 서비스 배포 env가 소리 없이 무시됨). 이름 변경은 소유자 결정 |
|
||||
| ⑦ | RR9-03-32 provider callback의 본문 없는 응답: 소유자 결정 12 「Envelope가 아닌 실패는 Draft-12 offset 문서 하나」 | 동작 그대로(provider는 status만 읽고, 인증 전 경로라 거절 이유를 싣지 않음), HTTP 계약 §1에 예외로 적는다 |
|
||||
| ⑧ | RR9-03-31 objectstorage fake: TESTING_STRATEGY 9.2 「소비자 없는 fake 금지」(결정 2026-11-03) vs capability 기준 5(fake와 adapter가 같은 계약) | fake를 둔다. 소비자는 객체 저장소를 쓰는 서비스의 유스케이스 시험이다. TESTING_STRATEGY 9.4에 예외로 적는다 |
|
||||
| ⑨ | RR9-03-31 objectstorage 포트의 거절: 타입 있는 결과로 바꾸기 vs 지금 예외를 선언 | 지금 동작(`IllegalArgumentException`=요청 그대로, `IllegalStateException`=지금 상태)을 포트 Javadoc에 선언하고 유스케이스가 기능 오류로 감싼다. 타입 결과는 공개 API 변경이라 하지 않는다 |
|
||||
|
||||
## 7. 멈춤 기준 상태 (`docs/work/improve.md` 4.5절)
|
||||
|
||||
1. 마지막 확인 리뷰 발견 0: 아님. 이 라운드 158건을 고친 뒤 확인 리뷰(독립 리뷰어 둘)가 판정한다.
|
||||
1. 마지막 확인 리뷰 발견 0: 아님. 이 라운드 164건을 고친 뒤 확인 리뷰(독립 리뷰어 둘)가 판정한다.
|
||||
2. 열린 「Declined to judge」 0: 참. 판정을 미룬 항목은 없다. 못 본 경로는 2절에 적었다.
|
||||
3. 합친 트리의 라운드 끝 게이트: 아직. 묶음을 합친 뒤 돈다.
|
||||
4. README의 남은 항목 0: 아님. 4절의 대기 묶음과 6절의 결정이 남았다.
|
||||
|
||||
@@ -215,7 +215,7 @@ source set에서 태그 `jpa-contract`로 `jpaPlatformContractTest` lane이 돌
|
||||
| `IdempotencyStorePort` | `idempotency.testkit.IdempotencyStoreContract` | `InMemoryIdempotencyStore` | `RedisIdempotencyStoreContractTest`(command fake, `test`) · `LiveRedisIdempotencyStoreContractTest`(실 Redis, `redisTopologyTest` standalone·cluster) · `PostgreSqlIdempotencyStoreContractTest`(실 PostgreSQL, `jpaPlatformContractTest`) |
|
||||
| `SecretSourcePort` | `secret.testkit.SecretSourceContract` | `InMemorySecretSource` | `EnvironmentSecretSourceContractTest` — support (`test`) |
|
||||
| `OutboxAppendPort` | `outbox.testkit.OutboxAppendContract` | `InMemoryOutboxStore(DirectTransactionPort)` | `PostgreSqlOutboxAppendTransactionalIntegrationTest` (`postgresqlOutboxAppendTransactionalIntegrationTest`) |
|
||||
| `LiveEventReplayPort` | `realtime.testkit.LiveEventReplayContract` | `InMemoryLiveEventReplay` | `JpaLiveEventReplayContractTest` (`jpaPlatformContractTest`) |
|
||||
| `LiveEventReplayQueryPort` | `realtime.testkit.LiveEventReplayQueryContract` | `InMemoryLiveEventReplay` | `JpaLiveEventReplayContractTest` (`jpaPlatformContractTest`) |
|
||||
| `AuthorizationPort` | `security.testkit.AuthorizationContract` | `InMemoryAuthorization` | `AuthorizationAdapterContractTest` — web (`test`) |
|
||||
| `CorrelationIdPort` | `observability.testkit.CorrelationIdContract` | `FixedCorrelationId` | `MdcCorrelationIdPortAdapterContractTest` — web (`test`) |
|
||||
| `CacheRegionPort` | `cache.testkit.CacheRegionContract` | `InMemoryCacheRegion` | `RedisCacheRegionContractTest`(`test`) · `LiveRedisCacheRegionContractTest`(`redisTopologyTest`) |
|
||||
@@ -299,9 +299,9 @@ PostgreSQL 쪽에만 있던 테스트를 계약으로 옮긴 것이다. `Reconci
|
||||
`PostgreSqlAdminOperationStoreContractTest`에만 남겼다. 처음 적용할 때 fake와 실제가 다르게 답한 경우는
|
||||
없었다. 유스케이스 테스트의 대역은 `PlatformFakes.RequestStore`·deduplication 람다·
|
||||
`AdminOperationExecutorTest.FakeStore`를 이 fake들로 바꿨다. 아직 테스트 안에 남은 대역: admin
|
||||
`NotificationAdminApplicationServiceTest.RecordingOperations`·`UnusedSuppressionStore`, reconciliation job
|
||||
`ReconciliationJobWorkerTest`(notification adapter)의 stub — 호출 횟수를 세거나 "부르지 않는다"를 확인하는
|
||||
용도라 fake로 바꾸면 단언을 다시 써야 한다.
|
||||
`NotificationAdminUseCasesTest.RecordingOperations`, reconciliation job
|
||||
`ReconcileOutstandingAttemptsUseCaseTest`(application-notification)의 stub — 호출 횟수를 세거나 "부르지 않는다"를
|
||||
확인하는 용도라 fake로 바꾸면 단언을 다시 써야 한다.
|
||||
|
||||
notification 계약 여덟 개(recipient lease·recipient delivery·attempt·resolver·projection·ledger·side
|
||||
effect·contact point, 2026-11-03 r3-J)로 9.2의 "다음 단계"가 끝났다. fake는 JPA 구현의 묶음을 따른다:
|
||||
|
||||
@@ -0,0 +1,41 @@
|
||||
# 업그레이드 안내 — 2026-11 application 구조와 작은 정리
|
||||
|
||||
- 범위: 시스템이 부르는 쓰기를 `@SystemInvoked` 유스케이스로 나누고, 알림 worker와 fileserver 정리 서비스 조립을
|
||||
composition으로 옮기고, 알림 운영자 연산을 유스케이스 넷으로 나누고, replay 읽기와 durable operation 제출을 유스케이스로
|
||||
거치게 한 변경. 쓰지 않던 공개 타입 일곱을 지웠다. 공개 타입과 생성자가 바뀐 곳이 있다. 아래 표가 그 목록이다.
|
||||
- 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 application 구조(B15a)와 작은 것(B15b) 발견
|
||||
|
||||
## 1. 누가 읽나
|
||||
|
||||
이 템플릿을 `upstream` remote로 두고 merge해 받는 파생 서비스가 읽는다. 특히 알림 운영자 연산이나 알림 worker bean을
|
||||
직접 쓴 서비스, `MessagingReplayBridge`로 stream을 다시 보내는 서비스, durable operation을 직접 제출하는 서비스,
|
||||
사용자 전송(web·GraphQL·gRPC·WebSocket) 클래스에서 저장 포트를 직접 쥐는 서비스다.
|
||||
|
||||
## 2. 할 일
|
||||
|
||||
| # | 할 일 | 안 하면 | 해당 서비스 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | `NotificationAdminService`·`NotificationAdminApplicationService`가 없어졌다. 운영자 연산은 `platform.admin`의 유스케이스 클래스 `RedriveDeliveryUseCase`·`ReconcileDeliveriesUseCase`·`ChangeSuppressionUseCase`·`ChangeProviderStateUseCase`를 주입받아 `handle(new …Command(request, actor))`로 부른다(command도 `platform.admin`). 운영자 요청 record의 이름이 바뀌었다: `RedriveCommand`→`RedriveRequest`, `ReconcileCommand`→`ReconcileRequest`, `SuppressCommand`→`SuppressionRequest`, `SetProviderStateCommand`→`ProviderStateRequest`. `adminAuthorizationGuard`·`duplicateRiskGuard` bean은 없어졌다(유스케이스 설정이 `new`로 만든다). 모듈 기본값이 role `notification-admin`에 permission 넷(`notification-admin:redrive`·`notification-admin:reconcile`·`notification-admin:suppress`·`notification-admin:provider-control`)을 준다. 운영자 role 이름이 다르면 `app.authz.role-permissions`에 직접 대응시킨다 | 컴파일이 실패한다. 두 guard bean을 주입받던 정의는 기동이 실패한다(`NoSuchBeanDefinitionException`). 운영자가 `notification-admin` role도 대응시킨 role도 없으면 운영자 호출이 403이다 | 알림 운영자 연산을 쓴 서비스 |
|
||||
| 2 | 알림 worker가 `adapter:outbound:notification`에서 `composition:notification-platform`으로 옮겼다. `NotificationBackgroundWorkers`는 `dev.caskeleton.composition.notification`의 공개 타입이고, 생성자는 서비스 대신 유스케이스를 받는다(lease 회복·replay·맞추기). 발송 scheduler(`NotificationSchedulerWorker`)는 그 패키지 안의 타입이 됐다. claim·발송·backlog 측정 유스케이스로 돌고, 바꿔 끼우는 bean이 아니다. `ReconciliationJobWorker`·`ProviderEventReplayWorker`는 application의 `@SystemInvoked` 유스케이스(`ReconcileOutstandingAttemptsUseCase(jobs, reconciler, tx, clock, deliveryLease, batchSize, maxAdditionalAttempts)`·`ReplayProviderEventsUseCase(projection, batchSize)`)가 됐다. `reconciliationJobWorker`·`notificationProviderEventReplayWorker` bean을 덮어쓰던 서비스는 `notificationBackgroundWorkers` bean을 덮어쓴다 | 옛 import와 생성자가 컴파일되지 않는다. 옛 bean 이름으로 덮어쓴 정의는 더는 쓰이지 않는다 | 알림 worker를 직접 조립하거나 덮어쓴 서비스 |
|
||||
| 3 | `MessagingReplayBridge`는 생성자에서 조회 유스케이스 둘을 받는다: `new MessagingReplayBridge<>(window, replay, decoder)`. 두 유스케이스는 서비스의 조립 설정(자기 `composition` 설정이나 bootstrap 설정, web 설정이 아니다)에서 bean으로 만든다: `@Bean GetReplayWindowUseCase(LiveEventReplayQueryPort port, TransactionPort tx)`, `@Bean ReplayLiveEventsUseCase(...)`. 템플릿은 bridge를 조립하지 않으므로 이 bean도 만들지 않는다. `LiveEventReplayPort`는 `LiveEventReplayQueryPort`로, testFixtures의 `LiveEventReplayContract`는 `LiveEventReplayQueryContract`로 이름이 바뀌었다 | 컴파일이 실패한다. web 설정에서 port를 쥐고 유스케이스를 만들면 5행 규칙에 걸린다 | stream replay를 쓰는 서비스 |
|
||||
| 4 | `OperationCommand`에서 operation id 인자를 지우고, tenant를 `Optional<TenantId>`(`application.tenant.TenantId`)로 넘긴다. `GetDurableOperationQuery`·`CancelDurableOperationCommand`의 tenant도 같다. `SubmitDurableOperationUseCase`는 생성자에 `DurableOperationIdFactory`를 받아 id를 직접 만든다. `DurableOperationController`는 id factory를 받지 않는다 | 컴파일이 실패한다 | durable operation을 직접 제출·조회하거나 그 use case를 조립한 서비스 |
|
||||
| 5 | 사용자 전송 패키지(시스템이 부르는 `..adapter.inbound.messaging..`·`..adapter.inbound.scheduler..`를 뺀 모든 `..adapter.inbound..`)의 클래스가 `*Repository`·`*StorePort`·`*QueryPort`·`*IdFactory`·`*IdGeneratorPort`·`*IdentifierPort`를 직접 쥐면 새 아키텍처 규칙 `USER_TRANSPORTS_DO_NOT_HOLD_PERSISTENCE_OR_ID_PORTS`가 빌드를 실패시킨다. 또 inbound 클래스가 application의 `*Service`·`*Orchestrator`·`*Coordinator`를 interface로 쥐어도 `INBOUND_ADAPTERS_DEPEND_ON_PORTS_NOT_APPLICATION_SERVICES`가 실패시킨다(전에는 구체 클래스만 봤다). 읽기·쓰기는 유스케이스를 거친다 | `architectureTest`가 실패한다 | 사용자 전송에서 포트나 서비스를 직접 쓴 서비스 |
|
||||
| 6 | `DefaultNotificationRetryPolicy`를 직접 만들던 코드는 `new DefaultNotificationRetryPolicy(timing, jitter)`로 바꾼다. `timing`은 새 값 `RetryTiming(backoff, reconcileDelay)`이고 배포 설정의 값은 `NotificationPlatformSettings.retry().timing()`이다(기본값은 `RetryTiming.DEFAULT`). `RetryBackoff`·`RetryBudget`·`RetryContext`·`RetryDecision.RetryAfter`·`RouteCandidate`·`RoutingContext`·`RoutingDecision`·`EligibilityResult`의 생성자와 `RetryBackoff.delay`(attempt 번호 1 미만)는 잘못된 값에 `IllegalStateException`을 던진다(전에는 `IllegalArgumentException`). 새 값 `RetryTiming`도 같다 | 컴파일이 실패한다. IAE를 잡던 코드는 그 예외를 놓친다 | 알림 retry policy를 직접 만들거나, route planner·plan codec·eligibility policy를 직접 구현하거나, `RoutingDecision`을 직접 만드는 서비스 |
|
||||
| 7 | 쓰는 곳이 없던 공개 타입 일곱을 지웠다: `application.transaction.ReadConsistency`, `FileserverSpans`, 알림의 `ProviderEventId`·`NotificationExpiredException`·`BatchNotificationProviderAdapter`·`CollapseCapability`·`ProviderCollapseMapping` | 그 타입을 쓴 코드는 컴파일이 실패한다. 템플릿 안에는 쓰는 곳이 없었다 | 그 타입을 쓴 서비스 |
|
||||
|
||||
## 3. 바뀐 동작 (따라 할 일 없음)
|
||||
|
||||
- 알림 재시도 시각이 설정이다: `app.notification.platform.retry.backoff-base`(1s)·`backoff-max`(5m)·`reconcile-delay`(1m).
|
||||
기본값은 전의 상수와 같고 코드(`RetryTiming.DEFAULT`)에만 있다. module-defaults에는 주석 예시만 있다. 값이 틀리면
|
||||
(`backoff-base` 0 이하, `backoff-max`가 base보다 짧음, `reconcile-delay` 음수) 기동이 실패한다.
|
||||
- fileserver cleanup worker와 알림 worker는 `@SystemInvoked` 유스케이스를 거쳐 쓴다(manual 07 「시스템이 부르는 쓰기」).
|
||||
알림 worker의 lease claim과 reconciliation job 기록은 이제 쓰기 트랜잭션 안에서, scheduler의 backlog 측정과 replay의
|
||||
ledger 읽기는 읽기 트랜잭션 안에서 돈다. provider에는 여전히 트랜잭션 없이 묻는다.
|
||||
- 운영자 redrive는 대상 attempt를 claim·쓰기와 같은 쓰기 트랜잭션에서 읽는다(dry run은 읽기 트랜잭션). 운영자
|
||||
reconcile의 tenant 확인은 읽기 트랜잭션에서 한다. 전에는 트랜잭션 밖에서 읽었다.
|
||||
- fileserver 정리·맞추기 서비스(`CleanupService`·`FileReconciliationService`)는 `composition:fileserver-platform`이 조립한다.
|
||||
bean 이름과 타입은 그대로다.
|
||||
- fileserver 관리 HTTP의 기본값(orphan 정리 dry run과 1 GiB·`ORPHAN_APPLY`, cleanup 100개·1 GiB, 목록 100개)은 application
|
||||
command의 `requested(...)`가 채운다. 응답은 같다.
|
||||
- `GetDurableOperationUseCase`·`PublishPendingOutboxEventsUseCase`가 final이 아니다.
|
||||
- 알림 받기의 `idempotencyKey`가 `IdempotencyExecutor`와 다른 이유는 manual 05 「executor를 쓰지 않는 중복 판정 둘」에 있다.
|
||||
@@ -0,0 +1,49 @@
|
||||
# 업그레이드 안내 — 2026-11 claim·fence·트랜잭션 시한·정리
|
||||
|
||||
- 범위: durable operation·알림 수신자·fileserver cleanup·멱등성 기록·live event·분산 락·stateless runner의 lease,
|
||||
fence, 조건부 쓰기, 정리, 시간 상한을 고친 변경. 포트 시그니처와 기동 조건이 바뀐 곳이 있다. 아래 표가 그 목록이다.
|
||||
- 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 claim·fence(B8)와 트랜잭션 시한·정리(B9) 발견
|
||||
|
||||
## 1. 누가 읽나
|
||||
|
||||
이 템플릿을 `upstream` remote로 두고 merge해 받는 파생 서비스가 읽는다. 특히 durable operation worker를 직접 쓴 서비스,
|
||||
알림 recipient store를 직접 구현한 서비스, `app.lock.wait-time`이나 알림 provider timeout을 설정한 서비스, experimental
|
||||
tenant pool 예산을 쓰는 서비스다.
|
||||
|
||||
## 2. 할 일
|
||||
|
||||
| # | 할 일 | 안 하면 | 해당 서비스 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | durable operation worker는 `claimNext`가 돌려주는 `DurableOperationClaim`을 들고 있다가 `heartbeat(claim, …)`·`reportProgress(claim, …)`·`succeed(claim, …)`·`fail(claim, …)`에 넘긴다. 예전에는 `(operationId, workerId, …)`였다 | 컴파일이 실패한다 | durable operation worker를 쓴 서비스 |
|
||||
| 2 | `DurableOperationStorePort`를 직접 구현했으면 claim마다 오르는 fence를 저장하고, 네 쓰기가 owner와 fence를 함께 확인하게 한다. `DurableOperationStoreContract`의 새 사례(같은 worker id가 다시 claim한 뒤 앞 실행의 쓰기는 거절)로 확인한다 | 재시작한 worker나 한 프로세스의 두 실행이 같은 id를 쓰면 앞 실행의 결과가 넘겨받은 실행 위에 기록된다 | 자기 durable operation store를 둔 서비스 |
|
||||
| 3 | persistence-jpa의 `V23__durable_operation_lease_fence.sql`(`durable_operation.lease_fence BIGINT NOT NULL DEFAULT 0`)이 기본 stream에 더해진다. 같은 번호의 서비스 마이그레이션이 있으면 번호를 옮긴다. `durable_operation`을 건드린 트랜잭션이 열려 있으면 5초 뒤 실패하고 V22에 남는다(다시 배포) | Flyway가 번호 충돌로 기동하지 않는다 | persistence-jpa를 쓰는 모든 서비스 |
|
||||
| 4 | 알림 stream에 `V14__notification_provider_event_open_index.sql`(부분 인덱스 `ix_notification_provider_event_open`)이 더해진다. `notification_provider_event`가 이미 큰 운영 DB는 배포 전에 같은 인덱스를 `CREATE INDEX CONCURRENTLY IF NOT EXISTS ix_notification_provider_event_open ON notification_provider_event (received_at) WHERE projection_status IN ('PENDING', 'FAILED') OR attempt_id IS NULL;`로 먼저 만든다. 미리 만든 인덱스가 실패해 남았으면(`SELECT indisvalid FROM pg_index WHERE indexrelid = 'ix_notification_provider_event_open'::regclass`가 false) `DROP INDEX CONCURRENTLY ix_notification_provider_event_open` 뒤 다시 만든다. `IF NOT EXISTS`는 쓸 수 없는 인덱스도 있는 것으로 보고 넘어간다 | 마이그레이션이 인덱스를 만드는 동안 provider callback 저장이 기다린다(provider가 callback을 다시 보낸다) | 알림 capability를 켠 서비스 |
|
||||
| 5 | `RecipientLeaseStorePort.expiredDispatching`이 `List<RecipientLease>`(버려질 때의 owner·fence·만료 시각)를 돌려주고, `RecipientDeliveryStorePort`에 `requeueAbandoned(lease, nextDispatchAt)`가 생겼다. 직접 구현했으면 상태가 `DISPATCHING`이고 owner·fence가 같고 lease가 늘지 않았을 때만 `READY_TO_DISPATCH`로 바꾼다(`RecipientDeliveryStoreContract` 새 사례). owner가 없거나 fence가 0인 `DISPATCHING` 행(notification V4 전에 남은 행)은 복구가 더는 고르지 않는다. 그런 행은 `SELECT id FROM notification_recipient_delivery WHERE delivery_state = 'DISPATCHING' AND (lease_owner IS NULL OR lease_fence = 0)`로 찾는다. 배포 전에 `UPDATE notification_recipient_delivery SET lease_owner = COALESCE(lease_owner, 'pre-v4'), lease_fence = lease_fence + 1, lease_until = now() - interval '1 day', version = version + 1, updated_at = now() WHERE delivery_state = 'DISPATCHING' AND (lease_owner IS NULL OR lease_fence = 0)`로 owner를 채우고 fence를 올려 복구 패스에 넘긴다. 복구는 attempt를 보고 정한다: attempt가 없으면 다시 보낼 차례로 돌리고, 끝나지 않은 attempt가 있으면 맞추기로 넘긴다(그 뒤는 `docs/notification/configuration-reference.md` 「발송」의 lease 문단). 손으로 `READY_TO_DISPATCH`로 바꾸지 않는다. 발송 중에 멈춘 행이면 같은 알림이 한 번 더 나간다. owner가 없는 행은 stuck lease 지표에도 잡히지 않는다 | 컴파일이 실패한다. 조건 없이 바꾸면 끝났거나 다시 claim된 delivery가 다시 발송된다 | 알림 store를 직접 구현한 서비스 |
|
||||
| 6 | 알림 provider profile의 `timeout`이 `app.notification.platform.dispatch.lease-duration`보다 짧은지 확인한다. 짧은 것은 필요조건일 뿐이다: lease는 claim 때 시작해서 attempt 기록·렌더링·provider 허가 대기도 lease를 쓴다. lease는 timeout보다 넉넉히 길게 둔다. 이 timeout은 SES에서는 API 호출 하나의 상한이다. SMTP의 추가 조건은 `docs/upgrade/2026-11-round9-outbound.md` 9행이다 | 짧지 않으면 기동이 실패한다(`notification provider profile '…': timeout (…) must be shorter than …lease-duration`). 전에는 provider 호출 하나가 lease보다 길어도 기동했다. 그때 생기는 일은 `docs/notification/configuration-reference.md` 「발송」의 lease 문단이다 | 알림 capability를 켠 서비스 |
|
||||
| 7 | `app.lock.wait-time`을 설정에서 지운다. 기다릴 시간은 `tryAcquire(key, waitTime, leaseTtl)`의 인자다 | `app.lock` 아래 모르는 키라 기동이 실패한다. 전에도 읽는 곳이 없었다 | `app.lock.wait-time`을 설정한 서비스 |
|
||||
| 8 | `JpaLiveEventReplay.sweepExpired()`를 부르던 코드를 지운다. replay를 켜면 `LiveEventReaper`가 `app.realtime.replay.reaper-interval`(기본 `PT10M`)마다 `retained_until`이 지난 행을 1000행씩 지운다. `app.realtime.replay.*`는 이제 `LiveEventReplaySettings`가 엄격하게 묶는다: 그 아래 모르는 키, 0 이하의 `retention`·`reaper-interval`은 기동을 실패시킨다 | 컴파일이 실패한다. 잘못 쓴 키는 기동이 실패한다. 전에는 지우는 곳이 없어 `live_event_log`가 끝없이 자랐다 | `app.realtime.replay.enabled=true`인 서비스 |
|
||||
| 9 | `IdempotencyReaper`를 직접 만들던 코드는 `new IdempotencyReaper(repository)`로 바꾼다(`Clock` 인자 삭제). 만료 비교는 DB 시계(`now()`)이고 1000행씩 지운다 | 컴파일이 실패한다 | reaper를 직접 조립한 서비스 |
|
||||
| 10 | `HibernateStatelessSessionRunner`의 트랜잭션은 이제 30초 상한이 있다(`DEFAULT_TIMEOUT`). 더 긴 일이면 셋째 인자로 상한을 넘기거나 일을 나눈다 | 30초를 넘는 문장이 취소되고 일 전체가 롤백된다. 전에는 상한이 없었다 | stateless runner를 쓰는 서비스 |
|
||||
| 11 | experimental `TenantPoolBudget.requireCapacity`·`hasCapacity`가 새 pool의 연결 수를 셋째 인자로 받는다. pool 수만 볼 때는 `requirePoolSlot(openPools)`를 쓴다. `TenantDataSourceRegistry`의 둘째 인자는 이제 열린 pool의 크기를 재는 함수가 아니라 tenant의 계획된 pool 크기(`ToIntFunction<TenantId>`)다. 예산은 pool을 열기 전에 그 크기로 본다 | 컴파일이 실패한다. 전에는 새 pool 크기를 모른 채 열어 연결 합계가 상한을 넘었다 | experimental tenant pool을 쓰는 서비스 |
|
||||
| 12 | fileserver cleanup 묶음의 `max-items`를 정할 때, 한 묶음이 claim lease(10분)의 첫 8분 안에 시작할 수 있는 만큼만 처리된다는 것을 안다. 나머지는 시도하지 않은 채 queue에 돌아가 다음 묶음이 다시 claim한다. 시도 횟수는 그대로다(바이트 예산이 바닥나 돌려준 항목도 이제 같다. 전에는 시도 한 번으로 세어 8번째에 보류됐다). 직접 구현한 `CleanupQueuePort`는 새 연산 `release`를 구현한다(`CleanupQueuePortContract` 새 사례) | 느린 저장소에서 큰 `max-items`는 그 사유로 도는 항목이 늘어난다. 전에는 lease가 끝난 뒤에도 남은 항목을 처리해 다른 worker와 겹쳤다 | fileserver capability를 켠 서비스 |
|
||||
|
||||
## 3. 바뀐 동작 (따라 할 일 없음)
|
||||
|
||||
- reaper 셋(outbox·멱등성·live event)의 트랜잭션은 `SpringTransaction.DEFAULT_TIMEOUT_SECONDS`(30초)로 묶인다.
|
||||
`app.persistence-jpa.transaction.*`를 바꿔도 reaper 시한은 그대로다. 한 트랜잭션이 1000행 한 묶음만 지운다.
|
||||
- 저장소가 행에서 만드는 `DurableOperationClaim`·`OperationLease`·`RecipientLease`·`OutboxLease`·`ClaimedOutboxEvent`·
|
||||
`ReconciliationJob`·`AdminOperationClaim`과 stateless runner의 timeout이 값을 거절할 때 `IllegalStateException`을 던진다
|
||||
(전에는 `IllegalArgumentException`). 요청에서 오는 값이 아니라 서버 결함이다. 이 IAE를 잡던 코드는 ISE를 잡는다.
|
||||
- 알림 lease 회복은 버려질 때의 lease 그대로일 때만 delivery를 다시 넣는다. 다른 인스턴스가 이미 다시 넣었거나 holder가
|
||||
끝냈으면 아무것도 쓰지 않고 처리 수에 세지 않는다.
|
||||
- 알림 만료 sweep(`EXPIRE_OVERDUE`)은 다른 트랜잭션이 쥔 행을 건너뛰고, 바깥 `UPDATE`에서도 상태·만료를 다시 본다.
|
||||
inbox 전체 읽음(`markAllRead`)도 바깥 `UPDATE`에서 상태를 다시 본다. 기다리는 사이 claim된 delivery나 보관된 inbox 항목을
|
||||
바꾸지 않는다.
|
||||
- 멱등성 reaper는 다른 트랜잭션이 쥔 기록을 건너뛰고, 바깥 `DELETE`에서도 만료를 다시 본다. 같은 키 요청이 만료된 기록을
|
||||
되살리는 동안 돈 reap이 그 claim을 지우지 않는다.
|
||||
- fileserver recovery 대기열 enqueue는 `INSERT … ON CONFLICT` 한 문장이다. 같은 파일을 동시에 넣어도 25P02로 실패하지 않는다.
|
||||
- 알림 scheduler는 poll마다 backlog 한 문장만 읽는다(전에는 넷). health snapshot의 projection 지연은 열린 provider event만
|
||||
읽는다.
|
||||
- 알림 backlog(`backlogDepth`, scheduler의 queue-depth gauge, health 임계값)는 claim이 지금 가져갈 delivery만 센다. claim과
|
||||
같은 SQL 조각이다. 전에는 창이 닫힌(`expires_at`이 지난) delivery도 셌고, lease가 지금 막 끝나는 행(`lease_until = now`)도
|
||||
셌다. 만료가 쌓인 플랫폼은 배포 직후 backlog 수치가 내려간다. 보낼 일이 줄어든 것이 아니라 보낼 수 없는 행을 빼고 센 것이다.
|
||||
@@ -1,7 +1,8 @@
|
||||
# 업그레이드 안내 — 2026-11 관측 registry·로그 내용·로컬 비밀 기본값
|
||||
|
||||
- 범위: 2026-11-12 전체 리뷰의 관측 registry 묶음, 로그 내용 묶음, 비밀·IP 문서 묶음을 고친 변경. 지표·MDC·헤더 registry를 코드에
|
||||
맞췄고, 로그 줄이 원본 경로·SQL·요청 값을 덜 싣게 했고, 로컬 비밀 기본값을 `__LOCAL_DEV_` 규칙에 맞췄다.
|
||||
맞췄고, 로그 줄이 원본 경로·SQL·요청 값을 덜 싣게 했고, 로컬 비밀 기본값을 `__LOCAL_DEV_` 규칙에 맞췄다. 2026-11-18에
|
||||
registry가 가리키는 경로를 PR에서 보는 문서 검사를 더했다(14번).
|
||||
- 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 RR9-02-05·07·08·09·10·12·13·15·21·22·26·27,
|
||||
RR9-03-05
|
||||
|
||||
@@ -27,6 +28,7 @@ compose로 개발하는 사람이다.
|
||||
| 11 | 단일 인스턴스(in-process) lock도 `lock.acquisition`을 센다 | 단일 인스턴스 배포의 lock 경보 기준선을 다시 잡는다 | 새로 생긴 값으로 경보가 울릴 수 있다 | persistence-jpa를 켠 서비스 |
|
||||
| 12 | `docs/registries/mdc-keys.yaml`은 코드가 MDC에 넣는 다섯 key(`request_id`, `trace_id`, `span_id`, `correlation_id`, `user_principal`)만 적는다. `headers.yaml`에서 아무도 쓰지 않던 `Deprecation`·`Sunset`을 지우고 쓰는 헤더 행을 더했다(`tracestate`는 W3C 전파가 쓰므로 `framework:` 행으로 둔다). 지표·헤더 행마다 `source`가 있다 | 자기 MDC key·헤더·지표를 더한 서비스는 `MdcKeys`·행을 같이 더하고 `source`를 적는다 | 새 정합 시험이 실패한다 | registry에 행을 더한 서비스 |
|
||||
| 13 | testFixtures `CardinalityBounds`: `STATUS_CODE`가 7에서 40(숫자 HTTP status)으로, `RESILIENCE4J_OUTCOME`(5)이 `OUTCOME`(6)으로 바뀌었고 `uri` key가 더해졌다. `MetricNaming.ALLOWED_UNITS`는 이름 접미사가 아니라 `unit` 칸의 값이다 | 그 상수를 쓰던 시험을 새 이름·값으로 고친다 | 시험 컴파일이 실패한다 | 그 fixture를 쓰는 서비스 |
|
||||
| 14 | `scripts/check-docs.py`의 `reference` 검사가 `docs/registries/*.yaml`의 값과 주석에 적은 repo 경로(`src/`·`docs/`·`scripts/` 등으로 시작하는 것)도 본다. 행의 `source`·`registered_by`가 옮기거나 지운 파일을 가리키면 PR 단계에서 걸린다(전에는 main 단계의 대조 시험만 `source`·`registered_by`를 봤고 주석은 아무도 보지 않았다) | `python3 scripts/check-docs.py --only reference`로 자기 registry 행과 주석의 경로가 지금 트리에 있는지 본다. 코드를 옮기는 변경에서 그 행도 고친다 | PR 단계 `documentCheck`가 「없는 경로다」로 실패한다 | registry에 행이나 주석을 더한 서비스 |
|
||||
|
||||
## 3. 바뀌지 않은 것
|
||||
|
||||
|
||||
@@ -0,0 +1,41 @@
|
||||
# 업그레이드 안내 — 2026-11 outbound 발행·발송·캐시·S3·MongoDB·HTTP client
|
||||
|
||||
- 범위: outbox 발행 대기, SMTP 발송 pool, Redis 캐시 시간·크기 상한, S3 조건부 쓰기, MongoDB 집계 예산·tenant
|
||||
client·migration lease, HTTP client 압축·proxy를 고친 변경. 기동 조건과 공개 타입이 바뀐 곳이 있다. 아래 표가 그
|
||||
목록이다.
|
||||
- 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 발행·발송·캐시(B10a)와 S3·Mongo·httpclient
|
||||
(B10b) 발견
|
||||
|
||||
## 1. 누가 읽나
|
||||
|
||||
이 템플릿을 `upstream` remote로 두고 merge해 받는 파생 서비스가 읽는다. 특히 SMTP 알림, Redis 캐시, MongoDB
|
||||
집계·tenant별 database, HTTP client의 압축이나 proxy를 쓰는 서비스다.
|
||||
|
||||
## 2. 할 일
|
||||
|
||||
| # | 할 일 | 안 하면 | 해당 서비스 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | SMTP provider profile들의 `max-concurrency` 합이 발송 pool이 담는 수(`app.notification.platform.smtp.dispatch-concurrency`개 thread와 그 네 배의 대기열) 이하인지 확인한다. 모든 SMTP profile이 pool 하나를 같이 쓴다. 기본값(profile 하나, 4와 4)은 맞는다 | 넘으면 넘게 만든 profile의 조립이 기동 때 실패한다. 전에는 넘친 발송이 대기열에서 거절되어 결과 불명으로 남았다 | SMTP 알림을 켠 서비스 |
|
||||
| 2 | Redis 캐시의 `command-timeout`이 이제 한 캐시 연산 전체(연결 대기와 응답 전부)의 상한이다. 연결 대기가 길던 배포는 값을 다시 본다 | 상한 안에 못 끝난 연산이 캐시 없음(`DEGRADED_UNAVAILABLE`·`Unavailable`)으로 끝나는 일이 늘 수 있다. 전에는 lane 대기 2초가 더해졌다 | Redis 캐시를 켠 서비스 |
|
||||
| 3 | encode한 값이 1 MiB(`RedisCacheRegionAdapter.DEFAULT_MAXIMUM_VALUE_BYTES`)를 넘는 캐시는 그 값을 기록하지 않는다(`NOT_RECORDED_PROVIDER_POLICY`). 더 큰 값이 필요하면 `app.capabilities.cache.maximum-value-bytes`(`APP_CACHE_REDIS_MAXIMUM_VALUE_BYTES`, 1..16777216)로 상한을 올린다. 2026-08-10에 폐기했던 그 env 키가 다시 묶였다 | 그 값은 매번 source에서 읽힌다 | 큰 값을 캐시하던 서비스 |
|
||||
| 4 | MongoDB `PolicyAwareMongoAggregationExecutor`는 등록 예산의 `maxResultBytes`를 집행하고, pipeline 끝에 `$limit(maxResults + 1)`을 붙인다. 결과가 큰 집계의 예산을 다시 본다. 집계 결과는 template의 converter로만 바뀌어 `AfterLoadEvent`·`AfterConvertEvent`와 entity callback이 돌지 않는다. 그것에 기대던 listener는 돌려받은 타입에서 직접 한다 | 바이트 예산을 넘는 집계가 `MongoOperationRejectedException`(`aggregation.result`)으로 실패한다. 전에는 결과를 전부 메모리에 올렸다 | MongoDB 집계를 쓰는 서비스 |
|
||||
| 5 | experimental `MongoTenantClientRegistry.acquire`가 `Lease`(interface)를 돌려준다. client를 다 쓴 뒤 `lease.close()`(또는 try-with-resources)를 부른다. 쓰는 중인 tenant의 `release`는 거부된다. idle 시간은 마지막 lease를 닫은 때부터 잰다. 열린 lease 수는 `openLeases()`다. 시각을 인자로 받던 `acquire(tenant, Instant)`는 없어졌다. 시계는 생성자의 `Clock` 하나다 | 반환값을 버리는 호출은 컴파일되지만, 닫지 않은 lease의 client는 쓰는 중으로 남아 내보내지지 않고 cap 한 칸을 계속 차지한다. `acquire(tenant, Instant)`를 부른 코드는 컴파일이 실패한다 | tenant별 database를 쓰는 서비스 |
|
||||
| 6 | MongoDB migration lease를 잃은 뒤의 `refresh`는 `MongoOperationRejectedException`(`migration.lock`)을 던진다. `IllegalStateException`을 잡던 코드를 바꾼다. collection을 직접 넘겨 `MongoCollectionMigrationLedger`를 만들던 코드는 셋째 인자로 lock collection(`MongoCollectionMigrationLock.DEFAULT_COLLECTION`)을 넘긴다. 옛 runner의 `recordApplied`는 새 runner가 lease를 잡은 뒤면(checkpoint를 쓰기 전이어도) 거부된다 | 그 예외를 잡지 못한다. 두 인자 생성자는 컴파일이 실패한다 | MongoDB migration runner를 직접 쓰는 서비스 |
|
||||
| 7 | HTTP client profile의 `proxy.type: SOCKS`를 지우거나 HTTP proxy로 바꾼다. `ProxyType`에는 이제 `HTTP`만 있다 | 설정 바인딩이 실패해 기동하지 않는다. 전에는 SOCKS port에 HTTP proxy로 붙어 첫 요청에서 실패했다 | SOCKS proxy를 설정한 서비스 |
|
||||
| 8 | `request.compression: true`인 HTTP client는 transport와 상관없이 `Accept-Encoding: gzip, deflate`를 보내고, 버퍼 본문과 스트리밍 다운로드 모두 이 플랫폼이 푼다(JDK transport는 전에 이 설정을 읽지 않았다). 압축을 켰든 껐든, 그 밖의 `Content-Encoding`(`br` 등)이나 겹친 coding으로 온 응답은 `HttpTargetRejectedException`(`TARGET_REJECTED`, 증거 `RESPONSE_RECEIVED`)으로 거부된다. 본문이 빈 gzip 응답(HEAD·204·304)은 빈 본문이다 | — 동작 변경. `response.max-wire-bytes`가 이제 압축된 크기로 센다. 스트리밍 다운로드도 identity 본문까지 `max-decoded-bytes`로 센다. 실험 transport인 Jetty HTTP/3도 이제 스스로 풀지 않는다 | HTTP client를 쓰는 서비스 |
|
||||
| 9 | SMTP provider profile의 `timeout`(기본이 `10s`에서 `30s`로 바뀌었다)이 발송 한 번을 두 번 묶는다. 발송이 send pool에서 그 시간이 지나도록 시작하지 못하면 relay에 보내지 않고 시작 전 실패(`PROVIDER_UNAVAILABLE`, 재시도)로 기록한다. 시작한 뒤 그 시간이 지나면 결과 불명(`PROVIDER_RESPONSE_LOST`)으로 기록하고 자동으로 다시 보내지 않는다. 값은 `mail.smtp.connectiontimeout`에 `mail.smtp.timeout`·`mail.smtp.writetimeout` 중 긴 것을 더한 값보다 길어야 하고, `dispatch.lease-duration`은 그 두 배보다 길어야 한다. `dispatch.shutdown-grace`가 그 두 배보다 짧으면 종료 중에 끝나지 않은 발송이 결과 불명으로 남는다(`docs/notification/configuration-reference.md` 「SMTP relay」). `SmtpNotificationProviderAdapter`를 직접 만들던 코드는 마지막 인자로 이 timeout을 넘긴다. 직접 만든 `ProviderRuntimeAssembler`는 새 default 메서드 `requireTogether(profiles, deliveryLease)`로 한 family의 켜진 profile 전체에 걸린 검사를 할 수 있다(`NotificationProviderAssembly`가 SERVING일 때 family마다 한 번 부른다). `assemble`을 직접 부르는 코드는 그 전에 `requireTogether`를 부른다 | timeout이 socket timeout 합 이하이거나 lease가 timeout 두 배 이하면 SMTP 조립이 기동 때 실패한다. 상한 안에 끝나지 않는 발송이 결과 불명으로 남는다. 전에는 socket timeout이 명령마다만 묶어, 느린 relay에서 발송이 lease를 넘으면 lease 복구가 아직 도는 발송을 운영자 확인으로 넘겼다. | SMTP 알림을 켠 서비스 |
|
||||
|
||||
## 3. 바뀐 동작 (따라 할 일 없음)
|
||||
|
||||
- outbox relay의 발행 대기는 `publish()`를 부른 때부터 publisher의 `longestAttempt()`까지다. 넘으면 결과 불명(`PUBLISH_WAIT_EXCEEDED`)으로 기록하고
|
||||
다음 claim에서 다시 본다. 직접 만든 `IntegrationEventPublishPort`는 `longestAttempt()`를 실제 최장 시간으로 답한다. 0이나
|
||||
음수를 답하면 그 행은 보내지 않고 `REJECTED_RETRYABLE`(`PUBLISH_BOUND_NOT_POSITIVE`)로 backoff 뒤에 다시 본다.
|
||||
- 이미 interrupt된 relay thread는 그 행을 발행하지 않고 `REJECTED_RETRYABLE`(`PUBLISH_INTERRUPTED_BEFORE_SEND`)로 돌려준다.
|
||||
relay가 그 행을 backoff 뒤로 미뤘다가 발행한다. 기다리는 중의 interrupt는 전처럼 결과 불명(`PUBLISH_WAIT_INTERRUPTED`)이다.
|
||||
- SMTP 발송 pool은 첫 발송부터 `dispatch-concurrency`개 thread로 돈다(전에는 대기열이 찰 때까지 thread 하나였다).
|
||||
pool이 거절한 발송은 relay에 닿지 않은 것(`PROVIDER_UNAVAILABLE`, `CAPACITY_REJECTED`)으로 기록되어 재시도된다.
|
||||
- S3 control 저장소의 조건부 `PUT`이 412를 받으면 key를 다시 읽는다. 이 호출이 쓴 record 그대로면 성공이다(SDK가 응답을
|
||||
잃은 첫 쓰기를 다시 보낸 경우). 다른 내용이나 없음이면 전처럼 충돌이다. 「그대로」는 같은 값이라는 뜻이라, 두 writer가
|
||||
같은 버전에서 같은 record를 쓰면 둘 다 성공으로 본다. 그럴 수 있는 호출자는 record에 자기 토큰을 싣는다.
|
||||
- MongoDB tenant client를 내보내다 닫기에 실패하면 그 tenant 대신 `evictionCloseFailures()`가 센다. 닫기를 부른 다른
|
||||
tenant의 `acquire`는 실패하지 않는다.
|
||||
@@ -125,7 +125,9 @@ Envelope가 아닌 응답은 두 곳뿐이다. fileserver의 프로토콜 예외
|
||||
`IDEMPOTENT_IN_FLIGHT`, lease가 지났으면 500 `IDEMPOTENCY_RECOVERY_REQUIRED`다. 이것은 Redis 저장소의
|
||||
판정이다. PostgreSQL 저장소는 아래처럼 첫 요청이 끝날 때까지 기다린 뒤 판정한다. 새 키로 보내면 서버는
|
||||
다른 요청으로 보고 막지 못한다(재리뷰 2026-11-03 README 4절 결정 RR-02-03, 2026-11-04 9.1절 결정
|
||||
RR-01-11).
|
||||
RR-01-11). Redis 저장소의 판정은 그 기록이 Redis에 남아 있는 동안만이다. Sentinel·Cluster failover는 비동기
|
||||
복제라 replica에 아직 넘기지 못한 기록을 잃을 수 있고, 그러면 같은 키 요청은 처음 보는 키로 다시 실행된다
|
||||
(`docs/manual/05-idempotency.md` 「클라이언트에게 무엇을 약속하나」).
|
||||
- **첫 시도가 lease보다 오래 걸릴 때 — 저장소마다 다르다.** executor는 lease를 늘리지 않으므로 30s를 넘는
|
||||
정상 요청도 lease가 지난다(재리뷰 2026-11-04 RR5-01-05).
|
||||
- Redis: lease가 지난 실행 기록을 다음 요청이 만나면 500으로 답하고 기록은 건드리지 않는다. 첫 시도가
|
||||
|
||||
@@ -64,7 +64,8 @@ workflow에만 있는 job: `pr.yml` `done`의 마지막 step과 `main.yml`의 `v
|
||||
| 공개 경로·보안 체인 | `verifyPublicPathSnapshot` |
|
||||
| 의존성 | `verifyDependencyLocks` |
|
||||
| 문서(`docs/**`, `AGENTS.md`·`CLAUDE.md`, README) | 그 문서를 읽는 document-contract lane(예: `:app-bootstrap:documentContractTest`) + 링크 검사(아래) + `python3 scripts/check-docs.py` |
|
||||
| 파일·폴더·Gradle 프로젝트를 지우거나 옮김 | `python3 scripts/check-docs.py`(문서가 가리키던 경로가 사라진다) |
|
||||
| 파일·폴더·Gradle 프로젝트를 지우거나 옮김 | `python3 scripts/check-docs.py`(문서와 `docs/registries/*.yaml`이 가리키던 경로가 사라진다) |
|
||||
| 지표·헤더를 등록하는 코드(이름 상수, 등록 줄, 그 파일)를 옮기거나 바꿈 | `:app-bootstrap:documentContractTest`(registry 행과 등록 코드를 대조한다. 파일은 남고 등록만 다른 파일로 간 행은 이 lane만 본다) |
|
||||
| `docs/work/`, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서 | `python3 scripts/check-work-docs.py` |
|
||||
| 다른 매뉴얼에서 이력 ID를 걷어냄 | `python3 scripts/check-work-docs.py --history <파일 또는 폴더>` |
|
||||
| build-logic·workflow(`.gitea/`) | `-p build-logic check javadoc`, `verifyStrictLaneStages --dry-run` |
|
||||
@@ -149,7 +150,7 @@ for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') |
|
||||
|
||||
**smoke 이미지가 이 트리에서 만들어졌음을 보이기.** smoke·compose lane은 Docker 레이어 캐시를 쓴다. 이미지 생성 시각은 runtime 레이어가 캐시에서 오면 증거가 못 된다. 앱 jar를 복사하는 단계가 smoke 로그의 build 출력에서 `CACHED`가 아닌지 본다. 앱 jar가 이 트리에서 새로 만들어졌으면 그 단계는 캐시가 될 수 없다. 결과 표 「실제 실행」 칸에 그 줄과 이미지 id를 적는다.
|
||||
|
||||
**원래 있던 실패 가리기.** 시간·자원에 기대는 실패(OOM, 시간 초과, 순서 의존)는 기준 커밋과 이번 트리에서 같은 명령을 각각 세 번 돌린다. 기준에서 한 번이라도 같은 원인(같은 테스트, 로그의 같은 OOM·시간 초과)으로 실패하면 이전부터의 실패로 적는다. 기준에서 세 번 다 통과하고 이번 트리에서만 실패하면 이번 변경 몫이다. 순서 의존을 재현하려면 그 테스트 클래스를 `--tests <클래스> --rerun`으로 열 번 돌리고, 부하가 필요하면 잠금을 쥔 채 `nproc`개의 `yes > /dev/null &`를 띄웠다가 끝나면 끈다. 실패한 반복 수를 적는다.
|
||||
**원래 있던 실패 가리기.** 시간·자원에 기대는 실패(OOM, 시간 초과, 순서 의존)는 기준 커밋과 이번 트리에서 같은 명령을 각각 세 번 돌린다. 기준에서 한 번이라도 같은 원인(같은 테스트, 로그의 같은 OOM·시간 초과)으로 실패하면 이전부터의 실패로 적는다. 기준에서 세 번 다 통과하고 이번 트리에서만 실패하면 이번 변경 몫이다. 순서 의존을 재현하려면 그 테스트 클래스를 `--tests <클래스> --rerun`으로 열 번 돌리고, 부하가 필요하면 잠금을 쥔 채 `nproc`개의 `yes > /dev/null &`를 띄웠다가 끝나면 끈다. 실패한 반복 수와 각 반복을 시작할 때의 부하(`uptime`)를 적는다. runner에서 실패했으면 그 job이 돈 시각에 desktop에서 잠금 아래 돈 실행도 적는다(runner는 잠금 밖이다). 흔들림으로 판정하면 `docs/ledger/flaky-tests.jsonl`에 한 줄을 더하고, 상한을 늘리거나 재시도를 붙이지 않고 design-docs `ci/manual.md` 8.4절대로 고친다.
|
||||
|
||||
**공유 잠금 기다리기.** 순서는 `flock`이 정한다(먼저 잡은 쪽). 따로 순번을 정하지 않는다. 기다리는 명령은 background로 두고 다른 일을 하며, 대기는 완료나 첫 실패에서 끝나는 것 하나로 둔다. 30분 넘게 못 잡으면 `ps -o pid,etime,args -C flock`으로 쥔 쪽을 보고 맡긴 쪽에 알린다([operate.md](../operate.md) 7절).
|
||||
|
||||
|
||||
@@ -159,7 +159,7 @@
|
||||
| 규칙 테스트가 위반·허용 fixture를 둘 다 가지나 | 위반 fixture만 있어 거짓 양성을 못 봄 |
|
||||
| `// when`이 하나인가 | 두 동작을 한 테스트가 봄 |
|
||||
| 테스트 코드도 정적 분석을 통과하나 | 게이트 밖에서 실패한 채 방치 |
|
||||
| 타이밍에 기대지 않나 | 부하가 높으면 실패하는 "스레드 없음" 단언 |
|
||||
| 타이밍에 기대지 않나 | 부하가 높으면 실패하는 "스레드 없음" 단언, PR·main 단계 시험의 벽시계 상한(「1.5초 안에」) 단언, 스레드 시작 순서를 결과 순서로 보는 단언. 시계 주입·조건 대기·결과 단언으로 쓴다(design-docs `ci/manual.md` 8.4절) |
|
||||
|
||||
fake와 공유 계약: 포트마다 hand-rolled fake 하나를 포트 소유 leaf의 `testFixtures`에 두고, fake와 실제 adapter가 같은 추상 계약(`XxxContract`)을 상속한다. 계약 밖 fake, 소비자 없는 fake, 계약과 겹친 adapter 손 사본 테스트는 만들지 않는다. fake 동작을 바꾸면 계약 케이스를 같이 바꾼다. 포트를 더하거나 계약을 옮기면 `docs/testing/TESTING_STRATEGY.md`의 현황표를 고친다.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user