Inside Bitcoin

251    // Only one CNetMessage object will exist for the same message on either
252    // the receive or processing queue. For performance reasons we therefore
253    // delete the copy constructor and assignment operator to avoid the
254    // possibility of copying CNetMessage objects.
255    CNetMessage(CNetMessage&&) = default;
256    CNetMessage(const CNetMessage&) = delete;
257    CNetMessage& operator=(CNetMessage&&) = default;
258    CNetMessage& operator=(const CNetMessage&) = delete;
259
260    /** Compute total memory usage of this object (own memory + any dynamic memory). */
261    size_t GetMemoryUsage() const noexcept;
262};
263
264/** The Transport converts one connection's sent messages to wire bytes, and received bytes back. */
265class Transport {
266public:
267    virtual ~Transport() = default;
268
269    struct Info
270    {
271        TransportProtocolType transport_type;
272        std::optional<uint256> session_id;
273    };
274
275    /** Retrieve information about this transport. */
276    virtual Info GetInfo() const noexcept = 0;
277
278    // 1. Receiver side functions, for decoding bytes received on the wire into transport protocol
279    // agnostic CNetMessage (message type & payload) objects.
280
281    /** Returns true if the current message is complete (so GetReceivedMessage can be called). */
282    virtual bool ReceivedMessageComplete() const = 0;
283
284    /** Feed wire bytes to the transport.
285     *
286     * @return false if some bytes were invalid, in which case the transport can't be used anymore.
287     *
288     * Consumed bytes are chopped off the front of msg_bytes.
289     */
290    virtual bool ReceivedBytes(std::span<const uint8_t>& msg_bytes) = 0;
291
292    /** Retrieve a completed message from transport.
293     *
294     * This can only be called when ReceivedMessageComplete() is true.
295     *
296     * If reject_message=true is returned the message itself is invalid, but (other than false
297     * returned by ReceivedBytes) the transport is not in an inconsistent state.
298     */
299    virtual CNetMessage GetReceivedMessage(NodeClock::time_point time, bool& reject_message) = 0;
300
301    // 2. Sending side functions, for converting messages into bytes to be sent over the wire.
302
303    /** Set the next message to send.
304     *
305     * If no message can currently be set (perhaps because the previous one is not yet done being
306     * sent), returns false, and msg will be unmodified. Otherwise msg is enqueued (and
307     * possibly moved-from) and true is returned.
308     */
309    virtual bool SetMessageToSend(CSerializedNetMsg& msg) noexcept = 0;
310
311    /** Return type for GetBytesToSend, consisting of:
312     *  - std::span<const uint8_t> to_send: span of bytes to be sent over the wire (possibly empty).
313     *  - bool more: whether there will be more bytes to be sent after the ones in to_send are
314     *    all sent (as signaled by MarkBytesSent()).
315     *  - const std::string& m_type: message type on behalf of which this is being sent
316     *    ("" for bytes that are not on behalf of any message).
317     */
318    using BytesToSend = std::tuple<
319        std::span<const uint8_t> /*to_send*/,
320        bool /*more*/,
321        const std::string& /*m_type*/
322    >;
323
324    /** Get bytes to send on the wire, if any, along with other information about it.
325     *
326     * As a const function, it does not modify the transport's observable state, and is thus safe
327     * to be called multiple times.
328     *
329     * @param[in] have_next_message If true, the "more" return value reports whether more will
330     *            be sendable after a SetMessageToSend call. It is set by the caller when they know
331     *            they have another message ready to send, and only care about what happens
332     *            after that. The have_next_message argument only affects this "more" return value
333     *            and nothing else.
334     *
335     *            Effectively, there are three possible outcomes about whether there are more bytes
336     *            to send:
337     *            - Yes:     the transport itself has more bytes to send later. For example, for
338     *                       V1Transport this happens during the sending of the header of a
339     *                       message, when there is a non-empty payload that follows.
340     *            - No:      the transport itself has no more bytes to send, but will have bytes to
341     *                       send if handed a message through SetMessageToSend. In V1Transport this
342     *                       happens when sending the payload of a message.
343     *            - Blocked: the transport itself has no more bytes to send, and is also incapable
344     *                       of sending anything more at all now, if it were handed another
345     *                       message to send. This occurs in V2Transport before the handshake is
346     *                       complete, as the encryption ciphers are not set up for sending
347     *                       messages before that point.
348     *
349     *            The boolean 'more' is true for Yes, false for Blocked, and have_next_message
350     *            controls what is returned for No.
351     *
352     * @return a BytesToSend object. The to_send member returned acts as a stream which is only
353     *         ever appended to. This means that with the exception of MarkBytesSent (which pops
354     *         bytes off the front of later to_sends), operations on the transport can only append
355     *         to what is being returned. Also note that m_type and to_send refer to data that is
356     *         internal to the transport, and calling any non-const function on this object may
357     *         invalidate them.
358     */
359    virtual BytesToSend GetBytesToSend(bool have_next_message) const noexcept = 0;
360
361    /** Report how many bytes returned by the last GetBytesToSend() have been sent.
362     *
363     * bytes_sent cannot exceed to_send.size() of the last GetBytesToSend() result.
364     *
365     * If bytes_sent=0, this call has no effect.
366     */
367    virtual void MarkBytesSent(size_t bytes_sent) noexcept = 0;
368
369    /** Return the memory usage of this transport attributable to buffered data to send. */
370    virtual size_t GetSendMemoryUsage() const noexcept = 0;
371
372    // 3. Miscellaneous functions.
373
374    /** Whether upon disconnections, a reconnect with V1 is warranted. */
375    virtual bool ShouldReconnectV1() const noexcept = 0;
376};
377
378class V1Transport final : public Transport
379{
380private:
381    const MessageStartChars m_magic_bytes;
382    const NodeId m_node_id; // Only for logging
383    mutable Mutex m_recv_mutex; //!< Lock for receive state
384    mutable CHash256 hasher GUARDED_BY(m_recv_mutex);
385    mutable uint256 data_hash GUARDED_BY(m_recv_mutex);
386    bool in_data GUARDED_BY(m_recv_mutex); // parsing header (false) or data (true)
387    DataStream hdrbuf GUARDED_BY(m_recv_mutex){}; // partially received header
388    CMessageHeader hdr GUARDED_BY(m_recv_mutex); // complete header
389    DataStream vRecv GUARDED_BY(m_recv_mutex){}; // received message data
390    unsigned int nHdrPos GUARDED_BY(m_recv_mutex);
391    unsigned int nDataPos GUARDED_BY(m_recv_mutex);
392
393    const uint256& GetMessageHash() const EXCLUSIVE_LOCKS_REQUIRED(m_recv_mutex);
394    int readHeader(std::span<const uint8_t> msg_bytes) EXCLUSIVE_LOCKS_REQUIRED(m_recv_mutex);
395    int readData(std::span<const uint8_t> msg_bytes) EXCLUSIVE_LOCKS_REQUIRED(m_recv_mutex);
396
397    void Reset() EXCLUSIVE_LOCKS_REQUIRED(m_recv_mutex) {
398        AssertLockHeld(m_recv_mutex);
399        vRecv.clear();
400        hdrbuf.clear();
401        hdrbuf.resize(24);
402        in_data = false;
403        nHdrPos = 0;
404        nDataPos = 0;
405        data_hash.SetNull();
406        hasher.Reset();
407    }
408
409    bool CompleteInternal() const noexcept EXCLUSIVE_LOCKS_REQUIRED(m_recv_mutex)
410    {
411        AssertLockHeld(m_recv_mutex);
412        if (!in_data) return false;
413        return hdr.nMessageSize == nDataPos;
414    }
415
416    /** Lock for sending state. */
417    mutable Mutex m_send_mutex;
418    /** The header of the message currently being sent. */
419    std::vector<uint8_t> m_header_to_send GUARDED_BY(m_send_mutex);
420    /** The data of the message currently being sent. */
421    CSerializedNetMsg m_message_to_send GUARDED_BY(m_send_mutex);
422    /** Whether we're currently sending header bytes or message bytes. */
423    bool m_sending_header GUARDED_BY(m_send_mutex) {false};
424    /** How many bytes have been sent so far (from m_header_to_send, or from m_message_to_send.data). */
425    size_t m_bytes_sent GUARDED_BY(m_send_mutex) {0};
426
427public:
428    explicit V1Transport(NodeId node_id) noexcept;
429
430    bool ReceivedMessageComplete() const override EXCLUSIVE_LOCKS_REQUIRED(!m_recv_mutex)
431    {
432        AssertLockNotHeld(m_recv_mutex);
433        return WITH_LOCK(m_recv_mutex, return CompleteInternal());
434    }
435
436    Info GetInfo() const noexcept override;
437
438    bool ReceivedBytes(std::span<const uint8_t>& msg_bytes) override EXCLUSIVE_LOCKS_REQUIRED(!m_recv_mutex)
439    {
440        AssertLockNotHeld(m_recv_mutex);
441        LOCK(m_recv_mutex);
442        int ret = in_data ? readData(msg_bytes) : readHeader(msg_bytes);
443        if (ret < 0) {
444            Reset();
445        } else {
446            msg_bytes = msg_bytes.subspan(ret);
447        }
448        return ret >= 0;
449    }
450
451    CNetMessage GetReceivedMessage(NodeClock::time_point time, bool& reject_message) override EXCLUSIVE_LOCKS_REQUIRED(!m_recv_mutex);
452
453    bool SetMessageToSend(CSerializedNetMsg& msg) noexcept override EXCLUSIVE_LOCKS_REQUIRED(!m_send_mutex);
454    BytesToSend GetBytesToSend(bool have_next_message) const noexcept override EXCLUSIVE_LOCKS_REQUIRED(!m_send_mutex);
455    void MarkBytesSent(size_t bytes_sent) noexcept override EXCLUSIVE_LOCKS_REQUIRED(!m_send_mutex);
456    size_t GetSendMemoryUsage() const noexcept override EXCLUSIVE_LOCKS_REQUIRED(!m_send_mutex);
457    bool ShouldReconnectV1() const noexcept override { return false; }
458};
459
460class V2Transport final : public Transport
461{
462private:
463    /** Contents of the version packet to send. BIP324 stipulates that senders should leave this
464     *  empty, and receivers should ignore it. Future extensions can change what is sent as long as
465     *  an empty version packet contents is interpreted as no extensions supported. */
466    static constexpr std::array<std::byte, 0> VERSION_CONTENTS = {};
467
468    /** The length of the V1 prefix to match bytes initially received by responders with to
469     *  determine if their peer is speaking V1 or V2. */
470    static constexpr size_t V1_PREFIX_LEN = 16;
471
472    // The sender side and receiver side of V2Transport are state machines that are transitioned
473    // through, based on what has been received. The receive state corresponds to the contents of,
474    // and bytes received to, the receive buffer. The send state controls what can be appended to
475    // the send buffer and what can be sent from it.
476
477    /** State type that defines the current contents of the receive buffer and/or how the next
478     *  received bytes added to it will be interpreted.
479     *
480     * Diagram:
481     *
482     *   start(responder)
483     *        |
484     *        |  start(initiator)                           /---------\
485     *        |          |                                  |         |
486     *        v          v                                  v         |
487     *  KEY_MAYBE_V1 -> KEY -> GARB_GARBTERM -> VERSION -> APP -> APP_READY
488     *        |
489     *        \-------> V1
490     */
491    enum class RecvState : uint8_t {
492        /** (Responder only) either v2 public key or v1 header.
493         *
494         * This is the initial state for responders, before data has been received to distinguish
495         * v1 from v2 connections. When that happens, the state becomes either KEY (for v2) or V1
496         * (for v1). */
497        KEY_MAYBE_V1,
498
499        /** Public key.
500         *