Initial commit: multi-peer torrent download engine

Reactor/loop-pool engine with TCP/µTP/MSE transports, per-connection
pipelining, priority-driven piece selection with endgame, and the Python
FFI test harness.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

tests/test_tracker_ffi_dht.py

@@ -0,0 +1,93 @@
+"""
+Smoke tests for the torrent-tracker DHT ctypes bindings.
+
+Run with:  python tests/test_tracker_ffi_dht.py
+"""
+from __future__ import annotations
+
+import ctypes as C
+import os
+import sys
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, os.path.join(ROOT, "harness"))
+
+from tracker_ffi import (  # noqa: E402
+    DHTClient,
+    DHTMessage,
+    DHT_MSG_QUERY,
+    DHT_MSG_RESPONSE,
+    DHT_QUERY_GET_PEERS,
+    TRACKER_ADDR_IPV4,
+    TRACKER_ADDR_IPV6,
+    TRACKER_OK,
+    TrackerPeer,
+)
+
+
+def _parse(client: DHTClient, raw: bytes) -> DHTMessage:
+    msg = DHTMessage()
+    raw_buf = C.create_string_buffer(raw, len(raw))
+    rc = client.lib.dht_parse_message(raw_buf, len(raw), C.byref(msg))
+    assert rc == TRACKER_OK
+    return msg
+
+
+def test_get_peers_query_roundtrips_through_tracker_library():
+    client = DHTClient(bootstrap=())
+    client.node_id = b"abcdefghij0123456789"
+    tx = b"aa"
+    info_hash = bytes(range(20))
+
+    msg = _parse(client, client._get_peers_packet(info_hash, tx))
+
+    assert msg.type == DHT_MSG_QUERY
+    assert msg.query == DHT_QUERY_GET_PEERS
+    assert bytes(msg.transaction[:msg.transaction_len]) == tx
+    assert bytes(msg.id) == client.node_id
+    assert bytes(msg.info_hash) == info_hash
+    assert msg.want_ipv4 == 1
+    assert msg.want_ipv6 == 1
+
+
+def test_peers_response_parses_to_endpoint_tuples():
+    client = DHTClient(bootstrap=())
+    tx = b"bb"
+    node_id = b"mnopqrstuvwxyz123456"
+    token = b"tok"
+    peers = (TrackerPeer * 2)()
+
+    peers[0].family = TRACKER_ADDR_IPV4
+    for i, b in enumerate((8, 8, 8, 8)):
+        peers[0].addr[i] = b
+    peers[0].port = 51413
+
+    peers[1].family = TRACKER_ADDR_IPV6
+    peers[1].addr[15] = 2
+    peers[1].port = 51414
+
+    buf = C.create_string_buffer(1024)
+    written = C.c_size_t()
+    tx_buf = C.create_string_buffer(tx, len(tx))
+    id_buf = C.create_string_buffer(node_id, len(node_id))
+    token_buf = C.create_string_buffer(token, len(token))
+    rc = client.lib.dht_write_peers_response(
+        tx_buf, len(tx), id_buf, token_buf, len(token), peers, 2,
+        buf, C.sizeof(buf), C.byref(written))
+    assert rc == TRACKER_OK
+
+    msg = _parse(client, buf.raw[:written.value])
+
+    assert msg.type == DHT_MSG_RESPONSE
+    assert bytes(msg.transaction[:msg.transaction_len]) == tx
+    assert bytes(msg.id) == node_id
+    assert bytes(msg.token[:msg.token_len]) == token
+    assert msg.peer_count == 2
+    assert client._peer_endpoint(msg.peers[0]) == ("8.8.8.8", 51413)
+    assert client._peer_endpoint(msg.peers[1]) == ("::2", 51414)
+
+
+if __name__ == "__main__":
+    test_get_peers_query_roundtrips_through_tracker_library()
+    test_peers_response_parses_to_endpoint_tuples()
+    print("tracker DHT ffi OK")