feat: jpa, messaging, notification, mongo, graphql 어댑터터 구현체 추가

This commit is contained in:
DongHyeonka
2026-08-15 13:01:58 +09:00
parent e23ed9486e
commit f56dd3e4eb
174 changed files with 10338 additions and 1274 deletions
@@ -43,4 +43,11 @@ public interface InboxRepository {
* @return how many rows were removed
*/
int purgeProcessedBefore(Instant processedBefore);
/**
* Deletes at most {@code limit} processed rows older than the cutoff.
*
* @return how many rows were deleted; fewer than {@code limit} means the sweep is finished
*/
int purgeProcessedBefore(Instant processedBefore, int limit);
}
@@ -0,0 +1,42 @@
package dev.caskeleton.messaging.reliability;
import java.time.Instant;
import java.util.Objects;
/**
* One relay's claim on one outbox record.
*
* <p>The port used to take a {@code MessageId} for every terminal transition, so a write said which
* row to change and nothing about which claim it belonged to. A relay that stalled past its lease
* could still record {@code AMBIGUOUS} over the {@code PUBLISHED} another relay had already
* written, and the row became claimable again — one message, published twice, by a system whose
* whole purpose is to publish it once.
*
* <p>The token is the part that makes staleness detectable. It increases on every claim, so a
* superseded relay holds a number the row no longer has and its update matches zero rows.
*/
public record OutboxLease(OutboxRecord record, String owner, long token, Instant expiresAt) {
public OutboxLease {
Objects.requireNonNull(record, "record must not be null");
Objects.requireNonNull(owner, "owner must not be null");
Objects.requireNonNull(expiresAt, "expiresAt must not be null");
if (owner.isBlank()) {
throw new IllegalArgumentException("a lease names its owner");
}
if (token < 1) {
throw new IllegalArgumentException(
"a claim's token starts at 1; 0 is the value of a row nobody has claimed");
}
}
/** The claimed record's identity. */
public dev.caskeleton.messaging.api.MessageId messageId() {
return record.messageId();
}
/** True when this lease has run out at the given moment. */
public boolean expiredAt(Instant now) {
return !Objects.requireNonNull(now, "now must not be null").isBefore(expiresAt);
}
}
@@ -35,6 +35,29 @@ public interface OutboxRepository {
*/
List<OutboxRecord> leaseBatch(int batchSize, Duration leaseDuration, Instant now);
/**
* Claims a batch and returns the leases, each carrying its owner and fencing token.
*
* <p>The token is what a terminal write is checked against. {@link #leaseBatch} returns records
* without one, so its callers cannot prove a write belongs to their claim; it remains for
* inspection paths and is deprecated for the relay's use.
*
* @param owner this relay's stable identity
*/
List<OutboxLease> claimBatch(String owner, int batchSize, Duration leaseDuration, Instant now);
/**
* Claims a batch, skipping rows that are waiting for their backoff or out of attempts.
*
* <p>Eligibility belongs in the row. A relay that decides in memory forgets on restart, and every
* replica decides for itself — so the same message is retried by as many workers as there are
* replicas, as often as they poll.
*
* @param maxAttempts the attempt budget; rows at or above it are not claimed
*/
List<OutboxLease> claimBatch(
String owner, int batchSize, Duration leaseDuration, Instant now, int maxAttempts);
/**
* Marks a record as confirmed by the broker.
*
@@ -43,6 +66,13 @@ public interface OutboxRepository {
*/
void markPublished(MessageId messageId, Instant now);
/**
* Records a confirmed publication, only if this lease still owns the row.
*
* @return {@link OutboxTransitionResult#STALE_LEASE} when another relay has taken it
*/
OutboxTransitionResult markPublished(OutboxLease lease, Instant now);
/**
* Marks a record whose publish outcome is unknown.
*
@@ -54,6 +84,21 @@ public interface OutboxRepository {
*/
void markAmbiguous(MessageId messageId, String failureCode, Instant now);
/** Records an ambiguous outcome, only if this lease still owns the row. */
OutboxTransitionResult markAmbiguous(OutboxLease lease, String failureCode, Instant now);
/** Records an ambiguous outcome and when this row may next be claimed. */
OutboxTransitionResult markAmbiguous(
OutboxLease lease, String failureCode, Instant now, Instant nextAttemptAt);
/**
* Parks a row whose attempt budget ran out.
*
* <p>Separate from {@link #markFailed}: a rejected message is invalid, an exhausted one never got
* an answer. The first needs a fix, the second a redrive.
*/
OutboxTransitionResult markExhausted(OutboxLease lease, String reason, Instant now);
/**
* Marks a record the broker definitively rejected.
*
@@ -63,6 +108,9 @@ public interface OutboxRepository {
*/
void markFailed(MessageId messageId, String failureCode, Instant now);
/** Records a terminal failure, only if this lease still owns the row. */
OutboxTransitionResult markFailed(OutboxLease lease, String failureCode, Instant now);
/**
* Releases a lease without changing the record's outcome.
*
@@ -70,6 +118,9 @@ public interface OutboxRepository {
*/
void releaseLease(MessageId messageId);
/** Gives a claim back, only if this lease still owns the row. */
OutboxTransitionResult releaseLease(OutboxLease lease);
/**
* Finds one record.
*
@@ -85,4 +136,17 @@ public interface OutboxRepository {
* @return how many rows were removed
*/
int purgePublishedBefore(Instant publishedBefore);
/**
* Deletes at most {@code limit} published rows older than the cutoff.
*
* <p>The unbounded version deletes everything before the cutoff in one statement. On a table that
* has been accumulating published rows since the last sweep that is a single long transaction
* holding locks and generating WAL in proportion to the backlog, which shows up as the relay and
* the business writes stalling behind retention. The cleanup jobs describe themselves as bounded
* by batch size; this is the parameter that makes that true.
*
* @return how many rows were deleted; fewer than {@code limit} means the sweep is finished
*/
int purgePublishedBefore(Instant publishedBefore, int limit);
}
@@ -23,5 +23,15 @@ public enum OutboxStatus {
AMBIGUOUS,
/** Definitively rejected; will not be retried without intervention. */
FAILED
FAILED,
/**
* The attempt budget ran out before any confirmed publish.
*
* <p>Distinct from {@link #FAILED}, which means the broker refused the message: this one means
* nobody ever got an answer. Collapsing the two loses the difference between "this message is
* invalid" and "the broker was unreachable for an hour", and those need different operator
* actions — the first a fix, the second a redrive.
*/
EXHAUSTED
}
@@ -0,0 +1,24 @@
package dev.caskeleton.messaging.reliability;
/**
* What a terminal outbox write actually did.
*
* <p>The transitions returned {@code void}, so an update that matched zero rows was
* indistinguishable from one that matched one. That is precisely the stale-lease case: the relay
* believes it recorded the outcome, the row still says something else, and nothing anywhere counts
* the disagreement.
*/
public enum OutboxTransitionResult {
/** The row moved to the requested state. */
APPLIED,
/**
* The row is no longer this lease's.
*
* <p>Another relay claimed it after the lease expired. Not an error to throw — the message is
* being handled by somebody else — but never a success either: it is the signal that this
* worker's publish attempt may have produced a duplicate, and it belongs on a metric.
*/
STALE_LEASE
}