READ THE CODE

Inside Bitcoin

The code behind the network, with room to understand it.

Stable release v32.1bitcoin/bitcoin · f0de87f04062 ↗3,020 source files · 47.5 MB stored on the server340 file guides

Release published 2026-10-28 · Snapshot fetched 2026-11-01. Latest stable release at fetch time; development branches and Git history are excluded. Only the selected code window and visible folders load here.

23,787 bytes · SHA-256 030fc40886d40e94… · View upstream ↗

1// Copyright (c) 2015-present The Bitcoin Core developers
2// Distributed under the MIT software license, see the accompanying
3// file COPYING or http://www.opensource.org/licenses/mit-license.php.
4
5#ifndef BITCOIN_HTTPSERVER_H
6#define BITCOIN_HTTPSERVER_H
7
8#include <atomic>
9#include <functional>
10#include <memory>
11#include <optional>
12#include <span>
13#include <stdexcept>
14#include <string>
15#include <vector>
16
17#include <netaddress.h>
18#include <rpc/protocol.h>
19#include <util/byte_units.h>
20#include <util/expected.h>
21#include <util/sock.h>
22#include <util/strencodings.h>
23#include <util/string.h>
24#include <util/threadinterrupt.h>
25#include <util/time.h>
26
27namespace util {
28class SignalInterrupt;
29} // namespace util
30
31/**
32 * The default value for `-rpcthreads`. This number of threads will be created at startup.
33 */
34inline constexpr int DEFAULT_HTTP_THREADS=16;
35
36/**
37 * The default value for `-rpcworkqueue`. This is the maximum depth of the work queue,
38 * we don't allocate this number of work queue items upfront.
39 */
40inline constexpr int DEFAULT_HTTP_WORKQUEUE=64;
41
42inline constexpr int DEFAULT_HTTP_SERVER_TIMEOUT=30;
43
44/**
45 * Maximum number of connected HTTP clients
46 */
47inline constexpr int DEFAULT_MAX_HTTP_CONNECTIONS = 16;
48
49enum class HTTPRequestMethod {
50    UNKNOWN,
51    GET,
52    POST,
53    HEAD,
54    PUT
55};
56
57class HTTPRequest;
58
59/** Handler for requests to a certain HTTP path */
60using HTTPRequestHandler = std::function<void(HTTPRequest* req, const std::string&)>;
61
62/** Register handler for prefix.
63 * If multiple handlers match a prefix, the first-registered one will
64 * be invoked.
65 */
66void RegisterHTTPHandler(const std::string &prefix, bool exactMatch, const HTTPRequestHandler &handler);
67/** Unregister handler for prefix */
68void UnregisterHTTPHandler(const std::string &prefix, bool exactMatch);
69
70namespace bitcoin_http {
71//! Shortest valid request line, used by libevent in evhttp_parse_request_line()
72inline constexpr size_t MIN_REQUEST_LINE_LENGTH = std::string_view("GET / HTTP/1.0").size();
73
74//! Maximum size of each headers line in an HTTP request,
75//! also the maximum size of all headers total.
76//! See https://github.com/bitcoin/bitcoin/pull/6859
77//! And libevent http.c evhttp_parse_headers_()
78inline constexpr size_t MAX_HEADERS_SIZE{8192};
79
80//! Maximum size of an HTTP request body received from a client.
81//! Also used to limit data queued for sending back to client.
82inline constexpr uint64_t MAX_BODY_SIZE{32_MiB};
83
84//! Thrown when a request body exceeds MAX_BODY_SIZE (or *will* exceed, in chunked transfer)
85//! so the server can reply with more specific code 413 (content too large) vs general 400 (bad request)
86struct ContentTooLargeError : std::runtime_error {
87    using std::runtime_error::runtime_error;
88};
89} // namespace bitcoin_http
90
91class HTTPHeaders
92{
93public:
94    /**
95     * @param[in] key The field-name of the header to search for
96     * @returns The value of the first header that matches the provided key
97     *          nullopt if key is not found
98     */
99    std::optional<std::string> FindFirst(std::string_view key) const;
100    /**
101     * @param[in] key The field-name of the header to search for
102     * @returns Views into all values matching the provided key (valid while this object is alive)
103     */
104    std::vector<std::string_view> FindAll(std::string_view key) const;
105    void Write(std::string&& key, std::string&& value);
106    /**
107     * @param[in] key The field-name of the header to search for and delete
108     */
109    void RemoveAll(std::string_view key);
110    /**
111     * @param[in] reader A LineReader instance initialized with the client's receive buffer.
112     * @param[in] write  Whether or not to write the parsed data to the object after validation.
113     * @returns false if LineReader hits the end of the buffer before reading an
114     *                \n, meaning that we are still waiting on more data from the client.
115     *          true  after reading an entire HTTP headers section, terminated
116     *                by an empty line and \n.
117     * @throws on exceeded read limit and on bad headers syntax (e.g. no ":" in a line)
118     */
119    bool Read(util::LineReader& reader, bool write = true);
120    std::string Stringify() const;
121
122private:
123    /**
124     * Headers can have duplicate field names, so we use a vector of key-value pairs instead of a map.
125     * https://httpwg.org/specs/rfc9110.html#rfc.section.5.2
126     */
127    std::vector<std::pair<std::string, std::string>> m_headers;
128
129    //! Track total bytes consumed in Read() for limit checks
130    size_t m_consumed{0};
131};
132
133struct HTTPVersion {
134    /**
135     * Default HTTP protocol version 1.1 is used by error responses
136     * when a request is unreadable.
137     */
138    /// @{
139    uint8_t major{1};
140    uint8_t minor{1};
141    /// @}
142};
143
144struct HTTPResponse {
145    HTTPVersion version;
146    HTTPStatusCode status{HTTP_INTERNAL_SERVER_ERROR};
147    HTTPHeaders headers;
148
149    std::string StringifyHeaders() const;
150};
151
152class HTTPRemoteClient;
153
154class HTTPRequest
155{
156public:
157    explicit HTTPRequest(const std::shared_ptr<HTTPRemoteClient>& client) : m_client{client} {}
158    //! Construct with a null client for unit tests
159    explicit HTTPRequest() : m_client{} {}
160
161    /**
162     * Methods that attempt to parse HTTP request fields line-by-line
163     * from a receive buffer.
164     * @param[in]   reader  A LineReader object constructed over a span of data.
165     * @returns     true    If the request field was parsed.
166     *              false   If there was not enough data in the buffer to complete the field.
167     * @throws      std::runtime_error if data is invalid.
168     */
169    /// @{
170    bool LoadControlData(util::LineReader& reader);
171    bool LoadHeaders(util::LineReader& reader);
172    bool LoadBody(util::LineReader& reader);
173    /// @}
174
175    void WriteReply(HTTPStatusCode status, std::span<const std::byte> reply_body = {});
176    void WriteReply(HTTPStatusCode status, std::string_view reply_body_view)
177    {
178        WriteReply(status, std::as_bytes(std::span{reply_body_view}));
179    }
180
181    const HTTPVersion& GetVersion() const { return m_version; }
182    std::shared_ptr<HTTPRemoteClient> GetClient() const { return m_client.lock(); }
183
184    // These methods reimplement the API from http_libevent::HTTPRequest
185    // for downstream JSONRPC and REST modules.
186    std::string GetURI() const { return m_target; }
187    CService GetPeer() const;
188    HTTPRequestMethod GetRequestMethod() const { return m_method; }
189    std::optional<std::string> GetQueryParameter(std::string_view key) const;
190    std::optional<std::string> GetHeader(std::string_view hdr) const;
191    std::string ReadBody() const { return m_body; }
192    void WriteHeader(std::string&& hdr, std::string&& value);
193    std::optional<uint64_t> GetChunkSize() const { return m_chunk_size; }
194    uint64_t GetChunkProgress() const { return m_chunk_read; }
195
196    enum class State {
197        Init,
198        NeedsHeaders,
199        NeedsBody,
200        Complete,
201        Error
202    };
203    State GetState() const { return m_state; }
204    void SetState(State state) { m_state = state; }
205
206private:
207    HTTPRequestMethod m_method;
208    std::string m_target;
209    HTTPVersion m_version;
210    HTTPHeaders m_headers;
211    std::string m_body;
212
213    //! Pointer to the client that made the request so we know who to respond to.
214    std::weak_ptr<HTTPRemoteClient> m_client;
215
216    //! Response headers may be set in advance before response body is known
217    HTTPHeaders m_response_headers;
218
219    // If a large request is sent with "Transfer-encoding: chunked" we may
220    // read the chunk size in a separate I/O loop iteration than the chunk
221    // of data itself. Store the chunk size value here until the chunk is read.
222    std::optional<uint64_t> m_chunk_size;
223    // We may also read a large chunk over multiple loop iterations.
224    // Track the progress of the chunk here.
225    uint64_t m_chunk_read{0};
226
227    State m_state = State::Init;
228};
229
230class HTTPServer
231{
232public:
233    /**
234     * Each connection is assigned an unique id of this type.
235     */
236    using Id = uint64_t;
237
238    explicit HTTPServer(std::function<void(std::unique_ptr<HTTPRequest>&&)> func)
239        : m_request_dispatcher{std::move(func)} {}
240
241    virtual ~HTTPServer()
242    {
243        Assume(!m_thread_socket_handler.joinable()); // Missing call to JoinSocketsThreads()
244        Assume(m_connected.empty()); // Missing call to DisconnectClients(), or disconnect flags not set
245        Assume(m_listen.empty()); // Missing call to StopListening()
246    }
247
248    /**
249     * Parse the user's -rpcallowip settings and populate m_allow_subnets
250     */

src/wallet/receive.cpp

src/wallet/coinselection.cpp

src/consensus/validation.h

src/primitives/transaction.cpp

src/script/descriptor.cpp

src/bitcoin-cli.cpp

src/rpc/blockchain.cpp

src/rpc/rawtransaction.cpp

src/init.cpp

src/crypto/sha256.cpp

src/consensus/merkle.h

src/consensus/tx_check.h

src/consensus/tx_verify.h

src/policy/feerate.h

src/policy/feerate.cpp

src/primitives/transaction_identifier.h

src/chainparamsbase.h

src/chainparamsbase.cpp

src/util/moneystr.cpp

src/crypto/ripemd160.h

src/crypto/sha1.h

src/crypto/sha512.h

src/crypto/hmac_sha256.h

src/crypto/hmac_sha512.h

src/crypto/hmac_sha256.cpp

src/crypto/hmac_sha512.cpp

src/crypto/hkdf_sha256_32.h

src/crypto/hkdf_sha256_32.cpp

src/support/cleanse.h

src/support/cleanse.cpp

src/crypto/siphash.cpp

src/crypto/muhash.h

src/crypto/chacha20.h

src/crypto/poly1305.h

src/crypto/chacha20poly1305.h

src/crypto/chacha20poly1305.cpp

src/util/chaintype.cpp

src/util/obfuscation.h

src/util/byte_units.h

src/util/overflow.h

src/blockencodings.cpp

src/net_permissions.cpp

src/policy/packages.cpp

src/policy/rbf.cpp

src/policy/truc_policy.cpp

src/policy/ephemeral_policy.cpp

src/policy/settings.cpp

src/policy/policy.cpp

src/node/transaction.cpp

src/node/coin.cpp

src/rpc/client.cpp

src/rpc/external_signer.cpp

src/rpc/request.cpp

src/rpc/server_util.cpp

src/rpc/fees.cpp

src/rpc/output_script.cpp

src/rpc/rawtransaction_util.cpp

src/rpc/rawtransaction_util.h

src/rpc/register.h

src/rpc/request.h

src/rpc/server_util.h

src/rpc/protocol.h

src/rpc/server.h

src/rpc/signmessage.cpp

src/rpc/txoutproof.cpp

src/rpc/util.cpp

src/rpc/util.h

src/wallet/rpc/addresses.cpp

src/wallet/rpc/backup.cpp

src/wallet/rpc/coins.cpp

src/wallet/rpc/encrypt.cpp

src/wallet/rpc/signmessage.cpp

src/wallet/rpc/util.cpp

src/wallet/rpc/util.h

src/wallet/coincontrol.cpp

src/wallet/coincontrol.h

src/wallet/context.cpp

src/wallet/context.h

src/wallet/crypter.cpp

src/wallet/crypter.h

src/wallet/db.cpp

src/wallet/export.cpp

src/wallet/external_signer_scriptpubkeyman.cpp

src/wallet/rpc/spend.cpp

src/wallet/rpc/transactions.cpp

src/wallet/rpc/wallet.cpp

src/wallet/feebumper.cpp

src/wallet/feebumper.h

src/index/base.h

src/index/base.cpp

src/index/txindex.h

src/index/txindex.cpp

src/index/txindex_key.h

src/index/txospenderindex.h

src/index/txospenderindex.cpp

src/index/blockfilterindex.h

src/index/blockfilterindex.cpp

src/index/coinstatsindex.h

src/index/coinstatsindex.cpp

src/index/db_key.h

src/index/disktxpos.h

src/kernel/chain.cpp

src/kernel/chain.h

src/kernel/checks.cpp

src/kernel/checks.h

src/kernel/context.cpp

src/kernel/context.h

src/kernel/cs_main.cpp

src/kernel/cs_main.h

src/kernel/disconnected_transactions.cpp

src/kernel/disconnected_transactions.h

src/kernel/mempool_removal_reason.cpp

src/kernel/mempool_removal_reason.h

src/kernel/coinstats.cpp

src/kernel/coinstats.h

src/kernel/chainparams.cpp

src/kernel/chainparams.h

src/wallet/sqlite.cpp

src/wallet/sqlite.h

src/wallet/transaction.cpp

src/wallet/transaction.h

src/wallet/dump.cpp

src/wallet/dump.h

src/wallet/init.cpp

src/wallet/walletutil.cpp

src/wallet/walletutil.h

src/wallet/wallettool.cpp

src/wallet/wallettool.h

src/wallet/export.h

src/wallet/migrate.cpp

src/wallet/migrate.h

src/wallet/db.h

src/wallet/walletdb.cpp

src/wallet/interfaces.cpp

src/wallet/scriptpubkeyman.cpp

src/wallet/scriptpubkeyman.h

src/kernel/bitcoinkernel.cpp

src/kernel/bitcoinkernel.h

src/kernel/bitcoinkernel_wrapper.h

src/node/chainstate.cpp

src/node/chainstate.h

src/node/blockstorage.cpp

src/node/blockstorage.h

src/node/mempool_persist.cpp

src/node/mempool_persist.h

src/node/utxo_snapshot.cpp

src/node/utxo_snapshot.h

src/node/kernel_notifications.cpp

src/node/kernel_notifications.h

src/node/blockmanager_args.cpp

src/kernel/blockmanager_opts.h

src/util/expected.cpp

src/policy/settings.h

src/util/types.h

src/kernel/messagestartchars.h

src/kernel/warning.h

src/util/exception.h

src/common/license_info.h

src/node/coins_view_args.h

src/node/database_args.h

src/util/batchpriority.h

src/util/ui_change_type.h

src/node/coins_view_args.cpp

src/node/peerman_args.h

src/util/serfloat.h

src/node/blockmanager_args.h

src/node/database_args.cpp

src/util/overloaded.h

src/interfaces/types.h

src/node/chainstatemanager_args.h

src/node/minisketchwrapper.h

src/util/macros.h

src/util/syserror.h

src/common/run_command.h

src/util/bytevectorhash.cpp

src/node/mempool_persist_args.cpp

src/util/exec.h

src/util/rbf.h

src/crypto/hex_base.h

src/node/mempool_persist_args.h

src/interfaces/echo.h

src/util/any.h

src/util/batchpriority.cpp

src/util/threadnames.h

src/node/coin.h

src/node/mempool_args.h

src/util/asmap.h

src/util/bytevectorhash.h

src/node/context.cpp

src/util/insert.h

src/util/readwritefile.h

src/node/peerman_args.cpp

src/node/interface_ui.cpp

src/interfaces/handler.h

src/node/mining_args.h

src/util/hasher.cpp

src/common/init.h

src/kernel/mempool_limits.h

src/common/system.h

src/crypto/sha3.h

src/util/threadinterrupt.cpp

src/node/protocol_version.h

src/util/exception.cpp

src/common/messages.h

src/node/connection_types.cpp

src/util/bip32.h

src/common/license_info.cpp

src/util/stdmutex.h

src/common/run_command.cpp

src/util/check.cpp

src/util/golombrice.h

src/node/types.h

src/node/timeoffsets.h

src/util/readwritefile.cpp

src/util/fastrange.h

src/util/signalinterrupt.h

src/util/task_runner.h

src/util/syserror.cpp

src/common/interfaces.cpp

src/common/types.h

src/util/threadinterrupt.h

src/kernel/chainstatemanager_opts.h

src/node/psbt.h

src/policy/ephemeral_policy.h

src/util/trace.h

src/common/url.cpp

src/kernel/mempool_options.h

src/util/serfloat.cpp

src/kernel/notifications_interface.h

src/node/timeoffsets.cpp

src/node/warnings.cpp

src/util/hash_type.h

src/crypto/hex_base.cpp

src/node/eviction.h

src/util/tokenbucket.h

src/crypto/aes.h

src/common/pcp.h

src/util/feefrac.cpp

src/node/transaction.h

src/util/threadnames.cpp

src/common/signmessage.h

src/util/exec.cpp

src/util/signalinterrupt.cpp

Independent explanations by MyBitcoinExplorer. Not affiliated with or endorsed by Bitcoin Core. Guides are educational and do not replace the source or its tests.

Bitcoin Core source © its contributors, distributed under the MIT license. Original notices and bundled third-party licenses are retained in the source tree.