drpc

package module

v0.0.34 Latest Latest Go to latest Published: Mar 12, 2024 License: MIT Imports: 3 Imported by: 129

README ¶

A drop-in, lightweight gRPC replacement.

Links

Highlights

Simple, at just a few thousand lines of code.
Small dependencies. Only 3 requirements in go.mod, and 9 lines of go mod graph!
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.
Battle Tested. Already used in production for years across tens of thousands of servers.

External Packages

go.bryk.io/pkg/net/drpc
- Simplified TLS setup (for client and server)
- Server middleware, including basic components for logging, token-based auth, rate limit, panic recovery, etc
- Client middleware, including basic components for logging, custom metadata, panic recovery, etc
- Bi-directional streaming support over upgraded HTTP(S) connections using WebSockets
- Concurrent RPCs via connection pool
go.elara.ws/drpc
- Concurrent RPCs based on yamux
- Simple drop-in replacements for drpcserver and drpcconn
Open an issue or join the Zulip chat if you'd like to be featured here.

Examples

Other Languages

DRPC can be made compatible with RPC clients generated from other languages. For example, Twirp clients and grpc-web clients can be used against the drpchttp package.

Native implementations can have some advantages, and so some support for other languages are in progress, all in various states of completeness. Join the Zulip chat if you want more information or to help out with any!

Language	Repository	Status
C++	https://github.com/storj/drpc-cpp	Incomplete
Rust	https://github.com/zeebo/drpc-rs	Incomplete
Node	https://github.com/mjpitz/drpc-node	Incomplete

Licensing

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

Benchmarks

These microbenchmarks attempt to provide a comparison and come with some caveats. First, it does not send data over a network connection which is expected to be the bottleneck almost all of the time. Second, no attempt was made to do the benchmarks in a controlled environment (CPU scaling disabled, noiseless, etc.). Third, no tuning was done to ensure they're both performing optimally, so there is an inherent advantage for DRPC because the author is familiar with how it works.

Measure

Benchmark

Small

Medium

Large

gRPC

DRPC

delta

gRPC

DRPC

delta

gRPC

DRPC

delta

time/op

Unitary

24.5µs

6.1µs

-74.87%

32.4µs

8.8µs

-72.89%

1.43ms

0.58ms

-59.47%

Input Stream

745ns

528ns

-29.13%

2.63µs

1.46µs

-44.66%

512µs

236µs

-53.89%

Output Stream

711ns

532ns

-25.11%

2.63µs

1.51µs

-42.59%

515µs

210µs

-59.26%

Bidir Stream

7.29µs

2.52µs

-65.46%

12.3µs

3.9µs

-68.68%

1.44ms

0.44ms

-69.05%

speed

Unitary

80.0kB/s

325.0kB/s

+306.25%

63.4MB/s

234.3MB/s

+269.56%

734MB/s

1812MB/s

+146.99%

Input Stream

2.69MB/s

3.79MB/s

+41.00%

780MB/s

1409MB/s

+80.67%

2.05GB/s

4.45GB/s

+117.12%

Output Stream

2.81MB/s

3.76MB/s

+33.52%

780MB/s

1360MB/s

+74.23%

2.04GB/s

5.01GB/s

+145.53%

Bidir Stream

274kB/s

794kB/s

+189.95%

166MB/s

533MB/s

+220.19%

730MB/s

2360MB/s

+223.10%

mem/op

Unitary

8.66kB

1.42kB

-83.62%

22.2kB

7.8kB

-64.83%

6.61MB

3.16MB

-52.21%

Input Stream

381B

80B

-79.01%

7.08kB

2.13kB

-69.95%

3.20MB

1.05MB

-67.17%

Output Stream

305B

80B

-73.80%

7.00kB

2.13kB

-69.62%

3.20MB

1.05MB

-67.19%

Bidir Stream

1.00kB

0.24kB

-75.90%

14.5kB

4.3kB

-70.10%

6.61MB

2.10MB

-68.20%

allocs/op

Unitary

168

7

-95.83%

170

9

-94.71%

400

9

-97.75%

Input Stream

9

1

-88.89%

10

2

-80.00%

118

2

-98.31%

Output Stream

9

1

-88.89%

10

2

-80.00%

120

2

-98.33%

Bidir Stream

39

3

-92.31%

42

5

-88.10%

277

5

-98.20%

Lines of code

DRPC is proud to get as much done in as few lines of code as possible. It's the author's belief that this is only possible by having a clean, strong architecture and that it reduces the chances for bugs to exist (most studies show a linear corellation with number of bugs and lines of code). This table helps keep the library honest, and it would be nice if more libraries considered this.

Package	Lines
storj.io/drpc/drpchttp	478
storj.io/drpc/drpcstream	470
storj.io/drpc/cmd/protoc-gen-go-drpc	424
storj.io/drpc/drpcmanager	374
storj.io/drpc/drpcwire	362
storj.io/drpc/drpcpool	276
storj.io/drpc/drpcmigrate	239
storj.io/drpc/drpcserver	161
storj.io/drpc/drpcsignal	133
storj.io/drpc/drpcconn	116
storj.io/drpc/drpcmetadata	115
storj.io/drpc/drpcmux	95
storj.io/drpc/drpccache	54
storj.io/drpc	47
storj.io/drpc/drpctest	45
storj.io/drpc/drpcerr	42
storj.io/drpc/drpcctx	41
storj.io/drpc/internal/drpcopts	27
storj.io/drpc/drpcstats	25
storj.io/drpc/drpcdebug	22
storj.io/drpc/drpcenc	15
Total	3561

Documentation ¶

Overview ¶

Package drpc is a light replacement for gprc.

Constants ¶

This section is empty.

Variables ¶

View Source

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

These error classes represent some common errors that drpc generates.

Functions ¶

This section is empty.

Types ¶

type Conn ¶

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

	// Closed returns a channel that is closed if the connection is definitely closed.
	Closed() <-chan struct{}

	// 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 ¶ added in v0.0.18

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
}

Encoding represents a way to marshal/unmarshal Message types.

type Handler ¶

type Handler interface {
	// HandleRPC executes the RPC identified by the rpc string using the stream to
	// communicate with the remote.
	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 ¶ added in v0.0.10

type Mux interface {
	// Register marks that the description should dispatch RPCs that it describes to
	// the provided srv.
	Register(srv interface{}, desc Description) error
}

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

type Receiver ¶ added in v0.0.10

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. Any net.Conn can be used as a Transport.

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
cmd
protoc-gen-go-drpc command protoc-gen-go-drpc generates DRPC code for protobuf services.	protoc-gen-go-drpc generates DRPC code for protobuf services.
drpccache Package drpccache implements per stream cache for drpc.	Package drpccache implements per stream cache for drpc.
drpcconn Package drpcconn creates a drpc client connection from a transport.	Package drpcconn creates a drpc client connection from a transport.
drpcctx Package drpcctx has helpers to interact with context.Context.	Package drpcctx has helpers to interact with context.Context.
drpcdebug Package drpcdebug provides helpers for debugging.	Package drpcdebug provides helpers for debugging.
drpcenc Package drpcenc holds some helper functions for encoding messages.	Package drpcenc holds some helper functions for encoding messages.
drpcerr Package drpcerr lets one associate error codes with errors.	Package drpcerr lets one associate error codes with errors.
drpchttp Package drpchttp implements a net/http handler for unitary RPCs.	Package drpchttp implements a net/http handler for unitary RPCs.
drpcmanager Package drpcmanager reads packets from a transport to make streams.	Package drpcmanager reads packets from a transport to make streams.
drpcmetadata Package drpcmetadata define the structure of the metadata supported by drpc library.	Package drpcmetadata define the structure of the metadata supported by drpc library.
drpcmigrate Package drpcmigrate provides tools to support drpc concurrently alongside gRPC on the same ports.	Package drpcmigrate provides tools to support drpc concurrently alongside gRPC on the same ports.
drpcmux Package drpcmux is a handler to dispatch rpcs to implementations.	Package drpcmux is a handler to dispatch rpcs to implementations.
drpcpool Package drpcpool is a simple connection pool for clients.	Package drpcpool is a simple connection pool for clients.
drpcserver Package drpcserver allows one to execute registered rpcs.	Package drpcserver allows one to execute registered rpcs.
drpcsignal Package drpcsignal holds a helper type to signal errors.	Package drpcsignal holds a helper type to signal errors.
drpcstats Package drpcstats contatins types for stat collection.	Package drpcstats contatins types for stat collection.
drpcstream Package drpcstream sends protobufs using the dprc wire protocol.	Package drpcstream sends protobufs using the dprc wire protocol.
drpctest Package drpctest provides test related helpers.	Package drpctest provides test related helpers.
drpcwire Package drpcwire provides low level helpers for the drpc wire protocol.	Package drpcwire provides low level helpers for the drpc wire protocol.
examples
drpc module
drpc_and_http module
grpc module
grpc_and_drpc module
opentelemetry module
internal
drpcopts Package drpcopts contains internal options.	Package drpcopts contains internal options.
backcompat module
backcompat/newservice module
backcompat/newservicedefs module
backcompat/oldservice module
backcompat/oldservicedefs module
backcompat/servicedefs module
grpccompat module
integration module
twirpcompat module

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL