mirror of
https://github.com/kaspanet/kaspad.git
synced 2025-03-30 15:08:33 +00:00
eb953286ec
* [NOD-641] Upgrade to github.com/pkg/errors v0.9.1 and use errors.As where needed * [NOD-641] Fix find and replace error * [NOD-641] Use errors.As for error type checking * [NOD-641] Fix errors.As for pointer types * [NOD-641] Use errors.As where needed * [NOD-641] Rename rErr->ruleErr * [NOD-641] Rename derr->dbErr * [NOD-641] e->flagsErr where necessary * [NOD-641] change jerr to more appropriate name * [NOD-641] Rename cerr->bdRuleErr * [NOD-641] Rename serr->scriptErr * [NOD-641] Use errors.Is instead of testutil.AreErrorsEqual in TestNewHashFromStr * [NOD-641] Rename bdRuleErr->dagRuleErr * [NOD-641] Rename mErr->msgErr * [NOD-641] Rename dErr->deserializeErr
150 lines
6.1 KiB
Go
150 lines
6.1 KiB
Go
/*
|
|
Package rpcclient implements a websocket-enabled kaspa JSON-RPC client.
|
|
|
|
Overview
|
|
|
|
This client provides a robust and easy to use client for interfacing with a
|
|
kaspa RPC server that uses a kaspa compatible kaspa JSON-RPC
|
|
API.
|
|
|
|
In addition to the compatible standard HTTP POST JSON-RPC API, kaspad
|
|
provides a websocket interface that is more efficient than the standard
|
|
HTTP POST method of accessing RPC. The section below discusses the differences
|
|
between HTTP POST and websockets.
|
|
|
|
By default, this client assumes the RPC server supports websockets and has
|
|
TLS enabled.
|
|
|
|
Websockets vs HTTP POST
|
|
|
|
In HTTP POST-based JSON-RPC, every request creates a new HTTP connection,
|
|
issues the call, waits for the response, and closes the connection. This adds
|
|
quite a bit of overhead to every call and lacks flexibility for features such as
|
|
notifications.
|
|
|
|
In contrast, the websocket-based JSON-RPC interface provided by kaspad
|
|
only uses a single connection that remains open and allows
|
|
asynchronous bi-directional communication.
|
|
|
|
The websocket interface supports all of the same commands as HTTP POST, but they
|
|
can be invoked without having to go through a connect/disconnect cycle for every
|
|
call. In addition, the websocket interface provides other nice features such as
|
|
the ability to register for asynchronous notifications of various events.
|
|
|
|
Synchronous vs Asynchronous API
|
|
|
|
The client provides both a synchronous (blocking) and asynchronous API.
|
|
|
|
The synchronous (blocking) API is typically sufficient for most use cases. It
|
|
works by issuing the RPC and blocking until the response is received. This
|
|
allows straightforward code where you have the response as soon as the function
|
|
returns.
|
|
|
|
The asynchronous API works on the concept of futures. When you invoke the async
|
|
version of a command, it will quickly return an instance of a type that promises
|
|
to provide the result of the RPC at some future time. In the background, the
|
|
RPC call is issued and the result is stored in the returned instance. Invoking
|
|
the Receive method on the returned instance will either return the result
|
|
immediately if it has already arrived, or block until it has. This is useful
|
|
since it provides the caller with greater control over concurrency.
|
|
|
|
Notifications
|
|
|
|
The first important part of notifications is to realize that they will only
|
|
work when connected via websockets. This should intuitively make sense
|
|
because HTTP POST mode does not keep a connection open!
|
|
|
|
All notifications provided by kaspad require registration to opt-in. For example,
|
|
if you want to be notified when blocks are added to the DAG, you register the
|
|
via the NotifyBlocks (or NotifyBlocksAsync) function.
|
|
|
|
Notification Handlers
|
|
|
|
Notifications are exposed by the client through the use of callback handlers
|
|
which are setup via a NotificationHandlers instance that is specified by the
|
|
caller when creating the client.
|
|
|
|
It is important that these notification handlers complete quickly since they
|
|
are intentionally in the main read loop and will block further reads until
|
|
they complete. This provides the caller with the flexibility to decide what to
|
|
do when notifications are coming in faster than they are being handled.
|
|
|
|
In particular this means issuing a blocking RPC call from a callback handler
|
|
will cause a deadlock as more server responses won't be read until the callback
|
|
returns, but the callback would be waiting for a response. Thus, any
|
|
additional RPCs must be issued an a completely decoupled manner.
|
|
|
|
Automatic Reconnection
|
|
|
|
By default, when running in websockets mode, this client will automatically
|
|
keep trying to reconnect to the RPC server should the connection be lost. There
|
|
is a back-off in between each connection attempt until it reaches one try per
|
|
minute. Once a connection is re-established, all previously registered
|
|
notifications are automatically re-registered and any in-flight commands are
|
|
re-issued. This means from the caller's perspective, the request simply takes
|
|
longer to complete.
|
|
|
|
The caller may invoke the Shutdown method on the client to force the client
|
|
to cease reconnect attempts and return ErrClientShutdown for all outstanding
|
|
commands.
|
|
|
|
The automatic reconnection can be disabled by setting the DisableAutoReconnect
|
|
flag to true in the connection config when creating the client.
|
|
|
|
Errors
|
|
|
|
There are 3 categories of errors that will be returned throughout this package:
|
|
|
|
- Errors related to the client connection such as authentication, endpoint,
|
|
disconnect, and shutdown
|
|
- Errors that occur before communicating with the remote RPC server such as
|
|
command creation and marshaling errors or issues talking to the remote
|
|
server
|
|
- Errors returned from the remote RPC server like unimplemented commands,
|
|
nonexistent requested blocks and transactions, malformed data, and incorrect
|
|
networks
|
|
|
|
The first category of errors are typically one of ErrInvalidAuth,
|
|
ErrInvalidEndpoint, ErrClientDisconnect, or ErrClientShutdown.
|
|
|
|
NOTE: The ErrClientDisconnect will not be returned unless the
|
|
DisableAutoReconnect flag is set since the client automatically handles
|
|
reconnect by default as previously described.
|
|
|
|
The second category of errors typically indicates a programmer error and as such
|
|
the type can vary, but usually will be best handled by simply showing/logging
|
|
it.
|
|
|
|
The third category of errors, that is errors returned by the server, can be
|
|
detected by type asserting the error in a *rpcmodel.RPCError. For example, to
|
|
detect if a command is unimplemented by the remote RPC server:
|
|
|
|
netTotals, err := client.GetNetTotals()
|
|
if err != nil {
|
|
var jErr *rpcmodel.RPCError
|
|
if errors.As(err, jErr) {
|
|
switch jErr.Code {
|
|
case rpcmodel.ErrRPCUnimplemented:
|
|
// Handle not implemented error
|
|
|
|
// Handle other specific errors you care about
|
|
}
|
|
}
|
|
|
|
// Log or otherwise handle the error knowing it was not one returned
|
|
// from the remote RPC server.
|
|
}
|
|
|
|
Example Usage
|
|
|
|
The following full-blown client examples are in the examples directory:
|
|
|
|
- httppost
|
|
Connects to a kaspa RPC server using HTTP POST mode with TLS disabled
|
|
and gets the current block count
|
|
- websockets
|
|
Connects to a kaspad RPC server using TLS-secured websockets, registers for
|
|
block added notifications, and gets the current block count
|
|
*/
|
|
package rpcclient
|