starpc 0.51.0 → 0.52.1

package/cmd/protoc-gen-es-starpc/typescript.ts

@@ -26,6 +26,7 @@ import {
 } from '@aptre/protobuf-es-lite/protoplugin/ecmascript'
 
 const MessageStream = createImportSymbol('MessageStream', 'starpc')
+const ServerContext = createImportSymbol('ServerContext', 'starpc')
 const RuntimeMethodKind = createImportSymbol(
   'MethodKind',
   '@aptre/protobuf-es-lite',
@@ -128,6 +129,42 @@ function generateService(
   f.print("}");
   f.print();
 
+  // Generate the server implementation interface.
+  f.print(f.jsDoc(service));
+  f.print("export interface ", localName(service), "Handler {");
+  for (let i = 0; i < service.methods.length; i++) {
+    const method = service.methods[i];
+    f.print(f.jsDoc(method, "  "));
+    if (method.methodKind === MethodKind.Unary) {
+      f.print(
+        "  ", method.name,
+        "(request: ", method.input, ", abortSignal: AbortSignal, context: ", ServerContext, "): ",
+        "Promise<", method.output, ">;"
+      );
+    } else if (method.methodKind === MethodKind.ServerStreaming) {
+      f.print(
+        "  ", method.name,
+        "(request: ", method.input, ", abortSignal: AbortSignal, context: ", ServerContext, "): ",
+        MessageStream, "<", method.output, ">;"
+      );
+    } else if (method.methodKind === MethodKind.ClientStreaming) {
+      f.print(
+        "  ", method.name,
+        "(request: ", MessageStream, "<", method.input, ">, abortSignal: AbortSignal, context: ", ServerContext, "): ",
+        "Promise<", method.output, ">;"
+      );
+    } else if (method.methodKind === MethodKind.BiDiStreaming) {
+      f.print(
+        "  ", method.name,
+        "(request: ", MessageStream, "<", method.input, ">, abortSignal: AbortSignal, context: ", ServerContext, "): ",
+        MessageStream, "<", method.output, ">;"
+      );
+    }
+    if (i < service.methods.length - 1) f.print();
+  }
+  f.print("}");
+  f.print();
+
 
   // Generate the service name constant
   f.print("export const ", localName(service), "ServiceName = ", localName(service), "Definition.typeName");

package/dist/cmd/protoc-gen-es-starpc/typescript.js

@@ -15,6 +15,7 @@
 import { MethodIdempotency, MethodKind, localName, } from '@aptre/protobuf-es-lite';
 import { createImportSymbol, } from '@aptre/protobuf-es-lite/protoplugin/ecmascript';
 const MessageStream = createImportSymbol('MessageStream', 'starpc');
+const ServerContext = createImportSymbol('ServerContext', 'starpc');
 const RuntimeMethodKind = createImportSymbol('MethodKind', '@aptre/protobuf-es-lite');
 const RuntimeMethodIdempotency = createImportSymbol('MethodIdempotency', '@aptre/protobuf-es-lite');
 // const Message = createImportSymbol('Message', '@aptre/protobuf-es-lite')
@@ -74,6 +75,29 @@ function generateService(f, service) {
     }
     f.print("}");
     f.print();
+    // Generate the server implementation interface.
+    f.print(f.jsDoc(service));
+    f.print("export interface ", localName(service), "Handler {");
+    for (let i = 0; i < service.methods.length; i++) {
+        const method = service.methods[i];
+        f.print(f.jsDoc(method, "  "));
+        if (method.methodKind === MethodKind.Unary) {
+            f.print("  ", method.name, "(request: ", method.input, ", abortSignal: AbortSignal, context: ", ServerContext, "): ", "Promise<", method.output, ">;");
+        }
+        else if (method.methodKind === MethodKind.ServerStreaming) {
+            f.print("  ", method.name, "(request: ", method.input, ", abortSignal: AbortSignal, context: ", ServerContext, "): ", MessageStream, "<", method.output, ">;");
+        }
+        else if (method.methodKind === MethodKind.ClientStreaming) {
+            f.print("  ", method.name, "(request: ", MessageStream, "<", method.input, ">, abortSignal: AbortSignal, context: ", ServerContext, "): ", "Promise<", method.output, ">;");
+        }
+        else if (method.methodKind === MethodKind.BiDiStreaming) {
+            f.print("  ", method.name, "(request: ", MessageStream, "<", method.input, ">, abortSignal: AbortSignal, context: ", ServerContext, "): ", MessageStream, "<", method.output, ">;");
+        }
+        if (i < service.methods.length - 1)
+            f.print();
+    }
+    f.print("}");
+    f.print();
     // Generate the service name constant
     f.print("export const ", localName(service), "ServiceName = ", localName(service), "Definition.typeName");
     f.print();

package/dist/echo/client-test.d.ts

@@ -1,4 +1,4 @@
 import { Client } from '../srpc/index.js';
 export declare function runClientTest(client: Client): Promise<void>;
 export declare function runAbortControllerTest(client: Client): Promise<void>;
-export declare function runRpcStreamTest(client: Client): Promise<void>;
+export declare function runRpcStreamTest(client: Client, release?: boolean): Promise<void>;

package/dist/echo/client-test.js

@@ -1,7 +1,7 @@
 import { Client, ERR_RPC_ABORT } from '../srpc/index.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';
 export async function runClientTest(client) {
     const demoServiceClient = new EchoerClient(client);
     console.log('Calling Echo: unary call...');
@@ -77,8 +77,14 @@ export async function runAbortControllerTest(client) {
         }
     });
 }
+function requireError(error, label, fragments) {
+    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) {
+export async function runRpcStreamTest(client, release = false) {
     console.log('Calling RpcStream to open a RPC stream client...');
     const service = new EchoerClient(client);
     const openStreamFn = buildRpcStreamOpenStream('test', service.RpcStream.bind(service));
@@ -89,4 +95,106 @@ export async function runRpcStreamTest(client) {
     console.log('rpc stream test: succeeded: response: ' + resp.body);
     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');
+    }
 }

package/dist/echo/echo_srpc.pb.d.ts

@@ -2,7 +2,7 @@ import { EchoMsg } from './echo.pb.js';
 import { MethodKind } from '@aptre/protobuf-es-lite';
 import { RpcStreamPacket } from '../rpcstream/rpcstream.pb.js';
 import { Empty } from '@aptre/protobuf-es-lite/google/protobuf/empty';
-import { MessageStream, ProtoRpc } from 'starpc';
+import { MessageStream, ProtoRpc, ServerContext } from 'starpc';
 /**
  * Echoer service returns the given message.
  *
@@ -122,6 +122,49 @@ export interface Echoer {
      */
     DoNothing(request: Empty, abortSignal?: AbortSignal): Promise<Empty>;
 }
+/**
+ * Echoer service returns the given message.
+ *
+ * @generated from service echo.Echoer
+ */
+export interface EchoerHandler {
+    /**
+     * Echo returns the given message.
+     *
+     * @generated from rpc echo.Echoer.Echo
+     */
+    Echo(request: EchoMsg, abortSignal: AbortSignal, context: ServerContext): Promise<EchoMsg>;
+    /**
+     * EchoServerStream is an example of a server -> client one-way stream.
+     *
+     * @generated from rpc echo.Echoer.EchoServerStream
+     */
+    EchoServerStream(request: EchoMsg, abortSignal: AbortSignal, context: ServerContext): MessageStream<EchoMsg>;
+    /**
+     * EchoClientStream is an example of client->server one-way stream.
+     *
+     * @generated from rpc echo.Echoer.EchoClientStream
+     */
+    EchoClientStream(request: MessageStream<EchoMsg>, abortSignal: AbortSignal, context: ServerContext): Promise<EchoMsg>;
+    /**
+     * EchoBidiStream is an example of a two-way stream.
+     *
+     * @generated from rpc echo.Echoer.EchoBidiStream
+     */
+    EchoBidiStream(request: MessageStream<EchoMsg>, abortSignal: AbortSignal, context: ServerContext): MessageStream<EchoMsg>;
+    /**
+     * RpcStream opens a nested rpc call stream.
+     *
+     * @generated from rpc echo.Echoer.RpcStream
+     */
+    RpcStream(request: MessageStream<RpcStreamPacket>, abortSignal: AbortSignal, context: ServerContext): MessageStream<RpcStreamPacket>;
+    /**
+     * DoNothing does nothing.
+     *
+     * @generated from rpc echo.Echoer.DoNothing
+     */
+    DoNothing(request: Empty, abortSignal: AbortSignal, context: ServerContext): Promise<Empty>;
+}
 export declare const EchoerServiceName: "echo.Echoer";
 export declare class EchoerClient implements Echoer {
     private readonly rpc;

package/dist/echo/server.d.ts

@@ -2,16 +2,17 @@ import { Message } from '@aptre/protobuf-es-lite';
 import { Empty } from '@aptre/protobuf-es-lite/google/protobuf/empty';
 import { EchoMsg } from './echo.pb.js';
 import { Server } from '../srpc/server.js';
+import type { ServerContext } from '../srpc/server-context.js';
 import { RpcStreamPacket } from '../rpcstream/rpcstream.pb.js';
 import { MessageStream } from '../srpc/message.js';
-import { Echoer } from './echo_srpc.pb.js';
-export declare class EchoerServer implements Echoer {
+import type { EchoerHandler } from './echo_srpc.pb.js';
+export declare class EchoerServer implements EchoerHandler {
     private proxyServer?;
     constructor(proxyServer?: Server);
-    Echo(request: EchoMsg): Promise<Message<EchoMsg>>;
-    EchoServerStream(request: EchoMsg): MessageStream<EchoMsg>;
-    EchoClientStream(request: MessageStream<EchoMsg>): Promise<Message<EchoMsg>>;
-    EchoBidiStream(request: MessageStream<EchoMsg>): MessageStream<EchoMsg>;
-    RpcStream(request: MessageStream<RpcStreamPacket>): MessageStream<RpcStreamPacket>;
-    DoNothing(): Promise<Empty>;
+    Echo(request: EchoMsg, _abortSignal: AbortSignal, _context: ServerContext): Promise<Message<EchoMsg>>;
+    EchoServerStream(request: EchoMsg, _abortSignal: AbortSignal, _context: ServerContext): MessageStream<EchoMsg>;
+    EchoClientStream(request: MessageStream<EchoMsg>, _abortSignal: AbortSignal, _context: ServerContext): Promise<Message<EchoMsg>>;
+    EchoBidiStream(request: MessageStream<EchoMsg>, _abortSignal: AbortSignal, _context: ServerContext): MessageStream<EchoMsg>;
+    RpcStream(request: MessageStream<RpcStreamPacket>, _abortSignal: AbortSignal, _context: ServerContext): MessageStream<RpcStreamPacket>;
+    DoNothing(_request: Empty, _abortSignal: AbortSignal, _context: ServerContext): Promise<Empty>;
 }

package/dist/echo/server.js

@@ -8,16 +8,16 @@ export class EchoerServer {
     constructor(proxyServer) {
         this.proxyServer = proxyServer;
     }
-    async Echo(request) {
+    async Echo(request, _abortSignal, _context) {
         return request;
     }
-    async *EchoServerStream(request) {
+    async *EchoServerStream(request, _abortSignal, _context) {
         for (let i = 0; i < 5; i++) {
             yield request;
             await new Promise((resolve) => setTimeout(resolve, 200));
         }
     }
-    async EchoClientStream(request) {
+    async EchoClientStream(request, _abortSignal, _context) {
         // return the first message sent by the client.
         const message = await first(request);
         if (!message) {
@@ -25,14 +25,14 @@ export class EchoerServer {
         }
         return message;
     }
-    EchoBidiStream(request) {
+    EchoBidiStream(request, _abortSignal, _context) {
         // build result observable
         const result = messagePushable();
         result.push({ body: 'hello from server' });
         writeToPushable(request, result);
         return result;
     }
-    RpcStream(request) {
+    RpcStream(request, _abortSignal, _context) {
         return handleRpcStream(request[Symbol.asyncIterator](), async () => {
             if (!this.proxyServer) {
                 throw new Error('rpc stream proxy server not set');
@@ -40,7 +40,7 @@ export class EchoerServer {
             return this.proxyServer.rpcStreamHandler;
         });
     }
-    async DoNothing() {
+    async DoNothing(_request, _abortSignal, _context) {
         return {};
     }
 }

package/dist/integration/cross-language/tcp-packet-stream.d.ts

@@ -0,0 +1,3 @@
+import net from 'net';
+import type { PacketStream } from '../../srpc/stream.js';
+export declare function tcpSocketToPacketStream(socket: net.Socket): PacketStream;

package/dist/integration/cross-language/tcp-packet-stream.js

@@ -0,0 +1,112 @@
+import { pipe } from 'it-pipe';
+import { pushable } from 'it-pushable';
+import { combineUint8ArrayListTransform } from '../../srpc/array-list.js';
+import { parseLengthPrefixTransform, prependLengthPrefixTransform, } from '../../srpc/packet.js';
+import { closeIterator, sourceIterator, TerminationGate, } from '../../srpc/termination.js';
+// tcpSocketToPacketStream wraps a Node.js TCP socket into a PacketStream.
+export function tcpSocketToPacketStream(socket) {
+    const sourceTermination = new TerminationGate();
+    const sinkTermination = new TerminationGate();
+    const bytes = pushable({ objectMode: true });
+    let bytesEnded = false;
+    const endBytes = (error) => {
+        if (bytesEnded)
+            return;
+        bytesEnded = true;
+        bytes.end(error);
+    };
+    const terminate = (error) => {
+        const first = sourceTermination.terminate(error);
+        sinkTermination.terminate(error);
+        endBytes(error);
+        return first;
+    };
+    socket.on('data', (data) => {
+        if (!bytesEnded)
+            bytes.push(new Uint8Array(data));
+    });
+    socket.on('end', () => endBytes());
+    socket.on('error', (error) => terminate(error));
+    socket.on('close', () => {
+        endBytes();
+        sinkTermination.terminate();
+    });
+    const close = async () => {
+        if (terminate())
+            socket.destroy();
+    };
+    const abort = (error) => {
+        if (terminate(error))
+            socket.destroy(error);
+    };
+    return {
+        close,
+        abort,
+        source: (async function* () {
+            const packets = pipe(bytes, parseLengthPrefixTransform(), combineUint8ArrayListTransform())[Symbol.asyncIterator]();
+            try {
+                while (true) {
+                    const next = await sourceTermination.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()));
+            try {
+                while (true) {
+                    const next = await sinkTermination.next(iterator);
+                    if ('terminated' in next) {
+                        if (next.error)
+                            throw next.error;
+                        return;
+                    }
+                    if ('error' in next)
+                        throw next.error;
+                    if (next.result.done) {
+                        socket.end();
+                        return;
+                    }
+                    const data = next.result.value instanceof Uint8Array
+                        ? next.result.value
+                        : next.result.value.subarray();
+                    const written = await sinkTermination.wait(new Promise((resolve, reject) => {
+                        socket.write(data, (error) => {
+                            if (error)
+                                reject(error);
+                            else
+                                resolve();
+                        });
+                    }));
+                    if ('terminated' in written) {
+                        if (written.error)
+                            throw written.error;
+                        return;
+                    }
+                    if ('error' in written)
+                        throw written.error;
+                }
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                abort(error);
+                throw error;
+            }
+            finally {
+                closeIterator(iterator);
+            }
+        },
+    };
+}

package/dist/integration/cross-language/tcp-packet-stream.test.d.ts

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

package/dist/integration/cross-language/tcp-packet-stream.test.js

@@ -0,0 +1,121 @@
+import net from 'net';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { pushable } from 'it-pushable';
+import { tcpSocketToPacketStream } from './tcp-packet-stream.js';
+const sockets = [];
+const servers = [];
+afterEach(() => {
+    for (const socket of sockets)
+        socket.destroy();
+    for (const server of servers)
+        server.close();
+    sockets.length = 0;
+    servers.length = 0;
+});
+describe('TCP PacketStream lifecycle', () => {
+    it('settles a blocked source when the peer ends cleanly', async () => {
+        const { local, peer } = await connectSockets();
+        const stream = tcpSocketToPacketStream(local);
+        const pending = stream.source.next();
+        peer.end();
+        await expect(settleBeforeTimeout(pending)).resolves.toEqual({
+            done: true,
+            value: undefined,
+        });
+    });
+    it('reports a truncated frame when the peer ends', async () => {
+        const { local, peer } = await connectSockets();
+        const stream = tcpSocketToPacketStream(local);
+        const pending = stream.source.next();
+        peer.end(Buffer.from([4, 0, 0, 0, 10, 1]));
+        await expect(settleBeforeTimeout(pending)).rejects.toThrow('truncated packet frame');
+    });
+    it('rejects a blocked source with the abort error', async () => {
+        const { local } = await connectSockets();
+        const stream = tcpSocketToPacketStream(local);
+        const pending = stream.source.next();
+        const error = new Error('stopped');
+        stream.abort(error);
+        await expect(settleBeforeTimeout(pending)).rejects.toBe(error);
+    });
+    it('settles a blocked sink when closed', async () => {
+        const { local } = await connectSockets();
+        const stream = tcpSocketToPacketStream(local);
+        const input = pushable({ objectMode: true });
+        const pending = stream.sink(input);
+        await stream.close();
+        await expect(pending).resolves.toBeUndefined();
+    });
+    it('settles an in-flight socket write when closed', async () => {
+        const { local } = await connectSockets();
+        const stream = tcpSocketToPacketStream(local);
+        const input = pushable({ objectMode: true });
+        const writeStarted = Promise.withResolvers();
+        vi.spyOn(local, 'write').mockImplementation(((_data, _callback) => {
+            writeStarted.resolve();
+            return true;
+        }));
+        input.push(new Uint8Array([1]));
+        const pending = stream.sink(input);
+        await writeStarted.promise;
+        await stream.close();
+        await expect(settleBeforeTimeout(pending)).resolves.toBeUndefined();
+    });
+    it('rejects a blocked sink with the abort error', async () => {
+        const { local } = await connectSockets();
+        const stream = tcpSocketToPacketStream(local);
+        const input = pushable({ objectMode: true });
+        const pending = stream.sink(input);
+        const error = new Error('stopped');
+        stream.abort(error);
+        await expect(pending).rejects.toBe(error);
+    });
+    it('does not write ready input after close', async () => {
+        const { local, peer } = await connectSockets();
+        const stream = tcpSocketToPacketStream(local);
+        const input = pushable({ objectMode: true });
+        const received = [];
+        peer.on('data', (data) => {
+            if (typeof data !== 'string')
+                received.push(data);
+        });
+        input.push(new Uint8Array([1]));
+        const pending = stream.sink(input);
+        await stream.close();
+        await pending;
+        await new Promise((resolve) => peer.once('close', () => resolve()));
+        expect(received).toEqual([]);
+    });
+});
+async function connectSockets() {
+    const accepted = Promise.withResolvers();
+    const server = net.createServer((socket) => accepted.resolve(socket));
+    servers.push(server);
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', resolve);
+    });
+    const address = server.address();
+    const local = net.connect(address.port, address.address);
+    await new Promise((resolve, reject) => {
+        local.once('connect', resolve);
+        local.once('error', reject);
+    });
+    const peer = await accepted.promise;
+    sockets.push(local, peer);
+    return { local, peer };
+}
+async function settleBeforeTimeout(promise) {
+    let timeout;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_resolve, reject) => {
+                timeout = setTimeout(() => reject(new Error('source stayed blocked')), 500);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}