drpc

README

A drop-in, lightweight gRPC replacement.

DRPC is:

• Compatible with your existing gRPC protocol buffer definitions
• Simple, at just ~3500 lines of code!
• Compatible. Works for many gRPC use-cases as-is!
• Fast. DRPC has a lightning quick wire format
• Extensible. DRPC is transport agnostic, supports middleware, and is designed around interfaces.

Licensing

DRPC is licensed under the MIT/expat license. See the LICENSE file for more.

Documentation

Overview

Package drpc is a light replacement for gprc.

Index

• Variables
• type Conn
• type Description
• type Encoding
• type Handler
• type Message
• type Mux
• type Receiver
• type Stream
• type Transport

Variables

var (
	Error         = errs.Class("drpc")
	InternalError = errs.Class("internal error")
	ProtocolError = errs.Class("protocol error")
)

These error classes represent some common errors that drpc generates.

Types

type Conn

type Conn interface {
	// Close closes the connection.
	Close() error

	// Closed returns true if the connection is definitely closed.
	Closed() bool

	// Transport returns the transport the connection is using.
	Transport() Transport

	// Invoke issues a unary rpc to the remote. Only one Invoke or Stream may be
	// open at once.
	Invoke(ctx context.Context, rpc string, enc Encoding, in, out Message) error

	// NewStream starts a stream with the remote. Only one Invoke or Stream may be
	// open at once.
	NewStream(ctx context.Context, rpc string, enc Encoding) (Stream, error)
}

Conn represents a client connection to a server.

type Description

type Description interface {
	// NumMethods returns the number of methods available.
	NumMethods() int

	// Method returns the information about the nth method along with a handler
	// to invoke it. The method interface that it returns is expected to be
	// a method expression like `(*Type).HandlerName`.
	Method(n int) (rpc string, encoding Encoding, receiver Receiver, method interface{}, ok bool)
}

Description is the interface implemented by things that can be registered by a Server.

type Encoding

type Encoding interface {
	// Marshal returns the encoded form of msg.
	Marshal(msg Message) ([]byte, error)

	// Unmarshal reads the encoded form of some Message into msg.
	// The buf is expected to contain only a single complete Message.
	Unmarshal(buf []byte, msg Message) error

	// JSONMarshal returns the json encoded form of msg.
	JSONMarshal(msg Message) ([]byte, error)

	// JSONUnmarshal reads the json encoded form of some Message into msg.
	// The buf is expected to contain only a single complete Message.
	JSONUnmarshal(buf []byte, msg Message) error
}

Encoding represents a way to marshal/unmarshal Message types.

type Handler

type Handler interface {
	HandleRPC(stream Stream, rpc string) (err error)
}

Handler handles streams and rpcs dispatched to it by a Server.

type Message

type Message interface{}

Message is a protobuf message. It is expected to be used with an Encoding. This exists so that one can use whatever protobuf library/runtime they want.

type Mux

type Mux interface {
	Register(srv interface{}, desc Description) error
}

Mux is a type that can have an implementation and a Description registered with it.

type Receiver

type Receiver = func(srv interface{}, ctx context.Context, in1, in2 interface{}) (out Message, err error)

Receiver is invoked by a server for a given rpc.

type Stream

type Stream interface {
	// Context returns the context associated with the stream. It is canceled
	// when the Stream is closed and no more messages will ever be sent or
	// received on it.
	Context() context.Context

	// MsgSend sends the Message to the remote.
	MsgSend(msg Message, enc Encoding) error

	// MsgRecv receives a Message from the remote.
	MsgRecv(msg Message, enc Encoding) error

	// CloseSend signals to the remote that we will no longer send any messages.
	CloseSend() error

	// Close closes the stream.
	Close() error
}

Stream is a bi-directional stream of messages to some other party.

type Transport

type Transport interface {
	io.Reader
	io.Writer
	io.Closer
}

Transport is an interface describing what is required for a drpc connection.