experimental-a2 0.6.0 → 0.8.0

package/src/session-socket.ts

@@ -11,7 +11,8 @@ import { A2Error } from './errors.ts'
 import { SOCKET_TIMINGS, STREAM_TIMINGS } from './internal.ts'
 import type { Event } from './store.ts'
 import type { EventDefs, PresencePatch, PresenceSnapshot } from './contract.ts'
-import type { PushedEvent, PushedPresence, Session } from './server.ts'
+import type { ParsedPushEvent, ParsedPushPresence } from './push-envelope.ts'
+import type { Session } from './server.ts'
 import { parsePresenceSibling, parsePushEvents } from './push-envelope.ts'
 import {
   SOCKET_PING_FRAME,
@@ -71,16 +72,15 @@ const MAX_MALFORMED_FRAMES = 5
  * The pump's runtime view of a session. The presence members are
  * conditional on the public surface (`WithPresence`) and therefore
  * invisible on a generic `Session<D>`, so capability is checked at
- * runtime (`setPresence` present) — the same resolution as the docs'
- * route sample. The casts live in `sessionsSocket` and `handle`.
+ * runtime (`setPresence` present). The cast stays inside the transport.
  */
 export type SocketSession = {
   stream(opts: {
     startAfter: number
     presence?: boolean
   }): AsyncIterable<Event | PresencePatch | PresenceSnapshot>
-  append(...events: PushedEvent[]): Promise<Event[]>
-  setPresence?(patch: PushedPresence): Promise<void>
+  append(...events: ParsedPushEvent[]): Promise<Event[]>
+  setPresence?(patch: ParsedPushPresence): Promise<void>
 }
 
 /**
@@ -238,7 +238,8 @@ export type SessionsSocketResolve<D extends EventDefs> = (
   sessionId: string,
   /** The entry's resume frontier — `stream({ startAfter })`. */
   startAfter: number,
-) => Session<D> | null | Promise<Session<D> | null>
+) =>
+  Pick<Session<D>, 'stream'> | null | Promise<Pick<Session<D>, 'stream'> | null>
 
 export type SessionsSocketOptions = {
   /** The `stream()` presence opt-in for every session on the socket —
@@ -247,17 +248,11 @@ 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
-  /**
-   * Per-frame push gate — policy's seam on the up lane, the socket
-   * counterpart of a POST route's checks (`handle`'s `before` rides
-   * it). Runs after the frame parses and before `append`: return an
-   * `A2Error` to answer the push with that error ack (nothing
-   * appended), `null` to allow. Absent, every push on an accepted
-   * subscription is allowed — the prior behavior, unchanged.
-   */
+  /** Runs after frame parsing and before append or presence I/O. */
   gatePush?(
     sessionId: string,
-    events: PushedEvent[],
+    events: ParsedPushEvent[],
+    presence?: ParsedPushPresence,
   ): A2Error | null | Promise<A2Error | null>
 }
 
@@ -359,11 +354,14 @@ export function sessionsSocket<D extends EventDefs>(
     id: string,
     index: number,
   ): Promise<void> => {
-    let session: Session<D> | null
+    let session: Pick<Session<D>, 'stream'> | null
     try {
       session = await resolve(id, index)
     } catch {
-      session = null
+      if (!shell.torn()) {
+        shell.send(socketUnsubscribedFor(id, 'stream failed'))
+      }
+      return
     }
     if (shell.torn()) return
     if (session === null) {
@@ -419,7 +417,8 @@ export function sessionsSocket<D extends EventDefs>(
     }
     try {
       const events = parsePushEvents(frame['events'])
-      const denial = (await options?.gatePush?.(sessionId, events)) ?? null
+      const denial =
+        (await options?.gatePush?.(sessionId, events, undefined)) ?? null
       if (denial !== null) {
         shell.send(socketErrorAckFor(req, denial, sessionId))
         return
@@ -442,11 +441,28 @@ export function sessionsSocket<D extends EventDefs>(
       shell.malformedFrame('presence frame on a presence-less session')
       return
     }
+    let patch: ParsedPushPresence | undefined
     try {
-      const patch = parsePresenceSibling(frame)
-      if (patch) await subscription.target.setPresence(patch)
+      patch = parsePresenceSibling(frame)
     } catch {
       shell.malformedFrame('invalid presence frame')
+      return
+    }
+    if (!patch) return
+    try {
+      const denial = (await options?.gatePush?.(sessionId, [], patch)) ?? null
+      if (denial !== null) return
+      await subscription.target.setPresence(patch)
+    } catch (error) {
+      const failure = asA2Error(error)
+      if (
+        failure.code === 'INVALID_PAYLOAD' ||
+        failure.code === 'UNKNOWN_PRESENCE_FIELD'
+      ) {
+        shell.malformedFrame('invalid presence frame')
+        return
+      }
+      shell.shutdown(1011, 'internal error')
     }
   }
 

package/src/sse.ts

@@ -1,7 +1,7 @@
 /**
  * The SSE response protocol — framing, heartbeat, deadline, and
- * teardown for the live stream lane. Internal module: `handle`'s
- * stream branch is the one sanctioned caller; the framing rules stay
+ * teardown for the live stream lane. Internal module: `server.fetch` is
+ * the sanctioned caller; the framing rules stay
  * documented on `sseResponse` because the client's parser (and the
  * stall watchdog) depend on them.
  */

package/src/store-memory.ts

@@ -21,7 +21,6 @@ import {
   type IdSource,
   type PresenceRow,
   type StoredEvent,
-  type StoredSessionSummary,
   type StoreStateRead,
 } from './store.ts'
 
@@ -102,6 +101,12 @@ const toEvent = (row: Row): Event => ({
   createdAt: new Date(row.createdAt),
 })
 
+const snapshotKey = (sessionId: string, reducerName: string): string =>
+  `${sessionId}\u0000${reducerName}`
+
+const eventPinKey = (sessionId: string, index: number): string =>
+  `${sessionId}\u0000${index}`
+
 export function memory(options: MemoryStoreOptions = {}): A2Store {
   const clock = options.clock ?? SYSTEM_CLOCK
   const generateId = options.ids ?? RANDOM_IDS
@@ -115,6 +120,12 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
     string,
     { index: number; state: unknown; updatedAt: Date }
   >()
+  const historicalSnapshots = new Map<
+    string,
+    { index: number; state: unknown; updatedAt: Date }
+  >()
+  const snapshotPins = new Map<string, Set<string>>()
+  const snapshotPinCounts = new Map<string, number>()
   const streamSubscribers = new Map<string, Set<(row: Row) => void>>()
   /** ns → participant → field → latest surviving write. */
   const presenceRows = new Map<
@@ -143,6 +154,28 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
     return rows
   }
 
+  const checkpointKey = (
+    sessionId: string,
+    reducerName: string,
+    index: number,
+  ): string => `${snapshotKey(sessionId, reducerName)}\u0000${index}`
+
+  const releaseSnapshotPins = (sessionId: string, eventIndex: number): void => {
+    const pinKey = eventPinKey(sessionId, eventIndex)
+    const checkpoints = snapshotPins.get(pinKey)
+    if (!checkpoints) return
+    for (const key of checkpoints) {
+      const next = (snapshotPinCounts.get(key) ?? 1) - 1
+      if (next === 0) {
+        snapshotPinCounts.delete(key)
+        historicalSnapshots.delete(key)
+      } else {
+        snapshotPinCounts.set(key, next)
+      }
+    }
+    snapshotPins.delete(pinKey)
+  }
+
   const dispatchOf = (sessionId: string): SessionDispatch => {
     let state = dispatch.get(sessionId)
     if (!state) {
@@ -296,16 +329,41 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
   const readStateOf = (
     sessionId: string,
     reducerName: string,
+    throughIndex?: number,
+    snapshotThroughIndex?: number,
   ): StoreStateRead => {
-    const snap = snapshots.get(`${sessionId}\u0000${reducerName}`)
-    const snapshot = snap
-      ? { index: snap.index, state: structuredClone(snap.state) }
+    const key = snapshotKey(sessionId, reducerName)
+    const snapshotFrontier = snapshotThroughIndex ?? throughIndex
+    const head = snapshots.get(key)
+    let candidate =
+      head && (snapshotFrontier === undefined || head.index <= snapshotFrontier)
+        ? head
+        : null
+    if (snapshotFrontier !== undefined) {
+      const prefix = `${key}\u0000`
+      for (const [historicalKey, snapshot] of historicalSnapshots) {
+        if (
+          historicalKey.startsWith(prefix) &&
+          snapshot.index <= snapshotFrontier &&
+          (!candidate || snapshot.index > candidate.index)
+        ) {
+          candidate = snapshot
+        }
+      }
+    }
+    const snapshot = candidate
+      ? { index: candidate.index, state: structuredClone(candidate.state) }
       : null
     const afterIndex = snapshot?.index ?? 0
     return {
+      headIndex: head?.index ?? null,
       snapshot,
       events: (sessions.get(sessionId) ?? [])
-        .filter((row) => row.index > afterIndex)
+        .filter(
+          (row) =>
+            row.index > afterIndex &&
+            (throughIndex === undefined || row.index <= throughIndex),
+        )
         .map(toEvent),
     }
   }
@@ -489,6 +547,7 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       parent.claimHolder = null
       parent.claimExpiresAt = null
       settle(sessionId, parent)
+      releaseSnapshotPins(sessionId, index)
       notifyStreams(sessionId, inserted)
       return { outcome: 'completed', events: inserted.map(toStored) }
     },
@@ -521,6 +580,7 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       if (row.failureCount >= maxFailures) {
         row.failedAt = new Date(failedAt)
         dispatchOf(sessionId).ready.delete(row.index)
+        releaseSnapshotPins(sessionId, index)
         return {
           outcome: 'dead_lettered',
           failureCount: row.failureCount,
@@ -529,26 +589,83 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       return { outcome: 'failed', failureCount: row.failureCount }
     },
 
-    async readState(sessionId, reducerName) {
-      return readStateOf(sessionId, reducerName)
+    async readState(sessionId, reducerName, stateOptions) {
+      return readStateOf(
+        sessionId,
+        reducerName,
+        stateOptions?.throughIndex,
+        stateOptions?.snapshotThroughIndex,
+      )
     },
 
-    async readStates(sessionIds, reducerName) {
-      return sessionIds.map((sessionId) => readStateOf(sessionId, reducerName))
+    async readStates(requests, reducerName) {
+      return requests.map((request) =>
+        readStateOf(
+          request.sessionId,
+          reducerName,
+          request.throughIndex,
+          request.snapshotThroughIndex,
+        ),
+      )
     },
 
-    async putSnapshot(sessionId, reducerName, index, state) {
-      const key = `${sessionId}\u0000${reducerName}`
-      const existing = snapshots.get(key)
-      // Guarded upsert: a slower concurrent writer must never clobber a
-      // further-along snapshot. A lost race costs a few refolded events
-      // next read — never correctness.
-      if (existing && existing.index >= index) return
-      snapshots.set(key, {
-        index,
-        state: structuredClone(state),
-        updatedAt: clock.now(),
-      })
+    async putSnapshots(sessionId, reducerName, writes) {
+      const key = snapshotKey(sessionId, reducerName)
+      for (const write of writes.toSorted((a, b) => a.index - b.index)) {
+        const checkpoint = checkpointKey(sessionId, reducerName, write.index)
+        for (const eventIndex of write.pinEventIndexes ?? []) {
+          const event = sessions.get(sessionId)?.[eventIndex - 1]
+          if (!event || event.processedAt !== null || event.failedAt !== null) {
+            continue
+          }
+          const pinKey = eventPinKey(sessionId, eventIndex)
+          let pinned = snapshotPins.get(pinKey)
+          if (!pinned) {
+            pinned = new Set()
+            snapshotPins.set(pinKey, pinned)
+          }
+          if (!pinned.has(checkpoint)) {
+            pinned.add(checkpoint)
+            snapshotPinCounts.set(
+              checkpoint,
+              (snapshotPinCounts.get(checkpoint) ?? 0) + 1,
+            )
+          }
+        }
+
+        const current = snapshots.get(key)
+        if (!current || write.index >= current.index) {
+          if (current && write.index > current.index) {
+            const currentCheckpoint = checkpointKey(
+              sessionId,
+              reducerName,
+              current.index,
+            )
+            if ((snapshotPinCounts.get(currentCheckpoint) ?? 0) > 0) {
+              historicalSnapshots.set(currentCheckpoint, {
+                index: current.index,
+                state: structuredClone(current.state),
+                updatedAt: new Date(current.updatedAt),
+              })
+            }
+          }
+          snapshots.set(key, {
+            index: write.index,
+            state: structuredClone(write.state),
+            updatedAt: clock.now(),
+          })
+          historicalSnapshots.delete(checkpoint)
+        } else if (
+          write.index < current.index &&
+          (snapshotPinCounts.get(checkpoint) ?? 0) > 0
+        ) {
+          historicalSnapshots.set(checkpoint, {
+            index: write.index,
+            state: structuredClone(write.state),
+            updatedAt: clock.now(),
+          })
+        }
+      }
     },
 
     presence: {
@@ -648,86 +765,6 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       },
     },
 
-    inspect: {
-      async listSessions(inspectionOptions) {
-        const ids = [...sessions.keys()]
-          .filter(
-            (sessionId) =>
-              sessionId.startsWith(inspectionOptions.prefix) &&
-              (inspectionOptions.cursor === undefined ||
-                sessionId > inspectionOptions.cursor),
-          )
-          .toSorted()
-        const visible = ids.slice(0, inspectionOptions.limit)
-        const summaries = visible.map((sessionId): StoredSessionSummary => {
-          const rows = sessions.get(sessionId)!
-          const first = rows[0]!
-          let updatedAt = first.createdAt
-          let pendingCount = 0
-          let failedCount = 0
-          let attemptCount = 0
-          let failureCount = 0
-          for (const row of rows) {
-            attemptCount += row.attemptCount
-            failureCount += row.failureCount
-            if (row.processedAt === null && row.failedAt === null) {
-              pendingCount += 1
-            }
-            if (row.failedAt !== null) failedCount += 1
-            for (const timestamp of [
-              row.createdAt,
-              row.firstClaimedAt,
-              row.lastClaimedAt,
-              row.lastFailedAt,
-              row.processedAt,
-              row.failedAt,
-            ]) {
-              if (timestamp && timestamp > updatedAt) updatedAt = timestamp
-            }
-          }
-          return {
-            sessionId,
-            eventCount: rows.length,
-            pendingCount,
-            failedCount,
-            attemptCount,
-            failureCount,
-            firstEventAt: new Date(first.createdAt),
-            updatedAt: new Date(updatedAt),
-          }
-        })
-        return {
-          sessions: summaries,
-          cursor: ids.length > visible.length ? (visible.at(-1) ?? null) : null,
-        }
-      },
-      async readEvents(sessionId, pageOptions) {
-        const rows = sessions.get(sessionId) ?? []
-        const throughIndex = Math.min(
-          pageOptions.throughIndex ?? rows.length,
-          rows.length,
-        )
-        return {
-          events: rows
-            .slice(pageOptions.afterIndex, throughIndex)
-            .slice(0, pageOptions.limit)
-            .map(toStored),
-          throughIndex,
-        }
-      },
-      async listSnapshots(sessionId) {
-        const prefix = `${sessionId}\u0000`
-        return [...snapshots.entries()]
-          .filter(([key]) => key.startsWith(prefix))
-          .map(([key, snapshot]) => ({
-            reducerName: key.slice(prefix.length),
-            index: snapshot.index,
-            updatedAt: new Date(snapshot.updatedAt),
-          }))
-          .toSorted((a, b) => a.reducerName.localeCompare(b.reducerName))
-      },
-    },
-
     stream(sessionId, opts) {
       const startAfter = opts?.startAfter ?? 0
       return {