starpc 0.52.0 → 0.52.1

package/dist/rpcstream/rpcstream.js

@@ -1,4 +1,5 @@
 import { pushable } from 'it-pushable';
+import { closeIterator, sourceIterator, TerminationGate, } from '../srpc/termination.js';
 // openRpcStream attempts to open a stream over a RPC call.
 // if waitAck is set, waits for the remote to ack the stream before returning.
 export async function openRpcStream(componentId, caller, waitAck) {
@@ -33,7 +34,7 @@ export async function openRpcStream(componentId, caller, waitAck) {
         }
     }
     // build & return the data stream
-    return new RpcStream(packetTx, packetIt);
+    return new RpcStream(packetTx, packetIt, () => closeIterator(packetIt));
 }
 // buildRpcStreamOpenStream builds a OpenStream func with a RpcStream.
 export function buildRpcStreamOpenStream(componentId, caller) {
@@ -87,7 +88,7 @@ export async function* handleRpcStream(packetRx, getter) {
     // build the outgoing packet sink & the packet source
     const packetTx = pushable({ objectMode: true });
     // start the handler
-    const rpcStream = new RpcStream(packetTx, packetRx);
+    const rpcStream = new RpcStream(packetTx, packetRx, () => closeIterator(packetRx));
     handler(rpcStream)
         .catch((err) => packetTx.end(err))
         .then(() => packetTx.end());
@@ -107,54 +108,100 @@ export class RpcStream {
     _packetRx;
     // _packetTx writes packets to the remote.
     _packetTx;
+    _termination = new TerminationGate();
+    _cancelRpc;
     // packetTx writes packets to the remote.
     // packetRx receives packets from the remote.
-    constructor(packetTx, packetRx) {
+    constructor(packetTx, packetRx, cancelRpc = () => closeIterator(packetRx)) {
         this._packetTx = packetTx;
         this._packetRx = packetRx;
+        this._cancelRpc = cancelRpc;
         this.sink = this._createSink();
         this.source = this._createSource();
     }
+    // close cleanly ends both directions of the stream.
+    async close() {
+        if (this._termination.terminate()) {
+            this._packetTx.end();
+            this._cancelRpc();
+        }
+    }
+    // abort ends both directions of the stream with err.
+    abort(err) {
+        if (this._termination.terminate(err)) {
+            this._packetTx.end(err);
+            this._cancelRpc();
+        }
+    }
     // _createSink initializes the sink field.
     _createSink() {
         return async (source) => {
+            const iterator = sourceIterator(source);
             try {
-                for await (const arr of source) {
+                while (true) {
+                    const next = await this._termination.next(iterator);
+                    if ('terminated' in next) {
+                        if (next.error)
+                            throw next.error;
+                        return;
+                    }
+                    if ('error' in next)
+                        throw next.error;
+                    if (next.result.done) {
+                        this._packetTx.end();
+                        return;
+                    }
+                    if (this._termination.terminated)
+                        return;
                     this._packetTx.push({
-                        body: { case: 'data', value: arr },
+                        body: { case: 'data', value: next.result.value },
                     });
                 }
-                this._packetTx.end();
             }
             catch (err) {
-                this._packetTx.end(err);
+                const error = err instanceof Error ? err : new Error(String(err));
+                this.abort(error);
+                throw error;
+            }
+            finally {
+                closeIterator(iterator);
             }
         };
     }
     // _createSource initializes the source field.
     _createSource() {
-        return (async function* (packetRx) {
-            while (true) {
-                const msgIt = await packetRx.next();
-                if (msgIt.done) {
-                    return;
-                }
-                const value = msgIt.value;
-                const body = value?.body;
-                if (!body) {
-                    continue;
-                }
-                switch (body.case) {
-                    case 'ack':
-                        if (body.value.error?.length) {
-                            throw new Error(body.value.error);
-                        }
-                        break;
-                    case 'data':
-                        yield body.value;
-                        break;
+        const packetRx = this._packetRx;
+        const termination = this._termination;
+        return (async function* () {
+            try {
+                while (true) {
+                    const next = await termination.next(packetRx);
+                    if ('terminated' in next) {
+                        if (next.error)
+                            throw next.error;
+                        return;
+                    }
+                    if ('error' in next)
+                        throw next.error;
+                    if (next.result.done)
+                        return;
+                    const body = next.result.value?.body;
+                    if (!body)
+                        continue;
+                    switch (body.case) {
+                        case 'ack':
+                            if (body.value.error?.length)
+                                throw new Error(body.value.error);
+                            break;
+                        case 'data':
+                            yield body.value;
+                            break;
+                    }
                 }
             }
-        })(this._packetRx);
+            finally {
+                closeIterator(packetRx);
+            }
+        })();
     }
 }

package/dist/rpcstream/rpcstream.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/rpcstream/rpcstream.test.js

@@ -0,0 +1,92 @@
+import { describe, expect, it, vi } from 'vitest';
+import { pushable } from 'it-pushable';
+import { RpcStream } from './rpcstream.js';
+describe('RpcStream lifecycle', () => {
+    it('closes while its source is blocked', async () => {
+        const tx = pushable({ objectMode: true });
+        const rx = pushable({ objectMode: true });
+        const stream = new RpcStream(tx, rx[Symbol.asyncIterator]());
+        const pending = stream.source.next();
+        await stream.close();
+        await expect(pending).resolves.toEqual({ done: true, value: undefined });
+        await expect(tx.next()).resolves.toEqual({ done: true, value: undefined });
+    });
+    it('aborts while its source is blocked', async () => {
+        const tx = pushable({ objectMode: true });
+        const rx = pushable({ objectMode: true });
+        const stream = new RpcStream(tx, rx[Symbol.asyncIterator]());
+        const pending = stream.source.next();
+        const error = new Error('stopped');
+        stream.abort(error);
+        await expect(pending).rejects.toBe(error);
+        await expect(tx.next()).rejects.toBe(error);
+    });
+    it('closes while its sink source is blocked', async () => {
+        const tx = pushable({ objectMode: true });
+        const rx = pushable({ objectMode: true });
+        const input = pushable({ objectMode: true });
+        const stream = new RpcStream(tx, rx[Symbol.asyncIterator]());
+        const pending = stream.sink(input);
+        await stream.close();
+        await expect(pending).resolves.toBeUndefined();
+        await expect(tx.next()).resolves.toEqual({ done: true, value: undefined });
+    });
+    it('aborts while its sink source is blocked', async () => {
+        const tx = pushable({ objectMode: true });
+        const rx = pushable({ objectMode: true });
+        const input = pushable({ objectMode: true });
+        const stream = new RpcStream(tx, rx[Symbol.asyncIterator]());
+        const pending = stream.sink(input);
+        const error = new Error('stopped');
+        stream.abort(error);
+        await expect(pending).rejects.toBe(error);
+        await expect(tx.next()).rejects.toBe(error);
+    });
+    it('does not write input that becomes ready as the stream closes', async () => {
+        const tx = pushable({ objectMode: true });
+        const rx = pushable({ objectMode: true });
+        const input = pushable({ objectMode: true });
+        const stream = new RpcStream(tx, rx[Symbol.asyncIterator]());
+        input.push(new Uint8Array([1]));
+        const pending = stream.sink(input);
+        await stream.close();
+        await expect(pending).resolves.toBeUndefined();
+        await expect(tx.next()).resolves.toEqual({ done: true, value: undefined });
+    });
+    it('does not close when its sink completes', async () => {
+        const tx = pushable({ objectMode: true });
+        const rx = pushable({ objectMode: true });
+        const stream = new RpcStream(tx, rx[Symbol.asyncIterator]());
+        await stream.sink((async function* () { })());
+        rx.push({ body: { case: 'data', value: new Uint8Array([1]) } });
+        await expect(stream.source.next()).resolves.toMatchObject({ done: false });
+    });
+    it('finalizes a sink input iterator when closed', async () => {
+        const tx = pushable({ objectMode: true });
+        const rx = pushable({ objectMode: true });
+        const returned = vi.fn(() => Promise.resolve({ done: true, value: undefined }));
+        const input = {
+            [Symbol.asyncIterator]: () => ({
+                next: () => new Promise(() => { }),
+                return: returned,
+            }),
+        };
+        const stream = new RpcStream(tx, rx[Symbol.asyncIterator]());
+        const pending = stream.sink(input);
+        await stream.close();
+        await pending;
+        expect(returned).toHaveBeenCalledOnce();
+    });
+    it('cancels the outer RPC when aborted after sink completion', async () => {
+        const tx = pushable({ objectMode: true });
+        const returned = vi.fn(() => Promise.resolve({ done: true, value: undefined }));
+        const rx = {
+            next: () => new Promise(() => { }),
+            return: returned,
+        };
+        const stream = new RpcStream(tx, rx);
+        await stream.sink((async function* () { })());
+        stream.abort(new Error('stopped'));
+        expect(returned).toHaveBeenCalledOnce();
+    });
+});

package/dist/srpc/client.js

@@ -82,13 +82,27 @@ export class Client {
         const stream = await openStreamFn();
         const call = new ClientRPC(rpcService, rpcMethod);
         const onAbort = () => {
+            if (call.isClosed)
+                return;
+            const error = new Error(ERR_RPC_ABORT);
             void call.writeCallCancel().catch(() => undefined);
-            void call.close(new Error(ERR_RPC_ABORT)).catch(() => undefined);
+            stream.abort(error);
+            void call.close(error).catch(() => undefined);
         };
         abortSignal?.addEventListener('abort', onAbort, { once: true });
-        pipe(stream, decodePacketSource, call, encodePacketSource, stream)
-            .catch((err) => call.close(err))
-            .then(() => call.close())
+        void pipe(stream, decodePacketSource, call, encodePacketSource, stream)
+            .then(async () => {
+            if (call.isClosed instanceof Error) {
+                stream.abort(call.isClosed);
+                return;
+            }
+            await stream.close();
+            await call.close();
+        }, async (err) => {
+            const error = err instanceof Error ? err : new Error(String(err));
+            stream.abort(error);
+            await call.close(error);
+        })
             .finally(() => {
             abortSignal?.removeEventListener('abort', onAbort);
         });

package/dist/srpc/common-rpc.test.js

@@ -101,6 +101,8 @@ describe('CommonRPC', () => {
         const responseGate = deferred();
         const response = new Uint8Array([7]);
         const client = new Client(async () => ({
+            close: async () => { },
+            abort: () => { },
             source: (async function* () {
                 await responseGate.promise;
                 yield Packet.toBinary({

package/dist/srpc/packet-codec.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/srpc/packet-codec.test.js

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest';
+import vectors from '../testdata/packet-codec-vectors.json';
+import { Packet } from './rpcproto.pb.js';
+import { decodePacketSource, encodePacketSource, lengthPrefixDecode, prependLengthPrefixTransform, uint32LEDecode, } from './packet.js';
+const bytes = (hex) => Uint8Array.from(hex.match(/../g) ?? [], (b) => parseInt(b, 16));
+const hex = (data) => Buffer.from(data.subarray()).toString('hex');
+const collect = async (source) => {
+    const out = [];
+    for await (const value of source)
+        out.push(value);
+    return out;
+};
+const validCases = vectors.cases.filter((entry) => Boolean(entry.packet_hex && entry.frame_hex));
+describe('packet codec golden vectors', () => {
+    it.each(validCases)('$name has exact protobuf and frame bytes', async (entry) => {
+        const packet = Packet.fromBinary(bytes(entry.packet_hex));
+        const encoded = (await collect(encodePacketSource((async function* () {
+            yield packet;
+        })())))[0];
+        expect(hex(encoded)).toBe(entry.packet_hex);
+        const framed = (await collect(prependLengthPrefixTransform()((async function* () {
+            yield encoded;
+        })())))[0];
+        expect(hex(framed)).toBe(entry.frame_hex);
+    });
+    it('rejects zero and oversized encoded chunks', async () => {
+        const zero = (async function* () {
+            yield new Uint8Array();
+        })();
+        await expect(collect(prependLengthPrefixTransform()(zero))).rejects.toThrow('invalid packet length');
+        const oversized = (async function* () {
+            yield new Uint8Array(10_000_001);
+        })();
+        await expect(collect(prependLengthPrefixTransform()(oversized))).rejects.toThrow('invalid packet length');
+    });
+    it('rejects zero and oversized lengths, and truncated bodies', async () => {
+        const zero = (async function* () {
+            yield bytes('00000000');
+        })();
+        await expect(collect(lengthPrefixDecode(zero, uint32LEDecode))).rejects.toThrow('invalid packet length');
+        const oversized = (async function* () {
+            yield bytes('81969800');
+        })();
+        await expect(collect(lengthPrefixDecode(oversized, uint32LEDecode))).rejects.toThrow('invalid packet length');
+        const truncated = (async function* () {
+            yield bytes('040000000a01');
+        })();
+        await expect(collect(lengthPrefixDecode(truncated, uint32LEDecode))).rejects.toThrow('truncated packet frame');
+    });
+    it('decodes fragmented and coalesced frames', async () => {
+        const frames = validCases.map((entry) => bytes(entry.frame_hex));
+        const combined = new Uint8Array(frames.reduce((n, frame) => n + frame.length, 0));
+        let offset = 0;
+        for (const frame of frames) {
+            combined.set(frame, offset);
+            offset += frame.length;
+        }
+        const payloads = await collect(lengthPrefixDecode((async function* () {
+            yield combined.subarray(0, 3);
+            yield combined.subarray(3, 11);
+            yield combined.subarray(11);
+        })(), uint32LEDecode));
+        expect(payloads.map(hex)).toEqual(validCases.map((entry) => entry.packet_hex));
+        const decoded = await collect(decodePacketSource(payloads.map((payload) => payload.slice())));
+        expect(decoded).toHaveLength(validCases.length);
+    });
+    it('rejects malformed protobuf and incomplete frame prefix', async () => {
+        const malformed = vectors.cases.find((entry) => entry.name === 'malformed_complete');
+        expect(() => Packet.fromBinary(bytes(malformed.frame_hex.slice(8)))).toThrow();
+        const incomplete = (async function* () {
+            yield bytes('010203');
+        })();
+        await expect(collect(lengthPrefixDecode(incomplete, uint32LEDecode))).rejects.toThrow('truncated packet frame');
+    });
+});

package/dist/srpc/packet.d.ts

@@ -12,7 +12,7 @@ export declare namespace uint32LEEncode {
     var bytes: number;
 }
 export declare function lengthPrefixEncode(source: Source<Uint8Array | Uint8ArrayList>, lengthEncoder: typeof uint32LEEncode): AsyncGenerator<Uint8ArrayList<ArrayBufferLike>, void, unknown>;
-export declare function lengthPrefixDecode(source: Source<Uint8Array | Uint8ArrayList>, lengthDecoder: typeof uint32LEDecode): AsyncGenerator<Uint8ArrayList<ArrayBufferLike>, void, unknown>;
+export declare function lengthPrefixDecode(source: Source<Uint8Array | Uint8ArrayList>, lengthDecoder: typeof uint32LEDecode): AsyncGenerator<Uint8ArrayList>;
 export declare function prependLengthPrefixTransform(lengthEncoder?: {
     (value: number): Uint8ArrayList<ArrayBuffer>;
     bytes: number;

package/dist/srpc/packet.js

@@ -1,6 +1,7 @@
 import { Uint8ArrayList } from 'uint8arraylist';
 import { Packet } from './rpcproto.pb.js';
 import { buildDecodeMessageTransform, buildEncodeMessageTransform, } from './message.js';
+const MAX_MESSAGE_SIZE = 10_000_000;
 // decodePacketSource decodes packets from a binary data stream.
 export const decodePacketSource = buildDecodeMessageTransform(Packet);
 // encodePacketSource encodes packets from a packet object stream.
@@ -25,6 +26,9 @@ export async function* lengthPrefixEncode(source, lengthEncoder) {
     for await (const chunk of source) {
         // Encode the length of the chunk.
         const length = chunk instanceof Uint8Array ? chunk.length : chunk.byteLength;
+        if (length === 0 || length > MAX_MESSAGE_SIZE) {
+            throw RangeError(`invalid packet length: ${length}`);
+        }
         const lengthEncoded = lengthEncoder(length);
         // Concatenate the length prefix and the data.
         yield new Uint8ArrayList(lengthEncoded, chunk);
@@ -38,16 +42,22 @@ export async function* lengthPrefixDecode(source, lengthDecoder) {
         // Continue extracting messages while buffer contains enough data for decoding.
         while (buffer.length >= lengthDecoder.bytes) {
             const messageLength = lengthDecoder(buffer);
+            if (messageLength === 0 || messageLength > MAX_MESSAGE_SIZE) {
+                throw RangeError(`invalid packet length: ${messageLength}`);
+            }
             const totalLength = lengthDecoder.bytes + messageLength;
             if (buffer.length < totalLength)
                 break; // Wait for more data if the full message hasn't arrived.
             // Extract the message excluding the length prefix.
-            const message = buffer.sublist(lengthDecoder.bytes, totalLength);
+            const message = new Uint8ArrayList(buffer.slice(lengthDecoder.bytes, totalLength));
             yield message;
             // Remove the processed message from the buffer.
             buffer.consume(totalLength);
         }
     }
+    if (buffer.length !== 0) {
+        throw new RangeError('truncated packet frame');
+    }
 }
 // prependLengthPrefixTransform adds a length prefix to a message source.
 // little-endian uint32

package/dist/srpc/server.js

@@ -13,9 +13,7 @@ export class Server {
     get rpcStreamHandler() {
         return async (stream) => {
             const rpc = this.startRpc();
-            return pipe(stream, decodePacketSource, rpc, encodePacketSource, stream)
-                .catch((err) => rpc.close(err))
-                .then(() => rpc.close());
+            return runPacketStream(stream, rpc);
         };
     }
     // startRpc starts a new server-side RPC.
@@ -27,9 +25,24 @@ export class Server {
     // the stream has one Uint8Array per packet w/o length prefix.
     handlePacketStream(stream) {
         const rpc = this.startRpc();
-        pipe(stream, decodePacketSource, rpc, encodePacketSource, stream)
-            .catch((err) => rpc.close(err))
-            .then(() => rpc.close());
+        void runPacketStream(stream, rpc).catch(() => undefined);
         return rpc;
     }
 }
+async function runPacketStream(stream, rpc) {
+    try {
+        await pipe(stream, decodePacketSource, rpc, encodePacketSource, stream);
+        if (rpc.isClosed instanceof Error) {
+            stream.abort(rpc.isClosed);
+            throw rpc.isClosed;
+        }
+        await stream.close();
+        await rpc.close();
+    }
+    catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        stream.abort(error);
+        await rpc.close(error);
+        throw error;
+    }
+}

package/dist/srpc/server.test.js

@@ -1,5 +1,6 @@
 import { describe, it, beforeEach, expect, vi } from 'vitest';
 import { pipe } from 'it-pipe';
+import { pushable } from 'it-pushable';
 import { createHandler, createMux, Server, Client, StreamConn, ChannelStream, combineUint8ArrayListTransform, Packet, createContextKey, serverContextValue, withServerContextValue, } from '../srpc/index.js';
 import { EchoerDefinition, EchoerServer, EchoerServiceName, EchoMsg, runClientTest, } from '../echo/index.js';
 import { runAbortControllerTest, runRpcStreamTest, } from '../echo/client-test.js';
@@ -112,6 +113,8 @@ describe('srpc server', () => {
         const server = new Server(mux.lookupMethod);
         const firstResponse = new Promise((resolve, reject) => {
             server.handlePacketStream({
+                close: async () => { },
+                abort: () => { },
                 source: (async function* () {
                     yield Packet.toBinary({
                         body: {
@@ -229,6 +232,46 @@ describe('srpc server', () => {
         controller.abort();
         await Promise.resolve();
     });
+    it('closes the packet stream when the server pipeline completes', async () => {
+        const server = new Server(createMux().lookupMethod);
+        const close = vi.fn(async () => { });
+        const source = pushable({ objectMode: true });
+        const stream = {
+            close,
+            abort: vi.fn(),
+            source,
+            sink: async (output) => {
+                for await (const _packet of output) {
+                    // Drain the response pipeline.
+                }
+            },
+        };
+        const rpc = server.handlePacketStream(stream);
+        await rpc.close();
+        source.end();
+        await vi.waitFor(() => expect(close).toHaveBeenCalledOnce());
+        expect(stream.abort).not.toHaveBeenCalled();
+    });
+    it('aborts the packet stream when the server pipeline fails', async () => {
+        const server = new Server(createMux().lookupMethod);
+        const error = new Error('input failed');
+        const abort = vi.fn();
+        const source = pushable({ objectMode: true });
+        const stream = {
+            close: vi.fn(async () => { }),
+            abort,
+            source,
+            sink: async (output) => {
+                for await (const _packet of output) {
+                    // Drain the response pipeline.
+                }
+            },
+        };
+        server.handlePacketStream(stream);
+        source.end(error);
+        await vi.waitFor(() => expect(abort).toHaveBeenCalledWith(error));
+        expect(stream.close).not.toHaveBeenCalled();
+    });
     it('tears down passive channel close state', async () => {
         const { port1, port2 } = new MessageChannel();
         const opts = { idleTimeoutMs: 1000, keepAliveMs: 1000 };

package/dist/srpc/stream.d.ts

@@ -2,7 +2,10 @@ import type { Duplex, Source } from 'it-stream-types';
 import type { Stream } from './stream-muxer.js';
 import type { Packet } from './rpcproto.pb.js';
 export type PacketHandler = (packet: Packet) => Promise<void>;
-export type PacketStream = Duplex<AsyncGenerator<Uint8Array>, Source<Uint8Array>, Promise<void>>;
+export interface PacketStream extends Duplex<AsyncGenerator<Uint8Array>, Source<Uint8Array>, Promise<void>> {
+    close(): Promise<void>;
+    abort(err: Error): void;
+}
 export type OpenStreamFunc = () => Promise<PacketStream>;
 export type HandleStreamFunc = (ch: PacketStream) => Promise<void>;
 export declare function streamToPacketStream(stream: Stream): PacketStream;

package/dist/srpc/stream.js

@@ -1,20 +1,79 @@
 import { pipe } from 'it-pipe';
 import { combineUint8ArrayListTransform } from './array-list.js';
 import { parseLengthPrefixTransform, prependLengthPrefixTransform, } from './packet.js';
+import { closeIterator, sourceIterator, TerminationGate, } from './termination.js';
 // streamToPacketStream converts a Stream into a PacketStream using length-prefix framing.
 export function streamToPacketStream(stream) {
+    const termination = new TerminationGate();
     return {
-        source: pipe(stream, parseLengthPrefixTransform(), combineUint8ArrayListTransform()),
+        close: async () => {
+            if (termination.terminate())
+                await stream.close();
+        },
+        abort: (err) => {
+            if (termination.terminate(err))
+                stream.abort(err);
+        },
+        source: (async function* () {
+            const packets = pipe(stream, parseLengthPrefixTransform(), combineUint8ArrayListTransform())[Symbol.asyncIterator]();
+            try {
+                while (true) {
+                    const next = await termination.next(packets);
+                    if ('terminated' in next) {
+                        if (next.error)
+                            throw next.error;
+                        return;
+                    }
+                    if ('error' in next)
+                        throw next.error;
+                    if (next.result.done)
+                        return;
+                    yield next.result.value;
+                }
+            }
+            finally {
+                closeIterator(packets);
+            }
+        })(),
         sink: async (source) => {
+            const iterator = sourceIterator(pipe(source, prependLengthPrefixTransform()));
+            const gatedSource = (async function* () {
+                while (true) {
+                    const next = await termination.next(iterator);
+                    if ('terminated' in next) {
+                        if (next.error)
+                            throw next.error;
+                        return;
+                    }
+                    if ('error' in next)
+                        throw next.error;
+                    if (next.result.done)
+                        return;
+                    if (termination.terminated)
+                        return;
+                    yield next.result.value;
+                }
+            })();
             try {
-                await pipe(source, prependLengthPrefixTransform(), stream);
+                const result = await termination.wait(stream.sink(gatedSource));
+                if ('terminated' in result) {
+                    if (result.error)
+                        throw result.error;
+                    return;
+                }
+                if ('error' in result)
+                    throw result.error;
                 await stream.closeWrite();
             }
             catch (err) {
                 const error = err instanceof Error ? err : new Error(String(err));
-                stream.abort(error);
+                if (termination.terminate(error))
+                    stream.abort(error);
                 throw error;
             }
+            finally {
+                closeIterator(iterator);
+            }
         },
     };
 }