starpc 0.0.1 → 0.1.2

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))

package/srpc/packet-rw.go

@@ -0,0 +1,102 @@
+package srpc
+
+import (
+	"bytes"
+	"encoding/binary"
+	"io"
+
+	"github.com/pkg/errors"
+)
+
+// maxMessageSize is the max message size in bytes
+var maxMessageSize = 1e7
+
+// PacketReaderWriter reads and writes packets from a io.ReadWriter.
+// Uses a LittleEndian uint32 length prefix.
+type PacketReaderWriter struct {
+	// rw is the io.ReadWriterCloser
+	rw io.ReadWriteCloser
+	// cb is the callback
+	cb PacketHandler
+	// buf is the buffered data
+	buf bytes.Buffer
+}
+
+// NewPacketReadWriter constructs a new read/writer.
+func NewPacketReadWriter(rw io.ReadWriteCloser, cb PacketHandler) *PacketReaderWriter {
+	return &PacketReaderWriter{rw: rw, cb: cb}
+}
+
+// WritePacket writes a packet to the writer.
+func (r *PacketReaderWriter) WritePacket(p *Packet) error {
+	msgSize := p.SizeVT()
+	data := make([]byte, 4+msgSize)
+	binary.LittleEndian.PutUint32(data, uint32(msgSize))
+	_, err := p.MarshalToVT(data[4:])
+	if err != nil {
+		return err
+	}
+	_, err = r.rw.Write(data)
+	return err
+}
+
+// ReadPump executes the read pump in a goroutine.
+func (r *PacketReaderWriter) ReadPump() error {
+	var currLen uint32
+	buf := make([]byte, 2048)
+	for {
+		n, err := r.rw.Read(buf)
+		if err != nil {
+			if err == io.EOF {
+				err = nil
+			}
+			return err
+		}
+		_, err = r.buf.Write(buf[:n])
+		if err != nil {
+			return err
+		}
+
+		// check if we have enough for a length prefix
+		bufLen := r.buf.Len()
+		if currLen == 0 {
+			if bufLen < 4 {
+				continue
+			}
+			currLen = r.readLengthPrefix(r.buf.Bytes())
+			if currLen == 0 {
+				return errors.New("unexpected zero len prefix")
+			}
+			if currLen > uint32(maxMessageSize) {
+				return errors.Errorf("message size %v greater than maximum %v", currLen, maxMessageSize)
+			}
+		}
+		if currLen != 0 && bufLen >= int(currLen)+4 {
+			pkt := r.buf.Next(int(currLen + 4))[4:]
+			currLen = 0
+			npkt := &Packet{}
+			if err := npkt.UnmarshalVT(pkt); err != nil {
+				return err
+			}
+			if err := r.cb(npkt); err != nil {
+				return err
+			}
+		}
+	}
+}
+
+// Close closes the packet rw.
+func (r *PacketReaderWriter) Close() error {
+	return r.rw.Close()
+}
+
+// readLengthPrefix reads the length prefix.
+func (r *PacketReaderWriter) readLengthPrefix(b []byte) uint32 {
+	if len(b) < 4 {
+		return 0
+	}
+	return binary.LittleEndian.Uint32(b)
+}
+
+// _ is a type assertion
+var _ Writer = (*PacketReaderWriter)(nil)

package/srpc/packet.go

@@ -0,0 +1,71 @@
+package srpc
+
+// PacketHandler handles a packet.
+type PacketHandler = func(pkt *Packet) error
+
+// Validate performs cursory validation of the packet.
+func (p *Packet) Validate() error {
+	switch b := p.GetBody().(type) {
+	case *Packet_CallStart:
+		return b.CallStart.Validate()
+	case *Packet_CallData:
+		return b.CallData.Validate()
+	case *Packet_CallStartResp:
+		return b.CallStartResp.Validate()
+	default:
+		return ErrUnrecognizedPacket
+	}
+}
+
+// NewCallStartPacket constructs a new CallStart packet.
+func NewCallStartPacket(service, method string, data []byte) *Packet {
+	return &Packet{Body: &Packet_CallStart{
+		CallStart: &CallStart{
+			RpcService: service,
+			RpcMethod:  method,
+			Data:       data,
+		},
+	}}
+}
+
+// Validate performs cursory validation of the packet.
+func (p *CallStart) Validate() error {
+	method := p.GetRpcMethod()
+	if len(method) == 0 {
+		return ErrEmptyMethodID
+	}
+	service := p.GetRpcService()
+	if len(service) == 0 {
+		return ErrEmptyServiceID
+	}
+	return nil
+}
+
+// NewCallDataPacket constructs a new CallData packet.
+func NewCallDataPacket(data []byte, complete bool, err error) *Packet {
+	var errStr string
+	if err != nil {
+		errStr = err.Error()
+	}
+	return &Packet{Body: &Packet_CallData{
+		CallData: &CallData{
+			Data:     data,
+			Complete: err != nil || complete,
+			Error:    errStr,
+		},
+	}}
+}
+
+// Validate performs cursory validation of the packet.
+func (p *CallData) Validate() error {
+	if len(p.GetData()) == 0 && !p.GetComplete() && len(p.GetError()) == 0 {
+		return ErrEmptyPacket
+	}
+	return nil
+}
+
+// Validate performs cursory validation of the packet.
+func (p *CallStartResp) Validate() error {
+	// nothing to check, empty packet is valid.
+	return nil
+}