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:
@@ -84,7 +84,9 @@ root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어
|
|||||||
줄 때문에 옵션을 별개 명령으로 떼어 내지 않는지 검사한다. 두 빌드가 각자 검사를 돌린다. `-x`로 뺀
|
줄 때문에 옵션을 별개 명령으로 떼어 내지 않는지 검사한다. 두 빌드가 각자 검사를 돌린다. `-x`로 뺀
|
||||||
lane(Gradle처럼 축약 이름도 맞춰 본다), `continue-on-error` 아래 명령, 상태 함수(`always()`·`success()`·
|
lane(Gradle처럼 축약 이름도 맞춰 본다), `continue-on-error` 아래 명령, 상태 함수(`always()`·`success()`·
|
||||||
`!cancelled()`)가 아닌 `if:` 아래 명령, `workflow_dispatch`로만 시작하는 workflow의 명령은 실행으로 세지
|
`!cancelled()`)가 아닌 `if:` 아래 명령, `workflow_dispatch`로만 시작하는 workflow의 명령은 실행으로 세지
|
||||||
않는다. 명령이 어느 빌드를 실행하는지는 `working-directory`와 `-p`를 합친 디렉터리로 정한다.
|
않는다. 명령이 어느 빌드를 실행하는지는 `working-directory`에서 시작해 같은 셸이 그 앞에서 확실히
|
||||||
|
실행한 `cd <상대 경로>`를 따라간 뒤 `-p`를 합친 디렉터리로 정한다. 따라갈 수 없는 `cd`(`cd "$VAR"`·
|
||||||
|
`cd -`·`pushd`·조건부·서브셸 등) 뒤의 명령은 추측하지 않고 세지 않는다.
|
||||||
|
|
||||||
작업 파일의 소유 leaf는 registry의 `source_path`로 판단하고 가장 가까운 `src/**/CLAUDE.md`를
|
작업 파일의 소유 leaf는 registry의 `source_path`로 판단하고 가장 가까운 `src/**/CLAUDE.md`를
|
||||||
함께 읽는다. focused test는 registry의 `gradle_path`에서
|
함께 읽는다. focused test는 registry의 `gradle_path`에서
|
||||||
|
|||||||
@@ -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
|
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
|
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;
|
`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
|
the build a command runs is its `working-directory`, then the `cd <relative path>` the same shell
|
||||||
`run:` block splits an option off its command.
|
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.
|
Commit policy is `human-only`: agents do not stage, commit, amend, or push implementation changes.
|
||||||
|
|
||||||
|
|||||||
@@ -56,11 +56,14 @@ DB 커밋 중 연결 끊김 ─────────────────
|
|||||||
|
|
||||||
같은 키 재전송은 작업을 다시 돌리지 않는다. 첫 시도가 실행을 시작한 뒤 processing lease(기본 30s)가
|
같은 키 재전송은 작업을 다시 돌리지 않는다. 첫 시도가 실행을 시작한 뒤 processing lease(기본 30s)가
|
||||||
지나면 두 저장소 모두 그 기록을 넘겨주지 않고 500 `IDEMPOTENCY_RECOVERY_REQUIRED`로 답한다. 넘겨받는 것은
|
지나면 두 저장소 모두 그 기록을 넘겨주지 않고 500 `IDEMPOTENCY_RECOVERY_REQUIRED`로 답한다. 넘겨받는 것은
|
||||||
실행 전 claim과 재시도 가능한 실패뿐이다. 기록은 lease + `replay-ttl` 동안 남고, `replay-ttl`이 lease보다
|
실행 전 claim과 재시도 가능한 실패뿐이다. 이 답은 기록을 바꾸지 않는다. executor는 lease를 늘리지 않아
|
||||||
짧으면 기동이 실패한다(`IdempotencyStoreContract`, 재리뷰 2026-11-04 RR-01-11·RR-03-11). 작업이 실패로
|
30s를 넘는 정상 요청도 lease가 지나는데, 그 첫 시도가 나중에 끝나면 결과가 기록되고 첫 요청은 정상 응답을
|
||||||
끝나 executor가 포기나 재시도 가능으로 표시한 기록은 표시한 때부터 `failure-retention`(기본 24h) 동안
|
받으며 그 뒤 같은 키 요청은 그 결과를 재생한다(2026-11-04 소유자 결정). 기록은 lease + `replay-ttl` 동안
|
||||||
남는다. 이 값은 검사하지 않으므로 `replay-ttl` 이상으로 둔다. 짧으면 효과 불명으로 포기한 기록이 먼저
|
남고, `replay-ttl`이 lease보다 짧으면 기동이 실패한다(`IdempotencyStoreContract`, 재리뷰 2026-11-04
|
||||||
사라져 같은 키 재전송이 작업을 다시 돌린다(RR3-03-02).
|
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 결정): 같은 키 재전송은 서버가 안전하게 판정하므로 다시
|
409를 `retryable=true`로 바꾼 이유(리뷰 02-01 결정): 같은 키 재전송은 서버가 안전하게 판정하므로 다시
|
||||||
보내는 것이 맞고, 새 키로 보내면 서버가 막지 못한다. 짝 프론트 분류기도 이 표를 따른다.
|
보내는 것이 맞고, 새 키로 보내면 서버가 막지 못한다. 짝 프론트 분류기도 이 표를 따른다.
|
||||||
|
|||||||
@@ -1682,9 +1682,10 @@ env_keys:
|
|||||||
|
|
||||||
- name: APP_IDEMPOTENCY_FAILURE_RETENTION
|
- name: APP_IDEMPOTENCY_FAILURE_RETENTION
|
||||||
# app.capabilities.idempotency.failure-retention: how long a record the executor marked failed
|
# 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
|
# (abandoned with an unknown effect, or retryable without one) stays, from the marking. At most
|
||||||
# compared with APP_IDEMPOTENCY_TTL at startup; keep it at least that long, or an abandoned
|
# 30d, and IdempotencySettings refuses less than APP_IDEMPOTENCY_TTL at startup: a shorter one
|
||||||
# record goes first and a same-key resend runs the work again (re-review 2026-11-04 RR3-03-02).
|
# 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
|
type: duration
|
||||||
default: 24h
|
default: 24h
|
||||||
allowed_values: null
|
allowed_values: null
|
||||||
@@ -1692,8 +1693,8 @@ env_keys:
|
|||||||
required: false
|
required: false
|
||||||
reload_policy: restart-only
|
reload_policy: restart-only
|
||||||
owner_branch: redis-production-capability-completion
|
owner_branch: redis-production-capability-completion
|
||||||
validation: positive_duration_le_30d
|
validation: positive_duration_le_30d_ge_replay_ttl
|
||||||
compatibility_impact: additive
|
compatibility_impact: behavior-change
|
||||||
required_test: redis-idempotency-contract:failure-retention-bounded
|
required_test: redis-idempotency-contract:failure-retention-bounded
|
||||||
|
|
||||||
- name: APP_LEASE_PROVIDER
|
- name: APP_LEASE_PROVIDER
|
||||||
|
|||||||
@@ -290,3 +290,31 @@ Minor 19건 중 동작에 닿는 것:
|
|||||||
| `scripts/verify-compose-profile-contracts.sh` | rc=0, 18 lane | — | 12.23 |
|
| `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분 넘게 길어진 것은 이 단계의 비용이다.
|
고친 테스트의 컨테이너 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 |
|
||||||
|
|||||||
@@ -24,12 +24,14 @@ status: active
|
|||||||
a transaction (an outbound call, a message) may have happened. This is not "nothing was executed".
|
a transaction (an outbound call, a message) may have happened. This is not "nothing was executed".
|
||||||
Clients resend with the same key.
|
Clients resend with the same key.
|
||||||
- HTTP 500 `IDEMPOTENCY_RECOVERY_REQUIRED` (`retryable=false`) means the opposite case: the store
|
- 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
|
cannot tell whether an earlier attempt's effect already happened. Two records produce it:
|
||||||
started and its processing lease (`APP_IDEMPOTENCY_PROCESSING_LEASE`, 30s) ran out before it
|
- `ABANDONED`: the action threw, or reported its effect unknown. Final until the record expires.
|
||||||
recorded a result — it crashed, or ran longer than the lease. The next request with the key marks
|
- `EXECUTING` past its processing lease (`APP_IDEMPOTENCY_PROCESSING_LEASE`, 30s): the attempt
|
||||||
the record abandoned and every later one gets this 500; the server never runs it again, and a late
|
crashed, or is still running longer than the lease. The executor never renews the lease, so a
|
||||||
result from the first attempt is not recorded either. An action that threw, or reported its effect
|
slow but healthy request lands here too. The server never runs it again and does not touch the
|
||||||
unknown, is abandoned the same way.
|
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
|
## Diagnosis
|
||||||
|
|
||||||
@@ -53,8 +55,10 @@ status: active
|
|||||||
PTTL <key>
|
PTTL <key>
|
||||||
```
|
```
|
||||||
|
|
||||||
`state` `ABANDONED` is the recovery-required record. `leaseUntil` is the lease end in epoch
|
`state` `ABANDONED` is final. `state` `EXECUTING` with a `leaseUntil` (lease end, epoch
|
||||||
milliseconds (server clock); `PTTL` is how long the record still lives, in milliseconds.
|
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:
|
- PostgreSQL, in the application's schema:
|
||||||
|
|
||||||
```sql
|
```sql
|
||||||
@@ -65,9 +69,11 @@ status: active
|
|||||||
AND scope_hash = '<scope digest>';
|
AND scope_hash = '<scope digest>';
|
||||||
```
|
```
|
||||||
|
|
||||||
`last_transition_kind` `EXPIRED_EXECUTION` means the lease ran out (the first attempt may still
|
`status` `ABANDONED` with `last_transition_kind` `FAIL_ABANDONED` means the action threw or
|
||||||
have finished its work); `FAIL_ABANDONED` means the action threw or reported its effect unknown.
|
reported its effect unknown. `status` `EXECUTING` with `processing_lease_until` before
|
||||||
`expires_at` is when the reaper deletes the row.
|
`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
|
## Action
|
||||||
|
|
||||||
@@ -76,14 +82,24 @@ status: active
|
|||||||
transaction for the failed requests (the ERROR log line names the code). A same-key resend replays
|
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,
|
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.
|
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
|
- `IDEMPOTENCY_RECOVERY_REQUIRED`: do not ask the client to retry blindly. If the record is
|
||||||
(the order, the payment, the downstream system) whether the earlier attempt's effect exists. There
|
`EXECUTING` past its lease, first wait for the attempt: look the record up again after the
|
||||||
is no way to complete the record by hand — the stored response is the action's own result.
|
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
|
- 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`).
|
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
|
- 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
|
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
|
- 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.
|
`DEL <key>`. A record that is about to expire needs nothing; once it is gone the key is new.
|
||||||
- PostgreSQL:
|
- PostgreSQL:
|
||||||
@@ -95,10 +111,10 @@ status: active
|
|||||||
AND status = 'ABANDONED';
|
AND status = 'ABANDONED';
|
||||||
```
|
```
|
||||||
|
|
||||||
Without either step the key is released when the record expires. That record lives for the
|
Without either step the key is released when the record expires. A record whose attempt never
|
||||||
processing lease plus `APP_IDEMPOTENCY_TTL` from its claim when its lease ran out, and for
|
finished lives for the processing lease plus `APP_IDEMPOTENCY_TTL` from its claim; one the action
|
||||||
`APP_IDEMPOTENCY_FAILURE_RETENTION` from the failure when the action failed
|
marked failed lives for `APP_IDEMPOTENCY_FAILURE_RETENTION` (not shorter than `APP_IDEMPOTENCY_TTL`)
|
||||||
(`docs/web/http-contract.md`, "서버가 기억하는 기간").
|
from the failure (`docs/web/http-contract.md`, "서버가 기억하는 기간").
|
||||||
|
|
||||||
## Escalation
|
## Escalation
|
||||||
|
|
||||||
|
|||||||
@@ -1681,7 +1681,7 @@ setter가 아니라 **registry 생성자**에서 설정한다.
|
|||||||
|---|---|
|
|---|---|
|
||||||
| `IdempotencyCapabilityGuard` | 3개 precondition (vendor, capability, transaction) |
|
| `IdempotencyCapabilityGuard` | 3개 precondition (vendor, capability, transaction) |
|
||||||
| `IdempotencyRowMapper` | row 읽기 + `clock_timestamp()` |
|
| `IdempotencyRowMapper` | row 읽기 + `clock_timestamp()` |
|
||||||
| `IdempotencyClaimGateway` | 소유권을 **정하는** 3개 statement (insert / reset / abandon) |
|
| `IdempotencyClaimGateway` | 소유권을 **정하는** 2개 statement (insert / reset) |
|
||||||
| `IdempotencyTransitionGateway` | 이미 가진 claim을 **진행시키는** 5개 statement |
|
| `IdempotencyTransitionGateway` | 이미 가진 claim을 **진행시키는** 5개 statement |
|
||||||
| `IdempotencyDigestPolicy` | transition digest 구성 |
|
| `IdempotencyDigestPolicy` | transition digest 구성 |
|
||||||
| `IdempotencyRecordRow` | row 정의 (package-private) |
|
| `IdempotencyRecordRow` | row 정의 (package-private) |
|
||||||
@@ -1704,13 +1704,15 @@ COMPLETED이고 replay_until 있음 → CompletedReplay(payl
|
|||||||
같은 token, 다른 operationId → OwnerOperationConflict
|
같은 token, 다른 operationId → OwnerOperationConflict
|
||||||
CLAIMED이고 lease 만료 → resetClaim → TakenOverClaimed
|
CLAIMED이고 lease 만료 → resetClaim → TakenOverClaimed
|
||||||
FAILED_RETRYABLE → resetClaim → TakenOverClaimed
|
FAILED_RETRYABLE → resetClaim → TakenOverClaimed
|
||||||
EXECUTING이고 lease 만료 → abandonExpiredExecution → RecoveryRequired
|
EXECUTING이고 lease 만료 → RecoveryRequired (행은 그대로)
|
||||||
ABANDONED → RecoveryRequired
|
ABANDONED → RecoveryRequired
|
||||||
그 외 → InProgress(retryAfter, attempt)
|
그 외 → InProgress(retryAfter, attempt)
|
||||||
```
|
```
|
||||||
|
|
||||||
**만료된 `CLAIMED`만 takeover하고, 만료된 `EXECUTING`은 `ABANDONED`로 닫고 reconciliation을
|
**만료된 `CLAIMED`만 takeover하고, 만료된 `EXECUTING`은 reconciliation을 요구하되 행은 바꾸지
|
||||||
요구한다.** 실행이 시작된 뒤의 blind retry를 하지 않는다는 뜻이다.
|
않는다.** 실행이 시작된 뒤의 blind retry를 하지 않는다는 뜻이다. 행을 그대로 두는 이유는 주인이 아직
|
||||||
|
돌고 있을 수 있어서다. 주인이 늦게 끝나면 그 결과가 기록되고 다음 claim이 재생한다(2026-11-04 소유자
|
||||||
|
결정 — 전에는 `abandonExpiredExecution`이 행을 `ABANDONED`로 바꿔 늦은 결과를 버렸다).
|
||||||
|
|
||||||
`IdempotencyCapabilityGuard`에 아주 좋은 버그 기록이 있다.
|
`IdempotencyCapabilityGuard`에 아주 좋은 버그 기록이 있다.
|
||||||
|
|
||||||
|
|||||||
@@ -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-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-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-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-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-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` |
|
| 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-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-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-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-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` |
|
| 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-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-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-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` |
|
| 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` |
|
| 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` |
|
| 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` |
|
| 멱등성 | `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` |
|
| sample-portfolio | 익명 쓰기 401, 포스터 제목 대소문자 무시 유일(409 `POSTER_ALREADY_EXISTS`), 관리자도 남의 work log 수정 불가, 샘플 이벤트 tenant `global` | sample을 남긴 서비스만 | `34565130`, `1400dc15` |
|
||||||
|
|
||||||
## 6. 따라오는 순서
|
## 6. 따라오는 순서
|
||||||
|
|||||||
+15
-10
@@ -110,7 +110,7 @@ status는 코드 표(`HttpStatusErrorCodes`)에 있는 것만 그대로 나간
|
|||||||
| --- | --- | --- | --- | --- | --- |
|
| --- | --- | --- | --- | --- | --- |
|
||||||
| 작업 실행 전(claim·시작 단계) 멱등성 저장소 응답 없음 | 503 | `IDEMPOTENCY_UNAVAILABLE` | `true` | 없음 | 작업은 실행되지 않았다. 같은 키로 나중에 다시 보낸다 |
|
| 작업 실행 전(claim·시작 단계) 멱등성 저장소 응답 없음 | 503 | `IDEMPOTENCY_UNAVAILABLE` | `true` | 없음 | 작업은 실행되지 않았다. 같은 키로 나중에 다시 보낸다 |
|
||||||
| 작업 실행 뒤 결과 기록(complete 단계) 중 저장소 응답 없음 — **결과 불명** | 503 | `IDEMPOTENCY_COMPLETION_UNKNOWN` | `true` | 없음 | "적용되지 않았다"고 알리지 않는다. **같은 키로** 나중에 다시 보낸다. 새 키 금지 |
|
| 작업 실행 뒤 결과 기록(complete 단계) 중 저장소 응답 없음 — **결과 불명** | 503 | `IDEMPOTENCY_COMPLETION_UNKNOWN` | `true` | 없음 | "적용되지 않았다"고 알리지 않는다. **같은 키로** 나중에 다시 보낸다. 새 키 금지 |
|
||||||
| 이전 시도의 효과를 증명할 수 없음 | 500 | `IDEMPOTENCY_RECOVERY_REQUIRED` | `false` | 없음 | 재전송도 재실행도 안전하지 않다. 업무 데이터로 결과를 확인한다 |
|
| 이전 시도의 효과를 증명할 수 없음 | 500 | `IDEMPOTENCY_RECOVERY_REQUIRED` | `false` | 없음 | 자동 재시도하지 않는다. 결과는 업무 데이터로 확인한다. 같은 키로 나중에 다시 보내도 서버는 작업을 다시 돌리지 않는다 — 첫 시도가 늦게 끝났으면 그 결과를 재생하고, 아니면 다시 500이다. 새 키로 보내지 않는다 |
|
||||||
|
|
||||||
- **결과 불명이 무엇을 뜻하나.** 작업은 이미 돌았다. 유스케이스가 executor를 쓰기 트랜잭션 안에서
|
- **결과 불명이 무엇을 뜻하나.** 작업은 이미 돌았다. 유스케이스가 executor를 쓰기 트랜잭션 안에서
|
||||||
불렀다면 그 트랜잭션의 DB 변경은 예외와 함께 롤백된다. 작업이 자기 트랜잭션을 따로 커밋했다면 그 변경은
|
불렀다면 그 트랜잭션의 DB 변경은 예외와 함께 롤백된다. 작업이 자기 트랜잭션을 따로 커밋했다면 그 변경은
|
||||||
@@ -118,23 +118,28 @@ status는 코드 표(`HttpStatusErrorCodes`)에 있는 것만 그대로 나간
|
|||||||
503이어도 code가 다르다. 클라이언트는 status가 아니라 `error.code`로 가른다.
|
503이어도 code가 다르다. 클라이언트는 status가 아니라 `error.code`로 가른다.
|
||||||
- **같은 키로 다시 보내면 서버가 판정하고, 작업을 다시 돌리지 않는다.** 결과가 실제로는 기록됐으면
|
- **같은 키로 다시 보내면 서버가 판정하고, 작업을 다시 돌리지 않는다.** 결과가 실제로는 기록됐으면
|
||||||
재생(첫 요청의 성공 응답), 첫 시도의 processing lease(`processing-lease`, 기본 30s)가 아직 남았으면 409
|
재생(첫 요청의 성공 응답), 첫 시도의 processing lease(`processing-lease`, 기본 30s)가 아직 남았으면 409
|
||||||
`IDEMPOTENT_IN_FLIGHT`, lease가 지났으면 500 `IDEMPOTENCY_RECOVERY_REQUIRED`다. lease가 지난 실행 기록을 다음
|
`IDEMPOTENT_IN_FLIGHT`, lease가 지났으면 500 `IDEMPOTENCY_RECOVERY_REQUIRED`다. 새 키로 보내면 서버는 다른
|
||||||
요청이 만나면 두 저장소(PostgreSQL·Redis) 모두 넘겨주지 않고 포기(abandoned)로 표시한다 — 그 뒤 첫 시도가
|
요청으로 보고 막지 못한다(재리뷰 2026-11-03 README 4절 결정 RR-02-03, 2026-11-04 9.1절 결정 RR-01-11).
|
||||||
늦게 끝나도 결과는 기록되지 않고 그 요청도 500을 받는다. 새 키로 보내면 서버는 다른 요청으로 보고 막지 못한다
|
- **첫 시도가 lease보다 오래 걸려도 그 결과는 기록된다.** executor는 lease를 늘리지 않으므로 30s를 넘는
|
||||||
(재리뷰 2026-11-03 README 4절 결정 RR-02-03, 2026-11-04 9.1절 결정 RR-01-11).
|
정상 요청도 lease가 지난다. lease가 지난 실행 기록을 다음 요청이 만나면 두 저장소(PostgreSQL·Redis) 모두
|
||||||
|
500으로 답하고 기록은 건드리지 않는다. 첫 시도가 그 뒤에 끝나면 결과가 그대로 기록되고, 첫 요청은 자기
|
||||||
|
응답을 정상으로 받는다. 그 뒤 같은 키 요청은 그 결과를 재생한다. 첫 시도가 실패를 보고하면 그 실패가
|
||||||
|
기록된다(효과 불명이면 계속 500, 효과 없는 재시도 가능 실패면 다음 같은 키 요청이 다시 실행한다). 기록이
|
||||||
|
이미 사라진 뒤에 끝나면 결과를 기록하지 못해 첫 요청도 500 `IDEMPOTENCY_RECOVERY_REQUIRED`를 받는다
|
||||||
|
(2026-11-04 소유자 결정).
|
||||||
- **서버가 기억하는 기간.** 위 판정은 기록이 남아 있는 동안만 선다. 기록이 사라지면 같은 키는 새
|
- **서버가 기억하는 기간.** 위 판정은 기록이 남아 있는 동안만 선다. 기록이 사라지면 같은 키는 새
|
||||||
요청으로 실행된다. 기록의 수명은 시도가 어떻게 끝났는지로 갈린다.
|
요청으로 실행된다. 기록의 수명은 시도가 어떻게 끝났는지로 갈린다.
|
||||||
- 완료된 응답: 완료부터 `replay-ttl`(`APP_IDEMPOTENCY_TTL`, 기본 24h).
|
- 완료된 응답: 완료부터 `replay-ttl`(`APP_IDEMPOTENCY_TTL`, 기본 24h).
|
||||||
- 끝나지 않은 시도: claim부터 processing lease + `replay-ttl`. lease가 지나 다음 요청이 포기로 표시한
|
- 끝나지 않은 시도: claim부터 processing lease + `replay-ttl`. lease가 지난 실행 기록도 이 수명을 그대로
|
||||||
기록도 이 수명을 그대로 쓴다.
|
쓴다. 그 사이 첫 시도가 끝나면 그때부터 위(완료)나 아래(실패)의 수명으로 바뀐다.
|
||||||
- 실패로 표시된 시도: 작업이 예외를 던졌거나 효과 불명으로 끝나 포기(abandoned)된 시도, 효과 없이
|
- 실패로 표시된 시도: 작업이 예외를 던졌거나 효과 불명으로 끝나 포기(abandoned)된 시도, 효과 없이
|
||||||
재시도 가능으로 끝난 시도. 표시한 때부터 `failure-retention`(`APP_IDEMPOTENCY_FAILURE_RETENTION`,
|
재시도 가능으로 끝난 시도. 표시한 때부터 `failure-retention`(`APP_IDEMPOTENCY_FAILURE_RETENTION`,
|
||||||
기본 24h).
|
기본 24h).
|
||||||
|
|
||||||
`replay-ttl`이 `processing-lease`보다 짧으면 기동이 실패한다(재리뷰 2026-11-04 RR-03-11).
|
`replay-ttl`이 `processing-lease`보다 짧으면 기동이 실패한다(재리뷰 2026-11-04 RR-03-11).
|
||||||
`failure-retention`은 `replay-ttl`과 비교하지 않는다. 더 짧게 두면 효과 불명으로 포기한 기록이 그만큼
|
`failure-retention`이 `replay-ttl`보다 짧아도 기동이 실패한다. 더 짧으면 효과 불명으로 포기한 기록이 그만큼
|
||||||
먼저 사라지고, 그 뒤 같은 키 재전송은 작업을 다시 돌린다. 그래서 `replay-ttl` 이상으로 둔다
|
먼저 사라지고, 그 뒤 같은 키 재전송은 작업을 다시 돌린다(재리뷰 2026-11-04 RR3-03-02, 2026-11-04 소유자
|
||||||
(재리뷰 2026-11-04 RR3-03-02).
|
결정).
|
||||||
|
|
||||||
## 3. 헤더
|
## 3. 헤더
|
||||||
|
|
||||||
|
|||||||
+1
-1
@@ -128,7 +128,7 @@ APP_IDEMPOTENCY_TTL=24h
|
|||||||
APP_IDEMPOTENCY_PROVIDER=disabled
|
APP_IDEMPOTENCY_PROVIDER=disabled
|
||||||
APP_IDEMPOTENCY_REDIS_NAMESPACE_ENVIRONMENT=local
|
APP_IDEMPOTENCY_REDIS_NAMESPACE_ENVIRONMENT=local
|
||||||
APP_IDEMPOTENCY_PROCESSING_LEASE=30s
|
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_IDEMPOTENCY_FAILURE_RETENTION=24h
|
||||||
APP_LEASE_PROVIDER=disabled
|
APP_LEASE_PROVIDER=disabled
|
||||||
APP_LEASE_REDIS_NAMESPACE_ENVIRONMENT=local
|
APP_LEASE_REDIS_NAMESPACE_ENVIRONMENT=local
|
||||||
|
|||||||
@@ -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
|
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
|
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
|
program answers `RECOVERY_REQUIRED` and leaves the record as it is, because the holder may still be
|
||||||
complete it. The PostgreSQL store answers the same; the shared `IdempotencyStoreContract` holds both
|
running. The holder's late completion or failure goes through the transition program as it would
|
||||||
to it on a real server (re-review 2026-11-04 RR-01-11 — this store used to take the record over and
|
have inside the lease, and the next claim replays or retries it; only the lease is final — `RENEW`
|
||||||
run the work a second time).
|
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),
|
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
|
and a renewal stretches it to the new lease plus that margin. With the replay TTL alone, a replay
|
||||||
|
|||||||
+40
-14
@@ -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
|
* <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
|
* 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} —
|
* EXECUTING} has an unknown effect, so it is answered {@code RECOVERY_REQUIRED} — running it
|
||||||
* running it again is the duplicate this store exists to prevent, and it is what a client
|
* again is the duplicate this store exists to prevent, and it is what a client resending after a
|
||||||
* resending after a result-unknown 503 was promised would not happen (re-review 2026-11-04
|
* result-unknown 503 was promised would not happen (re-review 2026-11-04 RR-01-11). The answer
|
||||||
* RR-01-11). The PostgreSQL store answers the same; {@code IdempotencyStoreContract} holds both
|
* changes nothing: the holder may still be running, and its late completion or failure is
|
||||||
* to it.
|
* 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
|
* <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
|
* 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 leaseUntil = tonumber(redis.call('HGET', KEYS[1], 'leaseUntil'))
|
||||||
local leaseOver = leaseUntil ~= nil and leaseUntil <= nowMillis
|
local leaseOver = leaseUntil ~= nil and leaseUntil <= nowMillis
|
||||||
if state == 'EXECUTING' and leaseOver then
|
if state == 'EXECUTING' and leaseOver then
|
||||||
-- The holder started and its lease ran out: whether the work took effect is unknown.
|
-- The holder started and its lease ran out: whether the work took effect is unknown, so it
|
||||||
-- Abandon it, so the late holder cannot complete over the verdict, and keep the key's TTL:
|
-- is never run again. The record is left as it is — owner, revision, key TTL — because the
|
||||||
-- the record stays as evidence for its remaining afterLease window.
|
-- holder may still finish and record its result.
|
||||||
redis.call('HSET', KEYS[1], 'state', 'ABANDONED', 'rev', rev + 1)
|
return {'RECOVERY_REQUIRED', attempt, rev, owner, '', ''}
|
||||||
return {'RECOVERY_REQUIRED', attempt, rev + 1, owner, '', ''}
|
|
||||||
end
|
end
|
||||||
if state == 'FAILED_RETRYABLE' or (state == 'CLAIMED' and leaseOver) then
|
if state == 'FAILED_RETRYABLE' or (state == 'CLAIMED' and leaseOver) then
|
||||||
-- Nothing ran under the previous holder: they never started, or they marked the attempt
|
-- 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}
|
* 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
|
* existed has none and keeps only the lease. The TTL is only ever lengthened here — completion
|
||||||
* sets the replay TTL again.
|
* 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 =
|
private static final String RENEW =
|
||||||
"""
|
"""
|
||||||
@@ -207,6 +214,10 @@ public final class IdempotencyScripts {
|
|||||||
end
|
end
|
||||||
local t = redis.call('TIME')
|
local t = redis.call('TIME')
|
||||||
local nowMillis = (tonumber(t[1]) * 1000) + math.floor(tonumber(t[2]) / 1000)
|
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],
|
redis.call('HSET', KEYS[1],
|
||||||
'leaseUntil', nowMillis + tonumber(ARGV[4]), 'rev', rev + 1,
|
'leaseUntil', nowMillis + tonumber(ARGV[4]), 'rev', rev + 1,
|
||||||
'renewedFromRev', ARGV[2], 'renewedLease', ARGV[4])
|
'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
|
* 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
|
* {@code afterLease} — reading the lease off the TTL reported it a replay TTL too late (re-review
|
||||||
* 2026-11-04 RR3-03-05).
|
* 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 =
|
private static final String INSPECT =
|
||||||
"""
|
"""
|
||||||
@@ -273,7 +289,16 @@ public final class IdempotencyScripts {
|
|||||||
mine = 'OPERATION_CONFLICT'
|
mine = 'OPERATION_CONFLICT'
|
||||||
end
|
end
|
||||||
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 '',
|
redis.call('HGET', KEYS[1], 'resp') or '',
|
||||||
mine .. '|' .. tostring(redis.call('PTTL', KEYS[1])) .. '|'
|
mine .. '|' .. tostring(redis.call('PTTL', KEYS[1])) .. '|'
|
||||||
.. (redis.call('HGET', KEYS[1], 'leaseUntil') or '')}
|
.. (redis.call('HGET', KEYS[1], 'leaseUntil') or '')}
|
||||||
@@ -323,9 +348,10 @@ public final class IdempotencyScripts {
|
|||||||
/**
|
/**
|
||||||
* What a program answered, parsed once.
|
* What a program answered, parsed once.
|
||||||
*
|
*
|
||||||
* <p>The transition verdicts and, for {@code INSPECT}, the record's state. The programs speak in
|
* <p>The transition verdicts and, for {@code INSPECT}, the record's state (or {@code
|
||||||
* strings; the adapter speaks in this enum, so a misspelt status is a compile error rather than a
|
* RECOVERY_REQUIRED}, see {@link #INSPECT}). The programs speak in strings; the adapter speaks in
|
||||||
* {@code default} branch that quietly turns it into "unavailable".
|
* this enum, so a misspelt status is a compile error rather than a {@code default} branch that
|
||||||
|
* quietly turns it into "unavailable".
|
||||||
*/
|
*/
|
||||||
enum ScriptStatus {
|
enum ScriptStatus {
|
||||||
ACQUIRED,
|
ACQUIRED,
|
||||||
|
|||||||
+4
-1
@@ -391,7 +391,10 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
|
|||||||
Optional.of(now.plusMillis(Math.max(1, ttlMillis))));
|
Optional.of(now.plusMillis(Math.max(1, ttlMillis))));
|
||||||
case FAILED_RETRYABLE ->
|
case FAILED_RETRYABLE ->
|
||||||
IdempotencyInspection.outcome(IdempotencyInspectionOutcome.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 ->
|
case CLAIMED ->
|
||||||
"MINE".equals(ownership)
|
"MINE".equals(ownership)
|
||||||
? new IdempotencyInspection(
|
? new IdempotencyInspection(
|
||||||
|
|||||||
+40
-2
@@ -353,8 +353,8 @@ class RedisIdempotencyStoreAdapterTest {
|
|||||||
}
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
@DisplayName("lease가 지나 다른 요청이 회복 필요로 판정한 실행은 이전 owner가 renew할 수 없다")
|
@DisplayName("lease가 지나 다른 요청이 회복 필요로 판정한 실행은 주인이 renew로 lease를 되살릴 수 없다")
|
||||||
void anOwnerWhoseExpiredExecutionWasAbandonedCannotRenew() {
|
void anOwnerWhoseExecutionWasFoundExpiredCannotRenewItsLease() {
|
||||||
// given
|
// given
|
||||||
IdempotencyOwner executing = executing();
|
IdempotencyOwner executing = executing();
|
||||||
gateway.advance(Duration.ofSeconds(60));
|
gateway.advance(Duration.ofSeconds(60));
|
||||||
@@ -386,6 +386,44 @@ class RedisIdempotencyStoreAdapterTest {
|
|||||||
recovery -> assertThat(recovery.currentAttempt()).isEqualTo(executing.attempt()));
|
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
|
@Test
|
||||||
@DisplayName("an expired claim that never started can be taken over, and the attempt increments")
|
@DisplayName("an expired claim that never started can be taken over, and the attempt increments")
|
||||||
void anExpiredLeaseIsTakenOver() {
|
void anExpiredLeaseIsTakenOver() {
|
||||||
|
|||||||
@@ -233,8 +233,11 @@ failure translation contract 다. 여기서는 SPI 구조와 fallback 근거만
|
|||||||
지운다. 그래서 `expires_at` 이 lease 보다 먼저 오면 실행 중인 행이 지워지고 다음 claim 이 같은 작업을
|
지운다. 그래서 `expires_at` 이 lease 보다 먼저 오면 실행 중인 행이 지워지고 다음 claim 이 같은 작업을
|
||||||
다시 돌린다(재리뷰 2026-11-04 RR-03-11). 공유 계약의 PostgreSQL lane 은 시간을 흘린 뒤 이 reaper 를
|
다시 돌린다(재리뷰 2026-11-04 RR-03-11). 공유 계약의 PostgreSQL lane 은 시간을 흘린 뒤 이 reaper 를
|
||||||
실제로 돌려 이 경우를 본다. reaper 는 provider 가 `postgresql` 일 때만 돈다.
|
실제로 돌려 이 경우를 본다. reaper 는 provider 가 `postgresql` 일 때만 돈다.
|
||||||
- **lease 가 지난 실행**: lease 가 지난 `EXECUTING` 행은 넘겨받지 않고 `ABANDONED` 로 바꿔
|
- **lease 가 지난 실행**: lease 가 지난 `EXECUTING` 행은 넘겨받지 않고 `RecoveryRequired` 로 답하며,
|
||||||
`RecoveryRequired` 로 답한다. Redis store 도 같다(`IdempotencyStoreContract`, RR-01-11).
|
행은 바꾸지 않는다. 주인이 늦게 complete·markFailed 하면 그대로 기록되고, 다음 claim 은 그 결과를
|
||||||
|
재생하거나 재시도한다. renew 는 이미 끝난 lease 를 늘리지 않는다. inspect 는 남의 lease 지난 실행을
|
||||||
|
`ABANDONED` 로 보고한다. Redis store 도 같다(`IdempotencyStoreContract`, RR-01-11, 2026-11-04 소유자
|
||||||
|
결정 — 전에는 행을 `ABANDONED`·`EXPIRED_EXECUTION` 으로 바꿔 늦은 결과를 버렸다).
|
||||||
|
|
||||||
## outbox — `JpaOutboxStore` 외
|
## outbox — `JpaOutboxStore` 외
|
||||||
|
|
||||||
|
|||||||
+7
-40
@@ -6,12 +6,14 @@ import java.util.UUID;
|
|||||||
import org.springframework.jdbc.core.JdbcOperations;
|
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
|
* <p>Claiming is a different problem from advancing a claim already held. These two write the owner
|
||||||
* owner tuple itself — first insert, take-over, and the abandonment of an execution whose lease ran
|
* tuple itself — first insert and take-over — and both are races between processes. The transitions
|
||||||
* out — and every one of them is a race between processes. The transitions in {@link
|
* in {@link IdempotencyTransitionGateway} are races only against the owner's own retries. An
|
||||||
* IdempotencyTransitionGateway} are races only against the owner's own retries.
|
* 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
|
* <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
|
* 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 = ?
|
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;
|
private final JdbcOperations jdbc;
|
||||||
|
|
||||||
IdempotencyClaimGateway(JdbcOperations jdbc) {
|
IdempotencyClaimGateway(JdbcOperations jdbc) {
|
||||||
@@ -173,20 +156,4 @@ final class IdempotencyClaimGateway {
|
|||||||
static long recordLifetimeMillis(IdempotencyClaimRequest request) {
|
static long recordLifetimeMillis(IdempotencyClaimRequest request) {
|
||||||
return request.processingLeaseTtl().plus(request.replayTtl()).toMillis();
|
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());
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|||||||
+5
@@ -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}
|
* 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
|
* 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.
|
* 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 =
|
private static final String RENEW_SQL =
|
||||||
"""
|
"""
|
||||||
|
|||||||
+16
-10
@@ -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
|
* <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
|
* 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
|
* 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
|
* 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
|
* 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) {
|
if (row.state() == IdempotencyState.FAILED_RETRYABLE) {
|
||||||
return resetClaim(request, row);
|
return resetClaim(request, row);
|
||||||
}
|
}
|
||||||
if (row.state() == IdempotencyState.EXECUTING && !dbNow.isBefore(row.processingLeaseUntil())) {
|
// An execution whose lease ran out has an unknown effect, so it is never run again — and the
|
||||||
abandonExpiredExecution(row);
|
// 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());
|
return new IdempotencyClaimOutcome.RecoveryRequired(row.attempt());
|
||||||
}
|
}
|
||||||
if (row.state() == IdempotencyState.ABANDONED) {
|
if (row.state() == IdempotencyState.ABANDONED) {
|
||||||
@@ -415,6 +418,12 @@ public final class PostgreSqlIdempotencyStore implements IdempotencyStorePort {
|
|||||||
if (row.ownerToken().equals(request.claimAttempt().ownerToken()) && !sameAttempt) {
|
if (row.ownerToken().equals(request.claimAttempt().ownerToken()) && !sameAttempt) {
|
||||||
return IdempotencyInspection.outcome(IdempotencyInspectionOutcome.OPERATION_CONFLICT);
|
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()) {
|
return switch (row.state()) {
|
||||||
case FAILED_RETRYABLE ->
|
case FAILED_RETRYABLE ->
|
||||||
IdempotencyInspection.outcome(IdempotencyInspectionOutcome.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());
|
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
|
// 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
|
// and the in-memory fake answer (IdempotencyStoreContract). OPERATION_CONFLICT keeps its one
|
||||||
// meaning: the same operation id already applied this transition with different arguments.
|
// meaning: the same operation id already applied this transition with different arguments.
|
||||||
@@ -586,6 +588,10 @@ public final class PostgreSqlIdempotencyStore implements IdempotencyStorePort {
|
|||||||
DIFFERENT_ARGUMENTS
|
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) {
|
private static boolean isExpiredCompleted(IdempotencyRecordRow row, Instant dbNow) {
|
||||||
return row.state() == IdempotencyState.COMPLETED
|
return row.state() == IdempotencyState.COMPLETED
|
||||||
&& row.replayUntil() != null
|
&& row.replayUntil() != null
|
||||||
|
|||||||
+5
-3
@@ -189,9 +189,11 @@ class PostgreSqlIdempotencyIntegrationTest {
|
|||||||
.isInstanceOfSatisfying(
|
.isInstanceOfSatisfying(
|
||||||
IdempotencyClaimOutcome.RecoveryRequired.class,
|
IdempotencyClaimOutcome.RecoveryRequired.class,
|
||||||
recovery -> assertThat(recovery.currentAttempt()).isEqualTo(executing.attempt()));
|
recovery -> assertThat(recovery.currentAttempt()).isEqualTo(executing.attempt()));
|
||||||
assertThat(
|
// The claim leaves the row to its holder, which may still finish and record its result (owner
|
||||||
store.inspect(new IdempotencyInspectionRequest(SCOPE, FINGERPRINT, original)).outcome())
|
// decision 2026-11-04): the holder still finds its own execution, unchanged.
|
||||||
.isEqualTo(IdempotencyInspectionOutcome.ABANDONED);
|
var holder = store.inspect(new IdempotencyInspectionRequest(SCOPE, FINGERPRINT, original));
|
||||||
|
assertThat(holder.outcome()).isEqualTo(IdempotencyInspectionOutcome.EXECUTING_SAME_OPERATION);
|
||||||
|
assertThat(holder.owner()).contains(executing);
|
||||||
}
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
|
|||||||
+16
-6
@@ -224,12 +224,11 @@ public final class InMemorySemanticRedisCommands implements SemanticRedisCommand
|
|||||||
}
|
}
|
||||||
long leaseUntil = Long.parseLong(field(rendered, "leaseUntil"));
|
long leaseUntil = Long.parseLong(field(rendered, "leaseUntil"));
|
||||||
boolean leaseOver = leaseUntil <= nowMillis;
|
boolean leaseOver = leaseUntil <= nowMillis;
|
||||||
// As the program: an expired EXECUTING record has an unknown effect, so it is abandoned and
|
// As the program: an expired EXECUTING record has an unknown effect, so it is answered
|
||||||
// answered RECOVERY_REQUIRED, never taken over (re-review 2026-11-04 RR-01-11).
|
// 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) {
|
if ("EXECUTING".equals(state) && leaseOver) {
|
||||||
setField(rendered, "state", "ABANDONED");
|
return reply("RECOVERY_REQUIRED", attempt, rev, owner, "", "");
|
||||||
setField(rendered, "rev", Long.toString(rev + 1));
|
|
||||||
return reply("RECOVERY_REQUIRED", attempt, rev + 1, owner, "", "");
|
|
||||||
}
|
}
|
||||||
if ("FAILED_RETRYABLE".equals(state) || ("CLAIMED".equals(state) && leaseOver)) {
|
if ("FAILED_RETRYABLE".equals(state) || ("CLAIMED".equals(state) && leaseOver)) {
|
||||||
setField(rendered, "state", "CLAIMED");
|
setField(rendered, "state", "CLAIMED");
|
||||||
@@ -322,6 +321,10 @@ public final class InMemorySemanticRedisCommands implements SemanticRedisCommand
|
|||||||
if (!"EXECUTING".equals(state)) {
|
if (!"EXECUTING".equals(state)) {
|
||||||
return reply("WRONG_STATE", attempt, rev, owner, 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, "leaseUntil", Long.toString(now() + Long.parseLong(leaseMillis)));
|
||||||
setField(rendered, "rev", Long.toString(rev + 1));
|
setField(rendered, "rev", Long.toString(rev + 1));
|
||||||
setField(rendered, "renewedFromRev", handleRevision);
|
setField(rendered, "renewedFromRev", handleRevision);
|
||||||
@@ -372,8 +375,15 @@ public final class InMemorySemanticRedisCommands implements SemanticRedisCommand
|
|||||||
}
|
}
|
||||||
String stored = field(rendered, "resp");
|
String stored = field(rendered, "resp");
|
||||||
String leaseUntil = field(rendered, "leaseUntil");
|
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(
|
return reply(
|
||||||
state,
|
expiredExecution ? "RECOVERY_REQUIRED" : state,
|
||||||
attempt,
|
attempt,
|
||||||
rev,
|
rev,
|
||||||
owner,
|
owner,
|
||||||
|
|||||||
@@ -263,15 +263,17 @@ generation; the V1 `IdempotencyScope`/`tryBegin` API is gone.
|
|||||||
`persistence-jpa`; default `disabled`). In-memory prod storage is forbidden.
|
`persistence-jpa`; default `disabled`). In-memory prod storage is forbidden.
|
||||||
- **Executor**: built once by `composition:idempotency` `IdempotencyAutoConfiguration` from
|
- **Executor**: built once by `composition:idempotency` `IdempotencyAutoConfiguration` from
|
||||||
`IdempotencySettings` (processing lease 30s, replay TTL `APP_IDEMPOTENCY_TTL` 24h ≤72h and not
|
`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` /
|
- The action returns `IdempotentAction.Outcome` (`Success` / `RetryableNoEffect` /
|
||||||
`EffectUnknown`); a thrown exception counts as effect-unknown. In progress → 409
|
`EffectUnknown`); a thrown exception counts as effect-unknown. In progress → 409
|
||||||
`IDEMPOTENT_IN_FLIGHT`, fingerprint mismatch (SHA-256) → 422 `IDEMPOTENT_REQUEST_MISMATCH`;
|
`IDEMPOTENT_IN_FLIGHT`, fingerprint mismatch (SHA-256) → 422 `IDEMPOTENT_REQUEST_MISMATCH`;
|
||||||
`IdempotencyUnavailableException` and `IdempotencyRecoveryRequiredException` mean the store
|
`IdempotencyUnavailableException` and `IdempotencyRecoveryRequiredException` mean the store
|
||||||
could not prove the outcome, so do not blindly retry.
|
could not prove the outcome, so do not blindly retry.
|
||||||
- Every store answers an execution whose processing lease ran out with `RecoveryRequired` and never
|
- 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
|
takes it over; only a claim that never started or a retryable failure is taken over. The answer
|
||||||
for the lease plus the replay TTL. `IdempotencyStoreContract` holds Redis and PostgreSQL to both on
|
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
|
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).
|
(re-review 2026-11-04 RR-01-11, RR-03-11, RR3-03-04).
|
||||||
|
|
||||||
|
|||||||
@@ -268,9 +268,10 @@ application 계층이 claim·replay·복구 **정책** 을 소유하고, 저장
|
|||||||
실패로 기록하고, `EffectUnknown` 이나 그냥 던진 예외는 "효과 불명"(`ABANDONED`)으로 남긴다.
|
실패로 기록하고, `EffectUnknown` 이나 그냥 던진 예외는 "효과 불명"(`ABANDONED`)으로 남긴다.
|
||||||
한 번 실행됐을지 모르는 작업을 재시도로 두 번 돌리지 않기 위해서다.
|
한 번 실행됐을지 모르는 작업을 재시도로 두 번 돌리지 않기 위해서다.
|
||||||
- processing lease 와 replay TTL 은 따로 간다. 만료된 `CLAIMED` 만 다른 caller 가 가져갈 수 있고,
|
- processing lease 와 replay TTL 은 따로 간다. 만료된 `CLAIMED` 만 다른 caller 가 가져갈 수 있고,
|
||||||
만료된 `EXECUTING` 은 `RECOVERY_REQUIRED` 로 닫는다.
|
만료된 `EXECUTING` 은 다른 caller 에게 `RECOVERY_REQUIRED` 로 답하되 기록은 그대로 둔다. 주인이 늦게
|
||||||
|
보고한 결과·실패는 기록된다(2026-11-04 소유자 결정).
|
||||||
- 생성은 app-bootstrap `IdempotencyProviderSelectionConfig` 가 한 번 한다(`IdempotencySettings`:
|
- 생성은 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). 유스케이스나 샘플 설정이 직접 만들지 않는다.
|
policy revision 2). 유스케이스나 샘플 설정이 직접 만들지 않는다.
|
||||||
- 이 계약은 요청 재생(replay) 근거를 남길 뿐이다. store 와 비즈니스 DB 사이의 exactly-once 를
|
- 이 계약은 요청 재생(replay) 근거를 남길 뿐이다. store 와 비즈니스 DB 사이의 exactly-once 를
|
||||||
보장하지 않는다.
|
보장하지 않는다.
|
||||||
|
|||||||
+4
@@ -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
|
* 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
|
* 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.
|
* 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 {
|
record RecoveryRequired(long currentAttempt) implements IdempotencyClaimOutcome {
|
||||||
public RecoveryRequired {
|
public RecoveryRequired {
|
||||||
|
|||||||
+12
-2
@@ -8,6 +8,12 @@ import java.util.Optional;
|
|||||||
/**
|
/**
|
||||||
* Owner-safe request-replay lifecycle over {@link IdempotencyStorePort}.
|
* 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
|
* <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.
|
* 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
|
* 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.
|
* Creates the executor.
|
||||||
*
|
*
|
||||||
* @param store the owner-safe store
|
* @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 replayTtl how long a completed response is replayable
|
||||||
* @param failureRetention how long a failed attempt's evidence is kept
|
* @param failureRetention how long a failed attempt's evidence is kept
|
||||||
* @param responseCodecId the identifier of the codec the stored payload was written with
|
* @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);
|
startAndRun(request, replayed.owner(), action, codec, false);
|
||||||
// Only a claim that never started or failed without effect is taken over, so running here is
|
// 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
|
// 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 ->
|
case IdempotencyClaimOutcome.TakenOverClaimed takenOver ->
|
||||||
startAndRun(request, takenOver.owner(), action, codec, false);
|
startAndRun(request, takenOver.owner(), action, codec, false);
|
||||||
};
|
};
|
||||||
|
|||||||
+6
@@ -8,6 +8,12 @@ public enum IdempotencyInspectionOutcome {
|
|||||||
COMPLETED_REPLAY,
|
COMPLETED_REPLAY,
|
||||||
IN_PROGRESS_OTHER,
|
IN_PROGRESS_OTHER,
|
||||||
FAILED_RETRYABLE,
|
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,
|
ABANDONED,
|
||||||
FINGERPRINT_MISMATCH,
|
FINGERPRINT_MISMATCH,
|
||||||
OPERATION_CONFLICT,
|
OPERATION_CONFLICT,
|
||||||
|
|||||||
+9
@@ -8,6 +8,15 @@ import java.time.Duration;
|
|||||||
*
|
*
|
||||||
* <p>Providers (Redis, PostgreSQL) contribute only this store; the {@link IdempotencyExecutor} that
|
* <p>Providers (Redis, PostgreSQL) contribute only this store; the {@link IdempotencyExecutor} that
|
||||||
* drives it is assembled once by the composition root.
|
* 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 {
|
public interface IdempotencyStorePort {
|
||||||
|
|
||||||
|
|||||||
+117
-3
@@ -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
|
* 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
|
* 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);
|
* 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
|
* <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
|
* 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
|
* 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
|
@Test
|
||||||
@DisplayName("lease가 지나 회복 필요로 판정된 실행은 원래 holder가 늦게 complete해도 기록되지 않는다")
|
@DisplayName("lease가 지난 실행을 만난 claim은 회복 필요로 답하고 기록은 실행 중인 주인의 것으로 그대로 둔다")
|
||||||
void anExecutionFoundExpiredCannotBeCompletedByItsLateHolder() {
|
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
|
// given
|
||||||
IdempotencyStorePort store = subject();
|
IdempotencyStorePort store = subject();
|
||||||
Duration lease = processingLease();
|
Duration lease = processingLease();
|
||||||
@@ -499,7 +528,92 @@ public abstract class IdempotencyStoreContract {
|
|||||||
store.complete(late, new StoredResponse("{}"), Duration.ofHours(1), OPERATION);
|
store.complete(late, new StoredResponse("{}"), Duration.ofHours(1), OPERATION);
|
||||||
|
|
||||||
// then
|
// 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
|
@Test
|
||||||
|
|||||||
@@ -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.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.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-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.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.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) |
|
| `ca.config-contract` | app-bootstrap's `verifyEnvKeys` (moved from the deleted build-tools included build; owner decision 4 keeps the task in app-bootstrap) |
|
||||||
|
|||||||
+46
-10
@@ -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
|
* <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
|
* 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,
|
* — its step's {@code working-directory}, moved by the {@code cd} commands the same shell surely
|
||||||
* which is where GitHub keeps {@code .github/workflows}. Applied to the main build only, it said
|
* ran before it, joined with its {@code -p}, from the repository root, which is where GitHub keeps
|
||||||
* "every strict lane" while the optional build's performance lane ran nowhere (RR-06-03).</p>
|
* {@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
|
* <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
|
* {@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,
|
File workflowDirectory,
|
||||||
String buildDirectory) {
|
String buildDirectory) {
|
||||||
List<String> problems = new ArrayList<>(foldedCommandBreaks(workflowDirectory));
|
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
|
// 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.
|
// up — and only as the command runs it: what its -x removes is not covered.
|
||||||
Map<String, Set<String>> tasksByProject = new LinkedHashMap<>();
|
Map<String, Set<String>> tasksByProject = new LinkedHashMap<>();
|
||||||
@@ -141,9 +147,11 @@ public final class StrictLaneStagesPlugin implements Plugin<Project> {
|
|||||||
+ workflowDirectory.getName()
|
+ workflowDirectory.getName()
|
||||||
+ " for the build in "
|
+ " for the build in "
|
||||||
+ buildDirectory
|
+ buildDirectory
|
||||||
+ " (a --dry-run, a command started in another directory, a command under"
|
+ " (a --dry-run, a command started in another directory, a command after a cd this"
|
||||||
+ " continue-on-error or an if: other than always()/success()/!cancelled(), and a"
|
+ " check does not follow, a command under continue-on-error or an if: other than"
|
||||||
+ " workflow that starts only on workflow_dispatch do not count)");
|
+ " always()/success()/!cancelled(), and a workflow that starts only on"
|
||||||
|
+ " workflow_dispatch do not count)"
|
||||||
|
+ notCounted(invocationsByWorkflow, stage));
|
||||||
continue;
|
continue;
|
||||||
}
|
}
|
||||||
Task stageTask = root.getTasks().findByPath(stage);
|
Task stageTask = root.getTasks().findByPath(stage);
|
||||||
@@ -179,6 +187,31 @@ public final class StrictLaneStagesPlugin implements Plugin<Project> {
|
|||||||
return problems;
|
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. */
|
/** 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) {
|
private static Set<String> plan(TaskExecutionGraph graph, Task stage, Set<String> excluded) {
|
||||||
Set<String> seen = new HashSet<>();
|
Set<String> seen = new HashSet<>();
|
||||||
@@ -219,11 +252,14 @@ public final class StrictLaneStagesPlugin implements Plugin<Project> {
|
|||||||
return files;
|
return files;
|
||||||
}
|
}
|
||||||
|
|
||||||
private static List<WorkflowGradleInvocations.Invocation> invocations(File workflowDirectory) {
|
/** Each workflow file's Gradle commands, by file name, in file order. */
|
||||||
List<WorkflowGradleInvocations.Invocation> invocations = new ArrayList<>();
|
private static Map<String, List<WorkflowGradleInvocations.Invocation>> invocations(
|
||||||
|
File workflowDirectory) {
|
||||||
|
Map<String, List<WorkflowGradleInvocations.Invocation>> invocations = new LinkedHashMap<>();
|
||||||
for (File file : workflowFiles(workflowDirectory)) {
|
for (File file : workflowFiles(workflowDirectory)) {
|
||||||
try {
|
try {
|
||||||
invocations.addAll(
|
invocations.put(
|
||||||
|
file.getName(),
|
||||||
WorkflowGradleInvocations.read(Files.readString(file.toPath(), StandardCharsets.UTF_8)));
|
WorkflowGradleInvocations.read(Files.readString(file.toPath(), StandardCharsets.UTF_8)));
|
||||||
} catch (IOException exception) {
|
} catch (IOException exception) {
|
||||||
throw new UncheckedIOException("failed to read " + file, exception);
|
throw new UncheckedIOException("failed to read " + file, exception);
|
||||||
|
|||||||
+217
-17
@@ -29,9 +29,19 @@ import java.util.regex.Pattern;
|
|||||||
* (review 2026-11-04 RR2-04-04).
|
* (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
|
* <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
|
* job's or the workflow's {@code defaults.run.working-directory}), then each {@code cd} the same
|
||||||
* {@code -pdir} and {@code --project-dir}), as a path from the repository root. A {@code run:} that
|
* shell ran before it, then its {@code -p} (also {@code -pdir} and {@code --project-dir}), as a
|
||||||
* is an input of a {@code uses:} step ({@code with: run:}) is not a shell command and is not read.
|
* 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 {
|
public final class WorkflowGradleInvocations {
|
||||||
private static final Pattern RUN_KEY = Pattern.compile("^(\\s*)(?:-\\s+)?run:(.*)$");
|
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. */
|
/** Conditions under which a step still runs on every run whose earlier steps passed. */
|
||||||
private static final Set<String> STATUS_CONDITIONS =
|
private static final Set<String> STATUS_CONDITIONS =
|
||||||
Set.of("always()", "success()", "!cancelled()", "true");
|
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 =
|
private static final Set<String> OPTIONS_WITH_VALUE =
|
||||||
Set.of(
|
Set.of(
|
||||||
"-p",
|
"-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 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 excludedTasks the {@code -x} / {@code --exclude-task} selectors, in order
|
||||||
* @param uncountedReason why the command gates nothing although it runs — {@code
|
* @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(
|
public record Invocation(
|
||||||
String workingDirectory,
|
String workingDirectory,
|
||||||
@@ -107,11 +132,16 @@ public final class WorkflowGradleInvocations {
|
|||||||
* the repository root such as {@code src}.
|
* the repository root such as {@code src}.
|
||||||
*/
|
*/
|
||||||
public boolean executes(String taskPath, String buildDirectory) {
|
public boolean executes(String taskPath, String buildDirectory) {
|
||||||
String wanted = absolute(taskPath);
|
|
||||||
return buildDirectory().equals(normalized(buildDirectory))
|
return buildDirectory().equals(normalized(buildDirectory))
|
||||||
&& !dryRun
|
&& !dryRun
|
||||||
&& uncountedReason == null
|
&& 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. */
|
/** 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) {
|
public static List<Invocation> read(String workflow) {
|
||||||
List<Invocation> invocations = new ArrayList<>();
|
List<Invocation> invocations = new ArrayList<>();
|
||||||
for (RunStep step : runSteps(workflow)) {
|
for (RunStep step : runSteps(workflow)) {
|
||||||
for (String command : shellCommands(step.script())) {
|
invocations.addAll(stepInvocations(step));
|
||||||
Invocation invocation =
|
}
|
||||||
gradleInvocation(command, step.workingDirectory(), step.uncountedReason());
|
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) {
|
if (invocation != null) {
|
||||||
invocations.add(invocation);
|
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;
|
return plain;
|
||||||
}
|
}
|
||||||
|
|
||||||
private static List<String> shellCommands(String script) {
|
/**
|
||||||
String joined = script.replace("\\\n", " ");
|
* The script as shell lists: a list ends at {@code ;} or at a line end that does not follow an
|
||||||
List<String> commands = new ArrayList<>();
|
* operator, and its commands are joined by {@code &&}, {@code ||} or {@code |}. Comments are
|
||||||
for (String line : joined.split("\n", -1)) {
|
* dropped first, so a separator inside one splits nothing.
|
||||||
for (String command : line.split(";|&&|\\|\\||\\|")) {
|
*/
|
||||||
commands.add(command);
|
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(
|
private static Invocation gradleInvocation(
|
||||||
|
|||||||
+53
@@ -441,6 +441,59 @@ class StrictLaneStagesFunctionalTest {
|
|||||||
assertThat(result.getOutput()).contains("stage :integrationCheck is executed by no workflow");
|
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 {
|
private void leafLanes(String lanes) throws Exception {
|
||||||
Files.writeString(
|
Files.writeString(
|
||||||
gradleRoot.resolve("leaf/build.gradle"),
|
gradleRoot.resolve("leaf/build.gradle"),
|
||||||
|
|||||||
+105
@@ -392,6 +392,111 @@ class WorkflowGradleInvocationsTest {
|
|||||||
assertThat(invocations.get(1).executes(":releaseCheck", "src")).isTrue();
|
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
|
@Test
|
||||||
@DisplayName("uses 단계의 with 입력에 적힌 run은 셸 명령이 아니므로 읽지 않는다")
|
@DisplayName("uses 단계의 with 입력에 적힌 run은 셸 명령이 아니므로 읽지 않는다")
|
||||||
void aRunInputOfAnActionIsNotAShellCommand() {
|
void aRunInputOfAnActionIsNotAShellCommand() {
|
||||||
|
|||||||
@@ -45,7 +45,7 @@ executor, 설정 기본값이 함께 빠진다(그때 KEYED use case는 executor
|
|||||||
| 언제 | 키 |
|
| 언제 | 키 |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
| 켤 때 | `APP_IDEMPOTENCY_PROVIDER` (`redis` 또는 `postgresql`), 그리고 그 provider 모듈의 줄과 env |
|
| 켤 때 | `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에서 옮김)
|
## 설계 결정 참조 (app-bootstrap에서 옮김)
|
||||||
|
|
||||||
@@ -74,7 +74,7 @@ executor, 설정 기본값이 함께 빠진다(그때 KEYED use case는 executor
|
|||||||
| `provider` | `APP_IDEMPOTENCY_PROVIDER` | `disabled` | `disabled` \| `redis` \| `postgresql` |
|
| `provider` | `APP_IDEMPOTENCY_PROVIDER` | `disabled` | `disabled` \| `redis` \| `postgresql` |
|
||||||
| `processing-lease` | `APP_IDEMPOTENCY_PROCESSING_LEASE` | 30s | 1h |
|
| `processing-lease` | `APP_IDEMPOTENCY_PROCESSING_LEASE` | 30s | 1h |
|
||||||
| `replay-ttl` | `APP_IDEMPOTENCY_TTL` | 24h | 72h, 그리고 `processing-lease` 이상 |
|
| `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자 |
|
| `response-codec-id` | — | `json-v2` | 1–64자 |
|
||||||
| `policy-revision` | — | 2 | 양수 |
|
| `policy-revision` | — | 2 | 양수 |
|
||||||
| `reaper-interval` | — | 10m | 양수 |
|
| `reaper-interval` | — | 10m | 양수 |
|
||||||
@@ -87,10 +87,11 @@ executor, 설정 기본값이 함께 빠진다(그때 KEYED use case는 executor
|
|||||||
둔다 — 이 검사는 store 를 지키는 것이 아니라 재생을 무력하게 만드는 정책을 막는다.
|
둔다 — 이 검사는 store 를 지키는 것이 아니라 재생을 무력하게 만드는 정책을 막는다.
|
||||||
`IdempotencyClaimRequest` 에는 두지 않았다: 포트는 어떤 값 쌍으로도 쓸 수 있고, store 가 모든 쌍에서
|
`IdempotencyClaimRequest` 에는 두지 않았다: 포트는 어떤 값 쌍으로도 쓸 수 있고, store 가 모든 쌍에서
|
||||||
안전한지는 공유 계약이 본다.
|
안전한지는 공유 계약이 본다.
|
||||||
- **`failure-retention` 은 `replay-ttl` 과 비교하지 않는다.** 실패로 표시된 기록(포기·재시도 가능)은 표시부터
|
- **`failure-retention` 이 `replay-ttl` 보다 짧으면 기동을 거부한다.** 실패로 표시된 기록(포기·재시도
|
||||||
이 기간만 남는다. `replay-ttl` 보다 짧으면 효과 불명으로 포기한 기록이 먼저 사라져 같은 키 재전송이 작업을
|
가능)은 표시부터 이 기간만 남는다. `replay-ttl` 보다 짧으면 효과 불명으로 포기한 기록이 먼저 사라져 같은
|
||||||
다시 돌리므로 운영 값은 `replay-ttl` 이상으로 둔다. 기동 검사로 막지 않은 이유: 지금 기동하는 설정을 이
|
키 재전송이 작업을 다시 돌린다. 메시지는 두 키와 값을 함께 보여 준다. 기본값(둘 다 24h)은 그대로 뜬다.
|
||||||
라운드에서 실패로 바꾸지 않는다 — 검사 추가는 소유자 결정으로 남겼다(재리뷰 2026-11-04 RR3-03-02).
|
재리뷰 RR3-03-02 때는 지금 기동하는 설정을 깨지 않으려고 문서로만 두었고, 2026-11-04 소유자 결정으로
|
||||||
|
검사를 넣었다.
|
||||||
- **상한 검사는 컴팩트 생성자에서 fail-fast 로 던진다.** `Duration`의 상한은 JSR-303(`@Valid`)
|
- **상한 검사는 컴팩트 생성자에서 fail-fast 로 던진다.** `Duration`의 상한은 JSR-303(`@Valid`)
|
||||||
애너테이션으로 표현할 수 없어 생성자에서 직접 검증한다. 검증을 느슨하게 두면 과도하게 긴 TTL 이
|
애너테이션으로 표현할 수 없어 생성자에서 직접 검증한다. 검증을 느슨하게 두면 과도하게 긴 TTL 이
|
||||||
저장소를 조용히 부풀리고 멱등성 키 추측 공격의 유효 시간 창을 넓히기 때문에, 부팅 시점에 즉시
|
저장소를 조용히 부풀리고 멱등성 키 추측 공격의 유효 시간 창을 넓히기 때문에, 부팅 시점에 즉시
|
||||||
|
|||||||
+17
-1
@@ -23,7 +23,8 @@ import org.springframework.core.env.Environment;
|
|||||||
* IdempotencyExecutor#IN_FLIGHT_RETRY_AFTER})
|
* IdempotencyExecutor#IN_FLIGHT_RETRY_AFTER})
|
||||||
* @param replayTtl how long a completed response is replayable (at most 72h, D6), and no shorter
|
* @param replayTtl how long a completed response is replayable (at most 72h, D6), and no shorter
|
||||||
* than {@code processingLease}
|
* 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 responseCodecId identifier of the codec the stored payload is written with
|
||||||
* @param policyRevision replay policy revision written into and compared on each record
|
* @param policyRevision replay policy revision written into and compared on each record
|
||||||
* @param reaperInterval how often the PostgreSQL provider purges expired rows
|
* @param reaperInterval how often the PostgreSQL provider purges expired rows
|
||||||
@@ -83,6 +84,21 @@ public record IdempotencySettings(
|
|||||||
"failure-retention",
|
"failure-retention",
|
||||||
orDefault(failureRetention, Duration.ofHours(24)),
|
orDefault(failureRetention, Duration.ofHours(24)),
|
||||||
MAX_FAILURE_RETENTION);
|
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 =
|
reaperInterval =
|
||||||
bounded("reaper-interval", orDefault(reaperInterval, Duration.ofMinutes(10)), null);
|
bounded("reaper-interval", orDefault(reaperInterval, Duration.ofMinutes(10)), null);
|
||||||
responseCodecId = responseCodecId == null ? "json-v2" : responseCodecId;
|
responseCodecId = responseCodecId == null ? "json-v2" : responseCodecId;
|
||||||
|
|||||||
+49
-2
@@ -47,7 +47,7 @@ class IdempotencySettingsTest {
|
|||||||
.withProperty(PREFIX + "provider", "postgresql")
|
.withProperty(PREFIX + "provider", "postgresql")
|
||||||
.withProperty(PREFIX + "processing-lease", "45s")
|
.withProperty(PREFIX + "processing-lease", "45s")
|
||||||
.withProperty(PREFIX + "replay-ttl", "72h")
|
.withProperty(PREFIX + "replay-ttl", "72h")
|
||||||
.withProperty(PREFIX + "failure-retention", "2h")
|
.withProperty(PREFIX + "failure-retention", "100h")
|
||||||
.withProperty(PREFIX + "response-codec-id", "json-v3")
|
.withProperty(PREFIX + "response-codec-id", "json-v3")
|
||||||
.withProperty(PREFIX + "policy-revision", "3")
|
.withProperty(PREFIX + "policy-revision", "3")
|
||||||
.withProperty(PREFIX + "reaper-interval", "1m");
|
.withProperty(PREFIX + "reaper-interval", "1m");
|
||||||
@@ -63,7 +63,7 @@ class IdempotencySettingsTest {
|
|||||||
IdempotencySettings.Provider.POSTGRESQL,
|
IdempotencySettings.Provider.POSTGRESQL,
|
||||||
Duration.ofSeconds(45),
|
Duration.ofSeconds(45),
|
||||||
Duration.ofHours(72),
|
Duration.ofHours(72),
|
||||||
Duration.ofHours(2),
|
Duration.ofHours(100),
|
||||||
"json-v3",
|
"json-v3",
|
||||||
3,
|
3,
|
||||||
Duration.ofMinutes(1)));
|
Duration.ofMinutes(1)));
|
||||||
@@ -201,6 +201,53 @@ class IdempotencySettingsTest {
|
|||||||
"app.capabilities.idempotency.replay-ttl must not be shorter than processing-lease");
|
"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
|
@Test
|
||||||
@DisplayName("replay-ttl이 processing-lease와 같으면 받아들인다")
|
@DisplayName("replay-ttl이 processing-lease와 같으면 받아들인다")
|
||||||
void aReplayTtlEqualToTheProcessingLeaseIsAccepted() {
|
void aReplayTtlEqualToTheProcessingLeaseIsAccepted() {
|
||||||
|
|||||||
Reference in New Issue
Block a user