mppx 0.6.31 → 0.7.0

package/src/tempo/session/server/Sse.ts

@@ -0,0 +1,256 @@
+import type { Hex } from 'viem'
+
+import * as Constants from '../../../Constants.js'
+import * as Credential from '../../../Credential.js'
+import {
+  createSessionReceipt,
+  extractData,
+  formatMessageEvent,
+  formatNeedVoucherEvent,
+  formatReceiptEvent,
+  parseEvent,
+  readSessionChallengeAmount,
+  requireSessionCredentialContext,
+  type SseEvent,
+} from '../precompile/Protocol.js'
+import * as ChannelStore from './ChannelStore.js'
+import { meterIterable, type SessionController } from './MeteredStream.js'
+
+/**
+ * SSE (Server-Sent Events) utilities for metered streaming payments.
+ *
+ * Provides event formatting/parsing, balance polling, the core
+ * `serve()` loop that meters an async iterable into a ReadableStream
+ * of SSE events, and helpers (`toResponse`, `fromRequest`) for
+ * building HTTP responses from the stream.
+ */
+
+export {
+  extractData,
+  formatMessageEvent,
+  formatNeedVoucherEvent,
+  formatReceiptEvent,
+  parseEvent,
+  readSessionChallengeAmount,
+  requireSessionCredentialContext,
+  type SseEvent,
+} from '../precompile/Protocol.js'
+
+/** Controller passed to manual-charge SSE generators. */
+export type { SessionController } from './MeteredStream.js'
+
+/**
+ * Wrap an async iterable with payment metering, producing an SSE stream.
+ *
+ * `generate` may be either:
+ * - An `AsyncIterable<string>` — each yielded value is automatically charged
+ *   (one `tickCost` per value).
+ * - A callback `(stream: SessionController) => AsyncIterable<string>` — the
+ *   generator controls when charges happen by calling `stream.charge()`.
+ *
+ * For each emitted value the stream:
+ * 1. Reserves `tickCost` from the channel's available voucher headroom
+ *    (auto or manual).
+ * 2. If balance is sufficient, emits `event: message` with the value.
+ * 3. If balance is exhausted, emits `event: payment-need-voucher`
+ *    and polls store until the client tops up the channel.
+ * 4. Commits the reserved charge immediately before the chunk is emitted.
+ * 5. On generator completion, emits a final `event: payment-receipt`.
+ *
+ * Returns a `ReadableStream<Uint8Array>` suitable for use as an HTTP response body.
+ */
+export function serve(options: serve.Options): ReadableStream<Uint8Array> {
+  const {
+    store,
+    channelId,
+    challengeId,
+    tickCost,
+    generate,
+    pollIntervalMs = 100,
+    signal,
+  } = options
+
+  const encoder = new TextEncoder()
+
+  return new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const aborted = () => signal?.aborted ?? false
+      const emit = (event: string) => controller.enqueue(encoder.encode(event))
+
+      try {
+        for await (const value of meterIterable({
+          store,
+          channelId,
+          tickCost,
+          generate,
+          pollIntervalMs,
+          prepaidUnits: options.prepaidUnits,
+          signal,
+          emitNeedVoucher: emit,
+          formatNeedVoucher: formatNeedVoucherEvent,
+        })) {
+          if (aborted()) break
+          controller.enqueue(encoder.encode(formatMessageEvent(value)))
+        }
+
+        if (!aborted()) {
+          const channel = await store.getChannel(channelId)
+          if (channel) {
+            const receipt = createSessionReceipt({
+              challengeId,
+              channelId,
+              acceptedCumulative: channel.highestVoucherAmount,
+              spent: channel.spent,
+              units: channel.units,
+            })
+            controller.enqueue(encoder.encode(formatReceiptEvent(receipt)))
+          }
+        }
+      } catch (e) {
+        if (!aborted()) controller.error(e)
+      } finally {
+        controller.close()
+      }
+    },
+  })
+}
+
+/** Type helpers for {@link serve}. */
+export declare namespace serve {
+  type Options = {
+    store: ChannelStore.ChannelStore
+    channelId: Hex
+    challengeId: string
+    tickCost: bigint
+    generate: AsyncIterable<string> | ((stream: SessionController) => AsyncIterable<string>)
+    pollIntervalMs?: number | undefined
+    prepaidUnits?: number | undefined
+    signal?: AbortSignal | undefined
+  }
+}
+
+/**
+ * Wrap a `ReadableStream<Uint8Array>` (from {@link serve}) in an HTTP
+ * `Response` with the correct SSE headers.
+ */
+export function toResponse(body: ReadableStream<Uint8Array>): Response {
+  return new Response(body, {
+    headers: {
+      'Cache-Control': 'no-cache, no-transform',
+      Connection: 'keep-alive',
+      'Content-Type': 'text/event-stream; charset=utf-8',
+    },
+  })
+}
+
+/**
+ * Extract `channelId`, `challengeId`, and `tickCost` from a `Request`'s
+ * `Authorization: Payment …` header.
+ *
+ * This is a convenience for callers that receive a raw `Request` and need
+ * the parameters required by {@link serve}.
+ */
+export function fromRequest(request: Request): fromRequest.Context {
+  const header = request.headers.get(Constants.Headers.authorization)
+  if (!header) throw new Error('Missing Authorization header.')
+
+  const payment = Credential.extractPaymentScheme(header)
+  if (!payment) throw new Error('Missing Payment credential in Authorization header.')
+
+  const credential = Credential.deserialize(payment)
+  const payload = requireSessionCredentialContext(credential.payload)
+  return {
+    challengeId: credential.challenge.id,
+    channelId: payload.channelId,
+    tickCost: readSessionChallengeAmount(credential.challenge),
+  }
+}
+
+/** Type helpers for {@link fromRequest}. */
+export declare namespace fromRequest {
+  type Context = {
+    challengeId: string
+    channelId: Hex
+    tickCost: bigint
+  }
+}
+
+/**
+ * Check whether a `Response` carries an SSE event stream.
+ *
+ * Returns `true` when the `Content-Type` header starts with
+ * `text/event-stream` (case-insensitive, ignoring charset params).
+ */
+export function isEventStream(response: Response): boolean {
+  const ct = response.headers.get('content-type')
+  return ct?.toLowerCase().startsWith('text/event-stream') ?? false
+}
+
+/**
+ * Parse an SSE `Response` body into an async iterable of `data:` payloads.
+ *
+ * Yields the raw `data:` field content for each SSE event in the stream.
+ * Events whose data matches the `skip` predicate are silently dropped
+ * (e.g. `[DONE]` sentinels used by OpenAI-compatible APIs).
+ *
+ * Each yielded value typically becomes one charge tick when fed to
+ * {@link serve} via the SSE transport's auto-charge mode.
+ *
+ * @example
+ * ```ts
+ * const upstream = await fetch('https://api.example.com/stream')
+ * for await (const data of Sse.iterateData(upstream)) {
+ *   console.log(data)
+ * }
+ * ```
+ */
+export async function* iterateData(
+  response: Response,
+  options?: iterateData.Options,
+): AsyncGenerator<string> {
+  const skip = options?.skip
+  const body = response.body
+  if (!body) return
+
+  const reader = body.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+
+  try {
+    while (true) {
+      const { value, done } = await reader.read()
+      if (done) break
+
+      buffer += decoder.decode(value, { stream: true })
+
+      // Split on double-newline SSE event boundaries.
+      const events = buffer.split('\n\n')
+      // Last element may be incomplete — keep in buffer.
+      buffer = events.pop() ?? ''
+
+      for (const event of events) {
+        if (!event.trim()) continue
+        const data = extractData(event)
+        if (data === null) continue
+        if (skip?.(data)) continue
+        yield data
+      }
+    }
+
+    // Flush remaining buffer.
+    if (buffer.trim()) {
+      const data = extractData(buffer)
+      if (data !== null && !skip?.(data)) yield data
+    }
+  } finally {
+    reader.releaseLock()
+  }
+}
+
+/** Type helpers for {@link iterateData}. */
+export declare namespace iterateData {
+  type Options = {
+    /** Predicate to skip specific data payloads (e.g. `d => d === '[DONE]'`). */
+    skip?: ((data: string) => boolean) | undefined
+  }
+}

package/src/tempo/session/server/Transports.test.ts

@@ -0,0 +1,346 @@
+import type { Address, Hex } from 'viem'
+import { describe, expect, test } from 'vp/test'
+
+import { ChannelClosedError } from '../../../Errors.js'
+import type { NeedVoucherEvent } from '../precompile/Protocol.js'
+import * as ChannelStore from './ChannelStore.js'
+import {
+  commitReservedCharges,
+  reserveChargeOrWait,
+  send,
+  subscribe,
+  toText,
+  type SocketEventListener,
+  type SocketEventMap,
+} from './Transports.js'
+
+describe('MeteredStream', () => {
+  const channelId = `0x${'01'.repeat(32)}` as Hex
+
+  const descriptor = {
+    authorizedSigner: '0x0000000000000000000000000000000000000001' as Address,
+    expiringNonceHash: `0x${'11'.repeat(32)}` as Hex,
+    operator: '0x0000000000000000000000000000000000000000' as Address,
+    payee: '0x0000000000000000000000000000000000000002' as Address,
+    payer: '0x0000000000000000000000000000000000000001' as Address,
+    salt: `0x${'22'.repeat(32)}` as Hex,
+    token: '0x20c0000000000000000000000000000000000001' as Address,
+  }
+
+  function channel(overrides: Partial<ChannelStore.State> = {}): ChannelStore.State {
+    const base: ChannelStore.State = {
+      authorizedSigner: descriptor.authorizedSigner,
+      backend: 'precompile',
+      chainId: 4217,
+      escrowContract: '0x4D50500000000000000000000000000000000000' as Address,
+      channelId,
+      closeRequestedAt: 0n,
+      createdAt: '2026-01-01T00:00:00.000Z',
+      deposit: 100n,
+      descriptor,
+      expiringNonceHash: descriptor.expiringNonceHash,
+      finalized: false,
+      highestVoucher: null,
+      highestVoucherAmount: 50n,
+      operator: descriptor.operator,
+      payee: descriptor.payee,
+      payer: descriptor.payer,
+      salt: descriptor.salt,
+      settledOnChain: 0n,
+      spent: 20n,
+      token: descriptor.token,
+      units: 2,
+    }
+    return { ...base, ...overrides }
+  }
+
+  function memoryStore(
+    initial: ChannelStore.State,
+    options: { waitForUpdate?: boolean } = {},
+  ): ChannelStore.ChannelStore {
+    let state: ChannelStore.State | null = initial
+    const waiters = new Set<() => void>()
+    const store: ChannelStore.ChannelStore = {
+      async getChannel() {
+        return state
+      },
+      async updateChannel(_channelId, fn) {
+        state = fn(state)
+        for (const waiter of waiters) waiter()
+        waiters.clear()
+        return state
+      },
+    }
+    if (options.waitForUpdate) {
+      store.waitForUpdate = () => {
+        return new Promise<void>((resolve) => {
+          waiters.add(resolve)
+        })
+      }
+    }
+    return store
+  }
+
+  function formatNeedVoucher(event: NeedVoucherEvent) {
+    return JSON.stringify(event)
+  }
+
+  describe('MeteredStream', () => {
+    test('reserveChargeOrWait returns immediately when voucher headroom is available', async () => {
+      const emitted: string[] = []
+      await reserveChargeOrWait({
+        amount: 10n,
+        channelId,
+        emit(message) {
+          emitted.push(message)
+        },
+        formatNeedVoucher,
+        pollIntervalMs: 1,
+        reservedAmount: 0n,
+        store: memoryStore(channel()),
+      })
+
+      expect(emitted).toEqual([])
+    })
+
+    test('reserveChargeOrWait emits need-voucher and waits for accepted headroom', async () => {
+      const emitted: string[] = []
+      const store = memoryStore(channel({ highestVoucherAmount: 25n, spent: 20n }))
+      const reserved = reserveChargeOrWait({
+        amount: 10n,
+        channelId,
+        emit(message) {
+          emitted.push(message)
+        },
+        formatNeedVoucher,
+        pollIntervalMs: 1,
+        reservedAmount: 0n,
+        store,
+      })
+
+      await Promise.resolve()
+      expect(emitted.map((item) => JSON.parse(item))).toEqual([
+        {
+          channelId,
+          requiredCumulative: '30',
+          acceptedCumulative: '25',
+          deposit: '100',
+        },
+      ])
+
+      await store.updateChannel(channelId, (current) =>
+        current ? { ...current, highestVoucherAmount: 30n } : current,
+      )
+      await reserved
+    })
+
+    test('reserveChargeOrWait observes updates that happen before wait registration', async () => {
+      const emitted: string[] = []
+      const store = memoryStore(channel({ highestVoucherAmount: 25n, spent: 20n }), {
+        waitForUpdate: true,
+      })
+
+      await reserveChargeOrWait({
+        amount: 10n,
+        channelId,
+        async emit(message) {
+          emitted.push(message)
+          await store.updateChannel(channelId, (current) =>
+            current ? { ...current, highestVoucherAmount: 30n } : current,
+          )
+        },
+        formatNeedVoucher,
+        pollIntervalMs: 1,
+        reservedAmount: 0n,
+        store,
+      })
+
+      expect(emitted).toHaveLength(1)
+    })
+
+    test('commitReservedCharges increments spend and units', async () => {
+      const store = memoryStore(channel({ spent: 20n, units: 2, highestVoucherAmount: 50n }))
+
+      await commitReservedCharges({ amount: 10n, channelId, store, units: 1 })
+
+      expect(await store.getChannel(channelId)).toMatchObject({ spent: 30n, units: 3 })
+    })
+
+    test('commitReservedCharges rejects when reserved coverage is no longer available', async () => {
+      await expect(
+        commitReservedCharges({
+          amount: 40n,
+          channelId,
+          store: memoryStore(channel({ spent: 20n, highestVoucherAmount: 50n })),
+          units: 1,
+        }),
+      ).rejects.toThrow('reserved voucher coverage is no longer available')
+    })
+
+    test('commitReservedCharges rejects closed channels', async () => {
+      await expect(
+        commitReservedCharges({
+          amount: 10n,
+          channelId,
+          store: memoryStore(channel({ finalized: true })),
+          units: 1,
+        }),
+      ).rejects.toThrow(ChannelClosedError)
+    })
+  })
+})
+
+describe('SocketTransport', () => {
+  class BrowserSocket {
+    sent: string[] = []
+    listeners = {
+      close: new Set<SocketEventListener<'close'>>(),
+      error: new Set<SocketEventListener<'error'>>(),
+      message: new Set<SocketEventListener<'message'>>(),
+    }
+
+    addEventListener<type extends keyof SocketEventMap>(
+      type: type,
+      listener: SocketEventListener<type>,
+    ) {
+      this.listeners[type].add(listener as never)
+    }
+
+    close() {
+      this.emit('close', { type: 'close' })
+    }
+
+    emit<type extends keyof SocketEventMap>(type: type, event: SocketEventMap[type]) {
+      for (const listener of this.listeners[type]) {
+        if (typeof listener === 'function') listener(event as never)
+        else listener.handleEvent(event as never)
+      }
+    }
+
+    removeEventListener<type extends keyof SocketEventMap>(
+      type: type,
+      listener: SocketEventListener<type>,
+    ) {
+      this.listeners[type].delete(listener as never)
+    }
+
+    send(data: string) {
+      this.sent.push(data)
+    }
+  }
+
+  class NodeSocket {
+    sent: string[] = []
+    listeners = {
+      close: new Set<(event: SocketEventMap['close']) => void>(),
+      error: new Set<(event: SocketEventMap['error']) => void>(),
+      message: new Set<(event: SocketEventMap['message']) => void>(),
+    }
+
+    close() {
+      this.emit('close', { type: 'close' })
+    }
+
+    emit<type extends keyof SocketEventMap>(type: type, event: SocketEventMap[type]) {
+      for (const listener of this.listeners[type]) listener(event as never)
+    }
+
+    off<type extends keyof SocketEventMap>(
+      type: type,
+      listener: (event: SocketEventMap[type]) => void,
+    ) {
+      this.listeners[type].delete(listener as never)
+    }
+
+    on<type extends keyof SocketEventMap>(
+      type: type,
+      listener: (event: SocketEventMap[type]) => void,
+    ) {
+      this.listeners[type].add(listener as never)
+    }
+
+    send(data: string) {
+      this.sent.push(data)
+    }
+  }
+
+  describe('SocketTransport', () => {
+    test('subscribe handles browser-style socket events', () => {
+      const socket = new BrowserSocket()
+      const messages: unknown[] = []
+      let closed = 0
+      let errors = 0
+
+      const unsubscribe = subscribe(socket, {
+        close() {
+          closed++
+        },
+        error() {
+          errors++
+        },
+        message(value) {
+          messages.push(value)
+        },
+      })
+
+      socket.emit('message', { data: 'hello', type: 'message' })
+      socket.emit('error', { type: 'error' })
+      socket.emit('close', { type: 'close' })
+      unsubscribe()
+      socket.emit('message', { data: 'ignored', type: 'message' })
+
+      expect(messages).toEqual(['hello'])
+      expect(errors).toBe(1)
+      expect(closed).toBe(1)
+    })
+
+    test('subscribe handles node-style socket events', () => {
+      const socket = new NodeSocket()
+      const messages: unknown[] = []
+
+      const unsubscribe = subscribe(socket, {
+        close() {},
+        error() {},
+        message(value) {
+          messages.push(value)
+        },
+      })
+
+      socket.emit('message', { data: 'hello', type: 'message' })
+      unsubscribe()
+      socket.emit('message', { data: 'ignored', type: 'message' })
+
+      expect(messages).toEqual([{ data: 'hello', type: 'message' }])
+    })
+
+    test('subscribe rejects unsupported socket implementations', () => {
+      expect(() =>
+        subscribe({ close() {}, send() {} }, { close() {}, error() {}, message() {} }),
+      ).toThrow('unsupported websocket implementation')
+    })
+
+    test('send supports sync and async socket implementations', async () => {
+      const syncSocket = new BrowserSocket()
+      const asyncSocket = {
+        close() {},
+        sent: [] as string[],
+        async send(data: string) {
+          this.sent.push(data)
+        },
+      }
+
+      await send(syncSocket, 'sync')
+      await send(asyncSocket, 'async')
+
+      expect(syncSocket.sent).toEqual(['sync'])
+      expect(asyncSocket.sent).toEqual(['async'])
+    })
+
+    test('toText normalizes common message payloads', () => {
+      expect(toText('hello')).toBe('hello')
+      expect(toText(new TextEncoder().encode('bytes'))).toBe('bytes')
+      expect(toText(new TextEncoder().encode('buffer').buffer)).toBe('buffer')
+      expect(toText({ data: 'object' })).toBeNull()
+    })
+  })
+})