DRPC Documentation

DRPC is a lightweight, high-performance replacement for gRPC. It is designed to be transport-agnostic, extensible via middleware, and compatible with many existing gRPC use cases. Key features include:

• Simplicity: A small codebase with minimal dependencies.
• Performance: A lightning-fast wire format that outperforms gRPC in microbenchmarks for latency, throughput, and memory allocation.
• Extensibility: Built around interfaces and supports middleware for various tasks.
• Compatibility: Can be made compatible with RPC clients from other languages (like Twirp or gRPC-web) using the drpchttp package.

The drpcstats package provides the Stats type, which is used to track the number of bytes read and written. It is designed for concurrent use, providing atomic updates to its counters.

import "storj.io/drpc/drpcstats"

// Stats keeps counters of read and written bytes.
type Stats struct {
	Read    uint64
	Written uint64
}

The drpcpool package provides a simple connection pool for DRPC clients. It manages a cache of connections with configurable limits on total capacity and per-key capacity. It also supports automatic expiration of connections that have been inactive in the pool for a specified duration.

To use it, import: import "storj.io/drpc/drpcpool"

The drpcmanager package provides a Manager type that handles the lifecycle of a drpc.Transport. It ensures the connection is continuously read from, manages stream forwarding, and handles closing the transport. You can use it to manage transports for both DRPC clients and servers.

To create a manager, use New(tr drpc.Transport) or NewWithOptions(tr drpc.Transport, opts Options) for more granular control.

The Signal type is a helper for capturing a single error and providing multiple ways to inspect or wait for it. It is particularly useful for coordinating goroutines where one might fail and others need to be notified.

Key behaviors:

• First error wins: Set(err error) only keeps track of the first error set. It returns true if it was the first error set, and false otherwise.
• Error vs. Set status: A non-nil error returned by Err() means the signal has been set, but a nil error does not necessarily mean the signal is unset (the signal could have been set with a nil error). Always use IsSet() or Get() to check if the signal has been triggered.

The drpcmigrate package allows you to multiplex a single network listener so that it can handle both DRPC and gRPC (or other protocols) on the same port. This is achieved by inspecting the first few bytes of a connection to determine which protocol it belongs to.

To implement this, use a ListenMux to route incoming connections based on a specific prefix. For DRPC, the package provides a predefined DRPCHeader constant designed to avoid conflicts with headerless gRPC, HTTP, or TLS requests.

Metadata is attached to requests using the X-Drpc-Metadata header. This header can be provided multiple times. The format for each header is:

X-Drpc-Metadata: percentEncode(key)=percentEncode(value)

Note that only the % and = characters must be percent-encoded.