diff --git a/AGENTS.md b/AGENTS.md index 85d4ba87..85ddbe81 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -84,7 +84,9 @@ root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어 줄 때문에 옵션을 별개 명령으로 떼어 내지 않는지 검사한다. 두 빌드가 각자 검사를 돌린다. `-x`로 뺀 lane(Gradle처럼 축약 이름도 맞춰 본다), `continue-on-error` 아래 명령, 상태 함수(`always()`·`success()`· `!cancelled()`)가 아닌 `if:` 아래 명령, `workflow_dispatch`로만 시작하는 workflow의 명령은 실행으로 세지 - 않는다. 명령이 어느 빌드를 실행하는지는 `working-directory`와 `-p`를 합친 디렉터리로 정한다. + 않는다. 명령이 어느 빌드를 실행하는지는 `working-directory`에서 시작해 같은 셸이 그 앞에서 확실히 + 실행한 `cd <상대 경로>`를 따라간 뒤 `-p`를 합친 디렉터리로 정한다. 따라갈 수 없는 `cd`(`cd "$VAR"`· + `cd -`·`pushd`·조건부·서브셸 등) 뒤의 명령은 추측하지 않고 세지 않는다. 작업 파일의 소유 leaf는 registry의 `source_path`로 판단하고 가장 가까운 `src/**/CLAUDE.md`를 함께 읽는다. focused test는 registry의 `gradle_path`에서 diff --git a/CLAUDE.md b/CLAUDE.md index f5be6770..86008ebb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -42,8 +42,9 @@ If this summary drifts from `AGENTS.md`, `AGENTS.md` wins and this summary must fails when a non-`explicitOnly` strict lane is in no stage a workflow executes — a lane the command removes with `-x` (abbreviations matched as Gradle does), a command under `continue-on-error` or a non-status `if:`, and a `workflow_dispatch`-only workflow do not count; - the build a command runs is its `working-directory` joined with `-p` — or a folded workflow - `run:` block splits an option off its command. + the build a command runs is its `working-directory`, then the `cd ` the same shell + surely ran before it, joined with `-p` (a `cd` it cannot follow is not guessed: the command does + not count) — or a folded workflow `run:` block splits an option off its command. Commit policy is `human-only`: agents do not stage, commit, amend, or push implementation changes. diff --git a/docs/manual/05-idempotency.md b/docs/manual/05-idempotency.md index 629ea091..df919df0 100644 --- a/docs/manual/05-idempotency.md +++ b/docs/manual/05-idempotency.md @@ -56,11 +56,14 @@ DB 커밋 중 연결 끊김 ───────────────── 같은 키 재전송은 작업을 다시 돌리지 않는다. 첫 시도가 실행을 시작한 뒤 processing lease(기본 30s)가 지나면 두 저장소 모두 그 기록을 넘겨주지 않고 500 `IDEMPOTENCY_RECOVERY_REQUIRED`로 답한다. 넘겨받는 것은 -실행 전 claim과 재시도 가능한 실패뿐이다. 기록은 lease + `replay-ttl` 동안 남고, `replay-ttl`이 lease보다 -짧으면 기동이 실패한다(`IdempotencyStoreContract`, 재리뷰 2026-11-04 RR-01-11·RR-03-11). 작업이 실패로 -끝나 executor가 포기나 재시도 가능으로 표시한 기록은 표시한 때부터 `failure-retention`(기본 24h) 동안 -남는다. 이 값은 검사하지 않으므로 `replay-ttl` 이상으로 둔다. 짧으면 효과 불명으로 포기한 기록이 먼저 -사라져 같은 키 재전송이 작업을 다시 돌린다(RR3-03-02). +실행 전 claim과 재시도 가능한 실패뿐이다. 이 답은 기록을 바꾸지 않는다. executor는 lease를 늘리지 않아 +30s를 넘는 정상 요청도 lease가 지나는데, 그 첫 시도가 나중에 끝나면 결과가 기록되고 첫 요청은 정상 응답을 +받으며 그 뒤 같은 키 요청은 그 결과를 재생한다(2026-11-04 소유자 결정). 기록은 lease + `replay-ttl` 동안 +남고, `replay-ttl`이 lease보다 짧으면 기동이 실패한다(`IdempotencyStoreContract`, 재리뷰 2026-11-04 +RR-01-11·RR-03-11). 작업이 실패로 끝나 executor가 포기나 재시도 가능으로 표시한 기록은 표시한 때부터 +`failure-retention`(기본 24h) 동안 남는다. `failure-retention`이 `replay-ttl`보다 짧으면 기동이 실패한다. +짧으면 효과 불명으로 포기한 기록이 먼저 사라져 같은 키 재전송이 작업을 다시 돌리기 때문이다(RR3-03-02, +2026-11-04 소유자 결정). 409를 `retryable=true`로 바꾼 이유(리뷰 02-01 결정): 같은 키 재전송은 서버가 안전하게 판정하므로 다시 보내는 것이 맞고, 새 키로 보내면 서버가 막지 못한다. 짝 프론트 분류기도 이 표를 따른다. diff --git a/docs/registries/env-keys.yaml b/docs/registries/env-keys.yaml index 130556ce..e1f99361 100644 --- a/docs/registries/env-keys.yaml +++ b/docs/registries/env-keys.yaml @@ -1682,9 +1682,10 @@ env_keys: - name: APP_IDEMPOTENCY_FAILURE_RETENTION # app.capabilities.idempotency.failure-retention: how long a record the executor marked failed - # (abandoned with an unknown effect, or retryable without one) stays, from the marking. Not - # compared with APP_IDEMPOTENCY_TTL at startup; keep it at least that long, or an abandoned - # record goes first and a same-key resend runs the work again (re-review 2026-11-04 RR3-03-02). + # (abandoned with an unknown effect, or retryable without one) stays, from the marking. At most + # 30d, and IdempotencySettings refuses less than APP_IDEMPOTENCY_TTL at startup: a shorter one + # lets an abandoned record go first, and a same-key resend runs the work again (re-review + # 2026-11-04 RR3-03-02, owner decision 2026-11-04). type: duration default: 24h allowed_values: null @@ -1692,8 +1693,8 @@ env_keys: required: false reload_policy: restart-only owner_branch: redis-production-capability-completion - validation: positive_duration_le_30d - compatibility_impact: additive + validation: positive_duration_le_30d_ge_replay_ttl + compatibility_impact: behavior-change required_test: redis-idempotency-contract:failure-retention-bounded - name: APP_LEASE_PROVIDER diff --git a/docs/reviews/2026-11-03-rereview/README.md b/docs/reviews/2026-11-03-rereview/README.md index 7e2cf65a..5df98328 100644 --- a/docs/reviews/2026-11-03-rereview/README.md +++ b/docs/reviews/2026-11-03-rereview/README.md @@ -290,3 +290,31 @@ Minor 19건 중 동작에 닿는 것: | `scripts/verify-compose-profile-contracts.sh` | rc=0, 18 lane | — | 12.23 | 고친 테스트의 컨테이너 lane은 수정 에이전트가 고친 클래스만 따로 돌렸다(`jpaPlatformContractTest` 9, `jpaPlatformFailureTest` 2, `postgresqlDistributedLockIntegrationTest` 6, `posterImageMigrationTest` 10, redis-sdk standalone `redisTopologyTest` 14). `mainCheck`가 5분 넘게 길어진 것은 이 단계의 비용이다. + +## 15. 소유자 결정 반영 r8 (2026-11-04) + +PR #1을 만든 뒤 사용자가 묶음이 기본값으로 정한 세 가지를 다시 물었다. 따져 본 결과와 소유자 결정: + +| # | 기본값 | 다시 따져 본 것 | 소유자 결정 | +|---|---|---|---| +| ① | lease가 지난 실행을 다음 claim이 포기(ABANDONED)로 표시해, 늦게 끝난 첫 시도의 결과를 버린다 | "기존 PostgreSQL이 그렇게 한다"는 것 말고 근거가 없었다. executor가 lease를 갱신하지 않아 30s 넘는 정상 요청도 해당된다. "늦은 완료는 기록"도 다시 실행하지 않으므로 똑같이 안전하고, 첫 요청은 자기 결과를 받는다 | **늦은 완료는 기록한다** | +| ② | `verifyStrictLaneStages`가 workflow 명령의 빌드를 `working-directory` + `-p`로만 정한다 | 빌드 도구 내부 결정이고 틀려도 거짓 실패 쪽이다. 다만 `cd src && ./gradlew`를 세지 않아 파생 서비스에서 거짓 실패가 난다 | **같은 셸의 `cd <상대 경로>`도 따라간다** | +| ③ | `failure-retention < replay-ttl`을 기동에서 막지 않는다(주석 경고뿐) | 효과 불명 실패의 중복 방지 기간이 조용히 짧아진다. "위험은 코드에 드러나야 한다"에 어긋나고, `replay-ttl < lease` 기동 실패와 같은 종류다 | **기동을 실패시킨다** | + +| 묶음 | 상태 | 검증 (에이전트) | 처리 내용 | 결정·남은 것 | +|---|---|---|---|---| +| r8-a 멱등성 | 완료 | application-core·composition:idempotency·persistence-jpa·cache-redis·redis-runtime `check`·`testQualityCheck`, PG 멱등성 계약 25/25, `postgresqlIdempotencyIntegrationTest` 8/8, `redisContainerContractTest` 64/64, architectureCheck, verifyEnvKeys, documentContractTest | ① lease 지난 EXECUTING을 claim이 만나면 기록을 바꾸지 않고 `RecoveryRequired`(PG `abandonExpiredExecution` 삭제, Redis CLAIM·command fake 같게). 주인의 늦은 `complete`·`markFailed`는 기록, 다음 claim은 재생(RED 실 PG 5·실 Redis 6·fake 2·PG 통합 1). 공유 계약의 "늦은 complete 거절" 케이스를 반대로, 시간 케이스 6개 추가. ③ `IdempotencySettings`가 `failure-retention < replay-ttl`이면 기동 실패(RED 2) | `renew`: 이미 끝난 lease는 두 저장소 모두 거절(Redis만 받던 것을 PG에 맞춤). `inspect`: lease 지난 남의 실행은 `ABANDONED`로 보고. runbook: lease가 지났어도 `EXECUTING` 기록은 지우지 않는다(지우면 늦은 완료가 사라지고 같은 키가 다시 실행된다). 오케스트레이터가 `http-contract.md` 표의 `IDEMPOTENCY_RECOVERY_REQUIRED` 행("재전송도 안전하지 않다")을 이 동작에 맞게 고쳤다. 남음: CLAIMED → 실행 시작에서 PG는 lease를 보고 Redis는 보지 않는다(새로 본 것, 고치지 않음) | +| r8-b workflow `cd` | 완료 | `-p build-logic check javadoc` 131, 두 빌드 verifyStrictLaneStages, 실제 workflow 15개의 명령 65개가 이전 판독과 같음, workflow 13개를 `cd` 모양으로 바꾼 실험(통과)과 `cd "$GITHUB_WORKSPACE/src"` 실험(이유를 대며 실패) | ② `working-directory` → 같은 셸의 최상위 `cd <상대 경로>`(혼자 한 줄, `;`, `&&`) → `-p` 순서로 빌드를 정한다(RED 단위 3·TestKit 2). 읽을 수 없는 이동(`$VAR`, `-`, `~`, 절대 경로, `pushd`, 서브셸·조건문 안, `||`·`|`) 뒤의 명령은 이유를 대며 세지 않는다 | 남음(이전부터, 고치지 않음): 실패를 막지 못하는 명령도 실행으로 센다 — `./gradlew ci || true`, `./gradlew ci | tee log`, `if ./gradlew ci; then`. 거짓 통과다 | + +### 15.1 게이트 (2026-11-04, 공유 잠금, 첫 실행 모두 통과) + +| 게이트 | 결과 | 시간 | 실행 직전 부하(1분) | +|---|---|---|---| +| `ci` | rc=0 | 6분 26초 | 3.17 | +| `verifyStrictLaneStages --dry-run` (주 빌드 / optional) | rc=0 / rc=0 | 10초 / 3초 | 12.86 / 10.84 | +| `mainCheck` | rc=0 | 8분 20초 | 10.84 | +| `:integrationCheck` | rc=0 | 14분 52초 | 10.34 | +| `-p optional-platforms ci integrationCheck performanceCheck` | rc=0 | 1분 46초 | 4.01 | +| `:performanceCheck` | rc=0 | 27초 | 22.93 | +| `:releaseCheck -PgitRevision=` | rc=0 | 4초 | 20.00 | +| `scripts/verify-compose-profile-contracts.sh` | rc=0, 18 lane | — | 18.72 | diff --git a/docs/runbooks/idempotency-unavailable.md b/docs/runbooks/idempotency-unavailable.md index cf32d735..457a53af 100644 --- a/docs/runbooks/idempotency-unavailable.md +++ b/docs/runbooks/idempotency-unavailable.md @@ -24,12 +24,14 @@ status: active a transaction (an outbound call, a message) may have happened. This is not "nothing was executed". Clients resend with the same key. - HTTP 500 `IDEMPOTENCY_RECOVERY_REQUIRED` (`retryable=false`) means the opposite case: the store - cannot tell whether an earlier attempt's effect already happened. The usual cause: an attempt - started and its processing lease (`APP_IDEMPOTENCY_PROCESSING_LEASE`, 30s) ran out before it - recorded a result — it crashed, or ran longer than the lease. The next request with the key marks - the record abandoned and every later one gets this 500; the server never runs it again, and a late - result from the first attempt is not recorded either. An action that threw, or reported its effect - unknown, is abandoned the same way. + cannot tell whether an earlier attempt's effect already happened. Two records produce it: + - `ABANDONED`: the action threw, or reported its effect unknown. Final until the record expires. + - `EXECUTING` past its processing lease (`APP_IDEMPOTENCY_PROCESSING_LEASE`, 30s): the attempt + crashed, or is still running longer than the lease. The executor never renews the lease, so a + slow but healthy request lands here too. The server never runs it again and does not touch the + record. If the attempt is still running and finishes, its result is recorded, the first request + gets its normal answer, and later requests with the key get that result replayed; a failure it + reports is recorded the same way. So this 500 can stop on its own (owner decision 2026-11-04). ## Diagnosis @@ -53,8 +55,10 @@ status: active PTTL ``` - `state` `ABANDONED` is the recovery-required record. `leaseUntil` is the lease end in epoch - milliseconds (server clock); `PTTL` is how long the record still lives, in milliseconds. + `state` `ABANDONED` is final. `state` `EXECUTING` with a `leaseUntil` (lease end, epoch + milliseconds, server clock) earlier than the server's `TIME` (first value × 1000) is an attempt + past its lease that may still be running. `PTTL` is how long the record still lives, in + milliseconds. - PostgreSQL, in the application's schema: ```sql @@ -65,9 +69,11 @@ status: active AND scope_hash = ''; ``` - `last_transition_kind` `EXPIRED_EXECUTION` means the lease ran out (the first attempt may still - have finished its work); `FAIL_ABANDONED` means the action threw or reported its effect unknown. - `expires_at` is when the reaper deletes the row. + `status` `ABANDONED` with `last_transition_kind` `FAIL_ABANDONED` means the action threw or + reported its effect unknown. `status` `EXECUTING` with `processing_lease_until` before + `clock_timestamp()` is an attempt past its lease that may still be running. (`ABANDONED` with + `EXPIRED_EXECUTION` is a lease that ran out under a version before 2026-11-04, which abandoned + such rows; it goes away when the row expires.) `expires_at` is when the reaper deletes the row. ## Action @@ -76,14 +82,24 @@ status: active transaction for the failed requests (the ERROR log line names the code). A same-key resend replays a result that was in fact recorded, gets `IDEMPOTENT_IN_FLIGHT` while the attempt's lease lasts, and `IDEMPOTENCY_RECOVERY_REQUIRED` after it — handle that one as below. -- `IDEMPOTENCY_RECOVERY_REQUIRED`: do not ask the client to retry blindly. Confirm from business data - (the order, the payment, the downstream system) whether the earlier attempt's effect exists. There - is no way to complete the record by hand — the stored response is the action's own result. +- `IDEMPOTENCY_RECOVERY_REQUIRED`: do not ask the client to retry blindly. If the record is + `EXECUTING` past its lease, first wait for the attempt: look the record up again after the + longest time the action can take. It changes by itself when the attempt finishes — `COMPLETED` + (resends replay it, nothing to do), `ABANDONED`, or `FAILED_RETRYABLE` (the attempt proved it had + no effect, and the next request with the key runs it). A crashed attempt, or one whose request + already ended with `IDEMPOTENCY_COMPLETION_UNKNOWN`, never changes it; that record stays + `EXECUTING` until it expires. Business data checked while the attempt still runs can say "no + effect" a moment before the effect lands. Then confirm from business data (the order, the + payment, the downstream system) whether the effect exists. There is no way to complete the record + by hand — the stored response is the action's own result. - The effect exists: tell the client it was applied. Leave the record; a resend with the key keeps getting this 500 until the record expires (Redis `PTTL`, PostgreSQL `expires_at`). - The effect does not exist: the client sends the request again under a new key. To let the same key run again instead, delete the record — only while it is `ABANDONED`, because any other state - belongs to a request in progress or a stored result: + belongs to a request that may still be running or to a stored result. Do not delete an + `EXECUTING` record, even past its lease: if its attempt is still alive, its late result finds no + record (`ABSENT`) — the result is lost, the first request gets this 500 after its work took + effect, and the next request with the key runs the work a second time. Leave it to expire. - Redis: check `HMGET state` is `ABANDONED` and `PTTL ` has minutes left, then `DEL `. A record that is about to expire needs nothing; once it is gone the key is new. - PostgreSQL: @@ -95,10 +111,10 @@ status: active AND status = 'ABANDONED'; ``` - Without either step the key is released when the record expires. That record lives for the - processing lease plus `APP_IDEMPOTENCY_TTL` from its claim when its lease ran out, and for - `APP_IDEMPOTENCY_FAILURE_RETENTION` from the failure when the action failed - (`docs/web/http-contract.md`, "서버가 기억하는 기간"). + Without either step the key is released when the record expires. A record whose attempt never + finished lives for the processing lease plus `APP_IDEMPOTENCY_TTL` from its claim; one the action + marked failed lives for `APP_IDEMPOTENCY_FAILURE_RETENTION` (not shorter than `APP_IDEMPOTENCY_TTL`) + from the failure (`docs/web/http-contract.md`, "서버가 기억하는 기간"). ## Escalation diff --git a/docs/study/postgresql-jpa-walkthrough.ko.md b/docs/study/postgresql-jpa-walkthrough.ko.md index d313dee9..8e95475e 100644 --- a/docs/study/postgresql-jpa-walkthrough.ko.md +++ b/docs/study/postgresql-jpa-walkthrough.ko.md @@ -1681,7 +1681,7 @@ setter가 아니라 **registry 생성자**에서 설정한다. |---|---| | `IdempotencyCapabilityGuard` | 3개 precondition (vendor, capability, transaction) | | `IdempotencyRowMapper` | row 읽기 + `clock_timestamp()` | -| `IdempotencyClaimGateway` | 소유권을 **정하는** 3개 statement (insert / reset / abandon) | +| `IdempotencyClaimGateway` | 소유권을 **정하는** 2개 statement (insert / reset) | | `IdempotencyTransitionGateway` | 이미 가진 claim을 **진행시키는** 5개 statement | | `IdempotencyDigestPolicy` | transition digest 구성 | | `IdempotencyRecordRow` | row 정의 (package-private) | @@ -1704,13 +1704,15 @@ COMPLETED이고 replay_until 있음 → CompletedReplay(payl 같은 token, 다른 operationId → OwnerOperationConflict CLAIMED이고 lease 만료 → resetClaim → TakenOverClaimed FAILED_RETRYABLE → resetClaim → TakenOverClaimed -EXECUTING이고 lease 만료 → abandonExpiredExecution → RecoveryRequired +EXECUTING이고 lease 만료 → RecoveryRequired (행은 그대로) ABANDONED → RecoveryRequired 그 외 → InProgress(retryAfter, attempt) ``` -**만료된 `CLAIMED`만 takeover하고, 만료된 `EXECUTING`은 `ABANDONED`로 닫고 reconciliation을 -요구한다.** 실행이 시작된 뒤의 blind retry를 하지 않는다는 뜻이다. +**만료된 `CLAIMED`만 takeover하고, 만료된 `EXECUTING`은 reconciliation을 요구하되 행은 바꾸지 +않는다.** 실행이 시작된 뒤의 blind retry를 하지 않는다는 뜻이다. 행을 그대로 두는 이유는 주인이 아직 +돌고 있을 수 있어서다. 주인이 늦게 끝나면 그 결과가 기록되고 다음 claim이 재생한다(2026-11-04 소유자 +결정 — 전에는 `abandonExpiredExecution`이 행을 `ABANDONED`로 바꿔 늦은 결과를 버렸다). `IdempotencyCapabilityGuard`에 아주 좋은 버그 기록이 있다. diff --git a/docs/upgrade/2026-11-maturity-review.md b/docs/upgrade/2026-11-maturity-review.md index ea1caea3..592739b2 100644 --- a/docs/upgrade/2026-11-maturity-review.md +++ b/docs/upgrade/2026-11-maturity-review.md @@ -79,7 +79,7 @@ | B-21 | 트랜잭션 제한: `TransactionPort` 쓰기·읽기 트랜잭션 30초(`app.persistence-jpa.transaction.write-timeout`·`read-timeout`, env 키 아님) | 30초를 넘는 트랜잭션은 문장이 취소되고 `DB_QUERY_CANCELED`로 실패 | 긴 일괄 작업은 쪼갠다. 꼭 필요하면 프로필 yml에서 값을 올린다 | `1400dc15` · `persistence-jpa.yml` | | B-22 | 격리 수준을 Hikari에서 고정: `spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED`. 다른 값이면 거부. `TransactionPort`는 트랜잭션마다 격리 수준을 정하지 않는다 | 다른 격리 수준을 설정했다면 기동 실패(`HikariPoolConstraintValidator`) | 값을 지운다. 더 높은 격리가 필요한 곳은 따로 설계한다 | `1400dc15` · `src/adapter/outbound/persistence-jpa/.../startup/HikariPoolConstraintValidator.java` | | B-23 | H2 드라이버가 운영 jar에서 빠짐(persistence-jpa `runtimeOnly` → `testRuntimeOnly`). `bootRunH2` 작업만 따로 넣는다 | `APP_PERSISTENCE_VENDOR=h2`로 `bootRunH2` 밖에서 띄우면 드라이버가 없다(정확한 오류 확인 못 함) | 로컬은 Compose PostgreSQL 또는 `bootRunH2`를 쓴다 | `1400dc15` · `src/adapter/outbound/persistence-jpa/build.gradle` | -| B-24 | `APP_IDEMPOTENCY_PROCESSING_LEASE`는 2초(`IdempotencyExecutor.IN_FLIGHT_RETRY_AFTER`)보다 길어야 한다. `APP_IDEMPOTENCY_TTL`(replay TTL)은 그 lease보다 짧으면 안 된다(재리뷰 RR-03-11) | 2초 이하면, 또는 replay TTL < lease면 기동 실패 | lease를 2초보다 길게(기본 30s), replay TTL을 lease 이상으로(기본 24h) | `5786126c`, `bbe944bd`, 3차 수정 · `src/composition/idempotency/.../IdempotencySettings.java` | +| B-24 | `APP_IDEMPOTENCY_PROCESSING_LEASE`는 2초(`IdempotencyExecutor.IN_FLIGHT_RETRY_AFTER`)보다 길어야 한다. `APP_IDEMPOTENCY_TTL`(replay TTL)은 그 lease보다 짧으면 안 된다(재리뷰 RR-03-11). `APP_IDEMPOTENCY_FAILURE_RETENTION`은 replay TTL보다 짧으면 안 된다(RR3-03-02) | 2초 이하면, replay TTL < lease면, 또는 failure retention < replay TTL이면 기동 실패(exit 78). 마지막은 메시지에 `failure-retention`·`replay-ttl` 두 키와 값이 나온다 | lease를 2초보다 길게(기본 30s), replay TTL을 lease 이상으로(기본 24h), failure retention을 replay TTL 이상으로(기본 24h — 기본값끼리는 그대로 뜬다) | `5786126c`, `bbe944bd`, 3차 수정, 2026-11-04 소유자 결정 · `src/composition/idempotency/.../IdempotencySettings.java` | | B-25 | 알림 콜백 본문 상한 65508 → 65251(바인딩에서 상한 검사) | `.env`에 옛 예제 값 `APP_NOTIFICATION_PLATFORM_CALLBACK_MAX_BODY_BYTES=65508`이 있으면 기동 실패 `max-body-bytes must be 1..65251` | 값을 지우거나 65251 이하로 | `5786126c` · `src/adapter/outbound/notification/.../autoconfigure/NotificationPlatformSettings.java` | | B-26 | `config/module-defaults/`에 같은 이름 파일이 둘이거나, 두 파일이 같은 키를 실으면 기동 실패 | 기동 실패 `two capability modules ship config/module-defaults/` 또는 `... both ship `(exit 78) | 자기 leaf의 module-defaults 파일 이름·키가 템플릿 모듈과 겹치지 않게 한다 | `1400dc15` · `src/adapter/outbound/support/.../startup/ModuleDefaultsEnvironmentPostProcessor.java` | | B-27 | (sample-portfolio를 남겨 둔 경우) 데모 계정은 활성 프로필이 모두 `local`·`test`·`demo` 중 하나일 때만. 프로필이 없어도 거부 | 기동 실패 `the sample's demo accounts authenticate only under the local, test or demo profile` | `SPRING_PROFILES_ACTIVE=demo`(이미지·jar), `local`(bootRun)로 띄우거나 sample 보안 설정을 지운다. 세 프로필 모두 sample `application.yml`이 object storage를 끈다(RR2-04-02) | `5786126c`, `bbe944bd` · `src/sample-portfolio/.../security/SampleDemoAccountsProductionGuard.java` | @@ -92,7 +92,7 @@ |---|---|---|---|---| | B-28 | 처리 중 409 `IDEMPOTENT_IN_FLIGHT`: `retryable` false→true, `Retry-After: 2` 추가. gRPC trailer `error-retryable`과 GraphQL extension `retryable`도 true | 409를 "재시도 금지"로 처리하던 클라이언트가 틀린다 | **같은 `Idempotency-Key`로** `Retry-After` 뒤 재전송하게 한다. 새 키 금지 | `34565130` · `src/shared-contract/.../error/OperationalError.java`, `docs/registries/error-codes.yaml` | | B-29 | Envelope의 `null` 필드를 키째 생략: 성공은 `error` 키 없음, 실패는 `data` 키 없음, `meta.page`·`meta.correlationId`·`error.details`도 값이 없으면 키 없음. 빈 목록은 그대로 | `"error": null`·`"data": null`을 기대하던 클라이언트·계약 테스트가 깨진다 | `success`로 가르고 키 존재로 판단하지 않는다 | `34565130` · `src/adapter/inbound/web/.../envelope/EnvelopeWireFormatConfig.java` | -| B-30 | 새 코드 `IDEMPOTENCY_COMPLETION_UNKNOWN`(503, `TRANSIENT_DEPENDENCY`, retryable=true): 작업 실행 **뒤** complete 단계에서 멱등성 저장소가 응답하지 않음. 전에는 `IDEMPOTENCY_UNAVAILABLE` | 503을 "적용 안 됨"으로 읽던 클라이언트가 새 키로 다시 보내 중복이 생길 수 있다 | `error.code`로 가른다. 결과 불명이므로 같은 키로만 재전송. 실행 중 lease가 지난 기록은 두 저장소 모두 500 `IDEMPOTENCY_RECOVERY_REQUIRED`로 답한다 — Redis 저장소는 전에 넘겨받아 작업을 다시 돌렸다(재리뷰 RR-01-11) | `bbe944bd`, 3차 수정 · `src/application-core/.../idempotency/IdempotencyCompletionUnknownException.java`, `IdempotencyExecutor.java`, `src/adapter/outbound/cache-redis/.../idempotency/IdempotencyScripts.java` | +| B-30 | 새 코드 `IDEMPOTENCY_COMPLETION_UNKNOWN`(503, `TRANSIENT_DEPENDENCY`, retryable=true): 작업 실행 **뒤** complete 단계에서 멱등성 저장소가 응답하지 않음. 전에는 `IDEMPOTENCY_UNAVAILABLE` | 503을 "적용 안 됨"으로 읽던 클라이언트가 새 키로 다시 보내 중복이 생길 수 있다 | `error.code`로 가른다. 결과 불명이므로 같은 키로만 재전송. 실행 중 lease가 지난 기록은 두 저장소 모두 500 `IDEMPOTENCY_RECOVERY_REQUIRED`로 답한다 — Redis 저장소는 전에 넘겨받아 작업을 다시 돌렸다(재리뷰 RR-01-11). 그 기록은 바꾸지 않아, 첫 시도가 늦게 끝나면 결과가 기록되고 그 뒤 재전송은 재생을 받는다(5절) | `bbe944bd`, 3차 수정, 2026-11-04 소유자 결정 · `src/application-core/.../idempotency/IdempotencyCompletionUnknownException.java`, `IdempotencyExecutor.java`, `src/adapter/outbound/cache-redis/.../idempotency/IdempotencyScripts.java` | | B-31 | 핸들러 밖 오류(`/error` 디스패치)를 `EnvelopeErrorController`가 실패 Envelope로 답한다. 전에는 Boot `/error` 맵이 `success:true`로 감싸져 요청 경로까지 실려 나갔다. 기본 JWT 체인에서 익명 400이 401로 바뀌지 않는다. 4xx·5xx 본문은 `success:true`로 감싸지 않는다. 보안 체인이 `DispatcherType.ERROR`를 허용한다 | 오류 본문 모양이 바뀐다. 자기 SecurityFilterChain이 ERROR 디스패치를 막으면 400이 401로 나간다 | 자기 체인에 `auth.dispatcherTypeMatchers(DispatcherType.ERROR).permitAll()`을 넣는다(템플릿 `SecurityConfig`와 같게) | `bbe944bd` · `src/adapter/inbound/web/.../error/EnvelopeErrorController.java`, `.../auth/SecurityConfig.java` | | B-32 | 새·바뀐 오류 코드: 비동기 요청 timeout 500 `INTERNAL_ERROR` → 503 `REQUEST_TIMEOUT`(retryable). `IDEMPOTENCY_KEY_INVALID` 400(`details.reason`=`MISSING`·`MALFORMED`, `IdempotencyKeyHeader.parse`를 쓰는 엔드포인트, sample은 `BAD_PARAMETER`에서 바뀜). web-advanced 예외 10종이 모두 500 `INTERNAL_ERROR`였다가 각자 코드(`ADMISSION_REFUSED` 503 등) | 코드로 분기하던 클라이언트가 새 코드를 모른다 | 클라이언트 분기표에 더한다. web-advanced 표는 `src/adapter/inbound/web-advanced/README.md` 「오류 응답」 | `1400dc15` · `src/adapter/inbound/web/.../error/WebTransportError.java`, `HttpStatusErrorCodes.java`, `src/adapter/inbound/web-advanced/.../error/WebAdvancedError.java` | | B-33 | DB 실패 분류: 낙관적 잠금 충돌 500 → 409 `DB_OPTIMISTIC_CONFLICT`. 커밋 단계 연결 끊김(08xxx, 40003 등)을 재시도 가능으로 답하던 것 → 500 `DB_COMPLETION_UNKNOWN`(retryable=false) | 응답 status·code가 바뀐다 | 409는 다시 읽고 재시도, `DB_COMPLETION_UNKNOWN`은 업무 데이터로 결과를 확인 | `34565130`, `1400dc15` · `src/adapter/outbound/persistence-jpa/.../failure/PersistenceExceptionTranslator.java` | @@ -103,7 +103,7 @@ |---|---|---|---|---| | B-34 | 템플릿 패키지 규칙(ArchUnit): `FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES`, `TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES`. 템플릿 이름: application `usecase command query capability transaction security tenant observability secret messaging outbox idempotency operation lease lock cache realtime notification fileserver objectstorage`, domain `identifier stereotype` | 기능 패키지 이름이 이 목록과 겹치거나(예: `domain.lock`), 업무 코드를 템플릿 패키지(예: `application.usecase.*`)에 두고 기능 패키지를 import하면 `:app-bootstrap:architectureTest` 실패 | 기능 패키지 이름을 바꾸고, 업무 코드를 `dev.caskeleton.application.`로 옮긴다. 규칙 정본은 `src/application-core/CLAUDE.md` "Package ownership" | `5786126c` · `src/app-bootstrap/src/architectureTest/.../TemplatePackageOwnership.java` | | B-35 | JPA 규칙: 양방향 연관은 한쪽에서만 매핑(`mappedBy`), notification·fileserver 저장소 엔티티는 그 leaf 안에서만, `@Version` 엔티티의 bulk update는 version을 올려야 함 | 위반 엔티티·쿼리가 있으면 architectureTest 실패 | 매핑·쿼리를 고친다 | `34565130`, `1400dc15`, `bbe944bd` · `src/app-bootstrap/src/architectureTest/.../JpaProductionArchitectureTest.java` | -| B-36 | 빌드 검사 강화: `modules.json`에 없는 `build.gradle`이 있으면 `verifyCleanArchitectureDependencies` 실패. `verifyStrictLaneStages --dry-run`은 모든 strict lane이 workflow가 실행하는 단계(`:ci` `:sample-portfolio:check` `:mainCheck` `:integrationCheck` `:performanceCheck` `:releaseCheck`)에 속해야 하고 `.github/workflows`를 읽는다. 명령의 빌드는 `working-directory`(단계·job·workflow `defaults`)와 `-p`를 합친 디렉터리로 정하고, `workflow_dispatch`로만 시작하는 workflow의 명령은 세지 않으며, 축약한 `-x`도 Gradle처럼 맞춰 본다(RR2-04-04). 붙여 쓴 `-x`·`-p`도 Gradle처럼 읽는다(RR3-04-02). `verifyEnvKeys`: lane 계약 json의 `APP_` 밖 키는 `SPRING_`·`MANAGEMENT_`·`SERVER_`이거나 `secret://…/`가 가리키는 변수여야 하고, 레지스트리 `property:` 행은 그 property가 설정 metadata에 있어야 읽히는 것으로 친다(`@ConditionalOnProperty`로만 읽는 스위치는 `META-INF/additional-spring-configuration-metadata.json`에 선언, RR2-04-05). SpotBugs 신뢰도 HIGH → MEDIUM | 등록 안 한 leaf, 단계에 안 걸린 자기 lane, 자기 코드의 MEDIUM 발견이 `ci`·`qualityCheck`를 막는다. `working-directory: src` 없이 `./gradlew`를 부르는 자기 workflow 단계는 실행으로 세지 않는다 | leaf를 등록하거나 지운다. 자기 lane은 단계에 건다. 단계를 부르는 workflow 명령에 `working-directory`를 둔다. SpotBugs 발견은 고치거나 이유를 단 제외로 | `1400dc15`, `34565130`, `bbe944bd`, `5786126c` · `src/build-logic/.../ModuleRegistry.java`, `.../strictlane/StrictLaneStagesPlugin.java`, `.../quality/QualityConventionsPlugin.java`, `src/build.gradle` | +| B-36 | 빌드 검사 강화: `modules.json`에 없는 `build.gradle`이 있으면 `verifyCleanArchitectureDependencies` 실패. `verifyStrictLaneStages --dry-run`은 모든 strict lane이 workflow가 실행하는 단계(`:ci` `:sample-portfolio:check` `:mainCheck` `:integrationCheck` `:performanceCheck` `:releaseCheck`)에 속해야 하고 `.github/workflows`를 읽는다. 명령의 빌드는 `working-directory`(단계·job·workflow `defaults`)에서 시작해 같은 `run:` 셸이 그 앞에서 실행한 `cd <상대 경로>`(`cd src && ./gradlew …`, `cd src; ./gradlew …`, 앞 줄의 `cd src`)를 따라간 뒤 `-p`를 붙인 디렉터리로 정하고(2026-11-04 소유자 결정), `workflow_dispatch`로만 시작하는 workflow의 명령은 세지 않으며, 축약한 `-x`도 Gradle처럼 맞춰 본다(RR2-04-04). 붙여 쓴 `-x`·`-p`도 Gradle처럼 읽는다(RR3-04-02). `verifyEnvKeys`: lane 계약 json의 `APP_` 밖 키는 `SPRING_`·`MANAGEMENT_`·`SERVER_`이거나 `secret://…/`가 가리키는 변수여야 하고, 레지스트리 `property:` 행은 그 property가 설정 metadata에 있어야 읽히는 것으로 친다(`@ConditionalOnProperty`로만 읽는 스위치는 `META-INF/additional-spring-configuration-metadata.json`에 선언, RR2-04-05). SpotBugs 신뢰도 HIGH → MEDIUM | 등록 안 한 leaf, 단계에 안 걸린 자기 lane, 자기 코드의 MEDIUM 발견이 `ci`·`qualityCheck`를 막는다. `working-directory: src`도 `cd src`도 없이 `./gradlew`를 부르는 자기 workflow 단계는 실행으로 세지 않는다. 확실히 따라갈 수 없는 디렉터리 이동(`cd "$VAR"`, `cd -`, `cd ~`, 절대 경로, `pushd`, `if`/`for`/`case`·`{ }`·서브셸 안의 `cd`, `||`·`|`로 이은 `cd`, 다른 명령과 `&&`로 묶인 `cd` 다음 줄) 뒤의 명령도 세지 않고, 실패 메시지에 그 명령과 이유를 적는다 | leaf를 등록하거나 지운다. 자기 lane은 단계에 건다. 단계를 부르는 workflow 명령에 `working-directory`를 두거나 같은 셸에서 `cd <상대 경로>`로 옮긴 뒤 부른다. SpotBugs 발견은 고치거나 이유를 단 제외로 | `1400dc15`, `34565130`, `bbe944bd`, `5786126c`, 2026-11-04 소유자 결정 · `src/build-logic/.../ModuleRegistry.java`, `.../strictlane/StrictLaneStagesPlugin.java`, `.../strictlane/WorkflowGradleInvocations.java`, `.../quality/QualityConventionsPlugin.java`, `src/build.gradle` | | B-37 | app-bootstrap 테스트 lane 분리: 저장소 파일을 읽는 테스트는 태그 `document-contract`(main 단계) 또는 `repository-contract`(`check`)여야 하고, 일반 `test` lane에는 `ca.repository.root`가 없다 | app-bootstrap에 둔 자기 테스트가 저장소 파일을 읽으면 `test`에서 실패 | 태그를 단다 | `1400dc15` · `src/app-bootstrap/build.gradle` | | B-40 | 테스트 코드 정적 분석 `testQualityCheck`: SpotBugs·FindSecBugs를 main 밖 모든 source set(test, testFixtures, integrationTest, systemTest 등)에 돌린다. 테스트용 제외 목록은 `config/spotbugs/exclude-test.xml`(보안 범주·내부 상태 노출·생성자 예외·반환값 null 역참조·아키텍처 위반 fixture). 분석 classpath가 그 source set의 runtime classpath로 넓어졌고, 분석이 불완전하면(빠진 클래스) 실패한다. main 빌드는 `mainCheck`(`qualificationCheck`), optional 빌드는 `ci` | 자기 테스트 코드의 SpotBugs 발견(예: `CountDownLatch.await` 반환값 무시, 공유 변수 비원자 쓰기, 닫지 않은 `Statement`)이 main 단계를 막는다. 테스트 classpath에 없는 타입을 참조하면 `SpotBugs analysis incomplete` | 고치거나, 클래스·메서드로 좁힌 Match를 이유와 함께 `exclude-test.xml`에 더한다. 빠진 타입은 그 테스트 suite 의존성에 넣는다 | `2678955c` · `src/build-logic/.../quality/QualityConventionsPlugin.java`, `src/config/spotbugs/exclude-test.xml`, `src/build.gradle` | @@ -223,6 +223,7 @@ V21 실패의 분류는 `docs/runbooks/migration-failed.md` "Classify the failur | deprecated | `APP_CACHE_REDIS_TTL_JITTER`는 아무것도 바인딩하지 않음(`removal_deadline: 2027-02-28`) | 값이 아무 효과 없다 | `1400dc15` · `env-keys.yaml` | | HTTP client(JDK transport) | 스트리밍 응답의 read-idle 감시가 전용 데몬 스레드 하나(`httpclient-jdk-read-idle`)에서 돈다. 스트림마다 감시 작업 하나, 스트림을 닫으면 작업을 바로 취소 | 스레드 덤프에 그 스레드가 하나 보인다. 공용 `ForkJoinPool`이 바빠도 timeout이 설정값에 난다(전에는 늦게 났다). Apache transport(기본)는 영향 없음 | 3차 확인 리뷰 RR3-03-01 · `src/adapter/outbound/httpclient/.../jdk/ReadIdleInputStream.java` | | 멱등성 | `IDEMPOTENCY_RECOVERY_REQUIRED`를 내는 예외 메시지 끝에 scope digest가 붙는다. Redis 기록 조회(INSPECT 스크립트)가 `leaseUntil`을 돌려줘 `processingLeaseUntil`이 실제 lease 끝이다(전에는 key TTL 끝, 즉 lease + replay TTL) | 예외 메시지 전체에 맞추던 로그 매처는 고친다. 회복 절차는 `docs/runbooks/idempotency-unavailable.md`(digest로 기록을 찾는다) | 3차 확인 리뷰 RR3-03-03·05 · `src/application-core/.../idempotency/IdempotencyRecoveryRequiredException.java`, `src/adapter/outbound/cache-redis/.../idempotency/IdempotencyScripts.java` | +| 멱등성(lease가 지난 실행) | lease가 지난 `EXECUTING` 기록을 claim이 만나면 기록을 바꾸지 않고 500 `IDEMPOTENCY_RECOVERY_REQUIRED`로 답한다. 그 실행의 주인이 늦게 부른 `complete`·`markFailed`는 기록된다. 전에는 두 저장소 모두 기록을 `ABANDONED`로 바꿔(PostgreSQL은 `last_transition_kind` `EXPIRED_EXECUTION`) 늦은 결과를 거절했고 첫 요청도 500이었다. 이미 끝난 lease의 `renew`는 두 저장소 모두 거절한다(Redis는 전에 받아들였다). 남의 lease 지난 실행을 `inspect`하면 `ABANDONED`(전에는 `IN_PROGRESS_OTHER`) | 30s를 넘는 정상 요청이 이제 결과를 남기고 정상 응답을 받는다. 같은 키 재전송은 500을 받은 뒤 재생을 받을 수 있다. 직접 구현한 store는 `IdempotencyStoreContract`의 바뀐 시간 케이스로 확인한다. 운영자는 `EXECUTING` 기록을 지우지 않는다 — 살아 있는 실행의 늦은 결과가 기록을 못 찾아(`ABSENT`) 사라진다(`docs/runbooks/idempotency-unavailable.md`) | 2026-11-04 소유자 결정 · `src/application-core/src/testFixtures/.../IdempotencyStoreContract.java`, `src/adapter/outbound/cache-redis/.../idempotency/IdempotencyScripts.java`, `src/adapter/outbound/persistence-jpa/.../postgresql/PostgreSqlIdempotencyStore.java` | | sample-portfolio | 익명 쓰기 401, 포스터 제목 대소문자 무시 유일(409 `POSTER_ALREADY_EXISTS`), 관리자도 남의 work log 수정 불가, 샘플 이벤트 tenant `global` | sample을 남긴 서비스만 | `34565130`, `1400dc15` | ## 6. 따라오는 순서 diff --git a/docs/web/http-contract.md b/docs/web/http-contract.md index 50edc581..334786c8 100644 --- a/docs/web/http-contract.md +++ b/docs/web/http-contract.md @@ -110,7 +110,7 @@ status는 코드 표(`HttpStatusErrorCodes`)에 있는 것만 그대로 나간 | --- | --- | --- | --- | --- | --- | | 작업 실행 전(claim·시작 단계) 멱등성 저장소 응답 없음 | 503 | `IDEMPOTENCY_UNAVAILABLE` | `true` | 없음 | 작업은 실행되지 않았다. 같은 키로 나중에 다시 보낸다 | | 작업 실행 뒤 결과 기록(complete 단계) 중 저장소 응답 없음 — **결과 불명** | 503 | `IDEMPOTENCY_COMPLETION_UNKNOWN` | `true` | 없음 | "적용되지 않았다"고 알리지 않는다. **같은 키로** 나중에 다시 보낸다. 새 키 금지 | -| 이전 시도의 효과를 증명할 수 없음 | 500 | `IDEMPOTENCY_RECOVERY_REQUIRED` | `false` | 없음 | 재전송도 재실행도 안전하지 않다. 업무 데이터로 결과를 확인한다 | +| 이전 시도의 효과를 증명할 수 없음 | 500 | `IDEMPOTENCY_RECOVERY_REQUIRED` | `false` | 없음 | 자동 재시도하지 않는다. 결과는 업무 데이터로 확인한다. 같은 키로 나중에 다시 보내도 서버는 작업을 다시 돌리지 않는다 — 첫 시도가 늦게 끝났으면 그 결과를 재생하고, 아니면 다시 500이다. 새 키로 보내지 않는다 | - **결과 불명이 무엇을 뜻하나.** 작업은 이미 돌았다. 유스케이스가 executor를 쓰기 트랜잭션 안에서 불렀다면 그 트랜잭션의 DB 변경은 예외와 함께 롤백된다. 작업이 자기 트랜잭션을 따로 커밋했다면 그 변경은 @@ -118,23 +118,28 @@ status는 코드 표(`HttpStatusErrorCodes`)에 있는 것만 그대로 나간 503이어도 code가 다르다. 클라이언트는 status가 아니라 `error.code`로 가른다. - **같은 키로 다시 보내면 서버가 판정하고, 작업을 다시 돌리지 않는다.** 결과가 실제로는 기록됐으면 재생(첫 요청의 성공 응답), 첫 시도의 processing lease(`processing-lease`, 기본 30s)가 아직 남았으면 409 - `IDEMPOTENT_IN_FLIGHT`, lease가 지났으면 500 `IDEMPOTENCY_RECOVERY_REQUIRED`다. lease가 지난 실행 기록을 다음 - 요청이 만나면 두 저장소(PostgreSQL·Redis) 모두 넘겨주지 않고 포기(abandoned)로 표시한다 — 그 뒤 첫 시도가 - 늦게 끝나도 결과는 기록되지 않고 그 요청도 500을 받는다. 새 키로 보내면 서버는 다른 요청으로 보고 막지 못한다 - (재리뷰 2026-11-03 README 4절 결정 RR-02-03, 2026-11-04 9.1절 결정 RR-01-11). + `IDEMPOTENT_IN_FLIGHT`, lease가 지났으면 500 `IDEMPOTENCY_RECOVERY_REQUIRED`다. 새 키로 보내면 서버는 다른 + 요청으로 보고 막지 못한다(재리뷰 2026-11-03 README 4절 결정 RR-02-03, 2026-11-04 9.1절 결정 RR-01-11). +- **첫 시도가 lease보다 오래 걸려도 그 결과는 기록된다.** executor는 lease를 늘리지 않으므로 30s를 넘는 + 정상 요청도 lease가 지난다. lease가 지난 실행 기록을 다음 요청이 만나면 두 저장소(PostgreSQL·Redis) 모두 + 500으로 답하고 기록은 건드리지 않는다. 첫 시도가 그 뒤에 끝나면 결과가 그대로 기록되고, 첫 요청은 자기 + 응답을 정상으로 받는다. 그 뒤 같은 키 요청은 그 결과를 재생한다. 첫 시도가 실패를 보고하면 그 실패가 + 기록된다(효과 불명이면 계속 500, 효과 없는 재시도 가능 실패면 다음 같은 키 요청이 다시 실행한다). 기록이 + 이미 사라진 뒤에 끝나면 결과를 기록하지 못해 첫 요청도 500 `IDEMPOTENCY_RECOVERY_REQUIRED`를 받는다 + (2026-11-04 소유자 결정). - **서버가 기억하는 기간.** 위 판정은 기록이 남아 있는 동안만 선다. 기록이 사라지면 같은 키는 새 요청으로 실행된다. 기록의 수명은 시도가 어떻게 끝났는지로 갈린다. - 완료된 응답: 완료부터 `replay-ttl`(`APP_IDEMPOTENCY_TTL`, 기본 24h). - - 끝나지 않은 시도: claim부터 processing lease + `replay-ttl`. lease가 지나 다음 요청이 포기로 표시한 - 기록도 이 수명을 그대로 쓴다. + - 끝나지 않은 시도: claim부터 processing lease + `replay-ttl`. lease가 지난 실행 기록도 이 수명을 그대로 + 쓴다. 그 사이 첫 시도가 끝나면 그때부터 위(완료)나 아래(실패)의 수명으로 바뀐다. - 실패로 표시된 시도: 작업이 예외를 던졌거나 효과 불명으로 끝나 포기(abandoned)된 시도, 효과 없이 재시도 가능으로 끝난 시도. 표시한 때부터 `failure-retention`(`APP_IDEMPOTENCY_FAILURE_RETENTION`, 기본 24h). `replay-ttl`이 `processing-lease`보다 짧으면 기동이 실패한다(재리뷰 2026-11-04 RR-03-11). - `failure-retention`은 `replay-ttl`과 비교하지 않는다. 더 짧게 두면 효과 불명으로 포기한 기록이 그만큼 - 먼저 사라지고, 그 뒤 같은 키 재전송은 작업을 다시 돌린다. 그래서 `replay-ttl` 이상으로 둔다 - (재리뷰 2026-11-04 RR3-03-02). + `failure-retention`이 `replay-ttl`보다 짧아도 기동이 실패한다. 더 짧으면 효과 불명으로 포기한 기록이 그만큼 + 먼저 사라지고, 그 뒤 같은 키 재전송은 작업을 다시 돌린다(재리뷰 2026-11-04 RR3-03-02, 2026-11-04 소유자 + 결정). ## 3. 헤더 diff --git a/src/.env.example b/src/.env.example index a15941b3..25b09cca 100644 --- a/src/.env.example +++ b/src/.env.example @@ -128,7 +128,7 @@ APP_IDEMPOTENCY_TTL=24h APP_IDEMPOTENCY_PROVIDER=disabled APP_IDEMPOTENCY_REDIS_NAMESPACE_ENVIRONMENT=local APP_IDEMPOTENCY_PROCESSING_LEASE=30s -# Failure retention: at most 30d. Not checked against APP_IDEMPOTENCY_TTL; keep it at least that long. +# Failure retention: at most 30d and not shorter than APP_IDEMPOTENCY_TTL (startup fails). APP_IDEMPOTENCY_FAILURE_RETENTION=24h APP_LEASE_PROVIDER=disabled APP_LEASE_REDIS_NAMESPACE_ENVIRONMENT=local diff --git a/src/adapter/outbound/cache-redis/README.md b/src/adapter/outbound/cache-redis/README.md index da0bd2e8..623c297b 100644 --- a/src/adapter/outbound/cache-redis/README.md +++ b/src/adapter/outbound/cache-redis/README.md @@ -285,10 +285,14 @@ a different lease is `OPERATION_CONFLICT`. A lease that runs out is taken over only from a claim that never started or an attempt marked retryable. A record still `EXECUTING` when its lease ran out has an unknown effect: the claim -program marks it `ABANDONED` and answers `RECOVERY_REQUIRED`, and the late holder can no longer -complete it. The PostgreSQL store answers the same; the shared `IdempotencyStoreContract` holds both -to it on a real server (re-review 2026-11-04 RR-01-11 — this store used to take the record over and -run the work a second time). +program answers `RECOVERY_REQUIRED` and leaves the record as it is, because the holder may still be +running. The holder's late completion or failure goes through the transition program as it would +have inside the lease, and the next claim replays or retries it; only the lease is final — `RENEW` +refuses one that has run out, and `INSPECT` reports somebody else's expired execution as +`RECOVERY_REQUIRED`. The PostgreSQL store answers the same; the shared `IdempotencyStoreContract` +holds both to it on a real server (re-review 2026-11-04 RR-01-11 — this store used to take the +record over and run the work a second time; owner decision 2026-11-04 — both stores then abandoned +the record, and a holder that outlived its lease lost its result). The record key lives for the processing lease plus the replay TTL (`afterLease`, kept on the record), and a renewal stretches it to the new lease plus that margin. With the replay TTL alone, a replay diff --git a/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/IdempotencyScripts.java b/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/IdempotencyScripts.java index 43c967e3..bc4c6f4b 100644 --- a/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/IdempotencyScripts.java +++ b/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/IdempotencyScripts.java @@ -33,11 +33,14 @@ public final class IdempotencyScripts { * *

A lease that ran out is taken over only when nothing can have happened under it: a claim * that never started, or an attempt its holder marked retryable. A record that was {@code - * EXECUTING} has an unknown effect, so it is abandoned and answered {@code RECOVERY_REQUIRED} — - * running it again is the duplicate this store exists to prevent, and it is what a client - * resending after a result-unknown 503 was promised would not happen (re-review 2026-11-04 - * RR-01-11). The PostgreSQL store answers the same; {@code IdempotencyStoreContract} holds both - * to it. + * EXECUTING} has an unknown effect, so it is answered {@code RECOVERY_REQUIRED} — running it + * again is the duplicate this store exists to prevent, and it is what a client resending after a + * result-unknown 503 was promised would not happen (re-review 2026-11-04 RR-01-11). The answer + * changes nothing: the holder may still be running, and its late completion or failure is + * recorded by {@link #TRANSITION} as it would have been inside the lease, after which this + * program replays or retries it (owner decision 2026-11-04 — the record used to be abandoned + * here, so a holder that outlived its lease lost its result). The PostgreSQL store answers the + * same; {@code IdempotencyStoreContract} holds both to it. * *

The key lives for the lease plus the replay TTL ({@code afterLease}), not for the replay TTL * alone. With the replay TTL alone, a replay TTL shorter than the lease dropped the key while the @@ -87,11 +90,10 @@ public final class IdempotencyScripts { local leaseUntil = tonumber(redis.call('HGET', KEYS[1], 'leaseUntil')) local leaseOver = leaseUntil ~= nil and leaseUntil <= nowMillis if state == 'EXECUTING' and leaseOver then - -- The holder started and its lease ran out: whether the work took effect is unknown. - -- Abandon it, so the late holder cannot complete over the verdict, and keep the key's TTL: - -- the record stays as evidence for its remaining afterLease window. - redis.call('HSET', KEYS[1], 'state', 'ABANDONED', 'rev', rev + 1) - return {'RECOVERY_REQUIRED', attempt, rev + 1, owner, '', ''} + -- The holder started and its lease ran out: whether the work took effect is unknown, so it + -- is never run again. The record is left as it is — owner, revision, key TTL — because the + -- holder may still finish and record its result. + return {'RECOVERY_REQUIRED', attempt, rev, owner, '', ''} end if state == 'FAILED_RETRYABLE' or (state == 'CLAIMED' and leaseOver) then -- Nothing ran under the previous holder: they never started, or they marked the attempt @@ -174,6 +176,11 @@ public final class IdempotencyScripts { * 2026-11-03 RR-04-08, re-review 2026-11-04 RR-03-11). A record claimed before {@code afterLease} * existed has none and keeps only the lease. The TTL is only ever lengthened here — completion * sets the replay TTL again. + * + *

A lease that has already run out is not renewed: a resend may have been told "recovery + * required" since, and a lease brought back would answer the next one "in progress" for the same + * unknown effect. The holder can still complete or fail the record. The PostgreSQL store refuses + * the same renewal ({@code IdempotencyStoreContract}, owner decision 2026-11-04). */ private static final String RENEW = """ @@ -207,6 +214,10 @@ public final class IdempotencyScripts { end local t = redis.call('TIME') local nowMillis = (tonumber(t[1]) * 1000) + math.floor(tonumber(t[2]) / 1000) + local leaseUntil = tonumber(redis.call('HGET', KEYS[1], 'leaseUntil')) + if leaseUntil ~= nil and leaseUntil <= nowMillis then + return {'NOT_OWNER', attempt, rev, owner, '', ''} + end redis.call('HSET', KEYS[1], 'leaseUntil', nowMillis + tonumber(ARGV[4]), 'rev', rev + 1, 'renewedFromRev', ARGV[2], 'renewedLease', ARGV[4]) @@ -250,6 +261,11 @@ public final class IdempotencyScripts { * its key's TTL; an in-progress record's lease is not, because its key lives for the lease plus * {@code afterLease} — reading the lease off the TTL reported it a replay TTL too late (re-review * 2026-11-04 RR3-03-05). + * + *

The status is the record's state, with one exception: somebody else's {@code EXECUTING} + * record whose lease ran out is reported {@code RECOVERY_REQUIRED}, the answer {@link #CLAIM} + * gives it, judged by the same server clock. Its holder still sees its own execution (owner + * decision 2026-11-04). */ private static final String INSPECT = """ @@ -273,7 +289,16 @@ public final class IdempotencyScripts { mine = 'OPERATION_CONFLICT' end end - return {state, attempt, rev, owner, + local verdict = state + if state == 'EXECUTING' and mine == 'OTHER' then + local t = redis.call('TIME') + local nowMillis = (tonumber(t[1]) * 1000) + math.floor(tonumber(t[2]) / 1000) + local leaseUntil = tonumber(redis.call('HGET', KEYS[1], 'leaseUntil')) + if leaseUntil ~= nil and leaseUntil <= nowMillis then + verdict = 'RECOVERY_REQUIRED' + end + end + return {verdict, attempt, rev, owner, redis.call('HGET', KEYS[1], 'resp') or '', mine .. '|' .. tostring(redis.call('PTTL', KEYS[1])) .. '|' .. (redis.call('HGET', KEYS[1], 'leaseUntil') or '')} @@ -323,9 +348,10 @@ public final class IdempotencyScripts { /** * What a program answered, parsed once. * - *

The transition verdicts and, for {@code INSPECT}, the record's state. The programs speak in - * strings; the adapter speaks in this enum, so a misspelt status is a compile error rather than a - * {@code default} branch that quietly turns it into "unavailable". + *

The transition verdicts and, for {@code INSPECT}, the record's state (or {@code + * RECOVERY_REQUIRED}, see {@link #INSPECT}). The programs speak in strings; the adapter speaks in + * this enum, so a misspelt status is a compile error rather than a {@code default} branch that + * quietly turns it into "unavailable". */ enum ScriptStatus { ACQUIRED, diff --git a/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/RedisIdempotencyStoreAdapter.java b/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/RedisIdempotencyStoreAdapter.java index 65249e1f..606f4f26 100644 --- a/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/RedisIdempotencyStoreAdapter.java +++ b/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/RedisIdempotencyStoreAdapter.java @@ -391,7 +391,10 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort Optional.of(now.plusMillis(Math.max(1, ttlMillis)))); case FAILED_RETRYABLE -> IdempotencyInspection.outcome(IdempotencyInspectionOutcome.FAILED_RETRYABLE); - case ABANDONED -> IdempotencyInspection.outcome(IdempotencyInspectionOutcome.ABANDONED); + // Abandoned by its holder, or somebody else's execution whose lease ran out (INSPECT reports + // that one RECOVERY_REQUIRED, as CLAIM answers it): either way nobody may run it again. + case ABANDONED, RECOVERY_REQUIRED -> + IdempotencyInspection.outcome(IdempotencyInspectionOutcome.ABANDONED); case CLAIMED -> "MINE".equals(ownership) ? new IdempotencyInspection( diff --git a/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/RedisIdempotencyStoreAdapterTest.java b/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/RedisIdempotencyStoreAdapterTest.java index 7b992580..13c584e0 100644 --- a/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/RedisIdempotencyStoreAdapterTest.java +++ b/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/RedisIdempotencyStoreAdapterTest.java @@ -353,8 +353,8 @@ class RedisIdempotencyStoreAdapterTest { } @Test - @DisplayName("lease가 지나 다른 요청이 회복 필요로 판정한 실행은 이전 owner가 renew할 수 없다") - void anOwnerWhoseExpiredExecutionWasAbandonedCannotRenew() { + @DisplayName("lease가 지나 다른 요청이 회복 필요로 판정한 실행은 주인이 renew로 lease를 되살릴 수 없다") + void anOwnerWhoseExecutionWasFoundExpiredCannotRenewItsLease() { // given IdempotencyOwner executing = executing(); gateway.advance(Duration.ofSeconds(60)); @@ -386,6 +386,44 @@ class RedisIdempotencyStoreAdapterTest { recovery -> assertThat(recovery.currentAttempt()).isEqualTo(executing.attempt())); } + @Test + @DisplayName("lease가 지난 실행을 주인이 늦게 complete하면 기록되고 다음 claim은 그 결과를 재생한다") + void aLateCompletionOfAnExpiredExecutionIsRecordedAndReplayed() { + // given + // The live contract proves the programs; this proves the fixture's copy of CLAIM leaves the + // record to its holder as the program does (owner decision 2026-11-04). + IdempotencyOwner late = executing(); + gateway.advance(Duration.ofSeconds(60)); + store.claim(claim(store.newClaimAttempt(OTHER_OPERATION))); + store.complete(late, new StoredResponse("{\"late\":true}"), Duration.ofHours(1), OPERATION); + + // when + IdempotencyClaimOutcome next = store.claim(claim(store.newClaimAttempt(OTHER_OPERATION))); + + // then + assertThat(next) + .isInstanceOfSatisfying( + IdempotencyClaimOutcome.CompletedReplay.class, + replay -> assertThat(replay.response().payload()).isEqualTo("{\"late\":true}")); + } + + @Test + @DisplayName("lease가 지난 남의 실행을 inspect하면 회복 필요(ABANDONED)로 보고한다") + void inspectingAnotherHoldersExpiredExecutionReportsAbandoned() { + // given + executing(); + gateway.advance(Duration.ofSeconds(60)); + + // when + var inspection = + store.inspect( + new IdempotencyInspectionRequest( + SCOPE, FINGERPRINT, store.newClaimAttempt(OTHER_OPERATION))); + + // then + assertThat(inspection.outcome()).isEqualTo(IdempotencyInspectionOutcome.ABANDONED); + } + @Test @DisplayName("an expired claim that never started can be taken over, and the attempt increments") void anExpiredLeaseIsTakenOver() { diff --git a/src/adapter/outbound/persistence-jpa/README.md b/src/adapter/outbound/persistence-jpa/README.md index 36cdf9e0..01755f23 100644 --- a/src/adapter/outbound/persistence-jpa/README.md +++ b/src/adapter/outbound/persistence-jpa/README.md @@ -233,8 +233,11 @@ failure translation contract 다. 여기서는 SPI 구조와 fallback 근거만 지운다. 그래서 `expires_at` 이 lease 보다 먼저 오면 실행 중인 행이 지워지고 다음 claim 이 같은 작업을 다시 돌린다(재리뷰 2026-11-04 RR-03-11). 공유 계약의 PostgreSQL lane 은 시간을 흘린 뒤 이 reaper 를 실제로 돌려 이 경우를 본다. reaper 는 provider 가 `postgresql` 일 때만 돈다. -- **lease 가 지난 실행**: lease 가 지난 `EXECUTING` 행은 넘겨받지 않고 `ABANDONED` 로 바꿔 - `RecoveryRequired` 로 답한다. Redis store 도 같다(`IdempotencyStoreContract`, RR-01-11). +- **lease 가 지난 실행**: lease 가 지난 `EXECUTING` 행은 넘겨받지 않고 `RecoveryRequired` 로 답하며, + 행은 바꾸지 않는다. 주인이 늦게 complete·markFailed 하면 그대로 기록되고, 다음 claim 은 그 결과를 + 재생하거나 재시도한다. renew 는 이미 끝난 lease 를 늘리지 않는다. inspect 는 남의 lease 지난 실행을 + `ABANDONED` 로 보고한다. Redis store 도 같다(`IdempotencyStoreContract`, RR-01-11, 2026-11-04 소유자 + 결정 — 전에는 행을 `ABANDONED`·`EXPIRED_EXECUTION` 으로 바꿔 늦은 결과를 버렸다). ## outbox — `JpaOutboxStore` 외 diff --git a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/idempotency/postgresql/IdempotencyClaimGateway.java b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/idempotency/postgresql/IdempotencyClaimGateway.java index e2d882d4..bae3b7b3 100644 --- a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/idempotency/postgresql/IdempotencyClaimGateway.java +++ b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/idempotency/postgresql/IdempotencyClaimGateway.java @@ -6,12 +6,14 @@ import java.util.UUID; import org.springframework.jdbc.core.JdbcOperations; /** - * The three statements that decide who owns a scope. + * The two statements that decide who owns a scope. * - *

Claiming is a different problem from advancing a claim already held. These three write the - * owner tuple itself — first insert, take-over, and the abandonment of an execution whose lease ran - * out — and every one of them is a race between processes. The transitions in {@link - * IdempotencyTransitionGateway} are races only against the owner's own retries. + *

Claiming is a different problem from advancing a claim already held. These two write the owner + * tuple itself — first insert and take-over — and both are races between processes. The transitions + * in {@link IdempotencyTransitionGateway} are races only against the owner's own retries. An + * execution whose lease ran out is not written here at all: the claim answers "recovery required" + * and leaves the row to its holder (owner decision 2026-11-04 removed the statement that abandoned + * it). * *

The insert is {@code on conflict ... do nothing}, so a concurrent second claimer gets zero * rows back rather than an exception. That matters: a unique-violation would abort the caller's @@ -92,25 +94,6 @@ final class IdempotencyClaimGateway { and state_revision = ? """; - private static final String ABANDON_EXPIRED_EXECUTION_SQL = - """ - update idempotency_record - set status = 'ABANDONED', - state_revision = state_revision + 1, - last_transition_operation_id = claim_operation_id, - last_transition_kind = 'EXPIRED_EXECUTION', - last_transition_result_digest = ?, - failure_disposition = 'EFFECT_UNKNOWN_ABANDONED', - updated_at = clock_timestamp() - where scope_hash = ? - and record_version = 2 - and status = 'EXECUTING' - and owner_token = ? - and attempt = ? - and claim_operation_id = ? - and state_revision = ? - """; - private final JdbcOperations jdbc; IdempotencyClaimGateway(JdbcOperations jdbc) { @@ -173,20 +156,4 @@ final class IdempotencyClaimGateway { static long recordLifetimeMillis(IdempotencyClaimRequest request) { return request.processingLeaseTtl().plus(request.replayTtl()).toMillis(); } - - /** - * Abandons an execution whose lease expired, repeating the whole owner tuple. - * - * @return {@code 1} when the expired owner was still the recorded one, {@code 0} otherwise - */ - int abandonExpiredExecution(IdempotencyRecordRow row, String resultDigest) { - return jdbc.update( - ABANDON_EXPIRED_EXECUTION_SQL, - resultDigest, - row.scopeHash(), - row.ownerToken(), - row.attempt(), - row.claimOperationId(), - row.stateRevision()); - } } diff --git a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/idempotency/postgresql/IdempotencyTransitionGateway.java b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/idempotency/postgresql/IdempotencyTransitionGateway.java index af8f021e..33282cb7 100644 --- a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/idempotency/postgresql/IdempotencyTransitionGateway.java +++ b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/idempotency/postgresql/IdempotencyTransitionGateway.java @@ -45,6 +45,11 @@ final class IdempotencyTransitionGateway { * the row as it was before this update. Without the move a lease renewed past {@code expires_at} * let the reaper delete a running operation's row (re-review 2026-11-04 RR-03-11); a row claimed * before the margin existed keeps at least its new lease. + * + *

A lease that has already run out is not renewed ({@code processing_lease_until > + * clock_timestamp()}): a resend may have been answered "recovery required" since. The holder can + * still complete or fail the row — those statements do not read the lease. The Redis store + * refuses the same renewal ({@code IdempotencyStoreContract}, owner decision 2026-11-04). */ private static final String RENEW_SQL = """ diff --git a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/idempotency/postgresql/PostgreSqlIdempotencyStore.java b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/idempotency/postgresql/PostgreSqlIdempotencyStore.java index 846aa9be..1119663f 100644 --- a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/idempotency/postgresql/PostgreSqlIdempotencyStore.java +++ b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/idempotency/postgresql/PostgreSqlIdempotencyStore.java @@ -38,7 +38,7 @@ import org.springframework.jdbc.core.JdbcOperations; * *

What is left here is the port and the decisions the port's outcomes encode: which state a row * is in, whether this caller still owns it, whether the request is a replay of a transition already - * applied, and which outcome each of those answers produces. The SQL that reads a row, the three + * applied, and which outcome each of those answers produces. The SQL that reads a row, the two * statements that decide ownership, the five that advance it, the digest composition and the * preconditions are each a collaborator of their own. That split is not cosmetic — this class held * all of them, so changing one transition's SQL meant editing the same file as the row mapper and @@ -150,8 +150,11 @@ public final class PostgreSqlIdempotencyStore implements IdempotencyStorePort { if (row.state() == IdempotencyState.FAILED_RETRYABLE) { return resetClaim(request, row); } - if (row.state() == IdempotencyState.EXECUTING && !dbNow.isBefore(row.processingLeaseUntil())) { - abandonExpiredExecution(row); + // An execution whose lease ran out has an unknown effect, so it is never run again — and the + // row is not touched: its holder may still finish, and its completion or failure is recorded as + // it would have been inside the lease (owner decision 2026-11-04; the row used to be abandoned + // here, so a holder that outlived its lease lost its result and its request got a 500). + if (isExpiredExecution(row, dbNow)) { return new IdempotencyClaimOutcome.RecoveryRequired(row.attempt()); } if (row.state() == IdempotencyState.ABANDONED) { @@ -415,6 +418,12 @@ public final class PostgreSqlIdempotencyStore implements IdempotencyStorePort { if (row.ownerToken().equals(request.claimAttempt().ownerToken()) && !sameAttempt) { return IdempotencyInspection.outcome(IdempotencyInspectionOutcome.OPERATION_CONFLICT); } + // Somebody else's execution whose lease ran out is reported as a claim would answer it. The + // database's clock decides, as it does for the claim; the read takes no lock, so a lease that + // ends between the row and the clock is reported as ended, which is what a claim would see. + if (row.state() == IdempotencyState.EXECUTING && isExpiredExecution(row, rows.databaseNow())) { + return IdempotencyInspection.outcome(IdempotencyInspectionOutcome.ABANDONED); + } return switch (row.state()) { case FAILED_RETRYABLE -> IdempotencyInspection.outcome(IdempotencyInspectionOutcome.FAILED_RETRYABLE); @@ -433,13 +442,6 @@ public final class PostgreSqlIdempotencyStore implements IdempotencyStorePort { return new IdempotencyClaimOutcome.TakenOverClaimed(owner(reset), reset.processingLeaseUntil()); } - private void abandonExpiredExecution(IdempotencyRecordRow row) { - String resultDigest = sha256("EXPIRED_EXECUTION|" + row.claimOperationId()); - if (claims.abandonExpiredExecution(row, resultDigest) != 1) { - throw indeterminateClaim(); - } - } - // A handle at an older revision is a stale owner tuple, so it is NOT_OWNER — what the Redis store // and the in-memory fake answer (IdempotencyStoreContract). OPERATION_CONFLICT keeps its one // meaning: the same operation id already applied this transition with different arguments. @@ -586,6 +588,10 @@ public final class PostgreSqlIdempotencyStore implements IdempotencyStorePort { DIFFERENT_ARGUMENTS } + private static boolean isExpiredExecution(IdempotencyRecordRow row, Instant dbNow) { + return row.state() == IdempotencyState.EXECUTING && !dbNow.isBefore(row.processingLeaseUntil()); + } + private static boolean isExpiredCompleted(IdempotencyRecordRow row, Instant dbNow) { return row.state() == IdempotencyState.COMPLETED && row.replayUntil() != null diff --git a/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlIdempotencyIntegrationTest.java b/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlIdempotencyIntegrationTest.java index 64057dae..e0e861c7 100644 --- a/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlIdempotencyIntegrationTest.java +++ b/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlIdempotencyIntegrationTest.java @@ -189,9 +189,11 @@ class PostgreSqlIdempotencyIntegrationTest { .isInstanceOfSatisfying( IdempotencyClaimOutcome.RecoveryRequired.class, recovery -> assertThat(recovery.currentAttempt()).isEqualTo(executing.attempt())); - assertThat( - store.inspect(new IdempotencyInspectionRequest(SCOPE, FINGERPRINT, original)).outcome()) - .isEqualTo(IdempotencyInspectionOutcome.ABANDONED); + // The claim leaves the row to its holder, which may still finish and record its result (owner + // decision 2026-11-04): the holder still finds its own execution, unchanged. + var holder = store.inspect(new IdempotencyInspectionRequest(SCOPE, FINGERPRINT, original)); + assertThat(holder.outcome()).isEqualTo(IdempotencyInspectionOutcome.EXECUTING_SAME_OPERATION); + assertThat(holder.owner()).contains(executing); } @Test diff --git a/src/adapter/outbound/redis-runtime/src/testFixtures/java/dev/caskeleton/adapter/outbound/cache/redis/runtime/command/InMemorySemanticRedisCommands.java b/src/adapter/outbound/redis-runtime/src/testFixtures/java/dev/caskeleton/adapter/outbound/cache/redis/runtime/command/InMemorySemanticRedisCommands.java index dad2ac5d..f100ccbb 100644 --- a/src/adapter/outbound/redis-runtime/src/testFixtures/java/dev/caskeleton/adapter/outbound/cache/redis/runtime/command/InMemorySemanticRedisCommands.java +++ b/src/adapter/outbound/redis-runtime/src/testFixtures/java/dev/caskeleton/adapter/outbound/cache/redis/runtime/command/InMemorySemanticRedisCommands.java @@ -224,12 +224,11 @@ public final class InMemorySemanticRedisCommands implements SemanticRedisCommand } long leaseUntil = Long.parseLong(field(rendered, "leaseUntil")); boolean leaseOver = leaseUntil <= nowMillis; - // As the program: an expired EXECUTING record has an unknown effect, so it is abandoned and - // answered RECOVERY_REQUIRED, never taken over (re-review 2026-11-04 RR-01-11). + // As the program: an expired EXECUTING record has an unknown effect, so it is answered + // RECOVERY_REQUIRED, never taken over (re-review 2026-11-04 RR-01-11), and left to its holder, + // whose late completion is still recorded (owner decision 2026-11-04). if ("EXECUTING".equals(state) && leaseOver) { - setField(rendered, "state", "ABANDONED"); - setField(rendered, "rev", Long.toString(rev + 1)); - return reply("RECOVERY_REQUIRED", attempt, rev + 1, owner, "", ""); + return reply("RECOVERY_REQUIRED", attempt, rev, owner, "", ""); } if ("FAILED_RETRYABLE".equals(state) || ("CLAIMED".equals(state) && leaseOver)) { setField(rendered, "state", "CLAIMED"); @@ -322,6 +321,10 @@ public final class InMemorySemanticRedisCommands implements SemanticRedisCommand if (!"EXECUTING".equals(state)) { return reply("WRONG_STATE", attempt, rev, owner, state, ""); } + // As the program: a lease that already ran out is not brought back. + if (Long.parseLong(field(rendered, "leaseUntil")) <= now()) { + return reply("NOT_OWNER", attempt, rev, owner, "", ""); + } setField(rendered, "leaseUntil", Long.toString(now() + Long.parseLong(leaseMillis))); setField(rendered, "rev", Long.toString(rev + 1)); setField(rendered, "renewedFromRev", handleRevision); @@ -372,8 +375,15 @@ public final class InMemorySemanticRedisCommands implements SemanticRedisCommand } String stored = field(rendered, "resp"); String leaseUntil = field(rendered, "leaseUntil"); + // As the program: somebody else's execution whose lease ran out is reported as CLAIM answers + // it. + boolean expiredExecution = + "EXECUTING".equals(state) + && "OTHER".equals(mine) + && leaseUntil != null + && Long.parseLong(leaseUntil) <= now(); return reply( - state, + expiredExecution ? "RECOVERY_REQUIRED" : state, attempt, rev, owner, diff --git a/src/application-core/CLAUDE.md b/src/application-core/CLAUDE.md index 9650df5c..010918a1 100644 --- a/src/application-core/CLAUDE.md +++ b/src/application-core/CLAUDE.md @@ -263,15 +263,17 @@ generation; the V1 `IdempotencyScope`/`tryBegin` API is gone. `persistence-jpa`; default `disabled`). In-memory prod storage is forbidden. - **Executor**: built once by `composition:idempotency` `IdempotencyAutoConfiguration` from `IdempotencySettings` (processing lease 30s, replay TTL `APP_IDEMPOTENCY_TTL` 24h ≤72h and not - shorter than the lease, failure retention 24h). Do not construct it in a use case or a sample config. + shorter than the lease, failure retention 24h and not shorter than the replay TTL). Do not + construct it in a use case or a sample config. - The action returns `IdempotentAction.Outcome` (`Success` / `RetryableNoEffect` / `EffectUnknown`); a thrown exception counts as effect-unknown. In progress → 409 `IDEMPOTENT_IN_FLIGHT`, fingerprint mismatch (SHA-256) → 422 `IDEMPOTENT_REQUEST_MISMATCH`; `IdempotencyUnavailableException` and `IdempotencyRecoveryRequiredException` mean the store could not prove the outcome, so do not blindly retry. - Every store answers an execution whose processing lease ran out with `RecoveryRequired` and never - takes it over; only a claim that never started or a retryable failure is taken over. A record lives - for the lease plus the replay TTL. `IdempotencyStoreContract` holds Redis and PostgreSQL to both on + takes it over; only a claim that never started or a retryable failure is taken over. The answer + leaves the record to its holder: the holder's late `complete`/`markFailed` is recorded, a lease that + ran out is not renewed (owner decision 2026-11-04). A record lives for the lease plus the replay TTL. `IdempotencyStoreContract` holds Redis and PostgreSQL to both on real servers; the in-memory fake models no time, so it runs only the contract's time-free cases (re-review 2026-11-04 RR-01-11, RR-03-11, RR3-03-04). diff --git a/src/application-core/README.md b/src/application-core/README.md index 1c084877..261e2582 100644 --- a/src/application-core/README.md +++ b/src/application-core/README.md @@ -268,9 +268,10 @@ application 계층이 claim·replay·복구 **정책** 을 소유하고, 저장 실패로 기록하고, `EffectUnknown` 이나 그냥 던진 예외는 "효과 불명"(`ABANDONED`)으로 남긴다. 한 번 실행됐을지 모르는 작업을 재시도로 두 번 돌리지 않기 위해서다. - processing lease 와 replay TTL 은 따로 간다. 만료된 `CLAIMED` 만 다른 caller 가 가져갈 수 있고, - 만료된 `EXECUTING` 은 `RECOVERY_REQUIRED` 로 닫는다. + 만료된 `EXECUTING` 은 다른 caller 에게 `RECOVERY_REQUIRED` 로 답하되 기록은 그대로 둔다. 주인이 늦게 + 보고한 결과·실패는 기록된다(2026-11-04 소유자 결정). - 생성은 app-bootstrap `IdempotencyProviderSelectionConfig` 가 한 번 한다(`IdempotencySettings`: - processing lease 30s, replay TTL 24h(최대 72h), failure retention 24h, codec id `json-v2`, + processing lease 30s, replay TTL 24h(최대 72h), failure retention 24h(replay TTL 이상), codec id `json-v2`, policy revision 2). 유스케이스나 샘플 설정이 직접 만들지 않는다. - 이 계약은 요청 재생(replay) 근거를 남길 뿐이다. store 와 비즈니스 DB 사이의 exactly-once 를 보장하지 않는다. diff --git a/src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyClaimOutcome.java b/src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyClaimOutcome.java index 64eb0246..13b86eb1 100644 --- a/src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyClaimOutcome.java +++ b/src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyClaimOutcome.java @@ -61,6 +61,10 @@ public sealed interface IdempotencyClaimOutcome { * An earlier attempt may have taken effect and nobody can say whether it did: it was marked * abandoned with an unknown effect, or its processing lease ran out while it was executing. The * action must not run again under this key; the outcome is settled from business data. + * + *

For an execution whose lease ran out the answer changes nothing in the store. Its holder may + * still finish: its completion is then recorded and a later claim replays it, and a failure it + * reports is recorded the same way (owner decision 2026-11-04). */ record RecoveryRequired(long currentAttempt) implements IdempotencyClaimOutcome { public RecoveryRequired { diff --git a/src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyExecutor.java b/src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyExecutor.java index 95ebeab5..c6f364b1 100644 --- a/src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyExecutor.java +++ b/src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyExecutor.java @@ -8,6 +8,12 @@ import java.util.Optional; /** * Owner-safe request-replay lifecycle over {@link IdempotencyStorePort}. * + *

The executor does not renew the processing lease, so an action may outlive it. That changes + * what a same-key resend is told — "recovery required" instead of "in flight" — and nothing about + * this call: the store still records its result or its failure, the caller gets its answer, and a + * later resend replays the result (owner decision 2026-11-04). A result that arrives after the + * record's whole lifetime finds no record and is reported as recovery required. + * *

This contract threads the owner handle through every mutation: a confirmed transition returns * the owner with its state revision advanced, and the next call must present that handle. * Re-using the claim's original owner would present a stale revision, which the store is built to @@ -47,7 +53,9 @@ public final class IdempotencyExecutor { * Creates the executor. * * @param store the owner-safe store - * @param processingLeaseTtl how long a claim holds the record before another caller may take over + * @param processingLeaseTtl how long a claim holds the record: after it, a claim that never + * started may be taken over and an execution is answered "recovery required" to anyone else, + * while this executor's own result for it is still recorded * @param replayTtl how long a completed response is replayable * @param failureRetention how long a failed attempt's evidence is kept * @param responseCodecId the identifier of the codec the stored payload was written with @@ -135,7 +143,9 @@ public final class IdempotencyExecutor { startAndRun(request, replayed.owner(), action, codec, false); // Only a claim that never started or failed without effect is taken over, so running here is // the first run that can have an effect. An execution whose lease ran out is not: the store - // answers RecoveryRequired for it above (IdempotencyStoreContract, RR-01-11). + // answers RecoveryRequired for it above and leaves it to its holder + // (IdempotencyStoreContract, + // RR-01-11, owner decision 2026-11-04). case IdempotencyClaimOutcome.TakenOverClaimed takenOver -> startAndRun(request, takenOver.owner(), action, codec, false); }; diff --git a/src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyInspectionOutcome.java b/src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyInspectionOutcome.java index 7b23f7e0..b8ed05d6 100644 --- a/src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyInspectionOutcome.java +++ b/src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyInspectionOutcome.java @@ -8,6 +8,12 @@ public enum IdempotencyInspectionOutcome { COMPLETED_REPLAY, IN_PROGRESS_OTHER, FAILED_RETRYABLE, + /** + * Nobody may run the operation again and its effect is unknown: the record was marked abandoned, + * or it is somebody else's execution whose processing lease ran out — what a claim answers with + * {@link IdempotencyClaimOutcome.RecoveryRequired}. The holder of that execution inspects it as + * {@link #EXECUTING_SAME_OPERATION} and can still complete it (owner decision 2026-11-04). + */ ABANDONED, FINGERPRINT_MISMATCH, OPERATION_CONFLICT, diff --git a/src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyStorePort.java b/src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyStorePort.java index 0f2be4bf..1e933997 100644 --- a/src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyStorePort.java +++ b/src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyStorePort.java @@ -8,6 +8,15 @@ import java.time.Duration; * *

Providers (Redis, PostgreSQL) contribute only this store; the {@link IdempotencyExecutor} that * drives it is assembled once by the composition root. + * + *

The processing lease decides only what other callers are told. A claim whose lease + * ran out before it started is taken over; an execution whose lease ran out is answered {@link + * IdempotencyClaimOutcome.RecoveryRequired} and left exactly as it is, because its holder may still + * be running. The holder's {@link #complete} and {@link #markFailed} are recorded whether or not + * the lease has run out — the holder's last report is the one the record keeps — while {@link + * #renew} refuses a lease that has already ended. Only the record's own lifetime ends it: once it + * is gone, every call answers {@code ABSENT} (owner decision 2026-11-04; {@code + * IdempotencyStoreContract}). */ public interface IdempotencyStorePort { diff --git a/src/application-core/src/testFixtures/java/dev/caskeleton/application/idempotency/testkit/IdempotencyStoreContract.java b/src/application-core/src/testFixtures/java/dev/caskeleton/application/idempotency/testkit/IdempotencyStoreContract.java index 319259a9..a9ddbb9e 100644 --- a/src/application-core/src/testFixtures/java/dev/caskeleton/application/idempotency/testkit/IdempotencyStoreContract.java +++ b/src/application-core/src/testFixtures/java/dev/caskeleton/application/idempotency/testkit/IdempotencyStoreContract.java @@ -43,6 +43,12 @@ import org.junit.jupiter.api.Test; * is unknown, and a client resending the same key after a result-unknown 503 was told exactly * that (re-review 2026-11-04 RR-01-11 — the Redis store took it over and ran it a second * time, the PostgreSQL store did not); + *

  • that answer leaves the record as it is. The execution may still be running, so its holder + * can still record its result or its failure, and the next claim then replays or retries + * accordingly; only the lease is final — the holder cannot renew it back, and an inspection + * by anyone else reports what a claim would answer (owner decision 2026-11-04: both stores + * used to abandon the record, so a first request that outlived the lease got a 500 for work + * that took effect, and its result was lost); *
  • a record outlives its processing lease by the replay TTL, whatever the two are set to. A * record that expired first — Redis at its key TTL, PostgreSQL at the reaper — let the next * claim of a running operation acquire it fresh (re-review 2026-11-04 RR-03-11), and one that @@ -485,8 +491,31 @@ public abstract class IdempotencyStoreContract { } @Test - @DisplayName("lease가 지나 회복 필요로 판정된 실행은 원래 holder가 늦게 complete해도 기록되지 않는다") - void anExecutionFoundExpiredCannotBeCompletedByItsLateHolder() { + @DisplayName("lease가 지난 실행을 만난 claim은 회복 필요로 답하고 기록은 실행 중인 주인의 것으로 그대로 둔다") + void aClaimMeetingAnExpiredExecutionLeavesTheRecordToItsHolder() { + // given + IdempotencyStorePort store = subject(); + Duration lease = processingLease(); + IdempotencyClaimAttempt original = store.newClaimAttempt(OPERATION); + IdempotencyOwner claimed = ownerOf(store.claim(claim(original, FINGERPRINT, lease))); + IdempotencyOwner late = store.markExecutionStarted(claimed, OPERATION).owner().orElseThrow(); + elapse(lease.multipliedBy(2)); + + // when + IdempotencyClaimOutcome resent = + store.claim(claim(store.newClaimAttempt(OTHER_OPERATION), FINGERPRINT, lease)); + + // then + assertThat(resent).isInstanceOf(IdempotencyClaimOutcome.RecoveryRequired.class); + IdempotencyInspection holder = + store.inspect(new IdempotencyInspectionRequest(SCOPE, FINGERPRINT, original)); + assertThat(holder.outcome()).isEqualTo(IdempotencyInspectionOutcome.EXECUTING_SAME_OPERATION); + assertThat(holder.owner()).contains(late); + } + + @Test + @DisplayName("lease가 지난 실행도 주인이 늦게 complete하면 완료로 기록된다") + void anExpiredExecutionIsStillCompletedByItsHolder() { // given IdempotencyStorePort store = subject(); Duration lease = processingLease(); @@ -499,7 +528,92 @@ public abstract class IdempotencyStoreContract { store.complete(late, new StoredResponse("{}"), Duration.ofHours(1), OPERATION); // then - assertThat(outcome).isEqualTo(IdempotencyCompleteOutcome.NOT_OWNER); + assertThat(outcome).isEqualTo(IdempotencyCompleteOutcome.COMPLETED); + } + + @Test + @DisplayName("lease가 지난 뒤 주인이 늦게 기록한 결과는 다음 claim에 재생된다") + void aLateCompletionReplaysToTheNextClaim() { + // given + IdempotencyStorePort store = subject(); + Duration lease = processingLease(); + IdempotencyOwner late = executingWith(store, lease, Duration.ofHours(24)); + elapse(lease.multipliedBy(2)); + store.claim(claim(store.newClaimAttempt(OTHER_OPERATION), FINGERPRINT, lease)); + store.complete(late, new StoredResponse("{\"late\":true}"), Duration.ofHours(1), OPERATION); + + // when + IdempotencyClaimOutcome next = + store.claim(claim(store.newClaimAttempt(OTHER_OPERATION), FINGERPRINT, lease)); + + // then + assertThat(next) + .isInstanceOfSatisfying( + IdempotencyClaimOutcome.CompletedReplay.class, + replay -> assertThat(replay.response().payload()).isEqualTo("{\"late\":true}")); + } + + @Test + @DisplayName("lease가 지난 실행도 주인이 늦게 보고한 재시도 가능 실패는 기록된다") + void anExpiredExecutionsHolderCanStillReportARetryableFailure() { + // given + // The holder's last report is taken whatever it says (owner decision 2026-11-04): a failure it + // proved had no effect frees the key exactly as it would have inside the lease. + IdempotencyStorePort store = subject(); + Duration lease = processingLease(); + IdempotencyOwner late = executingWith(store, lease, Duration.ofHours(24)); + elapse(lease.multipliedBy(2)); + store.claim(claim(store.newClaimAttempt(OTHER_OPERATION), FINGERPRINT, lease)); + + // when + IdempotencyFailOutcome outcome = + store.markFailed( + late, + IdempotencyFailureDisposition.NO_EFFECT_RETRYABLE, + Duration.ofHours(1), + OPERATION); + + // then + assertThat(outcome).isEqualTo(IdempotencyFailOutcome.MARKED_RETRYABLE); + } + + @Test + @DisplayName("다른 요청이 lease가 지난 남의 실행을 inspect하면 claim과 같이 회복 필요(ABANDONED)로 보고된다") + void inspectingAnotherHoldersExpiredExecutionReportsWhatAClaimWouldAnswer() { + // given + IdempotencyStorePort store = subject(); + Duration lease = processingLease(); + executingWith(store, lease, Duration.ofHours(24)); + elapse(lease.multipliedBy(2)); + + // when + IdempotencyInspection inspection = + store.inspect( + new IdempotencyInspectionRequest( + SCOPE, FINGERPRINT, store.newClaimAttempt(OTHER_OPERATION))); + + // then + assertThat(inspection.outcome()).isEqualTo(IdempotencyInspectionOutcome.ABANDONED); + assertThat(inspection.owner()).isEmpty(); + } + + @Test + @DisplayName("lease가 지난 실행은 주인도 renew로 lease를 되살리지 못한다") + void anExpiredExecutionsLeaseCannotBeRenewed() { + // given + // Once the lease has run out a resend may already have been told "recovery required"; a lease + // that came back would turn the next answer into "in progress" for the same unknown effect. + IdempotencyStorePort store = subject(); + Duration lease = processingLease(); + IdempotencyOwner late = executingWith(store, lease, Duration.ofHours(24)); + elapse(lease.multipliedBy(2)); + + // when + var renewed = store.renew(late, lease, OPERATION); + + // then + assertThat(renewed.outcome()).isNotEqualTo(IdempotencyRenewOutcome.RENEWED); + assertThat(renewed.owner()).isEmpty(); } @Test diff --git a/src/build-logic/README.md b/src/build-logic/README.md index bfdb77e9..633e4894 100644 --- a/src/build-logic/README.md +++ b/src/build-logic/README.md @@ -16,7 +16,7 @@ capability, and the files it reads are declared as that test task's inputs. | `ca.java-library` / `ca.spring-library` / `ca.spring-config` | leaf-level composition of the Java/quality conventions for plain and Spring libraries | | `ca.platform-module` / `ca.grpc-platform-module` | what a vendored platform leaf (`messaging:*`, `grpc:*`, `grpc-advanced:*`) is: `java-library`, plus the gRPC BOM for the leaves that had it | | `ca.strict-test-lane` | the one "named tests ran, none skipped" mechanism: tagged / named / own-source-set `Test` lanes that fail when they execute nothing, miss a `requires` class, or (with `rejectSkipped`) skip anything. `mainStage()` moves a tagged lane out of `test` into the leaf's `mainCheck`; `explicitOnly(reason)` keeps a lane that needs an outside input out of every aggregate, and the aggregate prints the reason. Extra test source sets are Gradle `jvm-test-suite` suites declared in the leaf (`testing { suites { … } }`); a lane named after its suite makes the suite's own `Test` task strict, and `ca.java-conventions` gives every suite the BOM's JUnit | -| `ca.strict-lane-stages` (root of each build with strict lanes: the main build and optional-platforms) | the other half of the lane mechanism: `verifyStrictLaneStages --dry-run` fails when a strict lane of that build that is not `explicitOnly` is in the task plan of no declared stage that a workflow executes, or when a declared stage is executed by no workflow. A `--dry-run`, a command for another build (the build a command starts is its step's `working-directory`, or the job's or workflow's `defaults.run.working-directory`, joined with `-p`; the plugin reads this build's own directory from where it sits under the repository that holds `.github/workflows`), a command under `continue-on-error` or an `if:` other than `always()`/`success()`/`!cancelled()`, and a command of a workflow that starts only on `workflow_dispatch` do not count, and a lane the command removes with `-x` is not covered — matched the way Gradle matches task and project names, abbreviations included (`TaskSelectors`, a copy of Gradle's internal `NameMatcher`). A `run:` input of a `uses:` step is not a command. The plan is Gradle's own; the workflows are read for their `run:` steps with YAML folding applied (review 2026-11-01 08-01, 2026-11-03 RR-06-03/04, 2026-11-04 RR2-04-04) | +| `ca.strict-lane-stages` (root of each build with strict lanes: the main build and optional-platforms) | the other half of the lane mechanism: `verifyStrictLaneStages --dry-run` fails when a strict lane of that build that is not `explicitOnly` is in the task plan of no declared stage that a workflow executes, or when a declared stage is executed by no workflow. A `--dry-run`, a command for another build (the build a command starts is its step's `working-directory`, or the job's or workflow's `defaults.run.working-directory`, moved by each `cd ` the same `run:` shell surely ran before it — alone on its line, before `;`, or joined to the command by `&&` alone — then joined with `-p`; the plugin reads this build's own directory from where it sits under the repository that holds `.github/workflows`), a command after a directory change the reader does not follow (`cd "$VAR"`, `cd -`, `cd ~`, an absolute path, `pushd`/`popd`, a `cd` inside `if`/`for`/`while`/`case`, `{ }` or after a subshell, one joined with `||` or `|`, and the lines after a `cd` that shares an `&&` list with other commands — not guessed, and the failure names each such command with its reason), a command under `continue-on-error` or an `if:` other than `always()`/`success()`/`!cancelled()`, and a command of a workflow that starts only on `workflow_dispatch` do not count, and a lane the command removes with `-x` is not covered — matched the way Gradle matches task and project names, abbreviations included (`TaskSelectors`, a copy of Gradle's internal `NameMatcher`). A `run:` input of a `uses:` step is not a command. The plan is Gradle's own; the workflows are read for their `run:` steps with YAML folding applied (review 2026-11-01 08-01, 2026-11-03 RR-06-03/04, 2026-11-04 RR2-04-04, owner decision 2026-11-04 on `cd`) | | `ca.redis-topology-lane` | the Redis topology lane (mode selection, `-P` property validation, per-mode required classes) the redis-sdk-topology workflow drives | | `ca.api-surface` | read-only public API surface verification with a separate update task, wired into the leaf's `check` (owner decision 20); optionally holds other leaves' imports to a reviewed adopter subset (`adopterBaseline`) | | `ca.config-contract` | app-bootstrap's `verifyEnvKeys` (moved from the deleted build-tools included build; owner decision 4 keeps the task in app-bootstrap) | diff --git a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesPlugin.java b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesPlugin.java index 0cf9de12..6d0cead2 100644 --- a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesPlugin.java +++ b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesPlugin.java @@ -40,9 +40,12 @@ import org.gradle.api.execution.TaskExecutionGraph; * *

    Each build that holds strict lanes applies it at its own root: the main build, and the * optional-platforms build. A command executes this build when it starts in this build's directory - * — its step's {@code working-directory} joined with its {@code -p}, from the repository root, - * which is where GitHub keeps {@code .github/workflows}. Applied to the main build only, it said - * "every strict lane" while the optional build's performance lane ran nowhere (RR-06-03).

    + * — its step's {@code working-directory}, moved by the {@code cd} commands the same shell surely + * ran before it, joined with its {@code -p}, from the repository root, which is where GitHub keeps + * {@code .github/workflows} ({@link WorkflowGradleInvocations} says which {@code cd} it follows). + * A stage named only by commands that do not count is reported with each command's reason. Applied + * to the main build only, it said "every strict lane" while the optional build's performance lane + * ran nowhere (RR-06-03).

    * *

    The task plan is Gradle's own: {@code verifyStrictLaneStages} depends on the stages, so a * {@code --dry-run} of it builds the real plan, and the check reads it when the graph is ready. It @@ -120,7 +123,10 @@ public final class StrictLaneStagesPlugin implements Plugin { File workflowDirectory, String buildDirectory) { List problems = new ArrayList<>(foldedCommandBreaks(workflowDirectory)); - List invocations = invocations(workflowDirectory); + Map> invocationsByWorkflow = + invocations(workflowDirectory); + List invocations = + invocationsByWorkflow.values().stream().flatMap(List::stream).toList(); // Only an executed stage covers a lane — a stage no workflow runs is the same gap one level // up — and only as the command runs it: what its -x removes is not covered. Map> tasksByProject = new LinkedHashMap<>(); @@ -141,9 +147,11 @@ public final class StrictLaneStagesPlugin implements Plugin { + workflowDirectory.getName() + " for the build in " + buildDirectory - + " (a --dry-run, a command started in another directory, a command under" - + " continue-on-error or an if: other than always()/success()/!cancelled(), and a" - + " workflow that starts only on workflow_dispatch do not count)"); + + " (a --dry-run, a command started in another directory, a command after a cd this" + + " check does not follow, a command under continue-on-error or an if: other than" + + " always()/success()/!cancelled(), and a workflow that starts only on" + + " workflow_dispatch do not count)" + + notCounted(invocationsByWorkflow, stage)); continue; } Task stageTask = root.getTasks().findByPath(stage); @@ -179,6 +187,31 @@ public final class StrictLaneStagesPlugin implements Plugin { return problems; } + /** + * The commands that name {@code stage} but do not count, each with why: a workflow that calls the + * stage in a way this check does not read is told so, instead of failing as if it never did. + */ + private static String notCounted( + Map> invocationsByWorkflow, String stage) { + List lines = new ArrayList<>(); + invocationsByWorkflow.forEach( + (workflow, invocations) -> + invocations.stream() + .filter(invocation -> invocation.uncountedReason() != null) + .filter(invocation -> invocation.requests(stage)) + .forEach( + invocation -> + lines.add( + workflow + + ": gradlew " + + String.join(" ", invocation.tasks()) + + " — " + + invocation.uncountedReason()))); + return lines.isEmpty() + ? "" + : "; commands that name it but do not count:\n " + String.join("\n ", lines); + } + /** The tasks {@code stage} reaches as a command runs it: what its -x removes is cut off. */ private static Set plan(TaskExecutionGraph graph, Task stage, Set excluded) { Set seen = new HashSet<>(); @@ -219,11 +252,14 @@ public final class StrictLaneStagesPlugin implements Plugin { return files; } - private static List invocations(File workflowDirectory) { - List invocations = new ArrayList<>(); + /** Each workflow file's Gradle commands, by file name, in file order. */ + private static Map> invocations( + File workflowDirectory) { + Map> invocations = new LinkedHashMap<>(); for (File file : workflowFiles(workflowDirectory)) { try { - invocations.addAll( + invocations.put( + file.getName(), WorkflowGradleInvocations.read(Files.readString(file.toPath(), StandardCharsets.UTF_8))); } catch (IOException exception) { throw new UncheckedIOException("failed to read " + file, exception); diff --git a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java index 20f37f6f..0cca44b8 100644 --- a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java +++ b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java @@ -29,9 +29,19 @@ import java.util.regex.Pattern; * (review 2026-11-04 RR2-04-04). * *

    Which build a command starts is where it starts: the step's {@code working-directory} (or the - * job's or the workflow's {@code defaults.run.working-directory}) joined with its {@code -p} (also - * {@code -pdir} and {@code --project-dir}), as a path from the repository root. A {@code run:} that - * is an input of a {@code uses:} step ({@code with: run:}) is not a shell command and is not read. + * job's or the workflow's {@code defaults.run.working-directory}), then each {@code cd} the same + * shell ran before it, then its {@code -p} (also {@code -pdir} and {@code --project-dir}), as a + * path from the repository root (owner decision 2026-11-04). A {@code cd} is followed only when it + * is certain to have run before the command and where it went: {@code cd } + * at the top level of the script, either alone on its line or before {@code ;} (GitHub runs + * {@code bash -e}, so a failed {@code cd} ends the step), or joined to the command by {@code &&} + * alone. Every other directory change is not guessed — {@code cd "$VAR"}, {@code cd -}, {@code cd + * ~}, an absolute path, {@code pushd}/{@code popd}, a {@code cd} inside {@code if}/{@code for}/ + * {@code while}/{@code case}, braces or after a subshell, one joined with {@code ||} or {@code |}, + * and one that shares an {@code &&} list with other commands, after which a failed {@code cd} lets + * the next line run in the old directory: the commands after it get an uncounted reason naming it, + * so they count for no build. A {@code run:} that is an input of a {@code uses:} step ({@code with: + * run:}) is not a shell command and is not read. */ public final class WorkflowGradleInvocations { private static final Pattern RUN_KEY = Pattern.compile("^(\\s*)(?:-\\s+)?run:(.*)$"); @@ -44,6 +54,20 @@ public final class WorkflowGradleInvocations { /** Conditions under which a step still runs on every run whose earlier steps passed. */ private static final Set STATUS_CONDITIONS = Set.of("always()", "success()", "!cancelled()", "true"); + /** Command separators: a list ends at {@code ;} (and a line end); the others join commands. */ + private static final Pattern SEPARATOR = Pattern.compile(";|&&|\\|\\||\\|"); + /** Words that change the shell's directory. */ + private static final Set DIRECTORY_COMMANDS = Set.of("cd", "pushd", "popd"); + /** A {@code cd} argument this reader follows: relative, with no variable, glob or {@code ~}. */ + private static final Pattern LITERAL_RELATIVE_PATH = + Pattern.compile("[A-Za-z0-9._][A-Za-z0-9._/-]*"); + /** Reserved words that open a compound command whose body runs conditionally or repeatedly. */ + private static final Set COMPOUND_OPENERS = Set.of("if", "while", "until", "{"); + /** Reserved words whose compound command's first line is a header, not a command. */ + private static final Set COMPOUND_HEADERS = Set.of("for", "select", "case"); + private static final Set COMPOUND_CLOSERS = Set.of("fi", "done", "esac", "}"); + private static final Set COMMAND_PREFIXES = + Set.of("then", "do", "else", "elif", "!", "time"); private static final Set OPTIONS_WITH_VALUE = Set.of( "-p", @@ -76,7 +100,8 @@ public final class WorkflowGradleInvocations { * @param dryRun whether it only plans ({@code --dry-run} or {@code -m}) instead of executing * @param excludedTasks the {@code -x} / {@code --exclude-task} selectors, in order * @param uncountedReason why the command gates nothing although it runs — {@code - * continue-on-error}, or a condition other than a status function — or {@code null} + * continue-on-error}, a condition other than a status function, or a directory change before + * it that this reader does not follow — or {@code null} */ public record Invocation( String workingDirectory, @@ -107,11 +132,16 @@ public final class WorkflowGradleInvocations { * the repository root such as {@code src}. */ public boolean executes(String taskPath, String buildDirectory) { - String wanted = absolute(taskPath); return buildDirectory().equals(normalized(buildDirectory)) && !dryRun && uncountedReason == null - && tasks.stream().map(Invocation::absolute).anyMatch(wanted::equals); + && requests(taskPath); + } + + /** Whether the command names the task at {@code taskPath}, whatever build it starts. */ + public boolean requests(String taskPath) { + String wanted = absolute(taskPath); + return tasks.stream().map(Invocation::absolute).anyMatch(wanted::equals); } /** A relative path with {@code .} and {@code ..} resolved; {@code .} for the root itself. */ @@ -146,15 +176,145 @@ public final class WorkflowGradleInvocations { public static List read(String workflow) { List invocations = new ArrayList<>(); for (RunStep step : runSteps(workflow)) { - for (String command : shellCommands(step.script())) { - Invocation invocation = - gradleInvocation(command, step.workingDirectory(), step.uncountedReason()); + invocations.addAll(stepInvocations(step)); + } + return List.copyOf(invocations); + } + + /** + * Where the shell of a {@code run:} script is: a path from the repository root ({@code null} for + * the root), or, once a directory change is not followed, why — the first such reason is kept. + */ + private record ShellDirectory(String path, String unread) { + static ShellDirectory at(String path) { + return new ShellDirectory(path, null); + } + + ShellDirectory cd(String target) { + return unread != null + ? this + : at(Invocation.normalized((path == null ? "." : path) + "/" + target)); + } + + ShellDirectory unreadBecause(String reason) { + return unread != null ? this : new ShellDirectory(path, reason); + } + } + + /** One command of a shell list and the operator ({@code &&}, {@code ||}, {@code |}) before it. */ + private record Link(String operator, String command) {} + + /** + * The Gradle commands of one step, each starting where the step's shell is when it runs: the + * step's working directory moved by the {@code cd} commands before it that are certain to have + * run (see the class comment). + */ + private static List stepInvocations(RunStep step) { + List invocations = new ArrayList<>(); + ShellDirectory shell = ShellDirectory.at(step.workingDirectory()); + int depth = 0; + boolean subshell = false; + for (List list : shellLists(step.script())) { + ShellDirectory current = shell; + String listCd = null; + int commands = 0; + for (int index = 0; index < list.size(); index++) { + Link link = list.get(index); + List words = new ArrayList<>(List.of(link.command().trim().split("\\s+"))); + words.removeIf(String::isEmpty); + if (words.isEmpty()) { + continue; + } + commands++; + int first = 0; + boolean header = false; + while (first < words.size()) { + String word = words.get(first); + if (COMPOUND_HEADERS.contains(word)) { + depth++; + header = true; + break; + } else if (COMPOUND_OPENERS.contains(word)) { + depth++; + } else if (COMPOUND_CLOSERS.contains(word)) { + depth = Math.max(0, depth - 1); + } else if (word.startsWith("(")) { + // Where a subshell ends is not read, so a cd anywhere after it is not followed. + subshell = true; + if (word.length() > 1) { + words.set(first, word.substring(1)); + break; + } + } else if (!COMMAND_PREFIXES.contains(word)) { + break; + } + first++; + } + String text = "`" + link.command().trim() + "`"; + if (listCd != null && !"&&".equals(link.operator())) { + current = + current.unreadBecause( + text + " follows " + listCd + " through " + link.operator() + + ", so it may run where that cd did not take the shell"); + } + if (words.stream() + .map(WorkflowGradleInvocations::bareWord) + .anyMatch(DIRECTORY_COMMANDS::contains)) { + listCd = text; + List command = header ? List.of() : words.subList(first, words.size()); + String next = index + 1 < list.size() ? list.get(index + 1).operator() : null; + String target = + command.size() == 2 && command.get(0).equals("cd") + && LITERAL_RELATIVE_PATH.matcher(unquote(command.get(1))).matches() + ? unquote(command.get(1)) + : null; + if (target == null) { + current = + current.unreadBecause( + text + " is not a cd to a literal relative path (a variable, -, ~, an absolute" + + " path, pushd and popd are not followed)"); + } else if (depth > 0 || subshell) { + current = + current.unreadBecause( + text + " runs inside if/for/while/case, { } or after a subshell ( ), so whether" + + " it ran before the command is not read"); + } else if (isConditionalOrPiped(link.operator()) || isConditionalOrPiped(next)) { + current = + current.unreadBecause( + text + " is joined with || or |, so it may not have run, or ran in a subshell"); + } else { + current = current.cd(target); + } + continue; + } + String reason = step.uncountedReason(); + if (reason == null && current.unread() != null) { + reason = "the directory it starts in is not read: " + current.unread(); + } + Invocation invocation = gradleInvocation(link.command(), current.path(), reason); if (invocation != null) { invocations.add(invocation); } } + if (listCd != null) { + shell = + commands == 1 + ? current + : current.unreadBecause( + listCd + " shares an && list with other commands, and if it failed the shell" + + " went on to the next line in the old directory"); + } } - return List.copyOf(invocations); + return invocations; + } + + private static boolean isConditionalOrPiped(String operator) { + return "||".equals(operator) || "|".equals(operator); + } + + /** A word without the quotes, parentheses and braces around it: {@code "cd} is {@code cd}. */ + private static String bareWord(String word) { + return word.replaceAll("^[\"'`({]+|[\"'`)};]+$", ""); } /** @@ -564,15 +724,55 @@ public final class WorkflowGradleInvocations { return plain; } - private static List shellCommands(String script) { - String joined = script.replace("\\\n", " "); - List commands = new ArrayList<>(); - for (String line : joined.split("\n", -1)) { - for (String command : line.split(";|&&|\\|\\||\\|")) { - commands.add(command); + /** + * The script as shell lists: a list ends at {@code ;} or at a line end that does not follow an + * operator, and its commands are joined by {@code &&}, {@code ||} or {@code |}. Comments are + * dropped first, so a separator inside one splits nothing. + */ + private static List> shellLists(String script) { + List> lists = new ArrayList<>(); + List list = new ArrayList<>(); + String operator = null; + for (String line : script.replace("\\\n", " ").split("\n", -1)) { + String code = withoutComment(line); + if (operator == null && !list.isEmpty()) { + lists.add(list); + list = new ArrayList<>(); + } + Matcher separator = SEPARATOR.matcher(code); + int start = 0; + while (separator.find()) { + list.add(new Link(operator, code.substring(start, separator.start()))); + start = separator.end(); + if (separator.group().equals(";")) { + lists.add(list); + list = new ArrayList<>(); + operator = null; + } else { + operator = separator.group(); + } + } + String rest = code.substring(start); + if (!rest.isBlank() || operator == null) { + list.add(new Link(operator, rest)); + operator = null; } } - return commands; + if (!list.isEmpty()) { + lists.add(list); + } + return lists; + } + + /** The line up to a {@code #} that starts a word, which the shell reads as a comment. */ + private static String withoutComment(String line) { + for (int index = 0; index < line.length(); index++) { + if (line.charAt(index) == '#' + && (index == 0 || Character.isWhitespace(line.charAt(index - 1)))) { + return line.substring(0, index); + } + } + return line; } private static Invocation gradleInvocation( diff --git a/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesFunctionalTest.java b/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesFunctionalTest.java index 3540d55a..2f7098d2 100644 --- a/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesFunctionalTest.java +++ b/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesFunctionalTest.java @@ -441,6 +441,59 @@ class StrictLaneStagesFunctionalTest { assertThat(result.getOutput()).contains("stage :integrationCheck is executed by no workflow"); } + @Test + @DisplayName("working-directory 없이 cd src로 옮긴 뒤 단계를 부르는 workflow도 실행으로 세어 통과한다") + void passesWhenTheWorkflowCdsIntoTheBuildBeforeCallingGradlew() throws Exception { + // given + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + """); + workflow( + """ + jobs: + main: + steps: + - run: cd src && ./gradlew ci --stacktrace + - run: | + cd src + ./gradlew integrationCheck --continue + """); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").build(); + + // then + assertThat(result.getOutput()).contains("every strict lane is in an executed stage"); + } + + @Test + @DisplayName("따라갈 수 없는 cd 뒤에 부른 단계는 세지 않고, 실패 메시지에 그 명령과 세지 않은 이유를 적는다") + void aStageCalledAfterACdThatCannotBeFollowedFailsNamingWhy() throws Exception { + // given + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + """); + workflow( + """ + jobs: + main: + steps: + - run: cd src && ./gradlew ci --stacktrace + - run: cd "$GITHUB_WORKSPACE/src" && ./gradlew integrationCheck + """); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("stage :integrationCheck is executed by no workflow") + .contains("main.yml: gradlew integrationCheck") + .contains("cd \"$GITHUB_WORKSPACE/src\""); + } + private void leafLanes(String lanes) throws Exception { Files.writeString( gradleRoot.resolve("leaf/build.gradle"), diff --git a/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocationsTest.java b/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocationsTest.java index 6a55507b..a1ec1d95 100644 --- a/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocationsTest.java +++ b/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocationsTest.java @@ -392,6 +392,111 @@ class WorkflowGradleInvocationsTest { assertThat(invocations.get(1).executes(":releaseCheck", "src")).isTrue(); } + @Test + @DisplayName("같은 셸에서 먼저 실행한 cd 뒤의 gradlew는 그 디렉터리의 빌드를 실행한다") + void gradlewAfterACdInTheSameShellStartsTheBuildInThatDirectory() { + // given + String workflow = + """ + jobs: + main: + steps: + - run: cd src && ./gradlew :ci + - run: cd src; ./gradlew :ci + - run: | + cd src + ./gradlew :ci + - run: >- + cd src + + ./gradlew :ci + --stacktrace + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations) + .hasSize(4) + .allSatisfy( + invocation -> { + assertThat(invocation.uncountedReason()).isNull(); + assertThat(invocation.executes(":ci", "src")).isTrue(); + assertThat(invocation.executes(":ci", ".")).isFalse(); + }); + } + + @Test + @DisplayName("cd는 working-directory에서 시작해 상대 경로로 쌓이고, -p는 그 뒤에 붙는다") + void cdAccumulatesFromTheWorkingDirectoryAndDashPAppliesAfterIt() { + // given + String workflow = + """ + jobs: + main: + steps: + - working-directory: src + run: cd optional-platforms && ../gradlew ci + - run: | + cd src + cd .. + ./gradlew :ci + - run: cd src && ./gradlew -p optional-platforms ci + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations) + .extracting(Invocation::buildDirectory) + .containsExactly("src/optional-platforms", ".", "src/optional-platforms"); + } + + @Test + @DisplayName("확실히 따라갈 수 없는 cd 뒤의 gradlew는 어느 빌드의 실행으로도 세지 않고 그 이유를 남긴다") + void gradlewAfterACdThatCannotBeFollowedCountsForNoBuildAndSaysWhy() { + // given + String workflow = + """ + jobs: + main: + steps: + - run: cd "$GITHUB_WORKSPACE/src" && ./gradlew :ci + - run: | + cd src + cd - + ./gradlew :ci + - run: pushd src && ./gradlew :ci + - run: | + ( cd src && ./gradlew :ci ) + ./gradlew :ci + - run: | + cd src || exit 1 + ./gradlew :ci + - run: | + if [ -d src ]; then cd src; fi + ./gradlew :ci + - run: | + cd src && echo ready + ./gradlew :ci + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations) + .hasSize(8) + .allSatisfy( + invocation -> { + assertThat(invocation.uncountedReason()).containsPattern("\\b(cd|pushd)\\b"); + assertThat(invocation.executes(":ci", "src")).isFalse(); + assertThat(invocation.executes(":ci", ".")).isFalse(); + }); + } + @Test @DisplayName("uses 단계의 with 입력에 적힌 run은 셸 명령이 아니므로 읽지 않는다") void aRunInputOfAnActionIsNotAShellCommand() { diff --git a/src/composition/idempotency/README.md b/src/composition/idempotency/README.md index df150724..775851cc 100644 --- a/src/composition/idempotency/README.md +++ b/src/composition/idempotency/README.md @@ -45,7 +45,7 @@ executor, 설정 기본값이 함께 빠진다(그때 KEYED use case는 executor | 언제 | 키 | | --- | --- | | 켤 때 | `APP_IDEMPOTENCY_PROVIDER` (`redis` 또는 `postgresql`), 그리고 그 provider 모듈의 줄과 env | -| 조정할 때 | `APP_IDEMPOTENCY_PROCESSING_LEASE`(≤1h), `APP_IDEMPOTENCY_TTL`(≤72h, processing lease 이상), `APP_IDEMPOTENCY_FAILURE_RETENTION`(≤30d, `APP_IDEMPOTENCY_TTL` 이상으로 — 기동 검사는 없다) | +| 조정할 때 | `APP_IDEMPOTENCY_PROCESSING_LEASE`(≤1h), `APP_IDEMPOTENCY_TTL`(≤72h, processing lease 이상), `APP_IDEMPOTENCY_FAILURE_RETENTION`(≤30d, `APP_IDEMPOTENCY_TTL` 이상) | ## 설계 결정 참조 (app-bootstrap에서 옮김) @@ -74,7 +74,7 @@ executor, 설정 기본값이 함께 빠진다(그때 KEYED use case는 executor | `provider` | `APP_IDEMPOTENCY_PROVIDER` | `disabled` | `disabled` \| `redis` \| `postgresql` | | `processing-lease` | `APP_IDEMPOTENCY_PROCESSING_LEASE` | 30s | 1h | | `replay-ttl` | `APP_IDEMPOTENCY_TTL` | 24h | 72h, 그리고 `processing-lease` 이상 | - | `failure-retention` | `APP_IDEMPOTENCY_FAILURE_RETENTION` | 24h | 30d. `replay-ttl`과 비교하지 않는다(아래) | + | `failure-retention` | `APP_IDEMPOTENCY_FAILURE_RETENTION` | 24h | 30d, 그리고 `replay-ttl` 이상 | | `response-codec-id` | — | `json-v2` | 1–64자 | | `policy-revision` | — | 2 | 양수 | | `reaper-interval` | — | 10m | 양수 | @@ -87,10 +87,11 @@ executor, 설정 기본값이 함께 빠진다(그때 KEYED use case는 executor 둔다 — 이 검사는 store 를 지키는 것이 아니라 재생을 무력하게 만드는 정책을 막는다. `IdempotencyClaimRequest` 에는 두지 않았다: 포트는 어떤 값 쌍으로도 쓸 수 있고, store 가 모든 쌍에서 안전한지는 공유 계약이 본다. -- **`failure-retention` 은 `replay-ttl` 과 비교하지 않는다.** 실패로 표시된 기록(포기·재시도 가능)은 표시부터 - 이 기간만 남는다. `replay-ttl` 보다 짧으면 효과 불명으로 포기한 기록이 먼저 사라져 같은 키 재전송이 작업을 - 다시 돌리므로 운영 값은 `replay-ttl` 이상으로 둔다. 기동 검사로 막지 않은 이유: 지금 기동하는 설정을 이 - 라운드에서 실패로 바꾸지 않는다 — 검사 추가는 소유자 결정으로 남겼다(재리뷰 2026-11-04 RR3-03-02). +- **`failure-retention` 이 `replay-ttl` 보다 짧으면 기동을 거부한다.** 실패로 표시된 기록(포기·재시도 + 가능)은 표시부터 이 기간만 남는다. `replay-ttl` 보다 짧으면 효과 불명으로 포기한 기록이 먼저 사라져 같은 + 키 재전송이 작업을 다시 돌린다. 메시지는 두 키와 값을 함께 보여 준다. 기본값(둘 다 24h)은 그대로 뜬다. + 재리뷰 RR3-03-02 때는 지금 기동하는 설정을 깨지 않으려고 문서로만 두었고, 2026-11-04 소유자 결정으로 + 검사를 넣었다. - **상한 검사는 컴팩트 생성자에서 fail-fast 로 던진다.** `Duration`의 상한은 JSR-303(`@Valid`) 애너테이션으로 표현할 수 없어 생성자에서 직접 검증한다. 검증을 느슨하게 두면 과도하게 긴 TTL 이 저장소를 조용히 부풀리고 멱등성 키 추측 공격의 유효 시간 창을 넓히기 때문에, 부팅 시점에 즉시 diff --git a/src/composition/idempotency/src/main/java/dev/caskeleton/composition/idempotency/IdempotencySettings.java b/src/composition/idempotency/src/main/java/dev/caskeleton/composition/idempotency/IdempotencySettings.java index 19bf60f7..e447d879 100644 --- a/src/composition/idempotency/src/main/java/dev/caskeleton/composition/idempotency/IdempotencySettings.java +++ b/src/composition/idempotency/src/main/java/dev/caskeleton/composition/idempotency/IdempotencySettings.java @@ -23,7 +23,8 @@ import org.springframework.core.env.Environment; * IdempotencyExecutor#IN_FLIGHT_RETRY_AFTER}) * @param replayTtl how long a completed response is replayable (at most 72h, D6), and no shorter * than {@code processingLease} - * @param failureRetention how long a failed attempt's evidence is kept + * @param failureRetention how long a failed attempt's evidence is kept (at most 30d), and no + * shorter than {@code replayTtl} * @param responseCodecId identifier of the codec the stored payload is written with * @param policyRevision replay policy revision written into and compared on each record * @param reaperInterval how often the PostgreSQL provider purges expired rows @@ -83,6 +84,21 @@ public record IdempotencySettings( "failure-retention", orDefault(failureRetention, Duration.ofHours(24)), MAX_FAILURE_RETENTION); + // A record the executor marked failed lives for this long from the marking. Shorter than the + // replay window, a record abandoned with an unknown effect is forgotten before a completed one + // would be, and the next same-key resend runs the work again (owner decision 2026-11-04, + // re-review RR3-03-02). + if (failureRetention.compareTo(replayTtl) < 0) { + throw StartupFailures.envValidation( + PREFIX + + ".failure-retention (" + + failureRetention + + ") must not be shorter than " + + PREFIX + + ".replay-ttl (" + + replayTtl + + ")"); + } reaperInterval = bounded("reaper-interval", orDefault(reaperInterval, Duration.ofMinutes(10)), null); responseCodecId = responseCodecId == null ? "json-v2" : responseCodecId; diff --git a/src/composition/idempotency/src/test/java/dev/caskeleton/composition/idempotency/IdempotencySettingsTest.java b/src/composition/idempotency/src/test/java/dev/caskeleton/composition/idempotency/IdempotencySettingsTest.java index a4ebe984..67845b34 100644 --- a/src/composition/idempotency/src/test/java/dev/caskeleton/composition/idempotency/IdempotencySettingsTest.java +++ b/src/composition/idempotency/src/test/java/dev/caskeleton/composition/idempotency/IdempotencySettingsTest.java @@ -47,7 +47,7 @@ class IdempotencySettingsTest { .withProperty(PREFIX + "provider", "postgresql") .withProperty(PREFIX + "processing-lease", "45s") .withProperty(PREFIX + "replay-ttl", "72h") - .withProperty(PREFIX + "failure-retention", "2h") + .withProperty(PREFIX + "failure-retention", "100h") .withProperty(PREFIX + "response-codec-id", "json-v3") .withProperty(PREFIX + "policy-revision", "3") .withProperty(PREFIX + "reaper-interval", "1m"); @@ -63,7 +63,7 @@ class IdempotencySettingsTest { IdempotencySettings.Provider.POSTGRESQL, Duration.ofSeconds(45), Duration.ofHours(72), - Duration.ofHours(2), + Duration.ofHours(100), "json-v3", 3, Duration.ofMinutes(1))); @@ -201,6 +201,53 @@ class IdempotencySettingsTest { "app.capabilities.idempotency.replay-ttl must not be shorter than processing-lease"); } + /** + * A record the executor marked failed lives for {@code failure-retention} from the marking. One + * shorter than the replay window lets an abandoned record — effect unknown — go first, and the + * next same-key resend runs the work again (owner decision 2026-11-04, re-review RR3-03-02). + */ + @ParameterizedTest + @CsvSource({"PT24H, PT23H59M", "PT72H, PT24H"}) + @DisplayName("failure-retention이 replay-ttl보다 짧으면 두 키와 값을 담아 기동을 거부한다") + void aFailureRetentionShorterThanTheReplayTtlIsRefused(Duration replay, Duration retention) { + // when + Throwable thrown = + catchThrowable( + () -> + new IdempotencySettings( + IdempotencySettings.Provider.REDIS, null, replay, retention, null, null, null)); + + // then + assertThat(thrown) + .isInstanceOfSatisfying( + StartupFailureException.class, + e -> assertThat(e.errorCode()).isEqualTo(StartupErrorCode.STARTUP_VALIDATION_FAILED)) + .hasMessageContaining( + "app.capabilities.idempotency.failure-retention (" + + retention + + ") must not be shorter than app.capabilities.idempotency.replay-ttl (" + + replay + + ")"); + } + + @Test + @DisplayName("failure-retention이 replay-ttl과 같으면 받아들인다") + void aFailureRetentionEqualToTheReplayTtlIsAccepted() { + // when + IdempotencySettings settings = + new IdempotencySettings( + IdempotencySettings.Provider.REDIS, + null, + Duration.ofHours(30), + Duration.ofHours(30), + null, + null, + null); + + // then + assertThat(settings.failureRetention()).isEqualTo(settings.replayTtl()); + } + @Test @DisplayName("replay-ttl이 processing-lease와 같으면 받아들인다") void aReplayTtlEqualToTheProcessingLeaseIsAccepted() {