experimental-a2 0.16.0 → 0.17.0

package/src/redis-http-reply.ts

@@ -0,0 +1,256 @@
+/* oxlint-disable no-await-in-loop -- response bytes and entries must be consumed in order */
+
+type Scan = { depth: number; quoted: boolean; escaped: boolean }
+
+/**
+ * Index just past the array or string `scan` is inside, or -1 when `text`
+ * ends first; `scan` then carries the state into the next chunk. Strings
+ * are skipped with `indexOf`, so the per-character loop only walks
+ * structure. A quote is escaped when an odd run of backslashes precedes
+ * it; a run is counted back only to where the string scan resumed, and
+ * `escaped` carries an odd trailing run across the chunk boundary.
+ */
+function scanValue(text: string, from: number, scan: Scan): number {
+  let at = from
+  while (at < text.length) {
+    if (scan.quoted) {
+      if (scan.escaped) {
+        scan.escaped = false
+        at++
+        continue
+      }
+      const quote = text.indexOf('"', at)
+      const end = quote < 0 ? text.length : quote
+      let run = 0
+      while (end - run - 1 >= at && text.charCodeAt(end - run - 1) === 92) run++
+      if (quote < 0) {
+        scan.escaped = run % 2 === 1
+        return -1
+      }
+      at = quote + 1
+      if (run % 2 === 1) continue
+      scan.quoted = false
+      if (scan.depth === 0) return at
+      continue
+    }
+    const code = text.charCodeAt(at++)
+    if (code === 34) scan.quoted = true
+    else if (code === 91 || code === 123) scan.depth++
+    else if ((code === 93 || code === 125) && --scan.depth === 0) return at
+  }
+  return -1
+}
+
+class JsonReply {
+  private readonly reader: ReadableStreamDefaultReader<Uint8Array>
+  private readonly decoder = new TextDecoder('utf-8', { fatal: true })
+  private readonly signal: AbortSignal
+  private text = ''
+  private position = 0
+  private done = false
+  private readonly abort: () => void
+  private array: 'first' | 'value' | 'entry' | 'separator' | 'closed' = 'first'
+  private scan: Scan = { depth: 0, quoted: false, escaped: false }
+  private fragments: string[] = []
+  private failure: unknown
+
+  constructor(options: {
+    body: ReadableStream<Uint8Array>
+    signal: AbortSignal
+  }) {
+    const { body, signal } = options
+    this.reader = body.getReader()
+    this.signal = signal
+    this.abort = () => {
+      void this.reader.cancel(signal.reason).catch(() => {})
+    }
+    signal.addEventListener('abort', this.abort, { once: true })
+    if (signal.aborted) this.abort()
+  }
+
+  private async available(): Promise<boolean> {
+    while (this.position === this.text.length && !this.done) {
+      this.signal.throwIfAborted()
+      const chunk = await this.reader.read()
+      this.signal.throwIfAborted()
+      this.done = Boolean(chunk.done)
+      this.text = chunk.done
+        ? this.decoder.decode()
+        : this.decoder.decode(chunk.value, { stream: true })
+      this.position = 0
+    }
+    return this.position < this.text.length
+  }
+
+  async peek(): Promise<string | undefined> {
+    while (await this.available()) {
+      while (this.position < this.text.length) {
+        const value = this.text[this.position]!
+        if (value !== ' ' && value !== '\n' && value !== '\r' && value !== '\t')
+          return value
+        this.position++
+      }
+    }
+    return undefined
+  }
+
+  async expect(value: string): Promise<void> {
+    if ((await this.peek()) !== value)
+      throw new Error('Invalid or truncated Redis HTTP reply')
+    this.position++
+  }
+
+  async value(): Promise<unknown> {
+    const first = await this.peek()
+    if (first !== '[' && first !== '"')
+      throw new Error('Invalid Redis HTTP reply value')
+    const scan: Scan = { depth: 0, quoted: false, escaped: false }
+    const fragments: string[] = []
+    while (await this.available()) {
+      const start = this.position
+      const end = scanValue(this.text, start, scan)
+      this.position = end < 0 ? this.text.length : end
+      fragments.push(this.text.slice(start, this.position))
+      if (end >= 0) return JSON.parse(fragments.join('')) as unknown
+    }
+    throw new Error('Truncated Redis HTTP reply value')
+  }
+
+  /**
+   * The next entries of an open array, parsed together: every entry that
+   * completes in the current transport chunk, reading further chunks only
+   * until one has completed. Entries before a malformed one are returned
+   * first; the malformed one fails the next call. `undefined` once the
+   * array has closed.
+   */
+  async entries(): Promise<unknown[] | undefined> {
+    if (this.failure !== undefined) throw this.failure
+    const texts: string[] = []
+    const fail = (message: string): void => {
+      const error = new Error(message)
+      if (texts.length === 0) throw error
+      this.failure = error
+    }
+    while (this.array !== 'closed') {
+      if (this.position === this.text.length) {
+        if (texts.length > 0) break
+        if (!(await this.available()))
+          throw new Error(
+            this.array === 'entry'
+              ? 'Truncated Redis HTTP reply value'
+              : this.array === 'separator'
+                ? 'Invalid or truncated Redis HTTP reply'
+                : 'Invalid Redis HTTP reply value',
+          )
+        continue
+      }
+      if (this.array === 'entry') {
+        const start = this.position
+        const end = scanValue(this.text, start, this.scan)
+        this.position = end < 0 ? this.text.length : end
+        this.fragments.push(this.text.slice(start, this.position))
+        if (end < 0) continue
+        texts.push(
+          this.fragments.length === 1
+            ? this.fragments[0]!
+            : this.fragments.join(''),
+        )
+        this.fragments = []
+        this.array = 'separator'
+        continue
+      }
+      const value = this.text[this.position]!
+      if (value === ' ' || value === '\n' || value === '\r' || value === '\t') {
+        this.position++
+        continue
+      }
+      if (
+        this.array === 'separator' ||
+        (this.array === 'first' && value === ']')
+      ) {
+        if (value === ']') this.array = 'closed'
+        else if (value === ',') this.array = 'value'
+        else {
+          fail('Invalid or truncated Redis HTTP reply')
+          break
+        }
+        this.position++
+        continue
+      }
+      if (value !== '[' && value !== '"') {
+        fail('Invalid Redis HTTP reply value')
+        break
+      }
+      this.scan = { depth: 0, quoted: false, escaped: false }
+      this.array = 'entry'
+    }
+    return texts.length > 0 ? this.parse(texts) : undefined
+  }
+
+  private parse(texts: string[]): unknown[] {
+    try {
+      return JSON.parse(`[${texts.join(',')}]`) as unknown[]
+    } catch {
+      // The joined parse fails only if one entry does: keep those before it.
+      const parsed: unknown[] = []
+      for (const text of texts) {
+        try {
+          parsed.push(JSON.parse(text))
+        } catch (error) {
+          this.failure = error
+          break
+        }
+      }
+      if (parsed.length === 0) throw this.failure
+      return parsed
+    }
+  }
+
+  async end(): Promise<void> {
+    await this.expect('}')
+    if ((await this.peek()) !== undefined)
+      throw new Error('Trailing data in Redis HTTP reply')
+  }
+
+  async close(): Promise<void> {
+    this.signal.removeEventListener('abort', this.abort)
+    try {
+      await this.reader.cancel()
+    } finally {
+      this.reader.releaseLock()
+      this.text = ''
+    }
+  }
+}
+
+/**
+ * The `result` array of an Upstash REST reply, in batches of the entries
+ * that complete in each transport chunk.
+ */
+export async function* redisHttpReply(options: {
+  body: ReadableStream<Uint8Array>
+  signal: AbortSignal
+}): AsyncGenerator<unknown[]> {
+  const reply = new JsonReply(options)
+  try {
+    await reply.expect('{')
+    const key = await reply.value()
+    await reply.expect(':')
+    if (key === 'error') {
+      const error = await reply.value()
+      if (typeof error !== 'string') throw new Error('Invalid Redis HTTP error')
+      await reply.end()
+      throw new Error(`Redis HTTP command failed: ${String(error)}`)
+    }
+    if (key !== 'result') throw new Error('Invalid Redis HTTP reply envelope')
+    await reply.expect('[')
+    for (;;) {
+      const entries = await reply.entries()
+      if (entries === undefined) break
+      yield entries
+    }
+    await reply.end()
+  } finally {
+    await reply.close()
+  }
+}

package/src/redis-http-stream.ts

@@ -0,0 +1,73 @@
+import { A2Error } from './errors.ts'
+import { redisHttpReply } from './redis-http-reply.ts'
+import type { StreamEntry } from './store-redis-core.ts'
+
+export const REDIS_HTTP_STREAM_READ_COUNT = 1000
+
+export async function* readRedisStreamPage({
+  key,
+  from,
+  signal,
+  url,
+  token,
+  count,
+}: {
+  key: string
+  from: string
+  signal: AbortSignal
+  url: string
+  token: string
+  count: number
+}): AsyncGenerator<StreamEntry[], void> {
+  signal.throwIfAborted()
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      authorization: `Bearer ${token}`,
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify(['XRANGE', key, from, '+', 'COUNT', String(count)]),
+    signal,
+  })
+  if (!response.ok || !response.body) {
+    const body = (await response.json().catch(() => null)) as {
+      error?: unknown
+    } | null
+    throw new A2Error(
+      'STORE_UNAVAILABLE',
+      `redis rest command failed: ${
+        typeof body?.error === 'string'
+          ? body.error
+          : `status ${response.status}`
+      }`,
+    )
+  }
+  let last = Number(from.slice(0, -2)) - 1
+  for await (const batch of redisHttpReply({ body: response.body, signal })) {
+    const entries: StreamEntry[] = []
+    try {
+      for (const entry of batch) {
+        if (
+          !Array.isArray(entry) ||
+          entry.length !== 2 ||
+          typeof entry[0] !== 'string' ||
+          !Array.isArray(entry[1]) ||
+          entry[1].length % 2 !== 0 ||
+          !entry[1].every((field) => typeof field === 'string')
+        )
+          throw new Error('Invalid Redis stream entry')
+        const index = /^\d+-0$/.test(entry[0])
+          ? Number(entry[0].slice(0, -2))
+          : NaN
+        if (!Number.isSafeInteger(index) || index <= last)
+          throw new Error('Redis stream entry did not advance')
+        last = index
+        entries.push(entry as StreamEntry)
+      }
+    } catch (error) {
+      if (entries.length > 0) yield entries
+      throw error
+    }
+    yield entries
+  }
+}

package/src/redis-http-subscriptions.ts

@@ -12,7 +12,11 @@ export function redisHttpSubscriptions({
   url: string
   token: string
   onReconnect: (channel: string) => void
-  fallback: { enabled(): boolean; enable(): Promise<void> }
+  fallback: {
+    enabled(): boolean
+    checkCommands(): Promise<void>
+    enable(): void
+  }
 }): RedisConnection {
   const subscriptions = new Map<
     string,
@@ -75,10 +79,14 @@ export function redisHttpSubscriptions({
             // oxlint-disable-next-line no-await-in-loop -- finish capability detection before falling back
             await response.body?.cancel()
             // oxlint-disable-next-line no-await-in-loop -- confirm that ordinary commands work
-            await fallback.enable()
-            for (const active of subscriptions.values()) active.stop()
-            subscriptions.clear()
-            return
+            await fallback.checkCommands()
+            if (stopped) return
+            if (!supported) {
+              fallback.enable()
+              for (const active of subscriptions.values()) active.stop()
+              subscriptions.clear()
+              return
+            }
           }
           if (
             !response.ok ||

package/src/reducer-runtime.ts

@@ -0,0 +1,52 @@
+const runtimeKey: unique symbol = Symbol('a2.reducerRuntime')
+
+type StateStorage<S> = {
+  encode(state: S): unknown
+  decode(stored: unknown): S
+}
+
+type ReducerRuntime<S> = {
+  storage?: StateStorage<S>
+  project?: (state: S) => S
+}
+
+type Carrier = { [runtimeKey]?: ReducerRuntime<unknown> }
+
+export function withReducerRuntime<R extends object, S>(options: {
+  reducer: R
+  storage?: StateStorage<S>
+  project?: (state: S) => S
+}): R {
+  const { reducer, ...runtime } = options
+  return {
+    ...reducer,
+    [runtimeKey]: {
+      ...(reducer as Carrier)[runtimeKey],
+      ...runtime,
+    },
+  }
+}
+
+export function encodeState(options: {
+  reducer: object
+  state: unknown
+}): unknown {
+  const storage = (options.reducer as Carrier)[runtimeKey]?.storage
+  return storage ? storage.encode(options.state) : options.state
+}
+
+export function decodeState(options: {
+  reducer: object
+  state: unknown
+}): unknown {
+  const storage = (options.reducer as Carrier)[runtimeKey]?.storage
+  return storage ? storage.decode(options.state) : options.state
+}
+
+export function projectClientState<S>(options: {
+  reducer: object
+  state: S
+}): S {
+  const project = (options.reducer as Carrier)[runtimeKey]?.project
+  return project ? (project(options.state) as S) : options.state
+}

package/src/reducer.ts

@@ -1,14 +1,62 @@
-import type { ContractEvent, EventDefs, PresenceDefs } from './contract.ts'
+import type {
+  ContractEvent,
+  EventDefs,
+  PresenceDefs,
+  ReducerOptions,
+} from './contract.ts'
+import { isSessionCleared, type SessionCleared } from './session-clear.ts'
 import type { StandardSchemaV1 } from './standard-schema.ts'
 import { validateSync } from './validate.ts'
 
-export const clientStateProjection: unique symbol = Symbol(
-  'a2.clientStateProjection',
-)
+export type StateSnapshot<S> = {
+  state: S
+  index: number
+  /** The session's latest clear marker, once it has been cleared. */
+  clearIndex?: number | undefined
+}
+
+/**
+ * A fresh copy of a reducer's seed, so a fold that mutates in place
+ * cannot corrupt the shared `initialState`. Non-cloneable seeds
+ * (functions, class instances, proxies) fall back to the original.
+ */
+export function cloneInitial<S>(initial: S): S {
+  try {
+    return structuredClone(initial)
+  } catch {
+    return initial
+  }
+}
+
+const markerFolds = new WeakSet<object>()
+
+/**
+ * Mark a fold that receives clear markers itself instead of resetting to its
+ * `initialState`. The actor follower has no seed of its own; its stream carries
+ * the reset state in the marker.
+ */
+export function foldsClearMarkers<
+  F extends (state: never, event: never) => unknown,
+>(fold: F): F {
+  markerFolds.add(fold)
+  return fold
+}
+
+/** One fold step; a clear marker resets to the seed on server and client alike. */
+export function foldEvent<D extends EventDefs, S>(
+  source: Pick<Reducer<D, S>, 'fold' | 'initialState'>,
+  state: S,
+  event: ContractEvent<D> | SessionCleared,
+): S {
+  if (!isSessionCleared(event)) return source.fold(state, event)
+  return markerFolds.has(source.fold)
+    ? source.fold(state, event as unknown as ContractEvent<D>)
+    : cloneInitial(source.initialState)
+}
 
 /**
  * A pure fold over a session's events — `(state, event) => state` —
- * derived from a contract via `contract.reducer(options).fold(fn)`.
+ * published inline in a contract or built with `reducer(options).fold(fn)`.
  *
  * The name is the reducer's identity. Cached folds (server snapshots,
  * the browser cache) are keyed by it, which makes it the invalidation
@@ -20,7 +68,6 @@ export type Reducer<
   D extends EventDefs = EventDefs,
   S = unknown,
   P extends PresenceDefs = Record<never, never>,
-  V = S,
 > = {
   /** Identity and cache key. Rename when the fold's logic changes. */
   readonly name: string
@@ -34,8 +81,6 @@ export type Reducer<
   readonly presence: Readonly<P>
   readonly fold: (state: S, event: ContractEvent<D>) => S
   readonly initialState: S
-  /** Internal read-side projection. Never used as a fold input or persisted. */
-  readonly [clientStateProjection]?: (state: S) => V
   /**
    * When present: `initialState` was validated against it at
    * definition, and any cached fold a2 rehydrates (server snapshots,
@@ -45,7 +90,7 @@ export type Reducer<
   readonly stateSchema: StandardSchemaV1<unknown, S> | undefined
 }
 
-/** The second step of `contract.reducer` — see the method's doc. */
+/** The second step of `reducer` — see the method's doc. */
 export type ReducerBuilder<
   D extends EventDefs,
   S,
@@ -54,7 +99,7 @@ export type ReducerBuilder<
   fold(fold: (state: S, event: ContractEvent<D>) => S): Reducer<D, S, P>
 }
 
-/** Internal — reducers are created through `contract.reducer(...).fold(...)`. */
+/** Internal — shared validation for inline and standalone reducer definitions. */
 export function makeReducerBuilder<
   D extends EventDefs,
   P extends PresenceDefs,
@@ -94,6 +139,19 @@ export function makeReducerBuilder<
       )
     }
     initialState = result.value as S
+    const restored = validateSync(
+      options.stateSchema,
+      initialState,
+      'the stateSchema',
+    )
+    if (
+      restored.issues ||
+      JSON.stringify(restored.value) !== JSON.stringify(initialState)
+    ) {
+      throw new TypeError(
+        'stateSchema must accept and preserve its own output so snapshots can be restored',
+      )
+    }
   }
 
   return {
@@ -113,3 +171,27 @@ export function makeReducerBuilder<
     },
   }
 }
+
+export type RegisteredReducer<
+  D extends EventDefs,
+  P extends PresenceDefs,
+> = Omit<Reducer<D, unknown, P>, 'fold'> & {
+  readonly fold: (state: never, event: never) => unknown
+}
+
+export function reducer<
+  D extends EventDefs,
+  P extends PresenceDefs,
+  Seed,
+  S = Seed,
+>(
+  options: ReducerOptions<Seed, S> & {
+    contract: { events: Readonly<D>; presence: Readonly<P> }
+  },
+): ReducerBuilder<D, S, P> {
+  return makeReducerBuilder(
+    options.contract.events,
+    options.contract.presence,
+    options,
+  )
+}

package/src/scheduler-qstash.ts

@@ -3,7 +3,8 @@
  *
  * QStash publishes one signed HTTP delivery per scheduler task. Drain tasks
  * use an absolute, whole-second `notBefore` and a fixed-size deduplication id;
- * append tasks hash their stable task id with the callback URL.
+ * append and clear tasks hash their stable task id with the callback URL, each
+ * under its own version tag.
  * Store-outage successors carry a signed private generation and back off to
  * one day without deriving their deduplication identity from the local clock.
  * `handler(...servers)` verifies the signature over the raw request body
@@ -28,6 +29,7 @@ import { retryableLazy } from './retryable-lazy.ts'
 import { normalizeSchedulerTask, type SchedulerTask } from './scheduler-task.ts'
 import {
   deliverSchedulerAppend,
+  deliverSchedulerClear,
   type A2Scheduler,
   type DrainableServer,
 } from './server.ts'
@@ -37,7 +39,7 @@ type QStashStoreOutage = {
   version: 1
   /** Zero is the first successor created for a store outage. */
   generation: number
-  /** The first failing drain task's due time. Append identity lives on the task. */
+  /** The first failing drain task's due time. Append and clear identity lives on the task. */
   rootDueAt?: number
 }
 
@@ -658,6 +660,16 @@ export function qstash(options: QStashSchedulerOptions = {}): A2Scheduler {
     task: SchedulerTask,
     outage: QStashStoreOutage,
   ): Promise<string> => {
+    if (task.kind === 'clear') {
+      return digestId([
+        'a2:scheduler-qstash:store-outage:clear:v1',
+        url,
+        task.contract,
+        task.sessionId,
+        task.id,
+        outage.generation,
+      ])
+    }
     if (task.kind === 'append') {
       return digestId([
         'a2:scheduler-qstash:store-outage:append:v1',
@@ -708,14 +720,27 @@ export function qstash(options: QStashSchedulerOptions = {}): A2Scheduler {
             sessionId: task.sessionId,
             dueAt,
             events: task.events,
+            ...(task.originIndex === undefined
+              ? {}
+              : { originIndex: task.originIndex }),
           }
-        : {
-            version: 1,
-            kind: 'drain',
-            contract: task.contract,
-            sessionId: task.sessionId,
-            dueAt,
-          }
+        : task.kind === 'clear'
+          ? {
+              version: 1,
+              kind: 'clear',
+              id: task.id,
+              contract: task.contract,
+              sessionId: task.sessionId,
+              dueAt,
+              ifLastIndex: task.ifLastIndex,
+            }
+          : {
+              version: 1,
+              kind: 'drain',
+              contract: task.contract,
+              sessionId: task.sessionId,
+              dueAt,
+            }
     const message: QStashMessage = {
       ...normalizedTask,
       ...(outage === undefined ? {} : { _a2QStash: outage }),
@@ -725,7 +750,7 @@ export function qstash(options: QStashSchedulerOptions = {}): A2Scheduler {
         ? {
             ...normalizedTask,
             _a2QStash:
-              normalizedTask.kind === 'append'
+              normalizedTask.kind !== 'drain'
                 ? { version: 1, generation: Number.MAX_SAFE_INTEGER }
                 : {
                     version: 1,
@@ -753,13 +778,15 @@ export function qstash(options: QStashSchedulerOptions = {}): A2Scheduler {
         ? await storeOutageDeduplicationId(task, outage)
         : task.kind === 'append'
           ? await digestId(['a2:scheduler-qstash:append:v1', url, task.id])
-          : await digestId([
-              'a2:scheduler-qstash:v1',
-              url,
-              task.contract,
-              task.sessionId,
-              dueAt,
-            ])
+          : task.kind === 'clear'
+            ? await digestId(['a2:scheduler-qstash:clear:v1', url, task.id])
+            : await digestId([
+                'a2:scheduler-qstash:v1',
+                url,
+                task.contract,
+                task.sessionId,
+                dueAt,
+              ])
     const trustedSource =
       inferredVercelPreview === true
         ? previewTrustedSource(Math.max(nowMs, dueAt))
@@ -793,7 +820,7 @@ export function qstash(options: QStashSchedulerOptions = {}): A2Scheduler {
     const nowMs = clock.now().getTime()
     const dueAt = Math.ceil((nowMs + delayMs) / 1_000) * 1_000
     const nextOutage: QStashStoreOutage =
-      task.kind === 'append'
+      task.kind !== 'drain'
         ? { version: 1, generation }
         : { version: 1, generation, rootDueAt: outage?.rootDueAt ?? task.dueAt }
     await sendTask({ ...task, dueAt }, nextOutage)
@@ -855,9 +882,11 @@ export function qstash(options: QStashSchedulerOptions = {}): A2Scheduler {
           )
         }
         const internals = serverInternals.get(server)
-        if (task.kind === 'append') {
+        if (task.kind !== 'drain') {
           try {
-            await deliverSchedulerAppend(server, task)
+            if (task.kind === 'append')
+              await deliverSchedulerAppend(server, task)
+            else await deliverSchedulerClear(server, task)
           } catch (error) {
             if (!storeUnavailable(error)) throw error
             await sendStoreOutageSuccessor(task, outage)