RPC argument metadata and typed accessors

251        std::string description,
252        std::vector<RPCArg> inner,
253        RPCArgOptions opts = {})
254        : m_names{std::move(name)},
255          m_type{type},
256          m_inner{std::move(inner)},
257          m_fallback{std::move(fallback)},
258          m_description{std::move(description)},
259          m_opts{std::move(opts)}
260    {
261        CHECK_NONFATAL(type == Type::ARR || type == Type::OBJ || type == Type::OBJ_NAMED_PARAMS || type == Type::OBJ_USER_KEYS);
262    }
263
264    bool IsOptional() const;
265
266    /**
267     * Check whether the request JSON type matches.
268     * Returns true if type matches, or object describing error(s) if not.
269     */
270    UniValue MatchesType(const UniValue& request) const;
271
272    /** Return the first of all aliases */
273    std::string GetFirstName() const;
274
275    /** Return the name, throws when there are aliases */
276    std::string GetName() const;
277
278    /**
279     * Return the type string of the argument.
280     * Set oneline to allow it to be overridden by a custom oneline type string (m_opts.oneline_description).
281     */
282    std::string ToString(bool oneline) const;
283    /**
284     * Return the type string of the argument when it is in an object (dict).
285     * Set oneline to get the oneline representation (less whitespace)
286     */
287    std::string ToStringObj(bool oneline) const;
288    /**
289     * Return the description string, including the argument type and whether
290     * the argument is required.
291     */
292    std::string ToDescriptionString(bool is_named_arg) const;
293};
294
295/// Controls how an RPCResult is rendered in human-readable help text.
296/// The std::string alternative carries the summary text rendered as "...".
297struct HelpElisionNone {}; //!< field printed normally
298struct HelpElisionSkip {}; //!< field hidden from help
299using HelpElision = std::variant<HelpElisionNone, HelpElisionSkip, std::string>;
300
301struct RPCResultOptions {
302    bool skip_type_check{false};
303    HelpElision print_elision{HelpElisionNone{}};
304};
305
306// NOLINTNEXTLINE(misc-no-recursion)
307struct RPCResult {
308    enum class Type {
309        OBJ,
310        ARR,
311        STR,
312        NUM,
313        BOOL,
314        NONE,
315        ANY,        //!< Special type to disable type checks
316        STR_AMOUNT, //!< Special string to represent a floating point amount
317        STR_HEX,    //!< Special string with only hex chars
318        OBJ_DYN,    //!< Special dictionary with keys that are not literals
319        ARR_FIXED,  //!< Special array that has a fixed number of entries
320        NUM_TIME,   //!< Special numeric to denote unix epoch time
321    };
322
323    const Type m_type;
324    const std::string m_key_name;         //!< Only used for dicts
325    const std::vector<RPCResult> m_inner; //!< Only used for arrays or dicts
326    const bool m_optional;
327    const RPCResultOptions m_opts;
328    const std::string m_description;
329    const std::string m_cond;
330
331    RPCResult(
332        std::string cond,
333        Type type,
334        std::string m_key_name,
335        bool optional,
336        std::string description,
337        std::vector<RPCResult> inner = {},
338        RPCResultOptions opts = {})
339        : m_type{type},
340          m_key_name{std::move(m_key_name)},
341          m_inner{std::move(inner)},
342          m_optional{optional},
343          m_opts{std::move(opts)},
344          m_description{std::move(description)},
345          m_cond{std::move(cond)}
346    {
347        CHECK_NONFATAL(!m_cond.empty());
348        CheckInnerDoc();
349    }
350
351    RPCResult(
352        std::string cond,
353        Type type,
354        std::string m_key_name,
355        std::string description,
356        std::vector<RPCResult> inner = {},
357        RPCResultOptions opts = {})
358        : RPCResult{std::move(cond), type, std::move(m_key_name), /*optional=*/false, std::move(description), std::move(inner), std::move(opts)} {}
359
360    RPCResult(
361        Type type,
362        std::string m_key_name,
363        bool optional,
364        std::string description,
365        std::vector<RPCResult> inner = {},
366        RPCResultOptions opts = {})
367        : m_type{type},
368          m_key_name{std::move(m_key_name)},
369          m_inner{std::move(inner)},
370          m_optional{optional},
371          m_opts{std::move(opts)},
372          m_description{std::move(description)},
373          m_cond{}
374    {
375        CheckInnerDoc();
376    }
377
378    RPCResult(
379        Type type,
380        std::string m_key_name,
381        std::string description,
382        std::vector<RPCResult> inner = {},
383        RPCResultOptions opts = {})
384        : RPCResult{type, std::move(m_key_name), /*optional=*/false, std::move(description), std::move(inner), std::move(opts)} {}
385
386    /// Copy with replacement options, for stamping new opts onto an existing result.
387    RPCResult(const RPCResult& other, RPCResultOptions opts)
388        : m_type{other.m_type},
389          m_key_name{other.m_key_name},
390          m_inner{other.m_inner},
391          m_optional{other.m_optional},
392          m_opts{std::move(opts)},
393          m_description{other.m_description},
394          m_cond{other.m_cond} {}
395
396    /** Append the sections of the result. */
397    void ToSections(Sections& sections, OuterType outer_type = OuterType::NONE, int current_indent = 0) const;
398    /** Return the type string of the result when it is in an object (dict). */
399    std::string ToStringObj() const;
400    /** Return the description string, including the result type. */
401    std::string ToDescriptionString() const;
402    /** Check whether the result JSON type matches.
403     * Returns true if type matches, or object describing error(s) if not.
404     */
405    UniValue MatchesType(const UniValue& result) const;
406
407private:
408    void CheckInnerDoc() const;
409};
410
411/// Stamp elision onto an entire vector of RPCResult fields at once.
412/// Merges into existing m_opts so that flags like skip_type_check are preserved.
413std::vector<RPCResult> ElideGroup(std::vector<RPCResult> fields, std::string summary = "");
414
415struct RPCResults {
416    const std::vector<RPCResult> m_results;
417
418    RPCResults(RPCResult result)
419        : m_results{{result}}
420    {
421    }
422
423    RPCResults(std::initializer_list<RPCResult> results)
424        : m_results{results}
425    {
426    }
427
428    /**
429     * Return the description string.
430     */
431    std::string ToDescriptionString() const;
432};
433
434struct RPCExamples {
435    const std::string m_examples;
436    explicit RPCExamples(
437        std::string examples)
438        : m_examples(std::move(examples))
439    {
440    }
441    std::string ToDescriptionString() const;
442};
443
444class RPCMethod
445{
446public:
447    RPCMethod(std::string name, std::string description, std::vector<RPCArg> args, RPCResults results, RPCExamples examples);
448    using RPCMethodImpl = std::function<UniValue(const RPCMethod&, const JSONRPCRequest&)>;
449    RPCMethod(std::string name, std::string description, std::vector<RPCArg> args, RPCResults results, RPCExamples examples, RPCMethodImpl fun);
450
451    UniValue HandleRequest(const JSONRPCRequest& request) const;
452    /**
453     * @brief Helper to get a required or default-valued request argument.
454     *
455     * Use this function when the argument is required or when it has a default value. If the
456     * argument is optional and may not be provided, use MaybeArg instead.
457     *
458     * This function only works during m_fun(), i.e., it should only be used in
459     * RPC method implementations. It internally checks whether the user-passed
460     * argument isNull() and parses (from JSON) and returns the user-passed argument,
461     * or the default value derived from the RPCArg documentation.
462     *
463     * The instantiation of this helper for type R must match the corresponding RPCArg::Type.
464     *
465     * @return The value of the RPC argument (or the default value) cast to type R.
466     *
467     * @see MaybeArg for handling optional arguments without default values.
468     */
469    template <typename R>
470    auto Arg(std::string_view key) const
471    {
472        auto i{GetParamIndex(key)};
473        // Return argument (required or with default value).
474        if constexpr (std::is_trivially_copyable_v<R>) {
475            // Return trivially copyable types by value.
476            return ArgValue<R>(i);
477        } else {
478            // Return everything else by reference.
479            return ArgValue<const R&>(i);
480        }
481    }
482    /**
483     * @brief Helper to get an optional request argument.
484     *
485     * Use this function when the argument is optional and does not have a default value. If the
486     * argument is required or has a default value, use Arg instead.
487     *
488     * This function only works during m_fun(), i.e., it should only be used in
489     * RPC method implementations. It internally checks whether the user-passed
490     * argument isNull() and parses (from JSON) and returns the user-passed argument,
491     * or a falsy value if no argument was passed.
492     *
493     * The instantiation of this helper for type R must match the corresponding RPCArg::Type.
494     *
495     * @return For trivially copyable types, a std::optional<R> is returned.
496     *         For other types, a R* pointer to the argument is returned. If the
497     *         argument is not provided, std::nullopt or a null pointer is returned.
498     *
499     * @see Arg for handling arguments that are required or have a default value.
500     */