librats 1.0.2 → 2.2.0

package/native-src/src/librats/node/dialer.cpp

@@ -0,0 +1,264 @@
+#include "librats/node/dialer.h"
+#include "librats/util/logger.h"
+
+#include <algorithm>
+#include <utility>
+
+namespace librats {
+
+namespace {
+
+/// The PeerTransports bit standing for one transport.
+uint8_t mask_for(TransportKind kind) noexcept {
+    return kind == TransportKind::Udp ? PeerTransportUdp : PeerTransportTcp;
+}
+
+} // namespace
+
+std::vector<TransportKind> Dialer::transport_order(uint8_t known) const {
+    const TransportKind first  = policy_.preferred;
+    const TransportKind second = first == TransportKind::Udp ? TransportKind::Tcp
+                                                             : TransportKind::Udp;
+    const auto allowed = [this](TransportKind k) {
+        return k == TransportKind::Udp ? policy_.allow_udp : policy_.allow_tcp;
+    };
+
+    std::vector<TransportKind> order;
+    if (allowed(first)) order.push_back(first);
+    // A zero fallback delay means "the preferred transport or nothing" — the
+    // second entry is exactly what the fallback timer would bring in.
+    if (allowed(second) && policy_.fallback_delay.count() > 0) order.push_back(second);
+    // ...unless the preferred one is not available at all, in which case the other
+    // is not a fallback, it is the only way out.
+    if (order.empty() && allowed(second)) order.push_back(second);
+
+    // A peer at this address has already told us which wires it accepts. Bring
+    // those to the front — stably, so the policy still decides between two the
+    // peer accepts equally. Nothing is dropped: the knowledge can be stale, and
+    // the cost of acting on a stale entry must stay "one fallback delay", never
+    // "this target is undialable". A single-entry order is left alone, which is
+    // what keeps a zero fallback delay meaning exactly what it says.
+    if (known != PeerTransportNone && order.size() > 1) {
+        std::stable_partition(order.begin(), order.end(), [known](TransportKind k) {
+            return (known & mask_for(k)) != 0;
+        });
+    }
+    return order;
+}
+
+void Dialer::dial(const std::string& host, uint16_t port) {
+    auto target  = std::make_shared<Target>();
+    target->host = host;
+    target->port = port;
+
+    bool started = false;
+    bool empty   = false;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (stopped_) return;
+        // Under the lock: the order depends on what identify has taught us about
+        // this address, which lives behind the same mutex as the bookkeeping.
+        target->pending = transport_order(recall(host, port));
+        empty           = target->pending.empty();
+        if (!empty) started = start_next(target);
+    }
+
+    if (empty) LOG_WARN("dialer", "No transport enabled; cannot dial " << host << ":" << port);
+
+    // Never with the lock held: a failure handler may well dial again (that is
+    // what a reconnection policy does), and this mutex is not recursive.
+    if (!started) on_failed_(host, port);
+}
+
+// ── What identify taught us about an address ────────────────────────────────
+
+std::string Dialer::key_for(const std::string& host, uint16_t port) {
+    return host + ":" + std::to_string(port);
+}
+
+uint8_t Dialer::recall(const std::string& host, uint16_t port) const {
+    const auto it = known_.find(key_for(host, port));
+    if (it == known_.end()) return PeerTransportNone;
+    if (Clock::now() - it->second.learned_at > kMemoryTtl) return PeerTransportNone;
+    return it->second.transports;
+}
+
+void Dialer::evict_one(Clock::time_point now) {
+    // One pass, and only when the cache is full: drop everything that has expired,
+    // and note the oldest survivor in case nothing had. A map capped at
+    // kMaxRemembered makes this bounded work on a path that runs once per dial.
+    auto oldest = known_.end();
+    for (auto it = known_.begin(); it != known_.end();) {
+        if (now - it->second.learned_at > kMemoryTtl) {
+            it = known_.erase(it);
+            continue;
+        }
+        if (oldest == known_.end() || it->second.learned_at < oldest->second.learned_at)
+            oldest = it;
+        ++it;
+    }
+    if (known_.size() >= kMaxRemembered && oldest != known_.end()) known_.erase(oldest);
+}
+
+void Dialer::remember(const std::string& host, uint16_t port, uint8_t transports) {
+    // 0 is "the peer did not say" (an older node predating the field), not
+    // "supports nothing" — storing it would teach us the opposite of the truth.
+    if (transports == PeerTransportNone || port == 0 || host.empty()) return;
+
+    const auto now = Clock::now();
+    std::lock_guard<std::mutex> lock(mutex_);
+
+    std::string key = key_for(host, port);
+    const auto  it  = known_.find(key);
+    if (it != known_.end()) {
+        it->second.transports = transports;
+        it->second.learned_at = now;
+        return;
+    }
+
+    if (known_.size() >= kMaxRemembered) evict_one(now);
+    known_.emplace(std::move(key), Known{transports, now});
+}
+
+uint8_t Dialer::known_transports(const std::string& host, uint16_t port) const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    return recall(host, port);
+}
+
+std::vector<TransportKind> Dialer::planned_order(const std::string& host, uint16_t port) const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    return transport_order(recall(host, port));
+}
+
+bool Dialer::start_next(const std::shared_ptr<Target>& target) {
+    // Walk the queue rather than taking only its head: a transport the pool cannot
+    // provide (no UDP socket, say) never becomes an attempt, so the next one takes
+    // its place at once instead of waiting out a fallback delay for nothing.
+    while (!target->pending.empty()) {
+        const TransportKind kind = target->pending.front();
+        target->pending.erase(target->pending.begin());
+
+        Reactor&     reactor = reactors_.pick(kind);
+        const ConnId id      = reactor.connect(target->host, target->port, kind);
+        if (id == kInvalidConnId) continue;
+
+        const PeerRoute route{reactor.index(), id};
+        target->routes.push_back(route);
+        attempts_.emplace(Key{route.reactor, route.conn}, target);
+        LOG_DEBUG("dialer", "Dialing " << target->host << ":" << target->port
+                  << " over " << to_string(kind));
+
+        if (!target->pending.empty()) arm_fallback(target, reactor);
+        return true;
+    }
+    return false;
+}
+
+void Dialer::arm_fallback(const std::shared_ptr<Target>& target, Reactor& reactor) {
+    // The timer holds only a weak reference and re-checks the target when it
+    // fires, so there is nothing to cancel when the race is decided early: the
+    // target is either gone or marked won, and the timer quietly does nothing.
+    std::weak_ptr<Target> weak  = target;
+    const auto            delay = policy_.fallback_delay;
+    Reactor*              r     = &reactor;
+
+    r->execute([this, r, weak, delay] {
+        r->schedule(delay, [this, weak] {
+            auto target = weak.lock();
+            if (!target) return;
+
+            bool        failed = false;
+            std::string host;
+            uint16_t    port = 0;
+            {
+                std::lock_guard<std::mutex> lock(mutex_);
+                if (stopped_ || target->won || target->pending.empty()) return;
+                LOG_DEBUG("dialer", "Racing the fallback transport for "
+                          << target->host << ":" << target->port);
+                if (!start_next(target) && target->routes.empty()) {
+                    failed = true;
+                    host   = target->host;
+                    port   = target->port;
+                }
+            }
+            if (failed) on_failed_(host, port);
+        });
+    });
+}
+
+void Dialer::on_established(PeerRoute route) {
+    std::vector<PeerRoute> superseded;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        auto it = attempts_.find(Key{route.reactor, route.conn});
+        if (it == attempts_.end()) return;  // inbound, or a dial already settled
+
+        std::shared_ptr<Target> target = it->second;
+        target->won = true;
+        target->pending.clear();
+
+        for (const PeerRoute& other : target->routes) {
+            attempts_.erase(Key{other.reactor, other.conn});
+            if (other != route) superseded.push_back(other);
+        }
+        target->routes.clear();
+    }
+
+    // Outside the lock: cancel_dial() posts to a reactor, and on this thread it may
+    // run the teardown — and therefore on_closed() — straight away.
+    //
+    // cancel_dial rather than close: a sibling that has finished its own handshake
+    // in the meantime is no longer this race's to end. Ending it anyway would be
+    // one end deciding, alone, which of two links to a peer lives — and the other
+    // end, which never saw this race, can just as easily decide the other way, so
+    // both links die and the peer is lost. Left alone, it reaches the peer table as
+    // an ordinary duplicate and is resolved there, the same way at both ends.
+    for (const PeerRoute& other : superseded)
+        reactors_.by_index(other.reactor).cancel_dial(other.conn, CloseReason::DialSuperseded);
+}
+
+void Dialer::on_closed(PeerRoute route) {
+    bool        failed = false;
+    std::string host;
+    uint16_t    port = 0;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        auto it = attempts_.find(Key{route.reactor, route.conn});
+        if (it == attempts_.end()) return;
+
+        std::shared_ptr<Target> target = it->second;
+        attempts_.erase(it);
+        target->routes.erase(std::remove(target->routes.begin(), target->routes.end(), route),
+                             target->routes.end());
+        if (stopped_ || target->won) return;
+
+        // This attempt is out. Bring the next transport in now rather than waiting
+        // for the fallback timer: a transport that fails fast should not cost the
+        // full delay before the other one is even tried.
+        if (!start_next(target) && target->routes.empty()) {
+            failed = true;
+            host   = target->host;
+            port   = target->port;
+        }
+    }
+    if (failed) on_failed_(host, port);
+}
+
+void Dialer::start() {
+    std::lock_guard<std::mutex> lock(mutex_);
+    stopped_ = false;
+    attempts_.clear();  // nothing from a previous run survives a restart
+}
+
+void Dialer::stop() {
+    std::lock_guard<std::mutex> lock(mutex_);
+    stopped_ = true;
+    attempts_.clear();
+}
+
+size_t Dialer::in_flight() const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    return attempts_.size();
+}
+
+} // namespace librats

package/native-src/src/librats/node/dialer.h

@@ -0,0 +1,188 @@
+#pragma once
+
+/**
+ * @file dialer.h
+ * @brief Picks the transport for an outbound connection, and races the fallback.
+ *
+ * With two equal transports available, "connect to this address" stops being one
+ * action. UDP is the better first choice for a peer-to-peer node — one socket and
+ * one NAT mapping for every peer, and a source port that is actually dialable —
+ * but some networks block or throttle it, and finding that out by waiting for a
+ * dial to time out would be unacceptable. So a dial is a small race, in the
+ * spirit of Happy Eyeballs (RFC 8305):
+ *
+ *   t = 0                start the preferred transport
+ *   t = fallback_delay   if it has not established yet, start the other one too
+ *   first to establish   wins; attempts still in flight for this target are cancelled
+ *   all attempts failed  report the dial as failed, exactly once
+ *
+ * Racing rather than falling back sequentially matters: on a UDP-hostile network
+ * the cost is the fallback delay, not a full connect timeout, and on a normal
+ * network the second attempt is never made at all.
+ *
+ * ── Not paying for the same discovery twice ─────────────────────────────────
+ * A peer says in its identify message which wires it accepts. Racing is how a
+ * dial finds that out when it has nothing to go on; paying the fallback delay
+ * *again*, on every later dial to an address that already told us, is pure loss —
+ * and a reconnection policy redials the same handful of addresses for the life of
+ * the node. So the dialer keeps a small cache of address → transports (fed by
+ * Node::handle_identify) and starts with a transport the peer actually has.
+ *
+ * Two properties make that safe to act on:
+ *   - It reorders, it never removes. Knowledge can be stale — a peer restarts
+ *     with a different config — and a stale entry must cost a fallback delay,
+ *     never a target that cannot be dialed at all. The transport the peer did not
+ *     claim stays in the queue behind the one it did.
+ *   - Only addresses the node can vouch for are recorded (see the caller). A
+ *     peer's self-advertised address list is its unverified word about where
+ *     anyone lives, so it is not allowed to set the dial order for someone else.
+ *
+ * Cancelling the loser is the reason Reactor::connect hands back a ConnId
+ * synchronously — without it every race would cost a second connection that has to
+ * be taken down after the fact.
+ *
+ * ── What this decides, and what it must not ─────────────────────────────────
+ * The race decides which transport this node *dials on*, and nothing more. It is
+ * settled by timing, here — and the peer never saw a race at all, only connections
+ * arriving. So a verdict reached here is one the other end cannot reproduce: if it
+ * also decided which link lives, it could just as well keep the one this end
+ * dropped, and then each end has torn down the other's choice and the peer is gone.
+ *
+ * Hence cancel_dial() rather than close(): an attempt that has already finished its
+ * handshake is left alone and handed on as an ordinary duplicate, for PeerTable::add
+ * to resolve from what both ends see alike (see peer_table.cpp).
+ *
+ * Threading: dial() is called from any thread; the attempt callbacks arrive on
+ * reactor threads. One mutex guards the (small) bookkeeping; nothing on the data
+ * path goes through here.
+ */
+
+#include "librats/core/types.h"
+#include "librats/peer/peer_table.h"   // PeerRoute
+#include "librats/transport/reactor_pool.h"
+
+#include <chrono>
+#include <cstdint>
+#include <functional>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+namespace librats {
+
+struct DialPolicy {
+    TransportKind             preferred = TransportKind::Udp;
+    bool                      allow_tcp = true;
+    bool                      allow_udp = true;
+    std::chrono::milliseconds fallback_delay{1200};
+};
+
+class Dialer {
+public:
+    using Clock = std::chrono::steady_clock;
+
+    /// Called once per target when every attempt has failed. Reactor thread.
+    using FailureHandler = std::function<void(const std::string& host, uint16_t port)>;
+
+    /// Addresses the transports cache holds. A node meets far more addresses than
+    /// it will ever redial (DHT and PEX see thousands), so this is a cache with a
+    /// ceiling, not a directory: past it the least recently learned entry goes.
+    static constexpr size_t kMaxRemembered = 1024;
+
+    /// How long a learned transports mask is trusted. A peer may restart on a
+    /// different config, and an entry that outlives the truth would send every
+    /// dial to a wire the peer no longer has — which costs the very fallback delay
+    /// this cache exists to avoid.
+    static constexpr std::chrono::minutes kMemoryTtl{10};
+
+    Dialer(ReactorPool& reactors, DialPolicy policy, FailureHandler on_failed)
+        : reactors_(reactors), policy_(policy), on_failed_(std::move(on_failed)) {}
+
+    /// Begin dialing `host:port`. Non-blocking; the outcome surfaces through the
+    /// node's peer-connected / dial-failed events.
+    void dial(const std::string& host, uint16_t port);
+
+    // — attempt outcomes, reported by the Node (reactor thread) —
+
+    /// An attempt completed its handshake; it wins the target.
+    void on_established(PeerRoute route);
+    /// An attempt ended (failed, was superseded, or simply closed later).
+    void on_closed(PeerRoute route);
+
+    /// Record which transports the peer reachable at `host:port` said it accepts
+    /// (a PeerTransports bitmask from its identify message). A later dial to the
+    /// same address starts with one of them instead of spending the fallback delay
+    /// rediscovering it. A mask of 0 ("did not say") is ignored rather than stored
+    /// as "supports nothing". Thread-safe; called from a reactor thread.
+    void remember(const std::string& host, uint16_t port, uint8_t transports);
+
+    /// What is currently believed about `host:port`, 0 if nothing (or if what was
+    /// learned has expired). Diagnostics and tests.
+    uint8_t known_transports(const std::string& host, uint16_t port) const;
+
+    /// The transports a dial to `host:port` would try, in order — exactly what
+    /// dial() computes, without starting anything. Diagnostics and tests.
+    std::vector<TransportKind> planned_order(const std::string& host, uint16_t port) const;
+
+    /// Accept dials again after a stop() — a Node may be restarted. What identify
+    /// taught us about addresses is knowledge about the network rather than
+    /// in-flight bookkeeping, so it deliberately survives the cycle.
+    void start();
+
+    /// Drop all bookkeeping; no further dials or fallbacks are started.
+    void stop();
+
+    /// Attempts currently in flight (diagnostics/tests).
+    size_t in_flight() const;
+
+private:
+    struct Target {
+        std::string                host;
+        uint16_t                   port = 0;
+        std::vector<TransportKind> pending;  ///< transports not yet tried, in order
+        std::vector<PeerRoute>     routes;   ///< attempts currently in flight
+        bool                       won = false;
+    };
+
+    using Key = std::pair<uint8_t, ConnId>;  ///< (reactor, conn) — unique per attempt
+
+    /// What one address last told us about itself.
+    struct Known {
+        uint8_t           transports = 0;
+        Clock::time_point learned_at{};
+    };
+
+    /// Start the next available transport in `target`'s queue; false if the queue
+    /// is exhausted (nothing was started). Caller holds the mutex — and must
+    /// report a resulting failure only after releasing it.
+    bool start_next(const std::shared_ptr<Target>& target);
+    /// Arm the timer that brings the second transport in. Caller holds the mutex.
+    void arm_fallback(const std::shared_ptr<Target>& target, Reactor& reactor);
+
+    /// The transports to try, in order: what the policy allows, with anything the
+    /// peer at this address said it accepts (`known`, 0 for "no idea") moved to
+    /// the front. Reorders only — see the note at the top of this file.
+    std::vector<TransportKind> transport_order(uint8_t known) const;
+
+    /// What is known about `host:port`, 0 if nothing or if it has expired. Caller
+    /// holds the mutex.
+    uint8_t recall(const std::string& host, uint16_t port) const;
+    /// Make room for one entry in a full cache. Caller holds the mutex.
+    void    evict_one(Clock::time_point now);
+
+    static std::string key_for(const std::string& host, uint16_t port);
+
+    ReactorPool&   reactors_;
+    DialPolicy     policy_;
+    FailureHandler on_failed_;
+
+    mutable std::mutex                        mutex_;
+    std::map<Key, std::shared_ptr<Target>>    attempts_;
+    std::unordered_map<std::string, Known>    known_;   ///< address → transports it accepts
+    bool                                      stopped_ = false;
+};
+
+} // namespace librats

package/native-src/src/librats/node/host_events.h

@@ -0,0 +1,26 @@
+#pragma once
+
+/**
+ * @file host_events.h
+ * @brief Node-level event types published on the EventBus.
+ *
+ * These describe things that happen to the *host* the node runs on (as opposed to
+ * the peer mesh), which several subsystems may want to react to independently.
+ * They are plain value types; a subsystem subscribes via `ctx.events.on<...>()`.
+ */
+
+#include <string>
+#include <vector>
+
+namespace librats {
+
+/// The set of local interface addresses changed — an interface came up/down, an
+/// IP was added/removed, the default route flipped (Wi-Fi↔cellular, VPN, dock,
+/// wake-from-sleep). Long-lived nodes react by renewing port mappings and
+/// re-discovering/re-announcing their public endpoint, which would otherwise go
+/// stale. Emitted (debounced) by the Node's NetworkMonitor.
+struct NetworkChanged {
+    std::vector<std::string> local_addresses;  ///< new, full list of local IPs
+};
+
+} // namespace librats

package/native-src/src/librats/node/identify.cpp

@@ -0,0 +1,130 @@
+#include "librats/node/identify.h"
+
+#include <utility>
+
+namespace librats {
+
+namespace {
+
+void put_u16(Bytes& out, uint16_t v) {
+    out.push_back(static_cast<uint8_t>(v >> 8));
+    out.push_back(static_cast<uint8_t>(v & 0xFF));
+}
+
+void put_addr(Bytes& out, const Address& a) {
+    // [len:u8][ip bytes: 4 or 16][port:u16] — the IP goes out as raw address bytes,
+    // not text, so an endpoint costs 7 (v4) or 19 (v6) bytes on the wire.
+    const ByteView ip = a.ip.bytes();
+    out.push_back(static_cast<uint8_t>(ip.size()));
+    out.insert(out.end(), ip.begin(), ip.end());
+    put_u16(out, a.port);
+}
+
+bool emittable(const Address& a) {
+    return !a.ip.is_unspecified();  // size() is then 4 or 16, always within kMaxIpLength
+}
+
+/// Bounds-checked forward reader: every read is validated against the remaining
+/// length, and the first short read latches `ok` false so the rest are no-ops.
+struct Reader {
+    const uint8_t* p;
+    size_t         n;
+    bool           ok = true;
+
+    explicit Reader(ByteView v) : p(v.data()), n(v.size()) {}
+
+    uint8_t u8() {
+        if (n < 1) { ok = false; return 0; }
+        const uint8_t v = *p;
+        ++p; --n;
+        return v;
+    }
+    uint16_t u16() {
+        const uint8_t hi = u8();
+        const uint8_t lo = u8();
+        return static_cast<uint16_t>((hi << 8) | lo);
+    }
+    std::string str(size_t len) {
+        if (n < len) { ok = false; return {}; }
+        std::string s(reinterpret_cast<const char*>(p), len);
+        p += len; n -= len;
+        return s;
+    }
+};
+
+} // namespace
+
+Bytes IdentifyMessage::encode() const {
+    Bytes out;
+    out.push_back(kVersion);
+    put_u16(out, listen_port);
+
+    // Emit at most kMaxAddresses well-formed addresses; the count prefix matches.
+    Bytes addr_blob;
+    uint8_t emitted = 0;
+    for (const Address& a : addresses) {
+        if (emitted >= kMaxAddresses) break;
+        if (!emittable(a) || a.port == 0) continue;
+        put_addr(addr_blob, a);
+        ++emitted;
+    }
+    out.push_back(emitted);
+    out.insert(out.end(), addr_blob.begin(), addr_blob.end());
+
+    // Observed address: an IP length of 0 means "none".
+    if (observed && emittable(*observed)) {
+        put_addr(out, *observed);
+    } else {
+        out.push_back(0);
+    }
+
+    // Appended last, where a decoder that predates it just ignores it.
+    out.push_back(transports);
+    return out;
+}
+
+std::optional<IdentifyMessage> IdentifyMessage::decode(ByteView in) {
+    Reader r(in);
+
+    const uint8_t version = r.u8();
+    if (!r.ok || version != kVersion) return std::nullopt;  // unknown/old → "no identify"
+
+    IdentifyMessage msg;
+    msg.listen_port = r.u16();
+
+    const uint8_t count = r.u8();
+    if (!r.ok || count > kMaxAddresses) return std::nullopt;  // capped: never over-reserve
+    msg.addresses.reserve(count);
+    for (uint8_t i = 0; i < count; ++i) {
+        const uint8_t ip_len = r.u8();
+        if (!r.ok || (ip_len != 4 && ip_len != 16)) return std::nullopt;
+        std::string ip = r.str(ip_len);
+        const uint16_t port = r.u16();
+        if (!r.ok) return std::nullopt;
+        auto addr = IpAddress::from_bytes(ByteView(ip));
+        if (!addr) return std::nullopt;
+        msg.addresses.push_back(Address{*addr, port});
+    }
+
+    const uint8_t obs_len = r.u8();
+    if (!r.ok) return std::nullopt;
+    if (obs_len != 0) {
+        if (obs_len != 4 && obs_len != 16) return std::nullopt;
+        std::string ip = r.str(obs_len);
+        const uint16_t port = r.u16();
+        if (!r.ok) return std::nullopt;
+        auto addr = IpAddress::from_bytes(ByteView(ip));
+        if (!addr) return std::nullopt;
+        msg.observed = Address{*addr, port};
+    }
+
+    // Optional trailing extension. A sender that predates it leaves the field at
+    // 0, which reads as "did not say" rather than "supports nothing".
+    const uint8_t transports = r.u8();
+    if (r.ok) msg.transports = transports;
+
+    // Any further trailing bytes (a future extension) are tolerated and ignored.
+    return msg;
+}
+
+} // namespace librats

package/native-src/src/librats/node/identify.h

@@ -0,0 +1,71 @@
+#pragma once
+
+/**
+ * @file identify.h
+ * @brief The node's "identify" control message — how peers learn each other's
+ *        dialable addresses (libp2p-identify in spirit).
+ *
+ * A TCP socket only reveals a peer's *source* endpoint: its IP plus an ephemeral
+ * port the OS picked for the outbound socket — never the port it listens on. So
+ * the dialable address of an INBOUND peer is unknowable from the connection
+ * alone; the peer must tell us. Right after the secure handshake, each side sends
+ * an Identify message over the authenticated channel carrying:
+ *
+ *   - listen_port : the TCP port this node accepts connections on. The receiver
+ *                   pairs it with the IP it sees the sender at to form a dialable
+ *                   address (the key that makes inbound peers reconnectable).
+ *   - addresses   : additional self-advertised dialable addresses (e.g. each local
+ *                   interface IP with the listen port) — the "multiaddr set".
+ *   - observed    : the address the sender observed the RECIPIENT connecting from,
+ *                   so a node can learn its own public IP as peers see it.
+ *   - transports  : which wires the sender accepts on that port (TCP, the
+ *                   datagram transport, or both). Both bind the SAME port, so
+ *                   this is a property of the node rather than of an address —
+ *                   it tells a peer which transports are worth dialing before it
+ *                   spends a fallback delay finding out.
+ *
+ * The transports byte is appended after the older fields, and decode has always
+ * ignored trailing bytes, so a node that predates it simply reads the message
+ * without it and reports "unspecified" rather than failing.
+ *
+ * The wire form is a compact, versioned, fully bounds-checked binary blob — decode
+ * never trusts a length without checking it against the buffer, and every count is
+ * capped, so a malformed or hostile payload yields nullopt rather than misbehaving.
+ */
+
+#include "librats/util/rats_export.h"
+#include "librats/core/address.h"
+#include "librats/core/bytes.h"
+
+#include <cstdint>
+#include <optional>
+#include <vector>
+
+namespace librats {
+
+struct RATS_API IdentifyMessage {
+    static constexpr uint8_t kVersion      = 1;   ///< IPs on the wire are raw bytes (4/16), not text
+    static constexpr size_t  kMaxAddresses = 32;  ///< cap advertised addresses
+    static constexpr size_t  kMaxIpLength  = 16;  ///< a single IP is 4 (v4) or 16 (v6) bytes
+
+    /// Transport bitmask values, matching PeerTransports in peer/peer_info.h.
+    static constexpr uint8_t kTransportTcp = 1 << 0;
+    static constexpr uint8_t kTransportUdp = 1 << 1;
+
+    uint16_t               listen_port = 0;
+    std::vector<Address>   addresses;   ///< sender's self-advertised dialable addrs
+    std::optional<Address> observed;    ///< address sender saw the recipient at
+    /// Transports the sender accepts on listen_port. 0 means the sender did not
+    /// say (an older peer); treat that as "no better information", not as "none".
+    uint8_t                transports = 0;
+
+    /// Serialise to the wire form. Addresses with an empty IP, an over-long IP, or
+    /// a zero port are skipped; at most kMaxAddresses are emitted.
+    Bytes encode() const;
+
+    /// Parse the wire form. Returns nullopt on an unknown version or any
+    /// truncation/inconsistency — the caller treats that as "no identify".
+    static std::optional<IdentifyMessage> decode(ByteView in);
+};
+
+} // namespace librats