@s2-dev/streamstore 0.17.5 → 0.18.0

package/dist/cjs/lib/retry.js

@@ -0,0 +1,839 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetryAppendSession = exports.RetryReadSession = exports.DEFAULT_RETRY_CONFIG = void 0;
+exports.isRetryable = isRetryable;
+exports.calculateDelay = calculateDelay;
+exports.sleep = sleep;
+exports.withRetries = withRetries;
+const debug_1 = require("debug");
+const error_js_1 = require("../error.js");
+const utils_js_1 = require("../utils.js");
+const result_js_1 = require("./result.js");
+const debugWith = (0, debug_1.default)("s2:retry:with");
+const debugRead = (0, debug_1.default)("s2:retry:read");
+const debugSession = (0, debug_1.default)("s2:retry:session");
+/**
+ * Default retry configuration.
+ */
+exports.DEFAULT_RETRY_CONFIG = {
+    maxAttempts: 3,
+    retryBackoffDurationMillis: 100,
+    appendRetryPolicy: "noSideEffects",
+    requestTimeoutMillis: 5000, // 5 seconds
+};
+const RETRYABLE_STATUS_CODES = new Set([
+    408, // request_timeout
+    429, // too_many_requests
+    500, // internal_server_error
+    502, // bad_gateway
+    503, // service_unavailable
+]);
+/**
+ * Determines if an error should be retried based on its characteristics.
+ * 400-level errors (except 408, 429) are non-retryable validation/client errors.
+ */
+function isRetryable(error) {
+    if (!error.status)
+        return false;
+    // Explicit retryable codes (including some 4xx like 408, 429)
+    if (RETRYABLE_STATUS_CODES.has(error.status)) {
+        return true;
+    }
+    // 400-level errors are generally non-retryable (validation, bad request)
+    if (error.status >= 400 && error.status < 500) {
+        return false;
+    }
+    return false;
+}
+/**
+ * Calculates the delay before the next retry attempt using fixed backoff
+ * with jitter. The `attempt` parameter is currently ignored to keep a
+ * constant base delay per attempt.
+ */
+function calculateDelay(attempt, baseDelayMillis) {
+    // Apply ±50% jitter around the base delay
+    const jitterRange = 0.5; // 50% up or down
+    const factor = 1 + (Math.random() * 2 - 1) * jitterRange; // [0.5, 1.5]
+    const delay = Math.max(0, baseDelayMillis * factor);
+    return Math.floor(delay);
+}
+/**
+ * Sleeps for the specified duration.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Executes an async function with automatic retry logic for transient failures.
+ *
+ * @param retryConfig Retry configuration (max attempts, backoff duration)
+ * @param fn The async function to execute
+ * @returns The result of the function
+ * @throws The last error if all retry attempts are exhausted
+ */
+async function withRetries(retryConfig, fn, isPolicyCompliant = () => true) {
+    const config = {
+        ...exports.DEFAULT_RETRY_CONFIG,
+        ...retryConfig,
+    };
+    // Enforce minimum of 1 attempt (1 = no retries)
+    if (config.maxAttempts < 1)
+        config.maxAttempts = 1;
+    let lastError = undefined;
+    // attemptNo is 1-based: 1..maxAttempts
+    for (let attemptNo = 1; attemptNo <= config.maxAttempts; attemptNo++) {
+        try {
+            const result = await fn();
+            if (attemptNo > 1) {
+                debugWith("succeeded after %d retries", attemptNo - 1);
+            }
+            return result;
+        }
+        catch (error) {
+            // withRetry only handles S2Errors (withS2Error should be called first)
+            if (!(error instanceof error_js_1.S2Error)) {
+                debugWith("non-S2Error thrown, rethrowing immediately: %s", error);
+                throw error;
+            }
+            lastError = error;
+            // Don't retry if this is the last attempt
+            if (attemptNo === config.maxAttempts) {
+                debugWith("max attempts exhausted, throwing error");
+                break;
+            }
+            // Check if error is retryable
+            if (!isPolicyCompliant(config, lastError) || !isRetryable(lastError)) {
+                debugWith("error not retryable, throwing immediately");
+                throw error;
+            }
+            // Calculate delay and wait before retrying
+            const delay = calculateDelay(attemptNo - 1, config.retryBackoffDurationMillis);
+            debugWith("retryable error, backing off for %dms, status=%s", delay, error.status);
+            await sleep(delay);
+        }
+    }
+    throw lastError;
+}
+class RetryReadSession extends ReadableStream {
+    _nextReadPosition = undefined;
+    _lastObservedTail = undefined;
+    _recordsRead = 0;
+    _bytesRead = 0;
+    static async create(generator, args = {}, config) {
+        return new RetryReadSession(args, generator, config);
+    }
+    constructor(args, generator, config) {
+        const retryConfig = {
+            ...exports.DEFAULT_RETRY_CONFIG,
+            ...config,
+        };
+        let session = undefined;
+        const startTimeMs = performance.now(); // Capture start time before super()
+        super({
+            start: async (controller) => {
+                let nextArgs = { ...args };
+                // Capture original request budget so retries compute from a stable baseline
+                const baselineCount = args?.count;
+                const baselineBytes = args?.bytes;
+                const baselineWait = args?.wait;
+                let attempt = 0;
+                while (true) {
+                    debugRead("starting read session with args: %o", nextArgs);
+                    session = await generator(nextArgs);
+                    const reader = session.getReader();
+                    while (true) {
+                        const { done, value: result } = await reader.read();
+                        // Update last observed tail if transport exposes it
+                        try {
+                            const tail = session.lastObservedTail?.();
+                            if (tail)
+                                this._lastObservedTail = tail;
+                        }
+                        catch { }
+                        if (done) {
+                            reader.releaseLock();
+                            controller.close();
+                            return;
+                        }
+                        // Check if result is an error
+                        if (!result.ok) {
+                            reader.releaseLock();
+                            const error = result.error;
+                            // Check if we can retry (track session attempts, not record reads)
+                            const effectiveMax = Math.max(1, retryConfig.maxAttempts);
+                            if (isRetryable(error) && attempt < effectiveMax - 1) {
+                                if (this._nextReadPosition) {
+                                    nextArgs.seq_num = this._nextReadPosition.seq_num;
+                                    // Clear alternative start position fields to avoid conflicting params
+                                    delete nextArgs.timestamp;
+                                    delete nextArgs.tail_offset;
+                                }
+                                // Compute planned backoff delay now so we can subtract it from wait budget
+                                const delay = calculateDelay(attempt, retryConfig.retryBackoffDurationMillis);
+                                // Recompute remaining budget from original request each time to avoid double-subtraction
+                                if (baselineCount !== undefined) {
+                                    nextArgs.count = Math.max(0, baselineCount - this._recordsRead);
+                                }
+                                if (baselineBytes !== undefined) {
+                                    nextArgs.bytes = Math.max(0, baselineBytes - this._bytesRead);
+                                }
+                                // Adjust wait from original budget based on total elapsed time since start
+                                if (baselineWait !== undefined) {
+                                    const elapsedSeconds = (performance.now() - startTimeMs) / 1000;
+                                    nextArgs.wait = Math.max(0, baselineWait - (elapsedSeconds + delay / 1000));
+                                }
+                                // Proactively cancel the current transport session before retrying
+                                try {
+                                    await session.cancel?.("retry");
+                                }
+                                catch { }
+                                debugRead("will retry after %dms, status=%s", delay, error.status);
+                                await sleep(delay);
+                                attempt++;
+                                break; // Break inner loop to retry
+                            }
+                            // Error is not retryable or attempts exhausted
+                            debugRead("error in retry loop: %s", error);
+                            controller.error(error);
+                            return;
+                        }
+                        // Success: enqueue the record and reset retry attempt counter
+                        const record = result.value;
+                        this._nextReadPosition = {
+                            seq_num: record.seq_num + 1,
+                            timestamp: record.timestamp,
+                        };
+                        this._recordsRead++;
+                        this._bytesRead += (0, utils_js_1.meteredBytes)(record);
+                        attempt = 0;
+                        controller.enqueue(record);
+                    }
+                }
+            },
+            cancel: async (reason) => {
+                try {
+                    await session?.cancel(reason);
+                }
+                catch (err) {
+                    // Ignore ERR_INVALID_STATE - stream may already be closed/cancelled
+                    if (err?.code !== "ERR_INVALID_STATE") {
+                        throw err;
+                    }
+                }
+            },
+        });
+    }
+    async [Symbol.asyncDispose]() {
+        await this.cancel("disposed");
+    }
+    // Polyfill for older browsers / Node.js environments
+    [Symbol.asyncIterator]() {
+        const fn = ReadableStream.prototype[Symbol.asyncIterator];
+        if (typeof fn === "function")
+            return fn.call(this);
+        const reader = this.getReader();
+        return {
+            next: async () => {
+                const r = await reader.read();
+                if (r.done) {
+                    reader.releaseLock();
+                    return { done: true, value: undefined };
+                }
+                return { done: false, value: r.value };
+            },
+            throw: async (e) => {
+                try {
+                    await reader.cancel(e);
+                }
+                catch (err) {
+                    if (err?.code !== "ERR_INVALID_STATE")
+                        throw err;
+                }
+                reader.releaseLock();
+                return { done: true, value: undefined };
+            },
+            return: async () => {
+                try {
+                    await reader.cancel("done");
+                }
+                catch (err) {
+                    if (err?.code !== "ERR_INVALID_STATE")
+                        throw err;
+                }
+                reader.releaseLock();
+                return { done: true, value: undefined };
+            },
+            [Symbol.asyncIterator]() {
+                return this;
+            },
+        };
+    }
+    lastObservedTail() {
+        return this._lastObservedTail;
+    }
+    nextReadPosition() {
+        return this._nextReadPosition;
+    }
+}
+exports.RetryReadSession = RetryReadSession;
+const DEFAULT_MAX_INFLIGHT_BYTES = 10 * 1024 * 1024; // 10 MiB default
+class RetryAppendSession {
+    generator;
+    sessionOptions;
+    requestTimeoutMillis;
+    maxQueuedBytes;
+    maxInflightBatches;
+    retryConfig;
+    inflight = [];
+    capacityWaiter; // Single waiter (WritableStream writer lock)
+    session;
+    queuedBytes = 0;
+    pendingBytes = 0;
+    consecutiveFailures = 0;
+    currentAttempt = 0;
+    pumpPromise;
+    pumpStopped = false;
+    closing = false;
+    pumpWakeup;
+    closed = false;
+    fatalError;
+    _lastAckedPosition;
+    acksController;
+    readable;
+    writable;
+    /**
+     * If the session has failed, returns the original fatal error that caused
+     * the pump to stop. Returns undefined when the session has not failed.
+     */
+    failureCause() {
+        return this.fatalError;
+    }
+    constructor(generator, sessionOptions, config) {
+        this.generator = generator;
+        this.sessionOptions = sessionOptions;
+        this.retryConfig = {
+            ...exports.DEFAULT_RETRY_CONFIG,
+            ...config,
+        };
+        this.requestTimeoutMillis = this.retryConfig.requestTimeoutMillis;
+        this.maxQueuedBytes =
+            this.sessionOptions?.maxInflightBytes ?? DEFAULT_MAX_INFLIGHT_BYTES;
+        this.maxInflightBatches = this.sessionOptions?.maxInflightBatches;
+        this.readable = new ReadableStream({
+            start: (controller) => {
+                this.acksController = controller;
+            },
+        });
+        this.writable = new WritableStream({
+            write: async (chunk) => {
+                const recordsArray = Array.isArray(chunk.records)
+                    ? chunk.records
+                    : [chunk.records];
+                // Calculate metered size
+                let batchMeteredSize = 0;
+                for (const record of recordsArray) {
+                    batchMeteredSize += (0, utils_js_1.meteredBytes)(record);
+                }
+                // Wait for capacity (backpressure for writable only)
+                await this.waitForCapacity(batchMeteredSize);
+                const { records: _records, ...rest } = chunk;
+                const args = rest;
+                args.precalculatedSize = batchMeteredSize;
+                // Move reserved bytes to queued bytes accounting before submission
+                this.pendingBytes = Math.max(0, this.pendingBytes - batchMeteredSize);
+                // Submit without waiting for ack (writable doesn't need per-batch resolution)
+                const promise = this.submitInternal(recordsArray, args, batchMeteredSize);
+                promise.catch(() => {
+                    // Swallow to avoid unhandled rejection; pump surfaces errors via readable stream
+                });
+            },
+            close: async () => {
+                await this.close();
+            },
+            abort: async (reason) => {
+                const error = (0, error_js_1.abortedError)(`AppendSession aborted: ${reason}`);
+                await this.abort(error);
+            },
+        });
+    }
+    static async create(generator, sessionOptions, config) {
+        return new RetryAppendSession(generator, sessionOptions, config);
+    }
+    /**
+     * Submit an append request. Returns a promise that resolves with the ack.
+     * This method does not block on capacity (only writable.write() does).
+     */
+    async submit(records, args) {
+        const recordsArray = Array.isArray(records) ? records : [records];
+        // Calculate metered size if not provided
+        let batchMeteredSize = args?.precalculatedSize ?? 0;
+        if (batchMeteredSize === 0) {
+            for (const record of recordsArray) {
+                batchMeteredSize += (0, utils_js_1.meteredBytes)(record);
+            }
+        }
+        const result = await this.submitInternal(recordsArray, args, batchMeteredSize);
+        // Convert discriminated union back to throw pattern for public API
+        if (result.ok) {
+            return result.value;
+        }
+        else {
+            throw result.error;
+        }
+    }
+    /**
+     * Internal submit that returns discriminated union.
+     * Creates inflight entry and starts pump if needed.
+     */
+    submitInternal(records, args, batchMeteredSize) {
+        if (this.closed || this.closing) {
+            return Promise.resolve((0, result_js_1.err)(new error_js_1.S2Error({ message: "AppendSession is closed", status: 400 })));
+        }
+        // Check for fatal error (e.g., from abort())
+        if (this.fatalError) {
+            debugSession("[SUBMIT] rejecting due to fatal error: %s", this.fatalError.message);
+            return Promise.resolve((0, result_js_1.err)(this.fatalError));
+        }
+        // Create promise for submit() callers
+        return new Promise((resolve) => {
+            // Create inflight entry (innerPromise will be set when pump processes it)
+            const entry = {
+                records,
+                args,
+                expectedCount: records.length,
+                meteredBytes: batchMeteredSize,
+                innerPromise: new Promise(() => { }), // Never-resolving placeholder
+                maybeResolve: resolve,
+                needsSubmit: true, // Mark for pump to submit
+            };
+            debugSession("[SUBMIT] enqueueing %d records (%d bytes): inflight=%d->%d, queuedBytes=%d->%d", records.length, batchMeteredSize, this.inflight.length, this.inflight.length + 1, this.queuedBytes, this.queuedBytes + batchMeteredSize);
+            this.inflight.push(entry);
+            this.queuedBytes += batchMeteredSize;
+            // Wake pump if it's sleeping
+            if (this.pumpWakeup) {
+                this.pumpWakeup();
+            }
+            // Start pump if not already running
+            this.ensurePump();
+        });
+    }
+    /**
+     * Wait for capacity before allowing write to proceed (writable only).
+     */
+    async waitForCapacity(bytes) {
+        debugSession("[CAPACITY] checking for %d bytes: queuedBytes=%d, pendingBytes=%d, maxQueuedBytes=%d, inflight=%d", bytes, this.queuedBytes, this.pendingBytes, this.maxQueuedBytes, this.inflight.length);
+        // Check if we have capacity
+        while (true) {
+            // Check for fatal error before adding to pendingBytes
+            if (this.fatalError) {
+                debugSession("[CAPACITY] fatal error detected, rejecting: %s", this.fatalError.message);
+                throw this.fatalError;
+            }
+            // Byte-based gating
+            if (this.queuedBytes + this.pendingBytes + bytes <= this.maxQueuedBytes) {
+                // Batch-based gating (if configured)
+                if (this.maxInflightBatches === undefined ||
+                    this.inflight.length < this.maxInflightBatches) {
+                    debugSession("[CAPACITY] capacity available, adding %d to pendingBytes", bytes);
+                    this.pendingBytes += bytes;
+                    return;
+                }
+            }
+            // No capacity - wait
+            // WritableStream enforces writer lock, so only one write can be blocked at a time
+            debugSession("[CAPACITY] no capacity, waiting for release");
+            await new Promise((resolve) => {
+                this.capacityWaiter = resolve;
+            });
+            debugSession("[CAPACITY] woke up, rechecking");
+        }
+    }
+    /**
+     * Release capacity and wake waiter if present.
+     */
+    releaseCapacity(bytes) {
+        debugSession("[CAPACITY] releasing %d bytes: queuedBytes=%d->%d, pendingBytes=%d->%d, hasWaiter=%s", bytes, this.queuedBytes, this.queuedBytes - bytes, this.pendingBytes, Math.max(0, this.pendingBytes - bytes), !!this.capacityWaiter);
+        this.queuedBytes -= bytes;
+        this.pendingBytes = Math.max(0, this.pendingBytes - bytes);
+        // Wake single waiter
+        const waiter = this.capacityWaiter;
+        if (waiter) {
+            debugSession("[CAPACITY] waking waiter");
+            this.capacityWaiter = undefined;
+            waiter();
+        }
+    }
+    /**
+     * Ensure pump loop is running.
+     */
+    ensurePump() {
+        if (this.pumpPromise || this.pumpStopped) {
+            return;
+        }
+        this.pumpPromise = this.runPump().catch((e) => {
+            debugSession("pump crashed unexpectedly: %s", e);
+            // This should never happen - pump handles all errors internally
+        });
+    }
+    /**
+     * Main pump loop: processes inflight queue, handles acks, retries, and recovery.
+     */
+    async runPump() {
+        debugSession("pump started");
+        while (true) {
+            debugSession("[PUMP] loop: inflight=%d, queuedBytes=%d, pendingBytes=%d, closing=%s, pumpStopped=%s", this.inflight.length, this.queuedBytes, this.pendingBytes, this.closing, this.pumpStopped);
+            // Check if we should stop
+            if (this.pumpStopped) {
+                debugSession("[PUMP] stopped by flag");
+                return;
+            }
+            // If closing and queue is empty, stop
+            if (this.closing && this.inflight.length === 0) {
+                debugSession("[PUMP] closing and queue empty, stopping");
+                this.pumpStopped = true;
+                return;
+            }
+            // If no entries, sleep and continue
+            if (this.inflight.length === 0) {
+                debugSession("[PUMP] no entries, sleeping 10ms");
+                // Use interruptible sleep - can be woken by new submissions
+                await Promise.race([
+                    sleep(10),
+                    new Promise((resolve) => {
+                        this.pumpWakeup = resolve;
+                    }),
+                ]);
+                this.pumpWakeup = undefined;
+                continue;
+            }
+            // Get head entry (we know it exists because we checked length above)
+            const head = this.inflight[0];
+            debugSession("[PUMP] processing head: expectedCount=%d, meteredBytes=%d", head.expectedCount, head.meteredBytes);
+            // Ensure session exists
+            debugSession("[PUMP] ensuring session exists");
+            await this.ensureSession();
+            if (!this.session) {
+                // Session creation failed - will retry
+                debugSession("[PUMP] session creation failed, sleeping 100ms");
+                await sleep(100);
+                continue;
+            }
+            // Submit ALL entries that need submitting (enables HTTP/2 pipelining for S2S)
+            for (const entry of this.inflight) {
+                if (!entry.innerPromise || entry.needsSubmit) {
+                    debugSession("[PUMP] submitting entry to inner session (%d records, %d bytes)", entry.expectedCount, entry.meteredBytes);
+                    entry.attemptStartedMonotonicMs = performance.now();
+                    entry.innerPromise = this.session.submit(entry.records, entry.args);
+                    delete entry.needsSubmit;
+                }
+            }
+            // Wait for head with timeout
+            debugSession("[PUMP] waiting for head result");
+            const result = await this.waitForHead(head);
+            debugSession("[PUMP] got result: kind=%s", result.kind);
+            if (result.kind === "timeout") {
+                // Ack timeout - fatal (per-attempt)
+                const attemptElapsed = head.attemptStartedMonotonicMs != null
+                    ? Math.round(performance.now() - head.attemptStartedMonotonicMs)
+                    : undefined;
+                const error = new error_js_1.S2Error({
+                    message: `Request timeout after ${attemptElapsed ?? "unknown"}ms (${head.expectedCount} records, ${head.meteredBytes} bytes)`,
+                    status: 408,
+                    code: "REQUEST_TIMEOUT",
+                });
+                debugSession("ack timeout for head entry: %s", error.message);
+                await this.abort(error);
+                return;
+            }
+            // Promise settled
+            const appendResult = result.value;
+            if (appendResult.ok) {
+                // Success!
+                const ack = appendResult.value;
+                debugSession("[PUMP] success, got ack", { ack });
+                // Invariant check: ack count matches batch count
+                const ackCount = Number(ack.end.seq_num) - Number(ack.start.seq_num);
+                if (ackCount !== head.expectedCount) {
+                    const error = (0, error_js_1.invariantViolation)(`Ack count mismatch: expected ${head.expectedCount}, got ${ackCount}`);
+                    debugSession("invariant violation: %s", error.message);
+                    await this.abort(error);
+                    return;
+                }
+                // Invariant check: sequence numbers must be strictly increasing
+                if (this._lastAckedPosition) {
+                    const prevEnd = BigInt(this._lastAckedPosition.end.seq_num);
+                    const currentEnd = BigInt(ack.end.seq_num);
+                    if (currentEnd <= prevEnd) {
+                        const error = (0, error_js_1.invariantViolation)(`Sequence number not strictly increasing: previous=${prevEnd}, current=${currentEnd}`);
+                        debugSession("invariant violation: %s", error.message);
+                        await this.abort(error);
+                        return;
+                    }
+                }
+                // Update last acked position
+                this._lastAckedPosition = ack;
+                // Resolve submit() caller if present
+                if (head.maybeResolve) {
+                    head.maybeResolve((0, result_js_1.ok)(ack));
+                }
+                // Emit to readable stream
+                try {
+                    this.acksController?.enqueue(ack);
+                }
+                catch (e) {
+                    debugSession("failed to enqueue ack: %s", e);
+                }
+                // Remove from inflight and release capacity
+                debugSession("[PUMP] removing head from inflight, releasing %d bytes", head.meteredBytes);
+                this.inflight.shift();
+                this.releaseCapacity(head.meteredBytes);
+                // Reset consecutive failures on success
+                this.consecutiveFailures = 0;
+                this.currentAttempt = 0;
+            }
+            else {
+                // Error result
+                const error = appendResult.error;
+                debugSession("[PUMP] error: status=%s, message=%s", error.status, error.message);
+                // Check if retryable
+                if (!isRetryable(error)) {
+                    debugSession("error not retryable, aborting");
+                    await this.abort(error);
+                    return;
+                }
+                // Check policy compliance
+                if (this.retryConfig.appendRetryPolicy === "noSideEffects" &&
+                    !this.isIdempotent(head)) {
+                    debugSession("error not policy-compliant (noSideEffects), aborting");
+                    await this.abort(error);
+                    return;
+                }
+                // Check max attempts (total attempts include initial; retries = max - 1)
+                const effectiveMax = Math.max(1, this.retryConfig.maxAttempts);
+                const allowedRetries = effectiveMax - 1;
+                if (this.currentAttempt >= allowedRetries) {
+                    debugSession("max attempts reached (%d), aborting", effectiveMax);
+                    const wrappedError = new error_js_1.S2Error({
+                        message: `Max attempts (${effectiveMax}) exhausted: ${error.message}`,
+                        status: error.status,
+                        code: error.code,
+                    });
+                    await this.abort(wrappedError);
+                    return;
+                }
+                // Perform recovery
+                this.consecutiveFailures++;
+                this.currentAttempt++;
+                debugSession("performing recovery (retry %d/%d)", this.currentAttempt, allowedRetries);
+                await this.recover();
+            }
+        }
+    }
+    /**
+     * Wait for head entry's innerPromise with timeout.
+     * Returns either the settled result or a timeout indicator.
+     *
+     * Per-attempt ack timeout semantics:
+     * - The deadline is computed from the most recent (re)submit attempt using
+     *   a monotonic clock (performance.now) to avoid issues with wall clock
+     *   adjustments.
+     * - If attempt start is missing (for backward compatibility), we measure
+     *   from "now" with the full timeout window.
+     */
+    async waitForHead(head) {
+        const startMono = head.attemptStartedMonotonicMs ?? performance.now();
+        const deadline = startMono + this.requestTimeoutMillis;
+        const remaining = Math.max(0, deadline - performance.now());
+        let timer;
+        const timeoutP = new Promise((resolve) => {
+            timer = setTimeout(() => resolve({ kind: "timeout" }), remaining);
+        });
+        const settledP = head.innerPromise.then((result) => ({
+            kind: "settled",
+            value: result,
+        }));
+        try {
+            return await Promise.race([settledP, timeoutP]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    /**
+     * Recover from transient error: recreate session and resubmit all inflight entries.
+     */
+    async recover() {
+        debugSession("starting recovery");
+        // Calculate backoff delay
+        const delay = calculateDelay(this.consecutiveFailures - 1, this.retryConfig.retryBackoffDurationMillis);
+        debugSession("backing off for %dms", delay);
+        await sleep(delay);
+        // Teardown old session
+        if (this.session) {
+            try {
+                const closeResult = await this.session.close();
+                if (!closeResult.ok) {
+                    debugSession("error closing old session during recovery: %s", closeResult.error.message);
+                }
+            }
+            catch (e) {
+                debugSession("exception closing old session: %s", e);
+            }
+            this.session = undefined;
+        }
+        // Create new session
+        await this.ensureSession();
+        if (!this.session) {
+            debugSession("failed to create new session during recovery");
+            // Will retry on next pump iteration
+            return;
+        }
+        // Store session in local variable to help TypeScript type narrowing
+        const session = this.session;
+        // Resubmit all inflight entries (replace their innerPromise and reset attempt start)
+        debugSession("resubmitting %d inflight entries", this.inflight.length);
+        for (const entry of this.inflight) {
+            // Attach .catch to superseded promise to avoid unhandled rejection
+            entry.innerPromise.catch(() => { });
+            // Create new promise from new session
+            entry.attemptStartedMonotonicMs = performance.now();
+            entry.innerPromise = session.submit(entry.records, entry.args);
+        }
+        debugSession("recovery complete");
+    }
+    /**
+     * Check if append can be retried under noSideEffects policy.
+     * For appends, idempotency requires match_seq_num.
+     */
+    isIdempotent(entry) {
+        const args = entry.args;
+        if (!args)
+            return false;
+        return args.match_seq_num !== undefined;
+    }
+    /**
+     * Ensure session exists, creating it if necessary.
+     */
+    async ensureSession() {
+        if (this.session) {
+            return;
+        }
+        try {
+            this.session = await this.generator(this.sessionOptions);
+        }
+        catch (e) {
+            const error = (0, error_js_1.s2Error)(e);
+            debugSession("failed to create session: %s", error.message);
+            // Don't set this.session - will retry later
+        }
+    }
+    /**
+     * Abort the session with a fatal error.
+     */
+    async abort(error) {
+        if (this.pumpStopped) {
+            return; // Already aborted
+        }
+        debugSession("aborting session: %s", error.message);
+        this.fatalError = error;
+        this.pumpStopped = true;
+        // Resolve all inflight entries with error
+        for (const entry of this.inflight) {
+            if (entry.maybeResolve) {
+                entry.maybeResolve((0, result_js_1.err)(error));
+            }
+        }
+        this.inflight.length = 0;
+        this.queuedBytes = 0;
+        this.pendingBytes = 0;
+        // Error the readable stream
+        try {
+            this.acksController?.error(error);
+        }
+        catch (e) {
+            debugSession("failed to error acks controller: %s", e);
+        }
+        // Wake capacity waiter to unblock any pending writer
+        if (this.capacityWaiter) {
+            this.capacityWaiter();
+            this.capacityWaiter = undefined;
+        }
+        // Close inner session
+        if (this.session) {
+            try {
+                await this.session.close();
+            }
+            catch (e) {
+                debugSession("error closing session during abort: %s", e);
+            }
+            this.session = undefined;
+        }
+    }
+    /**
+     * Close the append session.
+     * Waits for all pending appends to complete before resolving.
+     * Does not interrupt recovery - allows it to complete.
+     */
+    async close() {
+        if (this.closed) {
+            if (this.fatalError) {
+                throw this.fatalError;
+            }
+            return;
+        }
+        debugSession("close requested");
+        this.closing = true;
+        // Wake pump if it's sleeping so it can check closing flag
+        if (this.pumpWakeup) {
+            this.pumpWakeup();
+        }
+        // Wait for pump to stop (drains inflight queue, including through recovery)
+        if (this.pumpPromise) {
+            await this.pumpPromise;
+        }
+        // Close inner session
+        if (this.session) {
+            try {
+                const result = await this.session.close();
+                if (!result.ok) {
+                    debugSession("error closing inner session: %s", result.error.message);
+                }
+            }
+            catch (e) {
+                debugSession("exception closing inner session: %s", e);
+            }
+            this.session = undefined;
+        }
+        // Close readable stream
+        try {
+            this.acksController?.close();
+        }
+        catch (e) {
+            debugSession("error closing acks controller: %s", e);
+        }
+        this.closed = true;
+        // If fatal error occurred, throw it
+        if (this.fatalError) {
+            throw this.fatalError;
+        }
+        debugSession("close complete");
+    }
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+    /**
+     * Get a stream of acknowledgements for appends.
+     */
+    acks() {
+        return this.readable;
+    }
+    /**
+     * Get the last acknowledged position.
+     */
+    lastAckedPosition() {
+        return this._lastAckedPosition;
+    }
+}
+exports.RetryAppendSession = RetryAppendSession;
+//# sourceMappingURL=retry.js.map