mppx 0.8.15 → 0.8.18

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

@@ -1,254 +0,0 @@
-import type { Hex } from 'viem'
-
-import * as Constants from '../../../Constants.js'
-import * as Credential from '../../../Credential.js'
-import {
-  createSessionReceipt,
-  extractData,
-  formatMessageEvent,
-  formatNeedVoucherEvent,
-  formatReceiptEvent,
-  readSessionChallengeAmount,
-  requireSessionCredentialContext,
-} 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

@@ -1,346 +0,0 @@
-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()
-    })
-  })
-})