experimental-a2 0.22.0 → 0.24.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

@@ -326,12 +326,22 @@ export interface A2Store {
    * a `cause` at or below the latest clear marker throws
    * `SUPERSEDED_ATTEMPT`, an `originIndex` there throws `SESSION_CLEARED`,
    * and ids whose rows lie below the marker are free to reuse.
+   *
+   * `ifLastIndex` conditions a non-empty batch on the session's head, the
+   * last index including any clear marker: when the head is anything else,
+   * throw `lastIndexMismatchError` carrying the head and write nothing. It is
+   * checked last, after the replay path and both fences, inside the same
+   * atomic operation, never as a read before it. A conditional batch whose
+   * ids conflict (mixed, or not matching their rows) reports that head
+   * instead of `PARTIAL_DUPLICATE_BATCH` when it isn't `ifLastIndex`
+   * (`duplicateBatchError`).
    */
   append(
     sessionId: string,
     events: AppendEvent[],
     options?: {
       originIndex?: number
+      ifLastIndex?: number
       consumers?: readonly StoreConsumer[]
     },
   ): Promise<StoreAppendResult>

package/src/wire.ts

@@ -309,6 +309,7 @@ const ERROR_STATUS: Record<A2ServerErrorCode, number> = {
   PARTIAL_DUPLICATE_BATCH: 400,
   SUPERSEDED_ATTEMPT: 409,
   SESSION_CLEARED: 409,
+  LAST_INDEX_MISMATCH: 409,
   CLAIM_EXPIRED: 409,
   STORE_UNAVAILABLE: 503,
   STORE_NOT_CONFIGURED: 500,

package/dist/initial-snapshot-D3Lve43o.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"initial-snapshot-D3Lve43o.d.ts","names":[],"sources":["../src/errors.ts","../src/initial-snapshot.ts"],"mappings":";;KAAY;KAcA,cACV;cAEW,gBAAgB;WAClB,MAAM;;WAEN;EAET,YACE,MAAM,aACN,iBACA;IAAY;IAAmB;;;;;;;;;;;cA6CtB,0BAA0B;EACrC,YAAY,iBAAiB;IAAY;;;;;KCrE/B,gBAAgB,KACxB,cAAc,wBAGd,QAAQ,cAAc"}