starpc 0.1.7 → 0.2.0

package/srpc/client.ts

@@ -1,36 +1,16 @@
-import { Observable, from as observableFrom } from 'rxjs'
-import type { TsProtoRpc } from './ts-proto-rpc'
-import type { OpenStreamFunc } from './stream'
-import { DataCb, ClientRPC } from './client-rpc'
 import { pipe } from 'it-pipe'
 import { pushable, Pushable } from 'it-pushable'
+import { Observable, from as observableFrom } from 'rxjs'
+
+import type { TsProtoRpc } from './ts-proto-rpc.js'
+import type { OpenStreamFunc } from './stream.js'
+import { ClientRPC } from './client-rpc.js'
 import {
   decodePacketSource,
   encodePacketSource,
   parseLengthPrefixTransform,
   prependLengthPrefixTransform,
-} from './packet'
-
-// unaryDataCb builds a new unary request data callback.
-function unaryDataCb(resolve: (data: Uint8Array) => void): DataCb {
-  return async (data: Uint8Array): Promise<boolean | void> => {
-    // resolve the promise
-    resolve(data)
-    // this is the last data we expect.
-    return false
-  }
-}
-
-// streamingDataCb builds a new streaming request data callback.
-/*
-function streamingDataCb(resolve: (data: Uint8Array) => void): DataCb {
-  return async (
-    data: Uint8Array
-  ): Promise<boolean | void> => {
-    // TODO
-  }
-}
-*/
+} from './packet.js'
 
 // writeClientStream registers the subscriber to write the client data stream.
 function writeClientStream(call: ClientRPC, data: Observable<Uint8Array>) {
@@ -42,26 +22,11 @@ function writeClientStream(call: ClientRPC, data: Observable<Uint8Array>) {
       call.close(err)
     },
     complete() {
-      call.writeCallData(new Uint8Array(0), true)
+      call.writeCallData(undefined, true)
     },
   })
 }
 
-// waitCallComplete handles the call complete promise.
-function waitCallComplete(
-  call: ClientRPC,
-  resolve: (data: Uint8Array) => void,
-  reject: (err: Error) => void
-) {
-  call
-    .waitComplete()
-    .catch(reject)
-    .finally(() => {
-      // ensure we resolve it if no data was ever returned.
-      resolve(new Uint8Array())
-    })
-}
-
 // Client implements the ts-proto Rpc interface with the drpcproto protocol.
 export class Client implements TsProtoRpc {
   // openConnFn is the open connection function.
@@ -78,31 +43,31 @@ export class Client implements TsProtoRpc {
     method: string,
     data: Uint8Array
   ): Promise<Uint8Array> {
-    return new Promise<Uint8Array>((resolve, reject) => {
-      const dataCb = unaryDataCb(resolve)
-      this.startRpc(service, method, data, dataCb)
-        .then((call) => {
-          waitCallComplete(call, resolve, reject)
-        })
-        .catch(reject)
-    })
+    const call = await this.startRpc(service, method, data)
+    for await (const data of call.rpcDataSource) {
+      call.close()
+      return data
+    }
+    const err = new Error('empty response')
+    call.close(err)
+    throw err
   }
 
   // clientStreamingRequest starts a client side streaming request.
-  public clientStreamingRequest(
+  public async clientStreamingRequest(
     service: string,
     method: string,
     data: Observable<Uint8Array>
   ): Promise<Uint8Array> {
-    return new Promise<Uint8Array>((resolve, reject) => {
-      const dataCb = unaryDataCb(resolve)
-      this.startRpc(service, method, null, dataCb)
-        .then((call) => {
-          writeClientStream(call, data)
-          waitCallComplete(call, resolve, reject)
-        })
-        .catch(reject)
-    })
+    const call = await this.startRpc(service, method, null)
+    writeClientStream(call, data)
+    for await (const data of call.rpcDataSource) {
+      call.close()
+      return data
+    }
+    const err = new Error('empty response')
+    call.close(err)
+    throw err
   }
 
   // serverStreamingRequest starts a server-side streaming request.
@@ -113,24 +78,16 @@ export class Client implements TsProtoRpc {
   ): Observable<Uint8Array> {
     const pushServerData: Pushable<Uint8Array> = pushable()
     const serverData = observableFrom(pushServerData)
-    const dataCb: DataCb = async (
-      data: Uint8Array
-    ): Promise<boolean | void> => {
-      // push the message to the observable
-      pushServerData.push(data)
-      // expect more messages
-      return true
-    }
-    this.startRpc(service, method, data, dataCb)
-      .then((call) => {
-        call
-          .waitComplete()
-          .catch((err: Error) => {
-            pushServerData.throw(err)
-          })
-          .finally(() => {
-            pushServerData.end()
-          })
+    this.startRpc(service, method, data)
+      .then(async (call) => {
+        try {
+          for await (const data of call.rpcDataSource) {
+            pushServerData.push(data)
+          }
+        } catch (err) {
+          pushServerData.throw(err as Error)
+        }
+        pushServerData.end()
       })
       .catch(pushServerData.throw.bind(pushServerData))
     return serverData
@@ -144,25 +101,27 @@ export class Client implements TsProtoRpc {
   ): Observable<Uint8Array> {
     const pushServerData: Pushable<Uint8Array> = pushable()
     const serverData = observableFrom(pushServerData)
-    const dataCb: DataCb = async (
-      data: Uint8Array
-    ): Promise<boolean | void> => {
-      // push the message to the observable
-      pushServerData.push(data)
-      // expect more messages
-      return true
-    }
-    this.startRpc(service, method, null, dataCb)
-      .then((call) => {
-        writeClientStream(call, data)
-        call
-          .waitComplete()
-          .catch((err: Error) => {
-            pushServerData.throw(err)
-          })
-          .finally(() => {
-            pushServerData.end()
+    this.startRpc(service, method, null)
+      .then(async (call) => {
+        try {
+          data.subscribe({
+            next(value) {
+              call.writeCallData(value)
+            },
+            error(err) {
+              call.close(err)
+            },
+            complete() {
+              call.close()
+            },
           })
+          for await (const data of call.rpcDataSource) {
+            pushServerData.push(data)
+          }
+        } catch (err) {
+          pushServerData.throw(err as Error)
+        }
+        pushServerData.end()
       })
       .catch(pushServerData.throw.bind(pushServerData))
     return serverData
@@ -170,14 +129,14 @@ export class Client implements TsProtoRpc {
 
   // startRpc is a common utility function to begin a rpc call.
   // throws any error starting the rpc call
+  // if data == null and data.length == 0, sends a separate data packet.
   private async startRpc(
     rpcService: string,
     rpcMethod: string,
-    data: Uint8Array | null,
-    dataCb: DataCb
+    data: Uint8Array | null
   ): Promise<ClientRPC> {
     const conn = await this.openConnFn()
-    const call = new ClientRPC(rpcService, rpcMethod, dataCb)
+    const call = new ClientRPC(rpcService, rpcMethod)
     pipe(
       conn,
       parseLengthPrefixTransform(),

package/srpc/common-rpc.ts

@@ -0,0 +1,171 @@
+import type { Source, Sink } from 'it-stream-types'
+import { pushable } from 'it-pushable'
+
+import type { CallData, CallStart } from './rpcproto.js'
+import { Packet } from './rpcproto.js'
+
+// CommonRPC is common logic between server and client RPCs.
+export class CommonRPC {
+  // sink is the data sink for incoming messages.
+  public sink: Sink<Packet>
+  // source is the packet source for outgoing Packets.
+  public source: AsyncIterable<Packet>
+  // _source is used to write to the source.
+  private readonly _source: {
+    push: (val: Packet) => void
+    end: (err?: Error) => void
+  }
+  // rpcDataSource emits incoming client RPC messages to the caller.
+  public readonly rpcDataSource: Source<Uint8Array>
+  // _rpcDataSource is used to write to the rpc message source.
+  private readonly _rpcDataSource: {
+    push: (val: Uint8Array) => void
+    end: (err?: Error) => void
+  }
+
+  // service is the rpc service
+  protected service?: string
+  // method is the rpc method
+  protected method?: string
+
+  constructor() {
+    this.sink = this._createSink()
+
+    const sourcev = this._createSource()
+    this.source = sourcev
+    this._source = sourcev
+
+    const rpcDataSource = this._createRpcDataSource()
+    this.rpcDataSource = rpcDataSource
+    this._rpcDataSource = rpcDataSource
+  }
+
+  // writeCallData writes the call data packet.
+  public async writeCallData(
+    data?: Uint8Array,
+    complete?: boolean,
+    error?: string
+  ) {
+    const callData: CallData = {
+      data: data || new Uint8Array(0),
+      dataIsZero: !!data && data.length === 0,
+      complete: complete || false,
+      error: error || '',
+    }
+    await this.writePacket({
+      body: {
+        $case: 'callData',
+        callData,
+      },
+    })
+  }
+
+  // writePacket writes a packet to the stream.
+  protected async writePacket(packet: Packet) {
+    this._source.push(packet)
+  }
+
+  // handleMessage handles an incoming encoded Packet.
+  //
+  // note: closes the stream if any error is thrown.
+  public async handleMessage(message: Uint8Array) {
+    return this.handlePacket(Packet.decode(message))
+  }
+
+  // handlePacket handles an incoming packet.
+  //
+  // note: closes the stream if any error is thrown.
+  public async handlePacket(packet: Partial<Packet>) {
+    try {
+      switch (packet?.body?.$case) {
+        case 'callStart':
+          await this.handleCallStart(packet.body.callStart)
+          break
+        case 'callData':
+          await this.handleCallData(packet.body.callData)
+          break
+      }
+    } catch (err) {
+      let asError = err as Error
+      if (!asError?.message) {
+        asError = new Error('error handling packet')
+      }
+      this.close(asError)
+      throw asError
+    }
+  }
+
+  // handleCallStart handles a CallStart packet.
+  public async handleCallStart(packet: Partial<CallStart>) {
+    // no-op
+    throw new Error(
+      `unexpected call start: ${packet.rpcService}/${packet.rpcMethod}`
+    )
+  }
+
+  // pushRpcData pushes incoming rpc data to the rpc data source.
+  protected pushRpcData(
+    data: Uint8Array | undefined,
+    dataIsZero: boolean | undefined
+  ) {
+    if (dataIsZero) {
+      if (!data || data.length !== 0) {
+        data = new Uint8Array(0)
+      }
+    } else if (!data || data.length === 0) {
+      return
+    }
+    this._rpcDataSource.push(data)
+  }
+
+  // handleCallData handles a CallData packet.
+  public async handleCallData(packet: Partial<CallData>) {
+    if (!this.service || !this.method) {
+      throw new Error('call start must be sent before call data')
+    }
+
+    this.pushRpcData(packet.data, packet.dataIsZero)
+    if (packet.error) {
+      this._rpcDataSource.end(new Error(packet.error))
+    } else if (packet.complete) {
+      this._rpcDataSource.end()
+    }
+  }
+
+  // close marks the call as complete, optionally with an error.
+  public async close(err?: Error) {
+    this._rpcDataSource.end(err)
+    this._source.end(err)
+  }
+
+  // _createSink returns a value for the sink field.
+  private _createSink(): Sink<Packet> {
+    return async (source) => {
+      try {
+        for await (const msg of source) {
+          await this.handlePacket(msg)
+        }
+      } catch (err) {
+        const anyErr = err as any
+        if (anyErr?.code !== 'ERR_MPLEX_STREAM_RESET') {
+          this.close(err as Error)
+        }
+      }
+      this._rpcDataSource.end()
+    }
+  }
+
+  // _createSource returns a value for the source field.
+  private _createSource() {
+    return pushable<Packet>({
+      objectMode: true,
+    })
+  }
+
+  // _createRpcDataSource returns a value for the rpc data source field.
+  private _createRpcDataSource() {
+    return pushable<Uint8Array>({
+      objectMode: true,
+    })
+  }
+}

package/srpc/conn.ts

@@ -1,9 +1,13 @@
 import type { Stream } from '@libp2p/interface-connection'
-import type { StreamMuxer, StreamMuxerFactory } from '@libp2p/interface-stream-muxer'
+import type {
+  StreamMuxer,
+  StreamMuxerFactory,
+} from '@libp2p/interface-stream-muxer'
 import type { Duplex } from 'it-stream-types'
 import { Mplex } from '@libp2p/mplex'
-import type { Stream as SRPCStream } from './stream'
-import { Client } from './client'
+
+import type { OpenStreamFunc, Stream as SRPCStream } from './stream.js'
+import { Client } from './client.js'
 
 // ConnParams are parameters that can be passed to the Conn constructor.
 export interface ConnParams {
@@ -11,12 +15,27 @@ export interface ConnParams {
   muxerFactory?: StreamMuxerFactory
 }
 
+// StreamHandler handles incoming streams.
+// Implemented by Server.
+export interface StreamHandler {
+  // handleStream handles an incoming stream.
+  handleStream(strm: Duplex<Uint8Array>): Promise<void>
+}
+
 // Conn implements a generic connection with a two-way stream.
+// 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 implements Duplex<Uint8Array> {
   // muxer is the mplex stream muxer.
   private muxer: StreamMuxer
+  // server is the server side, if set.
+  private server?: StreamHandler
 
-  constructor(connParams?: ConnParams) {
+  constructor(server?: StreamHandler, connParams?: ConnParams) {
+    if (server) {
+      this.server = server
+    }
     let muxerFactory = connParams?.muxerFactory
     if (!muxerFactory) {
       muxerFactory = new Mplex()
@@ -51,8 +70,17 @@ export class Conn implements Duplex<Uint8Array> {
     return this.muxer.newStream()
   }
 
+  // buildOpenStreamFunc returns openStream bound to this conn.
+  public buildOpenStreamFunc(): OpenStreamFunc {
+    return this.openStream.bind(this)
+  }
+
   // handleIncomingStream handles an incoming stream.
   private handleIncomingStream(strm: Stream) {
-    strm.abort(new Error('server -> client streams not implemented'))
+    const server = this.server
+    if (!server) {
+      return strm.abort(new Error('server not implemented'))
+    }
+    server.handleStream(strm)
   }
 }

package/srpc/definition.ts

@@ -0,0 +1,30 @@
+import { MessageDefinition } from './message'
+
+// Definition describes the service definitions generated by ts-proto.
+// use --ts_proto_opt=outputServices=default,outputServices=generic-definitions
+export interface Definition {
+  // name is the name of the service.
+  // e.x.: Echo
+  name: string
+  // fullName is the fully qualified name of the service
+  // e.x.: echoer.Echoer
+  fullName: string
+  // methods is the set of RPC methods.
+  methods: { [id: string]: MethodDefinition<unknown, unknown> }
+}
+
+// MethodDefinition describes the method definitions generated by ts-proto.
+// use --ts_proto_opt=outputServices=default,outputServices=generic-definitions
+export interface MethodDefinition<RequestType, ResponseType> {
+  // name is the name and function name of the method.
+  // e.x.: Echo
+  name: string
+  // requestType is the object used for the request.
+  requestType: MessageDefinition<RequestType>
+  // requestStream indicates the request is a stream.
+  requestStream: boolean
+  // responseType is the object used for the response.
+  responseType: MessageDefinition<ResponseType>
+  // responseStream indicates the response is a stream.
+  responseStream: boolean
+}

package/srpc/handler.ts

@@ -0,0 +1,174 @@
+import type { Sink, Source } from 'it-stream-types'
+import { pipe } from 'it-pipe'
+import { pushable } from 'it-pushable'
+import { Observable, from as observableFrom } from 'rxjs'
+
+import { Definition, MethodDefinition } from './definition.js'
+import {
+  buildDecodeMessageTransform,
+  buildEncodeMessageTransform,
+} from './message.js'
+
+// InvokeFn describes an SRPC call method invoke function.
+export type InvokeFn = (
+  dataSource: Source<Uint8Array>,
+  dataSink: Sink<Uint8Array>
+) => Promise<void>
+
+// Handler describes a SRPC call handler implementation.
+export interface Handler {
+  // getServiceID returns the ID of the service.
+  getServiceID(): string
+  // getMethodIDs returns the IDs of the methods.
+  getMethodIDs(): string[]
+  // lookupMethod looks up the method matching the service & method ID.
+  // returns null if not found.
+  lookupMethod(serviceID: string, methodID: string): Promise<InvokeFn | null>
+}
+
+// MethodMap is a map from method id to invoke function.
+export type MethodMap = { [name: string]: InvokeFn }
+
+// StaticHandler is a handler with a definition and implementation.
+export class StaticHandler implements Handler {
+  // service is the service id
+  private service: string
+  // methods is the map of method to invoke fn
+  private methods: MethodMap
+
+  constructor(serviceID: string, methods: MethodMap) {
+    this.service = serviceID
+    this.methods = methods
+  }
+
+  // getServiceID returns the ID of the service.
+  public getServiceID(): string {
+    return this.service
+  }
+
+  // getMethodIDs returns the IDs of the methods.
+  public getMethodIDs(): string[] {
+    return Object.keys(this.methods)
+  }
+
+  // lookupMethod looks up the method matching the service & method ID.
+  // returns null if not found.
+  public async lookupMethod(
+    serviceID: string,
+    methodID: string
+  ): Promise<InvokeFn | null> {
+    if (serviceID && serviceID !== this.service) {
+      return null
+    }
+    return this.methods[methodID] || null
+  }
+}
+
+// MethodProto is a function which matches one of the RPC signatures.
+type MethodProto =
+  | ((request: unknown) => Promise<unknown>)
+  | ((request: unknown) => Observable<unknown>)
+  | ((request: Observable<unknown>) => Promise<unknown>)
+  | ((request: Observable<unknown>) => Observable<unknown>)
+
+// createInvokeFn builds an InvokeFn from a method definition and a function prototype.
+export function createInvokeFn(
+  methodInfo: MethodDefinition<unknown, unknown>,
+  methodProto: MethodProto
+): InvokeFn {
+  const requestDecode = buildDecodeMessageTransform(methodInfo.requestType)
+  return async (dataSource: Source<Uint8Array>, dataSink: Sink<Uint8Array>) => {
+    // responseSink is a Sink for response messages.
+    const responseSink = pushable<unknown>({
+      objectMode: true,
+    })
+
+    // pipe responseSink to dataSink.
+    const responsePipe = pipe(
+      responseSink,
+      buildEncodeMessageTransform(methodInfo.responseType),
+      dataSink
+    )
+
+    // build the request argument.
+    let requestArg: any
+    if (methodInfo.requestStream) {
+      // requestSource is a Source of decoded request messages.
+      const requestSource = pipe(dataSource, requestDecode)
+      // convert the request data source into an Observable<T>
+      requestArg = observableFrom(requestSource)
+    } else {
+      // receive a single message for the argument.
+      const requestRx = requestDecode(dataSource)
+      for await (const msg of requestRx) {
+        requestArg = msg
+        break
+      }
+    }
+
+    // Call the implementation.
+    try {
+      const responseObj = methodProto(requestArg)
+      if (!responseObj) {
+        throw new Error('return value was undefined')
+      }
+      if (methodInfo.responseStream) {
+        const responseObs = responseObj as Observable<unknown>
+        if (!responseObs.subscribe) {
+          throw new Error('expected return value to be an Observable')
+        }
+        return new Promise<void>((resolve, reject) => {
+          responseObs.subscribe({
+            next(value) {
+              responseSink.push(value)
+            },
+            error: (err: any) => {
+              responseSink.throw(err)
+              reject(err)
+            },
+            complete: () => {
+              responseSink.end()
+              responsePipe.finally(() => {
+                resolve()
+              })
+            },
+          })
+        })
+      } else {
+        const responsePromise = responseObj as Promise<unknown>
+        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.
+export function createHandler(definition: Definition, impl: any): Handler {
+  const methodMap: MethodMap = {}
+  for (const methodInfo of Object.values(definition.methods)) {
+    const methodName = methodInfo.name
+    let methodProto: MethodProto = impl[methodName]
+    if (!methodProto) {
+      continue
+    }
+    methodProto = methodProto.bind(impl)
+    methodMap[methodName] = createInvokeFn(methodInfo, methodProto)
+  }
+
+  return new StaticHandler(definition.fullName, methodMap)
+}

package/srpc/index.ts

@@ -1,3 +1,7 @@
-export { Client } from './client'
-export type { OpenStreamFunc } from './stream'
-export { WebSocketConn } from './websocket'
+export type { OpenStreamFunc } from './stream.js'
+export { Client } from './client.js'
+export { Server } from './server.js'
+export { Conn } from './conn.js'
+export { Handler, InvokeFn, createHandler, createInvokeFn } from './handler.js'
+export { Mux, createMux } from './mux.js'
+export { WebSocketConn } from './websocket.js'