experimental-a2 0.16.1 → 0.18.0

package/src/session-clear.ts

@@ -0,0 +1,23 @@
+import { A2Error } from './errors.ts'
+import type { Event } from './store.ts'
+
+/** A2's own event types start with this; application contracts cannot. */
+export const RESERVED_EVENT_PREFIX = 'a2.'
+
+/** Reserved type of the marker a clear appends. */
+export const CLEAR_EVENT_TYPE = 'a2.cleared'
+
+/** The marker `session.stream()` yields where a clear ended a lifetime. */
+export type SessionCleared = Event & {
+  type: typeof CLEAR_EVENT_TYPE
+  payload: null
+}
+
+/** Accepts any stream item, including presence patches and snapshots. */
+export function isSessionCleared(item: object): item is SessionCleared {
+  return (item as { type?: unknown }).type === CLEAR_EVENT_TYPE
+}
+
+export function sessionClearedError(message: string): A2Error {
+  return new A2Error('SESSION_CLEARED', message)
+}

package/src/session-socket.ts

@@ -15,10 +15,18 @@ import type { ParsedPushEvent, ParsedPushPresence } from './push-envelope.ts'
 import type { Session } from './server.ts'
 import { parsePresenceSibling, parsePushEvents } from './push-envelope.ts'
 import {
+  type StateSnapshotFrame,
+  type SocketSubscribeEntry,
+  type SubscriptionStart,
+  type WireVersion,
   SOCKET_PING_FRAME,
   asA2Error,
+  compactEventJson,
+  heldEventBatch,
+  isStreamEvent,
   socketAckFor,
   socketErrorAckFor,
+  socketEventsFor,
   socketFrameFor,
   socketSubscribedFor,
   socketUnsubscribedFor,
@@ -78,7 +86,9 @@ export type SocketSession = {
   stream(opts: {
     startAfter: number
     presence?: boolean
-  }): AsyncIterable<Event | PresencePatch | PresenceSnapshot>
+  }): AsyncIterable<
+    Event | PresencePatch | PresenceSnapshot | StateSnapshotFrame
+  >
   append(...events: ParsedPushEvent[]): Promise<Event[]>
   setPresence?(patch: ParsedPushPresence): Promise<void>
 }
@@ -238,8 +248,12 @@ export type SessionsSocketResolve<D extends EventDefs> = (
   sessionId: string,
   /** The entry's resume frontier — `stream({ startAfter })`. */
   startAfter: number,
+  selection?: SubscriptionStart,
 ) =>
-  Pick<Session<D>, 'stream'> | null | Promise<Pick<Session<D>, 'stream'> | null>
+  | Pick<Session<D>, 'stream'>
+  | Pick<SocketSession, 'stream'>
+  | null
+  | Promise<Pick<Session<D>, 'stream'> | Pick<SocketSession, 'stream'> | null>
 
 export type SessionsSocketOptions = {
   /** The `stream()` presence opt-in for every session on the socket —
@@ -248,6 +262,8 @@ export type SessionsSocketOptions = {
   /** Epoch ms: close cleanly (code 1000) at this time, ahead of a known
    * platform deadline, so clients reconnect on our schedule. */
   deadline?: number
+  /** `2` sends live events as `events` batches (the client's `wire=2`). */
+  wire?: WireVersion
   /** Runs after frame parsing and before append or presence I/O. */
   gatePush?(
     sessionId: string,
@@ -262,32 +278,48 @@ export type SessionSocketOptions = SessionsSocketOptions & {
 
 type SocketSubscription = {
   target: SocketSession
-  iterator: AsyncIterator<Event | PresencePatch | PresenceSnapshot>
+  iterator: AsyncIterator<
+    Event | PresencePatch | PresenceSnapshot | StateSnapshotFrame
+  >
   stopped: boolean
+  attempt?: number
 }
 
-const socketSubscription = (
-  target: SocketSession,
-  startAfter: number,
-  presence: boolean,
-): SocketSubscription => ({
-  target,
-  iterator: (presence
-    ? target.stream({ startAfter, presence: true })
-    : target.stream({ startAfter }))[Symbol.asyncIterator](),
-  stopped: false,
-})
+const socketSubscription = (options: {
+  target: SocketSession
+  startAfter: number
+  presence: boolean
+  attempt?: number | undefined
+}): SocketSubscription => {
+  const { target, startAfter, presence, attempt } = options
+  return {
+    target,
+    iterator: (presence
+      ? target.stream({ startAfter, presence: true })
+      : target.stream({ startAfter }))[Symbol.asyncIterator](),
+    stopped: false,
+    ...(attempt === undefined ? {} : { attempt }),
+  }
+}
 
 const stopSubscription = (subscription: SocketSubscription): void => {
   subscription.stopped = true
   void subscription.iterator.return?.()?.catch(() => {})
 }
 
-const pumpSubscription = async (
-  shell: SocketShell,
-  subscription: SocketSubscription,
-  frameFor: (item: Event | PresencePatch | PresenceSnapshot) => string,
-): Promise<void> => {
+/**
+ * Sends a subscription's items until it ends. With `batch`, an event and
+ * the events its iterator already holds go out as one frame.
+ */
+const pumpSubscription = async (options: {
+  shell: SocketShell
+  subscription: SocketSubscription
+  frameFor: (
+    item: Event | PresencePatch | PresenceSnapshot | StateSnapshotFrame,
+  ) => string
+  batch?: (events: string[]) => string
+}): Promise<void> => {
+  const { shell, subscription, frameFor, batch } = options
   for (;;) {
     while (
       !shell.torn() &&
@@ -301,7 +333,16 @@ const pumpSubscription = async (
     // oxlint-disable-next-line no-await-in-loop -- stream pump
     const { value, done } = await subscription.iterator.next()
     if (shell.torn() || subscription.stopped || done) return
-    shell.send(frameFor(value))
+    if (!batch || !isStreamEvent(value)) {
+      shell.send(frameFor(value))
+      continue
+    }
+    const { events } = heldEventBatch({
+      first: value,
+      iterator: subscription.iterator,
+      encode: compactEventJson,
+    })
+    shell.send(batch(events))
   }
 }
 
@@ -370,16 +411,16 @@ const applySocketPresence = async (
 
 export function sessionSocket<D extends EventDefs>(
   sessionId: string,
-  session: Pick<Session<D>, 'stream'>,
+  session: Pick<Session<D>, 'stream'> | Pick<SocketSession, 'stream'>,
   socket: A2Socket,
   options?: SessionSocketOptions,
 ): void {
   const target = session as unknown as SocketSession
-  const subscription = socketSubscription(
+  const subscription = socketSubscription({
     target,
-    options?.startAfter ?? 0,
-    options?.presence === true,
-  )
+    startAfter: options?.startAfter ?? 0,
+    presence: options?.presence === true,
+  })
 
   const handleFrame = (frame: Record<string, unknown>): void => {
     switch (frame['kind']) {
@@ -458,7 +499,14 @@ export function sessionSocket<D extends EventDefs>(
     options?.deadline,
   )
 
-  void pumpSubscription(shell, subscription, socketFrameFor).then(
+  void pumpSubscription({
+    shell,
+    subscription,
+    frameFor: socketFrameFor,
+    ...(options?.wire === 2
+      ? { batch: (events) => socketEventsFor(events) }
+      : {}),
+  }).then(
     () => shell.shutdown(1000),
     () => shell.shutdown(1011, 'stream failed'),
   )
@@ -466,17 +514,46 @@ export function sessionSocket<D extends EventDefs>(
 
 const parseSubscribeEntries = (
   value: unknown,
-): Array<{ id: string; index: number }> | null => {
+): SocketSubscribeEntry[] | null => {
   if (!Array.isArray(value) || value.length === 0) return null
-  const entries: Array<{ id: string; index: number }> = []
+  const entries: SocketSubscribeEntry[] = []
   for (const entry of value) {
     if (entry === null || typeof entry !== 'object') return null
-    const { id, index } = entry as Record<string, unknown>
+    const { id, attempt, index, bootstrap, reducer } = entry as Record<
+      string,
+      unknown
+    >
     if (typeof id !== 'string' || id.length === 0) return null
-    if (typeof index !== 'number' || !Number.isInteger(index) || index < 0) {
+    if (
+      attempt !== undefined &&
+      (typeof attempt !== 'number' ||
+        !Number.isSafeInteger(attempt) ||
+        attempt < 0)
+    )
       return null
+    if (
+      reducer !== undefined &&
+      (typeof reducer !== 'string' || reducer.length === 0)
+    )
+      return null
+    const lane = { id, ...(attempt === undefined ? {} : { attempt }) }
+    if (bootstrap === true) {
+      if (index !== undefined || typeof reducer !== 'string') return null
+      entries.push({ ...lane, bootstrap: true, reducer })
+    } else {
+      if (
+        bootstrap !== undefined ||
+        typeof index !== 'number' ||
+        !Number.isSafeInteger(index) ||
+        index < 0
+      )
+        return null
+      entries.push({
+        ...lane,
+        index,
+        ...(reducer === undefined ? {} : { reducer: reducer as string }),
+      })
     }
-    entries.push({ id, index })
   }
   return entries
 }
@@ -509,53 +586,81 @@ export function sessionsSocket<D extends EventDefs>(
     id: string,
     subscription: SocketSubscription,
   ): Promise<void> => {
+    const { attempt } = subscription
     try {
-      await pumpSubscription(shell, subscription, (item) =>
-        socketFrameFor(item, id),
-      )
+      await pumpSubscription({
+        shell,
+        subscription,
+        frameFor: (item) => socketFrameFor(item, id),
+        ...(options?.wire === 2
+          ? { batch: (events) => socketEventsFor(events, id) }
+          : {}),
+      })
       if (shell.torn() || subscription.stopped) return
       retire(id, subscription)
-      shell.send(socketUnsubscribedFor(id))
+      shell.send(socketUnsubscribedFor({ sessionId: id, attempt }))
     } catch (error) {
       if (shell.torn() || subscription.stopped) return
       retire(id, subscription)
-      shell.send(socketUnsubscribedFor(id, 'stream failed', asA2Error(error)))
+      shell.send(
+        socketUnsubscribedFor({
+          sessionId: id,
+          attempt,
+          reason: 'stream failed',
+          error: asA2Error(error),
+        }),
+      )
     }
   }
 
   const startSubscription = async (
-    id: string,
-    index: number,
+    entry: SocketSubscribeEntry,
   ): Promise<void> => {
+    const { id, attempt } = entry
+    const index = entry.index ?? 0
     const existing = subscriptions.get(id)
     if (existing) {
       stopSubscription(existing)
       subscriptions.delete(id)
     }
-    let session: Pick<Session<D>, 'stream'> | null
+    let session:
+      Pick<Session<D>, 'stream'> | Pick<SocketSession, 'stream'> | null
     try {
-      session = await resolve(id, index)
+      session = await resolve(id, index, entry)
     } catch (error) {
       if (!shell.torn()) {
-        shell.send(socketUnsubscribedFor(id, 'stream failed', asA2Error(error)))
+        shell.send(
+          socketUnsubscribedFor({
+            sessionId: id,
+            attempt,
+            reason: 'stream failed',
+            error: asA2Error(error),
+          }),
+        )
       }
       return
     }
     if (shell.torn()) return
     if (session === null) {
       shell.send(
-        socketUnsubscribedFor(
-          id,
-          'subscribe rejected',
-          new A2Error('FORBIDDEN', 'the subscription is not authorized'),
-        ),
+        socketUnsubscribedFor({
+          sessionId: id,
+          attempt,
+          reason: 'subscribe rejected',
+          error: new A2Error('FORBIDDEN', 'the subscription is not authorized'),
+        }),
       )
       return
     }
     const target = session as unknown as SocketSession
-    const subscription = socketSubscription(target, index, presence)
+    const subscription = socketSubscription({
+      target,
+      startAfter: index,
+      presence,
+      attempt,
+    })
     subscriptions.set(id, subscription)
-    shell.send(socketSubscribedFor(id))
+    shell.send(socketSubscribedFor({ sessionId: id, attempt }))
     void runSubscription(id, subscription)
   }
 
@@ -628,7 +733,7 @@ export function sessionsSocket<D extends EventDefs>(
           return
         }
         for (const entry of entries) {
-          control(() => startSubscription(entry.id, entry.index))
+          control(() => startSubscription(entry))
         }
         return
       }

package/src/sse.ts

@@ -12,14 +12,31 @@ import type { PresencePatch, PresenceSnapshot } from './contract.ts'
 import { invocationDeadlineMs } from './platform.ts'
 import { streamActivities } from './stream-activity.ts'
 import {
+  isSerializedEvent,
+  parseSerializedEvent,
+  takeBuffered,
+  type HeldEvent,
+} from './stream-buffer.ts'
+import {
+  type StateSnapshotFrame,
+  type WireVersion,
+  EVENT_WRITE_CHARS,
+  compactEventJson,
+  heldEventBatch,
+  isStreamEvent,
+  stateSnapshotToWire,
   eventToWire,
+  serializedEventToWireJson,
   presencePatchToWire,
   presenceSnapshotToWire,
 } from './wire.ts'
 
 /**
  * Pipe a live event iterable into an SSE `Response`. Each event is one
- * frame — `id:` carries the event-log index, `data:` the JSON event. A
+ * frame — `id:` carries the event-log index, `data:` the JSON event.
+ * Frames for events the iterable already holds are written together. With
+ * `wire: 2` those events share one frame instead: `data:` is a JSON array of
+ * `CompactWireEvent`s and `id:` the last one's index. A
  * `stream({ presence: true })` iterable also yields presence items,
  * which ride as named frames old clients skip: `event:
  * presence-snapshot` first (the map, ISO dates), then `event: presence`
@@ -34,8 +51,12 @@ import {
  * a platform-timeout failure.
  */
 export function sseResponse(
-  iterable: AsyncIterable<Event | PresencePatch | PresenceSnapshot>,
+  iterable: AsyncIterable<
+    Event | PresencePatch | PresenceSnapshot | StateSnapshotFrame
+  >,
+  options: { wire?: WireVersion } = {},
 ): Response {
+  const write = options.wire === 2 ? batchedFrames : eventFrames
   const iterator = iterable[Symbol.asyncIterator]()
   const encoder = new TextEncoder()
   let heartbeat: ReturnType<typeof setInterval> | undefined
@@ -121,7 +142,7 @@ export function sseResponse(
           controller.close()
           return
         }
-        controller.enqueue(encoder.encode(frameFor(value)))
+        controller.enqueue(encoder.encode(write(value, iterator)))
       } catch (error) {
         if (closed) return
         closed = true
@@ -147,12 +168,58 @@ export function sseResponse(
   })
 }
 
-function frameFor(item: Event | PresencePatch | PresenceSnapshot): string {
+type StreamItem =
+  HeldEvent | PresencePatch | PresenceSnapshot | StateSnapshotFrame
+
+/** Version 1: one frame per event, then each event the iterator holds. */
+function eventFrames(first: StreamItem, iterator: object): string {
+  let frames = frameFor(first)
+  while (frames.length < EVENT_WRITE_CHARS) {
+    const event = takeBuffered(iterator)
+    if (!event) break
+    frames += frameFor(event)
+  }
+  return frames
+}
+
+/**
+ * Version 2: events this write carries share one frame, a JSON array whose
+ * `id:` is its last index. Held events are always events, so only `first`
+ * can be a snapshot or presence frame.
+ */
+function batchedFrames(first: StreamItem, iterator: object): string {
+  const lead = isStreamEvent(first) ? '' : frameFor(first)
+  const head = isStreamEvent(first) ? first : takeBuffered(iterator)
+  if (!head) return lead
+  const { events, last } = heldEventBatch({
+    first: head,
+    iterator,
+    encode: compactJsonLine,
+  })
+  return `${lead}id: ${last.index}\ndata: [${events.join(',')}]\n\n`
+}
+
+// JSON.stringify output has no raw line breaks; any other stored text is
+// re-serialized so it stays on its data: line.
+const compactJsonLine = (event: HeldEvent): string =>
+  isSerializedEvent(event) && /[\r\n]/.test(event.payloadJson)
+    ? compactEventJson(parseSerializedEvent(event))
+    : compactEventJson(event)
+
+function frameFor(item: StreamItem): string {
+  if ('kind' in item)
+    return `event: a2-snapshot\ndata: ${JSON.stringify(stateSnapshotToWire(item))}\n\n`
   if ('snapshot' in item) {
     return `event: presence-snapshot\ndata: ${JSON.stringify(presenceSnapshotToWire(item))}\n\n`
   }
   if ('participant' in item) {
     return `event: presence\ndata: ${JSON.stringify(presencePatchToWire(item))}\n\n`
   }
+  // JSON.stringify output has no raw line breaks; any other stored text is
+  // re-serialized so it stays on its data: line.
+  if (isSerializedEvent(item))
+    return /[\r\n]/.test(item.payloadJson)
+      ? `id: ${item.index}\ndata: ${JSON.stringify(eventToWire(parseSerializedEvent(item)))}\n\n`
+      : `id: ${item.index}\ndata: ${serializedEventToWireJson(item)}\n\n`
   return `id: ${item.index}\ndata: ${JSON.stringify(eventToWire(item))}\n\n`
 }