mppx 0.11.0 → 0.13.1

package/dist/tempo/session/server/Sse.d.ts

@@ -27,7 +27,9 @@ export type { SessionController } from './MeteredStream.js';
  * 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.
+ * 4. Commits the reserved charge immediately before the chunk is emitted. If a
+ *    manual generator completes after charging without yielding another chunk,
+ *    commits that terminal charge on successful completion.
  * 5. On generator completion, emits a final `event: payment-receipt`.
  *
  * Returns a `ReadableStream<Uint8Array>` suitable for use as an HTTP response body.

package/dist/tempo/session/server/Sse.js

@@ -26,7 +26,9 @@ export { extractData, formatMessageEvent, formatNeedVoucherEvent, formatReceiptE
  * 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.
+ * 4. Commits the reserved charge immediately before the chunk is emitted. If a
+ *    manual generator completes after charging without yielding another chunk,
+ *    commits that terminal charge on successful completion.
  * 5. On generator completion, emits a final `event: payment-receipt`.
  *
  * Returns a `ReadableStream<Uint8Array>` suitable for use as an HTTP response body.
@@ -34,28 +36,59 @@ export { extractData, formatMessageEvent, formatNeedVoucherEvent, formatReceiptE
 export function serve(options) {
     const { store, channelId, challengeId, tickCost, generate, pollIntervalMs = 100, signal, } = options;
     const encoder = new TextEncoder();
+    const abortController = new AbortController();
+    let streamController;
+    let terminal = false;
+    const iterator = meterIterable({
+        store,
+        channelId,
+        tickCost,
+        generate,
+        onChargeCommitted: options.onChargeCommitted,
+        pollIntervalMs,
+        prepaidUnits: options.prepaidUnits,
+        signal: abortController.signal,
+        emitNeedVoucher: (event) => streamController?.enqueue(encoder.encode(event)),
+        formatNeedVoucher: formatNeedVoucherEvent,
+    })[Symbol.asyncIterator]();
+    const cleanup = () => signal?.removeEventListener('abort', abort);
+    const terminate = (reason) => {
+        if (terminal)
+            return;
+        terminal = true;
+        abortController.abort(reason);
+        cleanup();
+        void Promise.resolve()
+            .then(() => iterator.return?.(undefined))
+            .catch(() => { });
+        try {
+            streamController?.close();
+        }
+        catch { }
+    };
+    const abort = () => terminate(signal?.reason);
+    signal?.addEventListener('abort', abort, { once: true });
     return new ReadableStream({
-        async start(controller) {
-            const aborted = () => signal?.aborted ?? false;
-            const emit = (event) => controller.enqueue(encoder.encode(event));
+        start(controller) {
+            streamController = controller;
+            if (signal?.aborted)
+                abort();
+        },
+        async pull(controller) {
+            if (terminal)
+                return;
             try {
-                for await (const value of meterIterable({
-                    store,
-                    channelId,
-                    tickCost,
-                    generate,
-                    onChargeCommitted: options.onChargeCommitted,
-                    pollIntervalMs,
-                    prepaidUnits: options.prepaidUnits,
-                    signal,
-                    emitNeedVoucher: emit,
-                    formatNeedVoucher: formatNeedVoucherEvent,
-                })) {
-                    if (aborted())
-                        break;
+                const next = await iterator.next();
+                if (terminal)
+                    return;
+                if (!next.done) {
+                    if (abortController.signal.aborted)
+                        return;
+                    const value = next.value;
                     controller.enqueue(encoder.encode(formatMessageEvent(value)));
+                    return;
                 }
-                if (!aborted()) {
+                if (!abortController.signal.aborted) {
                     const channel = await store.getChannel(channelId);
                     if (channel) {
                         const receipt = createSessionReceipt({
@@ -66,16 +99,29 @@ export function serve(options) {
                             units: channel.units,
                         });
                         controller.enqueue(encoder.encode(formatReceiptEvent(receipt)));
+                        terminal = true;
+                        cleanup();
+                        controller.close();
+                        return;
                     }
                 }
+                terminal = true;
+                cleanup();
+                controller.close();
             }
             catch (e) {
-                if (!aborted())
+                if (terminal)
+                    return;
+                terminal = true;
+                cleanup();
+                if (!abortController.signal.aborted)
                     controller.error(e);
+                else
+                    controller.close();
             }
-            finally {
-                controller.close();
-            }
+        },
+        cancel(reason) {
+            terminate(reason);
         },
     });
 }
@@ -154,26 +200,30 @@ export async function* iterateData(response, options) {
         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) {
+                buffer += decoder.decode();
+            else
+                buffer += decoder.decode(value, { stream: true });
+            while (true) {
+                const separator = findSseSeparator(buffer, done);
+                if (!separator)
+                    break;
+                const event = buffer.slice(0, separator.index);
+                buffer = buffer.slice(separator.index + separator.length);
                 if (!event.trim())
                     continue;
-                const data = extractData(event);
+                const data = extractData(event.replace(/\r\n|\r/g, '\n'));
                 if (data === null)
                     continue;
                 if (skip?.(data))
                     continue;
                 yield data;
             }
+            if (done)
+                break;
         }
         // Flush remaining buffer.
         if (buffer.trim()) {
-            const data = extractData(buffer);
+            const data = extractData(buffer.replace(/\r\n|\r/g, '\n'));
             if (data !== null && !skip?.(data))
                 yield data;
         }
@@ -182,4 +232,27 @@ export async function* iterateData(response, options) {
         reader.releaseLock();
     }
 }
+function findSseSeparator(value, complete) {
+    for (let index = 0; index < value.length; index++) {
+        const first = lineEndingLength(value, index, complete);
+        if (!first)
+            continue;
+        const second = lineEndingLength(value, index + first, complete);
+        if (second)
+            return { index, length: first + second };
+        index += first - 1;
+    }
+    return undefined;
+}
+function lineEndingLength(value, index, complete) {
+    if (value[index] === '\n')
+        return 1;
+    if (value[index] !== '\r')
+        return 0;
+    if (value[index + 1] === '\n')
+        return 2;
+    if (index + 1 === value.length && !complete)
+        return 0;
+    return 1;
+}
 //# sourceMappingURL=Sse.js.map

package/dist/tempo/session/server/Transports.d.ts

@@ -13,34 +13,31 @@ export type ReserveChargeParameters = {
     formatNeedVoucher(parameters: NeedVoucherEvent): string;
     /** Store polling interval when `waitForUpdate` is unavailable. */
     pollIntervalMs: number;
-    /** Amount already reserved but not yet committed by this stream loop. */
-    reservedAmount: bigint;
+    /** Identifier owned by this stream across reserve, commit, and release. */
+    reservationId: string;
+    /** Requires a previous uncommitted charge to retain its lease. */
+    requireExisting?: boolean | undefined;
     /** Optional abort signal for long waits. */
     signal?: AbortSignal | undefined;
     /** Channel store used for state reads and waits. */
     store: ChannelStore.ChannelStore;
 };
-/** Parameters for committing previously reserved stream charges. */
+/** Inputs for updating the reservation owned by one stream. */
 export type CommitReservedChargesParameters = {
-    /** Reserved amount to commit. */
-    amount: bigint;
-    /** Channel being metered. */
     channelId: Hex;
-    /** Channel store used for atomic updates. */
+    reservationId: string;
     store: ChannelStore.ChannelStore;
-    /** Number of charge units to add. */
-    units: number;
 };
-/**
- * Reserves voucher headroom for a future stream emission.
- *
- * If the channel lacks headroom, emits one need-voucher frame, then waits for
- * a store update or polling interval until the accepted voucher covers both
- * already-reserved charges and the next requested amount.
- */
+/** Lease duration for abandoned stream reservations. Active generators renew it. */
+export declare const streamReservationLeaseMs = 30000;
+/** Atomically reserves shared voucher coverage before billable stream work begins. */
 export declare function reserveChargeOrWait(options: ReserveChargeParameters): Promise<void>;
-/** Atomically commits previously reserved stream charges to channel spend and unit counters. */
+/** Commits only this stream's live reservation, removing it in the same atomic update. */
 export declare function commitReservedCharges(options: CommitReservedChargesParameters): Promise<ChannelStore.State | undefined>;
+/** Releases only the unused reservation owned by this stream. */
+export declare function releaseReservedCharges({ store, channelId, reservationId, }: CommitReservedChargesParameters): Promise<void>;
+/** Renews a live reservation without reviving an expired or released lease. */
+export declare function renewReservedCharges({ store, channelId, reservationId, }: CommitReservedChargesParameters): Promise<void>;
 /** Throws when a channel can no longer be used for streaming charges. */
 export declare function throwIfChannelClosed(channel: ChannelStore.State): void;
 /** Minimal socket event map supported by browser and Node-style WebSocket runtimes. */
@@ -64,6 +61,8 @@ export type SocketEventListener<type extends keyof SocketEventMap> = ((event: So
 };
 /** Minimal socket shape required by the session WebSocket adapter. */
 export type Socket = {
+    /** Bytes queued by the runtime but not yet written to the network. */
+    readonly bufferedAmount?: number | undefined;
     close(code?: number, reason?: string): unknown;
     send(data: string): unknown;
     addEventListener?: <type extends keyof SocketEventMap>(type: type, listener: SocketEventListener<type>) => unknown;
@@ -71,6 +70,10 @@ export type Socket = {
     on?: <type extends keyof SocketEventMap>(type: type, listener: (event: SocketEventMap[type]) => void) => unknown;
     off?: <type extends keyof SocketEventMap>(type: type, listener: (event: SocketEventMap[type]) => void) => unknown;
 };
+/** Raised after a socket is closed to keep its outbound queue bounded. */
+export declare class WebSocketOutboundBufferLimitError extends Error {
+    readonly name = "WebSocketOutboundBufferLimitError";
+}
 /** Handlers for socket lifecycle and message events. */
 export type SocketHandlers = {
     /** Called when the socket closes. */
@@ -82,8 +85,10 @@ export type SocketHandlers = {
 };
 /** Subscribes to browser or Node-style socket events and returns an unsubscribe callback. */
 export declare function subscribe(socket: Socket, handlers: SocketHandlers): () => void;
-/** Sends a text frame through sync or async socket implementations. */
-export declare function send(socket: Socket, data: string): Promise<void>;
+/** Sends a text frame while bounding runtime-managed outbound buffering. */
+export declare function send(socket: Socket, data: string, options?: {
+    maxBufferedAmount?: number;
+}): Promise<void>;
 /** Converts socket message payloads into text frames when possible. */
 export declare function toText(value: unknown): string | null;
 //# sourceMappingURL=Transports.d.ts.map

package/dist/tempo/session/server/Transports.js

@@ -1,62 +1,133 @@
 import { ChannelClosedError } from '../../../Errors.js';
-/**
- * Reserves voucher headroom for a future stream emission.
- *
- * If the channel lacks headroom, emits one need-voucher frame, then waits for
- * a store update or polling interval until the accepted voucher covers both
- * already-reserved charges and the next requested amount.
- */
+import * as ChannelStore from './ChannelStore.js';
+/** Lease duration for abandoned stream reservations. Active generators renew it. */
+export const streamReservationLeaseMs = 30_000;
+/** Atomically reserves shared voucher coverage before billable stream work begins. */
 export async function reserveChargeOrWait(options) {
-    const { amount, channelId, emit, formatNeedVoucher, pollIntervalMs, reservedAmount, signal, store, } = options;
-    let channel = await store.getChannel(channelId);
-    if (!channel)
-        throw new Error('channel not found');
-    throwIfChannelClosed(channel);
-    const hasHeadroom = (state) => state.highestVoucherAmount - state.spent - reservedAmount >= amount;
-    if (hasHeadroom(channel))
-        return;
-    await Promise.resolve(emit(formatNeedVoucher({
-        channelId,
-        requiredCumulative: (channel.spent + reservedAmount + amount).toString(),
-        acceptedCumulative: channel.highestVoucherAmount.toString(),
-        deposit: channel.deposit.toString(),
-    })));
-    while (!hasHeadroom(channel)) {
-        await waitForUpdate(store, channelId, pollIntervalMs, signal);
-        channel = await store.getChannel(channelId);
+    const { amount, channelId, emit, formatNeedVoucher, pollIntervalMs, reservationId, signal, store, } = options;
+    if (amount < 0n)
+        throw new Error('stream charge must be non-negative');
+    if (store.atomic === false)
+        throw new Error('stream reservations require an atomic store');
+    let lastRequired;
+    while (true) {
+        throwIfAborted(signal);
+        let channel = await store.getChannel(channelId);
         if (!channel)
             throw new Error('channel not found');
         throwIfChannelClosed(channel);
+        if (options.requireExisting &&
+            (channel.streamReservations?.[reservationId]?.expiresAt ?? 0) <= Date.now())
+            throw new Error('stream reservation was lost');
+        if (channel.highestVoucherAmount - channel.spent - ChannelStore.reservedStreamAmount(channel) >=
+            amount) {
+            let reserved = false;
+            channel = await store.updateChannel(channelId, (current) => {
+                reserved = false;
+                if (!current)
+                    return current;
+                throwIfChannelClosed(current);
+                throwIfAborted(signal);
+                const now = Date.now();
+                const previous = current.streamReservations?.[reservationId];
+                if (options.requireExisting && !previous)
+                    throw new Error('stream reservation was lost');
+                if (previous && previous.expiresAt <= now)
+                    throw new Error('stream reservation expired');
+                if (current.highestVoucherAmount -
+                    current.spent -
+                    ChannelStore.reservedStreamAmount(current) <
+                    amount)
+                    return current;
+                const reservations = Object.fromEntries(Object.entries(current.streamReservations ?? {}).filter(([, item]) => item.expiresAt > now));
+                reserved = true;
+                return {
+                    ...current,
+                    streamReservations: {
+                        ...reservations,
+                        [reservationId]: {
+                            amount: (previous?.amount ?? 0n) + amount,
+                            units: (previous?.units ?? 0) + 1,
+                            expiresAt: now + streamReservationLeaseMs,
+                        },
+                    },
+                };
+            });
+            if (reserved)
+                return;
+            if (!channel)
+                throw new Error('channel not found');
+        }
+        const required = channel.spent + ChannelStore.reservedStreamAmount(channel) + amount;
+        if (required !== lastRequired) {
+            lastRequired = required;
+            await emit(formatNeedVoucher({
+                channelId,
+                requiredCumulative: required.toString(),
+                acceptedCumulative: channel.highestVoucherAmount.toString(),
+                deposit: channel.deposit.toString(),
+            }));
+        }
+        await waitForUpdate(store, channelId, pollIntervalMs, signal);
     }
 }
-/** Atomically commits previously reserved stream charges to channel spend and unit counters. */
+/** Commits only this stream's live reservation, removing it in the same atomic update. */
 export async function commitReservedCharges(options) {
-    const { amount, channelId, store, units } = options;
-    if (amount === 0n || units === 0)
-        return;
+    const { channelId, reservationId, store } = options;
     let committed = false;
     const channel = await store.updateChannel(channelId, (current) => {
+        committed = false;
         if (!current)
-            return null;
-        if (current.finalized)
-            return current;
-        if (current.closeRequestedAt !== 0n)
             return current;
-        if (current.highestVoucherAmount - current.spent < amount)
+        throwIfChannelClosed(current);
+        const reservation = current.streamReservations?.[reservationId];
+        if (!reservation)
             return current;
+        if (reservation.expiresAt <= Date.now())
+            throw new Error('stream reservation expired');
+        if (current.highestVoucherAmount - current.spent < reservation.amount)
+            throw new Error('reserved voucher coverage is no longer available');
+        const { [reservationId]: _, ...remaining } = current.streamReservations;
         committed = true;
         return {
             ...current,
-            spent: current.spent + amount,
-            units: current.units + units,
+            streamReservations: remaining,
+            spent: current.spent + reservation.amount,
+            units: current.units + reservation.units,
         };
     });
     if (!channel)
         throw new Error('channel not found');
-    throwIfChannelClosed(channel);
-    if (!committed)
-        throw new Error('reserved voucher coverage is no longer available');
-    return channel;
+    return committed ? channel : undefined;
+}
+/** Releases only the unused reservation owned by this stream. */
+export async function releaseReservedCharges({ store, channelId, reservationId, }) {
+    await store.updateChannel(channelId, (current) => {
+        if (!current?.streamReservations?.[reservationId])
+            return current;
+        const { [reservationId]: _, ...remaining } = current.streamReservations;
+        return { ...current, streamReservations: remaining };
+    });
+}
+/** Renews a live reservation without reviving an expired or released lease. */
+export async function renewReservedCharges({ store, channelId, reservationId, }) {
+    await store.updateChannel(channelId, (current) => {
+        if (!current)
+            throw new Error('channel not found');
+        throwIfChannelClosed(current);
+        const reservation = current.streamReservations?.[reservationId];
+        if (!reservation)
+            return current;
+        if (reservation.expiresAt <= Date.now())
+            throw new Error('stream reservation expired');
+        return {
+            ...current,
+            streamReservations: {
+                ...current.streamReservations,
+                [reservationId]: { ...reservation, expiresAt: Date.now() + streamReservationLeaseMs },
+            },
+        };
+    });
 }
 /** Throws when a channel can no longer be used for streaming charges. */
 export function throwIfChannelClosed(channel) {
@@ -68,11 +139,19 @@ export function throwIfChannelClosed(channel) {
 async function waitForUpdate(store, channelId, pollIntervalMs, signal) {
     throwIfAborted(signal);
     if (store.waitForUpdate) {
-        await Promise.race([
-            store.waitForUpdate(channelId),
-            sleep(pollIntervalMs, signal),
-            ...(signal ? [onceAborted(signal)] : []),
-        ]);
+        const controller = new AbortController();
+        const onAbort = () => controller.abort(signal?.reason);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        try {
+            await Promise.race([
+                store.waitForUpdate(channelId, controller.signal),
+                sleep(pollIntervalMs, controller.signal),
+            ]);
+        }
+        finally {
+            signal?.removeEventListener('abort', onAbort);
+            controller.abort();
+        }
     }
     else {
         await sleep(pollIntervalMs, signal);
@@ -92,21 +171,14 @@ function sleep(ms, signal) {
         signal?.addEventListener('abort', onAbort, { once: true });
     });
 }
-function onceAborted(signal) {
-    return new Promise((_, reject) => {
-        if (signal.aborted) {
-            reject(signal.reason ?? new Error('aborted'));
-            return;
-        }
-        signal.addEventListener('abort', () => reject(signal.reason ?? new Error('aborted')), {
-            once: true,
-        });
-    });
-}
 function throwIfAborted(signal) {
     if (signal?.aborted)
         throw signal.reason ?? new Error('aborted');
 }
+/** Raised after a socket is closed to keep its outbound queue bounded. */
+export class WebSocketOutboundBufferLimitError extends Error {
+    name = 'WebSocketOutboundBufferLimitError';
+}
 /** Subscribes to browser or Node-style socket events and returns an unsubscribe callback. */
 export function subscribe(socket, handlers) {
     if (socket.addEventListener && socket.removeEventListener) {
@@ -133,9 +205,48 @@ export function subscribe(socket, handlers) {
     }
     throw new Error('unsupported websocket implementation');
 }
-/** Sends a text frame through sync or async socket implementations. */
-export async function send(socket, data) {
-    await Promise.resolve(socket.send(data));
+const socketSendQueues = new WeakMap();
+/** Sends a text frame while bounding runtime-managed outbound buffering. */
+export async function send(socket, data, options = {}) {
+    const previous = socketSendQueues.get(socket) ?? Promise.resolve();
+    const current = previous
+        .catch(() => { })
+        .then(async () => {
+        const maxBufferedAmount = options.maxBufferedAmount ?? 1024 * 1024;
+        if ((socket.bufferedAmount ?? 0) + textByteLength(data) > maxBufferedAmount) {
+            try {
+                await Promise.resolve(socket.close(4008, 'outbound buffer limit exceeded'));
+            }
+            catch { }
+            throw new WebSocketOutboundBufferLimitError('websocket outbound buffer limit exceeded');
+        }
+        await Promise.resolve(socket.send(data));
+    });
+    socketSendQueues.set(socket, current);
+    try {
+        await current;
+    }
+    finally {
+        if (socketSendQueues.get(socket) === current)
+            socketSendQueues.delete(socket);
+    }
+}
+function textByteLength(value) {
+    let bytes = 0;
+    for (let index = 0; index < value.length; index++) {
+        const codePoint = value.codePointAt(index);
+        if (codePoint <= 0x7f)
+            bytes += 1;
+        else if (codePoint <= 0x7ff)
+            bytes += 2;
+        else if (codePoint <= 0xffff)
+            bytes += 3;
+        else {
+            bytes += 4;
+            index += 1;
+        }
+    }
+    return bytes;
 }
 /** Converts socket message payloads into text frames when possible. */
 export function toText(value) {

package/dist/tempo/session/server/Ws.d.ts

@@ -12,7 +12,7 @@ export type SessionRouteResult = {
     challenge: Response;
 } | {
     status: 200;
-    withReceipt(response?: Response): Response;
+    withReceipt(response?: Response): Response | Promise<Response>;
 };
 /** HTTP route used to perform a WebSocket payment probe. */
 export type SessionRoute = (request: Request) => Promise<SessionRouteResult>;
@@ -39,6 +39,10 @@ export declare namespace serve {
         /** Application stream. A manual stream can call `charge(amount)` with a
          *  per-message raw-unit amount; omitting it uses the challenge tick cost. */
         generate: AsyncIterable<string> | ((stream: SessionController) => AsyncIterable<string>);
+        /** Maximum accepted inbound WebSocket frame size in bytes. @default 65536 */
+        maxIncomingMessageBytes?: number | undefined;
+        /** Maximum queued outbound bytes before the socket is closed. @default 1048576 */
+        maxBufferedAmount?: number | undefined;
         pollIntervalMs?: number | undefined;
         /** Payment route handler. Receives synthetic `POST` requests with only
          *  the `Authorization` header — no cookies, bodies, or upgrade headers. */