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

package/dist/index.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "crypto";
 import { PubSub } from "@mastra/core/events";
-import { Batch, Decoder, GlideClient } from "@valkey/valkey-glide";
+import { Batch, Decoder, GlideClient, InfBoundary } from "@valkey/valkey-glide";
 //#region src/client.ts
 const text = (value) => Buffer.isBuffer(value) ? value.toString() : String(value);
 var ValkeyMulti = class {
@@ -93,18 +93,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: 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
+			} : InfBoundary.NegativeInfinity,
+			end: 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: 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]);
@@ -159,6 +173,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
@@ -189,6 +229,7 @@ var ValkeyStreamsPubSub = class extends PubSub {
 	#reclaimIntervalMs;
 	#reclaimIdleMs;
 	#maxDeliveryAttempts;
+	#inFlightTimeoutMs;
 	#logger;
 	#subscriptions = /* @__PURE__ */ new Map();
 	#cbIds = /* @__PURE__ */ new WeakMap();
@@ -219,6 +260,9 @@ var ValkeyStreamsPubSub = class extends 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
@@ -274,6 +318,15 @@ var ValkeyStreamsPubSub = class extends 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 = randomUUID();
 		const createdAt = /* @__PURE__ */ new Date();
@@ -290,18 +343,12 @@ var ValkeyStreamsPubSub = class extends 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");
@@ -344,41 +391,91 @@ var ValkeyStreamsPubSub = class extends 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);
@@ -411,6 +508,7 @@ var ValkeyStreamsPubSub = class extends 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) {
@@ -578,6 +676,7 @@ var ValkeyStreamsPubSub = class extends 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) {
@@ -662,6 +761,8 @@ var ValkeyStreamsPubSub = class extends PubSub {
 					topic: sub.topic,
 					err: err instanceof Error ? err.message : err
 				});
+			} finally {
+				sub.inFlight.delete(streamId);
 			}
 		};
 		const nack = async () => {
@@ -683,6 +784,8 @@ var ValkeyStreamsPubSub = class extends PubSub {
 						topic: sub.topic,
 						err: err instanceof Error ? err.message : err
 					});
+				} finally {
+					sub.inFlight.delete(streamId);
 				}
 				return;
 			}
@@ -700,6 +803,7 @@ var ValkeyStreamsPubSub = class extends PubSub {
 					err: err instanceof Error ? err.message : err
 				});
 				settled = false;
+				sub.inFlight.delete(streamId);
 				return;
 			}
 			try {
@@ -709,8 +813,62 @@ var ValkeyStreamsPubSub = class extends 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 () => {