experimental-a2 0.22.0 → 0.23.0

package/dist/store-redis.js

@@ -1,7 +1,7 @@
 import { i as A2Error } from "./session-clear-wHd5GCpZ.js";
 import { t as retryableLazy } from "./retryable-lazy-DZWmHpii.js";
 import { n as SYSTEM_CLOCK, t as RANDOM_IDS } from "./store-N8PXxDAS.js";
-import { t as createRedisNotifyStore } from "./store-redis-notify-CsJw_hfD.js";
+import { t as createRedisNotifyStore } from "./store-redis-notify-CBDVJxA_.js";
 //#region src/store-redis.ts
 /**
 * experimental-a2/store-redis — the Redis-protocol store backend, on Redis

package/dist/store-valkey.d.ts

@@ -0,0 +1,33 @@
+import { r as Clock, s as IdSource, t as A2Store } from "./store-D0MhBvg6.js";
+import { RedisClientOptions } from "redis";
+//#region src/store-valkey.d.ts
+/**
+ * node-redis `createClient` options. A2 reads replies in their RESP2
+ * shapes, so it always connects with `RESP: 2`, which rules out `RESP`
+ * and the options that need RESP3.
+ */
+type ValkeyClientOptions = Omit<RedisClientOptions, "RESP" | "clientSideCache" | "emitInvalidate" | "maintNotifications">;
+type ValkeyStoreOptions = {
+  /** `redis://` or `rediss://` URL. Overrides `clientOptions.url`. */
+  url?: string | undefined;
+  /**
+   * Options for both clients A2 creates: `socket` (TLS, connect timeout,
+   * `reconnectStrategy`), `credentialsProvider`, `commandOptions`,
+   * `disableOfflineQueue`, and so on.
+   */
+  clientOptions?: ValkeyClientOptions;
+  /** Key prefix — isolates multiple apps on one server. Default `'a2'`. */
+  keyPrefix?: string;
+  /** Injectable clock — every stored timestamp comes from here. */
+  clock?: Clock;
+  /** Injectable id source for generated event ids. */
+  ids?: IdSource;
+};
+type ValkeyStore = A2Store & {
+  /** Destroy the command client and the subscriber. */
+  close(): Promise<void>;
+};
+declare function valkey(options?: ValkeyStoreOptions): ValkeyStore;
+//#endregion
+export { ValkeyClientOptions, ValkeyStore, ValkeyStoreOptions, valkey };
+//# sourceMappingURL=store-valkey.d.ts.map

package/dist/store-valkey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-valkey.d.ts","names":[],"sources":["../src/store-valkey.ts"],"mappings":";;;;;;;;KAuCY,sBAAsB,KAChC;KAIU;;EAEV;;;;;;EAMA,gBAAgB;;EAEhB;;EAEA,QAAQ;;EAER,MAAM;;KAGI,cAAc;;EAExB,SAAS;;iBAkJK,OAAO,UAAS,qBAA0B"}

package/dist/store-valkey.js

@@ -0,0 +1,218 @@
+import { i as A2Error } from "./session-clear-wHd5GCpZ.js";
+import { t as retryableLazy } from "./retryable-lazy-DZWmHpii.js";
+import { n as SYSTEM_CLOCK, t as RANDOM_IDS } from "./store-N8PXxDAS.js";
+import { t as createRedisNotifyStore } from "./store-redis-notify-CBDVJxA_.js";
+//#region src/store-valkey.ts
+/** Overrides any `commandOptions.typeMapping`: replies decode as strings. */
+const STRING_REPLIES = { typeMapping: {} };
+/**
+* node-redis 6 needs `destroy()` to release a client whose reconnect
+* strategy gave up; node-redis 5 throws there instead.
+*/
+const dispose = (client) => {
+	try {
+		client?.destroy();
+	} catch {}
+};
+const closedError = () => new A2Error("STORE_UNAVAILABLE", "the store was closed");
+/** node-redis 6's default `commandOptions.timeout`; node-redis 5 has none. */
+const DEFAULT_TIMEOUT_MS = 5e3;
+/**
+* One A2-owned client at a time. `get` hands a new client out once it
+* first reports ready, waiting at most `timeoutMs` per call while it keeps
+* connecting, so `disableOfflineQueue` cannot reject a cold start's first
+* calls. Later reconnects follow node-redis's offline queue,
+* `disableOfflineQueue`, and command timeouts. A client whose connect
+* failed, or whose reconnect strategy gave up, is closed for good, so the
+* next `get` replaces it.
+*/
+const ownedClient = (options) => {
+	let current = null;
+	let closed = false;
+	const firstReady = async (entry) => {
+		const client = await entry.created;
+		if (entry.ready) return client;
+		let timer;
+		try {
+			await Promise.race([entry.connected, new Promise((_, reject) => {
+				timer = setTimeout(() => {
+					reject(new A2Error("STORE_UNAVAILABLE", `connect timed out after ${options.timeoutMs}ms`));
+				}, options.timeoutMs);
+			})]);
+		} catch (err) {
+			if (err instanceof A2Error) throw err;
+			throw new A2Error("STORE_UNAVAILABLE", "connect failed", { cause: err });
+		} finally {
+			clearTimeout(timer);
+		}
+		return client;
+	};
+	return {
+		get() {
+			if (closed) return Promise.reject(closedError());
+			if (current && (current.client === null || current.client.isOpen)) return firstReady(current);
+			dispose(current?.client);
+			const entry = {
+				client: null,
+				connected: null,
+				ready: false,
+				created: options.driver().then((driver) => {
+					if (closed) throw closedError();
+					const client = driver.create();
+					entry.client = client;
+					client.on("error", () => {});
+					entry.connected = client.connect().then(() => {
+						entry.ready = true;
+					}, (err) => {
+						if (current === entry) {
+							dispose(client);
+							current = null;
+						}
+						throw err;
+					});
+					entry.connected.catch(() => {});
+					options.opened(client);
+					return client;
+				})
+			};
+			current = entry;
+			entry.created.catch(() => {
+				if (current === entry) current = null;
+			});
+			return firstReady(entry);
+		},
+		close() {
+			closed = true;
+			dispose(current?.client);
+			current = null;
+		}
+	};
+};
+function valkey(options = {}) {
+	const clock = options.clock ?? SYSTEM_CLOCK;
+	const ids = options.ids ?? RANDOM_IDS;
+	const prefix = options.keyPrefix ?? "a2";
+	if (!options.url && !options.clientOptions) throw new TypeError("valkey() needs a url or clientOptions");
+	const clientOptions = {
+		...options.clientOptions,
+		...options.url ? { url: options.url } : {},
+		RESP: 2
+	};
+	const driver = retryableLazy(async () => {
+		const mod = await import("redis").catch(() => {
+			throw new A2Error("STORE_NOT_CONFIGURED", "experimental-a2/store-valkey needs the 'redis' package (optional peer dependency) — install it");
+		});
+		return {
+			create: () => mod.createClient(clientOptions),
+			bytes: { typeMapping: { [mod.RESP_TYPES.BLOB_STRING]: Buffer } }
+		};
+	});
+	const timeoutMs = clientOptions.commandOptions?.timeout ?? DEFAULT_TIMEOUT_MS;
+	const commands = ownedClient({
+		driver: driver.get,
+		opened: () => {},
+		timeoutMs
+	});
+	/**
+	* Channels the subscriber holds, restored on a replacement client. Each
+	* maps to the call that subscribed it, so a failed call only forgets its
+	* own subscription.
+	*/
+	const channels = /* @__PURE__ */ new Map();
+	let deliver;
+	let reconnected;
+	const onMessage = (message, channel) => {
+		deliver?.(channel, message);
+	};
+	const resubscribed = () => {
+		for (const channel of channels.keys()) reconnected?.(channel);
+	};
+	/**
+	* node-redis queues SUBSCRIBE outside `sendCommand`, so neither
+	* `disableOfflineQueue` nor `commandOptions.timeout` applies to it: a
+	* subscribe sent while the subscriber reconnects would wait for the
+	* server indefinitely. Apply both here. A timed-out SUBSCRIBE stays
+	* queued, so an UNSUBSCRIBE queued behind it cancels it.
+	*/
+	const subscribeBounded = async (client, channel) => {
+		if (!client.isReady && clientOptions.disableOfflineQueue) throw new A2Error("STORE_UNAVAILABLE", "the subscriber is offline");
+		let timer;
+		const timedOut = new Promise((_, reject) => {
+			timer = setTimeout(() => {
+				client.unsubscribe(channel).catch(() => {});
+				reject(new A2Error("STORE_UNAVAILABLE", `subscribe timed out after ${timeoutMs}ms`));
+			}, timeoutMs);
+		});
+		try {
+			return await Promise.race([client.subscribe(channel, onMessage), timedOut]);
+		} finally {
+			clearTimeout(timer);
+		}
+	};
+	const subscriber = ownedClient({
+		driver: driver.get,
+		opened: (client) => {
+			let readies = 0;
+			client.on("ready", () => {
+				readies += 1;
+				if (readies > 1) resubscribed();
+			});
+			if (channels.size === 0) return;
+			Promise.all([...channels.keys()].map((channel) => client.subscribe(channel, onMessage))).then(resubscribed, () => {});
+		},
+		timeoutMs
+	});
+	const subscriberConnection = {
+		async call(command, ...args) {
+			const channel = String(args[0]);
+			const name = command.toLowerCase();
+			if (name === "subscribe") {
+				const call = Symbol(channel);
+				try {
+					const client = await subscriber.get();
+					channels.set(channel, call);
+					return await subscribeBounded(client, channel);
+				} catch (err) {
+					if (channels.get(channel) === call) channels.delete(channel);
+					throw err;
+				}
+			}
+			if (name === "unsubscribe") {
+				channels.delete(channel);
+				return (await subscriber.get()).unsubscribe(channel);
+			}
+			return (await subscriber.get()).sendCommand([command, ...args.map(String)], STRING_REPLIES);
+		},
+		duplicate: () => subscriberConnection,
+		on(_event, listener) {
+			deliver = listener;
+		},
+		disconnect: subscriber.close
+	};
+	const commandConnection = {
+		call: async (command, ...args) => (await commands.get()).sendCommand([command, ...args.map(String)], STRING_REPLIES),
+		duplicate: () => subscriberConnection,
+		on: () => void 0,
+		disconnect: commands.close
+	};
+	return createRedisNotifyStore({
+		client: () => Promise.resolve(commandConnection),
+		callBytes: async (command, ...args) => {
+			const { bytes } = await driver.get();
+			return (await commands.get()).sendCommand([command, ...args.map(String)], bytes);
+		},
+		clock,
+		ids,
+		keyPrefix: prefix,
+		onReconnect: (listener) => {
+			reconnected = listener;
+		},
+		async closeClient() {
+			commands.close();
+		}
+	});
+}
+//#endregion
+export { valkey };
+
+//# sourceMappingURL=store-valkey.js.map

package/dist/store-valkey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-valkey.js","names":[],"sources":["../src/store-valkey.ts"],"sourcesContent":["/**\n * experimental-a2/store-valkey — the Redis store on node-redis connections,\n * for Valkey and Redis servers that need more than a URL: TLS settings,\n * rotating credentials (such as ElastiCache IAM tokens), reconnect\n * strategies, and timeouts. Storage and the live feed are the ones\n * experimental-a2/store-redis uses (store-redis-notify.ts); this module owns\n * the two connections.\n *\n * A2 creates both clients from the same options: one for commands, one\n * dedicated subscriber. node-redis restores subscriptions before it reports\n * a reconnect ready, so every feed and presence subscription on a channel\n * catches up right after a reconnect instead of waiting for the safety read.\n * A client whose reconnect strategy gives up is replaced on next use.\n *\n * Cluster mode is out: each script's keys share a session's hash tag, but\n * the store runs on one non-cluster connection for commands and one for\n * pub/sub. `redis` (node-redis) is an optional peer dependency.\n */\n\nimport type { RedisClientOptions } from 'redis'\nimport { A2Error } from './errors.ts'\nimport { retryableLazy } from './retryable-lazy.ts'\nimport {\n  createRedisNotifyStore,\n  type RedisConnection,\n} from './store-redis-notify.ts'\nimport {\n  RANDOM_IDS,\n  SYSTEM_CLOCK,\n  type A2Store,\n  type Clock,\n  type IdSource,\n} from './store.ts'\n\n/**\n * node-redis `createClient` options. A2 reads replies in their RESP2\n * shapes, so it always connects with `RESP: 2`, which rules out `RESP`\n * and the options that need RESP3.\n */\nexport type ValkeyClientOptions = Omit<\n  RedisClientOptions,\n  'RESP' | 'clientSideCache' | 'emitInvalidate' | 'maintNotifications'\n>\n\nexport type ValkeyStoreOptions = {\n  /** `redis://` or `rediss://` URL. Overrides `clientOptions.url`. */\n  url?: string | undefined\n  /**\n   * Options for both clients A2 creates: `socket` (TLS, connect timeout,\n   * `reconnectStrategy`), `credentialsProvider`, `commandOptions`,\n   * `disableOfflineQueue`, and so on.\n   */\n  clientOptions?: ValkeyClientOptions\n  /** Key prefix — isolates multiple apps on one server. Default `'a2'`. */\n  keyPrefix?: string\n  /** Injectable clock — every stored timestamp comes from here. */\n  clock?: Clock\n  /** Injectable id source for generated event ids. */\n  ids?: IdSource\n}\n\nexport type ValkeyStore = A2Store & {\n  /** Destroy the command client and the subscriber. */\n  close(): Promise<void>\n}\n\n/** The node-redis client surface this module uses. */\ntype Client = {\n  readonly isOpen: boolean\n  readonly isReady: boolean\n  connect(): Promise<unknown>\n  destroy(): void\n  on(event: 'error' | 'ready', listener: () => void): unknown\n  sendCommand(\n    args: string[],\n    options: { typeMapping: Record<number, unknown> },\n  ): Promise<unknown>\n  subscribe(\n    channel: string,\n    listener: (message: string, channel: string) => void,\n  ): Promise<unknown>\n  unsubscribe(channel: string): Promise<unknown>\n}\n\ntype Driver = {\n  create(): Client\n  bytes: { typeMapping: Record<number, unknown> }\n}\n\n/** Overrides any `commandOptions.typeMapping`: replies decode as strings. */\nconst STRING_REPLIES = { typeMapping: {} }\n\n/**\n * node-redis 6 needs `destroy()` to release a client whose reconnect\n * strategy gave up; node-redis 5 throws there instead.\n */\nconst dispose = (client: Client | null | undefined): void => {\n  try {\n    client?.destroy()\n  } catch {}\n}\n\nconst closedError = (): A2Error =>\n  new A2Error('STORE_UNAVAILABLE', 'the store was closed')\n\n/** node-redis 6's default `commandOptions.timeout`; node-redis 5 has none. */\nconst DEFAULT_TIMEOUT_MS = 5_000\n\ntype OwnedEntry = {\n  client: Client | null\n  created: Promise<Client>\n  /** Settles when the client first reports ready, or its connect fails. */\n  connected: Promise<unknown> | null\n  ready: boolean\n}\n\n/**\n * One A2-owned client at a time. `get` hands a new client out once it\n * first reports ready, waiting at most `timeoutMs` per call while it keeps\n * connecting, so `disableOfflineQueue` cannot reject a cold start's first\n * calls. Later reconnects follow node-redis's offline queue,\n * `disableOfflineQueue`, and command timeouts. A client whose connect\n * failed, or whose reconnect strategy gave up, is closed for good, so the\n * next `get` replaces it.\n */\nconst ownedClient = (options: {\n  driver: () => Promise<Driver>\n  opened: (client: Client) => void\n  timeoutMs: number\n}) => {\n  let current: OwnedEntry | null = null\n  let closed = false\n\n  const firstReady = async (entry: OwnedEntry): Promise<Client> => {\n    const client = await entry.created\n    if (entry.ready) return client\n    let timer: ReturnType<typeof setTimeout> | undefined\n    try {\n      await Promise.race([\n        entry.connected,\n        new Promise<never>((_, reject) => {\n          timer = setTimeout(() => {\n            reject(\n              new A2Error(\n                'STORE_UNAVAILABLE',\n                `connect timed out after ${options.timeoutMs}ms`,\n              ),\n            )\n          }, options.timeoutMs)\n        }),\n      ])\n    } catch (err) {\n      if (err instanceof A2Error) throw err\n      throw new A2Error('STORE_UNAVAILABLE', 'connect failed', { cause: err })\n    } finally {\n      clearTimeout(timer)\n    }\n    return client\n  }\n\n  return {\n    get(): Promise<Client> {\n      if (closed) return Promise.reject(closedError())\n      if (current && (current.client === null || current.client.isOpen))\n        return firstReady(current)\n      dispose(current?.client)\n      const entry: OwnedEntry = {\n        client: null,\n        connected: null,\n        ready: false,\n        created: options.driver().then((driver) => {\n          if (closed) throw closedError()\n          const client = driver.create()\n          entry.client = client\n          // Without a listener, node-redis's 'error' event crashes the\n          // process; failures still surface as command rejections.\n          client.on('error', () => {})\n          entry.connected = client.connect().then(\n            () => {\n              entry.ready = true\n              return undefined\n            },\n            (err: unknown) => {\n              if (current === entry) {\n                dispose(client)\n                current = null\n              }\n              throw err\n            },\n          )\n          void entry.connected.catch(() => {})\n          options.opened(client)\n          return client\n        }),\n      }\n      current = entry\n      void entry.created.catch(() => {\n        if (current === entry) current = null\n      })\n      return firstReady(entry)\n    },\n    close(): void {\n      closed = true\n      dispose(current?.client)\n      current = null\n    },\n  }\n}\n\nexport function valkey(options: ValkeyStoreOptions = {}): ValkeyStore {\n  const clock = options.clock ?? SYSTEM_CLOCK\n  const ids = options.ids ?? RANDOM_IDS\n  const prefix = options.keyPrefix ?? 'a2'\n\n  if (!options.url && !options.clientOptions) {\n    throw new TypeError('valkey() needs a url or clientOptions')\n  }\n  const clientOptions = {\n    ...options.clientOptions,\n    ...(options.url ? { url: options.url } : {}),\n    RESP: 2 as const,\n  }\n\n  // Lazy init — constructing the backend does no I/O.\n  const driver = retryableLazy(async (): Promise<Driver> => {\n    const mod = await import('redis').catch(() => {\n      throw new A2Error(\n        'STORE_NOT_CONFIGURED',\n        \"experimental-a2/store-valkey needs the 'redis' package (optional peer dependency) — install it\",\n      )\n    })\n    return {\n      create: () => mod.createClient(clientOptions) as unknown as Client,\n      bytes: { typeMapping: { [mod.RESP_TYPES.BLOB_STRING]: Buffer } },\n    }\n  })\n\n  const timeoutMs = clientOptions.commandOptions?.timeout ?? DEFAULT_TIMEOUT_MS\n  const commands = ownedClient({\n    driver: driver.get,\n    opened: () => {},\n    timeoutMs,\n  })\n\n  /**\n   * Channels the subscriber holds, restored on a replacement client. Each\n   * maps to the call that subscribed it, so a failed call only forgets its\n   * own subscription.\n   */\n  const channels = new Map<string, symbol>()\n  let deliver: ((channel: string, message: string) => void) | undefined\n  let reconnected: ((channel: string) => void) | undefined\n  const onMessage = (message: string, channel: string): void => {\n    deliver?.(channel, message)\n  }\n  const resubscribed = (): void => {\n    for (const channel of channels.keys()) reconnected?.(channel)\n  }\n  /**\n   * node-redis queues SUBSCRIBE outside `sendCommand`, so neither\n   * `disableOfflineQueue` nor `commandOptions.timeout` applies to it: a\n   * subscribe sent while the subscriber reconnects would wait for the\n   * server indefinitely. Apply both here. A timed-out SUBSCRIBE stays\n   * queued, so an UNSUBSCRIBE queued behind it cancels it.\n   */\n  const subscribeBounded = async (\n    client: Client,\n    channel: string,\n  ): Promise<unknown> => {\n    if (!client.isReady && clientOptions.disableOfflineQueue) {\n      throw new A2Error('STORE_UNAVAILABLE', 'the subscriber is offline')\n    }\n    let timer: ReturnType<typeof setTimeout> | undefined\n    const timedOut = new Promise<never>((_, reject) => {\n      timer = setTimeout(() => {\n        void client.unsubscribe(channel).catch(() => {})\n        reject(\n          new A2Error(\n            'STORE_UNAVAILABLE',\n            `subscribe timed out after ${timeoutMs}ms`,\n          ),\n        )\n      }, timeoutMs)\n    })\n    try {\n      return await Promise.race([\n        client.subscribe(channel, onMessage),\n        timedOut,\n      ])\n    } finally {\n      clearTimeout(timer)\n    }\n  }\n  const subscriber = ownedClient({\n    driver: driver.get,\n    opened: (client) => {\n      // node-redis restores subscriptions before a reconnect's 'ready'.\n      let readies = 0\n      client.on('ready', () => {\n        readies += 1\n        if (readies > 1) resubscribed()\n      })\n      if (channels.size === 0) return\n      void Promise.all(\n        [...channels.keys()].map((channel) =>\n          client.subscribe(channel, onMessage),\n        ),\n      ).then(resubscribed, () => {})\n    },\n    timeoutMs,\n  })\n\n  const subscriberConnection: RedisConnection = {\n    async call(command, ...args) {\n      const channel = String(args[0])\n      const name = command.toLowerCase()\n      if (name === 'subscribe') {\n        const call = Symbol(channel)\n        try {\n          // Restore only held channels while a replacement connects; a new\n          // channel belongs to the bounded subscribe after first readiness.\n          const client = await subscriber.get()\n          channels.set(channel, call)\n          return await subscribeBounded(client, channel)\n        } catch (err) {\n          if (channels.get(channel) === call) channels.delete(channel)\n          throw err\n        }\n      }\n      if (name === 'unsubscribe') {\n        channels.delete(channel)\n        return (await subscriber.get()).unsubscribe(channel)\n      }\n      return (await subscriber.get()).sendCommand(\n        [command, ...args.map(String)],\n        STRING_REPLIES,\n      )\n    },\n    duplicate: () => subscriberConnection,\n    on(_event, listener) {\n      deliver = listener\n    },\n    disconnect: subscriber.close,\n  }\n\n  const commandConnection: RedisConnection = {\n    call: async (command, ...args) =>\n      (await commands.get()).sendCommand(\n        [command, ...args.map(String)],\n        STRING_REPLIES,\n      ),\n    duplicate: () => subscriberConnection,\n    on: () => undefined,\n    disconnect: commands.close,\n  }\n\n  return createRedisNotifyStore({\n    client: () => Promise.resolve(commandConnection),\n    callBytes: async (command, ...args) => {\n      const { bytes } = await driver.get()\n      return (await commands.get()).sendCommand(\n        [command, ...args.map(String)],\n        bytes,\n      )\n    },\n    clock,\n    ids,\n    keyPrefix: prefix,\n    onReconnect: (listener) => {\n      reconnected = listener\n    },\n    async closeClient() {\n      commands.close()\n    },\n  })\n}\n"],"mappings":"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"}

package/docs/client/03-presence.mdx

@@ -207,6 +207,7 @@ store has it, at two tiers:
 | Backend | Delivery |
 | --- | --- |
 | `store-redis` | push: TTL'd hash plus pub/sub patches |
+| `store-valkey` | push: TTL'd hash plus pub/sub patches |
 | `store-redis-http` | push over HTTP subscriptions; adaptive polling when unsupported |
 | `store-memory` | in-process, immediate |
 | `store-postgres` | native notifications with `listenConnectionString`; adaptive polling by default |

package/docs/reference/01-core.mdx

@@ -20,6 +20,7 @@ description: "Every entry point, and the isomorphic `experimental-a2` core: cont
 | [`experimental-a2/store-postgres`](/stores/postgres) | `postgres`: Postgres store backend | `pg` (or inject a client) |
 | [`experimental-a2/store-redis`](/stores/redis) | `redis`: Redis Streams store backend, push-native streaming | `ioredis` (or inject a client) |
 | [`experimental-a2/store-redis-http`](/stores/redis-http) | `redisHttp`: the same Redis store over provider REST APIs (Upstash) | none |
+| [`experimental-a2/store-valkey`](/stores/valkey) | `valkey`: the same Redis store on node-redis connections (Valkey, ElastiCache) | `redis` |
 | [`experimental-a2/store-sqlite`](/stores/sqlite) | SQLite store backend | none |
 | [`experimental-a2/store-memory`](/stores/memory) | in-memory store backend | none |
 | [`experimental-a2/scheduler-vercel`](/schedulers/vercel-queues) | `vercelQueues`: recovery and timers | `@vercel/queue` |

package/docs/stores/01-overview.mdx

@@ -20,6 +20,7 @@ export const ordersServer = createServer({
 | Store | Use it for |
 | --- | --- |
 | [Redis](/stores/redis) | Production (recommended) |
+| [Valkey](/stores/valkey) | Production, on node-redis: rotating credentials, TLS and reconnect control |
 | [Redis over HTTP](/stores/redis-http) | Production, when your provider only offers a REST API |
 | [Postgres](/stores/postgres) | Production |
 | [SQLite](/stores/sqlite) | Development: the default |

package/docs/stores/02-redis.mdx

@@ -23,7 +23,9 @@ npm i ioredis
 
 Works on a single Redis or Valkey instance and on non-cluster providers such as
 Upstash, which is durable by default (use its TCP `rediss://` URL). There's
-nothing to set up: A2 creates its keys as it writes.
+nothing to set up: A2 creates its keys as it writes. For rotating credentials or
+custom TLS and reconnect settings, use the same store on node-redis:
+[Valkey](/stores/valkey).
 
 ## Options
 

package/docs/stores/07-valkey.mdx

@@ -0,0 +1,97 @@
+---
+title: Valkey
+description: The Redis store on node-redis, for Valkey and Redis servers that need TLS settings, rotating credentials, or reconnect control.
+---
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { valkey } from 'experimental-a2/store-valkey'
+import { orders } from '@/contracts'
+
+export const ordersServer = createServer({
+  contract: orders,
+  store: valkey({ url: process.env.VALKEY_URL }),
+  consumers: [
+    /* ... */
+  ],
+})
+```
+
+```package-install
+npm i redis
+```
+
+Stores sessions exactly like [Redis](/stores/redis), on
+[node-redis](https://github.com/redis/node-redis) connections instead of
+`ioredis`. Use it with Valkey or Redis when a URL isn't enough: managed
+servers such as ElastiCache that authenticate with short-lived tokens, custom
+TLS settings, or your own reconnect and timeout policy. It needs a single
+server or a non-cluster replication group: it holds one non-cluster
+connection for commands and one for pub/sub.
+
+## Options
+
+| Option | |
+| --- | --- |
+| `url` | a `redis://` or `rediss://` URL |
+| `clientOptions` | node-redis `createClient` options for both connections, such as `socket`, `credentialsProvider`, `commandOptions`, `disableOfflineQueue` |
+| `keyPrefix` | isolates several apps on one server. Default `'a2'` |
+| `clock`, `ids` | test seams for timestamps and generated event ids |
+
+Pass `url`, `clientOptions`, or both; `url` wins over `clientOptions.url`.
+A2 always connects with `RESP: 2`, so `clientOptions` has no `RESP`, nor the
+options that need RESP3 (`clientSideCache`, `emitInvalidate`,
+`maintNotifications`).
+
+## Rotating credentials
+
+An async credentials provider runs each time a connection authenticates,
+including every reconnect, so each one gets a fresh token:
+
+```ts server/store.ts
+import { valkey } from 'experimental-a2/store-valkey'
+
+export const store = valkey({
+  clientOptions: {
+    socket: { host: 'my-cache.example.com', port: 6379, tls: true },
+    credentialsProvider: {
+      type: 'async-credentials-provider',
+      credentials: async () => {
+        // your token source, such as an ElastiCache IAM auth token:
+        // const password = await createAuthToken()
+        const password = 'token'
+        return { username: 'a2', password }
+      },
+    },
+  },
+})
+```
+
+## Connections
+
+A2 creates two clients from your options: one for commands, on the first
+store call, and one subscriber, on the first live stream or presence
+subscription. Every live stream and presence subscription in the process
+shares that subscriber. `close()` destroys both.
+
+- A new client is used once it first connects: calls wait for it, each for at
+  most `commandOptions.timeout` (five seconds without one), so a cold start
+  works with `disableOfflineQueue`.
+- While a client reconnects, node-redis's own options decide what happens to
+  commands: they wait in its offline queue, bounded by
+  `commandOptions.timeout`, or fail at once with `disableOfflineQueue`. A2
+  applies the same rules to a new live stream's subscription, which node-redis
+  would otherwise queue without a bound.
+- A reconnect follows your `socket.reconnectStrategy`. When the subscriber
+  reconnects, every live stream reads what it missed right away, without
+  waiting for the safety re-read.
+- When a client's reconnect strategy gives up, A2 replaces it: the command
+  client on the next store call, the subscriber on the next new live stream or
+  presence subscription. Until then, live streams still deliver within the
+  ten-second safety re-read.
+- A2 listens for each client's `'error'` events, so a dropped socket never
+  crashes the process. Failures surface as `STORE_UNAVAILABLE` from the call
+  that hit them.
+
+The upgrade rules, key layout, and per-command costs are the same as
+[Redis](/stores/redis).

package/examples/playground/package.json

@@ -39,7 +39,7 @@
     "ai": "^7.0.58",
     "codemirror": "^6.0.2",
     "drizzle-orm": "^0.45.3",
-    "experimental-a2": "0.22.0",
+    "experimental-a2": "0.23.0",
     "geist": "^1.7.2",
     "ioredis": "^5.9.0",
     "libfx": "0.0.12",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-a2",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Syncs your immutable event log, from server to browser: one contract, handlers, derived state, and a live client per session.",
   "license": "MIT",
   "type": "module",
@@ -61,6 +61,7 @@
     "./store-postgres": "./dist/store-postgres.js",
     "./store-redis": "./dist/store-redis.js",
     "./store-redis-http": "./dist/store-redis-http.js",
+    "./store-valkey": "./dist/store-valkey.js",
     "./scheduler-qstash": "./dist/scheduler-qstash.js",
     "./scheduler-vercel": "./dist/scheduler-vercel.js",
     "./cache-indexeddb": "./dist/cache-indexeddb.js",
@@ -77,7 +78,8 @@
     "ioredis": "^5.4.0",
     "libfx": "^0.0.12",
     "pg": "^8.11.0",
-    "react": "^19.0.0"
+    "react": "^19.0.0",
+    "redis": "^5.8.0 || ^6.0.0"
   },
   "peerDependenciesMeta": {
     "@opentelemetry/api": {
@@ -109,6 +111,9 @@
     },
     "react": {
       "optional": true
+    },
+    "redis": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -119,6 +124,7 @@
     "@upstash/qstash": "^2.11.3",
     "ai": "^7.0.58",
     "ioredis": "^5.9.0",
+    "redis": "^6.2.1",
     "@opentelemetry/api": "^1.9.0",
     "@types/pg": "^8.15.0",
     "@types/ws": "^8.18.1",

package/src/ai-fx.ts

@@ -70,6 +70,8 @@ const SNAPSHOT_VERSION = 1
 const CATALOG_TTL_MS = 60 * 60 * 1000
 /** The Gateway model catalog libfx reads for each new kernel. */
 const CATALOG_PATH = '/coding-agent/v1/models'
+/** Times a step rebuilds its kernel for a stopped turn FX failed on replay. */
+const REPLAY_REBUILDS = 3
 
 type StreamPart = { type: string } & Record<string, unknown>
 /** A recorded tool call, with the input the kernel reads from its text. */
@@ -144,7 +146,13 @@ type KernelHooks = {
   tool: (toolName: string, input: unknown) => unknown
 }
 
-type Kernel = { agent: FxAgent; hooks: KernelHooks; waiting: Waiting[] }
+type Kernel = {
+  agent: FxAgent
+  hooks: KernelHooks
+  waiting: Waiting[]
+  /** Whether FX answered the kernel's latest prompt with an error. */
+  failed: boolean
+}
 
 /**
  * A kernel a step left waiting on its tool calls. The session's next step in
@@ -249,8 +257,12 @@ async function runStep(
       await resume(controller, turns.at(-1)!, adopted)
       return
     }
-    for (const plan of turns) {
+    let rebuilds = 0
+    let next = 0
+    while (next < turns.length) {
       if (stopped || step.signal.aborted) return
+      const plan = turns[next]!
+      next += 1
       // The step's abort cancels the turn; the turn outlives it when parked.
       const fxTurn = kernel!.agent.prompt(plan.prompt)
       const state: TurnState = {
@@ -282,6 +294,18 @@ async function runStep(
           throw diverged(
             `a recorded turn ended with ${result.stopReason}, not ${expected}`,
           )
+        if (kernel!.failed) {
+          // libfx's cancel aborts the request FX waits on as it sends the
+          // stop, and FX fails the turn when it reads the abort first. That
+          // kernel holds no interruption where the log has one, so the turns
+          // replay on a new kernel.
+          if (rebuilds === REPLAY_REBUILDS)
+            throw diverged('FX failed a stopped turn instead of cancelling it')
+          rebuilds += 1
+          await kernel!.agent.close().catch(() => {})
+          kernel = await create(read.saved)
+          next = 0
+        }
         continue
       }
       await finishLive(controller, state, drained)
@@ -577,7 +601,8 @@ async function runStep(
   const create = async (
     checkpoint: Uint8Array | undefined,
   ): Promise<Kernel> => {
-    const created = { hooks, waiting: [] as Waiting[] }
+    const created = { hooks, waiting: [] as Waiting[], failed: false }
+    let prompt: unknown
     const agent = await createFxAgent({
       apiKey: credential.token,
       model: kernelModel(step),
@@ -591,6 +616,24 @@ async function runStep(
       })),
       ...(checkpoint === undefined ? {} : { checkpoint }),
       fetch: (input, init) => created.hooks.fetch(input, init),
+      // libfx reports a turn FX failed after its cancel as cancelled; only
+      // the ACP response to the turn's prompt tells the two apart.
+      onEvent: ({ type, message }) => {
+        const rpc = (message ?? {}) as {
+          id?: unknown
+          method?: unknown
+          error?: unknown
+        }
+        if (type === 'acp.send' && rpc.method === 'session/prompt') {
+          prompt = rpc.id
+          created.failed = false
+        } else if (
+          type === 'acp.receive' &&
+          rpc.method === undefined &&
+          rpc.id === prompt
+        )
+          created.failed = rpc.error !== undefined
+      },
     })
     return Object.assign(created, { agent })
   }

package/src/libfx.d.ts

@@ -37,5 +37,7 @@ declare module 'libfx' {
       input: string | URL | Request,
       init?: RequestInit,
     ) => Promise<Response>
+    /** Diagnostics; `acp.send` and `acp.receive` carry each ACP message. */
+    onEvent?: (event: { type: string; message?: unknown }) => void
   }): Promise<FxAgent>
 }

package/src/store-redis-notify.ts

@@ -217,11 +217,17 @@ export function createRedisNotifyStore(options: {
    */
   let subscriberGate: Promise<RedisConnection> | null = null
   const gatedSubscriber = (): Promise<RedisConnection> => {
-    subscriberGate ??= getSubscriber().then(async (conn) => {
+    if (subscriberGate) return subscriberGate
+    const gate = getSubscriber().then(async (conn) => {
       await conn.call('echo', 'ready')
       return conn
     })
-    return subscriberGate
+    subscriberGate = gate
+    // A failed check is retried by the next channel command.
+    void gate.catch(() => {
+      if (subscriberGate === gate) subscriberGate = null
+    })
+    return gate
   }
 
   const acquireChannel = async (channel: string): Promise<void> => {