experimental-a2 0.21.1 → 0.23.0

package/src/store-valkey.ts

@@ -0,0 +1,376 @@
+/**
+ * experimental-a2/store-valkey — the Redis store on node-redis connections,
+ * for Valkey and Redis servers that need more than a URL: TLS settings,
+ * rotating credentials (such as ElastiCache IAM tokens), reconnect
+ * strategies, and timeouts. Storage and the live feed are the ones
+ * experimental-a2/store-redis uses (store-redis-notify.ts); this module owns
+ * the two connections.
+ *
+ * A2 creates both clients from the same options: one for commands, one
+ * dedicated subscriber. node-redis restores subscriptions before it reports
+ * a reconnect ready, so every feed and presence subscription on a channel
+ * catches up right after a reconnect instead of waiting for the safety read.
+ * A client whose reconnect strategy gives up is replaced on next use.
+ *
+ * Cluster mode is out: each script's keys share a session's hash tag, but
+ * the store runs on one non-cluster connection for commands and one for
+ * pub/sub. `redis` (node-redis) is an optional peer dependency.
+ */
+
+import type { RedisClientOptions } from 'redis'
+import { A2Error } from './errors.ts'
+import { retryableLazy } from './retryable-lazy.ts'
+import {
+  createRedisNotifyStore,
+  type RedisConnection,
+} from './store-redis-notify.ts'
+import {
+  RANDOM_IDS,
+  SYSTEM_CLOCK,
+  type A2Store,
+  type Clock,
+  type IdSource,
+} from './store.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.
+ */
+export type ValkeyClientOptions = Omit<
+  RedisClientOptions,
+  'RESP' | 'clientSideCache' | 'emitInvalidate' | 'maintNotifications'
+>
+
+export 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
+}
+
+export type ValkeyStore = A2Store & {
+  /** Destroy the command client and the subscriber. */
+  close(): Promise<void>
+}
+
+/** The node-redis client surface this module uses. */
+type Client = {
+  readonly isOpen: boolean
+  readonly isReady: boolean
+  connect(): Promise<unknown>
+  destroy(): void
+  on(event: 'error' | 'ready', listener: () => void): unknown
+  sendCommand(
+    args: string[],
+    options: { typeMapping: Record<number, unknown> },
+  ): Promise<unknown>
+  subscribe(
+    channel: string,
+    listener: (message: string, channel: string) => void,
+  ): Promise<unknown>
+  unsubscribe(channel: string): Promise<unknown>
+}
+
+type Driver = {
+  create(): Client
+  bytes: { typeMapping: Record<number, unknown> }
+}
+
+/** 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: Client | null | undefined): void => {
+  try {
+    client?.destroy()
+  } catch {}
+}
+
+const closedError = (): A2Error =>
+  new A2Error('STORE_UNAVAILABLE', 'the store was closed')
+
+/** node-redis 6's default `commandOptions.timeout`; node-redis 5 has none. */
+const DEFAULT_TIMEOUT_MS = 5_000
+
+type OwnedEntry = {
+  client: Client | null
+  created: Promise<Client>
+  /** Settles when the client first reports ready, or its connect fails. */
+  connected: Promise<unknown> | null
+  ready: boolean
+}
+
+/**
+ * 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: {
+  driver: () => Promise<Driver>
+  opened: (client: Client) => void
+  timeoutMs: number
+}) => {
+  let current: OwnedEntry | null = null
+  let closed = false
+
+  const firstReady = async (entry: OwnedEntry): Promise<Client> => {
+    const client = await entry.created
+    if (entry.ready) return client
+    let timer: ReturnType<typeof setTimeout> | undefined
+    try {
+      await Promise.race([
+        entry.connected,
+        new Promise<never>((_, 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(): Promise<Client> {
+      if (closed) return Promise.reject(closedError())
+      if (current && (current.client === null || current.client.isOpen))
+        return firstReady(current)
+      dispose(current?.client)
+      const entry: OwnedEntry = {
+        client: null,
+        connected: null,
+        ready: false,
+        created: options.driver().then((driver) => {
+          if (closed) throw closedError()
+          const client = driver.create()
+          entry.client = client
+          // Without a listener, node-redis's 'error' event crashes the
+          // process; failures still surface as command rejections.
+          client.on('error', () => {})
+          entry.connected = client.connect().then(
+            () => {
+              entry.ready = true
+              return undefined
+            },
+            (err: unknown) => {
+              if (current === entry) {
+                dispose(client)
+                current = null
+              }
+              throw err
+            },
+          )
+          void entry.connected.catch(() => {})
+          options.opened(client)
+          return client
+        }),
+      }
+      current = entry
+      void entry.created.catch(() => {
+        if (current === entry) current = null
+      })
+      return firstReady(entry)
+    },
+    close(): void {
+      closed = true
+      dispose(current?.client)
+      current = null
+    },
+  }
+}
+
+export function valkey(options: ValkeyStoreOptions = {}): ValkeyStore {
+  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 as const,
+  }
+
+  // Lazy init — constructing the backend does no I/O.
+  const driver = retryableLazy(async (): Promise<Driver> => {
+    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) as unknown as Client,
+      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 = new Map<string, symbol>()
+  let deliver: ((channel: string, message: string) => void) | undefined
+  let reconnected: ((channel: string) => void) | undefined
+  const onMessage = (message: string, channel: string): void => {
+    deliver?.(channel, message)
+  }
+  const resubscribed = (): void => {
+    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: Client,
+    channel: string,
+  ): Promise<unknown> => {
+    if (!client.isReady && clientOptions.disableOfflineQueue) {
+      throw new A2Error('STORE_UNAVAILABLE', 'the subscriber is offline')
+    }
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const timedOut = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => {
+        void 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) => {
+      // node-redis restores subscriptions before a reconnect's 'ready'.
+      let readies = 0
+      client.on('ready', () => {
+        readies += 1
+        if (readies > 1) resubscribed()
+      })
+      if (channels.size === 0) return
+      void Promise.all(
+        [...channels.keys()].map((channel) =>
+          client.subscribe(channel, onMessage),
+        ),
+      ).then(resubscribed, () => {})
+    },
+    timeoutMs,
+  })
+
+  const subscriberConnection: RedisConnection = {
+    async call(command, ...args) {
+      const channel = String(args[0])
+      const name = command.toLowerCase()
+      if (name === 'subscribe') {
+        const call = Symbol(channel)
+        try {
+          // Restore only held channels while a replacement connects; a new
+          // channel belongs to the bounded subscribe after first readiness.
+          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: RedisConnection = {
+    call: async (command, ...args) =>
+      (await commands.get()).sendCommand(
+        [command, ...args.map(String)],
+        STRING_REPLIES,
+      ),
+    duplicate: () => subscriberConnection,
+    on: () => undefined,
+    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()
+    },
+  })
+}

package/src/store.ts

@@ -300,6 +300,8 @@ export interface A2Store {
    * lost — return the existing rows as success. If only *some* ids
    * exist, the caller mixed an already-sent batch with fresh events —
    * always a caller bug — so throw `A2Error('PARTIAL_DUPLICATE_BATCH')`.
+   * Ids are unique per session: the same id in another session names a
+   * different event and plays no part in these checks.
    *
    * In the same atomic operation, each event's `targets` start cursor work:
    * a lane target queues the event in that consumer's lane, a null lane
@@ -538,11 +540,15 @@ export interface A2Store {
   presence?: {
     /**
      * Field-wise last-writer-wins merge of one participant's values:
-     * a field whose existing row has a strictly newer `at` (the
-     * sender's stamp) is left untouched; `null` deletes the row. Every
-     * applied write refreshes that field's expiry to the storage's own
+     * a field whose unexpired entry has a strictly newer `at` (the
+     * sender's stamp) is left untouched. `null` deletes the value but
+     * keeps a tombstone with its `at`, which takes part in the merge
+     * like a value until it expires, so a set older than the delete
+     * still loses when it arrives later. Every applied write, value or
+     * tombstone, refreshes that field's expiry to the storage's own
      * clock plus `ttlMs` — the sender stamp orders writes but never
-     * anchors their lifetime.
+     * anchors their lifetime. `subscribe` delivers applied writes only,
+     * a delete as `null`.
      */
     set(
       ns: string,
@@ -551,7 +557,10 @@ export interface A2Store {
       meta: { seen: number; at: Date; ttlMs: number },
     ): Promise<void>
 
-    /** The current map, pruned of rows at or past their `expiresAt`. */
+    /**
+     * The current map, pruned of rows at or past their `expiresAt`.
+     * Tombstones never appear.
+     */
     read(ns: string): Promise<PresenceRow[]>
 
     /**

package/dist/actor-HnGmrOZZ.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"actor-HnGmrOZZ.d.ts","names":[],"sources":["../src/actor-shared.ts","../src/actor.ts"],"mappings":";;;;;;;;;;;cAiCa,0BAA0B;;WAE5B;;WAEA;EACT,YAAY,eAAe,mBAAmB;;;;;;;;;KAepC;EACV;EACA;;;;;;;EAOA;;;KAIU,gBAAgB,UAAU,iBAAiB;EACrD,gBAAgB;IAEd;;KAIQ,oBAAoB,QAC7B,WAAW,cAAc,EAAE;;;;;;KAQlB,iBAAiB;GAExB,yBAAA,WAAW;IAAgB,OAAO,EAAE;IAAI;IAAc,IAAI;;;;;;;;;;;;KAanD,UAAU,iBACV,WAAW,eAAe,EAAE,MACjC,QAAQ,EAAE,eACV,OAAO,EAAE;;;;;;;;;KAWJ,uBAAuB;EAAmB;;;;;;;;;;;;KAY1C,kBAAkB,iBAClB,WAAW,eAAe,EAAE,MACjC,OAAO,EAAE,gBAAgB,SAAS,yBAAyB,iBAC3D,OAAO,EAAE,IAAI,SAAS,yBAAyB;;KAI1C,aAAa,UAAU;;EAEjC,OAAO;;EAEP;;EAEA;;EAEA,QAAQ;;EAER,MAAM,UAAU;;EAEhB,UAAU,kBAAkB;;;;;;;;KASlB,uBAAuB,UAAU;;EAE3C;;EAEA;;EAEA,QAAQ;;EAER,SAAS;IAAU,OAAO;IAAY;;;EAEtC,MAAM,UAAU;;EAEhB,UAAU,kBAAkB;;KAGlB,kBAAkB;EAC5B,OAAO;;EAEP;;EAEA;;EAEA;;;KAWU,qBAAqB;EAC/B,kBAAkB,iBAAiB,kBAAkB;;;;;;;;;;;;;;KClE3C,aAAa,UAAU,eAAe,gBAAgB,iBAC5D,KAAK,aAAa,IAAI,OAAO,YAAY,cAAc;EAEvD;EACA,SACE,KAAK,uBAAuB,IAC5B,OAAO,YAAY,cACT;;;;;;;;;;;;;;;;iBAiBF,WAAW,KAAK,GAC9B,SAAS,KAAK,KAAK,OAAO,aAAa;EACpC;EAAkB,SAAS,KAAK,KAAK,OAAO,aAAa;;KAIlD,aAAa,UAAU;;EAEjC;;EAEA,OAAO;;;;;EAKP,aAAa,WAAW,cAAc,aAAa,GAAG;EACtD,QAAQ;EACR,YAAY;EACZ,YAAY;MACR,gBAAgB;EAChB;;;;;;;;;;;;EAYA;;;;;;;KAQM;WACG;WAAwB;;WAExB;WACA;WACA;;WAGA;WACA;WACA;WACA;WACA;;WAGA;WACA;WACA;WACA,QAAQ,SAAS;;KAGpB,kBAAkB,UAAU;;EAEtC,aAAa,WAAW,6BAA6B;;;;;;;;;;;;EAYrD,QAAQ,OAAO;;KAGL;;EAEV;;KAGU,mBAAmB;;EAE7B;;KAGU,gBAAgB;;EAE1B,OAAO;;EAEP;;;;;EAKA;;KAGG,WACH,UAAU,eACV,gBAAgB,0BACH,YAAY,MAErB,QAAQ,YAAY,IACpB,UAAU,qBACP,QAAQ,gBAAgB,gBAE3B,OAAO,YAAY,IACnB,UAAU,qBACP,QAAQ,gBAAgB;KAE5B,WACH,UAAU,eACV,gBAAgB,0BACH,YAAY,MAErB,QAAQ,YAAY,IACpB,UAAU,qBACP;EAAU;EAAY;MAEzB,OAAO,YAAY,IACnB,UAAU,qBACP;EAAU;EAAY;;;KAGnB,YAAY,UAAU;WACvB;;;;;;;;WAQA,kBAAkB,WAAW,cAAc,WAAW,GAAG;;WAEzD,kBAAkB,WAAW,cAAc,WAAW,GAAG;;WAEzD,aAAa,QAAQ,gBAAgB;;;;;;;;;;;WAWrC,QACP,SAAS,SACT,UAAU,kBAAkB,OACzB,QAAQ;;WAEJ,SAAS,QAAQ;;KAGhB,gBAAgB,UAAU;WAC3B;;;;;;WAMA,WAAW;;WAEX,UAAU,SAAS;;WAEnB,QAAQ,SAAS;;WAEjB,SAAS,QAAQ,qBAAqB,aAAa;EAC5D,MAAM,aAAa,YAAY;;;;;;;iBAsDjB,MAAM,UAAU,eAC9B,SAAS,aAAa,KACrB,gBAAgB"}