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

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    This section is empty.

    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

              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

                    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

                        type ErrPeerListAlreadyStarted

                        type ErrPeerListAlreadyStarted string

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

                          func (ErrPeerListAlreadyStarted) Error

                          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

                                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.

                                                  Directories

                                                  Path Synopsis
                                                  Package peertest is a generated GoMock package.
                                                  Package peertest is a generated GoMock package.