experimental-a2 0.4.0 → 0.5.0

package/src/store-redis-http.ts

@@ -0,0 +1,116 @@
+/**
+ * experimental-a2/store-redis-http — the same Redis Streams store over a
+ * provider REST API (Upstash-shaped: POST one command as a JSON array,
+ * receive `{ result }` or `{ error }`). The storage semantics live in
+ * store-redis-core.ts, shared with experimental-a2/store-redis.
+ *
+ * Fully connectionless: every command is one `fetch`, so it works
+ * where a Redis-protocol connection cannot exist or cannot be spared.
+ * Without a connection there is no push and no pub/sub, so `stream()`
+ * is the shared activity-adaptive poll loop (25ms while events flow,
+ * backing off to a 250ms idle ceiling), and presence is the degraded
+ * tier: `set`/`read` from the shared core, no `subscribe`. No peer
+ * dependencies.
+ */
+
+import { A2Error } from './errors.ts'
+import { pollingStream } from './store-polling.ts'
+import { createRedisStoreCore } from './store-redis-core.ts'
+import {
+  RANDOM_IDS,
+  SYSTEM_CLOCK,
+  type A2Store,
+  type Clock,
+  type IdSource,
+} from './store.ts'
+
+export type RedisHttpStoreOptions = {
+  /** REST endpoint, e.g. `process.env.UPSTASH_REDIS_REST_URL`. */
+  url: string
+  /** Bearer token, e.g. `process.env.UPSTASH_REDIS_REST_TOKEN`. */
+  token: string
+  /** Key prefix — isolates multiple apps on one Redis. 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 RedisHttpStore = A2Store & {
+  /** Nothing to disconnect; present so callers can treat stores uniformly. */
+  close(): Promise<void>
+}
+
+export function redisHttp(options: RedisHttpStoreOptions): RedisHttpStore {
+  if (!options.url || !options.token) {
+    throw new TypeError('redisHttp() needs a url and a token')
+  }
+  const { url, token } = options
+
+  const call = async (
+    command: string,
+    ...args: Array<string | number>
+  ): Promise<unknown> => {
+    let response: Response
+    try {
+      response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          authorization: `Bearer ${token}`,
+          'content-type': 'application/json',
+        },
+        body: JSON.stringify([command, ...args.map(String)]),
+      })
+    } catch (err) {
+      throw new A2Error('STORE_UNAVAILABLE', 'redis rest request failed', {
+        cause: err,
+      })
+    }
+    const body = (await response.json().catch(() => null)) as {
+      result?: unknown
+      error?: string
+    } | null
+    if (body === null || !response.ok || body.error !== undefined) {
+      throw new A2Error(
+        'STORE_UNAVAILABLE',
+        `redis rest command failed: ${body?.error ?? `status ${response.status}`}`,
+      )
+    }
+    return body.result
+  }
+
+  const core = createRedisStoreCore({
+    call,
+    clock: options.clock ?? SYSTEM_CLOCK,
+    ids: options.ids ?? RANDOM_IDS,
+    keyPrefix: options.keyPrefix ?? 'a2',
+  })
+
+  return {
+    append: core.append,
+    read: core.read,
+    claimAvailable: core.claimAvailable,
+    renewClaims: core.renewClaims,
+    completeAttempt: core.completeAttempt,
+    failAttempt: core.failAttempt,
+    readState: core.readState,
+    putSnapshot: core.putSnapshot,
+    presence: {
+      async set(ns, participant, values, meta) {
+        await core.presence.set(ns, participant, values, meta)
+      },
+      read: core.presence.read,
+    },
+    inspect: core.inspect,
+
+    stream(sessionId, opts) {
+      return pollingStream(
+        (afterIndex) => core.readRange(sessionId, afterIndex),
+        opts?.startAfter !== undefined ? { startAfter: opts.startAfter } : {},
+      )
+    },
+
+    async close() {},
+  }
+}

package/src/store-redis.ts

@@ -0,0 +1,458 @@
+/**
+ * experimental-a2/store-redis — the Redis-protocol store backend, on Redis
+ * Streams. The storage semantics live in store-redis-core.ts (shared
+ * with experimental-a2/store-redis-http); this module owns the connection and
+ * the live feed.
+ *
+ * `stream()` is notify-driven: writes to watched sessions fire a
+ * disposable PUBLISH wake-up (feeds hold a TTL'd presence marker the
+ * write script checks, so unwatched sessions cost no wake-up), one
+ * shared subscriber connection per backend serves every local feed,
+ * and each wake triggers an `XRANGE` catch-up read. The notification
+ * only decides when to read, never what — a lost one is healed by a
+ * safety re-read (NOTIFY_TIMINGS), so delivery never depends on
+ * pub/sub. Connections scale with processes (one command client plus
+ * one subscriber), not with concurrent viewers.
+ *
+ * Works with any Redis-protocol server on a single instance or a
+ * non-cluster provider (Upstash — durable by default — Redis, Valkey).
+ * Cluster mode is out: the atomic scripts span keys. `ioredis` is an
+ * optional peer dependency; pass `url`, or inject any client exposing
+ * `call`/`duplicate`/`on`/`disconnect`.
+ */
+
+import type { PresencePatch } from './contract.ts'
+import { A2Error } from './errors.ts'
+import { NOTIFY_TIMINGS } from './internal.ts'
+import { defaultSleep, type Sleeper } from './store-polling.ts'
+import { createRedisStoreCore } from './store-redis-core.ts'
+import { retryableLazy } from './retryable-lazy.ts'
+import {
+  RANDOM_IDS,
+  SYSTEM_CLOCK,
+  type A2Store,
+  type Clock,
+  type Event,
+  type IdSource,
+} from './store.ts'
+
+/**
+ * The minimal client this backend needs — `ioredis` matches it
+ * structurally. `call` issues any command; `duplicate` opens the one
+ * shared subscriber connection; `on` delivers its pub/sub messages.
+ *
+ * The client must restore its subscriptions after a reconnect
+ * (`ioredis` does). One that doesn't stays correct — the safety
+ * re-read delivers everything — but every live feed silently degrades
+ * to safety-read latency from that point on.
+ */
+export type RedisConnection = {
+  call(command: string, ...args: Array<string | number>): Promise<unknown>
+  duplicate(): RedisConnection
+  on(
+    event: 'message',
+    listener: (channel: string, message: string) => void,
+  ): unknown
+  disconnect(): void
+}
+
+export type RedisStoreOptions = {
+  /** Creates an `ioredis` client lazily (optional peer dep `ioredis`). */
+  url?: string | undefined
+  /** Bring your own client — anything `call`/`duplicate`/`on`/`disconnect`. */
+  client?: RedisConnection
+  /** Key prefix — isolates multiple apps on one Redis. 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 RedisStore = A2Store & {
+  /** Disconnect the command client and the shared subscriber. */
+  close(): Promise<void>
+}
+
+/** A published presence patch: the patch fields plus the publishing
+ * instance's tag, so its own loopback delivery is not repeated. */
+type PresenceWireMessage = {
+  src: string
+  participant: string
+  values: Record<string, unknown>
+  seen: number
+  at: number
+}
+
+export function redis(options: RedisStoreOptions = {}): RedisStore {
+  const clock = options.clock ?? SYSTEM_CLOCK
+  const ids = options.ids ?? RANDOM_IDS
+  const prefix = options.keyPrefix ?? 'a2'
+
+  if (!options.client && !options.url) {
+    throw new TypeError('redis() needs a url or an injected client')
+  }
+
+  // Lazy init — constructing the backend does no I/O.
+  const connection = retryableLazy(async () => {
+    if (options.client) return options.client
+    const mod = await import('ioredis').catch(() => {
+      throw new A2Error(
+        'STORE_NOT_CONFIGURED',
+        "experimental-a2/store-redis with a url needs the 'ioredis' package (optional peer dependency) — install it, or inject a client",
+      )
+    })
+    return new mod.default(options.url as string) as RedisConnection
+  })
+  const client = connection.get
+
+  const notifyChannel = (sessionId: string): string =>
+    `${prefix}:${sessionId}:notify`
+  const presenceChannel = (ns: string): string => `${prefix}:${ns}:presence`
+
+  const core = createRedisStoreCore({
+    call: async (command, ...args) => {
+      const c = await client()
+      return c.call(command, ...args)
+    },
+    clock,
+    ids,
+    keyPrefix: prefix,
+    // Fire-and-forget: the wake-up is disposable, so a failed PUBLISH
+    // must never fail the write it follows.
+    notify: (sessionId, count) => {
+      void client()
+        .then((c) => c.call('publish', notifyChannel(sessionId), count))
+        .catch(() => {})
+    },
+  })
+
+  // ── the shared subscriber ──────────────────────────────────────────
+  // One duplicated connection serves every local feed: subscriber mode
+  // monopolizes a connection, so it cannot be the command client.
+
+  let severed = false
+  let subscriber: Promise<RedisConnection> | null = null
+  /** channel → parked-feed wake-ups, armed before each catch-up read. */
+  const wakers = new Map<string, Set<() => void>>()
+  /** channel → refcounted subscription held for each live iterator. */
+  const subscriptions = new Map<
+    string,
+    { refs: number; ready: Promise<unknown> }
+  >()
+  /**
+   * channel → last presence-marker refresh, throttling the SET.
+   * Deliberately real time (`Date.now()`), not the injected clock:
+   * the marker's PX expiry runs on server real time, and the throttle
+   * must tick with the TTL it refreshes or time-traveling tests would
+   * desync the two. Process-local and never stored, so the injected
+   * clock's every-stored-timestamp pledge is untouched.
+   */
+  const watchedRefreshedAt = new Map<string, number>()
+  /**
+   * `:presence` channel → live listeners. Same-instance patches are
+   * delivered here synchronously by `presence.set`, so subscribe/set
+   * ordering never depends on the SUBSCRIBE command settling; the
+   * channel carries only other instances' patches, with own echoes
+   * skipped by `src`.
+   */
+  const presenceListeners = new Map<
+    string,
+    Set<(patch: PresencePatch) => void>
+  >()
+  const instanceId = crypto.randomUUID()
+
+  const deliverRemotePresence = (
+    listeners: Set<(patch: PresencePatch) => void>,
+    message: string,
+  ): void => {
+    let parsed: PresenceWireMessage
+    try {
+      parsed = JSON.parse(message) as PresenceWireMessage
+    } catch {
+      return
+    }
+    if (parsed.src === instanceId) return
+    const patch: PresencePatch = {
+      participant: parsed.participant,
+      values: parsed.values,
+      seen: parsed.seen,
+      at: new Date(parsed.at),
+    }
+    for (const listener of listeners) listener(patch)
+  }
+
+  const getSubscriber = (): Promise<RedisConnection> => {
+    subscriber ??= (async () => {
+      const conn = (await client()).duplicate()
+      conn.on('message', (channel, message) => {
+        // wake() only resolves a promise; removal happens later via
+        // disarm(), so iterating the live set is safe.
+        const set = wakers.get(channel)
+        if (set) {
+          for (const wake of set) wake()
+        }
+        const listeners = presenceListeners.get(channel)
+        if (listeners) deliverRemotePresence(listeners, message)
+      })
+      return conn
+    })()
+    return subscriber
+  }
+
+  /**
+   * The subscriber, gated on connection readiness — for channel
+   * commands only (`close` uses the ungated promise, so it can never
+   * hang on an unreachable server). SUBSCRIBE carries redis's
+   * ok-loading flag, so ioredis writes it mid-handshake, ahead of the
+   * ready check's INFO — which then finds the connection already in
+   * subscriber mode and fails the check (a spurious error event plus
+   * a reconnect). ECHO has no such flag: it resolves only once the
+   * connection is ready, so every channel command chained behind it
+   * lands after the check.
+   */
+  let subscriberGate: Promise<RedisConnection> | null = null
+  const gatedSubscriber = (): Promise<RedisConnection> => {
+    subscriberGate ??= getSubscriber().then(async (conn) => {
+      await conn.call('echo', 'ready')
+      return conn
+    })
+    return subscriberGate
+  }
+
+  const acquireChannel = async (channel: string): Promise<void> => {
+    const existing = subscriptions.get(channel)
+    if (existing) {
+      existing.refs += 1
+      try {
+        await existing.ready
+      } catch (err) {
+        existing.refs -= 1
+        throw err
+      }
+      return
+    }
+    const lease = {
+      refs: 1,
+      // Lowercase on purpose: ioredis keys its subscriber-mode
+      // bookkeeping (and reconnect resubscription) on the exact
+      // command name.
+      ready: gatedSubscriber().then((conn) => conn.call('subscribe', channel)),
+    }
+    subscriptions.set(channel, lease)
+    try {
+      await lease.ready
+    } catch (err) {
+      if (subscriptions.get(channel) === lease) subscriptions.delete(channel)
+      throw err
+    }
+  }
+
+  const releaseChannel = (channel: string): void => {
+    const lease = subscriptions.get(channel)
+    if (!lease) return
+    lease.refs -= 1
+    if (lease.refs > 0) return
+    subscriptions.delete(channel)
+    watchedRefreshedAt.delete(channel)
+    void gatedSubscriber()
+      .then((conn) => conn.call('unsubscribe', channel))
+      .catch(() => {})
+  }
+
+  const armWaker = (
+    channel: string,
+  ): { wakeup: Promise<void>; wake: () => void; disarm: () => void } => {
+    let wake!: () => void
+    const wakeup = new Promise<void>((resolve) => {
+      wake = resolve // assigned synchronously by the executor
+    })
+    let set = wakers.get(channel)
+    if (!set) {
+      set = new Set()
+      wakers.set(channel, set)
+    }
+    set.add(wake)
+    return {
+      wakeup,
+      wake,
+      disarm: () => {
+        set.delete(wake)
+        if (set.size === 0) wakers.delete(channel)
+      },
+    }
+  }
+
+  return {
+    append: core.append,
+    read: core.read,
+    claimAvailable: core.claimAvailable,
+    renewClaims: core.renewClaims,
+    completeAttempt: core.completeAttempt,
+    failAttempt: core.failAttempt,
+    readState: core.readState,
+    putSnapshot: core.putSnapshot,
+    inspect: core.inspect,
+
+    presence: {
+      async set(ns, participant, values, meta) {
+        const patch = await core.presence.set(ns, participant, values, meta)
+        if (!patch) return
+        const channel = presenceChannel(ns)
+        const listeners = presenceListeners.get(channel)
+        if (listeners) {
+          for (const listener of listeners) listener(patch)
+        }
+        // Broadcast for other instances — best-effort like the notify
+        // PUBLISH (a failed one must never fail the applied write),
+        // but awaited so a patch can never reach a subscribe() that
+        // starts after this set resolved.
+        const message = JSON.stringify({
+          src: instanceId,
+          participant: patch.participant,
+          values: patch.values,
+          seen: patch.seen,
+          at: patch.at.getTime(),
+        } satisfies PresenceWireMessage)
+        await client()
+          .then((c) => c.call('publish', channel, message))
+          .catch(() => {})
+      },
+
+      read: core.presence.read,
+
+      subscribe(ns, onPatch) {
+        const channel = presenceChannel(ns)
+        let listeners = presenceListeners.get(channel)
+        if (!listeners) {
+          listeners = new Set()
+          presenceListeners.set(channel, listeners)
+        }
+        listeners.add(onPatch)
+        // Fire-and-forget on the shared refcounted subscription: it
+        // only carries remote patches, so settling late (or failing)
+        // degrades cross-instance latency, never same-process
+        // delivery.
+        void acquireChannel(channel).catch(() => {})
+        let stopped = false
+        return () => {
+          if (stopped) return
+          stopped = true
+          listeners.delete(onPatch)
+          if (listeners.size === 0) presenceListeners.delete(channel)
+          releaseChannel(channel)
+        }
+      },
+    },
+
+    stream(sessionId, opts) {
+      const startAfter = opts?.startAfter ?? 0
+      const channel = notifyChannel(sessionId)
+
+      return {
+        [Symbol.asyncIterator](): AsyncIterator<Event> {
+          let last = startAfter
+          let buffer: Event[] = []
+          let closed = false
+          let subscribed = false
+          let pending: Sleeper | null = null
+          let interrupt: (() => void) | null = null
+
+          const release = (): void => {
+            if (!subscribed) return
+            subscribed = false
+            releaseChannel(channel)
+          }
+
+          return {
+            async next(): Promise<IteratorResult<Event>> {
+              for (;;) {
+                if (closed) {
+                  release()
+                  return { value: undefined, done: true }
+                }
+                const row = buffer.shift()
+                if (row) {
+                  last = row.index
+                  return { value: row, done: false }
+                }
+                if (severed) {
+                  release()
+                  throw new A2Error('STORE_UNAVAILABLE', 'the store was closed')
+                }
+                const waker = armWaker(channel)
+                interrupt = waker.wake
+                try {
+                  if (!subscribed) {
+                    // Subscribe before reading: anything appended
+                    // after the read lands as a wake-up, so nothing
+                    // can slip between catch-up and park.
+                    // oxlint-disable-next-line no-await-in-loop -- one-time setup
+                    await acquireChannel(channel)
+                    subscribed = true
+                  }
+                  // Mark watched before reading, for the same reason:
+                  // a write after this read sees the marker and
+                  // publishes. Throttled — one SET per safety period
+                  // per session per process, shared across feeds.
+                  const markedAt = watchedRefreshedAt.get(channel) ?? 0
+                  if (Date.now() - markedAt >= NOTIFY_TIMINGS.safetyReadMs) {
+                    watchedRefreshedAt.set(channel, Date.now())
+                    // oxlint-disable-next-line no-await-in-loop -- live-feed loop
+                    await core.markWatched(
+                      sessionId,
+                      NOTIFY_TIMINGS.safetyReadMs * 3,
+                    )
+                  }
+                  // oxlint-disable-next-line no-await-in-loop -- live-feed loop
+                  buffer = await core.readEvents(sessionId, last)
+                  if (buffer.length === 0 && !closed && !severed) {
+                    pending = defaultSleep(NOTIFY_TIMINGS.safetyReadMs)
+                    // oxlint-disable-next-line no-await-in-loop -- live-feed loop
+                    await Promise.race([waker.wakeup, pending.promise])
+                    pending.cancel()
+                    pending = null
+                  }
+                } catch (err) {
+                  release()
+                  if (closed) return { value: undefined, done: true }
+                  if (err instanceof A2Error) throw err
+                  throw new A2Error(
+                    'STORE_UNAVAILABLE',
+                    'redis store operation failed',
+                    { cause: err },
+                  )
+                } finally {
+                  waker.disarm()
+                  interrupt = null
+                }
+              }
+            },
+            async return(): Promise<IteratorResult<Event>> {
+              closed = true
+              pending?.cancel()
+              interrupt?.() // wakes an in-flight next() immediately
+              release()
+              return { value: undefined, done: true }
+            },
+          }
+        },
+      }
+    },
+
+    async close() {
+      severed = true
+      for (const set of wakers.values()) {
+        for (const wake of set) wake()
+      }
+      if (subscriber) {
+        const sub = await subscriber.catch(() => null)
+        sub?.disconnect()
+      }
+      const current = connection.peek()
+      if (!current) return
+      const c = await current.catch(() => null)
+      c?.disconnect()
+    },
+  }
+}