go.uber.org/yarpc@v1.72.1/api/peer/doc.go (about)

     1  // Copyright (c) 2022 Uber Technologies, Inc.
     2  //
     3  // Permission is hereby granted, free of charge, to any person obtaining a copy
     4  // of this software and associated documentation files (the "Software"), to deal
     5  // in the Software without restriction, including without limitation the rights
     6  // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
     7  // copies of the Software, and to permit persons to whom the Software is
     8  // furnished to do so, subject to the following conditions:
     9  //
    10  // The above copyright notice and this permission notice shall be included in
    11  // all copies or substantial portions of the Software.
    12  //
    13  // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    14  // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    15  // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    16  // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    17  // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    18  // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    19  // THE SOFTWARE.
    20  
    21  // Package peer contains interfaces pertaining to peers, peer lists, peer list
    22  // updaters, and generally how to choose a peer for an outbound request.
    23  //
    24  // The `go.uber.org/yarpc/peer` package tree provides the corresponding
    25  // implementations.
    26  //
    27  // Outbounds for some transports support selecting a different peer from a peer
    28  // list for each individual request, for example load balancers and for pinning
    29  // requests to a consistent peer.
    30  // A peer instance models the host and port of a remote listening socket for a
    31  // particular transport protocol, like HTTP and TChannel.
    32  // For example, YARPC might have a TChannel peer instance to track connections
    33  // to 127.0.0.1:4040.
    34  //
    35  // Some transports, like HTTP and TChannel support peer selection on their
    36  // outbounds.  A `peer.Chooser` allows an outbound to obtain a peer for a given
    37  // request and also manages the lifecycle of all components it uses.
    38  // A peer chooser is typically also a `peer.List`, thus a `peer.ChooserList`.
    39  //
    40  // Peer list updaters send `Update` message to a `peer.List` to add and remove
    41  // peers.
    42  // Peer list updaters have no specific interface, but must in practice
    43  // implement `transport.Lifecycle` to bookend when they start and stop sending
    44  // updates.
    45  // A `peer.Binder` is a function that binds a `peer.List` to a peer list
    46  // updater and returns the `transport.Lifecycle` of the peer list updater.
    47  //
    48  // Not all `transport.Transport` instances support peer lists.
    49  // To support peer selection, they must also implement `peer.Transport`, which
    50  // has the `RetainPeer` and `ReleasePeer` methods, so a peer list can
    51  // hold strong references to peers maintained by a transport, and receive
    52  // notifications when peers start connecting, become available, become
    53  // unavailable, and when their pending request count changes.
    54  //
    55  // A peer list must provide a `peer.Subscriber` for each peer it retains or
    56  // releases.
    57  // The subscriber may be the peer list itself, though most peer lists contain
    58  // an internal representation of each of their retained peers for book-keeping
    59  // and sorting which benefits from receiving notifications for state changes
    60  // directly.
    61  package peer