librats 1.0.2 → 2.1.4

package/native-src/src/librats/subsystems/hole_punch.h

@@ -0,0 +1,266 @@
+#pragma once
+
+/**
+ * @file hole_punch.h
+ * @brief UDP hole punching: two nodes behind NATs dial each other at the same
+ *        instant, arranged through a peer they both already have.
+ *
+ * ── Why this can work at all ────────────────────────────────────────────────
+ * A NAT drops an inbound datagram unless something went out to that peer first.
+ * So neither side can be dialed — but if BOTH dial at once, each one's outbound
+ * Syn opens the mapping and the filter its peer's Syn needs, and the two cross
+ * mid-path. Whichever direction survives becomes an ordinary connection.
+ *
+ * Everything below that is already in place and is deliberately left alone:
+ *
+ *   - The punch packet is the Syn. A datagram dial sends one immediately
+ *     (UdpMux::connect) and retries it, so a punch needs no new packet type on the
+ *     wire — only a different retry shape (DialProfile::punch(): dense probes with
+ *     no backoff, because the first Syns are *expected* to die on the peer's NAT).
+ *   - One socket, one mapping. Every UDP peer shares the node's single datagram
+ *     socket, so the port a peer sees us send from is the port anyone can aim at.
+ *     That is what identify now reports on datagram links, and what nat_status.h
+ *     turns into "is this mapping stable enough to punch through at all".
+ *   - Both sides succeeding is fine. A punch normally lands in both directions,
+ *     leaving two connections; PeerTable::add resolves that pair identically at
+ *     both ends (the link from the smaller PeerId survives), exactly as it does for
+ *     any simultaneous cross-connect.
+ *
+ * ── The only genuinely hard part: agreeing on "now" ─────────────────────────
+ * Punching works when the two bursts overlap, and the peers have no shared clock.
+ * The fix (as in libp2p's DCUtR) is to derive the instant from the round trip
+ * itself rather than from any clock. With A the initiator, B the target and R a
+ * peer both are connected to:
+ *
+ *   1. A →R→ B   Connect{addrs of A}          A notes the time it sent this
+ *   2. B →R→ A   Connect{addrs of B}          B now waits
+ *   3. A →R→ B   Sync                         A starts dialing AT ONCE
+ *   4.           B receives Sync              B starts dialing AT ONCE
+ *
+ * A starts half a relayed round trip early and B starts on arrival, so the two
+ * bursts meet in the middle of the path. No clock synchronisation, and the accuracy
+ * degrades gracefully — a slow relay widens the window rather than breaking it,
+ * which is why the punch profile fires several probes instead of one.
+ *
+ * ── The relay ───────────────────────────────────────────────────────────────
+ * R is an ordinary node running this same subsystem. It forwards ONLY control
+ * messages, ONLY to a peer it is already connected to, and ONLY within a per-peer
+ * budget. It never opens a connection, never resolves an address and never carries
+ * application data — so it cannot be turned into an open reflector, and the traffic
+ * it does relay is a few dozen bytes per punch.
+ *
+ * ── Wire format (MessageType::Punch), big-endian ────────────────────────────
+ *   envelope : [u8 ver=1][u8 op]
+ *              op=0 Relay   : [32B dst_id][inner…]   sender → relay
+ *              op=1 Relayed : [32B src_id][inner…]   relay  → destination
+ *   inner    : [u8 kind]
+ *              kind=0 Connect : [u8 role][u8 n][ n × { u8 ip_len, ip bytes, u16 port } ]
+ *              kind=1 Sync    : —
+ *
+ * `role` says whether a Connect opens a rendezvous (0) or answers one (1). Without
+ * it the two are indistinguishable, and an initiator would read the answer it asked
+ * for as a competing rendezvous — hand the round to the peer, and the exchange would
+ * ping-pong Connects forever with neither side ever sending Sync. It is also what
+ * makes the collision case (both ends opening at once) recognisable, and therefore
+ * settleable by the same symmetric PeerId rule the peer table uses.
+ *
+ * The inner message is end-to-end between the two punching peers; the relay copies
+ * it across without looking inside. Every length is bounds-checked and every count
+ * capped, so a malformed or hostile payload is dropped rather than acted on.
+ *
+ * ── What this does NOT do ───────────────────────────────────────────────────
+ * A symmetric NAT (a fresh mapping per destination) cannot be punched through by
+ * any endpoint we can advertise, and this subsystem does not pretend otherwise: it
+ * checks NatMapping first and declines rather than firing a burst that cannot land.
+ * There is no TCP punching (the datagram wire is the one that fits), no port
+ * prediction (it would need more than the one socket the design is built on) and no
+ * relaying of data (a punch that fails, fails).
+ *
+ * Trust: the addresses a peer advertises for itself are its own unverified word, and
+ * a relay could forge a Connect naming somebody else's endpoint. Acting on that
+ * means sending a handful of 16-byte Syns to an address of another node's choosing —
+ * the same exposure PeerExchange already accepts when it dials what a peer told it
+ * about, and bounded here by the per-session address cap and the retry limits.
+ *
+ * Threading: message handlers run on reactor threads; one worker thread drives
+ * session timeouts and retries. All session state is behind one mutex, and no
+ * blocking work happens on a reactor thread.
+ */
+
+#include "librats/util/rats_export.h"
+#include "librats/core/address.h"
+#include "librats/core/types.h"
+#include "librats/node/nat_status.h"
+#include "librats/node/peer_network.h"
+#include "librats/peer/peer.h"
+#include "librats/peer/peer_id.h"
+#include "librats/subsystems/hole_punch_service.h"
+
+#include <atomic>
+#include <chrono>
+#include <condition_variable>
+#include <cstdint>
+#include <mutex>
+#include <thread>
+#include <unordered_map>
+#include <vector>
+
+namespace librats {
+
+class DialService;
+
+/// Published as HolePunchService, so a module that discovers a peer it cannot dial
+/// (PeerExchange) can hand the id over without depending on this class.
+class RATS_API HolePunch final : public Subsystem, public HolePunchService {
+public:
+    struct Config {
+        /// Peers asked to carry one punch's rendezvous. More than one because we
+        /// cannot know which of our peers also has the target; each relay that does
+        /// not simply drops the request. Small, because every extra relay is a
+        /// duplicate rendezvous the target has to recognise and ignore.
+        size_t max_relays = 3;
+
+        /// Endpoints advertised to the target, and therefore dialed by it. Capped:
+        /// this is the fan-out one peer's claim can make us produce.
+        size_t max_addresses = 4;
+
+        /// Rendezvous rounds before a target is given up on for `cooldown`.
+        int attempts = 3;
+
+        /// How long one round may take from the first Connect to a live connection.
+        /// Covers two relayed hops plus the punch burst itself.
+        std::chrono::milliseconds round_timeout{6000};
+
+        /// How long after giving up before the same target may be punched again.
+        /// Only a rendezvous WE opened ever ends in one: a round we merely answered
+        /// timing out says nothing about the target, and calling it off there would
+        /// silently drop the retries the initiator is already sending.
+        std::chrono::milliseconds cooldown{60000};
+
+        /// Concurrent punch sessions. Bounds both memory and how many dial bursts
+        /// this node can be talked into producing at once.
+        size_t max_sessions = 32;
+
+        /// Serve as a rendezvous for other peers' punches. Cheap (a few dozen bytes
+        /// forwarded per punch) but it is still work done on somebody else's behalf,
+        /// so it is a choice rather than an assumption.
+        bool enable_relay = true;
+
+        /// Relay budget: messages one peer may have forwarded per window. A punch
+        /// costs two forwarded messages per round, so the default leaves generous
+        /// room for honest use while capping what one peer can spend us.
+        size_t                    relay_budget = 12;
+        std::chrono::milliseconds relay_window{1000};
+
+        /// Refuse to punch when the mesh says our own mapping is per-destination
+        /// (symmetric NAT): no endpoint we could advertise would be the one the
+        /// target's packets arrive on, so the burst cannot land. Turn off only to
+        /// try anyway (a NAT can be misclassified by an unlucky sample).
+        bool skip_when_endpoint_dependent = true;
+
+        /// How hard each punch dial retries its Syn.
+        DialProfile profile = DialProfile::punch();
+
+        /// Session bookkeeping cadence — retries, timeouts, cooldown expiry.
+        std::chrono::milliseconds tick{250};
+    };
+
+    HolePunch();
+    explicit HolePunch(Config config);
+    ~HolePunch() override;
+
+    void attach(NodeContext& ctx) override;
+    void start() override;
+    void stop() override;
+
+    /// Try to reach `target` by punching. Non-blocking: the rendezvous runs in the
+    /// background and a successful punch surfaces as an ordinary peer-connected
+    /// event. A no-op when already connected to the target, when a session for it
+    /// is already running, when it is still in cooldown, or when this node has
+    /// nothing punchable to advertise (see nat_status.h).
+    /// @return whether a session was actually started.
+    bool punch(const PeerId& target) override;
+
+    /// Sessions currently in flight (diagnostics and tests).
+    size_t active_sessions() const;
+    /// Punch bursts this node has fired (diagnostics and tests).
+    uint64_t punches_started() const noexcept { return punches_started_.load(); }
+    /// Messages forwarded on behalf of other peers (diagnostics and tests).
+    uint64_t relayed() const noexcept { return relayed_.load(); }
+
+private:
+    enum class Phase : uint8_t {
+        AwaitingPeerConnect,  ///< initiator: our Connect is out, waiting for theirs
+        AwaitingSync,         ///< responder: our Connect is out, waiting for Sync
+        Punching,             ///< the burst is in flight
+    };
+
+    struct Session {
+        bool                                  initiator = false;
+        Phase                                 phase = Phase::AwaitingPeerConnect;
+        int                                   attempt = 0;
+        std::vector<Address>                  peer_addresses;
+        std::chrono::steady_clock::time_point deadline{};
+        /// The relay that last carried something from the target, if any. Once one
+        /// hop is known to work, the rest of the exchange goes back the same way —
+        /// it is the one path proven to reach the target, and it keeps the fan-out
+        /// (and the load on peers that cannot help) to the first message alone.
+        PeerId                                via{};
+        bool                                  have_via = false;
+    };
+
+    // — message handling (reactor threads) —
+    void handle(const Peer& from, ByteView payload);
+    void handle_relay_request(const Peer& from, const PeerId& dst, ByteView inner);
+    void handle_relayed(const Peer& via, const PeerId& src, ByteView inner);
+    /// @param opening whether the sender is opening a rendezvous (rather than
+    ///        answering ours) — see the `role` byte in the wire format above.
+    void handle_connect(const Peer& via, const PeerId& src, bool opening,
+                        std::vector<Address> addresses);
+    void handle_sync(const PeerId& src);
+
+    // — outgoing —
+    /// Wrap `inner` in a Relay envelope and hand it to peers that might reach `dst`:
+    /// just `via` when a working hop is already known, otherwise up to max_relays of
+    /// our peers. Returns how many were given it.
+    size_t relay_to(const PeerId& dst, const Bytes& inner, const PeerId* via);
+    bool   send_connect(const PeerId& target, bool opening, const PeerId* via);
+    void   send_sync(const PeerId& target, const PeerId* via);
+    /// Fire the dial burst at everything the peer advertised. Caller must NOT hold
+    /// the mutex: dialing reaches the reactor, which may run callbacks inline.
+    void   fire_punch(const PeerId& target, const std::vector<Address>& addresses);
+
+    // — worker —
+    void loop();
+    void service_sessions();
+
+    // — helpers —
+    std::vector<Address> own_punch_addresses() const;
+    bool                 relay_budget_ok(const PeerId& from);
+    bool                 in_cooldown(const PeerId& target) const;   ///< caller holds mutex_
+    void                 begin_cooldown(const PeerId& target);      ///< caller holds mutex_
+
+    Config                 config_;
+    PeerNetwork*           network_  = nullptr;
+    DialService*           dialer_   = nullptr;
+    ExternalAddressService* external_ = nullptr;
+
+    std::atomic<bool>     running_{false};
+    std::atomic<uint64_t> punches_started_{0};
+    std::atomic<uint64_t> relayed_{0};
+
+    mutable std::mutex      mutex_;
+    std::condition_variable cv_;
+    std::thread             worker_;
+    std::unordered_map<PeerId, Session, PeerId::Hash> sessions_;
+    std::unordered_map<PeerId, std::chrono::steady_clock::time_point, PeerId::Hash> cooldown_;
+
+    struct RelayBudget {
+        std::chrono::steady_clock::time_point window_started{};
+        size_t                                spent = 0;
+    };
+    std::mutex                                              relay_mutex_;
+    std::unordered_map<PeerId, RelayBudget, PeerId::Hash>    relay_budget_;
+};
+
+} // namespace librats

package/native-src/src/librats/subsystems/hole_punch_service.h

@@ -0,0 +1,38 @@
+#pragma once
+
+/**
+ * @file hole_punch_service.h
+ * @brief Capability that lets a sibling module ask for a NAT hole punch by PeerId.
+ *
+ * Published by HolePunch via ServiceRegistry (see service_registry.h). A discovery
+ * module knows *who* it failed to reach long before it knows why — PeerExchange, for
+ * instance, learns a peer's id together with an address that then refuses to dial —
+ * and this is the whole contract it needs to hand that id over: no addresses, no
+ * relay selection, no NAT reasoning, all of which are HolePunch's own business.
+ *
+ * Resolving it returns nullptr when hole punching is not enabled, which is exactly
+ * what makes the fallback optional at the consumer's side:
+ *
+ *     if (auto* punch = ctx.services.get<HolePunchService>()) punch->punch(id);
+ *
+ * The provider registers during attach(), so resolve it in start() (every attach()
+ * runs before any start()) rather than in your own attach(), where the provider may
+ * not have been attached yet. The pointer is NON-owning and valid while the node is.
+ */
+
+#include "librats/util/rats_export.h"
+#include "librats/peer/peer_id.h"
+
+namespace librats {
+
+struct RATS_API HolePunchService {
+    virtual ~HolePunchService() = default;
+
+    /// Try to reach `target` by punching. Non-blocking; a successful punch surfaces
+    /// as an ordinary peer-connected event. @return whether a rendezvous actually
+    /// started — false is routine (already connected, already punching, in cooldown,
+    /// or nothing punchable to advertise) and needs no handling by the caller.
+    virtual bool punch(const PeerId& target) = 0;
+};
+
+} // namespace librats

package/native-src/src/librats/subsystems/mdns_discovery.cpp

@@ -0,0 +1,66 @@
+#include "librats/subsystems/mdns_discovery.h"
+#include "librats/node/node_context.h"
+#include "librats/util/logger.h"
+
+namespace librats {
+
+MdnsDiscovery::MdnsDiscovery() : MdnsDiscovery(Config()) {}
+
+MdnsDiscovery::MdnsDiscovery(Config config) : config_(std::move(config)) {}
+
+MdnsDiscovery::~MdnsDiscovery() { stop(); }
+
+void MdnsDiscovery::attach(NodeContext& ctx) { network_ = &ctx.network; }
+
+void MdnsDiscovery::start() {
+    if (running_.exchange(true)) return;
+
+    instance_ = config_.instance_name.empty() ? ("rats-" + network_->local_id().short_hex())
+                                              : config_.instance_name;
+    const uint16_t port = network_->listen_port();
+
+    mdns_ = std::make_unique<MdnsClient>(instance_, port);
+    mdns_->set_service_callback([this](const MdnsService& service, bool is_new) { on_service(service, is_new); });
+    if (!mdns_->start()) {
+        LOG_ERROR("mdns-discovery", "Failed to start mDNS client");
+        running_.store(false);
+        mdns_.reset();
+        return;
+    }
+    mdns_->announce_service(instance_, port);
+    mdns_->start_discovery();
+    LOG_INFO("mdns-discovery", "Announcing '" << instance_ << "' on port " << port);
+}
+
+void MdnsDiscovery::stop() {
+    if (!running_.exchange(false)) return;
+    if (mdns_) {
+        mdns_->stop_discovery();
+        mdns_->stop_announcing();
+        mdns_->stop();
+        mdns_.reset();
+    }
+}
+
+bool MdnsDiscovery::is_running() const { return running_.load() && mdns_ && mdns_->is_running(); }
+
+void MdnsDiscovery::on_service(const MdnsService& service, bool /*is_new*/) {
+    if (service.ip_address.empty() || service.port == 0) return;
+    // Skip our own announcement (its name carries our instance label).
+    if (service.service_name.find(instance_) != std::string::npos) return;
+
+    // service.ip_address comes off the wire (untrusted); only dial a valid numeric IP.
+    const auto ip = IpAddress::parse(service.ip_address);
+    if (!ip) return;
+
+    const Address addr{*ip, service.port};
+    {
+        std::lock_guard<std::mutex> lock(dialed_mutex_);
+        if (!dialed_.insert(addr).second) return;  // already dialed this address
+    }
+    LOG_DEBUG("mdns-discovery", "Dialing discovered service " << service.service_name
+                                 << " at " << addr.to_string());
+    network_->connect(addr);
+}
+
+} // namespace librats

package/native-src/src/librats/subsystems/mdns_discovery.h

@@ -0,0 +1,55 @@
+#pragma once
+
+/**
+ * @file mdns_discovery.h
+ * @brief Local-network peer discovery via mDNS — a thin adapter, not a rewrite.
+ *
+ * Wraps the existing MdnsClient (src/mdns.h) as a Subsystem WITHOUT modifying it.
+ * On start it announces our TCP listen port as an mDNS service and browses for
+ * the same service type, dialing discovered instances through the node. Each
+ * node uses a unique instance name (derived from its PeerId) so two nodes on the
+ * same host don't collide and can filter out their own announcement.
+ */
+
+#include "librats/util/rats_export.h"
+#include "librats/node/peer_network.h"
+#include "librats/mdns/mdns.h"
+
+#include <atomic>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <unordered_set>
+
+namespace librats {
+
+class RATS_API MdnsDiscovery final : public Subsystem {
+public:
+    struct Config {
+        std::string instance_name = "";  ///< empty → derived from our PeerId
+    };
+
+    MdnsDiscovery();
+    explicit MdnsDiscovery(Config config);
+    ~MdnsDiscovery() override;
+
+    void attach(NodeContext& ctx) override;
+    void start() override;
+    void stop() override;
+
+    bool is_running() const;
+
+private:
+    void on_service(const MdnsService& service, bool is_new);
+
+    Config                     config_;
+    std::string                instance_;
+    PeerNetwork*               network_ = nullptr;
+    std::unique_ptr<MdnsClient> mdns_;
+    std::atomic<bool>          running_{false};
+
+    std::mutex                      dialed_mutex_;
+    std::unordered_set<Address> dialed_;  ///< peers we've already dialed
+};
+
+} // namespace librats

package/native-src/src/librats/subsystems/message_json.cpp

@@ -0,0 +1,112 @@
+#include "librats/subsystems/message_json.h"
+#include "librats/node/node_context.h"
+#include "librats/util/logger.h"
+
+#include <algorithm>
+
+namespace librats {
+
+void MessageJson::attach(NodeContext& ctx) {
+    network_ = &ctx.network;
+    network_->on(MessageType::Typed,
+        [this](const Peer& peer, ByteView payload) { on_typed(peer.id(), payload); });
+}
+
+// ── Registration ────────────────────────────────────────────────────────────
+
+void MessageJson::on(const std::string& type, Handler handler) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    handlers_[type].push_back({std::move(handler), /*once=*/false});
+}
+
+void MessageJson::once(const std::string& type, Handler handler) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    handlers_[type].push_back({std::move(handler), /*once=*/true});
+}
+
+void MessageJson::off(const std::string& type) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    handlers_.erase(type);
+}
+
+// ── Sending ─────────────────────────────────────────────────────────────────
+
+Bytes MessageJson::encode(const std::string& type, const librats::Json& data) {
+    const std::string body = data.dump();
+    Bytes out;
+    out.reserve(2 + type.size() + body.size());
+    out.push_back(static_cast<uint8_t>((type.size() >> 8) & 0xFF));
+    out.push_back(static_cast<uint8_t>(type.size() & 0xFF));
+    out.insert(out.end(), type.begin(), type.end());
+    out.insert(out.end(), body.begin(), body.end());
+    return out;
+}
+
+void MessageJson::send(const std::string& type, const librats::Json& data, SendCallback cb) {
+    if (!network_) { if (cb) cb(false, "not attached to a network"); return; }
+
+    const Bytes payload = encode(type, data);
+    const size_t n = network_->connected_peers().size();
+    network_->broadcast(MessageType::Typed, ByteView(payload));
+    if (cb) cb(n > 0, n > 0 ? "" : "no connected peers");
+}
+
+void MessageJson::send(const PeerId& to, const std::string& type, const librats::Json& data,
+                       SendCallback cb) {
+    if (!network_) { if (cb) cb(false, "not attached to a network"); return; }
+
+    // A send() to an unknown peer is a safe no-op, so only pay for the directory
+    // lookup when the caller actually wants a delivery verdict.
+    if (cb) {
+        const auto peers = network_->connected_peers();
+        if (std::find(peers.begin(), peers.end(), to) == peers.end()) {
+            cb(false, "peer not connected");
+            return;
+        }
+    }
+    network_->send(to, MessageType::Typed, ByteView(encode(type, data)));
+    if (cb) cb(true, "");
+}
+
+// ── Receiving (reactor thread) ──────────────────────────────────────────────
+
+void MessageJson::on_typed(const PeerId& from, ByteView payload) {
+    const uint8_t* p = payload.data();
+    const size_t   n = payload.size();
+    if (n < 2) return;
+
+    const size_t type_len = (static_cast<size_t>(p[0]) << 8) | p[1];
+    if (2 + type_len > n) return;
+
+    std::string type(reinterpret_cast<const char*>(p + 2), type_len);
+    librats::Json data = librats::Json::parse(p + 2 + type_len, p + n, nullptr, /*allow_exceptions=*/false);
+    if (data.is_discarded()) {
+        LOG_WARN("msgex", "Malformed JSON for type '" << type << "' from " << from.short_hex());
+        return;
+    }
+
+    // Snapshot the handlers under the lock and drop the one-shot ones, then invoke
+    // outside the lock so a handler may freely (un)register without deadlocking.
+    std::vector<Entry> to_call;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        auto it = handlers_.find(type);
+        if (it == handlers_.end()) return;
+        to_call = it->second;
+        auto& vec = it->second;
+        vec.erase(std::remove_if(vec.begin(), vec.end(), [](const Entry& e) { return e.once; }), vec.end());
+        if (vec.empty()) handlers_.erase(it);
+    }
+
+    for (const Entry& e : to_call) {
+        try {
+            e.handler(from, data);
+        } catch (const std::exception& ex) {
+            LOG_ERROR("msgex", "Handler for '" << type << "' threw: " << ex.what());
+        } catch (...) {
+            LOG_ERROR("msgex", "Handler for '" << type << "' threw an unknown exception");
+        }
+    }
+}
+
+} // namespace librats

package/native-src/src/librats/subsystems/message_json.h

@@ -0,0 +1,88 @@
+#pragma once
+
+/**
+ * @file message_json.h
+ * @brief Typed JSON message exchange over PeerNetwork.
+ *
+ * A familiar `on`/`once`/`off` + `send` messaging API as a Subsystem: an
+ * application names a message *type* (a string) and exchanges librats::Json
+ * payloads with peers, without caring about framing or channels. Attach it like
+ * any subsystem; reach it later via node.json() (or subsystem<MessageJson>()):
+ *
+ *   node.add_subsystem(std::make_unique<MessageJson>());
+ *   node.json()->on("chat", [](const PeerId& from, const json& j){ ... });
+ *   node.start();
+ *   node.json()->send(peer_id, "chat", json{{"text","hi"}});
+ *
+ * Two deliberate properties:
+ *   - the sender is the *authenticated* PeerId from the handshake, not a
+ *     self-reported field in the payload (which could be spoofed);
+ *   - no JSON envelope on the wire — just [type][payload], encrypted by the
+ *     transport like everything else.
+ *
+ * Wire format (MessageType::Typed payload):
+ *   [type_len:u16][type bytes][json payload bytes]   (json as compact text)
+ *
+ * Handlers run on a reactor thread; do not block in them. Registration is
+ * thread-safe and may happen before or after start().
+ */
+
+#include "librats/util/rats_export.h"
+#include "librats/node/peer_network.h"
+#include "librats/peer/peer.h"
+#include "librats/peer/peer_id.h"
+#include "librats/core/bytes.h"
+#include "librats/util/json.h"
+
+#include <functional>
+#include <mutex>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+namespace librats {
+
+class RATS_API MessageJson final : public Subsystem {
+public:
+    using Handler      = std::function<void(const PeerId& from, const librats::Json& data)>;
+    using SendCallback = std::function<void(bool ok, const std::string& error)>;
+
+    /// Register a handler for `type`. Additive: multiple handlers may coexist and
+    /// all fire (in registration order) for each received message of that type.
+    void on(const std::string& type, Handler handler);
+
+    /// Like on(), but the handler is removed right after it fires once.
+    void once(const std::string& type, Handler handler);
+
+    /// Remove every handler registered for `type`.
+    void off(const std::string& type);
+
+    /// Broadcast `data` of `type` to all connected peers. `cb`, if given, reports
+    /// whether there was at least one peer to send to.
+    void send(const std::string& type, const librats::Json& data, SendCallback cb = nullptr);
+
+    /// Send `data` of `type` to one peer. `cb`, if given, reports success or the
+    /// reason it could not be sent (e.g. the peer is not connected).
+    void send(const PeerId& to, const std::string& type, const librats::Json& data,
+              SendCallback cb = nullptr);
+
+    // Subsystem — no background thread; purely event-driven.
+    void attach(NodeContext& ctx) override;
+    void start() override {}
+    void stop() override {}
+
+private:
+    void on_typed(const PeerId& from, ByteView payload);
+    static Bytes encode(const std::string& type, const librats::Json& data);
+
+    struct Entry {
+        Handler handler;
+        bool    once;
+    };
+
+    PeerNetwork* network_ = nullptr;
+    mutable std::mutex mutex_;
+    std::unordered_map<std::string, std::vector<Entry>> handlers_;
+};
+
+} // namespace librats