Merge remote-tracking branch 'origin/claude/t5-idempotency-operation-id-9bd973' into claude/integration-r7

This commit is contained in:
DongHyeonka
2026-11-06 22:56:39 +09:00
20 changed files with 437 additions and 47 deletions
@@ -287,6 +287,15 @@ A lost renewal reply is recognised by what the renewal recorded — the revision
the lease it asked for: the same lease is `ALREADY_RENEWED_SAME_OPERATION` with the current handle,
a different lease is `OPERATION_CONFLICT`.
Every program compares the operation a call names with the one the record was claimed under, right
after the owner token: another operation is `OPERATION_CONFLICT` and changes nothing. The PostgreSQL
store and the in-memory fake used to apply it; they now answer the same (owner decision 2026-11-06,
`IdempotencyStoreContract`). The release program also checks the handle's revision, as the
transition does: owner token and operation alone let the handle from before the same attempt took
its claim over release the claim it holds now. A release deletes the record, so a release that finds
no record — its own retry, an expired record, one never claimed — is `ABSENT`; it used to be
confirmed as `ALREADY_RELEASED_SAME_OPERATION`, which the store cannot know.
A lease that runs out is taken over only from a claim that never started or an attempt marked
retryable — by whoever claims next, the holder's own attempt included: the claim program checks for
a takeover before it replays a same-owner claim, so an attempt whose start was refused takes its
@@ -267,7 +267,15 @@ public final class IdempotencyScripts {
return {'APPLIED', attempt, rev + 1, owner, '', ''}
""";
/** Release before execution: only from CLAIMED, and only by the owner that holds it. */
/**
* Release before execution: only from CLAIMED, and only by the owner that holds it at the
* revision its handle carries.
*
* <p>The release deletes the record, so a retry finds nothing and is {@code ABSENT}, as is a
* release whose record expired. The revision is checked as in {@link #TRANSITION}: the owner
* token and operation alone let the handle from before the same attempt took its claim over
* release the claim it holds now ({@code IdempotencyStoreContract}).
*/
private static final String RELEASE =
"""
local state = redis.call('HGET', KEYS[1], 'state')
@@ -284,6 +292,9 @@ public final class IdempotencyScripts {
if op ~= ARGV[3] then
return {'OPERATION_CONFLICT', attempt, rev, owner, '', ''}
end
if rev ~= tonumber(ARGV[2]) then
return {'NOT_OWNER', attempt, rev, owner, '', ''}
end
if state ~= 'CLAIMED' then
return {'WRONG_STATE', attempt, rev, owner, state, ''}
end
@@ -320,7 +320,10 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
operationId.value())));
return switch (reply.status()) {
case APPLIED -> IdempotencyReleaseOutcome.RELEASED_BEFORE_EXECUTION;
case ABSENT -> IdempotencyReleaseOutcome.ALREADY_RELEASED_SAME_OPERATION;
// The release deletes the record, so nothing tells this release's retry from a record
// that expired or was never there. It was confirmed as the release already applied;
// the PostgreSQL store answers a missing record ABSENT (IdempotencyStoreContract).
case ABSENT -> IdempotencyReleaseOutcome.ABSENT;
case NOT_OWNER -> IdempotencyReleaseOutcome.NOT_OWNER;
case OPERATION_CONFLICT -> IdempotencyReleaseOutcome.OPERATION_CONFLICT;
case WRONG_STATE -> IdempotencyReleaseOutcome.EXECUTION_ALREADY_STARTED;
@@ -437,8 +437,13 @@ RR6-02-01). raw client key는 저장하지 않고 versioned HMAC scope digest만
Redis store·in-memory fake와 같은 계약(`IdempotencyStoreContract`)을 실 PostgreSQL에서 통과한다
(`PostgreSqlIdempotencyStoreContractTest`, `jpaPlatformContractTest`). 그 계약에 맞춰 두 가지를
정했다(review 2026-11-01 01-05). 이전 revision의 핸들은 owner 튜플이 다르므로 `NOT_OWNER`다
(`OPERATION_CONFLICT`는 같은 operation id가 다른 인자로 이미 적용된 경우만). 시작은 핸들 말고 인자가 없어서,
정했다(review 2026-11-01 01-05). 이전 revision의 핸들은 owner 튜플이 다르므로 `NOT_OWNER`다.
`OPERATION_CONFLICT`는 둘이다. 하나는 owner token이 같은데 호출이 claim과 다른 operation id를 댄 경우로, 다섯
전이(start·renew·complete·fail·release) 모두 거절하고 행을 바꾸지 않는다. 같은 token·다른 operation의 inspect도
상태와 상관없이(완료된 행도) `OPERATION_CONFLICT`다(2026-11-06 소유자 결정 — 전에는 CAS가 핸들의 claim
operation만 보고 호출의 id는 `last_transition_operation_id`에 적기만 해서 적용했다). 다른 하나는 같은 operation
id가 다른 인자로 이미 적용된 경우다. complete 재생은 같은 owner token에만 확인한다 — 같은 operation id를 쓴 다른
attempt의 늦은 complete는 `NOT_OWNER`다(전에는 operation id만 보고 `ALREADY_COMPLETED_SAME_RESULT`). 시작은 핸들 말고 인자가 없어서,
이미 기록된 시작과 digest가 다르면 다른 핸들이다 — 넘겨받기 전 핸들은 `NOT_OWNER`, 재생받은 현재 핸들은
`NOT_CLAIMED`(라운드6 RR6-02-01, 전에는 `OPERATION_CONFLICT`). renew는 `EXECUTING`의
lease만 늘리고, 시작 전 `CLAIMED`는 `NOT_IN_PROGRESS`다.
@@ -183,6 +183,9 @@ public final class PostgreSqlIdempotencyStore implements IdempotencyStorePort {
if (row == null) {
return startResult(IdempotencyStartOutcome.ABSENT, null);
}
if (namesAnotherOperation(row, owner, operationId)) {
return startResult(IdempotencyStartOutcome.OPERATION_CONFLICT, null);
}
String startDigest = transitionDigest("START", operationId, owner);
// A start carries no argument but the handle, so a recorded start with another digest was
// applied from another handle of the same operation — one from before a takeover by the same
@@ -220,6 +223,9 @@ public final class PostgreSqlIdempotencyStore implements IdempotencyStorePort {
if (row == null) {
return renewResult(IdempotencyRenewOutcome.ABSENT, null);
}
if (namesAnotherOperation(row, owner, operationId)) {
return renewResult(IdempotencyRenewOutcome.OPERATION_CONFLICT, null);
}
// The lease TTL is part of what a renewal decided, so it is part of the digest. Without it, a
// retry asking for a different lease was confirmed as the renewal already applied, and the
// caller went on believing it held the record for longer than the row says it does.
@@ -267,9 +273,16 @@ public final class PostgreSqlIdempotencyStore implements IdempotencyStorePort {
if (row == null) {
return IdempotencyCompleteOutcome.ABSENT;
}
if (namesAnotherOperation(row, owner, operationId)) {
return IdempotencyCompleteOutcome.OPERATION_CONFLICT;
}
String responseDigest = sha256(response.payload());
// A completion is reported back to its own owner only. The operation id alone confirmed the
// late completion of another attempt that carried the same id, which the Redis store refuses
// as NOT_OWNER (IdempotencyStoreContract).
if (row.state() == IdempotencyState.COMPLETED
&& "COMPLETE".equals(row.lastTransitionKind())
&& row.ownerToken().equals(owner.ownerToken())
&& operationId.value().equals(row.lastTransitionOperationId())) {
return responseDigest.equals(row.responseDigest())
? IdempotencyCompleteOutcome.ALREADY_COMPLETED_SAME_RESULT
@@ -315,6 +328,9 @@ public final class PostgreSqlIdempotencyStore implements IdempotencyStorePort {
if (row == null) {
return IdempotencyFailOutcome.ABSENT;
}
if (namesAnotherOperation(row, owner, operationId)) {
return IdempotencyFailOutcome.OPERATION_CONFLICT;
}
String transitionKind =
disposition == IdempotencyFailureDisposition.NO_EFFECT_RETRYABLE
? "FAIL_RETRYABLE"
@@ -372,6 +388,9 @@ public final class PostgreSqlIdempotencyStore implements IdempotencyStorePort {
if (row == null) {
return IdempotencyReleaseOutcome.ABSENT;
}
if (namesAnotherOperation(row, owner, operationId)) {
return IdempotencyReleaseOutcome.OPERATION_CONFLICT;
}
String releaseDigest = transitionDigest("RELEASE", operationId, owner);
switch (replayVerdict(row, "RELEASE", operationId, releaseDigest)) {
case SAME_ARGUMENTS -> {
@@ -411,6 +430,11 @@ public final class PostgreSqlIdempotencyStore implements IdempotencyStorePort {
return IdempotencyInspection.outcome(IdempotencyInspectionOutcome.FINGERPRINT_MISMATCH);
}
boolean sameAttempt = sameClaimAttempt(row, request.claimAttempt());
// The owner token under another operation is refused in every state, a completed record
// included, as the Redis store refuses it; the response used to be replayed to it here.
if (row.ownerToken().equals(request.claimAttempt().ownerToken()) && !sameAttempt) {
return IdempotencyInspection.outcome(IdempotencyInspectionOutcome.OPERATION_CONFLICT);
}
if (row.state() == IdempotencyState.COMPLETED && row.responsePayload() != null) {
return new IdempotencyInspection(
IdempotencyInspectionOutcome.COMPLETED_REPLAY,
@@ -425,9 +449,6 @@ public final class PostgreSqlIdempotencyStore implements IdempotencyStorePort {
if (sameAttempt && row.state() == IdempotencyState.EXECUTING) {
return inspectionWithOwner(IdempotencyInspectionOutcome.EXECUTING_SAME_OPERATION, row);
}
if (row.ownerToken().equals(request.claimAttempt().ownerToken()) && !sameAttempt) {
return IdempotencyInspection.outcome(IdempotencyInspectionOutcome.OPERATION_CONFLICT);
}
// Somebody else's execution whose lease ran out is reported as a claim would answer it. The
// database's clock decides, as it does for the claim; the read takes no lock, so a lease that
// ends between the row and the clock is reported as ended, which is what a claim would see.
@@ -452,9 +473,25 @@ public final class PostgreSqlIdempotencyStore implements IdempotencyStorePort {
return new IdempotencyClaimOutcome.TakenOverClaimed(owner(reset), reset.processingLeaseUntil());
}
/**
* Whether the holder of the record names an operation other than the one it was claimed under.
*
* <p>Every transition names the claim's operation, and a holder naming another one is refused
* before anything else is read: nothing changes, as in the Redis store and the in-memory fake. It
* used to be applied — the owner tuple took the claim's operation from the handle, and the named
* one was only written to {@code last_transition_operation_id} (owner decision 2026-11-06, {@code
* IdempotencyStoreContract}). Another owner token is still {@code NOT_OWNER}.
*/
private static boolean namesAnotherOperation(
IdempotencyRecordRow row, IdempotencyOwner owner, OperationId operationId) {
return row.ownerToken().equals(owner.ownerToken())
&& !row.claimOperationId().equals(operationId.value());
}
// A handle at an older revision is a stale owner tuple, so it is NOT_OWNER — what the Redis store
// and the in-memory fake answer (IdempotencyStoreContract). OPERATION_CONFLICT keeps its one
// meaning: the same operation id already applied this transition with different arguments.
// and the in-memory fake answer (IdempotencyStoreContract). OPERATION_CONFLICT means the holder
// named another operation than the claim's (namesAnotherOperation), or the same operation id
// already applied this transition with different arguments.
private IdempotencyStartOutcome classifyStartMismatch(
IdempotencyRecordRow row, IdempotencyOwner owner) {
if (!sameOwnerIdentity(row, owner)) {
@@ -91,8 +91,7 @@ class PostgreSqlIdempotencyIntegrationTest {
ignored -> {
IdempotencyOwner owner =
((IdempotencyClaimOutcome.Acquired) store.claim(request)).owner();
owner =
store.markExecutionStarted(owner, new OperationId("start-1")).owner().orElseThrow();
owner = store.markExecutionStarted(owner, owner.claimOperationId()).owner().orElseThrow();
jdbc.update(
"insert into idempotency_business_probe(scope_hash, mutation_count) values (?, 1)",
SCOPE.digest());
@@ -102,7 +101,7 @@ class PostgreSqlIdempotencyIntegrationTest {
owner,
new StoredResponse("{\"workLogId\":\"42\"}"),
Duration.ofHours(24),
new OperationId("complete-1")))
owner.claimOperationId()))
.isEqualTo(IdempotencyCompleteOutcome.COMPLETED);
});
@@ -157,7 +156,7 @@ class PostgreSqlIdempotencyIntegrationTest {
transactions
.execute(
ignored ->
store.markExecutionStarted(staleOwner, new OperationId("stale-start")))
store.markExecutionStarted(staleOwner, staleOwner.claimOperationId()))
.outcome())
.isEqualTo(IdempotencyStartOutcome.NOT_OWNER);
}
@@ -173,7 +172,7 @@ class PostgreSqlIdempotencyIntegrationTest {
store.claim(request(original, Duration.ofMillis(25))))
.owner();
return store
.markExecutionStarted(owner, new OperationId("start-executing"))
.markExecutionStarted(owner, owner.claimOperationId())
.owner()
.orElseThrow();
});
@@ -217,7 +216,7 @@ class PostgreSqlIdempotencyIntegrationTest {
((IdempotencyClaimOutcome.Acquired) store.claim(firstRequest)).owner();
owner =
store
.markExecutionStarted(owner, new OperationId("start-first"))
.markExecutionStarted(owner, owner.claimOperationId())
.owner()
.orElseThrow();
jdbc.update(
@@ -229,7 +228,7 @@ class PostgreSqlIdempotencyIntegrationTest {
owner,
new StoredResponse("done"),
Duration.ofHours(1),
new OperationId("complete-first")))
owner.claimOperationId()))
.isEqualTo(IdempotencyCompleteOutcome.COMPLETED);
firstHasCompletedInsideTransaction.countDown();
await(allowFirstCommit);
@@ -284,7 +283,7 @@ class PostgreSqlIdempotencyIntegrationTest {
((IdempotencyClaimOutcome.Acquired) store.claim(firstRequest)).owner();
IdempotencyOwner executing =
store
.markExecutionStarted(owner, new OperationId("start-slow"))
.markExecutionStarted(owner, owner.claimOperationId())
.owner()
.orElseThrow();
firstStarted.countDown();
@@ -293,7 +292,7 @@ class PostgreSqlIdempotencyIntegrationTest {
executing,
new StoredResponse("slow-but-done"),
Duration.ofHours(1),
new OperationId("complete-slow"));
executing.claimOperationId());
});
return null;
});
@@ -346,7 +345,7 @@ class PostgreSqlIdempotencyIntegrationTest {
((IdempotencyClaimOutcome.Acquired) store.claim(firstRequest)).owner();
IdempotencyOwner executing =
store
.markExecutionStarted(owner, new OperationId("start-fails"))
.markExecutionStarted(owner, owner.claimOperationId())
.owner()
.orElseThrow();
firstStarted.countDown();
@@ -357,7 +356,7 @@ class PostgreSqlIdempotencyIntegrationTest {
executing,
IdempotencyFailureDisposition.EFFECT_UNKNOWN_ABANDONED,
Duration.ofHours(1),
new OperationId("fail-unknown"));
executing.claimOperationId());
throw new IllegalStateException("the action failed");
});
return null;
@@ -383,7 +382,7 @@ class PostgreSqlIdempotencyIntegrationTest {
@Test
void aRetriedFailureWithTheSameArgumentsIsConfirmedRatherThanAppliedTwice() {
IdempotencyOwner executing = claimAndStart("claim-fail-replay", "start-fail-replay");
IdempotencyOwner executing = claimAndStart("claim-fail-replay");
IdempotencyFailOutcome first =
transactions.execute(
@@ -392,7 +391,7 @@ class PostgreSqlIdempotencyIntegrationTest {
executing,
IdempotencyFailureDisposition.NO_EFFECT_RETRYABLE,
Duration.ofHours(1),
new OperationId("fail-1")));
executing.claimOperationId()));
IdempotencyFailOutcome retry =
transactions.execute(
ignored ->
@@ -400,7 +399,7 @@ class PostgreSqlIdempotencyIntegrationTest {
executing,
IdempotencyFailureDisposition.NO_EFFECT_RETRYABLE,
Duration.ofHours(1),
new OperationId("fail-1")));
executing.claimOperationId()));
assertThat(first).isEqualTo(IdempotencyFailOutcome.MARKED_RETRYABLE);
assertThat(retry).isEqualTo(IdempotencyFailOutcome.ALREADY_MARKED_SAME_OPERATION);
@@ -408,7 +407,7 @@ class PostgreSqlIdempotencyIntegrationTest {
@Test
void aFailureRepeatedUnderOneOperationIdWithDifferentRetentionIsAConflict() {
IdempotencyOwner executing = claimAndStart("claim-fail-conflict", "start-fail-conflict");
IdempotencyOwner executing = claimAndStart("claim-fail-conflict");
transactions.execute(
ignored ->
@@ -416,7 +415,7 @@ class PostgreSqlIdempotencyIntegrationTest {
executing,
IdempotencyFailureDisposition.NO_EFFECT_RETRYABLE,
Duration.ofHours(1),
new OperationId("fail-2")));
executing.claimOperationId()));
IdempotencyFailOutcome different =
transactions.execute(
ignored ->
@@ -424,7 +423,7 @@ class PostgreSqlIdempotencyIntegrationTest {
executing,
IdempotencyFailureDisposition.NO_EFFECT_RETRYABLE,
Duration.ofHours(9),
new OperationId("fail-2")));
executing.claimOperationId()));
assertThat(different)
.as(
@@ -443,25 +442,25 @@ class PostgreSqlIdempotencyIntegrationTest {
@Test
void aRenewalRepeatedUnderOneOperationIdWithADifferentLeaseIsAConflict() {
// Started first: only an executing operation's lease is renewed (IdempotencyStoreContract).
IdempotencyOwner executing = claimAndStart("claim-renew-conflict", "start-renew-conflict");
IdempotencyOwner executing = claimAndStart("claim-renew-conflict");
IdempotencyRenewOutcome first =
transactions
.execute(
ignored ->
store.renew(executing, Duration.ofSeconds(30), new OperationId("renew-1")))
store.renew(executing, Duration.ofSeconds(30), executing.claimOperationId()))
.outcome();
IdempotencyRenewOutcome same =
transactions
.execute(
ignored ->
store.renew(executing, Duration.ofSeconds(30), new OperationId("renew-1")))
store.renew(executing, Duration.ofSeconds(30), executing.claimOperationId()))
.outcome();
IdempotencyRenewOutcome different =
transactions
.execute(
ignored ->
store.renew(executing, Duration.ofMinutes(45), new OperationId("renew-1")))
store.renew(executing, Duration.ofMinutes(45), executing.claimOperationId()))
.outcome();
assertThat(first).isEqualTo(IdempotencyRenewOutcome.RENEWED);
@@ -488,10 +487,12 @@ class PostgreSqlIdempotencyIntegrationTest {
.owner());
}
private static IdempotencyOwner claimAndStart(String claimOperation, String startOperation) {
// Every transition names the operation its record was claimed under; these tests gave each
// transition an id of its own, which the store now refuses (owner decision 2026-11-06).
private static IdempotencyOwner claimAndStart(String claimOperation) {
IdempotencyOwner claimed = claim(claimOperation);
return transactions
.execute(ignored -> store.markExecutionStarted(claimed, new OperationId(startOperation)))
.execute(ignored -> store.markExecutionStarted(claimed, claimed.claimOperationId()))
.owner()
.orElseThrow();
}
@@ -366,6 +366,7 @@ public final class InMemorySemanticRedisCommands implements SemanticRedisCommand
private List<Object> idempotencyRelease(String rendered, List<byte[]> arguments) {
String ownerToken = text(arguments.get(0));
long expectedRev = Long.parseLong(text(arguments.get(1)));
String operationId = text(arguments.get(2));
String state = field(rendered, "state");
if (state == null) {
@@ -380,6 +381,9 @@ public final class InMemorySemanticRedisCommands implements SemanticRedisCommand
if (!operationId.equals(field(rendered, "op"))) {
return reply("OPERATION_CONFLICT", attempt, rev, owner, "", "");
}
if (rev != expectedRev) {
return reply("NOT_OWNER", attempt, rev, owner, "", "");
}
if (!"CLAIMED".equals(state)) {
return reply("WRONG_STATE", attempt, rev, owner, state, "");
}