fix!: 늦게 끝난 멱등 실행을 기록하고 설정·workflow 검사를 보강한다

문제: 기본값으로 정했던 세 가지를 소유자가 다시 정했다.
- lease(기본 30s)가 지난 실행을 다음 같은 키 요청이 포기로 표시해서,
  첫 시도가 늦게 끝나면 결과가 버려지고 그 요청도 500을 받았다.
  executor가 lease를 갱신하지 않아 30s를 넘는 정상 요청도 해당됐다.
- failure-retention이 replay-ttl보다 짧아도 기동이 막히지 않아, 효과
  불명 실패의 중복 방지 기간이 주석 경고만 남긴 채 짧아졌다.
- verifyStrictLaneStages가 `cd src && ./gradlew`를 저장소 루트 빌드로
  읽어 파생 서비스 workflow에서 거짓 실패가 났다.

방법:
- lease가 지난 실행 기록을 claim이 만나면 기록을 바꾸지 않고 회복
  필요로만 답한다. 주인의 늦은 complete·markFailed는 기록되고 다음
  claim은 그 결과를 재생한다. 다시 실행하지 않는다는 결정은 그대로다.
  PostgreSQL·Redis·fake와 공유 계약을 함께 바꿨다. 이미 끝난 lease의
  renew는 두 저장소 모두 거절한다(Redis만 받던 것을 맞춤).
- IdempotencySettings가 failure-retention < replay-ttl이면 기동을
  실패시킨다. 기본값(둘 다 24h)은 그대로 뜬다.
- workflow 명령의 빌드를 working-directory → 같은 셸의 최상위
  `cd <상대 경로>` → -p 순서로 정한다. 읽을 수 없는 이동($VAR, 절대
  경로, 서브셸·조건문 안) 뒤의 명령은 이유를 대며 세지 않는다.

위험·한계: lease가 지난 실행의 EXECUTING 기록을 운영자가 지우면 늦은
완료가 사라지고 같은 키가 다시 실행된다(runbook에 적음). 회복 필요를 받은
뒤 같은 키로 다시 보내면 성공 응답이 올 수 있다(프론트 인계 문서 갱신).
CLAIMED에서 실행 시작으로 넘어갈 때 PostgreSQL은 lease를 보고 Redis는
보지 않는다. `./gradlew ci || true` 같은 명령을 여전히 실행으로 센다
(이전부터, 거짓 통과).

검증: ci, 두 빌드 verifyStrictLaneStages --dry-run, mainCheck,
:integrationCheck, -p optional-platforms ci integrationCheck
performanceCheck, :performanceCheck, :releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 첫 실행 통과. 결정 ①은 실
PostgreSQL·실 Redis 계약 lane에서 RED(늦은 complete 거절)를 먼저 확인했다.

Refs: docs/reviews/2026-11-03-rereview/README.md 15절
BREAKING CHANGE: lease가 지난 멱등 실행의 늦은 완료가 기록된다(전에는
포기). failure-retention < replay-ttl 설정은 기동 실패.
This commit is contained in:
DongHyeonka
2026-11-04 20:17:27 +09:00
parent b76285a5aa
commit 70fb80bf04
35 changed files with 906 additions and 179 deletions
+3 -1
View File
@@ -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`에서
+3 -2
View File
@@ -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 <relative path>` 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.
+8 -5
View File
@@ -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 결정): 같은 키 재전송은 서버가 안전하게 판정하므로 다시
보내는 것이 맞고, 새 키로 보내면 서버가 막지 못한다. 짝 프론트 분류기도 이 표를 따른다.
+6 -5
View File
@@ -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
@@ -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=<HEAD>` | rc=0 | 4초 | 20.00 |
| `scripts/verify-compose-profile-contracts.sh` | rc=0, 18 lane | — | 18.72 |
+35 -19
View File
@@ -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 <key>
```
`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 = '<scope digest>';
```
`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 <key> state` is `ABANDONED` and `PTTL <key>` has minutes left, then
`DEL <key>`. 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
+6 -4
View File
@@ -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`에 아주 좋은 버그 기록이 있다.
+4 -3
View File
@@ -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/<file>` 또는 `... both ship <key>`(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.<feature>`로 옮긴다. 규칙 정본은 `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<task>`·`-p<dir>`도 Gradle처럼 읽는다(RR3-04-02). `verifyEnvKeys`: lane 계약 json의 `APP_` 밖 키는 `SPRING_`·`MANAGEMENT_`·`SERVER_`이거나 `secret://…/<VAR>`가 가리키는 변수여야 하고, 레지스트리 `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<task>`·`-p<dir>`도 Gradle처럼 읽는다(RR3-04-02). `verifyEnvKeys`: lane 계약 json의 `APP_` 밖 키는 `SPRING_`·`MANAGEMENT_`·`SERVER_`이거나 `secret://…/<VAR>`가 가리키는 변수여야 하고, 레지스트리 `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. 따라오는 순서
+15 -10
View File
@@ -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. 헤더
+1 -1
View File
@@ -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
+8 -4
View File
@@ -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
@@ -33,11 +33,14 @@ public final class IdempotencyScripts {
*
* <p>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.
*
* <p>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.
*
* <p>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).
*
* <p>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.
*
* <p>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".
* <p>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,
@@ -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(
@@ -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() {
@@ -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` 외
@@ -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.
*
* <p>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.
* <p>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).
*
* <p>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());
}
}
@@ -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.
*
* <p>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 =
"""
@@ -38,7 +38,7 @@ import org.springframework.jdbc.core.JdbcOperations;
*
* <p>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
@@ -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
@@ -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,
+5 -3
View File
@@ -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).
+3 -2
View File
@@ -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 를
보장하지 않는다.
@@ -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.
*
* <p>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 {
@@ -8,6 +8,12 @@ import java.util.Optional;
/**
* Owner-safe request-replay lifecycle over {@link IdempotencyStorePort}.
*
* <p>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.
*
* <p>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 <em>that</em> 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);
};
@@ -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,
@@ -8,6 +8,15 @@ import java.time.Duration;
*
* <p>Providers (Redis, PostgreSQL) contribute only this store; the {@link IdempotencyExecutor} that
* drives it is assembled once by the composition root.
*
* <p>The processing lease decides only what <em>other</em> 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 {
@@ -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);
* <li>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);
* <li>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
+1 -1
View File
@@ -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 <literal relative path>` 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) |
@@ -40,9 +40,12 @@ import org.gradle.api.execution.TaskExecutionGraph;
*
* <p>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).</p>
* — 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).</p>
*
* <p>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<Project> {
File workflowDirectory,
String buildDirectory) {
List<String> problems = new ArrayList<>(foldedCommandBreaks(workflowDirectory));
List<WorkflowGradleInvocations.Invocation> invocations = invocations(workflowDirectory);
Map<String, List<WorkflowGradleInvocations.Invocation>> invocationsByWorkflow =
invocations(workflowDirectory);
List<WorkflowGradleInvocations.Invocation> 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<String, Set<String>> tasksByProject = new LinkedHashMap<>();
@@ -141,9 +147,11 @@ public final class StrictLaneStagesPlugin implements Plugin<Project> {
+ 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<Project> {
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<String, List<WorkflowGradleInvocations.Invocation>> invocationsByWorkflow, String stage) {
List<String> 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<String> plan(TaskExecutionGraph graph, Task stage, Set<String> excluded) {
Set<String> seen = new HashSet<>();
@@ -219,11 +252,14 @@ public final class StrictLaneStagesPlugin implements Plugin<Project> {
return files;
}
private static List<WorkflowGradleInvocations.Invocation> invocations(File workflowDirectory) {
List<WorkflowGradleInvocations.Invocation> invocations = new ArrayList<>();
/** Each workflow file's Gradle commands, by file name, in file order. */
private static Map<String, List<WorkflowGradleInvocations.Invocation>> invocations(
File workflowDirectory) {
Map<String, List<WorkflowGradleInvocations.Invocation>> 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);
@@ -29,9 +29,19 @@ import java.util.regex.Pattern;
* (review 2026-11-04 RR2-04-04).
*
* <p>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 <literal relative path>}
* 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<String> 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<String> 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<String> 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<String> COMPOUND_HEADERS = Set.of("for", "select", "case");
private static final Set<String> COMPOUND_CLOSERS = Set.of("fi", "done", "esac", "}");
private static final Set<String> COMMAND_PREFIXES =
Set.of("then", "do", "else", "elif", "!", "time");
private static final Set<String> 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<Invocation> read(String workflow) {
List<Invocation> 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<Invocation> stepInvocations(RunStep step) {
List<Invocation> invocations = new ArrayList<>();
ShellDirectory shell = ShellDirectory.at(step.workingDirectory());
int depth = 0;
boolean subshell = false;
for (List<Link> 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<String> 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<String> 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<String> shellCommands(String script) {
String joined = script.replace("\\\n", " ");
List<String> 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<List<Link>> shellLists(String script) {
List<List<Link>> lists = new ArrayList<>();
List<Link> 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(
@@ -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"),
@@ -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<Invocation> 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<Invocation> 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<Invocation> 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() {
+7 -6
View File
@@ -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 이
저장소를 조용히 부풀리고 멱등성 키 추측 공격의 유효 시간 창을 넓히기 때문에, 부팅 시점에 즉시
@@ -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;
@@ -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() {