peer

Documentation

Overview

Package peer contains interfaces pertaining to peers, peer lists, peer list updaters, and generally how to choose a peer for an outbound request.

The `go.uber.org/yarpc/peer` package tree provides the corresponding implementations.

Outbounds for some transports support selecting a different peer from a peer list for each individual request, for example load balancers and for pinning requests to a consistent peer. A peer instance models the host and port of a remote listening socket for a particular transport protocol, like HTTP and TChannel. For example, YARPC might have a TChannel peer instance to track connections to 127.0.0.1:4040.

Some transports, like HTTP and TChannel support peer selection on their outbounds. A `peer.Chooser` allows an outbound to obtain a peer for a given request and also manages the lifecycle of all components it uses. A peer chooser is typically also a `peer.List`, thus a `peer.ChooserList`.

Peer list updaters send `Update` message to a `peer.List` to add and remove peers. Peer list updaters have no specific interface, but must in practice implement `transport.Lifecycle` to bookend when they start and stop sending updates. A `peer.Binder` is a function that binds a `peer.List` to a peer list updater and returns the `transport.Lifecycle` of the peer list updater.

Not all `transport.Transport` instances support peer lists. To support peer selection, they must also implement `peer.Transport`, which has the `RetainPeer` and `ReleasePeer` methods, so a peer list can hold strong references to peers maintained by a transport, and receive notifications when peers start connecting, become available, become unavailable, and when their pending request count changes.

A peer list must provide a `peer.Subscriber` for each peer it retains or releases. The subscriber may be the peer list itself, though most peer lists contain an internal representation of each of their retained peers for book-keeping and sorting which benefits from receiving notifications for state changes directly.

Index

• type Binder
• type Chooser
• type ChooserList
• type ConnectionStatus
  • func (i ConnectionStatus) String() string
• type ErrChooseContextHasNoDeadline
  • func (e ErrChooseContextHasNoDeadline) Error() string
• type ErrInvalidPeerConversion
  • func (e ErrInvalidPeerConversion) Error() string
• type ErrInvalidPeerType
  • func (e ErrInvalidPeerType) Error() string
• type ErrInvalidTransportConversion
  • func (e ErrInvalidTransportConversion) Error() string
• type ErrPeerAddAlreadyInList
  • func (e ErrPeerAddAlreadyInList) Error() string
• type ErrPeerHasNoReferenceToSubscriber
  • func (e ErrPeerHasNoReferenceToSubscriber) Error() string
• type ErrPeerListAlreadyStarted
  • func (e ErrPeerListAlreadyStarted) Error() string
• type ErrPeerListNotStarted
  • func (e ErrPeerListNotStarted) Error() string
• type ErrPeerRemoveNotInList
  • func (e ErrPeerRemoveNotInList) Error() string
• type ErrTransportHasNoReferenceToPeer
  • func (e ErrTransportHasNoReferenceToPeer) Error() string
• type Identifier
• type List
• type ListImplementation
• type ListUpdates
• type Peer
• type Status
  • func (s Status) String() string
• type StatusPeer
• type Subscriber
• type Transport

Types

type Binder

type Binder func(List) transport.Lifecycle

Binder is a callback for peer.Bind that accepts a peer list and binds it to a peer list updater for the duration of the returned peer list updater. The peer list updater must implement the lifecycle interface, and start and stop updates over that lifecycle. The binder must not block on updating the list, because update may block until the peer list has started. The binder must return a peer list updater that will begin updating when it starts, and stop updating when it stops.

type Chooser

type Chooser interface {
	transport.Lifecycle

	// Choose a Peer for the next call, block until a peer is available (or timeout)
	Choose(context.Context, *transport.Request) (peer Peer, onFinish func(error), err error)
}

Chooser is a collection of Peers. Outbounds request peers from the peer.Chooser to determine where to send requests. The chooser is responsible for managing the lifecycle of any retained peers.

type ChooserList

type ChooserList interface {
	Chooser
	List
}

ChooserList is both a Chooser and a List, useful for expressing both capabilities of a single instance.

type ConnectionStatus

type ConnectionStatus int

ConnectionStatus maintains information about the Peer's connection state

const (
	// Unavailable indicates the Peer is unavailable for requests
	Unavailable ConnectionStatus = iota

	// Connecting indicates the Peer is in the process of connecting
	Connecting

	// Available indicates the Peer is available for requests
	Available
)

func (ConnectionStatus) String

func (i ConnectionStatus) String() string

type ErrChooseContextHasNoDeadline

type ErrChooseContextHasNoDeadline string

ErrChooseContextHasNoDeadline is returned when a context is sent to a peerlist with no deadline DEPRECATED use yarpcerrors api instead.

func (ErrChooseContextHasNoDeadline) Error

func (e ErrChooseContextHasNoDeadline) Error() string

type ErrInvalidPeerConversion

type ErrInvalidPeerConversion struct {
	Peer         Peer
	ExpectedType string
}

ErrInvalidPeerConversion is called when a peer can't be properly converted

func (ErrInvalidPeerConversion) Error

func (e ErrInvalidPeerConversion) Error() string

type ErrInvalidPeerType

type ErrInvalidPeerType struct {
	ExpectedType   string
	PeerIdentifier Identifier
}

ErrInvalidPeerType is when a specfic peer type is required, but was not passed in

func (ErrInvalidPeerType) Error

func (e ErrInvalidPeerType) Error() string

type ErrInvalidTransportConversion

type ErrInvalidTransportConversion struct {
	Transport    Transport
	ExpectedType string
}

ErrInvalidTransportConversion is called when a transport can't be properly converted

func (ErrInvalidTransportConversion) Error

func (e ErrInvalidTransportConversion) Error() string

type ErrPeerAddAlreadyInList

type ErrPeerAddAlreadyInList string

ErrPeerAddAlreadyInList is returned to peer list updater if the peerlist is already tracking a peer for the added identifier

func (ErrPeerAddAlreadyInList) Error

func (e ErrPeerAddAlreadyInList) Error() string

type ErrPeerHasNoReferenceToSubscriber

type ErrPeerHasNoReferenceToSubscriber struct {
	PeerIdentifier Identifier
	PeerSubscriber Subscriber
}

ErrPeerHasNoReferenceToSubscriber is called when a Peer is expected to operate on a PeerSubscriber it has no reference to

func (ErrPeerHasNoReferenceToSubscriber) Error

func (e ErrPeerHasNoReferenceToSubscriber) Error() string

type ErrPeerListAlreadyStarted

type ErrPeerListAlreadyStarted string

ErrPeerListAlreadyStarted represents a failure because Start() was already called on the peerlist.

func (ErrPeerListAlreadyStarted) Error

func (e ErrPeerListAlreadyStarted) Error() string

type ErrPeerListNotStarted

type ErrPeerListNotStarted string

ErrPeerListNotStarted represents a failure because Start() was not called on a peerlist or if Stop() was called.

func (ErrPeerListNotStarted) Error

func (e ErrPeerListNotStarted) Error() string

type ErrPeerRemoveNotInList

type ErrPeerRemoveNotInList string

ErrPeerRemoveNotInList is returned to peer list updater if the peerlist is not tracking the peer to remove for a given identifier

func (ErrPeerRemoveNotInList) Error

func (e ErrPeerRemoveNotInList) Error() string

type ErrTransportHasNoReferenceToPeer

type ErrTransportHasNoReferenceToPeer struct {
	TransportName  string
	PeerIdentifier string
}

ErrTransportHasNoReferenceToPeer is called when a transport is expected to operate on a Peer it has no reference to

func (ErrTransportHasNoReferenceToPeer) Error

func (e ErrTransportHasNoReferenceToPeer) Error() string

type Identifier

type Identifier interface {
	Identifier() string
}

Identifier is able to uniquely identify a peer (e.g. hostport)

type List

type List interface {
	// Update performs the additions and removals to the Peer List
	Update(updates ListUpdates) error
}

List listens to adds and removes of Peers from a peer list updater. A Chooser will implement the List interface in order to receive updates to the list of Peers it is keeping track of.

type ListImplementation

type ListImplementation interface {
	transport.Lifecycle

	Add(StatusPeer) Subscriber
	Remove(StatusPeer, Subscriber)
	// Choose must return an available peer under a list read lock, so must
	// not block.
	Choose(context.Context, *transport.Request) StatusPeer
}

ListImplementation is a collection of available peers, with its own subscribers for peer status change notifications. The available peer list encapsulates the logic for selecting from among available peers, whereas a ChooserList is responsible for retaining, releasing, and monitoring peer availability. Use "go.uber.org/yarpc/peer/peerlist".List in conjunction with a ListImplementation to produce a "go.uber.org/yarpc/api/peer".List.

peerlist.List and ListImplementation compose well with sharding schemes the degenerate to returning the only available peer.

The peerlist.List calls Add, Remove, and Choose under a write lock so the implementation is free to perform mutations on its own data without locks.

Deprecated in favor of "go.uber.org/yarpc/peer/peerlist/v2".Implementation.

type ListUpdates

type ListUpdates struct {
	// Additions are the identifiers that should be added to the list
	Additions []Identifier

	// Removals are the identifiers that should be removed to the list
	Removals []Identifier
}

ListUpdates specifies the updates to be made to a List

type Peer

type Peer interface {
	StatusPeer

	// Tell the peer that a request is starting
	StartRequest()

	// Tell the peer that a request has finished
	EndRequest()
}

Peer captures a concrete peer implementation for a particular transport, providing both observability (Identifier and Status), along with load change notifications (StartRequest) (EndRequest). Transports reveal peers to peer lists, which in turn offer them to outbounds when they choose a peer. Having Start/End request messages allows the outbound to broadcast load changes to all subscribed load balancers. The peer should be created by a transport so we can maintain multiple references to the same peer (e.g., hostport).

type Status

type Status struct {
	// Current number of pending requests on this peer
	PendingRequestCount int

	// Current status of the Peer's connection
	ConnectionStatus ConnectionStatus
}

Status holds all the information about a peer's state that would be useful to Subscribers

func (Status) String

func (s Status) String() string

type StatusPeer

type StatusPeer interface {
	Identifier

	// Get the status of the Peer
	Status() Status
}

StatusPeer captures a concrete peer implementation for a particular transport, exposing its Identifier and Status. StatusPeer provides observability without mutability.

type Subscriber

type Subscriber interface {
	// The Peer Notifies the Subscriber when its status changes (e.g.
	// connections status, pending requests)
	//
	// NotifyStatusChanged may call methods of the corresponding Peer,
	// particularly Status.
	// So, subscriber methods must not be called while holding a lock on the
	// Transport.
	NotifyStatusChanged(Identifier)
}

Subscriber listens to changes of a Peer over time.

type Transport

type Transport interface {
	// Get or create a Peer for the Subscriber
	RetainPeer(Identifier, Subscriber) (Peer, error)

	// Unallocate a peer from the Subscriber
	ReleasePeer(Identifier, Subscriber) error
}

Transport manages Peers across different Subscribers.

A Subscriber will request a Peer for a specific PeerIdentifier and the Transport has the ability to create a new Peer or return an existing one.

RetainPeer and ReleasePeer must not call or synchronize with goroutines that call methods of the Subscriber.