@mastra/valkey-streams 0.5.1-alpha.1 → 0.5.2-alpha.0

package/dist/client.d.ts

@@ -53,17 +53,25 @@ export declare class ValkeyStreamsClient {
         COUNT?: number;
         BLOCK?: number;
     }): Promise<StreamReply[] | null>;
-    xAutoClaim(key: string, group: string, consumer: string, minIdle: number, start: string, options?: {
-        COUNT?: number;
+    /**
+     * XPENDING <key> <group> [IDLE ms] <start> + <count>. `afterId` makes the
+     * range exclusive so callers can page past entries they've already seen.
+     */
+    xPendingRange(key: string, group: string, count: number, options?: {
+        IDLE?: number;
+        afterId?: string;
     }): Promise<{
-        nextId: string;
-        messages: {
-            id: string;
-            message: {
-                [k: string]: string;
-            };
-        }[];
-    }>;
+        id: string;
+        consumer: string;
+        millisecondsSinceLastDelivery: number;
+        deliveriesCounter: number;
+    }[]>;
+    xClaim(key: string, group: string, consumer: string, minIdle: number, ids: string[]): Promise<{
+        id: string;
+        message: {
+            [k: string]: string;
+        };
+    }[]>;
     xAck(key: string, group: string, id: string): Promise<number>;
     del(key: string): Promise<number>;
     set(key: string, value: string, options?: {

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.cjs

@@ -94,18 +94,32 @@ var ValkeyStreamsClient = class {
 			}))
 		})) ?? null;
 	}
-	async xAutoClaim(key, group, consumer, minIdle, start, options = {}) {
-		const result = await (await this.getClient()).xautoclaim(key, group, consumer, minIdle, start, {
-			count: options.COUNT,
-			decoder: _valkey_valkey_glide.Decoder.String
-		});
-		return {
-			nextId: text(result[0]),
-			messages: Object.entries(result[1] ?? {}).map(([id, fields]) => ({
-				id,
-				message: Object.fromEntries(fields.map(([field, value]) => [text(field), text(value)]))
-			}))
-		};
+	/**
+	* XPENDING <key> <group> [IDLE ms] <start> + <count>. `afterId` makes the
+	* range exclusive so callers can page past entries they've already seen.
+	*/
+	async xPendingRange(key, group, count, options = {}) {
+		return (await (await this.getClient()).xpendingWithOptions(key, group, {
+			start: options.afterId ? {
+				value: options.afterId,
+				isInclusive: false
+			} : _valkey_valkey_glide.InfBoundary.NegativeInfinity,
+			end: _valkey_valkey_glide.InfBoundary.PositiveInfinity,
+			count,
+			minIdleTime: options.IDLE
+		})).map(([id, consumer, millisecondsSinceLastDelivery, deliveriesCounter]) => ({
+			id: text(id),
+			consumer: text(consumer),
+			millisecondsSinceLastDelivery,
+			deliveriesCounter
+		}));
+	}
+	async xClaim(key, group, consumer, minIdle, ids) {
+		const result = await (await this.getClient()).xclaim(key, group, consumer, minIdle, ids, { decoder: _valkey_valkey_glide.Decoder.String });
+		return Object.entries(result ?? {}).map(([id, fields]) => ({
+			id,
+			message: Object.fromEntries(fields.map(([field, value]) => [text(field), text(value)]))
+		}));
 	}
 	async xAck(key, group, id) {
 		return (await this.getClient()).xack(key, group, [id]);
@@ -160,6 +174,32 @@ var ValkeyStreamsClient = class {
 const createClient = (options) => new ValkeyStreamsClient(options);
 //#endregion
 //#region src/index.ts
+/** Page size for the reclaim loop's XPENDING scan and the max entries claimed per tick. */
+const RECLAIM_PAGE_SIZE = 100;
+/**
+* Atomically nack a pending entry only if it is still owned by the given
+* consumer. Returns 1 if this consumer owned it and it was settled, 0 if the
+* entry was not pending for this consumer (acked, or claimed by a sibling).
+*
+* KEYS[1] stream key
+* ARGV[1] group, ARGV[2] consumer, ARGV[3] stream entry id,
+* ARGV[4] republish payload ('' = drop without republish),
+* ARGV[5] stream idle TTL in ms (0 = none)
+*/
+const NACK_IF_OWNED_SCRIPT = `
+  local pending = redis.call("XPENDING", KEYS[1], ARGV[1], ARGV[3], ARGV[3], 1)
+  if #pending == 0 or pending[1][2] ~= ARGV[2] then
+    return 0
+  end
+  if ARGV[4] ~= "" then
+    redis.call("XADD", KEYS[1], "*", "event", ARGV[4])
+    if tonumber(ARGV[5]) > 0 then
+      redis.call("PEXPIRE", KEYS[1], ARGV[5])
+    end
+  end
+  redis.call("XACK", KEYS[1], ARGV[1], ARGV[3])
+  return 1
+`;
 /**
 * Flatten an error into searchable text. node-redis MULTI failures throw a
 * `MultiErrorReply` whose own message is just "N commands failed…" — the real
@@ -190,6 +230,7 @@ var ValkeyStreamsPubSub = class extends _mastra_core_events.PubSub {
 	#reclaimIntervalMs;
 	#reclaimIdleMs;
 	#maxDeliveryAttempts;
+	#inFlightTimeoutMs;
 	#logger;
 	#subscriptions = /* @__PURE__ */ new Map();
 	#cbIds = /* @__PURE__ */ new WeakMap();
@@ -220,6 +261,9 @@ var ValkeyStreamsPubSub = class extends _mastra_core_events.PubSub {
 			this.#maxDeliveryAttempts = Infinity;
 		} else if (cap < 0 || Number.isNaN(cap)) throw new Error(`valkey-streams: maxDeliveryAttempts must be >= 1 or Infinity, got ${cap}`);
 		else this.#maxDeliveryAttempts = cap;
+		const inFlightTimeout = options.inFlightTimeoutMs ?? 0;
+		if (!Number.isFinite(inFlightTimeout) || inFlightTimeout < 0) throw new Error(`valkey-streams: inFlightTimeoutMs must be a non-negative number (milliseconds), got ${inFlightTimeout}`);
+		this.#inFlightTimeoutMs = inFlightTimeout;
 	}
 	/**
 	* Attach the `'error'` listener node-redis requires on every client. Without
@@ -275,6 +319,15 @@ var ValkeyStreamsPubSub = class extends _mastra_core_events.PubSub {
 			this.#deliverLocal(topic, localEvent);
 			return;
 		}
+		const promise = this.#publishRemote(topic, event);
+		this.#pendingPublishes.add(promise);
+		try {
+			await promise;
+		} finally {
+			this.#pendingPublishes.delete(promise);
+		}
+	}
+	async #publishRemote(topic, event) {
 		await this.#ensureWriterConnected();
 		const id = (0, crypto.randomUUID)();
 		const createdAt = /* @__PURE__ */ new Date();
@@ -291,18 +344,12 @@ var ValkeyStreamsPubSub = class extends _mastra_core_events.PubSub {
 			threshold: this.#maxStreamLength
 		};
 		const streamKey = this.#streamKey(topic);
-		const promise = this.#streamIdleTtlMs > 0 ? this.#writeClient.multi().xAdd(streamKey, "*", { event: JSON.stringify(payload) }, xaddOptions).pExpire(streamKey, this.#streamIdleTtlMs).exec().then((replies) => {
+		await (this.#streamIdleTtlMs > 0 ? this.#writeClient.multi().xAdd(streamKey, "*", { event: JSON.stringify(payload) }, xaddOptions).pExpire(streamKey, this.#streamIdleTtlMs).exec().then((replies) => {
 			if (Number(replies[1]) !== 1) this.#logger?.warn?.("valkey-streams: PEXPIRE inside publish MULTI did not apply", {
 				streamKey,
 				reply: String(replies[1])
 			});
-		}) : this.#writeClient.xAdd(streamKey, "*", { event: JSON.stringify(payload) }, xaddOptions);
-		this.#pendingPublishes.add(promise);
-		try {
-			await promise;
-		} finally {
-			this.#pendingPublishes.delete(promise);
-		}
+		}) : this.#writeClient.xAdd(streamKey, "*", { event: JSON.stringify(payload) }, xaddOptions));
 	}
 	async subscribe(topic, cb, options) {
 		if (this.#closed) throw new Error("ValkeyStreamsPubSub: cannot subscribe on closed client");
@@ -345,41 +392,91 @@ var ValkeyStreamsPubSub = class extends _mastra_core_events.PubSub {
 			readClient,
 			stopped: false,
 			loop: void 0,
-			reclaimTimer: void 0
+			reclaimTimer: void 0,
+			inFlight: /* @__PURE__ */ new Map()
 		};
 		this.#subscriptions.set(key, sub);
 		sub.loop = this.#runReadLoop(sub);
 		this.#startReclaimLoop(sub);
 	}
 	/**
-	* Periodically run XAUTOCLAIM against this subscription's group so that
-	* messages a crashed/stuck consumer read but never acked get redelivered to
-	* a live sibling. Runs only for grouped subscriptions — fan-out groups are
-	* private to one consumer, so there's no sibling to claim from.
+	* Periodically reclaim idle pending entries in this subscription's group so
+	* that messages a crashed/stuck consumer read but never acked get redelivered
+	* to a live sibling. Fan-out groups are private to one consumer, so there is
+	* no sibling to claim from and the XPENDING/XCLAIM scan is skipped for them;
+	* the loop still runs so `inFlightTimeoutMs` can recover a hung handler,
+	* which is the only recovery path a single-consumer group has.
 	*/
 	#startReclaimLoop(sub) {
 		if (this.#reclaimIntervalMs <= 0) return;
-		if (!sub.isGrouped) return;
+		if (!sub.isGrouped && this.#inFlightTimeoutMs <= 0) return;
 		const tick = async () => {
 			if (sub.stopped || this.#closed) return;
 			try {
-				const messages = (await this.#writeClient.xAutoClaim(sub.streamKey, sub.group, sub.consumer, this.#reclaimIdleMs, "0-0", { COUNT: 100 }))?.messages ?? [];
-				for (const entry of messages) {
+				await this.#expireInFlight(sub);
+				if (!sub.isGrouped) {
+					sub.reclaimTimer = setTimeout(runTick, this.#reclaimIntervalMs);
+					return;
+				}
+				const ids = [];
+				let afterId;
+				for (;;) {
+					const page = await this.#writeClient.xPendingRange(sub.streamKey, sub.group, RECLAIM_PAGE_SIZE, {
+						IDLE: this.#reclaimIdleMs,
+						afterId
+					});
+					for (const p of page) {
+						if (sub.inFlight.has(p.id)) continue;
+						ids.push(p.id);
+						if (ids.length >= RECLAIM_PAGE_SIZE) break;
+					}
+					if (page.length < RECLAIM_PAGE_SIZE || ids.length >= RECLAIM_PAGE_SIZE) break;
+					afterId = page[page.length - 1].id;
+				}
+				if (ids.length === 0 || sub.stopped || this.#closed) {
 					if (sub.stopped || this.#closed) return;
-					if (!entry) continue;
-					await this.#deliverMessage(sub, entry.id, entry.message);
+					sub.reclaimTimer = setTimeout(runTick, this.#reclaimIntervalMs);
+					return;
 				}
+				const claimed = await this.#writeClient.xClaim(sub.streamKey, sub.group, sub.consumer, this.#reclaimIdleMs, ids);
+				for (const entry of claimed) await this.#deliverMessage(sub, entry.id, entry.message);
 			} catch (err) {
-				this.#logger?.debug?.("valkey-streams: XAUTOCLAIM failed", {
+				this.#logger?.debug?.("valkey-streams: reclaim failed", {
 					topic: sub.topic,
 					group: sub.group,
 					err: err instanceof Error ? err.message : err
 				});
 			}
 			if (sub.stopped || this.#closed) return;
-			sub.reclaimTimer = setTimeout(tick, this.#reclaimIntervalMs);
+			sub.reclaimTimer = setTimeout(runTick, this.#reclaimIntervalMs);
+		};
+		const runTick = () => {
+			sub.reclaimLoop = tick().finally(() => {
+				sub.reclaimLoop = void 0;
+			});
 		};
-		sub.reclaimTimer = setTimeout(tick, this.#reclaimIntervalMs);
+		sub.reclaimTimer = setTimeout(runTick, this.#reclaimIntervalMs);
+	}
+	/**
+	* Give up on local in-flight entries older than `inFlightTimeoutMs` by
+	* nacking them on the handler's behalf. This is the only way a
+	* single-consumer group recovers a hung handler: the reclaim loop never
+	* claims its own in-flight entries (see the tick above), so without a
+	* timeout the entry stays pending until the process restarts.
+	*/
+	async #expireInFlight(sub) {
+		if (this.#inFlightTimeoutMs <= 0) return;
+		const cutoff = Date.now() - this.#inFlightTimeoutMs;
+		for (const [streamId, entry] of sub.inFlight) {
+			if (entry.since > cutoff) continue;
+			this.#logger?.warn?.("valkey-streams: handler exceeded inFlightTimeoutMs; nacking on its behalf", {
+				topic: sub.topic,
+				group: sub.group,
+				streamId,
+				inFlightMs: Date.now() - entry.since
+			});
+			await entry.expire();
+		}
 	}
 	async unsubscribe(topic, cb) {
 		const localBucket = this.#localCallbacks.get(topic);
@@ -412,6 +509,7 @@ var ValkeyStreamsPubSub = class extends _mastra_core_events.PubSub {
 				err: err instanceof Error ? err.message : err
 			});
 		}
+		await sub.reclaimLoop;
 		if (!sub.isGrouped) try {
 			await this.#writeClient.xGroupDestroy(sub.streamKey, sub.group);
 		} catch (err) {
@@ -579,6 +677,7 @@ var ValkeyStreamsPubSub = class extends _mastra_core_events.PubSub {
 		const subs = [...this.#subscriptions.values()];
 		await Promise.all(subs.map((sub) => this.unsubscribe(sub.topic, sub.cb)));
 		this.#localCallbacks.clear();
+		await this.flush();
 		if (this.#writeClient.isOpen) try {
 			await this.#writeClient.quit();
 		} catch (err) {
@@ -663,6 +762,8 @@ var ValkeyStreamsPubSub = class extends _mastra_core_events.PubSub {
 					topic: sub.topic,
 					err: err instanceof Error ? err.message : err
 				});
+			} finally {
+				sub.inFlight.delete(streamId);
 			}
 		};
 		const nack = async () => {
@@ -684,6 +785,8 @@ var ValkeyStreamsPubSub = class extends _mastra_core_events.PubSub {
 						topic: sub.topic,
 						err: err instanceof Error ? err.message : err
 					});
+				} finally {
+					sub.inFlight.delete(streamId);
 				}
 				return;
 			}
@@ -701,6 +804,7 @@ var ValkeyStreamsPubSub = class extends _mastra_core_events.PubSub {
 					err: err instanceof Error ? err.message : err
 				});
 				settled = false;
+				sub.inFlight.delete(streamId);
 				return;
 			}
 			try {
@@ -710,8 +814,62 @@ var ValkeyStreamsPubSub = class extends _mastra_core_events.PubSub {
 					topic: sub.topic,
 					err: err instanceof Error ? err.message : err
 				});
+			} finally {
+				sub.inFlight.delete(streamId);
+			}
+		};
+		const expire = async () => {
+			if (settled) return;
+			settled = true;
+			const attempt = event.deliveryAttempt ?? 1;
+			const drop = attempt >= this.#maxDeliveryAttempts;
+			const payload = drop ? "" : JSON.stringify({
+				...event,
+				deliveryAttempt: attempt + 1
+			});
+			let owned;
+			try {
+				owned = await this.#writeClient.eval(NACK_IF_OWNED_SCRIPT, {
+					keys: [sub.streamKey],
+					arguments: [
+						sub.group,
+						sub.consumer,
+						streamId,
+						payload,
+						String(this.#streamIdleTtlMs)
+					]
+				});
+			} catch (err) {
+				this.#logger?.warn?.("valkey-streams: timeout nack failed; leaving original pending for reclaim", {
+					topic: sub.topic,
+					eventId: event.id,
+					err: err instanceof Error ? err.message : err
+				});
+				settled = false;
+				sub.inFlight.delete(streamId);
+				return;
+			}
+			sub.inFlight.delete(streamId);
+			if (owned !== 1) {
+				this.#logger?.warn?.("valkey-streams: handler exceeded inFlightTimeoutMs but entry is no longer owned; disowning", {
+					topic: sub.topic,
+					group: sub.group,
+					streamId
+				});
+				return;
 			}
+			if (drop) this.#logger?.warn?.("valkey-streams: dropping event after max delivery attempts", {
+				topic: sub.topic,
+				eventType: event.type,
+				eventId: event.id,
+				attempt,
+				max: this.#maxDeliveryAttempts
+			});
 		};
+		sub.inFlight.set(streamId, {
+			since: Date.now(),
+			expire
+		});
 		try {
 			const result = sub.cb(event, ack, nack);
 			if (result && typeof result.catch === "function") result.catch(async () => {