starpc 0.51.0 → 0.52.1

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-context.d.ts

@@ -0,0 +1,11 @@
+declare const contextKeyValue: unique symbol;
+export interface ContextKey<T> {
+    readonly [contextKeyValue]?: T;
+}
+export interface ServerContext {
+    readonly signal: AbortSignal;
+}
+export declare function createContextKey<T>(): ContextKey<T>;
+export declare function withServerContextValue<T>(context: ServerContext, key: ContextKey<T>, value: T): ServerContext;
+export declare function serverContextValue<T>(context: ServerContext, key: ContextKey<T>): T | undefined;
+export {};

package/dist/srpc/server-context.js

@@ -0,0 +1,28 @@
+const contextParent = Symbol('server context parent');
+const contextKey = Symbol('server context key');
+const contextStoredValue = Symbol('server context value');
+// createContextKey constructs an identity key for one server-context value.
+export function createContextKey() {
+    return {};
+}
+// withServerContextValue derives a context with one immutable typed value.
+export function withServerContextValue(context, key, value) {
+    const derived = {
+        signal: context.signal,
+        [contextParent]: context,
+        [contextKey]: key,
+        [contextStoredValue]: value,
+    };
+    return derived;
+}
+// serverContextValue retrieves the nearest value for a typed identity key.
+export function serverContextValue(context, key) {
+    let current = context;
+    while (current) {
+        if (current[contextKey] === key) {
+            return current[contextStoredValue];
+        }
+        current = current[contextParent];
+    }
+    return undefined;
+}

package/dist/srpc/server-rpc.js

@@ -38,7 +38,9 @@ export class ServerRPC extends CommonRPC {
     async invokeRPC(invokeFn) {
         const dataSink = this._createDataSink();
         try {
-            await invokeFn(this.rpcDataSource, dataSink, this.invocationSignal);
+            await invokeFn(this.rpcDataSource, dataSink, {
+                signal: this.invocationSignal,
+            });
         }
         catch (err) {
             this.close(err);

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,6 +1,7 @@
 import { describe, it, beforeEach, expect, vi } from 'vitest';
 import { pipe } from 'it-pipe';
-import { createHandler, createMux, Server, Client, StreamConn, ChannelStream, combineUint8ArrayListTransform, Packet, } from '../srpc/index.js';
+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';
 describe('srpc server', () => {
@@ -39,12 +40,17 @@ describe('srpc server', () => {
     it('should pass rpc stream tests', async () => {
         await runRpcStreamTest(client);
     });
-    it('passes the exact invocation signal after async request decode', async () => {
+    it('passes the exact invocation context after async request decode', async () => {
         const controller = new AbortController();
-        let observedSignal;
+        const callerKey = createContextKey();
+        let observedAbortSignal;
+        let observedContextSignal;
+        let observedCaller;
         const handler = createHandler(EchoerDefinition, {
-            Echo: async (request, signal) => {
-                observedSignal = signal;
+            Echo: async (request, abortSignal, context) => {
+                observedAbortSignal = abortSignal;
+                observedContextSignal = context.signal;
+                observedCaller = serverContextValue(context, callerKey);
                 return request;
             },
         });
@@ -62,8 +68,32 @@ describe('srpc server', () => {
                 // Drain the encoded response so the invocation pipeline completes.
             }
             drained.resolve();
-        }, controller.signal);
+        }, withServerContextValue({ signal: controller.signal }, callerKey, 'caller-1'));
         await drained.promise;
+        expect(observedAbortSignal).toBe(controller.signal);
+        expect(observedContextSignal).toBe(controller.signal);
+        expect(observedCaller).toBe('caller-1');
+    });
+    it('keeps two-argument server handlers compatible', async () => {
+        const controller = new AbortController();
+        let observedSignal;
+        const handler = createHandler(EchoerDefinition, {
+            Echo: async (request, abortSignal) => {
+                observedSignal = abortSignal;
+                return request;
+            },
+        });
+        const invokeFn = await handler.lookupMethod(EchoerServiceName, 'Echo');
+        if (!invokeFn)
+            throw new Error('Echo method was not found');
+        const request = EchoMsg.create({ body: 'legacy handler' });
+        await invokeFn((async function* () {
+            yield EchoMsg.toBinary(request);
+        })(), async (source) => {
+            for await (const _data of source) {
+                // Drain the response.
+            }
+        }, { signal: controller.signal });
         expect(observedSignal).toBe(controller.signal);
     });
     it('keeps detached server-streaming responses open after request source completes', async () => {
@@ -83,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: {
@@ -200,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);
+            }
         },
     };
 }

package/dist/srpc/stream.test.js

@@ -1,5 +1,7 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { pipe } from 'it-pipe';
+import { pushable } from 'it-pushable';
+import { streamToPacketStream } from './stream.js';
 import { ChannelStream, combineUint8ArrayListTransform, StreamConn, } from '../srpc/index.js';
 describe('StreamConn packet stream', () => {
     it('keeps yamux peer writes open after local packet source completes normally', async () => {
@@ -48,6 +50,113 @@ describe('StreamConn packet stream', () => {
         await serverDone;
         expect(serverError).toBeUndefined();
     });
+    it('settles a blocked packet source when closed', async () => {
+        const { clientConn, cleanup } = connectStreamConns({
+            handlePacketStream() { },
+        });
+        try {
+            const stream = await clientConn.openStream();
+            const pending = stream.source.next();
+            await stream.close();
+            await expect(pending).resolves.toEqual({ done: true, value: undefined });
+        }
+        finally {
+            cleanup();
+        }
+    });
+    it('settles a blocked packet source when aborted', async () => {
+        const { clientConn, cleanup } = connectStreamConns({
+            handlePacketStream() { },
+        });
+        try {
+            const stream = await clientConn.openStream();
+            const pending = stream.source.next();
+            const error = new Error('stopped');
+            stream.abort(error);
+            await expect(pending).rejects.toBe(error);
+        }
+        finally {
+            cleanup();
+        }
+    });
+    it('settles a blocked packet sink when closed', async () => {
+        const { clientConn, cleanup } = connectStreamConns({
+            handlePacketStream() { },
+        });
+        try {
+            const stream = await clientConn.openStream();
+            const input = pushable({ objectMode: true });
+            const pending = stream.sink(input);
+            await stream.close();
+            await expect(pending).resolves.toBeUndefined();
+        }
+        finally {
+            cleanup();
+        }
+    });
+    it('settles a packet sink blocked in the underlying write', async () => {
+        const sinkStarted = Promise.withResolvers();
+        const transport = {
+            source: (async function* () { })(),
+            sink: async (source) => {
+                for await (const _chunk of source) {
+                    sinkStarted.resolve();
+                    await new Promise(() => { });
+                }
+            },
+            close: vi.fn(async () => { }),
+            closeRead: vi.fn(async () => { }),
+            closeWrite: vi.fn(async () => { }),
+            abort: vi.fn(),
+        };
+        const stream = streamToPacketStream(transport);
+        const input = pushable({ objectMode: true });
+        input.push(new Uint8Array([1]));
+        const pending = stream.sink(input);
+        await sinkStarted.promise;
+        await stream.close();
+        await expect(pending).resolves.toBeUndefined();
+    });
+    it('rejects a blocked packet sink with the abort error', async () => {
+        const { clientConn, cleanup } = connectStreamConns({
+            handlePacketStream() { },
+        });
+        try {
+            const stream = await clientConn.openStream();
+            const input = pushable({ objectMode: true });
+            const pending = stream.sink(input);
+            const error = new Error('stopped');
+            stream.abort(error);
+            await expect(pending).rejects.toBe(error);
+        }
+        finally {
+            cleanup();
+        }
+    });
+    it('does not write ready input after close', async () => {
+        const serverStream = Promise.withResolvers();
+        const { clientConn, cleanup } = connectStreamConns({
+            handlePacketStream(stream) {
+                serverStream.resolve(stream);
+            },
+        });
+        try {
+            const stream = await clientConn.openStream();
+            const peer = await serverStream.promise;
+            const input = pushable({ objectMode: true });
+            input.push(new Uint8Array([1]));
+            const pending = stream.sink(input);
+            await stream.close();
+            await expect(pending).resolves.toBeUndefined();
+            await expect(nextWithTimeout(peer.source, 'server eof')).resolves.toEqual({
+                done: true,
+                value: undefined,
+            });
+        }
+        finally {
+            cleanup();
+        }
+    });
     it('aborts the yamux stream when the packet source errors', async () => {
         const request = new TextEncoder().encode('request');
         const sourceError = new Error('source failed');

package/dist/srpc/termination.d.ts

@@ -0,0 +1,27 @@
+import type { Source } from 'it-stream-types';
+type Terminated = {
+    terminated: true;
+    error?: Error;
+};
+type Received<T> = {
+    result: IteratorResult<T>;
+} | {
+    error: unknown;
+};
+type WaitResult<T> = {
+    result: T;
+} | {
+    error: unknown;
+};
+export declare class TerminationGate {
+    private readonly _waiters;
+    private _error;
+    private _terminated;
+    get terminated(): boolean;
+    terminate(error?: Error): boolean;
+    wait<T>(promise: Promise<T>): Promise<WaitResult<T> | Terminated>;
+    next<T>(iterator: AsyncIterator<T>): Promise<Received<T> | Terminated>;
+}
+export declare function sourceIterator<T>(source: Source<T>): AsyncIterator<T>;
+export declare function closeIterator<T>(iterator: AsyncIterator<T>): void;
+export {};

package/dist/srpc/termination.js

@@ -0,0 +1,56 @@
+// TerminationGate makes the first clean close or abort visible to blocked I/O.
+export class TerminationGate {
+    _waiters = new Set();
+    _error;
+    _terminated = false;
+    get terminated() {
+        return this._terminated;
+    }
+    terminate(error) {
+        if (this._terminated)
+            return false;
+        this._terminated = true;
+        this._error = error;
+        for (const waiter of this._waiters)
+            waiter(error);
+        this._waiters.clear();
+        return true;
+    }
+    async wait(promise) {
+        if (this._terminated)
+            return { terminated: true, error: this._error };
+        let notify;
+        const terminated = new Promise((resolve) => {
+            notify = (error) => resolve({ terminated: true, error });
+            this._waiters.add(notify);
+        });
+        const received = promise.then((result) => ({ result }), (error) => ({ error }));
+        try {
+            const result = await Promise.race([received, terminated]);
+            if (this._terminated) {
+                return { terminated: true, error: this._error };
+            }
+            return result;
+        }
+        finally {
+            this._waiters.delete(notify);
+        }
+    }
+    next(iterator) {
+        return this.wait(iterator.next());
+    }
+}
+export function sourceIterator(source) {
+    if (Symbol.asyncIterator in source)
+        return source[Symbol.asyncIterator]();
+    const iterator = source[Symbol.iterator]();
+    return { next: async () => iterator.next() };
+}
+// closeIterator asks an abandoned iterator to release its upstream resources.
+// Async generators may wait for an active next call before running return;
+// rejection is observed here so cleanup cannot create an unhandled promise.
+export function closeIterator(iterator) {
+    if (!iterator.return)
+        return;
+    void Promise.resolve(iterator.return()).catch(() => undefined);
+}

package/dist/srpc/termination.test.d.ts

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

package/dist/srpc/termination.test.js

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { TerminationGate } from './termination.js';
+describe('TerminationGate', () => {
+    it('prioritizes termination over an already-ready result', async () => {
+        const gate = new TerminationGate();
+        const iterator = (async function* () {
+            yield 1;
+        })();
+        const pending = gate.next(iterator);
+        const error = new Error('stopped');
+        gate.terminate(error);
+        await expect(pending).resolves.toEqual({ terminated: true, error });
+    });
+    it('keeps the first termination result', async () => {
+        const gate = new TerminationGate();
+        const error = new Error('stopped');
+        expect(gate.terminate(error)).toBe(true);
+        expect(gate.terminate()).toBe(false);
+        await expect(gate.wait(new Promise(() => { }))).resolves.toEqual({
+            terminated: true,
+            error,
+        });
+    });
+});