cluster

Documentation

Overview

Package cluster implements an almost drop-in replacement for a normal Client which accounts for a redis cluster setup. It will transparently redirect requests to the correct nodes, as well as keep track of which slots are mapped to which nodes and updating them accordingly so requests can remain as fast as possible.

This package will initially call `cluster slots` in order to retrieve an initial idea of the topology of the cluster, but other than that will not make any other extraneous calls.

All methods on a Cluster are thread-safe, and connections are automatically pooled

Index

• Constants
• Variables
• func CRC16(buf []byte) uint16
• func Slot(key string) uint16
• type Cluster
  • func New(addr string) (*Cluster, error)
  • func NewWithOpts(o Opts) (*Cluster, error)
  • func (c *Cluster) Close()
  • func (c *Cluster) Cmd(cmd string, args ...interface{}) *redis.Resp
  • func (c *Cluster) GetAddrForKey(key string) string
  • func (c *Cluster) GetEvery() (map[string]*redis.Client, error)
  • func (c *Cluster) GetEveryAvail() map[string]int
  • func (c *Cluster) GetForKey(key string) (*redis.Client, error)
  • func (c *Cluster) Put(conn *redis.Client)
  • func (c *Cluster) Reset() error
• type DialFunc
• type Opts

Constants

const NumSlots = 16384

NumSlots is the number of slots keys are sharded into in a redis cluster

Variables

var (
	// ErrBadCmdNoKey is an error reply returned when no key is given to the Cmd
	// method
	ErrBadCmdNoKey = errors.New("bad command, no key")
)

Functions

func CRC16

func CRC16(buf []byte) uint16

CRC16 returns checksum for a given set of bytes based on the crc algorithm defined for hashing redis keys in a cluster setup

func Slot

func Slot(key string) uint16

Slot returns the cluster slot the given key will fall into, taking into account curly braces within the key as per the spec.

Types

type Cluster

type Cluster struct {

	// This is written to whenever a slot miss (either a MOVED or ASK) is
	// encountered. This is mainly for informational purposes, it's not meant to
	// be actionable. If nothing is listening the message is dropped
	MissCh chan struct{}

	// This is written to whenever the cluster discovers there's been some kind
	// of re-ordering/addition/removal of cluster nodes. If nothing is listening
	// the message is dropped
	ChangeCh chan struct{}
	// contains filtered or unexported fields
}

Cluster wraps a Client and accounts for all redis cluster logic

func New

func New(addr string) (*Cluster, error)

New will perform the following steps to initialize:

- Connect to the node given in the argument

- Use that node to call CLUSTER SLOTS. The return from this is used to build a mapping of slot number -> connection. At the same time any new connections which need to be made are created here.

- *Cluster is returned

At this point the Cluster has a complete view of the cluster's topology and can immediately start performing commands with (theoretically) zero slot misses

func NewWithOpts

func NewWithOpts(o Opts) (*Cluster, error)

NewWithOpts is the same as NewCluster, but with more fine-tuned configuration options. See Opts for more available options

func (*Cluster) Close

func (c *Cluster) Close()

Close calls Close on all connected clients. Once this is called no other methods should be called on this instance of Cluster

func (*Cluster) Cmd

func (c *Cluster) Cmd(cmd string, args ...interface{}) *redis.Resp

Cmd performs the given command on the correct cluster node and gives back the command's reply. The command *must* have a key parameter (i.e. len(args) >= 1). If any MOVED or ASK errors are returned they will be transparently handled by this method.

NOTE if you're doing any lua or scan operations through this method you might save yourself some time and effort by checking out the LuaEval and NewScanner functions in the util package. They properly handle the cluster client being used.

func (*Cluster) GetAddrForKey

func (c *Cluster) GetAddrForKey(key string) string

GetAddrForKey returns the address which would be used to handle the given key in the cluster.

func (*Cluster) GetEvery

func (c *Cluster) GetEvery() (map[string]*redis.Client, error)

GetEvery returns a single *redis.Client per master that the cluster currently knows about. The map returned maps the address of the client to the client itself. If there is an error retrieving any of the clients (for instance if a new connection has to be made to get it) only that error is returned. Each client must be returned back to its pools using Put when through

func (*Cluster) GetEveryAvail

func (c *Cluster) GetEveryAvail() map[string]int

GetEveryAvail returns a mapping of every master address to the results of calling Avail on that instance's Pool instance. See pool.Avail for specifics on what Avail means.

func (*Cluster) GetForKey

func (c *Cluster) GetForKey(key string) (*redis.Client, error)

GetForKey returns the Client which *ought* to handle the given key, based on Cluster's understanding of the cluster topology at the given moment. If the slot isn't known or there is an error contacting the correct node, a random client is returned. The client must be returned back to its pool using Put when through

func (*Cluster) Put

func (c *Cluster) Put(conn *redis.Client)

Put putss the connection back in its pool. To be used alongside any of the Get* methods once use of the redis.Client is done

func (*Cluster) Reset

func (c *Cluster) Reset() error

Reset will re-retrieve the cluster topology and set up/teardown connections as necessary. It begins by calling CLUSTER SLOTS on a random known connection. The return from that is used to re-create the topology, create any missing clients, and close any clients which are no longer needed.

This call is inherently throttled, so that multiple clients can call it at the same time and it will only actually occur once (subsequent clients will have nil returned immediately).

type DialFunc

type DialFunc func(network, addr string) (*redis.Client, error)

DialFunc is a function which can be incorporated into Opts. Note that network will always be "tcp" in Cluster.

type Opts

type Opts struct {

	// Required. The address of a single node in the cluster
	Addr string

	// Read and write timeout which should be used on individual redis clients.
	// Default is to not set the timeout and let the connection use it's
	// default. This will be ignored if the Dialer field is set.
	Timeout time.Duration

	// The size of the connection pool to use for each host. Default is 10
	PoolSize int

	// PoolOpts contain optional Opt's to pass to pool.NewCustom
	PoolOpts []pool.Opt

	// The time which must elapse between subsequent calls to create a new
	// connection pool (on a per redis instance basis) in certain circumstances.
	// The default is 500 milliseconds
	PoolThrottle time.Duration

	// The time which must elapse between subsequent calls to Reset(). The
	// default is 500 milliseconds
	ResetThrottle time.Duration

	// The function which will be used to create connections within the pool for
	// each redis cluster instance. The common use-case is to do authentication
	// for new connections. Defaults to using redis.DialTimeout if not set.
	Dialer DialFunc

	// The maximimum number of times the cluster will allow a command to be
	// redirected to another instance via a MOVED or ASK error before giving up
	// on that command. Defaults to 2.
	MaxRedirectCount int
}

Opts are Options which can be passed in to NewWithOpts. If any are set to their zero value the default value will be used instead