consistent

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:

1. Register the balancer (typically in main):

balancer.Register(consistent.NewBuilder(xxhash.Sum64))

1. 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
• Variables
• type BalancerConfig
  • func (c *BalancerConfig) MustServiceConfigJSON() string
  • func (c *BalancerConfig) ServiceConfigJSON() (string, error)
• type Builder
  • func NewBuilder(hashfn hashring.HashFunc) Builder

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

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
}

Builder combines both of gRPC's `balancer.Builder` and `balancer.ConfigParser` interfaces.

func NewBuilder

func NewBuilder(hashfn hashring.HashFunc) Builder

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