1// Copyright (c) 2010 Satoshi Nakamoto
2// Copyright (c) 2009-present The Bitcoin Core developers
3// Distributed under the MIT software license, see the accompanying
4// file COPYING or http://www.opensource.org/licenses/mit-license.php.
5
6#ifndef BITCOIN_RPC_SERVER_H
7#define BITCOIN_RPC_SERVER_H
8
9#include <rpc/request.h>
10#include <rpc/util.h>
11#include <univalue.h>
12
13#include <cstdint>
14#include <functional>
15#include <map>
16#include <string>
17#include <string_view>
18#include <utility>
19#include <vector>
20
21/** Query whether RPC is running */
22bool IsRPCRunning();
23
24/** Throw JSONRPCError if RPC is not running */
25void RpcInterruptionPoint();
26
27/**
28 * Set the RPC warmup status.  When this is done, all RPC calls will error out
29 * immediately with RPC_IN_WARMUP.
30 */
31void SetRPCWarmupStatus(const std::string& newStatus);
32void SetRPCWarmupStarting();
33/* Mark warmup as done.  RPC calls will be processed from now on.  */
34void SetRPCWarmupFinished();
35
36/* returns the current warmup state.  */
37bool RPCIsInWarmup(std::string *outStatus);
38
39typedef RPCMethod (*RpcMethodFnType)();
40
41class CRPCCommand
42{
43public:
44    //! RPC method handler reading request and assigning result. Should return
45    //! true if request is fully handled, false if it should be passed on to
46    //! subsequent handlers.
47    using Actor = std::function<bool(const JSONRPCRequest& request, UniValue& result, bool last_handler)>;
48
49    //! Constructor taking Actor callback supporting multiple handlers.
50    CRPCCommand(std::string category, std::string name, Actor actor, std::vector<std::pair<std::string, bool>> args, intptr_t unique_id)
51        : category(std::move(category)), name(std::move(name)), actor(std::move(actor)), argNames(std::move(args)),
52          unique_id(unique_id)
53    {
54    }
55
56    //! Simplified constructor taking plain RpcMethodFnType function pointer.
57    CRPCCommand(std::string category, RpcMethodFnType fn)
58        : CRPCCommand(
59              category,
60              fn().m_name,
61              [fn](const JSONRPCRequest& request, UniValue& result, bool) { result = fn().HandleRequest(request); return true; },
62              fn().GetArgNames(),
63              intptr_t(fn))
64    {
65        this->metadata_fn = fn;
66    }
67
68    std::string category;
69    std::string name;
70    Actor actor;
71    //! List of method arguments and whether they are named-only. Incoming RPC
72    //! requests contain a "params" field that can either be an array containing
73    //! unnamed arguments or an object containing named arguments. The
74    //! "argNames" vector is used in the latter case to transform the params
75    //! object into an array. Each argument in "argNames" gets mapped to a
76    //! unique position in the array, based on the order it is listed, unless
77    //! the argument is a named-only argument with argNames[x].second set to
78    //! true. Named-only arguments are combined into a JSON object that is
79    //! appended after other arguments, see transformNamedArguments for details.
80    std::vector<std::pair<std::string, bool>> argNames;
81    intptr_t unique_id;
82    RpcMethodFnType metadata_fn{nullptr};
83};
84
85/**
86 * RPC command dispatcher.
87 */
88class CRPCTable
89{
90private:
91    std::map<std::string, std::vector<const CRPCCommand*>> mapCommands;
92public:
93    CRPCTable();
94    std::string help(std::string_view name, const JSONRPCRequest& helpreq) const;
95
96    /**
97     * Execute a method.
98     * @param request The JSONRPCRequest to execute
99     * @returns Result of the call.
100     * @throws an exception (UniValue) when an error happens.
101     */
102    UniValue execute(const JSONRPCRequest &request) const;
103
104    /**
105    * Returns a list of registered commands
106    * @returns List of registered commands.
107    */
108    std::vector<std::string> listCommands() const;
109    /** Return a complete OpenRPC 1.4.1 document for registered commands. */
110    UniValue buildOpenRPCDoc(bool include_hidden = false) const;
111
112    /**
113     * Return all named arguments that need to be converted by the client from string to another JSON type
114     */
115    UniValue dumpArgMap(const JSONRPCRequest& request) const;
116
117    /**
118     * Appends a CRPCCommand to the dispatch table.
119     *
120     * Precondition: RPC server is not running
121     *
122     * Commands with different method names but the same unique_id will
123     * be considered aliases, and only the first registered method name will
124     * show up in the help text command listing. Aliased commands do not have
125     * to have the same behavior. Server and client code can distinguish
126     * between calls based on method name, and aliased commands can also
127     * register different names, types, and numbers of parameters.
128     */
129    void appendCommand(const std::string& name, const CRPCCommand* pcmd);
130    bool removeCommand(const std::string& name, const CRPCCommand* pcmd);
131};
132
133bool IsDeprecatedRPCEnabled(const std::string& method);
134
135extern CRPCTable tableRPC;
136
137void StartRPC();
138void InterruptRPC();
139void StopRPC();
140UniValue JSONRPCExec(const JSONRPCRequest& jreq, bool catch_errors);
141
142#endif // BITCOIN_RPC_SERVER_H
143