Skip to content

Commit 702b56d

Browse files
ryanofskyachow101
ryanofsky
and
achow101
committed
RPC: Add add OBJ_NAMED_PARAMS type
OBJ_NAMED_PARAMS type works the same as OBJ type except it registers the object keys to be accepted as top-level named-only RPC parameters. Generated documentation also lists the object keys seperately in a new "Named arguments" section of help text. Named-only RPC parameters have the same semantics as python keyword-only arguments (https://peps.python.org/pep-3102/). They are always required to be passed by name, so they don't affect interpretation of positional arguments, and aren't affected when positional arguments are added or removed. The new OBJ_NAMED_PARAMS type is used in the next commit to make it easier to pass options values to various RPC methods. Co-authored-by: Andrew Chow <github@achow101.com>
1 parent 1d7f1ad commit 702b56d

File tree

5 files changed

+133
-29
lines changed

5 files changed

+133
-29
lines changed

‎src/rpc/server.cpp

Lines changed: 38 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -392,7 +392,7 @@ std::string JSONRPCExecBatch(const JSONRPCRequest& jreq, const UniValue& vReq)
392392
* Process named arguments into a vector of positional arguments, based on the
393393
* passed-in specification for the RPC call's arguments.
394394
*/
395-
static inline JSONRPCRequest transformNamedArguments(const JSONRPCRequest& in, const std::vector<std::string>& argNames)
395+
static inline JSONRPCRequest transformNamedArguments(const JSONRPCRequest& in, const std::vector<std::pair<std::string, bool>>& argNames)
396396
{
397397
JSONRPCRequest out = in;
398398
out.params = UniValue(UniValue::VARR);
@@ -417,7 +417,9 @@ static inline JSONRPCRequest transformNamedArguments(const JSONRPCRequest& in, c
417417
// "args" parameter, if present.
418418
int hole = 0;
419419
int initial_hole_size = 0;
420-
for (const std::string &argNamePattern: argNames) {
420+
const std::string* initial_param = nullptr;
421+
UniValue options{UniValue::VOBJ};
422+
for (const auto& [argNamePattern, named_only]: argNames) {
421423
std::vector<std::string> vargNames = SplitString(argNamePattern, '|');
422424
auto fr = argsIn.end();
423425
for (const std::string & argName : vargNames) {
@@ -426,30 +428,58 @@ static inline JSONRPCRequest transformNamedArguments(const JSONRPCRequest& in, c
426428
break;
427429
}
428430
}
429-
if (fr != argsIn.end()) {
431+
432+
// Handle named-only parameters by pushing them into a temporary options
433+
// object, and then pushing the accumulated options as the next
434+
// positional argument.
435+
if (named_only) {
436+
if (fr != argsIn.end()) {
437+
if (options.exists(fr->first)) {
438+
throw JSONRPCError(RPC_INVALID_PARAMETER, "Parameter " + fr->first + " specified multiple times");
439+
}
440+
options.__pushKV(fr->first, *fr->second);
441+
argsIn.erase(fr);
442+
}
443+
continue;
444+
}
445+
446+
if (!options.empty() || fr != argsIn.end()) {
430447
for (int i = 0; i < hole; ++i) {
431448
// Fill hole between specified parameters with JSON nulls,
432449
// but not at the end (for backwards compatibility with calls
433450
// that act based on number of specified parameters).
434451
out.params.push_back(UniValue());
435452
}
436453
hole = 0;
437-
out.params.push_back(*fr->second);
438-
argsIn.erase(fr);
454+
if (!initial_param) initial_param = &argNamePattern;
439455
} else {
440456
hole += 1;
441457
if (out.params.empty()) initial_hole_size = hole;
442458
}
459+
460+
// If named input parameter "fr" is present, push it onto out.params. If
461+
// options are present, push them onto out.params. If both are present,
462+
// throw an error.
463+
if (fr != argsIn.end()) {
464+
if (!options.empty()) {
465+
throw JSONRPCError(RPC_INVALID_PARAMETER, "Parameter " + fr->first + " conflicts with parameter " + options.getKeys().front());
466+
}
467+
out.params.push_back(*fr->second);
468+
argsIn.erase(fr);
469+
}
470+
if (!options.empty()) {
471+
out.params.push_back(std::move(options));
472+
options = UniValue{UniValue::VOBJ};
473+
}
443474
}
444475
// If leftover "args" param was found, use it as a source of positional
445476
// arguments and add named arguments after. This is a convenience for
446477
// clients that want to pass a combination of named and positional
447478
// arguments as described in doc/JSON-RPC-interface.md#parameter-passing
448479
auto positional_args{argsIn.extract("args")};
449480
if (positional_args && positional_args.mapped()->isArray()) {
450-
const bool has_named_arguments{initial_hole_size < (int)argNames.size()};
451-
if (initial_hole_size < (int)positional_args.mapped()->size() && has_named_arguments) {
452-
throw JSONRPCError(RPC_INVALID_PARAMETER, "Parameter " + argNames[initial_hole_size] + " specified twice both as positional and named argument");
481+
if (initial_hole_size < (int)positional_args.mapped()->size() && initial_param) {
482+
throw JSONRPCError(RPC_INVALID_PARAMETER, "Parameter " + *initial_param + " specified twice both as positional and named argument");
453483
}
454484
// Assign positional_args to out.params and append named_args after.
455485
UniValue named_args{std::move(out.params)};

‎src/rpc/server.h

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,7 @@ class CRPCCommand
9595
using Actor = std::function<bool(const JSONRPCRequest& request, UniValue& result, bool last_handler)>;
9696

9797
//! Constructor taking Actor callback supporting multiple handlers.
98-
CRPCCommand(std::string category, std::string name, Actor actor, std::vector<std::string> args, intptr_t unique_id)
98+
CRPCCommand(std::string category, std::string name, Actor actor, std::vector<std::pair<std::string, bool>> args, intptr_t unique_id)
9999
: category(std::move(category)), name(std::move(name)), actor(std::move(actor)), argNames(std::move(args)),
100100
unique_id(unique_id)
101101
{
@@ -115,7 +115,16 @@ class CRPCCommand
115115
std::string category;
116116
std::string name;
117117
Actor actor;
118-
std::vector<std::string> argNames;
118+
//! List of method arguments and whether they are named-only. Incoming RPC
119+
//! requests contain a "params" field that can either be an array containing
120+
//! unnamed arguments or an object containing named arguments. The
121+
//! "argNames" vector is used in the latter case to transform the params
122+
//! object into an array. Each argument in "argNames" gets mapped to a
123+
//! unique position in the array, based on the order it is listed, unless
124+
//! the argument is a named-only argument with argNames[x].second set to
125+
//! true. Named-only arguments are combined into a JSON object that is
126+
//! appended after other arguments, see transformNamedArguments for details.
127+
std::vector<std::pair<std::string, bool>> argNames;
119128
intptr_t unique_id;
120129
};
121130

‎src/rpc/util.cpp

Lines changed: 48 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -389,7 +389,8 @@ struct Sections {
389389
case RPCArg::Type::NUM:
390390
case RPCArg::Type::AMOUNT:
391391
case RPCArg::Type::RANGE:
392-
case RPCArg::Type::BOOL: {
392+
case RPCArg::Type::BOOL:
393+
case RPCArg::Type::OBJ_NAMED_PARAMS: {
393394
if (is_top_level_arg) return; // Nothing more to do for non-recursive types on first recursion
394395
auto left = indent;
395396
if (arg.m_opts.type_str.size() != 0 && push_name) {
@@ -605,12 +606,17 @@ bool RPCHelpMan::IsValidNumArgs(size_t num_args) const
605606
return num_required_args <= num_args && num_args <= m_args.size();
606607
}
607608

608-
std::vector<std::string> RPCHelpMan::GetArgNames() const
609+
std::vector<std::pair<std::string, bool>> RPCHelpMan::GetArgNames() const
609610
{
610-
std::vector<std::string> ret;
611+
std::vector<std::pair<std::string, bool>> ret;
611612
ret.reserve(m_args.size());
612613
for (const auto& arg : m_args) {
613-
ret.emplace_back(arg.m_names);
614+
if (arg.m_type == RPCArg::Type::OBJ_NAMED_PARAMS) {
615+
for (const auto& inner : arg.m_inner) {
616+
ret.emplace_back(inner.m_names, /*named_only=*/true);
617+
}
618+
}
619+
ret.emplace_back(arg.m_names, /*named_only=*/false);
614620
}
615621
return ret;
616622
}
@@ -642,20 +648,31 @@ std::string RPCHelpMan::ToString() const
642648

643649
// Arguments
644650
Sections sections;
651+
Sections named_only_sections;
645652
for (size_t i{0}; i < m_args.size(); ++i) {
646653
const auto& arg = m_args.at(i);
647654
if (arg.m_opts.hidden) break; // Any arg that follows is also hidden
648655

649-
if (i == 0) ret += "\nArguments:\n";
650-
651656
// Push named argument name and description
652657
sections.m_sections.emplace_back(::ToString(i + 1) + ". " + arg.GetFirstName(), arg.ToDescriptionString(/*is_named_arg=*/true));
653658
sections.m_max_pad = std::max(sections.m_max_pad, sections.m_sections.back().m_left.size());
654659

655660
// Recursively push nested args
656661
sections.Push(arg);
662+
663+
// Push named-only argument sections
664+
if (arg.m_type == RPCArg::Type::OBJ_NAMED_PARAMS) {
665+
for (const auto& arg_inner : arg.m_inner) {
666+
named_only_sections.PushSection({arg_inner.GetFirstName(), arg_inner.ToDescriptionString(/*is_named_arg=*/true)});
667+
named_only_sections.Push(arg_inner);
668+
}
669+
}
657670
}
671+
672+
if (!sections.m_sections.empty()) ret += "\nArguments:\n";
658673
ret += sections.ToString();
674+
if (!named_only_sections.m_sections.empty()) ret += "\nNamed Arguments:\n";
675+
ret += named_only_sections.ToString();
659676

660677
// Result
661678
ret += m_results.ToDescriptionString();
@@ -669,17 +686,30 @@ std::string RPCHelpMan::ToString() const
669686
UniValue RPCHelpMan::GetArgMap() const
670687
{
671688
UniValue arr{UniValue::VARR};
689+
690+
auto push_back_arg_info = [&arr](const std::string& rpc_name, int pos, const std::string& arg_name, const RPCArg::Type& type) {
691+
UniValue map{UniValue::VARR};
692+
map.push_back(rpc_name);
693+
map.push_back(pos);
694+
map.push_back(arg_name);
695+
map.push_back(type == RPCArg::Type::STR ||
696+
type == RPCArg::Type::STR_HEX);
697+
arr.push_back(map);
698+
};
699+
672700
for (int i{0}; i < int(m_args.size()); ++i) {
673701
const auto& arg = m_args.at(i);
674702
std::vector<std::string> arg_names = SplitString(arg.m_names, '|');
675703
for (const auto& arg_name : arg_names) {
676-
UniValue map{UniValue::VARR};
677-
map.push_back(m_name);
678-
map.push_back(i);
679-
map.push_back(arg_name);
680-
map.push_back(arg.m_type == RPCArg::Type::STR ||
681-
arg.m_type == RPCArg::Type::STR_HEX);
682-
arr.push_back(map);
704+
push_back_arg_info(m_name, i, arg_name, arg.m_type);
705+
if (arg.m_type == RPCArg::Type::OBJ_NAMED_PARAMS) {
706+
for (const auto& inner : arg.m_inner) {
707+
std::vector<std::string> inner_names = SplitString(inner.m_names, '|');
708+
for (const std::string& inner_name : inner_names) {
709+
push_back_arg_info(m_name, i, inner_name, inner.m_type);
710+
}
711+
}
712+
}
683713
}
684714
}
685715
return arr;
@@ -708,6 +738,7 @@ static std::optional<UniValue::VType> ExpectedType(RPCArg::Type type)
708738
return UniValue::VBOOL;
709739
}
710740
case Type::OBJ:
741+
case Type::OBJ_NAMED_PARAMS:
711742
case Type::OBJ_USER_KEYS: {
712743
return UniValue::VOBJ;
713744
}
@@ -781,6 +812,7 @@ std::string RPCArg::ToDescriptionString(bool is_named_arg) const
781812
break;
782813
}
783814
case Type::OBJ:
815+
case Type::OBJ_NAMED_PARAMS:
784816
case Type::OBJ_USER_KEYS: {
785817
ret += "json object";
786818
break;
@@ -809,6 +841,7 @@ std::string RPCArg::ToDescriptionString(bool is_named_arg) const
809841
} // no default case, so the compiler can warn about missing cases
810842
}
811843
ret += ")";
844+
if (m_type == Type::OBJ_NAMED_PARAMS) ret += " Options object that can be used to pass named arguments, listed below.";
812845
ret += m_description.empty() ? "" : " " + m_description;
813846
return ret;
814847
}
@@ -1054,6 +1087,7 @@ std::string RPCArg::ToStringObj(const bool oneline) const
10541087
}
10551088
return res + "...]";
10561089
case Type::OBJ:
1090+
case Type::OBJ_NAMED_PARAMS:
10571091
case Type::OBJ_USER_KEYS:
10581092
// Currently unused, so avoid writing dead code
10591093
NONFATAL_UNREACHABLE();
@@ -1077,6 +1111,7 @@ std::string RPCArg::ToString(const bool oneline) const
10771111
return GetFirstName();
10781112
}
10791113
case Type::OBJ:
1114+
case Type::OBJ_NAMED_PARAMS:
10801115
case Type::OBJ_USER_KEYS: {
10811116
const std::string res = Join(m_inner, ",", [&](const RPCArg& i) { return i.ToStringObj(oneline); });
10821117
if (m_type == Type::OBJ) {

‎src/rpc/util.h

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,13 @@ struct RPCArg {
139139
STR,
140140
NUM,
141141
BOOL,
142+
OBJ_NAMED_PARAMS, //!< Special type that behaves almost exactly like
143+
//!< OBJ, defining an options object with a list of
144+
//!< pre-defined keys. The only difference between OBJ
145+
//!< and OBJ_NAMED_PARAMS is that OBJ_NAMED_PARMS
146+
//!< also allows the keys to be passed as top-level
147+
//!< named parameters, as a more convenient way to pass
148+
//!< options to the RPC method without nesting them.
142149
OBJ_USER_KEYS, //!< Special type where the user must set the keys e.g. to define multiple addresses; as opposed to e.g. an options object where the keys are predefined
143150
AMOUNT, //!< Special type representing a floating point amount (can be either NUM or STR)
144151
STR_HEX, //!< Special type that is a STR with only hex chars
@@ -183,7 +190,7 @@ struct RPCArg {
183190
m_description{std::move(description)},
184191
m_opts{std::move(opts)}
185192
{
186-
CHECK_NONFATAL(type != Type::ARR && type != Type::OBJ && type != Type::OBJ_USER_KEYS);
193+
CHECK_NONFATAL(type != Type::ARR && type != Type::OBJ && type != Type::OBJ_NAMED_PARAMS && type != Type::OBJ_USER_KEYS);
187194
}
188195

189196
RPCArg(
@@ -200,7 +207,7 @@ struct RPCArg {
200207
m_description{std::move(description)},
201208
m_opts{std::move(opts)}
202209
{
203-
CHECK_NONFATAL(type == Type::ARR || type == Type::OBJ || type == Type::OBJ_USER_KEYS);
210+
CHECK_NONFATAL(type == Type::ARR || type == Type::OBJ || type == Type::OBJ_NAMED_PARAMS || type == Type::OBJ_USER_KEYS);
204211
}
205212

206213
bool IsOptional() const;
@@ -369,7 +376,8 @@ class RPCHelpMan
369376
UniValue GetArgMap() const;
370377
/** If the supplied number of args is neither too small nor too high */
371378
bool IsValidNumArgs(size_t num_args) const;
372-
std::vector<std::string> GetArgNames() const;
379+
//! Return list of arguments and whether they are named-only.
380+
std::vector<std::pair<std::string, bool>> GetArgNames() const;
373381

374382
const std::string m_name;
375383

‎src/test/rpc_tests.cpp

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -42,11 +42,11 @@ class HasJSON
4242
class RPCTestingSetup : public TestingSetup
4343
{
4444
public:
45-
UniValue TransformParams(const UniValue& params, std::vector<std::string> arg_names) const;
45+
UniValue TransformParams(const UniValue& params, std::vector<std::pair<std::string, bool>> arg_names) const;
4646
UniValue CallRPC(std::string args);
4747
};
4848

49-
UniValue RPCTestingSetup::TransformParams(const UniValue& params, std::vector<std::string> arg_names) const
49+
UniValue RPCTestingSetup::TransformParams(const UniValue& params, std::vector<std::pair<std::string, bool>> arg_names) const
5050
{
5151
UniValue transformed_params;
5252
CRPCTable table;
@@ -84,7 +84,7 @@ BOOST_FIXTURE_TEST_SUITE(rpc_tests, RPCTestingSetup)
8484

8585
BOOST_AUTO_TEST_CASE(rpc_namedparams)
8686
{
87-
const std::vector<std::string> arg_names{"arg1", "arg2", "arg3", "arg4", "arg5"};
87+
const std::vector<std::pair<std::string, bool>> arg_names{{"arg1", false}, {"arg2", false}, {"arg3", false}, {"arg4", false}, {"arg5", false}};
8888

8989
// Make sure named arguments are transformed into positional arguments in correct places separated by nulls
9090
BOOST_CHECK_EQUAL(TransformParams(JSON(R"({"arg2": 2, "arg4": 4})"), arg_names).write(), "[null,2,null,4]");
@@ -109,6 +109,28 @@ BOOST_AUTO_TEST_CASE(rpc_namedparams)
109109
BOOST_CHECK_EQUAL(TransformParams(JSON(R"([1,2,3,4,5,6,7,8,9,10])"), arg_names).write(), "[1,2,3,4,5,6,7,8,9,10]");
110110
}
111111

112+
BOOST_AUTO_TEST_CASE(rpc_namedonlyparams)
113+
{
114+
const std::vector<std::pair<std::string, bool>> arg_names{{"arg1", false}, {"arg2", false}, {"opt1", true}, {"opt2", true}, {"options", false}};
115+
116+
// Make sure optional parameters are really optional.
117+
BOOST_CHECK_EQUAL(TransformParams(JSON(R"({"arg1": 1, "arg2": 2})"), arg_names).write(), "[1,2]");
118+
119+
// Make sure named-only parameters are passed as options.
120+
BOOST_CHECK_EQUAL(TransformParams(JSON(R"({"arg1": 1, "arg2": 2, "opt1": 10, "opt2": 20})"), arg_names).write(), R"([1,2,{"opt1":10,"opt2":20}])");
121+
122+
// Make sure options can be passed directly.
123+
BOOST_CHECK_EQUAL(TransformParams(JSON(R"({"arg1": 1, "arg2": 2, "options":{"opt1": 10, "opt2": 20}})"), arg_names).write(), R"([1,2,{"opt1":10,"opt2":20}])");
124+
125+
// Make sure options and named parameters conflict.
126+
BOOST_CHECK_EXCEPTION(TransformParams(JSON(R"({"arg1": 1, "arg2": 2, "opt1": 10, "options":{"opt1": 10}})"), arg_names), UniValue,
127+
HasJSON(R"({"code":-8,"message":"Parameter options conflicts with parameter opt1"})"));
128+
129+
// Make sure options object specified through args array conflicts.
130+
BOOST_CHECK_EXCEPTION(TransformParams(JSON(R"({"args": [1, 2, {"opt1": 10}], "opt2": 20})"), arg_names), UniValue,
131+
HasJSON(R"({"code":-8,"message":"Parameter options specified twice both as positional and named argument"})"));
132+
}
133+
112134
BOOST_AUTO_TEST_CASE(rpc_rawparams)
113135
{
114136
// Test raw transaction API argument handling

0 commit comments

Comments
 (0)