starpc 0.0.1 → 0.1.0

package/srpc/client-rpc.ts

@@ -0,0 +1,197 @@
+import type { CallData, CallStart, CallStartResp } from './rpcproto'
+import { Packet } from './rpcproto'
+import type { Sink } from 'it-stream-types'
+import { pushable } from 'it-pushable'
+
+// DataCb is a callback to handle incoming RPC messages.
+// Returns true if more data is expected, false otherwise.
+// If returns undefined, assumes more data is expected.
+export type DataCb = (data: Uint8Array) => Promise<boolean | void>
+
+// ClientRPC is an ongoing RPC from the client side.
+export class ClientRPC {
+  // 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
+  }
+  // service is the rpc service
+  private service: string
+  // method is the rpc method
+  private method: string
+  // dataCb is called with any incoming data.
+  private dataCb?: DataCb
+  // started is resolved when the request starts.
+  private started: Promise<void>
+  // onStarted is called by the message handler when the request starts.
+  private onStarted?: (err?: Error) => void
+  // complete is resolved when the request completes.
+  // rejected with an error if the call encountered any error.
+  private complete: Promise<void>
+  // onComplete is called by the message handler when the call completes.
+  private onComplete?: (err?: Error) => void
+  // closed indicates close has been called
+  private closed: boolean
+
+  constructor(service: string, method: string, dataCb: DataCb | null) {
+    this.closed = false
+    this.sink = this._createSink()
+    const sourcev = this._createSource()
+    this.source = sourcev
+    this._source = sourcev
+    this.service = service
+    this.method = method
+    if (dataCb) {
+      this.dataCb = dataCb
+    }
+    this.started = new Promise<void>((resolveStarted, rejectStarted) => {
+      this.onStarted = (err?: Error) => {
+        if (err) {
+          rejectStarted(err)
+        } else {
+          resolveStarted()
+        }
+      }
+    })
+    this.complete = new Promise<void>((resolveComplete, rejectComplete) => {
+      this.onComplete = (err?: Error) => {
+        this.closed = true
+        if (err) {
+          rejectComplete(err)
+        } else {
+          resolveComplete()
+        }
+      }
+    })
+  }
+
+  // waitStarted returns the started promise.
+  public waitStarted(): Promise<void> {
+    return this.started
+  }
+
+  // waitComplete returns the complete promise.
+  public waitComplete(): Promise<void> {
+    return this.complete
+  }
+
+  // writeCallStart writes the call start packet.
+  public async writeCallStart(data?: Uint8Array) {
+    const callStart: CallStart = {
+      rpcService: this.service,
+      rpcMethod: this.method,
+      data: data || new Uint8Array(0),
+    }
+    await this.writePacket({
+      body: {
+        $case: 'callStart',
+        callStart,
+      },
+    })
+  }
+
+  // writeCallData writes the call data packet.
+  public async writeCallData(data: Uint8Array, complete?: boolean, error?: string) {
+    const callData: CallData = {
+      data,
+      complete: complete || false,
+      error: error || "",
+    }
+    await this.writePacket({
+      body: {
+        $case: 'callData',
+        callData,
+      },
+    })
+  }
+
+  // writePacket writes a packet to the stream.
+  private async writePacket(packet: Packet) {
+    this._source.push(packet)
+  }
+
+  // handleMessage handles an incoming encoded Packet.
+  //
+  // note: may throw an error if the message was unexpected or invalid.
+  public async handleMessage(message: Uint8Array) {
+    return this.handlePacket(Packet.decode(message))
+  }
+
+  // handlePacket handles an incoming packet.
+  public async handlePacket(packet: Partial<Packet>) {
+    switch (packet?.body?.$case) {
+      case 'callStart':
+        return this.handleCallStart(packet.body.callStart)
+      case 'callStartResp':
+        return this.handleCallStartResp(packet.body.callStartResp)
+      case 'callData':
+        return this.handleCallData(packet.body.callData)
+    }
+  }
+
+  // handleCallStart handles a CallStart packet.
+  public async handleCallStart(packet: Partial<CallStart>) {
+    // we do not implement server -> client RPCs.
+    throw new Error(`unexpected server to client rpc: ${packet.rpcService}/${packet.rpcMethod}`)
+  }
+
+  // handleCallStartResp handles a CallStartResp packet.
+  public async handleCallStartResp(packet: Partial<CallStartResp>) {
+    if (packet.error && packet.error.length) {
+      const err = new Error(packet.error)
+      this.onStarted!(err)
+      this.onComplete!(err)
+    }
+  }
+
+  // handleCallData handles a CallData packet.
+  public async handleCallData(packet: Partial<CallData>) {
+    const data = packet.data
+    if (this.dataCb && data?.length) {
+      await this.dataCb(data)
+    }
+    if (packet.error && packet.error.length) {
+      this.onComplete!(new Error(packet.error))
+    } else if (packet.complete) {
+      this.onComplete!()
+    }
+  }
+
+  // close closes the active call if not already completed.
+  public async close(err?: Error) {
+    if (!this.closed) {
+      await this.writeCallData(new Uint8Array(0), true, err ? err.message : "")
+    }
+    if (!err) {
+      err = new Error('call closed')
+    }
+    this.onComplete!(err)
+  }
+
+  // _createSink initializes the sink field.
+  private _createSink(): Sink<Packet> {
+    return async (source) => {
+      try {
+        for await (const msg of source) {
+          await this.handlePacket(msg)
+        }
+      } catch (err) {
+        this.close(err as Error)
+      }
+    }
+  }
+
+  // _createSource initializes the source field.
+  private _createSource() {
+    return pushable<Packet>({
+      objectMode: true,
+      onEnd: (err?: Error): void => {
+        this.onComplete!(err)
+      },
+    })
+  }
+}

package/srpc/client.go

@@ -0,0 +1,96 @@
+package srpc
+
+import (
+	"context"
+	"io"
+
+	"github.com/pkg/errors"
+)
+
+// Client implements a SRPC client which can initiate RPC streams.
+type Client interface {
+	// Invoke executes a unary RPC with the remote.
+	Invoke(ctx context.Context, service, method string, in, out Message) error
+
+	// NewStream starts a streaming RPC with the remote & returns the stream.
+	// firstMsg is optional.
+	NewStream(ctx context.Context, service, method string, firstMsg Message) (Stream, error)
+}
+
+// OpenStreamFunc opens a stream with a remote.
+// msgHandler must not be called concurrently.
+type OpenStreamFunc = func(ctx context.Context, msgHandler func(pkt *Packet) error) (Writer, error)
+
+// client implements Client with a transport.
+type client struct {
+	// openStream opens a new stream.
+	openStream OpenStreamFunc
+}
+
+// NewClient constructs a client with a OpenStreamFunc.
+func NewClient(openStream OpenStreamFunc) Client {
+	return &client{
+		openStream: openStream,
+	}
+}
+
+// Invoke executes a unary RPC with the remote.
+func (c *client) Invoke(rctx context.Context, service, method string, in, out Message) error {
+	ctx, ctxCancel := context.WithCancel(rctx)
+	defer ctxCancel()
+
+	firstMsg, err := in.MarshalVT()
+	if err != nil {
+		return err
+	}
+	clientRPC := NewClientRPC(ctx, service, method)
+	writer, err := c.openStream(ctx, clientRPC.HandlePacket)
+	if err != nil {
+		return err
+	}
+	if err := clientRPC.Start(writer, firstMsg); err != nil {
+		return err
+	}
+	msgs, err := clientRPC.ReadAll()
+	if err != nil {
+		// this includes any server returned error.
+		return err
+	}
+	if len(msgs) == 0 {
+		// no reply? return eof.
+		return io.EOF
+	}
+	// parse first message to out
+	if err := out.UnmarshalVT(msgs[0]); err != nil {
+		return errors.Wrap(ErrInvalidMessage, err.Error())
+	}
+	// done
+	return nil
+}
+
+// NewStream starts a streaming RPC with the remote & returns the stream.
+// firstMsg is optional.
+func (c *client) NewStream(ctx context.Context, service, method string, firstMsg Message) (Stream, error) {
+	var firstMsgData []byte
+	if firstMsg != nil {
+		var err error
+		firstMsgData, err = firstMsg.MarshalVT()
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	clientRPC := NewClientRPC(ctx, service, method)
+	writer, err := c.openStream(ctx, clientRPC.HandlePacket)
+	if err != nil {
+		return nil, err
+	}
+	if err := clientRPC.Start(writer, firstMsgData); err != nil {
+		return nil, err
+	}
+
+	return NewRPCStream(ctx, clientRPC.writer, clientRPC.dataCh), nil
+}
+
+// _ is a type assertion
+var _ Client = ((*client)(nil))

package/srpc/client.ts

@@ -0,0 +1,182 @@
+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 {
+  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
+  }
+}
+*/
+
+// writeClientStream registers the subscriber to write the client data stream.
+function writeClientStream(call: ClientRPC, data: Observable<Uint8Array>) {
+  data.subscribe({
+    next(value) {
+      call.writeCallData(value)
+    },
+    error(err) {
+      call.close(err)
+    },
+    complete() {
+      call.writeCallData(new Uint8Array(0), 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.
+  // called when starting RPC.
+  private openConnFn: OpenStreamFunc
+
+  constructor(openConnFn: OpenStreamFunc) {
+    this.openConnFn = openConnFn
+  }
+
+  // request starts a non-streaming request.
+  public async request(
+    service: string,
+    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)
+    })
+  }
+
+  // clientStreamingRequest starts a client side streaming request.
+  public 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)
+    })
+  }
+
+  // serverStreamingRequest starts a server-side streaming request.
+  public serverStreamingRequest(
+    service: string,
+    method: string,
+    data: Uint8Array
+  ): 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()
+        })
+      })
+      .catch(pushServerData.throw.bind(pushServerData))
+    return serverData
+  }
+
+  // bidirectionalStreamingRequest starts a two-way streaming request.
+  public bidirectionalStreamingRequest(
+    service: string,
+    method: string,
+    data: Observable<Uint8Array>
+  ): 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()
+        })
+      })
+      .catch(pushServerData.throw.bind(pushServerData))
+    return serverData
+  }
+
+  // startRpc is a common utility function to begin a rpc call.
+  // throws any error starting the rpc call
+  private async startRpc(
+    rpcService: string,
+    rpcMethod: string,
+    data: Uint8Array | null,
+    dataCb: DataCb
+  ): Promise<ClientRPC> {
+    const conn = await this.openConnFn()
+    const call = new ClientRPC(rpcService, rpcMethod, dataCb)
+    pipe(
+      conn,
+      parseLengthPrefixTransform(),
+      decodePacketSource,
+      call,
+      encodePacketSource,
+      prependLengthPrefixTransform(),
+      conn,
+    )
+    await call.writeCallStart(data || undefined)
+    return call
+  }
+}

package/srpc/conn.go

@@ -0,0 +1,7 @@
+package srpc
+
+// Conn represents a connection to a remote.
+type Conn interface {
+	// GetOpenStreamFunc returns the OpenStream func.
+	GetOpenStreamFunc() OpenStreamFunc
+}

package/srpc/conn.ts

@@ -0,0 +1,49 @@
+import type { Stream } from '@libp2p/interfaces/connection'
+import type { Duplex } from 'it-stream-types'
+import { Components } from '@libp2p/interfaces/components'
+import { MplexStreamMuxer } from '@libp2p/mplex'
+import type { Stream as SRPCStream } from './stream'
+import { Client } from './client'
+
+// Conn implements a generic connection with a two-way stream.
+export class Conn implements Duplex<Uint8Array> {
+  // muxer is the mplex stream muxer.
+  private muxer: MplexStreamMuxer
+
+  constructor() {
+    // see https://github.com/libp2p/js-libp2p-mplex/pull/179
+    this.muxer = new MplexStreamMuxer(new Components(), {
+      onIncomingStream: this.handleIncomingStream.bind(this),
+    })
+  }
+
+  // sink returns the message sink.
+  get sink() {
+    return this.muxer.sink
+  }
+
+  // source returns the outgoing message source.
+  get source() {
+    return this.muxer.source
+  }
+
+  // streams returns the set of all ongoing streams.
+  get streams() {
+    return this.muxer.streams
+  }
+
+  // buildClient builds a new client from the connection.
+  public buildClient(): Client {
+    return new Client(this.openStream.bind(this))
+  }
+
+  // openStream implements the client open stream function.
+  public async openStream(): Promise<SRPCStream> {
+    return this.muxer.newStream()
+  }
+
+  // handleIncomingStream handles an incoming stream.
+  private handleIncomingStream(strm: Stream) {
+    strm.abort(new Error('server -> client streams not implemented'))
+  }
+}

package/srpc/errors.go

@@ -0,0 +1,20 @@
+package srpc
+
+import "errors"
+
+var (
+	// ErrUnimplemented is returned if the RPC method was not implemented.
+	ErrUnimplemented = errors.New("unimplemented")
+	// ErrCompleted is returned if a message is received after the rpc was completed.
+	ErrCompleted = errors.New("unexpected packet after rpc was completed")
+	// ErrUnrecognizedPacket is returned if the packet type was not recognized.
+	ErrUnrecognizedPacket = errors.New("unrecognized packet type")
+	// ErrEmptyPacket is returned if nothing is specified in a packet.
+	ErrEmptyPacket = errors.New("invalid empty packet")
+	// ErrInvalidMessage indicates the message failed to parse.
+	ErrInvalidMessage = errors.New("invalid message")
+	// ErrEmptyMethodID is returned if the method id was empty.
+	ErrEmptyMethodID = errors.New("method id empty")
+	// ErrEmptyServiceID is returned if the service id was empty.
+	ErrEmptyServiceID = errors.New("service id empty")
+)

package/srpc/handler.go

@@ -0,0 +1,13 @@
+package srpc
+
+// Handler describes a SRPC call handler implementation.
+type Handler interface {
+	// GetServiceID returns the ID of the service.
+	GetServiceID() string
+	// GetMethodIDs returns the list of methods for the service.
+	GetMethodIDs() []string
+	// InvokeMethod invokes the method matching the service & method ID.
+	// Returns false, nil if not found.
+	// If service string is empty, ignore it.
+	InvokeMethod(serviceID, methodID string, strm Stream) (bool, error)
+}

package/srpc/index.ts

@@ -0,0 +1,3 @@
+export { Client } from './client'
+export type { OpenStreamFunc } from './stream'
+export { WebSocketConn } from './websocket'

package/srpc/message.go

@@ -0,0 +1,7 @@
+package srpc
+
+// Message is the vtprotobuf message interface.
+type Message interface {
+	MarshalVT() ([]byte, error)
+	UnmarshalVT([]byte) error
+}

package/srpc/mux.go

@@ -0,0 +1,76 @@
+package srpc
+
+import "sync"
+
+// Mux contains a set of <service, method> handlers.
+type Mux interface {
+	// Register registers a new RPC method handler (service).
+	Register(handler Handler) error
+	// InvokeMethod invokes the method matching the service & method ID.
+	// Returns false, nil if not found.
+	// If service string is empty, ignore it.
+	InvokeMethod(serviceID, methodID string, strm Stream) (bool, error)
+}
+
+// muxMethods is a mapping from method id to handler.
+type muxMethods map[string]Handler
+
+// mux is the default implementation of Mux.
+type mux struct {
+	// rmtx guards below fields
+	rmtx sync.RWMutex
+	// services contains a mapping from services to handlers.
+	services map[string]muxMethods
+}
+
+// NewMux constructs a new Mux.
+func NewMux() Mux {
+	return &mux{services: make(map[string]muxMethods)}
+}
+
+// Register registers a new RPC method handler (service).
+func (m *mux) Register(handler Handler) error {
+	serviceID := handler.GetServiceID()
+	methodIDs := handler.GetMethodIDs()
+	if serviceID == "" {
+		return ErrEmptyServiceID
+	}
+
+	m.rmtx.Lock()
+	defer m.rmtx.Unlock()
+
+	serviceMethods := m.services[serviceID]
+	if serviceMethods == nil {
+		serviceMethods = make(muxMethods)
+		m.services[serviceID] = serviceMethods
+	}
+	for _, methodID := range methodIDs {
+		if methodID != "" {
+			serviceMethods[methodID] = handler
+		}
+	}
+
+	return nil
+}
+
+// InvokeMethod invokes the method matching the service & method ID.
+// Returns false, nil if not found.
+// If service string is empty, ignore it.
+func (m *mux) InvokeMethod(serviceID, methodID string, strm Stream) (bool, error) {
+	var handler Handler
+	m.rmtx.RLock()
+	svcMethods := m.services[serviceID]
+	if svcMethods != nil {
+		handler = svcMethods[methodID]
+	}
+	m.rmtx.RUnlock()
+
+	if handler == nil {
+		return false, nil
+	}
+
+	return handler.InvokeMethod(serviceID, methodID, strm)
+}
+
+// _ is a type assertion
+var _ Mux = ((*mux)(nil))