README
¶
consistent
This package implements a gRPC Balancer that routes requests based upon a consistent hashring. The hashing algorithm is customizable, but xxhash is recommended. It was originally built to serve SpiceDB, but has been extracted from that repository to be made available for other projects.
In order to use this balancer, you must:
- Register the balancer (typically in
main):
balancer.Register(consistent.NewBuilder(xxhash.Sum64))
- Configure the connections:
// This is using the defaults, but you can create your own config.
grpc.Dial(addr, grpc.WithDefaultServiceConfig(consistent.DefaultServiceConfigJSON))
Acknowledgements
This project is a community effort fueled by contributions from both organizations and individuals. We appreciate all contributions, large and small, and would like to thank all those involved.
A large portion of the structure of this library is based off of the example implementation in grpc-go. That original work is copyrighted by the gRPC authors and licensed under the Apache License, Version 2.0.
Documentation
¶
Overview ¶
Package consistent implements a gRPC Balancer that routes requests based upon a consistent hashring.
The hashing algorithm is customizable, but xxhash is recommended.
A large portion of the structure of this library is based off of the example implementation in grpc-go. That original work is copyrighted by the gRPC authors and licensed under the Apache License, Version 2.0.
This package relies on the synchronization guarantees provided by `ccBalancerWrapper`, an upstream type that serializes calls to the balancer.
Index ¶
Constants ¶
const ( // BalancerName is the name used to identify this implementation of a // consistent-hashring balancer to gRPC. BalancerName = "consistent-hashring" // CtxKey is the key that will be present in each gRPC request's context // that points to the value that will be hashed in order to map the request // to the hashring. // // The value stored at this key must be []byte. CtxKey ctxKey = "requestKey" // DefaultReplicationFactor is the value that will be used when parsing a // service config provides an invalid value. DefaultReplicationFactor = 100 // DefaultSpread is the value that will be used when parsing a service // config provides an invalid value. DefaultSpread = 1 )
Variables ¶
var DefaultServiceConfigJSON = (&BalancerConfig{ ReplicationFactor: DefaultReplicationFactor, Spread: DefaultSpread, }).MustServiceConfigJSON()
DefaultServiceConfigJSON is a helper to easily leverage the defaults.
Here's an example: ```go grpc.Dial(addr, grpc.WithDefaultServiceConfig(consistent.DefaultServiceConfigJSON)) ```
var ErrNoRing = errors.New("no hashring available for target")
ErrNoRing means that no hashring exists for the target. gRPC builds balancers lazily, so before the first connection attempt there is no ring to read. A closed balancer also withdraws its ring.
Functions ¶
This section is empty.
Types ¶
type BalancerConfig ¶
type BalancerConfig struct {
serviceconfig.LoadBalancingConfig `json:"-"`
ReplicationFactor uint16 `json:"replicationFactor,omitempty"`
Spread uint8 `json:"spread,omitempty"`
}
BalancerConfig exposes the configurable aspects of the balancer.
This type is meant to be used with `grpc.WithDefaultServiceConfig()` through the `ServiceConfigJSON()` or `MustServiceConfigJSON()` methods.
If you're unsure of what values to use in this configuration, use `DefaultBalancerConfig`.
func (*BalancerConfig) MustServiceConfigJSON ¶
func (c *BalancerConfig) MustServiceConfigJSON() string
MustServiceConfigJSON calls ServiceConfigJSON, but panics if there is an error.
func (*BalancerConfig) ServiceConfigJSON ¶
func (c *BalancerConfig) ServiceConfigJSON() (string, error)
ServiceConfigJSON encodes the current config into the gRPC Service Config JSON format.
type Builder ¶
type Builder interface {
balancer.Builder
balancer.ConfigParser
// RingFor returns a read-only view of the live hashring that routes
// requests to the given target. The target is the string form of the
// dial target, for example "kubernetes:///spicedb.default:50053".
//
// The returned view is always non-nil, and callers can get it before any
// balancer for the target exists. Its methods return ErrNoRing (or no
// members) until the balancer produces a ring. ClientConns that share a
// target string share one view, and the last writer wins.
RingFor(target string) RingView
}
Builder combines gRPC's `balancer.Builder` and `balancer.ConfigParser` interfaces. It also exposes read-only views of the hashrings of the balancers it builds.
func NewBuilder ¶
NewBuilder allocates a new gRPC balancer.Builder that will route traffic according to a hashring configured with the provided hash function.
The following is an example usage: ```go balancer.Register(consistent.NewBuilder(xxhash.Sum64)) ```
type RingView ¶ added in v0.4.0
type RingView interface {
// FindN returns the first n unique members of the ring for the given key,
// exactly as the balancer's picker sees them. It returns ErrNoRing if no
// ring exists yet for the target.
FindN(key []byte, n uint8) ([]hashring.Member, error)
// Members returns all members currently on the ring. It returns nil if
// no ring exists yet for the target.
Members() []hashring.Member
}
RingView is a read-only view of the live hashring a balancer routes with.
A view is a stable handle. It follows the balancer's ring across replacements (a ReplicationFactor change replaces the ring) and it shows membership changes as they happen. Queries through a view therefore agree with the picker's routing decisions. The one exception is a membership change that races the query: that can misplace a request's locality, never its delivery.
Source Files
Directories