experimental-a2 0.18.0 → 0.19.0

package/src/store.ts

@@ -53,9 +53,15 @@ export type StoredEvent = Event & {
   attemptCount: number
   /** Current dispatch holder; null when the event is not claimed. */
   claimHolder: string | null
-  /** Adapter clock expiry for the current dispatch claim. */
+  /**
+   * Adapter clock expiry for the current dispatch claim, or, with no holder,
+   * the end of a failed attempt's retry hold.
+   */
   claimExpiresAt: Date | null
-  /** Caught handler failures. This alone drives dead-lettering. */
+  /**
+   * Failed attempts: caught handler failures, and lapsed claims a later claim
+   * took over. This alone drives dead-lettering.
+   */
   failureCount: number
   /** Adapter clock time recorded by the most recent caught handler failure. */
   lastFailedAt: Date | null
@@ -299,6 +305,15 @@ export interface A2Store {
     ttlMs: number
     expiresAtMs?: number
     excludeIndexes?: readonly number[]
+    /**
+     * Taking over a lapsed claim (one whose holder is still recorded, never
+     * completed or failed) adds one to `failureCount`. When that reaches
+     * `maxFailures`, the event dead-letters instead of being claimed: it
+     * comes back in `events` with `failedAt` set and no claim. Its
+     * `attemptCount` still advances, fencing the lapsed attempt, and its
+     * `lastFailedAttempt` is unchanged.
+     */
+    maxFailures?: number
   }): Promise<StoreClaimAvailableResult>
 
   /**
@@ -333,7 +348,10 @@ export interface A2Store {
   /**
    * Atomically records a caught failure for one claimed attempt. A stale
    * attempt cannot poison a processed event or a newer dispatch. Accepted
-   * failures record the operation's clock time.
+   * failures record the operation's clock time. A failure that does not
+   * dead-letter releases the claim and, with `retryAfterMs`, keeps the event
+   * unclaimable for that long: its claim expiry is set with no holder, so
+   * `claimAvailable` reports it `busy` until then.
    */
   failAttempt(options: {
     sessionId: string
@@ -341,6 +359,7 @@ export interface A2Store {
     attempt: number
     error: string
     maxFailures: number
+    retryAfterMs?: number
   }): Promise<FailAttemptResult>
 
   /**