Migrating from AuthServiceProxy¶
Two files answer to that name, and they no longer agree with each other:
Bitcoin Core’s own copy, test/functional/test_framework/authproxy.py,
and python-bitcoinrpc’s bitcoinrpc/authproxy.py, which most PyPI
packages carrying a vendored client mean by it. Every claim below about
one of the two is checked against it directly — Core’s copy at
05e49b342f, python-bitcoinrpc’s at
c5527bcdd0b1d98dd9d785729f52337f5bb44a16 — and labelled by file where
the two no longer behave alike.
COMPARISON.md makes the case for the switch and
is not repeated here: this page is the mechanics of it, an
AuthServiceProxy line at a time with the line that replaces it, for a
caller carrying either file.
Construction¶
Both variants take one url, and the credential — where there is one — sits inside it. That string is also what ends up in a configuration file, a traceback and a log, which is why a url shaped that way is refused here; the credential is an argument instead.
# AuthServiceProxy
rpc = AuthServiceProxy(f"http://{user}:{password}@127.0.0.1:8332")
# this client
client = BitcoinCoreRpcClient("http://127.0.0.1:8332", user=user, password=password)
The cookie file. Neither variant’s constructor reads one: a caller
does, by hand, and builds the credential into the url before
constructing it — Core’s own test framework is such a caller,
get_auth_cookie reading .cookie and create_new_rpc_connection
building f"http://{rpc_u}:{rpc_p}@{host}:{port}" from what it returns.
from_chain is that same read, made once inside the constructor rather
than in the caller’s own code, and made again at every call rather than
held: a client built while the node is up still works after a restart
rewrites the file.
# AuthServiceProxy (a caller's own glue, e.g. test_framework/test_node.py)
rpc_u, rpc_p = get_auth_cookie(datadir, chain)
rpc = AuthServiceProxy(f"http://{rpc_u}:{rpc_p}@127.0.0.1:{port}")
# this client
client = BitcoinCoreRpcClient.from_chain("main")
A non-default -rpcport or -datadir. Neither is a keyword either
constructor takes: a caller builds it into the url, and into whatever
reads the cookie, by hand. from_chain carries the chain’s own default
port; a node moved off it is an explicit url, and a node started with
-datadir= elsewhere is cookie_path, per
Talking to a node.
client = BitcoinCoreRpcClient.from_chain(
"main", cookie_path=Path("/srv/bitcoin/.cookie")
)
https. Both variants dispatch on the url’s scheme —
http.client.HTTPSConnection where it reads https, exactly as this
client’s own transports do — so an https:// url is the same story on
either side, with the same standard-library certificate trust and no
extra knob on any of the three.
Invoking a method¶
Attribute style. AuthServiceProxy.__getattr__ returns a new proxy
bound to the name, sharing the connection; RpcChannel wraps a client
for the same syntax one to one, with no second object underneath it.
# AuthServiceProxy
block = rpc.getblock(block_id, 2)
# this client
rpc = RpcChannel(client)
block = rpc.getblock(block_id, 2)
The explicit form. call is the equivalent with no attribute lookup
at all, and it is what RpcChannel calls underneath: an unknown method
is a value the node answers for, not an AttributeError here.
block = client.call("getblock", [block_id, 2])
block = client.call("getblock", {"blockhash": block_id, "verbosity": 2})
Positional and named together. Core’s copy accepts both in one
call, folding the positional ones under args —
params = dict(args=args, **argsn) — the same convenience
src/rpc/server.cpp reads back out of a named call on the node’s own
side. RpcChannel refuses the combination outright, json-rpc having one
params shape per call and not both; call still reaches it, written out
as the mapping Core’s own args convenience already is.
# AuthServiceProxy (Core's copy)
block = rpc.getblock(block_id, verbosity=2)
# this client
block = client.call("getblock", {"args": [block_id], "verbosity": 2})
Wallet endpoints¶
Core’s copy overloads /: rpc / "wallet/hot" builds a second proxy at
the concatenated path, sharing the connection. python-bitcoinrpc’s copy
has no such operator, so a caller there starts from a second url built
by hand instead. Either way the wallet name reaches the url exactly as
written; for_wallet percent-encodes it, a wallet being a directory and
free to be called anything a filesystem accepts.
# AuthServiceProxy (Core's copy)
hot = rpc / "wallet/hot"
balance = hot.getbalance()
# AuthServiceProxy (python-bitcoinrpc)
hot = AuthServiceProxy(f"http://{user}:{password}@127.0.0.1:8332/wallet/hot")
balance = hot.getbalance()
# this client
balance = client.for_wallet("hot").call("getbalance")
Batching¶
Core’s copy names it batch, python-bitcoinrpc’s batch_; call_batch
replaces either name. The shape of the answer differs more than the
name: Core’s batch hands back the raw reply objects unread, and
python-bitcoinrpc’s batch_ raises the first error it finds and
discards every answer beside it, where call_batch reads each member
the way call reads its own and keeps going — position i holds member
i’s result, or its RpcError as a value.
# AuthServiceProxy (python-bitcoinrpc)
hashes = rpc.batch_([["getblockhash", height] for height in heights])
# AuthServiceProxy (Core's copy)
calls = [rpc.getblockhash.get_request(height) for height in heights]
hashes = rpc.batch(calls)
# this client
hashes = client.call_batch([("getblockhash", [height]) for height in heights])
Errors¶
AuthServiceProxy |
this client |
|---|---|
|
|
|
|
|
|
any other |
|
python-bitcoinrpc’s own JSONRPCException carries no HTTP status at
all — its constructor takes only the error object, and _get_response
reads http_response.status solely to word the message of the one
error it raises for a non-json content type, never to distinguish a
routine rpc error from a backend that failed outright. Core’s copy added
http_status for exactly that reason, and it is the field
HttpError.status answers.
# AuthServiceProxy
try:
raw = rpc.getrawtransaction(tx_id)
except JSONRPCException as e:
if e.error["code"] == -5:
...
# this client
try:
raw = client.call("getrawtransaction", [tx_id])
except RpcError as e:
if e.code == -5:
...
COMPARISON.md has the except OSError
trap beside this: a refused connection is a plain OSError on both
AuthServiceProxy variants and a FetchError, derived from
RuntimeError, here.
Amounts¶
A reply’s floating-point numbers decode as Decimal and its integers as int
on every side alike — both authproxy.py files pass
parse_float=decimal.Decimal to json.loads and nothing for integers, and this
client reads the same way. Requests are where the two variants part ways from
each other as well as from this one: python-bitcoinrpc’s EncodeDecimal rounds
a Decimal parameter through float before sending it (float(round(o, 8)));
Core’s copy stringifies it instead (serialization_fallback’s str(o)), which
keeps the digits but turns the parameter from a number into a string: an amount
argument accepts it and an integer one refuses it. This client writes a
Decimal parameter as the JSON number it is, digit for digit: a number, the
type both kinds of argument accept.
Timeouts¶
Both variants hand timeout to http.client’s own connection, which
spends it per socket operation: a peer dripping a reply one byte at a
time resets the clock on every read and can hold the call open past
what was asked for. timeout and request_timeout are a deadline over
the whole exchange instead, taken once before the connect, so the same
dripped reply cannot hold this client open past it either.
request_timeout is the one to widen for a method that legitimately
runs long — rescanblockchain, scantxoutset — rather than building a
second client for it.
Connections¶
Both AuthServiceProxy variants keep one http.client connection open
for the object’s life, and __getattr__ hands it on to every proxy
derived from the first one. This client opens a fresh connection per
call by default, per
Keeping a connection alive;
SessionTransport is the equivalent, one connection kept per node and
passed as transport=.
from bitcoin_core_rpc import BitcoinCoreRpcClient, SessionTransport
with SessionTransport() as session:
client = BitcoinCoreRpcClient.from_chain("main", transport=session)
The envelope¶
Core’s copy exposes _request and _get_response for a caller who
wants to send a request __call__ would not build and read the reply
before anything is asked of its shape — both reached by poking at
attributes (rpc._AuthServiceProxy__url, name-mangled) the class does
not otherwise publish. call_raw is the same seam, public: the same
authenticated POST call builds, the protocol marker itself an
argument, and the answer handed back exactly as parsed — no id check,
no result extracted, no shape assumed.
status, reply = client.call_raw("getblockcount", jsonrpc=None)
Testing¶
Neither AuthServiceProxy variant takes a seam: a caller wanting to
test code that calls a node monkeypatches http.client itself, or the
connection object each constructor builds by hand. transport is that
seam here, a callable in place of the constructor’s default, taking the
request and the timeout and answering the status and the body — the
suite of this project opens no socket, and neither has yours to, per
Testing code that calls a
node.
What has no equivalent¶
Notifications. A request sent with no id, which a node does not
answer, is not a documented feature of either AuthServiceProxy file —
but nothing in __call__ refuses building one by hand, where call
always sends an id. No AuthServiceProxy consumer is giving anything
up.
A request this client refuses to build. Neither AuthServiceProxy
file validates a method name or its params before sending them —
__call__ sends whatever json.dumps accepts, method, params and all —
where this client refuses a non-string method, or params that are
neither a sequence nor a mapping, before opening a connection. A caller
building a request that is deliberately invalid — a conformance harness
testing a server’s own handling of a malformed one — has http_request
for it, the public seam beneath call and call_raw alike, rather than
a version of AuthServiceProxy’s own permissiveness inside this class.