github.com/palcoin-project/palcd@v1.0.0/rpcclient/doc.go (about)

     1  // Copyright (c) 2014-2017 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 rpcclient implements a websocket-enabled Bitcoin JSON-RPC client.
     7  
     8  Overview
     9  
    10  This client provides a robust and easy to use client for interfacing with a
    11  Bitcoin RPC server that uses a btcd/bitcoin core compatible Bitcoin JSON-RPC
    12  API.  This client has been tested with btcd (https://github.com/palcoin-project/palcd),
    13  btcwallet (https://github.com/palcoin-project/palcwallet), and
    14  bitcoin core (https://github.com/bitcoin).
    15  
    16  In addition to the compatible standard HTTP POST JSON-RPC API, btcd and
    17  btcwallet provide a websocket interface that is more efficient than the standard
    18  HTTP POST method of accessing RPC.  The section below discusses the differences
    19  between HTTP POST and websockets.
    20  
    21  By default, this client assumes the RPC server supports websockets and has
    22  TLS enabled.  In practice, this currently means it assumes you are talking to
    23  btcd or btcwallet by default.  However, configuration options are provided to
    24  fall back to HTTP POST and disable TLS to support talking with inferior bitcoin
    25  core style RPC servers.
    26  
    27  Websockets vs HTTP POST
    28  
    29  In HTTP POST-based JSON-RPC, every request creates a new HTTP connection,
    30  issues the call, waits for the response, and closes the connection.  This adds
    31  quite a bit of overhead to every call and lacks flexibility for features such as
    32  notifications.
    33  
    34  In contrast, the websocket-based JSON-RPC interface provided by btcd and
    35  btcwallet only uses a single connection that remains open and allows
    36  asynchronous bi-directional communication.
    37  
    38  The websocket interface supports all of the same commands as HTTP POST, but they
    39  can be invoked without having to go through a connect/disconnect cycle for every
    40  call.  In addition, the websocket interface provides other nice features such as
    41  the ability to register for asynchronous notifications of various events.
    42  
    43  Synchronous vs Asynchronous API
    44  
    45  The client provides both a synchronous (blocking) and asynchronous API.
    46  
    47  The synchronous (blocking) API is typically sufficient for most use cases.  It
    48  works by issuing the RPC and blocking until the response is received.  This
    49  allows  straightforward code where you have the response as soon as the function
    50  returns.
    51  
    52  The asynchronous API works on the concept of futures.  When you invoke the async
    53  version of a command, it will quickly return an instance of a type that promises
    54  to provide the result of the RPC at some future time.  In the background, the
    55  RPC call is issued and the result is stored in the returned instance.  Invoking
    56  the Receive method on the returned instance will either return the result
    57  immediately if it has already arrived, or block until it has.  This is useful
    58  since it provides the caller with greater control over concurrency.
    59  
    60  Notifications
    61  
    62  The first important part of notifications is to realize that they will only
    63  work when connected via websockets.  This should intuitively make sense
    64  because HTTP POST mode does not keep a connection open!
    65  
    66  All notifications provided by btcd require registration to opt-in.  For example,
    67  if you want to be notified when funds are received by a set of addresses, you
    68  register the addresses via the NotifyReceived (or NotifyReceivedAsync) function.
    69  
    70  Notification Handlers
    71  
    72  Notifications are exposed by the client through the use of callback handlers
    73  which are setup via a NotificationHandlers instance that is specified by the
    74  caller when creating the client.
    75  
    76  It is important that these notification handlers complete quickly since they
    77  are intentionally in the main read loop and will block further reads until
    78  they complete.  This provides the caller with the flexibility to decide what to
    79  do when notifications are coming in faster than they are being handled.
    80  
    81  In particular this means issuing a blocking RPC call from a callback handler
    82  will cause a deadlock as more server responses won't be read until the callback
    83  returns, but the callback would be waiting for a response.   Thus, any
    84  additional RPCs must be issued an a completely decoupled manner.
    85  
    86  Automatic Reconnection
    87  
    88  By default, when running in websockets mode, this client will automatically
    89  keep trying to reconnect to the RPC server should the connection be lost.  There
    90  is a back-off in between each connection attempt until it reaches one try per
    91  minute.  Once a connection is re-established, all previously registered
    92  notifications are automatically re-registered and any in-flight commands are
    93  re-issued.  This means from the caller's perspective, the request simply takes
    94  longer to complete.
    95  
    96  The caller may invoke the Shutdown method on the client to force the client
    97  to cease reconnect attempts and return ErrClientShutdown for all outstanding
    98  commands.
    99  
   100  The automatic reconnection can be disabled by setting the DisableAutoReconnect
   101  flag to true in the connection config when creating the client.
   102  
   103  Minor RPC Server Differences and Chain/Wallet Separation
   104  
   105  Some of the commands are extensions specific to a particular RPC server.  For
   106  example, the DebugLevel call is an extension only provided by btcd (and
   107  btcwallet passthrough).  Therefore if you call one of these commands against
   108  an RPC server that doesn't provide them, you will get an unimplemented error
   109  from the server.  An effort has been made to call out which commands are
   110  extensions in their documentation.
   111  
   112  Also, it is important to realize that btcd intentionally separates the wallet
   113  functionality into a separate process named btcwallet.  This means if you are
   114  connected to the btcd RPC server directly, only the RPCs which are related to
   115  chain services will be available.  Depending on your application, you might only
   116  need chain-related RPCs.  In contrast, btcwallet provides pass through treatment
   117  for chain-related RPCs, so it supports them in addition to wallet-related RPCs.
   118  
   119  Errors
   120  
   121  There are 3 categories of errors that will be returned throughout this package:
   122  
   123    - Errors related to the client connection such as authentication, endpoint,
   124      disconnect, and shutdown
   125    - Errors that occur before communicating with the remote RPC server such as
   126      command creation and marshaling errors or issues talking to the remote
   127      server
   128    - Errors returned from the remote RPC server like unimplemented commands,
   129      nonexistent requested blocks and transactions, malformed data, and incorrect
   130      networks
   131  
   132  The first category of errors are typically one of ErrInvalidAuth,
   133  ErrInvalidEndpoint, ErrClientDisconnect, or ErrClientShutdown.
   134  
   135  NOTE: The ErrClientDisconnect will not be returned unless the
   136  DisableAutoReconnect flag is set since the client automatically handles
   137  reconnect by default as previously described.
   138  
   139  The second category of errors typically indicates a programmer error and as such
   140  the type can vary, but usually will be best handled by simply showing/logging
   141  it.
   142  
   143  The third category of errors, that is errors returned by the server, can be
   144  detected by type asserting the error in a *btcjson.RPCError.  For example, to
   145  detect if a command is unimplemented by the remote RPC server:
   146  
   147    amount, err := client.GetBalance("")
   148    if err != nil {
   149    	if jerr, ok := err.(*btcjson.RPCError); ok {
   150    		switch jerr.Code {
   151    		case btcjson.ErrRPCUnimplemented:
   152    			// Handle not implemented error
   153  
   154    		// Handle other specific errors you care about
   155  		}
   156    	}
   157  
   158    	// Log or otherwise handle the error knowing it was not one returned
   159    	// from the remote RPC server.
   160    }
   161  
   162  Example Usage
   163  
   164  The following full-blown client examples are in the examples directory:
   165  
   166   - bitcoincorehttp
   167     Connects to a bitcoin core RPC server using HTTP POST mode with TLS disabled
   168     and gets the current block count
   169   - btcdwebsockets
   170     Connects to a btcd RPC server using TLS-secured websockets, registers for
   171     block connected and block disconnected notifications, and gets the current
   172     block count
   173   - btcwalletwebsockets
   174     Connects to a btcwallet RPC server using TLS-secured websockets, registers
   175     for notifications about changes to account balances, and gets a list of
   176     unspent transaction outputs (utxos) the wallet can sign
   177  */
   178  package rpcclient