starpc 0.23.2 → 0.24.0

package/srpc/common-rpc.ts

@@ -3,13 +3,14 @@ import { pushable } from 'it-pushable'
 
 import type { CallData, CallStart } from './rpcproto.pb.js'
 import { Packet } from './rpcproto.pb.js'
+import { ERR_RPC_ABORT } from './errors.js'
 
 // CommonRPC is common logic between server and client RPCs.
 export class CommonRPC {
   // sink is the data sink for incoming messages.
-  public sink: Sink<Source<Packet>>
+  public readonly sink: Sink<Source<Packet>>
   // source is the packet source for outgoing Packets.
-  public source: AsyncIterable<Packet>
+  public readonly source: AsyncIterable<Packet>
   // rpcDataSource is the source for rpc packets.
   public readonly rpcDataSource: AsyncIterable<Uint8Array>
 
@@ -95,6 +96,7 @@ export class CommonRPC {
   //
   // note: closes the stream if any error is thrown.
   public async handlePacket(packet: Partial<Packet>) {
+    // console.log('handlePacket', packet)
     try {
       switch (packet?.body?.$case) {
         case 'callStart':
@@ -103,6 +105,11 @@ export class CommonRPC {
         case 'callData':
           await this.handleCallData(packet.body.callData)
           break
+        case 'callCancel':
+          if (packet.body.callCancel) {
+            await this.handleCallCancel()
+          }
+          break
       }
     } catch (err) {
       let asError = err as Error
@@ -151,19 +158,28 @@ export class CommonRPC {
     }
   }
 
+  // handleCallCancel handles a CallCancel packet.
+  public async handleCallCancel() {
+    this.close(new Error(ERR_RPC_ABORT))
+  }
+
   // close closes the call, optionally with an error.
   public async close(err?: Error) {
     if (this.closed) {
       return
     }
     this.closed = true
-    this._rpcDataSource.end(err)
-    try {
+    // note: don't pass error to _source here.
+    if (err) {
       await this.writeCallCancel()
-    } finally {
-      // note: don't pass error to _source here.
-      this._source.end()
     }
+    this._source.end()
+    this._rpcDataSource.end(err)
+  }
+
+  // closeWrite closes the call for writing.
+  public closeWrite() {
+    this._source.end()
   }
 
   // _createSink returns a value for the sink field.
@@ -181,7 +197,6 @@ export class CommonRPC {
             await this.handlePacket(msg)
           }
         }
-        this._rpcDataSource.end()
       } catch (err) {
         this.close(err as Error)
       }

package/srpc/conn.ts

@@ -1,33 +1,31 @@
-import { yamux } from '@chainsafe/libp2p-yamux'
+import { YamuxMuxerInit, yamux } from '@chainsafe/libp2p-yamux'
 import type {
   Direction,
   Stream,
   StreamMuxer,
   StreamMuxerFactory,
 } from '@libp2p/interface'
-import { pipe } from 'it-pipe'
-import type { Duplex, Source } from 'it-stream-types'
+import type { Duplex } from 'it-stream-types'
 import { Uint8ArrayList } from 'uint8arraylist'
-import isPromise from 'is-promise'
-import { pushable, Pushable } from 'it-pushable'
 import { defaultLogger } from '@libp2p/logger'
 
-import type { OpenStreamFunc, Stream as SRPCStream } from './stream.js'
-import { Client } from './client.js'
-import { combineUint8ArrayListTransform } from './array-list.js'
 import {
-  parseLengthPrefixTransform,
-  prependLengthPrefixTransform,
-} from './packet.js'
-import { buildPushableSink } from './pushable.js'
+  streamToPacketStream,
+  type OpenStreamFunc,
+  type PacketStream,
+} from './stream.js'
+import { Client } from './client.js'
 
-// ConnParams are parameters that can be passed to the Conn constructor.
-export interface ConnParams {
+// ConnParams are parameters that can be passed to the StreamConn constructor.
+export interface StreamConnParams {
   // muxerFactory overrides using the default yamux factory.
   muxerFactory?: StreamMuxerFactory
   // direction is the muxer connection direction.
   // defaults to outbound (client).
   direction?: Direction
+  // yamuxParams are parameters to pass to yamux.
+  // only used if muxerFactory is unset
+  yamuxParams?: YamuxMuxerInit
 }
 
 // StreamHandler handles incoming streams.
@@ -35,52 +33,35 @@ export interface ConnParams {
 export interface StreamHandler {
   // handlePacketStream handles an incoming Uint8Array duplex.
   // the stream has one Uint8Array per packet w/o length prefix.
-  handlePacketStream(strm: SRPCStream): void
-}
-
-// streamToSRPCStream converts a Stream to a SRPCStream.
-// uses length-prefix for packet framing
-export function streamToSRPCStream(
-  stream: Duplex<
-    AsyncIterable<Uint8ArrayList>,
-    Source<Uint8ArrayList | Uint8Array>,
-    Promise<void>
-  >,
-): SRPCStream {
-  const pushSink: Pushable<Uint8Array> = pushable({ objectMode: true })
-  pipe(pushSink, prependLengthPrefixTransform(), stream.sink)
-  return {
-    source: pipe(
-      stream,
-      parseLengthPrefixTransform(),
-      combineUint8ArrayListTransform(),
-    ),
-    sink: buildPushableSink(pushSink),
-  }
+  handlePacketStream(strm: PacketStream): void
 }
 
-// Conn implements a generic connection with a two-way stream.
+// StreamConn implements a generic connection with a two-way stream.
+// The stream is not expected to manage packet boundaries.
+// Packets will be sent with uint32le length prefixes.
+// Uses Yamux to manage streams over the connection.
+//
 // Implements the client by opening streams with the remote.
 // Implements the server by handling incoming streams.
 // If the server is unset, rejects any incoming streams.
-export class Conn
+export class StreamConn
   implements Duplex<AsyncGenerator<Uint8Array | Uint8ArrayList>>
 {
   // muxer is the stream muxer.
-  private muxer: StreamMuxer
+  private _muxer: StreamMuxer
   // server is the server side, if set.
-  private server?: StreamHandler
+  private _server?: StreamHandler
 
-  constructor(server?: StreamHandler, connParams?: ConnParams) {
+  constructor(server?: StreamHandler, connParams?: StreamConnParams) {
     if (server) {
-      this.server = server
+      this._server = server
     }
     const muxerFactory =
       connParams?.muxerFactory ??
-      yamux({ enableKeepAlive: false })({
+      yamux({ enableKeepAlive: false, ...connParams?.yamuxParams })({
         logger: defaultLogger(),
       })
-    this.muxer = muxerFactory.createStreamMuxer({
+    this._muxer = muxerFactory.createStreamMuxer({
       onIncomingStream: this.handleIncomingStream.bind(this),
       direction: connParams?.direction || 'outbound',
     })
@@ -88,17 +69,27 @@ export class Conn
 
   // sink returns the message sink.
   get sink() {
-    return this.muxer.sink
+    return this._muxer.sink
   }
 
   // source returns the outgoing message source.
   get source() {
-    return this.muxer.source
+    return this._muxer.source
   }
 
   // streams returns the set of all ongoing streams.
   get streams() {
-    return this.muxer.streams
+    return this._muxer.streams
+  }
+
+  // muxer returns the muxer
+  get muxer() {
+    return this._muxer
+  }
+
+  // server returns the server, if any.
+  get server() {
+    return this._server
   }
 
   // buildClient builds a new client from the connection.
@@ -107,15 +98,9 @@ export class Conn
   }
 
   // openStream implements the client open stream function.
-  public async openStream(): Promise<SRPCStream> {
-    const streamPromise = this.muxer.newStream()
-    let stream: Stream
-    if (isPromise(streamPromise)) {
-      stream = await streamPromise
-    } else {
-      stream = streamPromise
-    }
-    return streamToSRPCStream(stream)
+  public async openStream(): Promise<PacketStream> {
+    const strm = await this.muxer.newStream()
+    return streamToPacketStream(strm)
   }
 
   // buildOpenStreamFunc returns openStream bound to this conn.
@@ -124,11 +109,22 @@ export class Conn
   }
 
   // handleIncomingStream handles an incoming stream.
-  private handleIncomingStream(strm: Stream) {
+  //
+  // this is usually called by the muxer when streams arrive.
+  public handleIncomingStream(strm: Stream) {
     const server = this.server
     if (!server) {
       return strm.abort(new Error('server not implemented'))
     }
-    server.handlePacketStream(streamToSRPCStream(strm))
+    server.handlePacketStream(streamToPacketStream(strm))
+  }
+
+  // close closes or aborts the muxer with an optional error.
+  public close(err?: Error) {
+    if (err) {
+      this.muxer.abort(err)
+    } else {
+      this.muxer.close()
+    }
   }
 }

package/srpc/handler.ts

@@ -1,13 +1,6 @@
 import type { Sink, Source } from 'it-stream-types'
-import { pipe } from 'it-pipe'
-import { pushable } from 'it-pushable'
-
-import { Definition, MethodDefinition } from './definition.js'
-import {
-  buildDecodeMessageTransform,
-  buildEncodeMessageTransform,
-} from './message.js'
-import { writeToPushable } from './pushable.js'
+import { Definition } from './definition.js'
+import { MethodProto, createInvokeFn } from './invoker.js'
 
 // InvokeFn describes an SRPC call method invoke function.
 export type InvokeFn = (
@@ -64,89 +57,6 @@ export class StaticHandler implements Handler {
   }
 }
 
-// MethodProto is a function which matches one of the RPC signatures.
-type MethodProto<R, O> =
-  | ((request: R) => Promise<O>)
-  | ((request: R) => AsyncIterable<O>)
-  | ((request: AsyncIterable<R>) => Promise<O>)
-  | ((request: AsyncIterable<R>) => AsyncIterable<O>)
-
-// createInvokeFn builds an InvokeFn from a method definition and a function prototype.
-export function createInvokeFn<R, O>(
-  methodInfo: MethodDefinition<R, O>,
-  methodProto: MethodProto<R, O>,
-): InvokeFn {
-  const requestDecode = buildDecodeMessageTransform<R>(methodInfo.requestType)
-  return async (
-    dataSource: Source<Uint8Array>,
-    dataSink: Sink<Source<Uint8Array>>,
-  ) => {
-    // responseSink is a Sink for response messages.
-    const responseSink = pushable<O>({
-      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: any
-    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) {
-        if (msg) {
-          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 as AsyncIterable<O>
-        return writeToPushable(response, responseSink)
-      } else {
-        const responsePromise = responseObj as Promise<O>
-        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 as Error
-      if (!asError?.message) {
-        asError = new Error('error calling implementation: ' + err)
-      }
-      // mux will return the error to the rpc caller.
-      throw asError
-    }
-  }
-}
-
 // createHandler creates a handler from a definition and an implementation.
 // if serviceID is not set, uses the fullName of the service as the identifier.
 export function createHandler(

package/srpc/index.ts

@@ -1,22 +1,33 @@
 export { ERR_RPC_ABORT, isAbortError, castToError } from './errors.js'
 export { Client } from './client.js'
 export { Server } from './server.js'
-export { Conn, ConnParams } from './conn.js'
+export { StreamConn, StreamConnParams, StreamHandler } from './conn.js'
 export { WebSocketConn } from './websocket.js'
-export { StreamConn } from './conn-stream.js'
-export type { PacketHandler, Stream, OpenStreamFunc } from './stream.js'
-export { Handler, InvokeFn, createHandler, createInvokeFn } from './handler.js'
+export type {
+  PacketHandler,
+  OpenStreamFunc,
+  PacketStream,
+  streamToPacketStream,
+} from './stream.js'
+export {
+  Handler,
+  InvokeFn,
+  MethodMap,
+  StaticHandler,
+  createHandler,
+} from './handler.js'
+export { MethodProto, createInvokeFn } from './invoker.js'
 export { Packet, CallStart, CallData } from './rpcproto.pb.js'
-export { Mux, StaticMux, createMux } from './mux.js'
+export { Mux, StaticMux, LookupMethod, createMux } from './mux.js'
 export {
   BroadcastChannelDuplex,
-  newBroadcastChannelDuplex,
   BroadcastChannelConn,
+  newBroadcastChannelDuplex,
 } from './broadcast-channel.js'
 export {
   MessagePortDuplex,
-  newMessagePortDuplex,
   MessagePortConn,
+  newMessagePortDuplex,
 } from './message-port.js'
 export {
   MessageDefinition,

package/srpc/invoker.ts

@@ -0,0 +1,92 @@
+import { Sink, Source } from 'it-stream-types'
+import { pushable } from 'it-pushable'
+import { pipe } from 'it-pipe'
+import { MethodDefinition } from './definition.js'
+import { InvokeFn } from './handler.js'
+import {
+  buildDecodeMessageTransform,
+  buildEncodeMessageTransform,
+} from './message.js'
+import { writeToPushable } from './pushable.js'
+
+// MethodProto is a function which matches one of the RPC signatures.
+export type MethodProto<R, O> =
+  | ((request: R) => Promise<O>)
+  | ((request: R) => AsyncIterable<O>)
+  | ((request: AsyncIterable<R>) => Promise<O>)
+  | ((request: AsyncIterable<R>) => AsyncIterable<O>)
+
+// createInvokeFn builds an InvokeFn from a method definition and a function prototype.
+export function createInvokeFn<R, O>(
+  methodInfo: MethodDefinition<R, O>,
+  methodProto: MethodProto<R, O>,
+): InvokeFn {
+  const requestDecode = buildDecodeMessageTransform<R>(methodInfo.requestType)
+  return async (
+    dataSource: Source<Uint8Array>,
+    dataSink: Sink<Source<Uint8Array>>,
+  ) => {
+    // responseSink is a Sink for response messages.
+    const responseSink = pushable<O>({
+      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: any
+    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 as AsyncIterable<O>
+        return writeToPushable(response, responseSink)
+      } else {
+        const responsePromise = responseObj as Promise<O>
+        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 as Error
+      if (!asError?.message) {
+        asError = new Error('error calling implementation: ' + err)
+      }
+      // mux will return the error to the rpc caller.
+      responseSink.end()
+      throw asError
+    }
+  }
+}

package/srpc/message-port.ts

@@ -1,13 +1,19 @@
-import type { Source } from 'it-stream-types'
+import type { Duplex, Source } from 'it-stream-types'
 import { EventIterator } from 'event-iterator'
+import { pipe } from 'it-pipe'
 
-import { ConnParams } from './conn.js'
+import { StreamConn, StreamConnParams } from './conn.js'
 import { Server } from './server'
-import { Stream } from './stream.js'
-import { StreamConn } from './conn-stream.js'
+import { combineUint8ArrayListTransform } from './array-list.js'
 
 // MessagePortDuplex is a AsyncIterable wrapper for MessagePort.
-export class MessagePortDuplex<T> implements Stream<T> {
+//
+// 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<T>
+  implements Duplex<AsyncGenerator<T>, Source<T>, Promise<void>>
+{
   // port is the message port
   public readonly port: MessagePort
   // sink is the sink for incoming messages.
@@ -23,24 +29,35 @@ export class MessagePortDuplex<T> implements Stream<T> {
 
   // close closes the message port.
   public close() {
+    this.port.postMessage(null)
     this.port.close()
   }
 
   // _createSink initializes the sink field.
   private _createSink(): (source: Source<T>) => Promise<void> {
     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: 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()
         }
       }
 
@@ -50,9 +67,16 @@ export class MessagePortDuplex<T> implements Stream<T> {
       }
     })
 
-    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()
   }
 }
 
@@ -66,23 +90,49 @@ export function newMessagePortDuplex<T>(
 // 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 {
-  // messagePort is the message port iterable.
-  private messagePort: MessagePortDuplex<Uint8Array>
+  // _messagePort is the message port iterable.
+  private _messagePort: MessagePortDuplex<Uint8Array>
 
-  constructor(port: MessagePort, server?: Server, connParams?: ConnParams) {
+  constructor(
+    port: MessagePort,
+    server?: Server,
+    connParams?: StreamConnParams,
+  ) {
     const messagePort = new MessagePortDuplex<Uint8Array>(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.
-  public getMessagePort(): MessagePort {
-    return this.messagePort.port
+  // messagePort returns the MessagePort.
+  get messagePort(): MessagePort {
+    return this._messagePort.port
   }
 
   // close closes the message port.
-  public close() {
+  public override close(err?: Error) {
+    super.close(err)
     this.messagePort.close()
   }
 }

package/srpc/open-stream-ctr.ts

@@ -1,4 +1,4 @@
-import { OpenStreamFunc, Stream } from './stream.js'
+import { OpenStreamFunc } from './stream.js'
 import { ValueCtr } from './value-ctr.js'
 
 // OpenStreamCtr contains an OpenStream func which can be awaited.
@@ -9,7 +9,7 @@ export class OpenStreamCtr extends ValueCtr<OpenStreamFunc> {
 
   // openStreamFunc returns an OpenStreamFunc which waits for the underlying OpenStreamFunc.
   get openStreamFunc(): OpenStreamFunc {
-    return async (): Promise<Stream> => {
+    return async () => {
       let openFn = this.value
       if (!openFn) {
         openFn = await this.wait()