starpc 0.23.2 → 0.24.0

package/dist/srpc/invoker.d.ts

@@ -0,0 +1,4 @@
+import { MethodDefinition } from './definition.js';
+import { InvokeFn } from './handler.js';
+export type MethodProto<R, O> = ((request: R) => Promise<O>) | ((request: R) => AsyncIterable<O>) | ((request: AsyncIterable<R>) => Promise<O>) | ((request: AsyncIterable<R>) => AsyncIterable<O>);
+export declare function createInvokeFn<R, O>(methodInfo: MethodDefinition<R, O>, methodProto: MethodProto<R, O>): InvokeFn;

package/dist/srpc/invoker.js

@@ -0,0 +1,66 @@
+import { pushable } from 'it-pushable';
+import { pipe } from 'it-pipe';
+import { buildDecodeMessageTransform, buildEncodeMessageTransform, } from './message.js';
+import { writeToPushable } from './pushable.js';
+// createInvokeFn builds an InvokeFn from a method definition and a function prototype.
+export function createInvokeFn(methodInfo, methodProto) {
+    const requestDecode = buildDecodeMessageTransform(methodInfo.requestType);
+    return async (dataSource, dataSink) => {
+        // responseSink is a Sink for response messages.
+        const responseSink = pushable({
+            objectMode: true,
+        });
+        // pipe responseSink to dataSink.
+        pipe(responseSink, buildEncodeMessageTransform(methodInfo.responseType), dataSink);
+        // requestSource is a Source of decoded request messages.
+        const requestSource = pipe(dataSource, requestDecode);
+        // build the request argument.
+        let requestArg;
+        if (methodInfo.requestStream) {
+            // use the request source as the argument.
+            requestArg = requestSource;
+        }
+        else {
+            // receive a single message for the argument.
+            for await (const msg of requestSource) {
+                requestArg = msg;
+                break;
+            }
+        }
+        if (!requestArg) {
+            throw new Error('request object was empty');
+        }
+        // Call the implementation.
+        try {
+            const responseObj = methodProto(requestArg);
+            if (!responseObj) {
+                throw new Error('return value was undefined');
+            }
+            if (methodInfo.responseStream) {
+                const response = responseObj;
+                return writeToPushable(response, responseSink);
+            }
+            else {
+                const responsePromise = responseObj;
+                if (!responsePromise.then) {
+                    throw new Error('expected return value to be a Promise');
+                }
+                const responseMsg = await responsePromise;
+                if (!responseMsg) {
+                    throw new Error('expected non-empty response object');
+                }
+                responseSink.push(responseMsg);
+                responseSink.end();
+            }
+        }
+        catch (err) {
+            let asError = err;
+            if (!asError?.message) {
+                asError = new Error('error calling implementation: ' + err);
+            }
+            // mux will return the error to the rpc caller.
+            responseSink.end();
+            throw asError;
+        }
+    };
+}

package/dist/srpc/message-port.d.ts

@@ -1,9 +1,7 @@
-import type { Source } from 'it-stream-types';
-import { ConnParams } from './conn.js';
+import type { Duplex, Source } from 'it-stream-types';
+import { StreamConn, StreamConnParams } from './conn.js';
 import { Server } from './server';
-import { Stream } from './stream.js';
-import { StreamConn } from './conn-stream.js';
-export declare class MessagePortDuplex<T> implements Stream<T> {
+export declare class MessagePortDuplex<T> implements Duplex<AsyncGenerator<T>, Source<T>, Promise<void>> {
     readonly port: MessagePort;
     sink: (source: Source<T>) => Promise<void>;
     source: AsyncGenerator<T>;
@@ -14,8 +12,8 @@ export declare class MessagePortDuplex<T> implements Stream<T> {
 }
 export declare function newMessagePortDuplex<T>(port: MessagePort): MessagePortDuplex<T>;
 export declare class MessagePortConn extends StreamConn {
-    private messagePort;
-    constructor(port: MessagePort, server?: Server, connParams?: ConnParams);
-    getMessagePort(): MessagePort;
-    close(): void;
+    private _messagePort;
+    constructor(port: MessagePort, server?: Server, connParams?: StreamConnParams);
+    get messagePort(): MessagePort;
+    close(err?: Error): void;
 }

package/dist/srpc/message-port.js

@@ -1,6 +1,12 @@
 import { EventIterator } from 'event-iterator';
-import { StreamConn } from './conn-stream.js';
+import { pipe } from 'it-pipe';
+import { StreamConn } from './conn.js';
+import { combineUint8ArrayListTransform } from './array-list.js';
 // MessagePortDuplex is a AsyncIterable wrapper for MessagePort.
+//
+// When the sink is closed, the message port will also be closed.
+// Note: there is no way to know when a MessagePort is closed!
+// You will need an additional keep-alive on top of MessagePortDuplex.
 export class MessagePortDuplex {
     constructor(port) {
         this.port = port;
@@ -9,22 +15,34 @@ export class MessagePortDuplex {
     }
     // close closes the message port.
     close() {
+        this.port.postMessage(null);
         this.port.close();
     }
     // _createSink initializes the sink field.
     _createSink() {
         return async (source) => {
-            for await (const msg of source) {
-                this.port.postMessage(msg);
+            try {
+                for await (const msg of source) {
+                    this.port.postMessage(msg);
+                }
             }
+            catch (err) {
+                this.close();
+                throw err;
+            }
+            this.close();
         };
     }
     // _createSource initializes the source field.
     async *_createSource() {
         const iterator = new EventIterator((queue) => {
             const messageListener = (ev) => {
-                if (ev.data) {
-                    queue.push(ev.data);
+                const data = ev.data;
+                if (data !== null) {
+                    queue.push(data);
+                }
+                else {
+                    queue.stop();
                 }
             };
             this.port.addEventListener('message', messageListener);
@@ -32,9 +50,16 @@ export class MessagePortDuplex {
                 this.port.removeEventListener('message', messageListener);
             };
         });
-        for await (const value of iterator) {
-            yield value;
+        try {
+            for await (const value of iterator) {
+                yield value;
+            }
+        }
+        catch (err) {
+            this.close();
+            throw err;
         }
+        this.close();
     }
 }
 // newMessagePortDuplex constructs a MessagePortDuplex with a channel name.
@@ -44,18 +69,36 @@ export function newMessagePortDuplex(port) {
 // MessagePortConn implements a connection with a MessagePort.
 //
 // expects Uint8Array objects over the MessagePort.
+// uses Yamux to mux streams over the port.
 export class MessagePortConn extends StreamConn {
     constructor(port, server, connParams) {
         const messagePort = new MessagePortDuplex(port);
-        super(messagePort, server, connParams);
-        this.messagePort = messagePort;
+        super(server, {
+            ...connParams,
+            yamuxParams: {
+                // There is no way to tell when a MessagePort is closed.
+                // We will send an undefined object through the MessagePort to indicate closed.
+                // We still need a way to detect when the connection is not cleanly terminated.
+                // Enable keep-alive to detect this on the other end.
+                enableKeepAlive: true,
+                keepAliveInterval: 1500,
+                ...connParams?.yamuxParams,
+            },
+        });
+        this._messagePort = messagePort;
+        pipe(messagePort, this, 
+        // Uint8ArrayList usually cannot be sent over MessagePort, so we combine to a Uint8Array as part of the pipe.
+        combineUint8ArrayListTransform(), messagePort)
+            .catch((err) => this.close(err))
+            .then(() => this.close());
     }
-    // getMessagePort returns the MessagePort.
-    getMessagePort() {
-        return this.messagePort.port;
+    // messagePort returns the MessagePort.
+    get messagePort() {
+        return this._messagePort.port;
     }
     // close closes the message port.
-    close() {
+    close(err) {
+        super.close(err);
         this.messagePort.close();
     }
 }

package/dist/srpc/pushable.d.ts

@@ -1,4 +1,4 @@
 import { Pushable } from 'it-pushable';
-import { Source, Sink } from 'it-stream-types';
+import { Sink, Source } from 'it-stream-types';
 export declare function writeToPushable<T>(dataSource: AsyncIterable<T>, out: Pushable<T>): Promise<void>;
 export declare function buildPushableSink<T>(target: Pushable<T>): Sink<Source<T>, Promise<void>>;

package/dist/srpc/pushable.js

@@ -15,15 +15,13 @@ export function buildPushableSink(target) {
     return async (source) => {
         try {
             if (Symbol.asyncIterator in source) {
-                // Handle AsyncIterable
                 for await (const pkt of source) {
-                    processPacket(pkt, target);
+                    target.push(pkt);
                 }
             }
             else {
-                // Handle Iterable
                 for (const pkt of source) {
-                    processPacket(pkt, target);
+                    target.push(pkt);
                 }
             }
             target.end();
@@ -33,13 +31,3 @@ export function buildPushableSink(target) {
         }
     };
 }
-function processPacket(pkt, target) {
-    if (Array.isArray(pkt)) {
-        for (const p of pkt) {
-            target.push(p);
-        }
-    }
-    else {
-        target.push(pkt);
-    }
-}

package/dist/srpc/server-rpc.js

@@ -50,6 +50,7 @@ export class ServerRPC extends CommonRPC {
                     await this.writeCallData(msg);
                 }
                 await this.writeCallData(undefined, true);
+                this.close();
             }
             catch (err) {
                 this.close(err);

package/dist/srpc/server.d.ts

@@ -1,16 +1,12 @@
-import { Duplex, Source } from 'it-stream-types';
 import { LookupMethod } from './mux.js';
 import { ServerRPC } from './server-rpc.js';
-import { Packet } from './rpcproto.pb.js';
 import { StreamHandler } from './conn.js';
-import { Stream } from './stream.js';
+import { PacketStream } from './stream.js';
 import { RpcStreamHandler } from '../rpcstream/rpcstream.js';
 export declare class Server implements StreamHandler {
     private lookupMethod;
     constructor(lookupMethod: LookupMethod);
     get rpcStreamHandler(): RpcStreamHandler;
     startRpc(): ServerRPC;
-    handleFragmentStream(stream: Stream): ServerRPC;
-    handlePacketStream(stream: Stream): ServerRPC;
-    handlePacketDuplex(stream: Duplex<Source<Packet>>): ServerRPC;
+    handlePacketStream(stream: PacketStream): ServerRPC;
 }

package/dist/srpc/server.js

@@ -1,7 +1,6 @@
 import { pipe } from 'it-pipe';
 import { ServerRPC } from './server-rpc.js';
-import { parseLengthPrefixTransform, prependLengthPrefixTransform, decodePacketSource, encodePacketSource, } from './packet.js';
-import { combineUint8ArrayListTransform } from './array-list.js';
+import { decodePacketSource, encodePacketSource } from './packet.js';
 // Server implements the SRPC server in TypeScript with a Mux.
 export class Server {
     constructor(lookupMethod) {
@@ -17,25 +16,13 @@ export class Server {
     startRpc() {
         return new ServerRPC(this.lookupMethod);
     }
-    // handleFragmentStream handles an incoming stream.
-    // assumes that stream does not maintain packet framing.
-    // uses length-prefixed packets for packet framing.
-    handleFragmentStream(stream) {
-        const rpc = this.startRpc();
-        pipe(stream, parseLengthPrefixTransform(), combineUint8ArrayListTransform(), decodePacketSource, rpc, encodePacketSource, prependLengthPrefixTransform(), combineUint8ArrayListTransform(), stream);
-        return rpc;
-    }
     // handlePacketStream handles an incoming Uint8Array duplex.
     // the stream has one Uint8Array per packet w/o length prefix.
     handlePacketStream(stream) {
         const rpc = this.startRpc();
-        pipe(stream, decodePacketSource, rpc, encodePacketSource, stream);
-        return rpc;
-    }
-    // handlePacketDuplex handles an incoming Packet duplex.
-    handlePacketDuplex(stream) {
-        const rpc = this.startRpc();
-        pipe(stream, rpc, stream);
+        pipe(stream, decodePacketSource, rpc, encodePacketSource, stream)
+            .catch((err) => rpc.close(err))
+            .then(() => rpc.close());
         return rpc;
     }
 }

package/dist/srpc/stream.d.ts

@@ -1,5 +1,7 @@
-import type { Packet } from './rpcproto.pb.js';
 import type { Duplex, Source } from 'it-stream-types';
+import { Stream } from '@libp2p/interface';
+import type { Packet } from './rpcproto.pb.js';
 export type PacketHandler = (packet: Packet) => Promise<void>;
-export type Stream<T = Uint8Array> = Duplex<AsyncGenerator<T>, Source<T>, Promise<void>>;
-export type OpenStreamFunc = () => Promise<Stream>;
+export type PacketStream = Duplex<AsyncGenerator<Uint8Array>, Source<Uint8Array>, Promise<void>>;
+export type OpenStreamFunc = () => Promise<PacketStream>;
+export declare function streamToPacketStream(stream: Stream): PacketStream;

package/dist/srpc/stream.js

@@ -1 +1,16 @@
-export {};
+import { pipe } from 'it-pipe';
+import { combineUint8ArrayListTransform } from './array-list.js';
+import { parseLengthPrefixTransform, prependLengthPrefixTransform, } from './packet.js';
+// streamToPacketStream converts a Stream into a PacketStream using length-prefix framing.
+//
+// The stream is closed when the source writing to the sink ends.
+export function streamToPacketStream(stream) {
+    return {
+        source: pipe(stream, parseLengthPrefixTransform(), combineUint8ArrayListTransform()),
+        sink: async (source) => {
+            await pipe(source, prependLengthPrefixTransform(), stream)
+                .catch((err) => stream.close(err))
+                .then(() => stream.close());
+        },
+    };
+}

package/dist/srpc/websocket.d.ts

@@ -1,9 +1,9 @@
 /// <reference types="ws" />
 import { Direction } from '@libp2p/interface';
 import type WebSocket from '@aptre/it-ws/web-socket';
-import { Conn } from './conn.js';
+import { StreamConn } from './conn.js';
 import { Server } from './server.js';
-export declare class WebSocketConn extends Conn {
+export declare class WebSocketConn extends StreamConn {
     private socket;
     constructor(socket: WebSocket, direction: Direction, server?: Server);
     getSocket(): WebSocket;

package/dist/srpc/websocket.js

@@ -1,9 +1,9 @@
 import { pipe } from 'it-pipe';
 import duplex from '@aptre/it-ws/duplex';
-import { Conn } from './conn.js';
+import { StreamConn } from './conn.js';
 import { combineUint8ArrayListTransform } from './array-list.js';
 // WebSocketConn implements a connection with a WebSocket and optional Server.
-export class WebSocketConn extends Conn {
+export class WebSocketConn extends StreamConn {
     constructor(socket, direction, server) {
         super(server, { direction });
         this.socket = socket;

package/e2e/e2e.ts

@@ -1,7 +1,7 @@
 import { pipe } from 'it-pipe'
-import { createHandler, createMux, Server, Client, Conn } from '../srpc'
+import { createHandler, createMux, Server, Client, StreamConn } from '../srpc'
 import { EchoerDefinition, EchoerServer, runClientTest } from '../echo'
-import { runRpcStreamTest } from '../echo/client-test'
+import { runAbortControllerTest, runRpcStreamTest } from '../echo/client-test'
 
 async function runRPC() {
   const mux = createMux()
@@ -9,13 +9,16 @@ async function runRPC() {
   const echoer = new EchoerServer(server)
   mux.register(createHandler(EchoerDefinition, echoer))
 
-  const clientConn = new Conn()
-  const serverConn = new Conn(server, { direction: 'inbound' })
+  const clientConn = new StreamConn()
+  const serverConn = new StreamConn(server, { direction: 'inbound' })
+
   pipe(clientConn, serverConn, clientConn)
+
   const client = new Client(clientConn.buildOpenStreamFunc())
 
-  await runRpcStreamTest(client)
   await runClientTest(client)
+  await runAbortControllerTest(client)
+  await runRpcStreamTest(client)
 }
 
 runRPC()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starpc",
-  "version": "0.23.2",
+  "version": "0.24.0",
   "description": "Streaming protobuf RPC service protocol over any two-way channel.",
   "license": "MIT",
   "author": {

package/srpc/broadcast-channel.ts

@@ -1,62 +1,86 @@
-import type { Source } from 'it-stream-types'
+import type { Duplex, Source } from 'it-stream-types'
 import { EventIterator } from 'event-iterator'
 
-import { ConnParams } from './conn.js'
+import { StreamConn, StreamConnParams } from './conn.js'
 import { Server } from './server.js'
-import { StreamConn } from './conn-stream.js'
-import { Stream } from './stream.js'
+import { combineUint8ArrayListTransform } from './array-list.js'
+import { pipe } from 'it-pipe'
 
 // BroadcastChannelDuplex is a AsyncIterable wrapper for BroadcastChannel.
-export class BroadcastChannelDuplex<T> implements Stream<T> {
-  // readChannel is the incoming broadcast channel
-  public readonly readChannel: BroadcastChannel
-  // writeChannel is the outgoing broadcast channel
-  public readonly writeChannel: BroadcastChannel
+//
+// When the sink is closed, the broadcast channel also be closed.
+// Note: there is no way to know when a BroadcastChannel is closed!
+// You will need an additional keep-alive on top of BroadcastChannelDuplex.
+export class BroadcastChannelDuplex<T>
+  implements Duplex<AsyncGenerator<T>, Source<T>, Promise<void>>
+{
+  // read is the read channel
+  public readonly read: BroadcastChannel
+  // write is the write channel
+  public readonly write: BroadcastChannel
   // sink is the sink for incoming messages.
   public sink: (source: Source<T>) => Promise<void>
   // source is the source for outgoing messages.
   public source: AsyncGenerator<T>
 
-  constructor(readChannel: BroadcastChannel, writeChannel: BroadcastChannel) {
-    this.readChannel = readChannel
-    this.writeChannel = writeChannel
+  constructor(read: BroadcastChannel, write: BroadcastChannel) {
+    this.read = read
+    this.write = write
     this.sink = this._createSink()
     this.source = this._createSource()
   }
 
-  // close closes the broadcast channels.
+  // close closes the message port.
   public close() {
-    this.readChannel.close()
-    this.writeChannel.close()
+    this.write.postMessage(null)
+    this.write.close()
+    this.read.close()
   }
 
   // _createSink initializes the sink field.
   private _createSink(): (source: Source<T>) => Promise<void> {
     return async (source) => {
-      for await (const msg of source) {
-        this.writeChannel.postMessage(msg)
+      try {
+        for await (const msg of source) {
+          this.write.postMessage(msg)
+        }
+      } catch (err: unknown) {
+        this.close()
+        throw err
       }
+
+      this.close()
     }
   }
 
   // _createSource initializes the source field.
   private async *_createSource(): AsyncGenerator<T> {
     const iterator = new EventIterator<T>((queue) => {
-      const messageListener = (ev: MessageEvent<T>) => {
-        if (ev.data) {
-          queue.push(ev.data)
+      const messageListener = (ev: MessageEvent<T | null>) => {
+        const data = ev.data
+        if (data !== null) {
+          queue.push(data)
+        } else {
+          queue.stop()
         }
       }
 
-      this.readChannel.addEventListener('message', messageListener)
+      this.read.addEventListener('message', messageListener)
       return () => {
-        this.readChannel.removeEventListener('message', messageListener)
+        this.read.removeEventListener('message', messageListener)
       }
     })
 
-    for await (const value of iterator) {
-      yield value
+    try {
+      for await (const value of iterator) {
+        yield value
+      }
+    } catch (err) {
+      this.close()
+      throw err
     }
+
+    this.close()
   }
 }
 
@@ -74,36 +98,43 @@ export function newBroadcastChannelDuplex<T>(
 // BroadcastChannelConn implements a connection with a BroadcastChannel.
 //
 // expects Uint8Array objects over the BroadcastChannel.
+// uses Yamux to mux streams over the port.
 export class BroadcastChannelConn extends StreamConn {
-  // broadcastChannel is the broadcast channel iterable
-  private broadcastChannel: BroadcastChannelDuplex<Uint8Array>
+  // duplex is the broadcast channel duplex.
+  public readonly duplex: BroadcastChannelDuplex<Uint8Array>
 
   constructor(
-    readChannel: BroadcastChannel,
-    writeChannel: BroadcastChannel,
+    duplex: BroadcastChannelDuplex<Uint8Array>,
     server?: Server,
-    connParams?: ConnParams,
+    connParams?: StreamConnParams,
   ) {
-    const broadcastChannel = new BroadcastChannelDuplex<Uint8Array>(
-      readChannel,
-      writeChannel,
+    super(server, {
+      ...connParams,
+      yamuxParams: {
+        // There is no way to tell when a BroadcastChannel is closed.
+        // We will send an undefined object through the BroadcastChannel to indicate closed.
+        // We still need a way to detect when the connection is not cleanly terminated.
+        // Enable keep-alive to detect this on the other end.
+        enableKeepAlive: true,
+        keepAliveInterval: 1500,
+        ...connParams?.yamuxParams,
+      },
+    })
+    this.duplex = duplex
+    pipe(
+      duplex,
+      this,
+      // Uint8ArrayList usually cannot be sent over BroadcastChannel, so we combine to a Uint8Array as part of the pipe.
+      combineUint8ArrayListTransform(),
+      duplex,
     )
-    super(broadcastChannel, server, connParams)
-    this.broadcastChannel = broadcastChannel
+      .catch((err) => this.close(err))
+      .then(() => this.close())
   }
 
-  // getReadChannel returns the read BroadcastChannel.
-  public getReadChannel(): BroadcastChannel {
-    return this.broadcastChannel.readChannel
-  }
-
-  // getWriteChannel returns the write BroadcastChannel.
-  public getWriteChannel(): BroadcastChannel {
-    return this.broadcastChannel.writeChannel
-  }
-
-  // close closes the read and write channels.
-  public close() {
-    this.broadcastChannel.close()
+  // close closes the message port.
+  public override close(err?: Error) {
+    super.close(err)
+    this.duplex.close()
   }
 }

package/srpc/client.ts

@@ -68,7 +68,9 @@ export class Client implements TsProtoRpc {
     const serverData: Pushable<Uint8Array> = pushable({ objectMode: true })
     this.startRpc(service, method, data, abortSignal)
       .then(async (call) => {
-        return writeToPushable(call.rpcDataSource, serverData)
+        const result = writeToPushable(call.rpcDataSource, serverData)
+        result.finally(() => call.close())
+        return result
       })
       .catch((err) => serverData.end(err))
     return serverData
@@ -84,14 +86,16 @@ export class Client implements TsProtoRpc {
     const serverData: Pushable<Uint8Array> = pushable({ objectMode: true })
     this.startRpc(service, method, null, abortSignal)
       .then(async (call) => {
-        call.writeCallDataFromSource(data)
+        call.writeCallDataFromSource(data).catch((err) => call.close(err))
         try {
           for await (const message of call.rpcDataSource) {
             serverData.push(message)
           }
           serverData.end()
+          call.close()
         } catch (err) {
-          serverData.end(err as Error)
+          call.close(err as Error)
+          throw err
         }
       })
       .catch((err) => serverData.end(err))
@@ -114,9 +118,12 @@ export class Client implements TsProtoRpc {
     const stream = await openStreamFn()
     const call = new ClientRPC(rpcService, rpcMethod)
     abortSignal?.addEventListener('abort', () => {
+      call.writeCallCancel()
       call.close(new Error(ERR_RPC_ABORT))
     })
     pipe(stream, decodePacketSource, call, encodePacketSource, stream)
+      .then(() => call.close())
+      .catch((err) => call.close(err))
     await call.writeCallStart(data || undefined)
     return call
   }

package/srpc/common-rpc.go

@@ -131,16 +131,7 @@ func (c *commonRPC) HandleStreamClose(closeErr error) {
 
 // HandleCallCancel handles the call cancel packet.
 func (c *commonRPC) HandleCallCancel() error {
-	c.mtx.Lock()
-	defer c.mtx.Unlock()
-	if c.remoteErr != nil {
-		c.remoteErr = context.Canceled
-	}
-	c.dataClosed = true
-	if c.writer != nil {
-		_ = c.writer.Close()
-	}
-	c.bcast.Broadcast()
+	c.HandleStreamClose(context.Canceled)
 	return nil
 }