Skip to content

Commit a8baddd

Browse files
authored
refactor: add DuplicateStreamSequenceException (#989)
1 parent 6d1a231 commit a8baddd

2 files changed

Lines changed: 175 additions & 0 deletions

File tree

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
/*
2+
* Copyright 2026 Flamingock (https://www.flamingock.io)
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package io.flamingock.internal.common.core.journal;
17+
18+
import io.flamingock.internal.common.core.error.FlamingockException;
19+
20+
/**
21+
* Signals that a journal event could not be appended because its
22+
* {@code (streamId, streamSequence)} position was already taken.
23+
* <p>
24+
* Every audit store already rejects a duplicate position — MongoDB through a unique index on
25+
* {@code (streamId, streamSequence)} plus an insert that is never an upsert, SQL through
26+
* {@code PRIMARY KEY (stream_id, stream_sequence)} and a plain {@code INSERT}, Couchbase because the
27+
* document key <em>is</em> the position and it inserts rather than upserts, and DynamoDB because the pair
28+
* is the table's primary key, guarded by a condition expression. What they do not share is <em>how</em>
29+
* they say so: {@code DuplicateKeyException}, a {@code SQLException}, {@code DocumentExistsException}, or
30+
* a {@code ConditionalCheckFailedException} buried inside a transaction cancellation.
31+
* <p>
32+
* This is the common type they translate to, so a caller can tell "that position is taken" apart from
33+
* "the write failed for some other reason" without knowing which backend it is talking to. That
34+
* distinction is what makes a portable retry possible: retrying a genuine infrastructure failure would
35+
* be wrong, and retrying nothing at all would leave a recoverable collision as a hard failure.
36+
* <p>
37+
* Nothing throws this yet. Each store translates its own exception in its own change; see
38+
* {@code docs/AUDIT_COMPACTION_CONTRIBUTOR_GUIDE.md} for how the journal work is split.
39+
*
40+
* <h2>Why it carries the position</h2>
41+
* A retry needs to know which position was rejected, and an operator reading a log needs both halves:
42+
* {@code streamSequence} on its own identifies nothing, since every stream has its own sequence 1.
43+
*/
44+
public class DuplicateStreamSequenceException extends FlamingockException {
45+
46+
private final String streamId;
47+
private final long streamSequence;
48+
49+
/**
50+
* @param streamId the stream whose position was taken
51+
* @param streamSequence the position within that stream
52+
* @param cause the backend's own exception. Worth keeping rather than swallowing: without it,
53+
* a position collision and a database rejecting the write for an unrelated
54+
* reason are indistinguishable after the fact
55+
*/
56+
public DuplicateStreamSequenceException(String streamId, long streamSequence, Throwable cause) {
57+
super(message(streamId, streamSequence), cause);
58+
this.streamId = streamId;
59+
this.streamSequence = streamSequence;
60+
}
61+
62+
/**
63+
* For the case where a store detects the duplicate without an exception to wrap — for instance from an
64+
* affected-row count, or a conditional write that reports failure as a value.
65+
*
66+
* @param streamId the stream whose position was taken
67+
* @param streamSequence the position within that stream
68+
*/
69+
public DuplicateStreamSequenceException(String streamId, long streamSequence) {
70+
super(message(streamId, streamSequence));
71+
this.streamId = streamId;
72+
this.streamSequence = streamSequence;
73+
}
74+
75+
public String getStreamId() {
76+
return streamId;
77+
}
78+
79+
public long getStreamSequence() {
80+
return streamSequence;
81+
}
82+
83+
private static String message(String streamId, long streamSequence) {
84+
return "Journal event position already taken [streamId=" + streamId
85+
+ " streamSequence=" + streamSequence + "]";
86+
}
87+
}
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
/*
2+
* Copyright 2026 Flamingock (https://www.flamingock.io)
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package io.flamingock.internal.common.core.journal;
17+
18+
import io.flamingock.internal.common.core.error.FlamingockException;
19+
import org.junit.jupiter.api.DisplayName;
20+
import org.junit.jupiter.api.Test;
21+
22+
import static org.junit.jupiter.api.Assertions.assertEquals;
23+
import static org.junit.jupiter.api.Assertions.assertNull;
24+
import static org.junit.jupiter.api.Assertions.assertSame;
25+
import static org.junit.jupiter.api.Assertions.assertTrue;
26+
27+
/**
28+
* There is little behaviour in an exception class, so these cover only what something else depends on:
29+
* the position the retry reads back, the cause a diagnosis needs, and the message an operator sees.
30+
*/
31+
class DuplicateStreamSequenceExceptionTest {
32+
33+
@Test
34+
@DisplayName("the message names both halves of the position")
35+
void messageNamesTheWholePosition() {
36+
DuplicateStreamSequenceException exception =
37+
new DuplicateStreamSequenceException("stage-one", 42L, new IllegalStateException("taken"));
38+
39+
String message = exception.getMessage();
40+
// Both halves, because a sequence on its own identifies nothing: every stream has a position 1.
41+
// This message is all an operator gets from a log line.
42+
assertTrue(message.contains("stage-one"), message);
43+
assertTrue(message.contains("42"), message);
44+
}
45+
46+
@Test
47+
@DisplayName("the backend's own exception is preserved as the cause")
48+
void preservesTheBackendCause() {
49+
IllegalStateException backendFailure = new IllegalStateException("E11000 duplicate key");
50+
51+
DuplicateStreamSequenceException exception =
52+
new DuplicateStreamSequenceException("stage-one", 42L, backendFailure);
53+
54+
// The one that matters. Swallowing it would make a position collision and a database rejecting
55+
// the write for an unrelated reason look identical after the fact.
56+
assertSame(backendFailure, exception.getCause());
57+
}
58+
59+
@Test
60+
@DisplayName("the position is readable, which is what a retry needs")
61+
void exposesThePosition() {
62+
DuplicateStreamSequenceException exception =
63+
new DuplicateStreamSequenceException("stage-one", 42L, new IllegalStateException());
64+
65+
assertEquals("stage-one", exception.getStreamId());
66+
assertEquals(42L, exception.getStreamSequence());
67+
}
68+
69+
@Test
70+
@DisplayName("a store with no exception to wrap still reports the position")
71+
void supportsDetectionWithoutABackendException() {
72+
// For backends that report a rejected conditional write as a value rather than by throwing.
73+
DuplicateStreamSequenceException exception =
74+
new DuplicateStreamSequenceException("stage-one", 42L);
75+
76+
assertNull(exception.getCause());
77+
assertEquals("stage-one", exception.getStreamId());
78+
assertEquals(42L, exception.getStreamSequence());
79+
}
80+
81+
@Test
82+
@DisplayName("it is a FlamingockException, so existing handlers see it")
83+
void isAFlamingockException() {
84+
// Relevant if it ever escapes un-retried: it surfaces as a Flamingock error rather than a bare
85+
// runtime exception.
86+
assertTrue(new DuplicateStreamSequenceException("stage-one", 1L) instanceof FlamingockException);
87+
}
88+
}

0 commit comments

Comments
 (0)