balancertesting

Documentation

Overview

Package balancertesting provides some helper functions and types that can be useful when testing custom load balancer implementations.

Index

• func DeterministicReconciler(newAddrs []resolver.Address, removeConns []conn.Conn)
• func FindConn(set conns.Set, addr resolver.Address, index int) conn.Conn
• func NewFakePicker(_ picker.Picker, connections conn.Conns) picker.Picker
• type ConnHealth
  • func (ch ConnHealth) AsSet() conns.Set
• type FakeConn
  • func (c *FakeConn) Address() resolver.Address
  • func (c *FakeConn) Prewarm(ctx context.Context) error
  • func (c *FakeConn) RoundTrip(*http.Request, func()) (*http.Response, error)
  • func (c *FakeConn) Scheme() string
  • func (c *FakeConn) UpdateAttributes(values attribute.Values)
• type FakeConnPool
  • func NewFakeConnPool() *FakeConnPool
  • func (p *FakeConnPool) AwaitConnUpdate(ctx context.Context) (conns.Set, error)
  • func (p *FakeConnPool) AwaitPickerUpdate(ctx context.Context) (PickerState, error)
  • func (p *FakeConnPool) AwaitResolveNow(ctx context.Context) (int, error)
  • func (p *FakeConnPool) Conns() conn.Conns
  • func (p *FakeConnPool) NewConn(address resolver.Address) (conn.Conn, bool)
  • func (p *FakeConnPool) RemoveConn(toRemove conn.Conn) bool
  • func (p *FakeConnPool) ResolveNow()
  • func (p *FakeConnPool) SnapshotConns() conns.Set
  • func (p *FakeConnPool) UpdatePicker(picker picker.Picker, isWarm bool)
• type FakeHealthChecker
  • func NewFakeHealthChecker() *FakeHealthChecker
  • func (hc *FakeHealthChecker) AwaitCheckerUpdate(ctx context.Context) (ConnHealth, error)
  • func (hc *FakeHealthChecker) AwaitConnectionInitialized(ctx context.Context, connection conn.Conn) (health.State, error)
  • func (hc *FakeHealthChecker) New(_ context.Context, connection conn.Conn, tracker health.Tracker) io.Closer
  • func (hc *FakeHealthChecker) SetInitialState(state health.State)
  • func (hc *FakeHealthChecker) SnapshotConns() ConnHealth
  • func (hc *FakeHealthChecker) UpdateHealthState(connection conn.Conn, state health.State)
• type FakePicker
  • func (p *FakePicker) Pick(*http.Request) (conn conn.Conn, whenDone func(), err error)
• type PickerState

Functions

func DeterministicReconciler

func DeterministicReconciler(newAddrs []resolver.Address, removeConns []conn.Conn)

DeterministicReconciler sorts the given slices, which are used by a balancer when reconciling connections. Sorting them guarantees that reconciliation activity is deterministic, making test assertions simpler.

func FindConn

func FindConn(set conns.Set, addr resolver.Address, index int) conn.Conn

FindConn finds the connection with the given address and index in the given conn.Set. returns nil if no such connection can be found.

func NewFakePicker

func NewFakePicker(_ picker.Picker, connections conn.Conns) picker.Picker

NewFakePicker constructs a new FakePicker with the given connections.

The return type is picker.Picker so this function can be directly used as a "new picker" function with a balancer. But this function always returns values whose type is *FakePicker.

Types

type ConnHealth

type ConnHealth map[conn.Conn]health.State

ConnHealth is map that tracks the health state of connections.

func (ConnHealth) AsSet

func (ch ConnHealth) AsSet() conns.Set

type FakeConn

type FakeConn struct {
	Index int
	// contains filtered or unexported fields
}

FakeConn is an implementation of conn.Conn that can be used for testing. It is not usable for actual request traffic: attempts to call its RoundTrip method will always result in error.

To create new instances of FakeConn, use a FakeConnPool.

func (*FakeConn) Address

func (c *FakeConn) Address() resolver.Address

Address implements the conn.Conn interface. It returns the resolved address associated with this connection.

func (*FakeConn) Prewarm

func (c *FakeConn) Prewarm(ctx context.Context) error

Prewarm implements the conn.Conn interface. For a FakeConn, it will call the FakeConnPool's Prewarm function, if it was set. Otherwise, it returns nil immediately.

func (*FakeConn) RoundTrip

func (c *FakeConn) RoundTrip(*http.Request, func()) (*http.Response, error)

RoundTrip implements the conn.Conn interface. For a FakeConn, it always returns an error as a FakeConn is not meant for real requests.

func (*FakeConn) Scheme

func (c *FakeConn) Scheme() string

Scheme implements the conn.Conn interface. For a FakeConn, it always returns "http".

func (*FakeConn) UpdateAttributes

func (c *FakeConn) UpdateAttributes(values attribute.Values)

UpdateAttributes implements the conn.Conn interface. It updates the attributes on this connection's associated address.

type FakeConnPool

type FakeConnPool struct {
	// Prewarm can be set to a function that is invoked by the Prewarm
	// method of connections created by this pool. It should be set
	// immediately after the pool is created, before any connections
	// are created, to avoid races.
	Prewarm func(conn.Conn, context.Context) error // +checklocksignore: mu is not required, but happens to always be held.
	// contains filtered or unexported fields
}

FakeConnPool is an implementation of balancer.ConnPool that can be used for testing balancer.Balancer implementations. It marks the connections created with its NewConn method with an index in sequential order. So the first connection created is a *FakeConn with an Index of 1. The second will have Index 2, and so on.

See NewFakeConnPool.

func NewFakeConnPool

func NewFakeConnPool() *FakeConnPool

NewFakeConnPool constructs a new FakeConnPool.

func (*FakeConnPool) AwaitConnUpdate

func (p *FakeConnPool) AwaitConnUpdate(ctx context.Context) (conns.Set, error)

AwaitConnUpdate waits for concurrent changes to the set of active connections, via calls to NewConn and RemoveConn. It may return immediately if there was a past call to NewConn or RemoveConn that has yet to be acknowledged via a call to this method. It returns a snapshot of the connections on success. If returns an error if the given context is cancelled or times out before the connections are updated.

func (*FakeConnPool) AwaitPickerUpdate

func (p *FakeConnPool) AwaitPickerUpdate(ctx context.Context) (PickerState, error)

AwaitPickerUpdate waits for a concurrent call to UpdatePicker. It may return immediately if there was a past call to UpdatePicker that has yet to be acknowledged via a call to this method. If the pool's current picker is a *FakePicker, then the returned state also includes a snapshot of the connections used to create the picker. If the pickers is not a *FakePicker, the returned state's SnapshotConns field will be nil. An error is returned if the given context is cancelled or times out before the picker is updated.

func (*FakeConnPool) AwaitResolveNow

func (p *FakeConnPool) AwaitResolveNow(ctx context.Context) (int, error)

AwaitResolveNow waits for a concurrent call to ResolveNow, usually called by the balancer when the number of healthy connections is running below the threshold. If the context is cancelled before the ResolveNow method is called, this function returns the context error. If it succeeds, it will return the number of times ResolveNow has been called.

func (*FakeConnPool) Conns

func (p *FakeConnPool) Conns() conn.Conns

GetConns implements the balancer.ConnPool interface. It returns a snapshot of the pool's set of active connections.

func (*FakeConnPool) NewConn

func (p *FakeConnPool) NewConn(address resolver.Address) (conn.Conn, bool)

NewConn implements the balancer.ConnPool interface. It always returns *FakeConn instances. Test code can asynchronously await a call to NewConn or RemoveConn using the AwaitConnUpdate method.

func (*FakeConnPool) RemoveConn

func (p *FakeConnPool) RemoveConn(toRemove conn.Conn) bool

RemoveConn implements the balancer.ConnPool interface. Test code can asynchronously await a call to NewConn or RemoveConn using the AwaitConnUpdate method.

func (*FakeConnPool) ResolveNow

func (p *FakeConnPool) ResolveNow()

ResolveNow implements the balancer.ConnPool interface. It increments a counter that can be introspected.

func (*FakeConnPool) SnapshotConns

func (p *FakeConnPool) SnapshotConns() conns.Set

SnapshotConns returns a snapshot of the current active connections. This will include all connections created via NewConn but not yet removed via RemoveConn.

func (*FakeConnPool) UpdatePicker

func (p *FakeConnPool) UpdatePicker(picker picker.Picker, isWarm bool)

UpdatePicker implements the balancer.ConnPool interface. Test code can asynchronously await a call to UpdatePicker using the AwaitPickerUpdate method.

type FakeHealthChecker

type FakeHealthChecker struct {
	// contains filtered or unexported fields
}

FakeHealthChecker is an implementation of healthchecker.Checker that can be used for testing balancer.Balancer implementations. It tracks the connections for which check processes are active (created with New but not closed). By default, all connections will be immediately healthy, but SetInitialState can be used to change that.

See NewFakeHealthChecker.

func NewFakeHealthChecker

func NewFakeHealthChecker() *FakeHealthChecker

NewFakeHealthChecker creates a new FakeHealthChecker.

func (*FakeHealthChecker) AwaitCheckerUpdate

func (hc *FakeHealthChecker) AwaitCheckerUpdate(ctx context.Context) (ConnHealth, error)

AwaitCheckerUpdate waits for the set of checked connections to change. This will return after a call to New or after a process is closed. It may return immediately if there was a past call to New or to a process's Close that has yet to be acknowledged via a call to this method. It returns a snapshot of the connections and their latest health state on success. It returns an error if the given context is cancelled or times out before any connection checks are created or closed.

func (*FakeHealthChecker) AwaitConnectionInitialized

func (hc *FakeHealthChecker) AwaitConnectionInitialized(ctx context.Context, connection conn.Conn) (health.State, error)

AwaitConnectionInitialized waits for given connection's initial health state to be set. It will return immediately if the given connection is not known to this checker (which can happen if the connection's health check process has already been closed). It returns a snapshot of the connection's state on success. It returns an error if the given context is cancelled or times out before the connection's state is initialized.

func (*FakeHealthChecker) New

func (hc *FakeHealthChecker) New(_ context.Context, connection conn.Conn, tracker health.Tracker) io.Closer

New implements the healthchecker.Checker interface. It will use the given tracker to mark the given connection with the currently configured initial health state (which defaults to health).

func (*FakeHealthChecker) SetInitialState

func (hc *FakeHealthChecker) SetInitialState(state health.State)

SetInitialState sets the state that new connections will be put into in subsequent calls to New.

func (*FakeHealthChecker) SnapshotConns

func (hc *FakeHealthChecker) SnapshotConns() ConnHealth

SnapshotConns returns a snapshot of active connections and their latest health state.

func (*FakeHealthChecker) UpdateHealthState

func (hc *FakeHealthChecker) UpdateHealthState(connection conn.Conn, state health.State)

UpdateHealthState allows the state of a connection to be changed.

type FakePicker

type FakePicker struct {
	Conns conns.Set
}

FakePicker is a picker implementation that can be used for testing. It always returns the first picker it encounters in its set. Its set is exported so test code can examine the set of connections used to create the picker.

Also see NewFakePicker.

func (*FakePicker) Pick

func (p *FakePicker) Pick(*http.Request) (conn conn.Conn, whenDone func(), err error)

Pick implements the picker.Picker interface.

type PickerState

type PickerState struct {
	Picker        picker.Picker
	IsWarm        bool
	SnapshotConns conns.Set
}

PickerState represents the attributes of a picker. It encapsulates the picker itself, whether the balancer indicated that the pool is warm when the picker was configured, and also a snapshot of the connections used to create the picker (only if the picker is a *FakePicker).