1  // Copyright (c) 2015-2016 The btcsuite developers
  2  // Use of this source code is governed by an ISC
  3  // license that can be found in the LICENSE file.
  4  
  5  /*
  6  Package peer provides a common base for creating and managing Bitcoin network
  7  peers.
  8  
  9  Overview
 10  
 11  This package builds upon the wire package, which provides the fundamental
 12  primitives necessary to speak the bitcoin wire protocol, in order to simplify
 13  the process of creating fully functional peers.  In essence, it provides a
 14  common base for creating concurrent safe fully validating nodes, Simplified
 15  Payment Verification (SPV) nodes, proxies, etc.
 16  
 17  A quick overview of the major features peer provides are as follows:
 18  
 19   - Provides a basic concurrent safe bitcoin peer for handling bitcoin
 20     communications via the peer-to-peer protocol
 21   - Full duplex reading and writing of bitcoin protocol messages
 22   - Automatic handling of the initial handshake process including protocol
 23     version negotiation
 24   - Asynchronous message queuing of outbound messages with optional channel for
 25     notification when the message is actually sent
 26   - Flexible peer configuration
 27     - Caller is responsible for creating outgoing connections and listening for
 28       incoming connections so they have flexibility to establish connections as
 29       they see fit (proxies, etc)
 30     - User agent name and version
 31     - Bitcoin network
 32     - Service support signalling (full nodes, bloom filters, etc)
 33     - Maximum supported protocol version
 34     - Ability to register callbacks for handling bitcoin protocol messages
 35   - Inventory message batching and send trickling with known inventory detection
 36     and avoidance
 37   - Automatic periodic keep-alive pinging and pong responses
 38   - Random nonce generation and self connection detection
 39   - Proper handling of bloom filter related commands when the caller does not
 40     specify the related flag to signal support
 41     - Disconnects the peer when the protocol version is high enough
 42     - Does not invoke the related callbacks for older protocol versions
 43   - Snapshottable peer statistics such as the total number of bytes read and
 44     written, the remote address, user agent, and negotiated protocol version
 45   - Helper functions pushing addresses, getblocks, getheaders, and reject
 46     messages
 47     - These could all be sent manually via the standard message output function,
 48       but the helpers provide additional nice functionality such as duplicate
 49       filtering and address randomization
 50   - Ability to wait for shutdown/disconnect
 51   - Comprehensive test coverage
 52  
 53  Peer Configuration
 54  
 55  All peer configuration is handled with the Config struct.  This allows the
 56  caller to specify things such as the user agent name and version, the bitcoin
 57  network to use, which services it supports, and callbacks to invoke when bitcoin
 58  messages are received.  See the documentation for each field of the Config
 59  struct for more details.
 60  
 61  Inbound and Outbound Peers
 62  
 63  A peer can either be inbound or outbound.  The caller is responsible for
 64  establishing the connection to remote peers and listening for incoming peers.
 65  This provides high flexibility for things such as connecting via proxies, acting
 66  as a proxy, creating bridge peers, choosing whether to listen for inbound peers,
 67  etc.
 68  
 69  NewOutboundPeer and NewInboundPeer functions must be followed by calling Connect
 70  with a net.Conn instance to the peer.  This will start all async I/O goroutines
 71  and initiate the protocol negotiation process.  Once finished with the peer call
 72  Disconnect to disconnect from the peer and clean up all resources.
 73  WaitForDisconnect can be used to block until peer disconnection and resource
 74  cleanup has completed.
 75  
 76  Callbacks
 77  
 78  In order to do anything useful with a peer, it is necessary to react to bitcoin
 79  messages.  This is accomplished by creating an instance of the MessageListeners
 80  struct with the callbacks to be invoke specified and setting the Listeners field
 81  of the Config struct specified when creating a peer to it.
 82  
 83  For convenience, a callback hook for all of the currently supported bitcoin
 84  messages is exposed which receives the peer instance and the concrete message
 85  type.  In addition, a hook for OnRead is provided so even custom messages types
 86  for which this package does not directly provide a hook, as long as they
 87  implement the wire.Message interface, can be used.  Finally, the OnWrite hook
 88  is provided, which in conjunction with OnRead, can be used to track server-wide
 89  byte counts.
 90  
 91  It is often useful to use closures which encapsulate state when specifying the
 92  callback handlers.  This provides a clean method for accessing that state when
 93  callbacks are invoked.
 94  
 95  Queuing Messages and Inventory
 96  
 97  The QueueMessage function provides the fundamental means to send messages to the
 98  remote peer.  As the name implies, this employs a non-blocking queue.  A done
 99  channel which will be notified when the message is actually sent can optionally
100  be specified.  There are certain message types which are better sent using other
101  functions which provide additional functionality.
102  
103  Of special interest are inventory messages.  Rather than manually sending MsgInv
104  messages via Queuemessage, the inventory vectors should be queued using the
105  QueueInventory function.  It employs batching and trickling along with
106  intelligent known remote peer inventory detection and avoidance through the use
107  of a most-recently used algorithm.
108  
109  Message Sending Helper Functions
110  
111  In addition to the bare QueueMessage function previously described, the
112  PushAddrMsg, PushGetBlocksMsg, PushGetHeadersMsg, and PushRejectMsg functions
113  are provided as a convenience.  While it is of course possible to create and
114  send these message manually via QueueMessage, these helper functions provided
115  additional useful functionality that is typically desired.
116  
117  For example, the PushAddrMsg function automatically limits the addresses to the
118  maximum number allowed by the message and randomizes the chosen addresses when
119  there are too many.  This allows the caller to simply provide a slice of known
120  addresses, such as that returned by the addrmgr package, without having to worry
121  about the details.
122  
123  Next, the PushGetBlocksMsg and PushGetHeadersMsg functions will construct proper
124  messages using a block locator and ignore back to back duplicate requests.
125  
126  Finally, the PushRejectMsg function can be used to easily create and send an
127  appropriate reject message based on the provided parameters as well as
128  optionally provides a flag to cause it to block until the message is actually
129  sent.
130  
131  Peer Statistics
132  
133  A snapshot of the current peer statistics can be obtained with the StatsSnapshot
134  function.  This includes statistics such as the total number of bytes read and
135  written, the remote address, user agent, and negotiated protocol version.
136  
137  Logging
138  
139  This package provides extensive logging capabilities through the UseLogger
140  function which allows a btclog.Logger to be specified.  For example, logging at
141  the debug level provides summaries of every message sent and received, and
142  logging at the trace level provides full dumps of parsed messages as well as the
143  raw message bytes using a format similar to hexdump -C.
144  
145  Bitcoin Improvement Proposals
146  
147  This package supports all BIPS supported by the wire package.
148  (https://godoc.org/github.com/btcsuite/btcd/wire#hdr-Bitcoin_Improvement_Proposals)
149  */
150  package peer