Merge #19509: Per-Peer Message Capture

bff7c66e67aa2f18ef70139338643656a54444fe Add documentation to contrib folder (Troy Giorshev)
381f77be858d7417209b6de0b7cd23cb7eb99261 Add Message Capture Test (Troy Giorshev)
e4f378a505922c0f544b4cfbfdb169e884e02be9 Add capture parser (Troy Giorshev)
4d1a582549bc982d55e24585b0ba06f92f21e9da Call CaptureMessage at appropriate locations (Troy Giorshev)
f2a77ff97bec09dd5fcc043d8659d8ec5dfb87c2 Add CaptureMessage (Troy Giorshev)
dbf779d5deb04f55c6e8493ce4e12ed4628638f3 Clean PushMessage and ProcessMessages (Troy Giorshev)

Pull request description:

  This PR introduces per-peer message capture into Bitcoin Core.  📓

  ## Purpose

  The purpose and scope of this feature is intentionally limited.  It answers a question anyone new to Bitcoin's P2P protocol has had: "Can I see what messages my node is sending and receiving?".

  ## Functionality

  When a new debug-only command line argument `capturemessages` is set, any message that the node receives or sends is captured.  The capture occurs in the MessageHandler thread.  When receiving a message, it is captured as soon as the MessageHandler thread takes the message off of the vProcessMsg queue.  When sending, the message is captured just before the message is pushed onto the vSendMsg queue.

  The message capture is as minimal as possible to reduce the performance impact on the node.  Messages are captured to a new `message_capture` folder in the datadir.  Each node has their own subfolder named with their IP address and port.  Inside, received and sent messages are captured into two binary files, msgs_recv.dat and msgs_sent.dat, like so:

  ```
  message_capture/203.0.113.7:56072/msgs_recv.dat
  message_capture/203.0.113.7:56072/msgs_sent.dat
  ```

  Because the messages are raw binary dumps, included in this PR is a Python parsing tool to convert the binary files into human-readable JSON.  This script has been placed on its own and out of the way in the new `contrib/message-capture` folder.  Its usage is simple and easily discovered by the autogenerated `-h` option.

  ## Future Maintenance

  I sympathize greatly with anyone who says "the best code is no code".

  The future maintenance of this feature will be minimal.  The logic to deserialize the payload of the p2p messages exists in our testing framework.  As long as our testing framework works, so will this tool.

  Additionally, I hope that the simplicity of this tool will mean that it gets used frequently, so that problems will be discovered and solved when they are small.

  ## FAQ

  "Why not just use Wireshark"

  Yes, Wireshark has the ability to filter and decode Bitcoin messages.  However, the purpose of the message capture added in this PR is to assist with debugging, primarily for new developers looking to improve their knowledge of the Bitcoin Protocol.  This drives the design in a different direction than Wireshark, in two different ways.  First, this tool must be convenient and simple to use.  Using an external tool, like Wireshark, requires setup and interpretation of the results.  To a new user who doesn't necessarily know what to expect, this is unnecessary difficulty.  This tool, on the other hand, "just works".  Turn on the command line flag, run your node, run the script, read the JSON.  Second, because this tool is being used for debugging, we want it to be as close to the true behavior of the node as possible.  A lot can happen in the SocketHandler thread that would be missed by Wireshark.

  Additionally, if we are to use Wireshark, we are at the mercy of whoever it maintaining the protocol in Wireshark, both as to it being accurate and recent.  As can be seen by the **many** previous attempts to include Bitcoin in Wireshark (google "bitcoin dissector") this is easier said than done.

  Lastly, I truly believe that this tool will be used significantly more by being included in the codebase.  It's just that much more discoverable.

ACKs for top commit:
  MarcoFalke:
    re-ACK bff7c66e67aa2f18ef70139338643656a54444fe only some minor changes: 👚
  jnewbery:
    utACK bff7c66e67aa2f18ef70139338643656a54444fe
  theStack:
    re-ACK bff7c66e67aa2f18ef70139338643656a54444fe

Tree-SHA512: e59e3160422269221f70f98720b47842775781c247c064071d546c24fa7a35a0e5534e8baa4b4591a750d7eb16de6b4ecf54cbee6d193b261f4f104e28c15f47

3 files changed, 78 insertions, 1 deletions

diff --git a/test/functional/p2p_message_capture.py b/test/functional/p2p_message_capture.py
new file mode 100755
index 0000000000..113e26c425
--- /dev/null
+++ b/test/functional/p2p_message_capture.py
@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+# Copyright (c) 2020 The Bitcoin Core developers
+# Distributed under the MIT software license, see the accompanying
+# file COPYING or http://www.opensource.org/licenses/mit-license.php.
+"""Test per-peer message capture capability.
+
+Additionally, the output of contrib/message-capture/message-capture-parser.py should be verified manually.
+"""
+
+import glob
+from io import BytesIO
+import os
+
+from test_framework.p2p import P2PDataStore, MESSAGEMAP
+from test_framework.test_framework import BitcoinTestFramework
+from test_framework.util import assert_equal
+
+TIME_SIZE = 8
+LENGTH_SIZE = 4
+MSGTYPE_SIZE = 12
+
+def mini_parser(dat_file):
+    """Parse a data file created by CaptureMessage.
+
+    From the data file we'll only check the structure.
+
+    We won't care about things like:
+    - Deserializing the payload of the message
+        - This is managed by the deserialize methods in test_framework.messages
+    - The order of the messages
+        - There's no reason why we can't, say, change the order of the messages in the handshake
+    - Message Type
+        - We can add new message types
+
+    We're ignoring these because they're simply too brittle to test here.
+    """
+    with open(dat_file, 'rb') as f_in:
+        # This should have at least one message in it
+        assert(os.fstat(f_in.fileno()).st_size >= TIME_SIZE + LENGTH_SIZE + MSGTYPE_SIZE)
+        while True:
+            tmp_header_raw = f_in.read(TIME_SIZE + LENGTH_SIZE + MSGTYPE_SIZE)
+            if not tmp_header_raw:
+                break
+            tmp_header = BytesIO(tmp_header_raw)
+            int.from_bytes(tmp_header.read(TIME_SIZE), "little")      # type: int
+            raw_msgtype = tmp_header.read(MSGTYPE_SIZE)
+            msgtype = raw_msgtype.split(b'\x00', 1)[0]     # type: bytes
+            remainder =  raw_msgtype.split(b'\x00', 1)[1]
+            assert(len(msgtype) > 0)
+            assert(msgtype in MESSAGEMAP)
+            assert(len(remainder) == 0 or not remainder.decode().isprintable())
+            length = int.from_bytes(tmp_header.read(LENGTH_SIZE), "little")  # type: int
+            data = f_in.read(length)
+            assert_equal(len(data), length)
+
+
+
+class MessageCaptureTest(BitcoinTestFramework):
+    def set_test_params(self):
+        self.num_nodes = 1
+        self.extra_args = [["-capturemessages"]]
+        self.setup_clean_chain = True
+
+    def run_test(self):
+        capturedir = os.path.join(self.nodes[0].datadir, "regtest/message_capture")
+        # Connect a node so that the handshake occurs
+        self.nodes[0].add_p2p_connection(P2PDataStore())
+        self.nodes[0].disconnect_p2ps()
+        recv_file = glob.glob(os.path.join(capturedir, "*/msgs_recv.dat"))[0]
+        mini_parser(recv_file)
+        sent_file = glob.glob(os.path.join(capturedir, "*/msgs_sent.dat"))[0]
+        mini_parser(sent_file)
+
+
+if __name__ == '__main__':
+    MessageCaptureTest().main()
diff --git a/test/functional/test_framework/messages.py b/test/functional/test_framework/messages.py
index 6ad4e13db2..27a09ef86c 100755
--- a/test/functional/test_framework/messages.py
+++ b/test/functional/test_framework/messages.py
@@ -1273,7 +1273,7 @@ class msg_block:
 # for cases where a user needs tighter control over what is sent over the wire
 # note that the user must supply the name of the msgtype, and the data
 class msg_generic:
-    __slots__ = ("msgtype", "data")
+    __slots__ = ("data")
 
     def __init__(self, msgtype, data=None):
         self.msgtype = msgtype
diff --git a/test/functional/test_runner.py b/test/functional/test_runner.py
index c652ac0a06..0e6340b69d 100755
--- a/test/functional/test_runner.py
+++ b/test/functional/test_runner.py
@@ -266,6 +266,7 @@ BASE_SCRIPTS = [
     'p2p_add_connections.py',
     'p2p_unrequested_blocks.py',
     'p2p_blockfilters.py',
+    'p2p_message_capture.py',
     'feature_includeconf.py',
     'feature_asmap.py',
     'mempool_unbroadcast.py',