librats 1.0.2 → 2.2.0

package/native-src/src/librats/bittorrent/disk_io.cpp

@@ -0,0 +1,209 @@
+#include "librats/bittorrent/disk_io.h"
+
+#include "librats/bittorrent/log.h"
+#include "librats/crypto/sha1.h"
+#include "librats/util/fs.h"
+
+#include <algorithm>
+#include <cstring>
+#include <utility>
+
+namespace librats::bittorrent {
+
+ThreadedDiskIo::ThreadedDiskIo(const TorrentInfo& info, std::string save_path,
+                               CompletionPoster poster, Config config)
+    : files_(info.files())
+    , piece_hashes_(info.piece_hashes())
+    , save_path_(std::move(save_path))
+    , poster_(std::move(poster))
+    , ensured_(info.num_files(), 0) {
+    const int n = (std::max)(1, config.num_threads);
+    workers_.reserve(std::size_t(n));
+    for (int i = 0; i < n; ++i) workers_.emplace_back([this] { worker_loop(); });
+}
+
+ThreadedDiskIo::~ThreadedDiskIo() {
+    stop();
+}
+
+void ThreadedDiskIo::stop() {
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (stopping_) return;
+        stopping_ = true;
+    }
+    cv_.notify_all();
+    for (auto& t : workers_)
+        if (t.joinable()) t.join();
+    workers_.clear();
+}
+
+void ThreadedDiskIo::enqueue(std::function<void()> job) {
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (stopping_) return;
+        jobs_.push(std::move(job));
+    }
+    cv_.notify_one();
+}
+
+void ThreadedDiskIo::worker_loop() {
+    for (;;) {
+        std::function<void()> job;
+        {
+            std::unique_lock<std::mutex> lock(mutex_);
+            cv_.wait(lock, [this] { return stopping_ || !jobs_.empty(); });
+            if (stopping_ && jobs_.empty()) return;
+            job = std::move(jobs_.front());
+            jobs_.pop();
+        }
+        job();
+    }
+}
+
+void ThreadedDiskIo::complete(std::function<void()> handler) {
+    if (poster_) poster_(std::move(handler));
+    else handler();
+}
+
+std::string ThreadedDiskIo::file_path(std::size_t file_index) const {
+    return combine_paths(save_path_, files_.file_at(file_index).path);
+}
+
+bool ThreadedDiskIo::ensure_file(std::size_t file_index) {
+    std::lock_guard<std::mutex> lock(ensure_mutex_);
+    if (ensured_[file_index]) return true;
+
+    const std::string   path = file_path(file_index);
+    const std::int64_t  size = files_.file_at(file_index).size;
+
+    const std::string parent = get_parent_directory(path.c_str());
+    if (!parent.empty() && !directory_exists(parent.c_str())) {
+        if (!create_directories(parent.c_str())) {
+            LOG_ERROR("bt.disk", "✗ failed to create directory " << parent);
+            return false;
+        }
+    }
+
+    if (file_exists(path.c_str())) {
+        // Extend a short (e.g. partially-downloaded) file without truncating it.
+        if (size > 0 && get_file_size(path.c_str()) < size) {
+            const std::uint8_t zero = 0;
+            if (!write_file_chunk(path, std::uint64_t(size - 1), &zero, 1)) {
+                LOG_ERROR("bt.disk", "✗ failed to extend file " << path << " to " << size << " bytes");
+                return false;
+            }
+        }
+    } else if (!create_file_with_size(path, std::uint64_t(size))) {
+        LOG_ERROR("bt.disk", "✗ failed to create file " << path << " (" << size << " bytes)");
+        return false;
+    }
+
+    ensured_[file_index] = 1;
+    return true;
+}
+
+bool ThreadedDiskIo::write_range(std::uint32_t piece, std::uint32_t offset, const Bytes& data) {
+    auto slices = files_.map_block(piece, offset, std::int64_t(data.size()));
+    std::int64_t in_pos = 0;
+    for (const auto& s : slices) {
+        if (!ensure_file(s.file_index)) return false;
+        if (!write_file_chunk(file_path(s.file_index), std::uint64_t(s.offset),
+                              data.data() + in_pos, std::size_t(s.size))) {
+            return false;
+        }
+        in_pos += s.size;
+    }
+    return in_pos == std::int64_t(data.size());
+}
+
+bool ThreadedDiskIo::read_range(std::uint32_t piece, std::uint32_t offset, std::uint32_t length,
+                                Bytes& out, bool use_store, bool allow_short) {
+    out.assign(length, 0);
+    auto slices = files_.map_block(piece, offset, std::int64_t(length));
+    std::int64_t out_pos = 0;
+    for (const auto& s : slices) {
+        const std::string path = file_path(s.file_index);
+        // On the check path a missing/short file is expected (piece not yet on
+        // disk); probe the size first so we don't trip read_file_chunk's error log.
+        if (allow_short && get_file_size(path.c_str()) < s.offset + s.size) return false;
+        if (!read_file_chunk(path, std::uint64_t(s.offset), out.data() + out_pos, std::size_t(s.size)))
+            return false;
+        out_pos += s.size;
+    }
+    if (use_store) store_.overlay(piece, offset, out);
+    return true;
+}
+
+void ThreadedDiskIo::async_read(std::uint32_t piece, std::uint32_t offset, std::uint32_t length,
+                                DiskReadHandler handler) {
+    enqueue([this, piece, offset, length, handler = std::move(handler)]() mutable {
+        Bytes out;
+        const bool ok = read_range(piece, offset, length, out, /*use_store=*/true, /*allow_short=*/false);
+        complete([handler = std::move(handler), ok, out = std::move(out)]() mutable {
+            if (handler) handler(ok, std::move(out));
+        });
+    });
+}
+
+void ThreadedDiskIo::async_write(std::uint32_t piece, std::uint32_t offset, Bytes data,
+                                 DiskWriteHandler handler) {
+    // Park the block so reads/hashes see it before the write reaches disk, and
+    // count it toward the pending-write total that drives backpressure (D-2).
+    const std::size_t sz = data.size();
+    store_.insert(piece, offset, data);
+    queued_bytes_.fetch_add(sz, std::memory_order_relaxed);
+    enqueue([this, piece, offset, sz, data = std::move(data), handler = std::move(handler)]() mutable {
+        const bool ok = write_range(piece, offset, data);
+        store_.erase(piece, offset);
+        queued_bytes_.fetch_sub(sz, std::memory_order_relaxed);
+        complete([handler = std::move(handler), ok]() mutable {
+            if (handler) handler(ok);
+        });
+    });
+}
+
+void ThreadedDiskIo::async_hash(std::uint32_t piece, DiskHashHandler handler) {
+    enqueue([this, piece, handler = std::move(handler)]() mutable {
+        const std::uint32_t ps = files_.piece_size(piece);
+        Bytes buf;
+        const bool ok = read_range(piece, 0, ps, buf, /*use_store=*/true, /*allow_short=*/false);
+        std::array<std::uint8_t, 20> digest{};
+        if (ok) digest = SHA1::hash_raw(buf.data(), buf.size());
+        complete([handler = std::move(handler), ok, digest]() mutable {
+            if (handler) handler(ok, digest);
+        });
+    });
+}
+
+void ThreadedDiskIo::async_check_files(Bitfield trusted_have, DiskCheckProgress progress,
+                                       DiskCheckHandler handler) {
+    enqueue([this, trusted_have = std::move(trusted_have), progress = std::move(progress),
+             handler = std::move(handler)]() mutable {
+        const std::uint32_t n = files_.num_pieces();
+        const bool have_trust = trusted_have.size() == n;
+        Bitfield have(n, false);
+
+        for (std::uint32_t p = 0; p < n; ++p) {
+            if (have_trust && trusted_have.get(p)) {
+                have.set(p);  // fast resume: trust the saved bit, skip hashing
+            } else {
+                Bytes buf;
+                if (read_range(p, 0, files_.piece_size(p), buf, /*use_store=*/false, /*allow_short=*/true)) {
+                    auto digest = SHA1::hash_raw(buf.data(), buf.size());
+                    if (std::memcmp(digest.data(), piece_hashes_.data() + std::size_t(p) * 20, 20) == 0)
+                        have.set(p);
+                }
+            }
+            if (progress) {
+                const std::uint32_t done = p + 1;
+                complete([progress, done, n] { progress(done, n); });
+            }
+        }
+        complete([handler = std::move(handler), have = std::move(have)]() mutable {
+            if (handler) handler(std::move(have));
+        });
+    });
+}
+
+} // namespace librats::bittorrent

package/native-src/src/librats/bittorrent/disk_io.h

@@ -0,0 +1,150 @@
+#pragma once
+
+/**
+ * @file disk_io.h
+ * @brief Asynchronous piece storage — the boundary between the network thread
+ *        and the filesystem.
+ *
+ * The engine never blocks on disk: it submits async_read / async_write /
+ * async_hash / async_check_files jobs and is called back with the result. DiskIo
+ * is an interface so a torrent can be tested against an in-memory fake, and so
+ * the threading strategy is swappable.
+ *
+ * Completions are delivered through a CompletionPoster — a closure the owner
+ * supplies to marshal handlers onto its own thread (the reactor, in the full
+ * engine). With no poster, handlers run inline on the disk-worker thread.
+ *
+ * Offsets passed to read/write/hash are relative to the *piece* (piece index +
+ * byte offset within it); ThreadedDiskIo translates them to file regions via
+ * FileStorage::map_block.
+ */
+
+#include "librats/bittorrent/bitfield.h"
+#include "librats/bittorrent/file_storage.h"
+#include "librats/bittorrent/store_buffer.h"
+#include "librats/bittorrent/torrent_info.h"
+#include "librats/core/bytes.h"
+
+#include <array>
+#include <atomic>
+#include <condition_variable>
+#include <cstdint>
+#include <functional>
+#include <mutex>
+#include <queue>
+#include <string>
+#include <thread>
+#include <vector>
+
+namespace librats::bittorrent {
+
+/// Marshals a completion closure onto the owner's thread. If empty, handlers run
+/// inline on the disk-worker thread.
+using CompletionPoster = std::function<void(std::function<void()>)>;
+
+using DiskReadHandler     = std::function<void(bool ok, Bytes data)>;
+using DiskWriteHandler    = std::function<void(bool ok)>;
+using DiskHashHandler     = std::function<void(bool ok, std::array<std::uint8_t, 20> sha1)>;
+using DiskCheckProgress   = std::function<void(std::uint32_t piece, std::uint32_t total)>;
+using DiskCheckHandler    = std::function<void(Bitfield have)>;
+
+class DiskIo {
+public:
+    virtual ~DiskIo() = default;
+
+    /// Read @p length bytes at @p offset within @p piece.
+    virtual void async_read(std::uint32_t piece, std::uint32_t offset, std::uint32_t length,
+                            DiskReadHandler handler) = 0;
+
+    /// Write a block at @p offset within @p piece.
+    virtual void async_write(std::uint32_t piece, std::uint32_t offset, Bytes data,
+                             DiskWriteHandler handler) = 0;
+
+    /// SHA-1 the whole of @p piece (for hash verification by the caller).
+    virtual void async_hash(std::uint32_t piece, DiskHashHandler handler) = 0;
+
+    /// Verify which pieces are already complete on disk. Pieces whose bit is set
+    /// in @p trusted_have are accepted without re-hashing (fast resume); the rest
+    /// are read and hashed. @p progress fires per piece (may be null).
+    virtual void async_check_files(Bitfield trusted_have, DiskCheckProgress progress,
+                                   DiskCheckHandler handler) = 0;
+
+    /// Bytes of block data accepted for writing but not yet flushed to disk. The
+    /// Torrent uses this to apply backpressure — it stops requesting new blocks
+    /// while this is high — so a fast network can't grow the write queue without
+    /// bound when the disk is slow. Default 0 for fakes with no real queue.
+    virtual std::size_t queued_write_bytes() const noexcept { return 0; }
+
+    /// Stop workers and quiesce. Safe to call more than once.
+    virtual void stop() = 0;
+};
+
+/// Disk subsystem backed by a small pool of worker threads.
+class ThreadedDiskIo final : public DiskIo {
+public:
+    struct Config {
+        int num_threads = 2;
+    };
+
+    ThreadedDiskIo(const TorrentInfo& info, std::string save_path,
+                   CompletionPoster poster, Config config);
+
+    // Convenience overloads (defined inline so Config{} sits in a complete-class
+    // context — it cannot appear in a default argument of the primary ctor).
+    explicit ThreadedDiskIo(const TorrentInfo& info, std::string save_path)
+        : ThreadedDiskIo(info, std::move(save_path), CompletionPoster{}, Config{}) {}
+    ThreadedDiskIo(const TorrentInfo& info, std::string save_path, CompletionPoster poster)
+        : ThreadedDiskIo(info, std::move(save_path), std::move(poster), Config{}) {}
+
+    ~ThreadedDiskIo() override;
+
+    ThreadedDiskIo(const ThreadedDiskIo&) = delete;
+    ThreadedDiskIo& operator=(const ThreadedDiskIo&) = delete;
+
+    void async_read(std::uint32_t piece, std::uint32_t offset, std::uint32_t length,
+                    DiskReadHandler handler) override;
+    void async_write(std::uint32_t piece, std::uint32_t offset, Bytes data,
+                     DiskWriteHandler handler) override;
+    void async_hash(std::uint32_t piece, DiskHashHandler handler) override;
+    void async_check_files(Bitfield trusted_have, DiskCheckProgress progress,
+                           DiskCheckHandler handler) override;
+    std::size_t queued_write_bytes() const noexcept override { return queued_bytes_.load(std::memory_order_relaxed); }
+    void stop() override;
+
+private:
+    void enqueue(std::function<void()> job);
+    void worker_loop();
+    void complete(std::function<void()> handler);
+
+    bool ensure_file(std::size_t file_index);
+    bool write_range(std::uint32_t piece, std::uint32_t offset, const Bytes& data);
+    /// Read [offset, offset+length) of @p piece into @p out. With @p use_store the
+    /// store-buffer is overlaid. With @p allow_short a missing/short file yields
+    /// false (used by check_files) instead of being treated as an error.
+    bool read_range(std::uint32_t piece, std::uint32_t offset, std::uint32_t length,
+                    Bytes& out, bool use_store, bool allow_short);
+
+    std::string file_path(std::size_t file_index) const;
+
+    FileStorage      files_;
+    Bytes            piece_hashes_;   ///< concatenated 20-byte SHA-1s
+    std::string      save_path_;
+    CompletionPoster poster_;
+    StoreBuffer      store_;
+
+    // File preallocation bookkeeping.
+    std::mutex        ensure_mutex_;
+    std::vector<char> ensured_;       ///< per-file "already sized on disk" flag
+
+    // Bytes of block data queued for writing but not yet flushed (backpressure).
+    std::atomic<std::size_t> queued_bytes_{0};
+
+    // Worker pool + job queue.
+    std::vector<std::thread>          workers_;
+    std::queue<std::function<void()>> jobs_;
+    std::mutex                        mutex_;
+    std::condition_variable           cv_;
+    bool                              stopping_ = false;
+};
+
+} // namespace librats::bittorrent

package/native-src/src/librats/bittorrent/extensions.cpp

@@ -0,0 +1,191 @@
+#include "librats/bittorrent/extensions.h"
+#include "librats/bittorrent/bencode.h"
+#include "librats/bittorrent/byte_io.h"
+
+#include <cstdio>
+
+namespace librats::bittorrent::ext {
+
+namespace {
+
+/// Parse "a.b.c.d" into 4 bytes. Returns false on anything that isn't dotted IPv4.
+bool ipv4_to_bytes(const std::string& ip, std::uint8_t out[4]) {
+    unsigned a, b, c, d;
+    char extra;
+    if (std::sscanf(ip.c_str(), "%u.%u.%u.%u%c", &a, &b, &c, &d, &extra) != 4) return false;
+    if (a > 255 || b > 255 || c > 255 || d > 255) return false;
+    out[0] = std::uint8_t(a); out[1] = std::uint8_t(b);
+    out[2] = std::uint8_t(c); out[3] = std::uint8_t(d);
+    return true;
+}
+
+std::string ipv4_to_string(const std::uint8_t* b) {
+    char buf[16];
+    std::snprintf(buf, sizeof(buf), "%u.%u.%u.%u", b[0], b[1], b[2], b[3]);
+    return buf;
+}
+
+/// Pack peers into the 6-bytes-each compact form (4 IPv4 + 2 port BE).
+std::string compact(const std::vector<PexPeer>& peers) {
+    std::string out;
+    for (const auto& p : peers) {
+        std::uint8_t ip[4];
+        if (!ipv4_to_bytes(p.ip, ip)) continue;
+        out.append(reinterpret_cast<const char*>(ip), 4);
+        std::uint8_t port[2];
+        write_u16_be(port, p.port);
+        out.append(reinterpret_cast<const char*>(port), 2);
+    }
+    return out;
+}
+
+std::vector<PexPeer> uncompact(const std::string& s) {
+    std::vector<PexPeer> peers;
+    for (std::size_t i = 0; i + 6 <= s.size(); i += 6) {
+        const auto* b = reinterpret_cast<const std::uint8_t*>(s.data() + i);
+        peers.push_back(PexPeer{ipv4_to_string(b), read_u16_be(b + 4)});
+    }
+    return peers;
+}
+
+// Length of the first bencoded value at the start of `d` (0 on malformed input).
+// A small local scanner so we can split a ut_metadata header dict from the raw
+// metadata block that follows it.
+std::size_t bencode_value_length(const std::uint8_t* d, std::size_t n, std::size_t pos = 0) {
+    if (pos >= n) return 0;
+    const char c = char(d[pos]);
+    if (c == 'i') {
+        std::size_t e = pos + 1;
+        while (e < n && d[e] != 'e') ++e;
+        return e < n ? e + 1 - pos : 0;
+    }
+    if (c == 'l' || c == 'd') {
+        std::size_t p = pos + 1;
+        while (p < n && d[p] != 'e') {
+            const std::size_t len = bencode_value_length(d, n, p);
+            if (len == 0) return 0;
+            p += len;
+        }
+        return p < n ? p + 1 - pos : 0;
+    }
+    if (c >= '0' && c <= '9') {
+        std::size_t colon = pos;
+        while (colon < n && d[colon] != ':') ++colon;
+        if (colon >= n) return 0;
+        std::uint64_t len = 0;
+        for (std::size_t i = pos; i < colon; ++i) len = len * 10 + std::uint64_t(d[i] - '0');
+        const std::size_t total = (colon + 1 - pos) + len;
+        return (pos + total <= n) ? total : 0;
+    }
+    return 0;
+}
+
+const librats::BencodeValue* find(const librats::BencodeValue& dict, const char* key) {
+    return dict.find(key);
+}
+
+std::optional<std::int64_t> find_int(const librats::BencodeValue& dict, const char* key) {
+    const auto* v = find(dict, key);
+    if (v && v->is_integer()) return v->as_integer();
+    return std::nullopt;
+}
+
+} // namespace
+
+Bytes encode_handshake(std::uint32_t metadata_size, std::uint16_t listen_port) {
+    librats::BencodeValue d = librats::BencodeValue::create_dict();
+    librats::BencodeValue m = librats::BencodeValue::create_dict();
+    m["ut_metadata"] = librats::BencodeValue(std::int64_t(kUtMetadataLocalId));
+    m["ut_pex"]      = librats::BencodeValue(std::int64_t(kUtPexLocalId));
+    d["m"]           = m;
+    if (metadata_size > 0) d["metadata_size"] = librats::BencodeValue(std::int64_t(metadata_size));
+    if (listen_port > 0)   d["p"]             = librats::BencodeValue(std::int64_t(listen_port));
+    d["v"] = librats::BencodeValue(std::string("librats"));
+    return d.encode();
+}
+
+std::optional<PeerExtensions> decode_handshake(ByteView payload) {
+    try {
+        librats::BencodeValue d = librats::BencodeDecoder::decode(payload.data(), payload.size());
+        if (!d.is_dict()) return std::nullopt;
+        PeerExtensions ext;
+        if (const auto* m = find(d, "m"); m && m->is_dict()) {
+            if (auto v = find_int(*m, "ut_metadata")) ext.ut_metadata_id = std::uint8_t(*v);
+            if (auto v = find_int(*m, "ut_pex"))      ext.ut_pex_id      = std::uint8_t(*v);
+        }
+        if (auto v = find_int(d, "metadata_size"); v && *v > 0) ext.metadata_size = std::uint32_t(*v);
+        if (auto v = find_int(d, "p"); v && *v > 0)             ext.listen_port   = std::uint16_t(*v);
+        return ext;
+    } catch (const std::exception&) {
+        return std::nullopt;
+    }
+}
+
+Bytes encode_metadata_request(std::uint32_t piece) {
+    librats::BencodeValue d = librats::BencodeValue::create_dict();
+    d["msg_type"] = librats::BencodeValue(std::int64_t(MetadataType::Request));
+    d["piece"]    = librats::BencodeValue(std::int64_t(piece));
+    return d.encode();
+}
+
+Bytes encode_metadata_reject(std::uint32_t piece) {
+    librats::BencodeValue d = librats::BencodeValue::create_dict();
+    d["msg_type"] = librats::BencodeValue(std::int64_t(MetadataType::Reject));
+    d["piece"]    = librats::BencodeValue(std::int64_t(piece));
+    return d.encode();
+}
+
+Bytes encode_metadata_data(std::uint32_t piece, std::uint32_t total_size, ByteView block) {
+    librats::BencodeValue d = librats::BencodeValue::create_dict();
+    d["msg_type"]   = librats::BencodeValue(std::int64_t(MetadataType::Data));
+    d["piece"]      = librats::BencodeValue(std::int64_t(piece));
+    d["total_size"] = librats::BencodeValue(std::int64_t(total_size));
+    Bytes out = d.encode();
+    out.insert(out.end(), block.begin(), block.end());
+    return out;
+}
+
+std::optional<MetadataMessage> decode_metadata(ByteView payload) {
+    const std::size_t header_len = bencode_value_length(payload.data(), payload.size());
+    if (header_len == 0) return std::nullopt;
+    try {
+        librats::BencodeValue d = librats::BencodeDecoder::decode(payload.data(), header_len);
+        if (!d.is_dict()) return std::nullopt;
+        const auto type  = find_int(d, "msg_type");
+        const auto piece = find_int(d, "piece");
+        if (!type || !piece) return std::nullopt;
+
+        MetadataMessage msg;
+        msg.type  = MetadataType(*type);
+        msg.piece = std::uint32_t(*piece);
+        if (msg.type == MetadataType::Data) {
+            if (auto ts = find_int(d, "total_size")) msg.total_size = std::uint32_t(*ts);
+            msg.block.assign(payload.begin() + std::ptrdiff_t(header_len), payload.end());
+        }
+        return msg;
+    } catch (const std::exception&) {
+        return std::nullopt;
+    }
+}
+
+Bytes encode_pex(const std::vector<PexPeer>& added, const std::vector<PexPeer>& dropped) {
+    librats::BencodeValue d = librats::BencodeValue::create_dict();
+    d["added"]   = librats::BencodeValue(compact(added));
+    d["dropped"] = librats::BencodeValue(compact(dropped));
+    return d.encode();
+}
+
+std::optional<PexMessage> decode_pex(ByteView payload) {
+    try {
+        librats::BencodeValue d = librats::BencodeDecoder::decode(payload.data(), payload.size());
+        if (!d.is_dict()) return std::nullopt;
+        PexMessage msg;
+        if (const auto* a = find(d, "added");   a && a->is_string()) msg.added   = uncompact(a->as_string());
+        if (const auto* dr = find(d, "dropped"); dr && dr->is_string()) msg.dropped = uncompact(dr->as_string());
+        return msg;
+    } catch (const std::exception&) {
+        return std::nullopt;
+    }
+}
+
+} // namespace librats::bittorrent::ext

package/native-src/src/librats/bittorrent/extensions.h

@@ -0,0 +1,94 @@
+#pragma once
+
+/**
+ * @file extensions.h
+ * @brief BEP 10 extension protocol + BEP 9 metadata-exchange message codecs.
+ *
+ * BEP 10 layers named extensions on top of the wire's `extended` message
+ * (id 20). After the BitTorrent handshake each side sends an *extended
+ * handshake* (extended id 0) carrying a bencoded `m` dict that maps extension
+ * names to the message ids it wants them sent under — so the id you use to send
+ * a peer a `ut_metadata` message is the id *that peer* advertised, while the id
+ * you receive it under is the one *you* advertised (our fixed kUtMetadataLocalId).
+ *
+ * BEP 9 (`ut_metadata`) fetches the info-dictionary from peers for magnet links:
+ * the metadata is split into 16 KiB pieces requested/served via three message
+ * types (request / data / reject).
+ *
+ * These functions are pure (de)serialisation — the stateful request/serve/verify
+ * logic lives in the Torrent. That keeps the wire format unit-testable in
+ * isolation.
+ */
+
+#include "librats/bittorrent/types.h"
+#include "librats/core/bytes.h"
+
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace librats::bittorrent::ext {
+
+// Our local extended-message ids (what we tell peers to address us by).
+constexpr std::uint8_t kUtMetadataLocalId = 1;
+constexpr std::uint8_t kUtPexLocalId      = 2;
+
+constexpr char kUtMetadataName[] = "ut_metadata";
+constexpr char kUtPexName[]      = "ut_pex";
+
+// ---- extended handshake (extended id 0) ----
+
+/// Build our extended handshake. @p metadata_size is advertised only when > 0
+/// (i.e. we actually hold the metadata); likewise @p listen_port when non-zero.
+Bytes encode_handshake(std::uint32_t metadata_size, std::uint16_t listen_port);
+
+struct PeerExtensions {
+    std::uint8_t  ut_metadata_id = 0;  ///< id to send ut_metadata under (0 = unsupported)
+    std::uint8_t  ut_pex_id      = 0;
+    std::uint32_t metadata_size  = 0;  ///< peer's info-dict size, if advertised
+    std::uint16_t listen_port    = 0;
+};
+
+/// Parse a peer's extended handshake. nullopt if it isn't a valid bencoded dict.
+std::optional<PeerExtensions> decode_handshake(ByteView payload);
+
+// ---- ut_metadata (BEP 9) ----
+
+enum class MetadataType : std::uint8_t { Request = 0, Data = 1, Reject = 2 };
+
+Bytes encode_metadata_request(std::uint32_t piece);
+Bytes encode_metadata_reject(std::uint32_t piece);
+/// A `data` message: the bencoded header followed by the raw metadata @p block.
+Bytes encode_metadata_data(std::uint32_t piece, std::uint32_t total_size, ByteView block);
+
+struct MetadataMessage {
+    MetadataType  type        = MetadataType::Request;
+    std::uint32_t piece       = 0;
+    std::uint32_t total_size  = 0;  ///< only set on Data
+    Bytes         block;            ///< only set on Data (the raw 16 KiB slice)
+};
+
+/// Parse a ut_metadata message (header dict + optional trailing block). nullopt
+/// if malformed.
+std::optional<MetadataMessage> decode_metadata(ByteView payload);
+
+// ---- ut_pex (BEP 11) ----
+
+struct PexPeer {
+    std::string   ip;
+    std::uint16_t port = 0;
+};
+
+/// Encode an IPv4 peer-exchange message (`added`/`dropped` compact lists).
+Bytes encode_pex(const std::vector<PexPeer>& added, const std::vector<PexPeer>& dropped);
+
+struct PexMessage {
+    std::vector<PexPeer> added;
+    std::vector<PexPeer> dropped;
+};
+
+/// Parse a ut_pex message. nullopt if malformed. (IPv4 `added`/`dropped` only.)
+std::optional<PexMessage> decode_pex(ByteView payload);
+
+} // namespace librats::bittorrent::ext