mirror of
https://github.com/bitcoin/bitcoin.git
synced 2026-01-18 22:35:39 +01:00
Merge bitcoin/bitcoin#27101: Support JSON-RPC 2.0 when requested by client
cbc6c440e3doc: add comments and release-notes for JSON-RPC 2.0 (Matthew Zipkin)e7ee80dcf2rpc: JSON-RPC 2.0 should not respond to "notifications" (Matthew Zipkin)bf1a1f1662rpc: Avoid returning HTTP errors for JSON-RPC 2.0 requests (Matthew Zipkin)466b90562frpc: Add "jsonrpc" field and drop null "result"/"error" fields (Matthew Zipkin)2ca1460ae3rpc: identify JSON-RPC 2.0 requests (Matthew Zipkin)a64a2b77e0rpc: refactor single/batch requests (Matthew Zipkin)df6e3756d6rpc: Avoid copies in JSONRPCReplyObj() (Matthew Zipkin)09416f9ec4test: cover JSONRPC 2.0 requests, batches, and notifications (Matthew Zipkin)4202c170datest: refactor interface_rpc.py (Matthew Zipkin) Pull request description: Closes https://github.com/bitcoin/bitcoin/issues/2960 Bitcoin Core's JSONRPC server behaves with a special blend of 1.0, 1.1 and 2.0 behaviors. This introduces compliance issues with more strict clients. There are the major misbehaviors that I found: - returning non-200 HTTP codes for RPC errors like "Method not found" (this is not a server error or an HTTP error) - returning both `"error"` and `"result"` fields together in a response object. - different error-handling behavior for single and batched RPC requests (batches contain errors in the response but single requests will actually throw HTTP errors) https://github.com/bitcoin/bitcoin/pull/15495 added regression tests after a discussion in https://github.com/bitcoin/bitcoin/pull/15381 to kinda lock in our RPC behavior to preserve backwards compatibility. https://github.com/bitcoin/bitcoin/pull/12435 was an attempt to allow strict 2.0 compliance behind a flag, but was abandoned. The approach in this PR is not strict and preserves backwards compatibility in a familiar bitcoin-y way: all old behavior is preserved, but new rules are applied to clients that opt in. One of the rules in the [JSON RPC 2.0 spec](https://www.jsonrpc.org/specification#request_object) is that the kv pair `"jsonrpc": "2.0"` must be present in the request. Well, let's just use that to trigger strict 2.0 behavior! When that kv pair is included in a request object, the [response will adhere to strict JSON-RPC 2.0 rules](https://www.jsonrpc.org/specification#response_object), essentially: - always return HTTP 200 "OK" unless there really is a server error or malformed request - either return `"error"` OR `"result"` but never both - same behavior for single and batch requests If this is merged next steps can be: - Refactor bitcoin-cli to always use strict 2.0 - Refactor the python test framework to always use strict 2.0 for everything - Begin deprecation process for 1.0/1.1 behavior (?) If we can one day remove the old 1.0/1.1 behavior we can clean up the rpc code quite a bit. ACKs for top commit: cbergqvist: re ACKcbc6c440e3ryanofsky: Code review ACKcbc6c440e3. Just suggested changes since the last review: changing uncaught exception error code from PARSE_ERROR to MISC_ERROR, renaming a few things, and adding comments. tdb3: re ACK forcbc6c440e3Tree-SHA512: 0b702ed32368b34b29ad570d090951a7aeb56e3b0f2baf745bd32fdc58ef68fee6b0b8fad901f1ca42573ed714b150303829cddad4a34ca7ad847350feeedb36
This commit is contained in:
Ryan Ofsky
@@ -74,6 +74,22 @@ major version via the `-deprecatedrpc=` command line option. The release notes
|
||||
of a new major release come with detailed instructions on what RPC features
|
||||
were deprecated and how to re-enable them temporarily.
|
||||
|
||||
## JSON-RPC 1.1 vs 2.0
|
||||
|
||||
The server recognizes [JSON-RPC v2.0](https://www.jsonrpc.org/specification) requests
|
||||
and responds accordingly. A 2.0 request is identified by the presence of
|
||||
`"jsonrpc": "2.0"` in the request body. If that key + value is not present in a request,
|
||||
the legacy JSON-RPC v1.1 protocol is followed instead, which was the only available
|
||||
protocol in previous releases.
|
||||
|
||||
|| 1.1 | 2.0 |
|
||||
|-|-|-|
|
||||
| Request marker | `"version": "1.1"` (or none) | `"jsonrpc": "2.0"` |
|
||||
| Response marker | (none) | `"jsonrpc": "2.0"` |
|
||||
| `"error"` and `"result"` fields in response | both present | only one is present |
|
||||
| HTTP codes in response | `200` unless there is any kind of RPC error (invalid parameters, method not found, etc) | Always `200` unless there is an actual HTTP server error (request parsing error, endpoint not found, etc) |
|
||||
| Notifications: requests that get no reply | (not supported) | Supported for requests that exclude the "id" field |
|
||||
|
||||
## Security
|
||||
|
||||
The RPC interface allows other programs to control Bitcoin Core,
|
||||
|
||||
9
doc/release-notes-27101.md
Normal file
9
doc/release-notes-27101.md
Normal file
@@ -0,0 +1,9 @@
|
||||
JSON-RPC
|
||||
--------
|
||||
|
||||
The JSON-RPC server now recognizes JSON-RPC 2.0 requests and responds with
|
||||
strict adherence to the specification (https://www.jsonrpc.org/specification):
|
||||
|
||||
- Returning HTTP "204 No Content" responses to JSON-RPC 2.0 notifications instead of full responses.
|
||||
- Returning HTTP "200 OK" responses in all other cases, rather than 404 responses for unknown methods, 500 responses for invalid parameters, etc.
|
||||
- Returning either "result" fields or "error" fields in JSON-RPC responses, rather than returning both fields with one field set to null.
|
||||
@@ -298,7 +298,7 @@ public:
|
||||
}
|
||||
addresses.pushKV("total", total);
|
||||
result.pushKV("addresses_known", addresses);
|
||||
return JSONRPCReplyObj(result, NullUniValue, 1);
|
||||
return JSONRPCReplyObj(std::move(result), NullUniValue, /*id=*/1, JSONRPCVersion::V1_LEGACY);
|
||||
}
|
||||
};
|
||||
|
||||
@@ -367,7 +367,7 @@ public:
|
||||
}
|
||||
result.pushKV("relayfee", batch[ID_NETWORKINFO]["result"]["relayfee"]);
|
||||
result.pushKV("warnings", batch[ID_NETWORKINFO]["result"]["warnings"]);
|
||||
return JSONRPCReplyObj(result, NullUniValue, 1);
|
||||
return JSONRPCReplyObj(std::move(result), NullUniValue, /*id=*/1, JSONRPCVersion::V1_LEGACY);
|
||||
}
|
||||
};
|
||||
|
||||
@@ -622,7 +622,7 @@ public:
|
||||
}
|
||||
}
|
||||
|
||||
return JSONRPCReplyObj(UniValue{result}, NullUniValue, 1);
|
||||
return JSONRPCReplyObj(UniValue{result}, NullUniValue, /*id=*/1, JSONRPCVersion::V1_LEGACY);
|
||||
}
|
||||
|
||||
const std::string m_help_doc{
|
||||
@@ -709,7 +709,7 @@ public:
|
||||
UniValue result(UniValue::VOBJ);
|
||||
result.pushKV("address", address_str);
|
||||
result.pushKV("blocks", reply.get_obj()["result"]);
|
||||
return JSONRPCReplyObj(result, NullUniValue, 1);
|
||||
return JSONRPCReplyObj(std::move(result), NullUniValue, /*id=*/1, JSONRPCVersion::V1_LEGACY);
|
||||
}
|
||||
protected:
|
||||
std::string address_str;
|
||||
|
||||
@@ -73,8 +73,11 @@ static std::vector<std::vector<std::string>> g_rpcauth;
|
||||
static std::map<std::string, std::set<std::string>> g_rpc_whitelist;
|
||||
static bool g_rpc_whitelist_default = false;
|
||||
|
||||
static void JSONErrorReply(HTTPRequest* req, const UniValue& objError, const UniValue& id)
|
||||
static void JSONErrorReply(HTTPRequest* req, UniValue objError, const JSONRPCRequest& jreq)
|
||||
{
|
||||
// Sending HTTP errors is a legacy JSON-RPC behavior.
|
||||
Assume(jreq.m_json_version != JSONRPCVersion::V2);
|
||||
|
||||
// Send error reply from json-rpc error object
|
||||
int nStatus = HTTP_INTERNAL_SERVER_ERROR;
|
||||
int code = objError.find_value("code").getInt<int>();
|
||||
@@ -84,7 +87,7 @@ static void JSONErrorReply(HTTPRequest* req, const UniValue& objError, const Uni
|
||||
else if (code == RPC_METHOD_NOT_FOUND)
|
||||
nStatus = HTTP_NOT_FOUND;
|
||||
|
||||
std::string strReply = JSONRPCReply(NullUniValue, objError, id);
|
||||
std::string strReply = JSONRPCReplyObj(NullUniValue, std::move(objError), jreq.id, jreq.m_json_version).write() + "\n";
|
||||
|
||||
req->WriteHeader("Content-Type", "application/json");
|
||||
req->WriteReply(nStatus, strReply);
|
||||
@@ -185,7 +188,7 @@ static bool HTTPReq_JSONRPC(const std::any& context, HTTPRequest* req)
|
||||
// Set the URI
|
||||
jreq.URI = req->GetURI();
|
||||
|
||||
std::string strReply;
|
||||
UniValue reply;
|
||||
bool user_has_whitelist = g_rpc_whitelist.count(jreq.authUser);
|
||||
if (!user_has_whitelist && g_rpc_whitelist_default) {
|
||||
LogPrintf("RPC User %s not allowed to call any methods\n", jreq.authUser);
|
||||
@@ -200,13 +203,23 @@ static bool HTTPReq_JSONRPC(const std::any& context, HTTPRequest* req)
|
||||
req->WriteReply(HTTP_FORBIDDEN);
|
||||
return false;
|
||||
}
|
||||
UniValue result = tableRPC.execute(jreq);
|
||||
|
||||
// Send reply
|
||||
strReply = JSONRPCReply(result, NullUniValue, jreq.id);
|
||||
// Legacy 1.0/1.1 behavior is for failed requests to throw
|
||||
// exceptions which return HTTP errors and RPC errors to the client.
|
||||
// 2.0 behavior is to catch exceptions and return HTTP success with
|
||||
// RPC errors, as long as there is not an actual HTTP server error.
|
||||
const bool catch_errors{jreq.m_json_version == JSONRPCVersion::V2};
|
||||
reply = JSONRPCExec(jreq, catch_errors);
|
||||
|
||||
if (jreq.IsNotification()) {
|
||||
// Even though we do execute notifications, we do not respond to them
|
||||
req->WriteReply(HTTP_NO_CONTENT);
|
||||
return true;
|
||||
}
|
||||
|
||||
// array of requests
|
||||
} else if (valRequest.isArray()) {
|
||||
// Check authorization for each request's method
|
||||
if (user_has_whitelist) {
|
||||
for (unsigned int reqIdx = 0; reqIdx < valRequest.size(); reqIdx++) {
|
||||
if (!valRequest[reqIdx].isObject()) {
|
||||
@@ -223,18 +236,49 @@ static bool HTTPReq_JSONRPC(const std::any& context, HTTPRequest* req)
|
||||
}
|
||||
}
|
||||
}
|
||||
strReply = JSONRPCExecBatch(jreq, valRequest.get_array());
|
||||
|
||||
// Execute each request
|
||||
reply = UniValue::VARR;
|
||||
for (size_t i{0}; i < valRequest.size(); ++i) {
|
||||
// Batches never throw HTTP errors, they are always just included
|
||||
// in "HTTP OK" responses. Notifications never get any response.
|
||||
UniValue response;
|
||||
try {
|
||||
jreq.parse(valRequest[i]);
|
||||
response = JSONRPCExec(jreq, /*catch_errors=*/true);
|
||||
} catch (UniValue& e) {
|
||||
response = JSONRPCReplyObj(NullUniValue, std::move(e), jreq.id, jreq.m_json_version);
|
||||
} catch (const std::exception& e) {
|
||||
response = JSONRPCReplyObj(NullUniValue, JSONRPCError(RPC_PARSE_ERROR, e.what()), jreq.id, jreq.m_json_version);
|
||||
}
|
||||
if (!jreq.IsNotification()) {
|
||||
reply.push_back(std::move(response));
|
||||
}
|
||||
}
|
||||
// Return no response for an all-notification batch, but only if the
|
||||
// batch request is non-empty. Technically according to the JSON-RPC
|
||||
// 2.0 spec, an empty batch request should also return no response,
|
||||
// However, if the batch request is empty, it means the request did
|
||||
// not contain any JSON-RPC version numbers, so returning an empty
|
||||
// response could break backwards compatibility with old RPC clients
|
||||
// relying on previous behavior. Return an empty array instead of an
|
||||
// empty response in this case to favor being backwards compatible
|
||||
// over complying with the JSON-RPC 2.0 spec in this case.
|
||||
if (reply.size() == 0 && valRequest.size() > 0) {
|
||||
req->WriteReply(HTTP_NO_CONTENT);
|
||||
return true;
|
||||
}
|
||||
}
|
||||
else
|
||||
throw JSONRPCError(RPC_PARSE_ERROR, "Top-level object parse error");
|
||||
|
||||
req->WriteHeader("Content-Type", "application/json");
|
||||
req->WriteReply(HTTP_OK, strReply);
|
||||
} catch (const UniValue& objError) {
|
||||
JSONErrorReply(req, objError, jreq.id);
|
||||
req->WriteReply(HTTP_OK, reply.write() + "\n");
|
||||
} catch (UniValue& e) {
|
||||
JSONErrorReply(req, std::move(e), jreq);
|
||||
return false;
|
||||
} catch (const std::exception& e) {
|
||||
JSONErrorReply(req, JSONRPCError(RPC_PARSE_ERROR, e.what()), jreq.id);
|
||||
JSONErrorReply(req, JSONRPCError(RPC_PARSE_ERROR, e.what()), jreq);
|
||||
return false;
|
||||
}
|
||||
return true;
|
||||
|
||||
@@ -10,6 +10,7 @@
|
||||
enum HTTPStatusCode
|
||||
{
|
||||
HTTP_OK = 200,
|
||||
HTTP_NO_CONTENT = 204,
|
||||
HTTP_BAD_REQUEST = 400,
|
||||
HTTP_UNAUTHORIZED = 401,
|
||||
HTTP_FORBIDDEN = 403,
|
||||
|
||||
@@ -26,6 +26,17 @@
|
||||
*
|
||||
* 1.0 spec: http://json-rpc.org/wiki/specification
|
||||
* 1.2 spec: http://jsonrpc.org/historical/json-rpc-over-http.html
|
||||
*
|
||||
* If the server receives a request with the JSON-RPC 2.0 marker `{"jsonrpc": "2.0"}`
|
||||
* then Bitcoin will respond with a strictly specified response.
|
||||
* It will only return an HTTP error code if an actual HTTP error is encountered
|
||||
* such as the endpoint is not found (404) or the request is not formatted correctly (500).
|
||||
* Otherwise the HTTP code is always OK (200) and RPC errors will be included in the
|
||||
* response body.
|
||||
*
|
||||
* 2.0 spec: https://www.jsonrpc.org/specification
|
||||
*
|
||||
* Also see http://www.simple-is-better.org/rpc/#differences-between-1-0-and-2-0
|
||||
*/
|
||||
|
||||
UniValue JSONRPCRequestObj(const std::string& strMethod, const UniValue& params, const UniValue& id)
|
||||
@@ -37,22 +48,23 @@ UniValue JSONRPCRequestObj(const std::string& strMethod, const UniValue& params,
|
||||
return request;
|
||||
}
|
||||
|
||||
UniValue JSONRPCReplyObj(const UniValue& result, const UniValue& error, const UniValue& id)
|
||||
UniValue JSONRPCReplyObj(UniValue result, UniValue error, std::optional<UniValue> id, JSONRPCVersion jsonrpc_version)
|
||||
{
|
||||
UniValue reply(UniValue::VOBJ);
|
||||
if (!error.isNull())
|
||||
reply.pushKV("result", NullUniValue);
|
||||
else
|
||||
reply.pushKV("result", result);
|
||||
reply.pushKV("error", error);
|
||||
reply.pushKV("id", id);
|
||||
return reply;
|
||||
}
|
||||
// Add JSON-RPC version number field in v2 only.
|
||||
if (jsonrpc_version == JSONRPCVersion::V2) reply.pushKV("jsonrpc", "2.0");
|
||||
|
||||
std::string JSONRPCReply(const UniValue& result, const UniValue& error, const UniValue& id)
|
||||
{
|
||||
UniValue reply = JSONRPCReplyObj(result, error, id);
|
||||
return reply.write() + "\n";
|
||||
// Add both result and error fields in v1, even though one will be null.
|
||||
// Omit the null field in v2.
|
||||
if (error.isNull()) {
|
||||
reply.pushKV("result", std::move(result));
|
||||
if (jsonrpc_version == JSONRPCVersion::V1_LEGACY) reply.pushKV("error", NullUniValue);
|
||||
} else {
|
||||
if (jsonrpc_version == JSONRPCVersion::V1_LEGACY) reply.pushKV("result", NullUniValue);
|
||||
reply.pushKV("error", std::move(error));
|
||||
}
|
||||
if (id.has_value()) reply.pushKV("id", std::move(id.value()));
|
||||
return reply;
|
||||
}
|
||||
|
||||
UniValue JSONRPCError(int code, const std::string& message)
|
||||
@@ -171,7 +183,30 @@ void JSONRPCRequest::parse(const UniValue& valRequest)
|
||||
const UniValue& request = valRequest.get_obj();
|
||||
|
||||
// Parse id now so errors from here on will have the id
|
||||
id = request.find_value("id");
|
||||
if (request.exists("id")) {
|
||||
id = request.find_value("id");
|
||||
} else {
|
||||
id = std::nullopt;
|
||||
}
|
||||
|
||||
// Check for JSON-RPC 2.0 (default 1.1)
|
||||
m_json_version = JSONRPCVersion::V1_LEGACY;
|
||||
const UniValue& jsonrpc_version = request.find_value("jsonrpc");
|
||||
if (!jsonrpc_version.isNull()) {
|
||||
if (!jsonrpc_version.isStr()) {
|
||||
throw JSONRPCError(RPC_INVALID_REQUEST, "jsonrpc field must be a string");
|
||||
}
|
||||
// The "jsonrpc" key was added in the 2.0 spec, but some older documentation
|
||||
// incorrectly included {"jsonrpc":"1.0"} in a request object, so we
|
||||
// maintain that for backwards compatibility.
|
||||
if (jsonrpc_version.get_str() == "1.0") {
|
||||
m_json_version = JSONRPCVersion::V1_LEGACY;
|
||||
} else if (jsonrpc_version.get_str() == "2.0") {
|
||||
m_json_version = JSONRPCVersion::V2;
|
||||
} else {
|
||||
throw JSONRPCError(RPC_INVALID_REQUEST, "JSON-RPC version not supported");
|
||||
}
|
||||
}
|
||||
|
||||
// Parse method
|
||||
const UniValue& valMethod{request.find_value("method")};
|
||||
|
||||
@@ -7,13 +7,18 @@
|
||||
#define BITCOIN_RPC_REQUEST_H
|
||||
|
||||
#include <any>
|
||||
#include <optional>
|
||||
#include <string>
|
||||
|
||||
#include <univalue.h>
|
||||
|
||||
enum class JSONRPCVersion {
|
||||
V1_LEGACY,
|
||||
V2
|
||||
};
|
||||
|
||||
UniValue JSONRPCRequestObj(const std::string& strMethod, const UniValue& params, const UniValue& id);
|
||||
UniValue JSONRPCReplyObj(const UniValue& result, const UniValue& error, const UniValue& id);
|
||||
std::string JSONRPCReply(const UniValue& result, const UniValue& error, const UniValue& id);
|
||||
UniValue JSONRPCReplyObj(UniValue result, UniValue error, std::optional<UniValue> id, JSONRPCVersion jsonrpc_version);
|
||||
UniValue JSONRPCError(int code, const std::string& message);
|
||||
|
||||
/** Generate a new RPC authentication cookie and write it to disk */
|
||||
@@ -28,7 +33,7 @@ std::vector<UniValue> JSONRPCProcessBatchReply(const UniValue& in);
|
||||
class JSONRPCRequest
|
||||
{
|
||||
public:
|
||||
UniValue id;
|
||||
std::optional<UniValue> id = UniValue::VNULL;
|
||||
std::string strMethod;
|
||||
UniValue params;
|
||||
enum Mode { EXECUTE, GET_HELP, GET_ARGS } mode = EXECUTE;
|
||||
@@ -36,8 +41,10 @@ public:
|
||||
std::string authUser;
|
||||
std::string peerAddr;
|
||||
std::any context;
|
||||
JSONRPCVersion m_json_version = JSONRPCVersion::V1_LEGACY;
|
||||
|
||||
void parse(const UniValue& valRequest);
|
||||
[[nodiscard]] bool IsNotification() const { return !id.has_value() && m_json_version == JSONRPCVersion::V2; };
|
||||
};
|
||||
|
||||
#endif // BITCOIN_RPC_REQUEST_H
|
||||
|
||||
@@ -360,36 +360,22 @@ bool IsDeprecatedRPCEnabled(const std::string& method)
|
||||
return find(enabled_methods.begin(), enabled_methods.end(), method) != enabled_methods.end();
|
||||
}
|
||||
|
||||
static UniValue JSONRPCExecOne(JSONRPCRequest jreq, const UniValue& req)
|
||||
UniValue JSONRPCExec(const JSONRPCRequest& jreq, bool catch_errors)
|
||||
{
|
||||
UniValue rpc_result(UniValue::VOBJ);
|
||||
|
||||
try {
|
||||
jreq.parse(req);
|
||||
|
||||
UniValue result = tableRPC.execute(jreq);
|
||||
rpc_result = JSONRPCReplyObj(result, NullUniValue, jreq.id);
|
||||
}
|
||||
catch (const UniValue& objError)
|
||||
{
|
||||
rpc_result = JSONRPCReplyObj(NullUniValue, objError, jreq.id);
|
||||
}
|
||||
catch (const std::exception& e)
|
||||
{
|
||||
rpc_result = JSONRPCReplyObj(NullUniValue,
|
||||
JSONRPCError(RPC_PARSE_ERROR, e.what()), jreq.id);
|
||||
UniValue result;
|
||||
if (catch_errors) {
|
||||
try {
|
||||
result = tableRPC.execute(jreq);
|
||||
} catch (UniValue& e) {
|
||||
return JSONRPCReplyObj(NullUniValue, std::move(e), jreq.id, jreq.m_json_version);
|
||||
} catch (const std::exception& e) {
|
||||
return JSONRPCReplyObj(NullUniValue, JSONRPCError(RPC_MISC_ERROR, e.what()), jreq.id, jreq.m_json_version);
|
||||
}
|
||||
} else {
|
||||
result = tableRPC.execute(jreq);
|
||||
}
|
||||
|
||||
return rpc_result;
|
||||
}
|
||||
|
||||
std::string JSONRPCExecBatch(const JSONRPCRequest& jreq, const UniValue& vReq)
|
||||
{
|
||||
UniValue ret(UniValue::VARR);
|
||||
for (unsigned int reqIdx = 0; reqIdx < vReq.size(); reqIdx++)
|
||||
ret.push_back(JSONRPCExecOne(jreq, vReq[reqIdx]));
|
||||
|
||||
return ret.write() + "\n";
|
||||
return JSONRPCReplyObj(std::move(result), NullUniValue, jreq.id, jreq.m_json_version);
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -179,6 +179,6 @@ extern CRPCTable tableRPC;
|
||||
void StartRPC();
|
||||
void InterruptRPC();
|
||||
void StopRPC();
|
||||
std::string JSONRPCExecBatch(const JSONRPCRequest& jreq, const UniValue& vReq);
|
||||
UniValue JSONRPCExec(const JSONRPCRequest& jreq, bool catch_errors);
|
||||
|
||||
#endif // BITCOIN_RPC_SERVER_H
|
||||
|
||||
@@ -175,7 +175,7 @@ std::string HelpExampleCliNamed(const std::string& methodname, const RPCArgList&
|
||||
|
||||
std::string HelpExampleRpc(const std::string& methodname, const std::string& args)
|
||||
{
|
||||
return "> curl --user myusername --data-binary '{\"jsonrpc\": \"1.0\", \"id\": \"curltest\", "
|
||||
return "> curl --user myusername --data-binary '{\"jsonrpc\": \"2.0\", \"id\": \"curltest\", "
|
||||
"\"method\": \"" + methodname + "\", \"params\": [" + args + "]}' -H 'content-type: text/plain;' http://127.0.0.1:8332/\n";
|
||||
}
|
||||
|
||||
@@ -186,7 +186,7 @@ std::string HelpExampleRpcNamed(const std::string& methodname, const RPCArgList&
|
||||
params.pushKV(param.first, param.second);
|
||||
}
|
||||
|
||||
return "> curl --user myusername --data-binary '{\"jsonrpc\": \"1.0\", \"id\": \"curltest\", "
|
||||
return "> curl --user myusername --data-binary '{\"jsonrpc\": \"2.0\", \"id\": \"curltest\", "
|
||||
"\"method\": \"" + methodname + "\", \"params\": " + params.write() + "}' -H 'content-type: text/plain;' http://127.0.0.1:8332/\n";
|
||||
}
|
||||
|
||||
|
||||
@@ -552,7 +552,7 @@ BOOST_AUTO_TEST_CASE(help_example)
|
||||
// test different argument types
|
||||
const RPCArgList& args = {{"foo", "bar"}, {"b", true}, {"n", 1}};
|
||||
BOOST_CHECK_EQUAL(HelpExampleCliNamed("test", args), "> bitcoin-cli -named test foo=bar b=true n=1\n");
|
||||
BOOST_CHECK_EQUAL(HelpExampleRpcNamed("test", args), "> curl --user myusername --data-binary '{\"jsonrpc\": \"1.0\", \"id\": \"curltest\", \"method\": \"test\", \"params\": {\"foo\":\"bar\",\"b\":true,\"n\":1}}' -H 'content-type: text/plain;' http://127.0.0.1:8332/\n");
|
||||
BOOST_CHECK_EQUAL(HelpExampleRpcNamed("test", args), "> curl --user myusername --data-binary '{\"jsonrpc\": \"2.0\", \"id\": \"curltest\", \"method\": \"test\", \"params\": {\"foo\":\"bar\",\"b\":true,\"n\":1}}' -H 'content-type: text/plain;' http://127.0.0.1:8332/\n");
|
||||
|
||||
// test shell escape
|
||||
BOOST_CHECK_EQUAL(HelpExampleCliNamed("test", {{"foo", "b'ar"}}), "> bitcoin-cli -named test foo='b'''ar'\n");
|
||||
@@ -565,7 +565,7 @@ BOOST_AUTO_TEST_CASE(help_example)
|
||||
obj_value.pushKV("b", false);
|
||||
obj_value.pushKV("n", 1);
|
||||
BOOST_CHECK_EQUAL(HelpExampleCliNamed("test", {{"name", obj_value}}), "> bitcoin-cli -named test name='{\"foo\":\"bar\",\"b\":false,\"n\":1}'\n");
|
||||
BOOST_CHECK_EQUAL(HelpExampleRpcNamed("test", {{"name", obj_value}}), "> curl --user myusername --data-binary '{\"jsonrpc\": \"1.0\", \"id\": \"curltest\", \"method\": \"test\", \"params\": {\"name\":{\"foo\":\"bar\",\"b\":false,\"n\":1}}}' -H 'content-type: text/plain;' http://127.0.0.1:8332/\n");
|
||||
BOOST_CHECK_EQUAL(HelpExampleRpcNamed("test", {{"name", obj_value}}), "> curl --user myusername --data-binary '{\"jsonrpc\": \"2.0\", \"id\": \"curltest\", \"method\": \"test\", \"params\": {\"name\":{\"foo\":\"bar\",\"b\":false,\"n\":1}}}' -H 'content-type: text/plain;' http://127.0.0.1:8332/\n");
|
||||
|
||||
// test array params
|
||||
UniValue arr_value(UniValue::VARR);
|
||||
@@ -573,7 +573,7 @@ BOOST_AUTO_TEST_CASE(help_example)
|
||||
arr_value.push_back(false);
|
||||
arr_value.push_back(1);
|
||||
BOOST_CHECK_EQUAL(HelpExampleCliNamed("test", {{"name", arr_value}}), "> bitcoin-cli -named test name='[\"bar\",false,1]'\n");
|
||||
BOOST_CHECK_EQUAL(HelpExampleRpcNamed("test", {{"name", arr_value}}), "> curl --user myusername --data-binary '{\"jsonrpc\": \"1.0\", \"id\": \"curltest\", \"method\": \"test\", \"params\": {\"name\":[\"bar\",false,1]}}' -H 'content-type: text/plain;' http://127.0.0.1:8332/\n");
|
||||
BOOST_CHECK_EQUAL(HelpExampleRpcNamed("test", {{"name", arr_value}}), "> curl --user myusername --data-binary '{\"jsonrpc\": \"2.0\", \"id\": \"curltest\", \"method\": \"test\", \"params\": {\"name\":[\"bar\",false,1]}}' -H 'content-type: text/plain;' http://127.0.0.1:8332/\n");
|
||||
|
||||
// test types don't matter for shell
|
||||
BOOST_CHECK_EQUAL(HelpExampleCliNamed("foo", {{"arg", true}}), HelpExampleCliNamed("foo", {{"arg", "true"}}));
|
||||
|
||||
@@ -4,22 +4,80 @@
|
||||
# file COPYING or http://www.opensource.org/licenses/mit-license.php.
|
||||
"""Tests some generic aspects of the RPC interface."""
|
||||
|
||||
import json
|
||||
import os
|
||||
from test_framework.authproxy import JSONRPCException
|
||||
from dataclasses import dataclass
|
||||
from test_framework.test_framework import BitcoinTestFramework
|
||||
from test_framework.util import assert_equal, assert_greater_than_or_equal
|
||||
from threading import Thread
|
||||
from typing import Optional
|
||||
import subprocess
|
||||
|
||||
|
||||
def expect_http_status(expected_http_status, expected_rpc_code,
|
||||
fcn, *args):
|
||||
try:
|
||||
fcn(*args)
|
||||
raise AssertionError(f"Expected RPC error {expected_rpc_code}, got none")
|
||||
except JSONRPCException as exc:
|
||||
assert_equal(exc.error["code"], expected_rpc_code)
|
||||
assert_equal(exc.http_status, expected_http_status)
|
||||
RPC_INVALID_ADDRESS_OR_KEY = -5
|
||||
RPC_INVALID_PARAMETER = -8
|
||||
RPC_METHOD_NOT_FOUND = -32601
|
||||
RPC_INVALID_REQUEST = -32600
|
||||
RPC_PARSE_ERROR = -32700
|
||||
|
||||
|
||||
@dataclass
|
||||
class BatchOptions:
|
||||
version: Optional[int] = None
|
||||
notification: bool = False
|
||||
request_fields: Optional[dict] = None
|
||||
response_fields: Optional[dict] = None
|
||||
|
||||
|
||||
def format_request(options, idx, fields):
|
||||
request = {}
|
||||
if options.version == 1:
|
||||
request.update(version="1.1")
|
||||
elif options.version == 2:
|
||||
request.update(jsonrpc="2.0")
|
||||
elif options.version is not None:
|
||||
raise NotImplementedError(f"Unknown JSONRPC version {options.version}")
|
||||
if not options.notification:
|
||||
request.update(id=idx)
|
||||
request.update(fields)
|
||||
if options.request_fields:
|
||||
request.update(options.request_fields)
|
||||
return request
|
||||
|
||||
|
||||
def format_response(options, idx, fields):
|
||||
if options.version == 2 and options.notification:
|
||||
return None
|
||||
response = {}
|
||||
if not options.notification:
|
||||
response.update(id=idx)
|
||||
if options.version == 2:
|
||||
response.update(jsonrpc="2.0")
|
||||
else:
|
||||
response.update(result=None, error=None)
|
||||
response.update(fields)
|
||||
if options.response_fields:
|
||||
response.update(options.response_fields)
|
||||
return response
|
||||
|
||||
|
||||
def send_raw_rpc(node, raw_body: bytes) -> tuple[object, int]:
|
||||
return node._request("POST", "/", raw_body)
|
||||
|
||||
|
||||
def send_json_rpc(node, body: object) -> tuple[object, int]:
|
||||
raw = json.dumps(body).encode("utf-8")
|
||||
return send_raw_rpc(node, raw)
|
||||
|
||||
|
||||
def expect_http_rpc_status(expected_http_status, expected_rpc_error_code, node, method, params, version=1, notification=False):
|
||||
req = format_request(BatchOptions(version, notification), 0, {"method": method, "params": params})
|
||||
response, status = send_json_rpc(node, req)
|
||||
|
||||
if expected_rpc_error_code is not None:
|
||||
assert_equal(response["error"]["code"], expected_rpc_error_code)
|
||||
|
||||
assert_equal(status, expected_http_status)
|
||||
|
||||
|
||||
def test_work_queue_getblock(node, got_exceeded_error):
|
||||
@@ -48,37 +106,126 @@ class RPCInterfaceTest(BitcoinTestFramework):
|
||||
assert_greater_than_or_equal(command['duration'], 0)
|
||||
assert_equal(info['logpath'], os.path.join(self.nodes[0].chain_path, 'debug.log'))
|
||||
|
||||
def test_batch_request(self):
|
||||
self.log.info("Testing basic JSON-RPC batch request...")
|
||||
|
||||
results = self.nodes[0].batch([
|
||||
def test_batch_request(self, call_options):
|
||||
calls = [
|
||||
# A basic request that will work fine.
|
||||
{"method": "getblockcount", "id": 1},
|
||||
{"method": "getblockcount"},
|
||||
# Request that will fail. The whole batch request should still
|
||||
# work fine.
|
||||
{"method": "invalidmethod", "id": 2},
|
||||
{"method": "invalidmethod"},
|
||||
# Another call that should succeed.
|
||||
{"method": "getblockhash", "id": 3, "params": [0]},
|
||||
])
|
||||
{"method": "getblockhash", "params": [0]},
|
||||
# Invalid request format
|
||||
{"pizza": "sausage"}
|
||||
]
|
||||
results = [
|
||||
{"result": 0},
|
||||
{"error": {"code": RPC_METHOD_NOT_FOUND, "message": "Method not found"}},
|
||||
{"result": "0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206"},
|
||||
{"error": {"code": RPC_INVALID_REQUEST, "message": "Missing method"}},
|
||||
]
|
||||
|
||||
result_by_id = {}
|
||||
for res in results:
|
||||
result_by_id[res["id"]] = res
|
||||
request = []
|
||||
response = []
|
||||
for idx, (call, result) in enumerate(zip(calls, results), 1):
|
||||
options = call_options(idx)
|
||||
if options is None:
|
||||
continue
|
||||
request.append(format_request(options, idx, call))
|
||||
r = format_response(options, idx, result)
|
||||
if r is not None:
|
||||
response.append(r)
|
||||
|
||||
assert_equal(result_by_id[1]['error'], None)
|
||||
assert_equal(result_by_id[1]['result'], 0)
|
||||
rpc_response, http_status = send_json_rpc(self.nodes[0], request)
|
||||
if len(response) == 0 and len(request) > 0:
|
||||
assert_equal(http_status, 204)
|
||||
assert_equal(rpc_response, None)
|
||||
else:
|
||||
assert_equal(http_status, 200)
|
||||
assert_equal(rpc_response, response)
|
||||
|
||||
assert_equal(result_by_id[2]['error']['code'], -32601)
|
||||
assert_equal(result_by_id[2]['result'], None)
|
||||
def test_batch_requests(self):
|
||||
self.log.info("Testing empty batch request...")
|
||||
self.test_batch_request(lambda idx: None)
|
||||
|
||||
assert_equal(result_by_id[3]['error'], None)
|
||||
assert result_by_id[3]['result'] is not None
|
||||
self.log.info("Testing basic JSON-RPC 2.0 batch request...")
|
||||
self.test_batch_request(lambda idx: BatchOptions(version=2))
|
||||
|
||||
self.log.info("Testing JSON-RPC 2.0 batch with notifications...")
|
||||
self.test_batch_request(lambda idx: BatchOptions(version=2, notification=idx < 2))
|
||||
|
||||
self.log.info("Testing JSON-RPC 2.0 batch of ALL notifications...")
|
||||
self.test_batch_request(lambda idx: BatchOptions(version=2, notification=True))
|
||||
|
||||
# JSONRPC 1.1 does not support batch requests, but test them for backwards compatibility.
|
||||
self.log.info("Testing nonstandard JSON-RPC 1.1 batch request...")
|
||||
self.test_batch_request(lambda idx: BatchOptions(version=1))
|
||||
|
||||
self.log.info("Testing nonstandard mixed JSON-RPC 1.1/2.0 batch request...")
|
||||
self.test_batch_request(lambda idx: BatchOptions(version=2 if idx % 2 else 1))
|
||||
|
||||
self.log.info("Testing nonstandard batch request without version numbers...")
|
||||
self.test_batch_request(lambda idx: BatchOptions())
|
||||
|
||||
self.log.info("Testing nonstandard batch request without version numbers or ids...")
|
||||
self.test_batch_request(lambda idx: BatchOptions(notification=True))
|
||||
|
||||
self.log.info("Testing nonstandard jsonrpc 1.0 version number is accepted...")
|
||||
self.test_batch_request(lambda idx: BatchOptions(request_fields={"jsonrpc": "1.0"}))
|
||||
|
||||
self.log.info("Testing unrecognized jsonrpc version number is rejected...")
|
||||
self.test_batch_request(lambda idx: BatchOptions(
|
||||
request_fields={"jsonrpc": "2.1"},
|
||||
response_fields={"result": None, "error": {"code": RPC_INVALID_REQUEST, "message": "JSON-RPC version not supported"}}))
|
||||
|
||||
def test_http_status_codes(self):
|
||||
self.log.info("Testing HTTP status codes for JSON-RPC requests...")
|
||||
self.log.info("Testing HTTP status codes for JSON-RPC 1.1 requests...")
|
||||
# OK
|
||||
expect_http_rpc_status(200, None, self.nodes[0], "getblockhash", [0])
|
||||
# Errors
|
||||
expect_http_rpc_status(404, RPC_METHOD_NOT_FOUND, self.nodes[0], "invalidmethod", [])
|
||||
expect_http_rpc_status(500, RPC_INVALID_PARAMETER, self.nodes[0], "getblockhash", [42])
|
||||
# force-send empty request
|
||||
response, status = send_raw_rpc(self.nodes[0], b"")
|
||||
assert_equal(response, {"id": None, "result": None, "error": {"code": RPC_PARSE_ERROR, "message": "Parse error"}})
|
||||
assert_equal(status, 500)
|
||||
# force-send invalidly formatted request
|
||||
response, status = send_raw_rpc(self.nodes[0], b"this is bad")
|
||||
assert_equal(response, {"id": None, "result": None, "error": {"code": RPC_PARSE_ERROR, "message": "Parse error"}})
|
||||
assert_equal(status, 500)
|
||||
|
||||
expect_http_status(404, -32601, self.nodes[0].invalidmethod)
|
||||
expect_http_status(500, -8, self.nodes[0].getblockhash, 42)
|
||||
self.log.info("Testing HTTP status codes for JSON-RPC 2.0 requests...")
|
||||
# OK
|
||||
expect_http_rpc_status(200, None, self.nodes[0], "getblockhash", [0], 2, False)
|
||||
# RPC errors but not HTTP errors
|
||||
expect_http_rpc_status(200, RPC_METHOD_NOT_FOUND, self.nodes[0], "invalidmethod", [], 2, False)
|
||||
expect_http_rpc_status(200, RPC_INVALID_PARAMETER, self.nodes[0], "getblockhash", [42], 2, False)
|
||||
# force-send invalidly formatted requests
|
||||
response, status = send_json_rpc(self.nodes[0], {"jsonrpc": 2, "method": "getblockcount"})
|
||||
assert_equal(response, {"result": None, "error": {"code": RPC_INVALID_REQUEST, "message": "jsonrpc field must be a string"}})
|
||||
assert_equal(status, 400)
|
||||
response, status = send_json_rpc(self.nodes[0], {"jsonrpc": "3.0", "method": "getblockcount"})
|
||||
assert_equal(response, {"result": None, "error": {"code": RPC_INVALID_REQUEST, "message": "JSON-RPC version not supported"}})
|
||||
assert_equal(status, 400)
|
||||
|
||||
self.log.info("Testing HTTP status codes for JSON-RPC 2.0 notifications...")
|
||||
# Not notification: id exists
|
||||
response, status = send_json_rpc(self.nodes[0], {"jsonrpc": "2.0", "id": None, "method": "getblockcount"})
|
||||
assert_equal(response["result"], 0)
|
||||
assert_equal(status, 200)
|
||||
# Not notification: JSON 1.1
|
||||
expect_http_rpc_status(200, None, self.nodes[0], "getblockcount", [], 1)
|
||||
# Not notification: has "id" field
|
||||
expect_http_rpc_status(200, None, self.nodes[0], "getblockcount", [], 2, False)
|
||||
block_count = self.nodes[0].getblockcount()
|
||||
# Notification response status code: HTTP_NO_CONTENT
|
||||
expect_http_rpc_status(204, None, self.nodes[0], "generatetoaddress", [1, "bcrt1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqdku202"], 2, True)
|
||||
# The command worked even though there was no response
|
||||
assert_equal(block_count + 1, self.nodes[0].getblockcount())
|
||||
# No error response for notifications even if they are invalid
|
||||
expect_http_rpc_status(204, None, self.nodes[0], "generatetoaddress", [1, "invalid_address"], 2, True)
|
||||
# Sanity check: command was not executed
|
||||
assert_equal(block_count + 1, self.nodes[0].getblockcount())
|
||||
|
||||
def test_work_queue_exceeded(self):
|
||||
self.log.info("Testing work queue exceeded...")
|
||||
@@ -94,7 +241,7 @@ class RPCInterfaceTest(BitcoinTestFramework):
|
||||
|
||||
def run_test(self):
|
||||
self.test_getrpcinfo()
|
||||
self.test_batch_request()
|
||||
self.test_batch_requests()
|
||||
self.test_http_status_codes()
|
||||
self.test_work_queue_exceeded()
|
||||
|
||||
|
||||
@@ -160,6 +160,15 @@ class AuthServiceProxy():
|
||||
raise JSONRPCException({
|
||||
'code': -342, 'message': 'missing HTTP response from server'})
|
||||
|
||||
# Check for no-content HTTP status code, which can be returned when an
|
||||
# RPC client requests a JSON-RPC 2.0 "notification" with no response.
|
||||
# Currently this is only possible if clients call the _request() method
|
||||
# directly to send a raw request.
|
||||
if http_response.status == HTTPStatus.NO_CONTENT:
|
||||
if len(http_response.read()) != 0:
|
||||
raise JSONRPCException({'code': -342, 'message': 'Content received with NO CONTENT status code'})
|
||||
return None, http_response.status
|
||||
|
||||
content_type = http_response.getheader('Content-Type')
|
||||
if content_type != 'application/json':
|
||||
raise JSONRPCException(
|
||||
|
||||
Reference in New Issue
Block a user