starpc 0.52.0 → 0.52.2

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);
+            }
         },
     };
 }

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,
+        });
+    });
+});

package/dist/testdata/packet-codec-vectors.json

@@ -0,0 +1,64 @@
+{
+    "version": 1,
+    "max_message_size": 10000000,
+    "frame_prefix": "uint32 little-endian",
+    "cases": [
+        {
+            "name": "call_start_data",
+            "packet_hex": "0a120a0373766312066d6574686f641a03616263",
+            "frame_hex": "140000000a120a0373766312066d6574686f641a03616263"
+        },
+        {
+            "name": "call_start_absent_empty",
+            "packet_hex": "0a0d0a0373766312066d6574686f64",
+            "frame_hex": "0f0000000a0d0a0373766312066d6574686f64"
+        },
+        {
+            "name": "call_start_present_empty",
+            "packet_hex": "0a0f0a0373766312066d6574686f642001",
+            "frame_hex": "110000000a0f0a0373766312066d6574686f642001"
+        },
+        {
+            "name": "call_data_terminal",
+            "packet_hex": "12070a036f75741801",
+            "frame_hex": "0900000012070a036f75741801"
+        },
+        {
+            "name": "call_data_error",
+            "packet_hex": "120a180122066661696c6564",
+            "frame_hex": "0c000000120a180122066661696c6564"
+        },
+        {
+            "name": "call_cancel",
+            "packet_hex": "1801",
+            "frame_hex": "020000001801"
+        },
+        {
+            "name": "malformed_complete",
+            "frame_hex": "030000000a01ff",
+            "expect_error": "malformed_packet"
+        },
+        {
+            "name": "invalid_zero_length",
+            "frame_hex": "00000000",
+            "expect_error": "invalid_length"
+        },
+        {
+            "name": "invalid_oversized_prefix",
+            "frame_hex": "81969800",
+            "expect_error": "oversized_frame"
+        },
+        {
+            "name": "invalid_empty_packet",
+            "packet_hex": "",
+            "expect_error": "empty_packet"
+        },
+        { "name": "invalid_empty_service_id", "expect_error": "empty_service_id" },
+        { "name": "invalid_empty_method_id", "expect_error": "empty_method_id" },
+        {
+            "name": "truncated_body",
+            "frame_hex": "040000000a01",
+            "expect_error": "truncated_frame"
+        }
+    ]
+}

package/echo/Cargo.toml

@@ -23,3 +23,11 @@ starpc = { workspace = true }
 prost = { workspace = true }
 tokio = { version = "1", features = ["full"] }
 async-trait = { workspace = true }
+futures = { workspace = true }
+
+[[test]]
+name = "half_close"
+path = "half_close_test.rs"
+
+[dev-dependencies]
+tokio-util = { workspace = true }

package/echo/client-test.ts

@@ -2,7 +2,10 @@ import { Client, ERR_RPC_ABORT } from '../srpc/index.js'
 import { EchoMsg } from './echo.pb.js'
 import { EchoerClient } from './echo_srpc.pb.js'
 import { pushable } from 'it-pushable'
-import { buildRpcStreamOpenStream } from '../rpcstream/rpcstream.js'
+import {
+  buildRpcStreamOpenStream,
+  openRpcStream,
+} from '../rpcstream/rpcstream.js'
 import { Message } from '@aptre/protobuf-es-lite'
 
 export async function runClientTest(client: Client) {
@@ -89,8 +92,19 @@ export async function runAbortControllerTest(client: Client) {
   })
 }
 
+function requireError(
+  error: unknown,
+  label: string,
+  fragments: string[],
+): void {
+  const message = error instanceof Error ? error.message : String(error)
+  if (!fragments.some((fragment) => message.includes(fragment))) {
+    throw new Error(`${label} returned unexpected error: ${message}`)
+  }
+}
+
 // runRpcStreamTest tests a RPCStream.
-export async function runRpcStreamTest(client: Client) {
+export async function runRpcStreamTest(client: Client, release = false) {
   console.log('Calling RpcStream to open a RPC stream client...')
   const service = new EchoerClient(client)
   const openStreamFn = buildRpcStreamOpenStream(
@@ -106,4 +120,112 @@ export async function runRpcStreamTest(client: Client) {
 
   console.log('Running client test over RPC stream...')
   await runClientTest(proxiedClient)
+
+  if (release) {
+    let unknownRejected = false
+    try {
+      await openRpcStream('missing', service.RpcStream.bind(service), true)
+    } catch (error) {
+      unknownRejected = true
+      requireError(error, 'unknown component', ['unknown component: missing'])
+    }
+    if (!unknownRejected) {
+      throw new Error('unknown component unexpectedly succeeded')
+    }
+  }
+
+  let methodRejected = false
+  try {
+    await proxiedClient.request('missing.Service', 'Missing', new Uint8Array())
+  } catch (error) {
+    methodRejected = true
+    requireError(error, 'unknown nested method', [
+      'missing.Service',
+      'unimplemented',
+    ])
+  }
+  if (!methodRejected) {
+    throw new Error('unknown nested method unexpectedly succeeded')
+  }
+
+  if (release) {
+    const terminalService = new EchoerClient(proxiedClient)
+    let terminalFailed = false
+    try {
+      await terminalService.Echo({ body: '__nested_error__' })
+    } catch (error) {
+      terminalFailed = true
+      requireError(error, 'terminal nested error', ['nested terminal error'])
+    }
+    if (!terminalFailed) {
+      throw new Error('terminal nested error unexpectedly succeeded')
+    }
+  }
+
+  if (release) {
+    const releaseClient = new Client(
+      buildRpcStreamOpenStream('release', service.RpcStream.bind(service)),
+    )
+    let releaseFailed = false
+    const releaseService = new EchoerClient(releaseClient)
+    try {
+      await releaseService.Echo({ body: '__nested_release__' })
+    } catch (error) {
+      releaseFailed = true
+      requireError(error, 'release during active call', [
+        'closed before completion',
+        'stream closed',
+        'abort',
+        'cancel',
+      ])
+    }
+    if (!releaseFailed) {
+      throw new Error('release during active call unexpectedly succeeded')
+    }
+    const releaseStatus = await service.Echo({
+      body: '__nested_release_status__',
+    })
+    if (releaseStatus.body !== 'released') {
+      throw new Error(`release completion returned ${releaseStatus.body}`)
+    }
+    let releasedRejected = false
+    try {
+      await releaseService.Echo({})
+    } catch (error) {
+      releasedRejected = true
+      requireError(error, 'released component', ['unknown component: release'])
+    }
+    if (!releasedRejected) {
+      throw new Error('released component unexpectedly remained available')
+    }
+  }
+
+  const cancelled = new AbortController()
+  const cancelledStream = proxiedClient.bidirectionalStreamingRequest(
+    'echo.Echoer',
+    'EchoBidiStream',
+    (async function* () {
+      yield new Uint8Array()
+      await new Promise(() => undefined)
+    })(),
+    cancelled.signal,
+  )
+  const cancelledIterator = cancelledStream[Symbol.asyncIterator]()
+  const firstNestedResponse = await cancelledIterator.next()
+  if (firstNestedResponse.done) {
+    throw new Error('nested cancellation call ended before its first response')
+  }
+  cancelled.abort()
+  let cancelRejected = false
+  try {
+    while (!(await cancelledIterator.next()).done) {
+      // Drain until the abort reaches the nested call.
+    }
+  } catch (error) {
+    cancelRejected = true
+    requireError(error, 'nested cancellation', [ERR_RPC_ABORT])
+  }
+  if (!cancelRejected) {
+    throw new Error('nested cancellation unexpectedly completed normally')
+  }
 }