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, "");
}
+3
View File
@@ -288,6 +288,9 @@ generation; the V1 `IdempotencyScope`/`tryBegin` API is gone.
(owner decision 2026-11-04, re-review RR5-01-02·03). A record lives for the lease plus the replay TTL. `IdempotencyStoreContract` holds Redis and PostgreSQL to both on
real servers; the in-memory fake models no time, so it runs only the contract's time-free cases
(re-review 2026-11-04 RR-01-11, RR-03-11, RR3-03-04).
- Every transition names the operation its record was claimed under (`IdempotencyOwner.claimOperationId()`).
Another one is `OPERATION_CONFLICT` in every store and changes nothing; so is an inspection that
brings the owner token under another operation (owner decision 2026-11-06).
The former ArchUnit freeze rule `inbound_port_implementations_do_not_declare_keyed_idempotency`
and its fixture were removed when this branch merged.
@@ -8,6 +8,10 @@ public enum IdempotencyCompleteOutcome {
ABSENT,
NOT_OWNER,
NOT_IN_PROGRESS,
/**
* The call names an operation other than the one the record was claimed under; nothing was
* recorded (owner decision 2026-11-06).
*/
OPERATION_CONFLICT,
INDETERMINATE,
UNAVAILABLE
@@ -8,6 +8,11 @@ public enum IdempotencyFailOutcome {
ABSENT,
NOT_OWNER,
NOT_IN_PROGRESS,
/**
* The call names an operation other than the one the record was claimed under (owner decision
* 2026-11-06), or this failure was already recorded with another disposition or retention.
* Nothing changed.
*/
OPERATION_CONFLICT,
INDETERMINATE,
UNAVAILABLE
@@ -16,6 +16,10 @@ public enum IdempotencyInspectionOutcome {
*/
ABANDONED,
FINGERPRINT_MISMATCH,
/**
* The attempt's owner token holds the record under another operation. It is the answer in every
* state, a completed record included: its response is not replayed to it.
*/
OPERATION_CONFLICT,
UNAVAILABLE
}
@@ -3,10 +3,19 @@ package dev.caskeleton.application.idempotency;
/** Outcomes of releasing a claim only while business execution has not started. */
public enum IdempotencyReleaseOutcome {
RELEASED_BEFORE_EXECUTION,
/** This release was already applied: a store that keeps released records recognises it. */
ALREADY_RELEASED_SAME_OPERATION,
/**
* No record exists: it expired, was never there, or was released by a store that deletes what it
* releases — that store cannot tell its own release's retry apart, so it confirms nothing.
*/
ABSENT,
NOT_OWNER,
EXECUTION_ALREADY_STARTED,
/**
* The call names an operation other than the one the record was claimed under; nothing was
* released (owner decision 2026-11-06).
*/
OPERATION_CONFLICT,
INDETERMINATE,
UNAVAILABLE
@@ -29,7 +29,10 @@ public enum IdempotencyRenewOutcome {
* with the same handle are still recorded (owner decision 2026-11-04).
*/
LEASE_EXPIRED(false),
/** The same operation id already renewed with different arguments. */
/**
* The call names an operation other than the one the record was claimed under (owner decision
* 2026-11-06), or this renewal was already applied asking for a different lease. Nothing changed.
*/
OPERATION_CONFLICT(false),
/** The store may have applied the renewal; inspect before relying on either answer. */
INDETERMINATE(false),
@@ -33,7 +33,11 @@ public enum IdempotencyStartOutcome {
* store started it).
*/
LEASE_EXPIRED(false),
/** The same operation id already started this record with different arguments. */
/**
* The handle's owner token holds the record, but the call names an operation other than the one
* the record was claimed under; nothing changed. Every store refuses it (owner decision
* 2026-11-06 — the PostgreSQL store started it).
*/
OPERATION_CONFLICT(false),
/** The store may have applied the start; inspect before relying on either answer. */
INDETERMINATE(false),
@@ -21,6 +21,14 @@ import java.time.Duration;
* record from its holder. Only the record's own lifetime ends it: once it is gone, every call
* answers {@code ABSENT} (owner decision 2026-11-04; re-review 2026-11-04 RR5-01-02·03; {@code
* IdempotencyStoreContract}).
*
* <p>Every transition names the operation its record was claimed under — the handle's {@link
* IdempotencyOwner#claimOperationId()}. A holder naming another one is answered {@code
* OPERATION_CONFLICT} and nothing changes; a claim that brings the owner token under another
* operation to a record still in progress is {@link
* IdempotencyClaimOutcome.OwnerOperationConflict}, and an inspection is {@code OPERATION_CONFLICT}
* in every state (owner decision 2026-11-06). For renew and failure {@code OPERATION_CONFLICT} also
* still means the same transition was already applied with other arguments.
*/
public interface IdempotencyStorePort {
@@ -514,6 +514,244 @@ public abstract class IdempotencyStoreContract {
.isGreaterThan(claimed.stateRevision());
}
// Every transition names the operation its record was claimed under. A holder naming another one
// is refused as OPERATION_CONFLICT and the record is left as it was: the Redis store refused it,
// the PostgreSQL store and the in-memory fake applied it — the PostgreSQL store wrote the named
// operation beside the claim's and read the claim's from the handle (owner decision 2026-11-06).
@Test
void startingUnderAnotherOperationThanTheClaimIsAConflictThatStartsNothing() {
// given
IdempotencyStorePort store = subject();
IdempotencyOwner claimed = acquire(store);
// when
IdempotencyMutationResult<IdempotencyStartOutcome> conflict =
store.markExecutionStarted(claimed, OTHER_OPERATION);
// then
assertThat(conflict.outcome()).isEqualTo(IdempotencyStartOutcome.OPERATION_CONFLICT);
assertThat(store.markExecutionStarted(claimed, OPERATION).outcome())
.isEqualTo(IdempotencyStartOutcome.STARTED);
}
@Test
void renewingUnderAnotherOperationThanTheClaimIsAConflictThatRenewsNothing() {
// given
IdempotencyStorePort store = subject();
IdempotencyOwner executing = executing(store);
// when
IdempotencyMutationResult<IdempotencyRenewOutcome> conflict =
store.renew(executing, Duration.ofSeconds(30), OTHER_OPERATION);
// then
assertThat(conflict.outcome()).isEqualTo(IdempotencyRenewOutcome.OPERATION_CONFLICT);
// The revision did not move, so the handle the start returned still completes the record.
assertThat(store.complete(executing, new StoredResponse("{}"), Duration.ofHours(1), OPERATION))
.isEqualTo(IdempotencyCompleteOutcome.COMPLETED);
}
@Test
void completingUnderAnotherOperationThanTheClaimIsAConflictThatRecordsNothing() {
// given
IdempotencyStorePort store = subject();
IdempotencyOwner executing = executing(store);
// when
IdempotencyCompleteOutcome conflict =
store.complete(
executing, new StoredResponse("{\"v\":1}"), Duration.ofHours(1), OTHER_OPERATION);
// then
assertThat(conflict).isEqualTo(IdempotencyCompleteOutcome.OPERATION_CONFLICT);
// No response was recorded: another one completes the record rather than conflicting with it.
assertThat(
store.complete(
executing, new StoredResponse("{\"v\":2}"), Duration.ofHours(1), OPERATION))
.isEqualTo(IdempotencyCompleteOutcome.COMPLETED);
}
@Test
void markingFailedUnderAnotherOperationThanTheClaimIsAConflictThatMarksNothing() {
// given
IdempotencyStorePort store = subject();
IdempotencyOwner executing = executing(store);
// when
IdempotencyFailOutcome conflict =
store.markFailed(
executing,
IdempotencyFailureDisposition.NO_EFFECT_RETRYABLE,
Duration.ofHours(1),
OTHER_OPERATION);
// then
assertThat(conflict).isEqualTo(IdempotencyFailOutcome.OPERATION_CONFLICT);
assertThat(store.complete(executing, new StoredResponse("{}"), Duration.ofHours(1), OPERATION))
.isEqualTo(IdempotencyCompleteOutcome.COMPLETED);
}
@Test
void releasingUnderAnotherOperationThanTheClaimIsAConflictThatReleasesNothing() {
// given
IdempotencyStorePort store = subject();
IdempotencyOwner claimed = acquire(store);
// when
IdempotencyReleaseOutcome conflict = store.releaseBeforeExecution(claimed, OTHER_OPERATION);
// then
assertThat(conflict).isEqualTo(IdempotencyReleaseOutcome.OPERATION_CONFLICT);
assertThat(store.markExecutionStarted(claimed, OPERATION).outcome())
.isEqualTo(IdempotencyStartOutcome.STARTED);
}
@Test
void anotherAttemptCompletingARecordCompletedUnderTheSameOperationIsNotItsOwner() {
// given
// One operation id on two attempts — a caller that keeps its operation id across resends. The
// second attempt took the retryable failure over and completed it; the first attempt's late
// completion is not that completion. The PostgreSQL store confirmed it, because its replay
// check read the operation id and not the owner.
IdempotencyStorePort store = subject();
IdempotencyOwner first = executing(store);
store.markFailed(
first, IdempotencyFailureDisposition.NO_EFFECT_RETRYABLE, Duration.ofHours(1), OPERATION);
IdempotencyOwner second =
started(store, ownerOf(store.claim(claim(store.newClaimAttempt(OPERATION), FINGERPRINT))));
store.complete(second, new StoredResponse("{\"v\":1}"), Duration.ofHours(1), OPERATION);
// when
IdempotencyCompleteOutcome late =
store.complete(first, new StoredResponse("{\"v\":1}"), Duration.ofHours(1), OPERATION);
// then
assertThat(late).isEqualTo(IdempotencyCompleteOutcome.NOT_OWNER);
}
@Test
void aClaimWithTheOwnerTokenUnderAnotherOperationIsAnOwnerOperationConflict() {
// given
IdempotencyStorePort store = subject();
IdempotencyClaimAttempt attempt = store.newClaimAttempt(OPERATION);
IdempotencyOwner claimed = ownerOf(store.claim(claim(attempt, FINGERPRINT)));
// when
IdempotencyClaimOutcome conflict =
store.claim(
claim(new IdempotencyClaimAttempt(attempt.ownerToken(), OTHER_OPERATION), FINGERPRINT));
// then
assertThat(conflict).isInstanceOf(IdempotencyClaimOutcome.OwnerOperationConflict.class);
assertThat(store.markExecutionStarted(claimed, OPERATION).outcome())
.isEqualTo(IdempotencyStartOutcome.STARTED);
}
@Test
void inspectingAClaimWithTheOwnerTokenUnderAnotherOperationIsAnOperationConflict() {
// given
IdempotencyStorePort store = subject();
IdempotencyClaimAttempt attempt = store.newClaimAttempt(OPERATION);
store.claim(claim(attempt, FINGERPRINT));
// when
IdempotencyInspection inspection =
store.inspect(
new IdempotencyInspectionRequest(
SCOPE,
FINGERPRINT,
new IdempotencyClaimAttempt(attempt.ownerToken(), OTHER_OPERATION)));
// then
assertThat(inspection.outcome()).isEqualTo(IdempotencyInspectionOutcome.OPERATION_CONFLICT);
}
@Test
void inspectingACompletedRecordWithTheOwnerTokenUnderAnotherOperationIsAnOperationConflict() {
// given
// In every state, a completed record included: the Redis store refused it, the PostgreSQL
// store and the in-memory fake replayed the response to it.
IdempotencyStorePort store = subject();
IdempotencyClaimAttempt attempt = store.newClaimAttempt(OPERATION);
store.complete(
started(store, ownerOf(store.claim(claim(attempt, FINGERPRINT)))),
new StoredResponse("{\"ok\":true}"),
Duration.ofHours(1),
OPERATION);
// when
IdempotencyInspection inspection =
store.inspect(
new IdempotencyInspectionRequest(
SCOPE,
FINGERPRINT,
new IdempotencyClaimAttempt(attempt.ownerToken(), OTHER_OPERATION)));
// then
assertThat(inspection.outcome()).isEqualTo(IdempotencyInspectionOutcome.OPERATION_CONFLICT);
}
@Test
void releasingAScopeWithNoRecordIsAbsent() {
// given
// A handle whose record is gone — expired, reaped — stands in here as one for a scope nobody
// claimed. Nothing was found, so nothing is confirmed: the Redis store answered that it had
// already released it.
IdempotencyStorePort store = subject();
IdempotencyOwner gone =
new IdempotencyOwner(SCOPE, store.newClaimAttempt(OPERATION).ownerToken(), 1, 1, OPERATION);
// when
IdempotencyReleaseOutcome released = store.releaseBeforeExecution(gone, OPERATION);
// then
assertThat(released).isEqualTo(IdempotencyReleaseOutcome.ABSENT);
}
@Test
void aReleaseRetriedAfterItWasAppliedReleasesNothingMore() {
// given
IdempotencyStorePort store = subject();
IdempotencyOwner claimed = acquire(store);
store.releaseBeforeExecution(claimed, OPERATION);
// when
IdempotencyReleaseOutcome again = store.releaseBeforeExecution(claimed, OPERATION);
// then
// A store that keeps the released record recognises the release (PostgreSQL); one that forgets
// it finds no record (Redis, the in-memory fake). Neither releases a second time.
assertThat(again)
.isIn(
IdempotencyReleaseOutcome.ALREADY_RELEASED_SAME_OPERATION,
IdempotencyReleaseOutcome.ABSENT);
}
@Test
void releasingThroughTheHandleFromBeforeTheAttemptTookItsClaimOverIsRefusedAsAStaleOwner() {
// given
// The same attempt took its retryable failure over, so the record is a claim again under the
// same owner token and operation. The Redis program read no revision and released it.
IdempotencyStorePort store = subject();
IdempotencyClaimAttempt attempt = store.newClaimAttempt(OPERATION);
IdempotencyOwner before = ownerOf(store.claim(claim(attempt, FINGERPRINT)));
store.markFailed(
started(store, before),
IdempotencyFailureDisposition.NO_EFFECT_RETRYABLE,
Duration.ofHours(1),
OPERATION);
IdempotencyOwner current = ownerOf(store.claim(claim(attempt, FINGERPRINT)));
// when
IdempotencyReleaseOutcome released = store.releaseBeforeExecution(before, OPERATION);
// then
assertThat(released).isEqualTo(IdempotencyReleaseOutcome.NOT_OWNER);
assertThat(store.markExecutionStarted(current, OPERATION).outcome())
.isEqualTo(IdempotencyStartOutcome.STARTED);
}
@Test
@DisplayName("실행 중인 자기 기록을 inspect하면 기록 수명이 아니라 claim이 받은 처리 lease 만료 시각이 나온다")
void inspectingAnOwnExecutionReportsItsProcessingLeaseNotTheRecordLifetime() {
@@ -34,7 +34,8 @@ import java.util.Random;
* attempt against an in-flight record is always {@code InProgress}. Leases and replay windows are
* reported as {@link Instant#MAX}. What it keeps exact is what a test of a caller relies on: one
* claim wins, the owner handle's revision advances on every transition, a completed response
* replays, a different fingerprint is refused, and a retryable failure can be claimed again.
* replays, a different fingerprint is refused, a retryable failure can be claimed again, and an
* owner naming an operation other than its claim's is refused.
*/
public final class InMemoryIdempotencyStore implements IdempotencyStorePort {
@@ -82,6 +83,10 @@ public final class InMemoryIdempotencyStore implements IdempotencyStorePort {
&& row.owner.claimOperationId().equals(request.claimAttempt().operationId())) {
return new IdempotencyClaimOutcome.ReplayedAcquire(row.owner, Instant.MAX);
}
// The owner token under another operation is refused, not reported in progress.
if (row.owner.ownerToken().equals(request.claimAttempt().ownerToken())) {
return new IdempotencyClaimOutcome.OwnerOperationConflict();
}
return new IdempotencyClaimOutcome.InProgress(Duration.ZERO, row.owner.attempt());
}
@@ -92,11 +97,13 @@ public final class InMemoryIdempotencyStore implements IdempotencyStorePort {
IdempotencyStartOutcome outcome =
row == null
? IdempotencyStartOutcome.ABSENT
: !row.owner.equals(owner)
? IdempotencyStartOutcome.NOT_OWNER
: row.state != IdempotencyState.CLAIMED
? IdempotencyStartOutcome.NOT_CLAIMED
: IdempotencyStartOutcome.STARTED;
: row.namesAnotherOperation(owner, operationId)
? IdempotencyStartOutcome.OPERATION_CONFLICT
: !row.owner.equals(owner)
? IdempotencyStartOutcome.NOT_OWNER
: row.state != IdempotencyState.CLAIMED
? IdempotencyStartOutcome.NOT_CLAIMED
: IdempotencyStartOutcome.STARTED;
if (outcome != IdempotencyStartOutcome.STARTED) {
return new IdempotencyMutationResult<>(outcome, null, IdempotencyStartOutcome::carriesOwner);
}
@@ -114,11 +121,13 @@ public final class InMemoryIdempotencyStore implements IdempotencyStorePort {
IdempotencyRenewOutcome refused =
row == null
? IdempotencyRenewOutcome.ABSENT
: !row.owner.equals(owner)
? IdempotencyRenewOutcome.NOT_OWNER
: row.state != IdempotencyState.EXECUTING
? IdempotencyRenewOutcome.NOT_IN_PROGRESS
: null;
: row.namesAnotherOperation(owner, operationId)
? IdempotencyRenewOutcome.OPERATION_CONFLICT
: !row.owner.equals(owner)
? IdempotencyRenewOutcome.NOT_OWNER
: row.state != IdempotencyState.EXECUTING
? IdempotencyRenewOutcome.NOT_IN_PROGRESS
: null;
if (refused != null) {
return new IdempotencyMutationResult<>(refused, null, IdempotencyRenewOutcome::carriesOwner);
}
@@ -137,6 +146,9 @@ public final class InMemoryIdempotencyStore implements IdempotencyStorePort {
if (row == null) {
return IdempotencyCompleteOutcome.ABSENT;
}
if (row.namesAnotherOperation(owner, operationId)) {
return IdempotencyCompleteOutcome.OPERATION_CONFLICT;
}
if (row.state == IdempotencyState.COMPLETED && owner.equals(row.completedBy)) {
// The completing handle retried, as after a lost reply: the same result is a no-op, another
// result is a conflict, exactly as the stores answer.
@@ -166,6 +178,9 @@ public final class InMemoryIdempotencyStore implements IdempotencyStorePort {
if (row == null) {
return IdempotencyFailOutcome.ABSENT;
}
if (row.namesAnotherOperation(owner, operationId)) {
return IdempotencyFailOutcome.OPERATION_CONFLICT;
}
if (!row.owner.equals(owner)) {
return IdempotencyFailOutcome.NOT_OWNER;
}
@@ -186,6 +201,9 @@ public final class InMemoryIdempotencyStore implements IdempotencyStorePort {
if (row == null) {
return IdempotencyReleaseOutcome.ABSENT;
}
if (row.namesAnotherOperation(owner, operationId)) {
return IdempotencyReleaseOutcome.OPERATION_CONFLICT;
}
if (!row.owner.equals(owner)) {
return IdempotencyReleaseOutcome.NOT_OWNER;
}
@@ -205,6 +223,11 @@ public final class InMemoryIdempotencyStore implements IdempotencyStorePort {
if (!row.fingerprint.equals(request.requestFingerprint())) {
return IdempotencyInspection.outcome(IdempotencyInspectionOutcome.FINGERPRINT_MISMATCH);
}
// The stores' order: the owner token under another operation is refused in every state.
if (row.owner.ownerToken().equals(request.claimAttempt().ownerToken())
&& !row.owner.claimOperationId().equals(request.claimAttempt().operationId())) {
return IdempotencyInspection.outcome(IdempotencyInspectionOutcome.OPERATION_CONFLICT);
}
if (row.state == IdempotencyState.COMPLETED) {
return new IdempotencyInspection(
IdempotencyInspectionOutcome.COMPLETED_REPLAY,
@@ -274,5 +297,15 @@ public final class InMemoryIdempotencyStore implements IdempotencyStorePort {
owner = owner.withStateRevision(owner.stateRevision() + 1);
state = next;
}
/**
* Whether the record's owner names an operation other than its claim's. The stores refuse that
* before anything else is read, whatever the handle's revision ({@code
* IdempotencyStoreContract}).
*/
boolean namesAnotherOperation(IdempotencyOwner caller, OperationId operationId) {
return owner.ownerToken().equals(caller.ownerToken())
&& !owner.claimOperationId().equals(operationId);
}
}
}