librats 1.0.2 → 2.2.0

package/native-src/src/librats/bindings/rats.cpp

@@ -0,0 +1,762 @@
+#include "librats/bindings/rats.h"
+
+#include "librats/node/node.h"
+#include "librats/peer/peer_info.h"
+#include "librats/subsystems/dht_discovery.h"
+#include "librats/subsystems/mdns_discovery.h"
+#include "librats/subsystems/port_mapping_service.h"
+#include "librats/subsystems/hole_punch.h"
+#include "librats/subsystems/relay.h"
+#include "librats/subsystems/pubsub.h"
+#include "librats/subsystems/message_json.h"
+#include "librats/subsystems/file_transfer.h"
+#include "librats/subsystems/ping_service.h"
+#include "librats/subsystems/reconnection.h"
+#ifdef RATS_SEARCH_FEATURES
+#include "librats/subsystems/bittorrent.h"
+#endif
+#include "librats/core/address.h"
+#include "librats/util/network_utils.h"
+#include "librats/util/logger.h"
+#include "librats/util/json.h"
+#include "librats/util/version.h"
+
+#include <cstdlib>
+#include <cstring>
+#include <memory>
+#include <string>
+
+using namespace librats;
+
+namespace {
+
+// A C handle is a thin owner of the Node plus non-owning pointers to the
+// subsystems it has enabled (the Node owns those). Subsystems are explicit: each
+// rats_enable_* attaches one before start() and records it here; the *_enabled
+// flags dedup the enables that don't keep a pointer. `started` gates the
+// before-start contract so enables after start() can be rejected cleanly.
+struct RatsHandle {
+    std::unique_ptr<Node> node;
+    PubSub*              pubsub    = nullptr;
+    MessageJson*         messages  = nullptr;
+    FileTransfer*        files     = nullptr;
+    PingService*         ping      = nullptr;
+    ReconnectionService* reconnect = nullptr;
+    HolePunch*           punch     = nullptr;
+    Relay*               relay     = nullptr;
+#ifdef RATS_SEARCH_FEATURES
+    Bittorrent*          bittorrent = nullptr;
+#endif
+    std::string data_dir;  ///< copied from NodeConfig so subsystems can co-locate state
+    bool dht_enabled     = false;
+    bool mdns_enabled    = false;
+    bool portmap_enabled = false;
+    bool started         = false;
+};
+
+// Build a handle around a freshly-constructed Node, remembering the data_dir
+// (the config is moved into the Node, so copy it out first) for subsystems that
+// co-locate persistent state (DHT routing table, reconnection store).
+RatsHandle* make_handle(NodeConfig config) {
+    auto* h = new RatsHandle();
+    h->data_dir = config.data_dir;
+    h->node = std::make_unique<Node>(std::move(config));
+    return h;
+}
+
+RatsHandle* as_handle(rats_t handle) { return static_cast<RatsHandle*>(handle); }
+
+// Turn a caller-supplied (host, port) into a numeric Address. A numeric literal is
+// used verbatim; a hostname is resolved here at the API boundary (IPv4 first, then
+// IPv6) so the reconnection subsystem only ever holds resolved endpoints. Returns
+// nullopt if the host is neither a valid literal nor resolvable.
+std::optional<Address> resolve_target(const char* host, uint16_t port) {
+    if (auto ip = IpAddress::parse(host)) return Address{*ip, port};
+    std::string resolved = network_utils::resolve_hostname(host);
+    if (resolved.empty()) resolved = network_utils::resolve_hostname_v6(host);
+    if (auto ip = IpAddress::parse(resolved)) return Address{*ip, port};
+    return std::nullopt;
+}
+Node*       node_of(rats_t handle)   { return as_handle(handle)->node.get(); }
+
+char* dup_string(const std::string& s) {
+    char* out = static_cast<char*>(std::malloc(s.size() + 1));
+    if (out) std::memcpy(out, s.c_str(), s.size() + 1);
+    return out;
+}
+
+} // namespace
+
+extern "C" {
+
+const char* rats_error_str(rats_error_t err) {
+    switch (err) {
+        case RATS_OK:                  return "RATS_OK";
+        case RATS_ERR_INVALID_ARG:     return "RATS_ERR_INVALID_ARG";
+        case RATS_ERR_NOT_STARTED:     return "RATS_ERR_NOT_STARTED";
+        case RATS_ERR_ALREADY_STARTED: return "RATS_ERR_ALREADY_STARTED";
+        case RATS_ERR_NOT_ENABLED:     return "RATS_ERR_NOT_ENABLED";
+        case RATS_ERR_NO_SUCH_PEER:    return "RATS_ERR_NO_SUCH_PEER";
+        case RATS_ERR_BIND:            return "RATS_ERR_BIND";
+        case RATS_ERR_INTERNAL:        return "RATS_ERR_INTERNAL";
+    }
+    return "RATS_ERR_UNKNOWN";
+}
+
+/* — construction / lifecycle — */
+
+rats_config_t rats_config_default(void) {
+    rats_config_t c;
+    c.listen_port      = 0;
+    c.enable_listen    = 1;
+    c.bind_address     = nullptr;
+    c.security         = RATS_SECURITY_NOISE;
+    c.data_dir         = nullptr;
+    c.protocol         = nullptr;
+    c.max_peers        = 0;
+    c.enable_tcp            = 1;
+    c.enable_udp            = 1;
+    c.preferred_transport   = RATS_TRANSPORT_UDP;
+    c.transport_fallback_ms = 1200;
+    return c;
+}
+
+rats_t rats_create_config(const rats_config_t* cfg) {
+    NodeConfig config;
+    if (cfg) {
+        config.listen_port   = cfg->listen_port;
+        config.enable_listen = cfg->enable_listen != 0;
+        if (cfg->bind_address)     config.bind_address     = cfg->bind_address;
+        config.security = (cfg->security == RATS_SECURITY_PLAINTEXT) ? NodeConfig::Security::Plaintext
+                                                                     : NodeConfig::Security::Noise;
+        if (cfg->data_dir)         config.data_dir         = cfg->data_dir;
+        if (cfg->protocol)         config.protocol         = cfg->protocol;
+        config.max_peers = cfg->max_peers;
+
+        // Neither transport enabled is not a configuration anyone means — it is a
+        // node that can neither dial nor accept, and it fails *silently*: with
+        // enable_listen set, start() refuses; without it, the node comes up and
+        // then simply never connects to anything. And it is precisely what the
+        // commonest way of filling this struct in C produces, because zeroed
+        // memory reads as "both off":
+        //
+        //     rats_config_t cfg = {0};      // or a partial designated initialiser
+        //     cfg.listen_port = 9000;
+        //
+        // That worked before these two fields existed, so treating 0/0 as "both"
+        // is what keeps it working. Anyone who really wants one transport says so
+        // by enabling the other.
+        const bool any_transport = cfg->enable_tcp != 0 || cfg->enable_udp != 0;
+        config.enable_tcp = any_transport ? (cfg->enable_tcp != 0) : true;
+        config.enable_udp = any_transport ? (cfg->enable_udp != 0) : true;
+        config.preferred_transport = (cfg->preferred_transport == RATS_TRANSPORT_TCP)
+                                         ? TransportKind::Tcp
+                                         : TransportKind::Udp;
+        config.transport_fallback_ms = cfg->transport_fallback_ms;
+    }
+    return make_handle(std::move(config));
+}
+
+rats_t rats_create(uint16_t listen_port) {
+    NodeConfig config;
+    config.listen_port = listen_port;
+    return make_handle(std::move(config));
+}
+
+rats_t rats_create_ex(uint16_t listen_port, int enable_listen,
+                      const char* bind_address, rats_security_t security) {
+    NodeConfig config;
+    config.listen_port = listen_port;
+    config.enable_listen = enable_listen != 0;
+    if (bind_address) config.bind_address = bind_address;
+    config.security = (security == RATS_SECURITY_PLAINTEXT) ? NodeConfig::Security::Plaintext
+                                                            : NodeConfig::Security::Noise;
+    return make_handle(std::move(config));
+}
+
+void rats_destroy(rats_t node) { delete as_handle(node); }
+
+rats_error_t rats_start(rats_t node) {
+    auto* h = as_handle(node);
+    if (h->started) return RATS_ERR_ALREADY_STARTED;
+    if (!h->node->start()) return RATS_ERR_BIND;
+    h->started = true;
+    return RATS_OK;
+}
+
+void rats_stop(rats_t node) {
+    auto* h = as_handle(node);
+    h->node->stop();
+    h->started = false;   // allow a subsequent rats_start() to bind again
+}
+
+uint16_t rats_listen_port(rats_t node) { return node_of(node)->listen_port(); }
+
+uint32_t rats_transports(rats_t node) { return node_of(node)->transports(); }
+
+char* rats_local_id(rats_t node) { return dup_string(node_of(node)->local_id().to_hex()); }
+
+/* — connections — */
+
+rats_error_t rats_connect(rats_t node, const char* host, uint16_t port) {
+    if (!host) return RATS_ERR_INVALID_ARG;
+    node_of(node)->connect(std::string(host), port);
+    return RATS_OK;
+}
+
+size_t rats_peer_count(rats_t node) { return node_of(node)->peer_count(); }
+
+void rats_set_max_peers(rats_t node, size_t max_peers) {
+    node_of(node)->set_max_peers(max_peers);
+}
+
+size_t rats_max_peers(rats_t node) { return node_of(node)->max_peers(); }
+
+/* — messaging — */
+
+rats_error_t rats_send(rats_t node, const char* peer_id_hex,
+                       const char* channel, const void* data, size_t len) {
+    if (!peer_id_hex || !channel) return RATS_ERR_INVALID_ARG;
+    auto id = PeerId::from_hex(peer_id_hex);
+    if (!id) return RATS_ERR_INVALID_ARG;
+    if (!node_of(node)->peer(*id)) return RATS_ERR_NO_SUCH_PEER;
+    node_of(node)->send(*id, channel, ByteView(static_cast<const uint8_t*>(data), len));
+    return RATS_OK;
+}
+
+rats_error_t rats_broadcast(rats_t node, const char* channel, const void* data, size_t len) {
+    if (!channel) return RATS_ERR_INVALID_ARG;
+    node_of(node)->broadcast(channel, ByteView(static_cast<const uint8_t*>(data), len));
+    return RATS_OK;
+}
+
+rats_error_t rats_on_peer_connected(rats_t node, rats_peer_cb cb, void* user) {
+    if (!cb) return RATS_ERR_INVALID_ARG;
+    node_of(node)->on_peer_connected([cb, user](const Peer& peer) {
+        cb(user, peer.id().to_hex().c_str());
+    });
+    return RATS_OK;
+}
+
+rats_error_t rats_on_peer_disconnected(rats_t node, rats_peer_cb cb, void* user) {
+    if (!cb) return RATS_ERR_INVALID_ARG;
+    node_of(node)->on_peer_disconnected([cb, user](const PeerId& id) {
+        cb(user, id.to_hex().c_str());
+    });
+    return RATS_OK;
+}
+
+rats_error_t rats_on(rats_t node, const char* channel, rats_message_cb cb, void* user) {
+    if (!channel || !cb) return RATS_ERR_INVALID_ARG;
+    node_of(node)->on(channel, [cb, user](const Peer& peer, ByteView data) {
+        cb(user, peer.id().to_hex().c_str(), data.data(), data.size());
+    });
+    return RATS_OK;
+}
+
+/* — discovery / NAT subsystems — */
+
+rats_error_t rats_enable_dht(rats_t node, uint16_t dht_port, const char* discovery_key) {
+    auto* h = as_handle(node);
+    if (h->started) return RATS_ERR_ALREADY_STARTED;
+    if (h->dht_enabled) return RATS_OK;
+    DhtDiscovery::Config config;
+    config.dht_port = dht_port;
+    config.data_dir = h->data_dir;  // co-locate routing tables with identity (else cwd)
+    if (discovery_key) config.discovery_key = discovery_key;
+    h->node->add_subsystem(std::make_unique<DhtDiscovery>(std::move(config)));
+    h->dht_enabled = true;
+    return RATS_OK;
+}
+
+rats_error_t rats_enable_mdns(rats_t node) {
+    auto* h = as_handle(node);
+    if (h->started) return RATS_ERR_ALREADY_STARTED;
+    if (h->mdns_enabled) return RATS_OK;
+    h->node->add_subsystem(std::make_unique<MdnsDiscovery>());
+    h->mdns_enabled = true;
+    return RATS_OK;
+}
+
+rats_error_t rats_enable_port_mapping(rats_t node, int enable_upnp, int enable_natpmp) {
+    auto* h = as_handle(node);
+    if (h->started) return RATS_ERR_ALREADY_STARTED;
+    if (h->portmap_enabled) return RATS_OK;
+    PortMappingConfig config;
+    config.enable_upnp   = enable_upnp != 0;
+    config.enable_natpmp = enable_natpmp != 0;
+    h->node->add_subsystem(std::make_unique<PortMappingService>(config));
+    h->portmap_enabled = true;
+    return RATS_OK;
+}
+
+rats_error_t rats_enable_hole_punch(rats_t node, int serve_as_relay) {
+    auto* h = as_handle(node);
+    if (h->started) return RATS_ERR_ALREADY_STARTED;
+    if (!h->punch) {
+        HolePunch::Config config;
+        config.enable_relay = serve_as_relay != 0;
+        h->punch = h->node->add_subsystem(std::make_unique<HolePunch>(config));
+    }
+    return RATS_OK;
+}
+
+rats_error_t rats_enable_relay(rats_t node, int serve_as_relay) {
+    auto* h = as_handle(node);
+    if (h->started) return RATS_ERR_ALREADY_STARTED;
+    if (!h->relay) {
+        Relay::Config config;
+        config.serve = serve_as_relay != 0;
+        h->relay = h->node->add_subsystem(std::make_unique<Relay>(config));
+    }
+    return RATS_OK;
+}
+
+rats_error_t rats_connect_via_relay(rats_t node, const char* peer_id_hex) {
+    if (!peer_id_hex) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->relay) return RATS_ERR_NOT_ENABLED;
+    auto id = PeerId::from_hex(peer_id_hex);
+    if (!id) return RATS_ERR_INVALID_ARG;
+    // As with punching, every reason an attempt is declined is "nothing to do or
+    // nothing to try with" — already connected, already trying, in cooldown, or no
+    // peer that could carry it — and none of them is separately actionable.
+    return h->relay->connect_via_relay(*id) ? RATS_OK : RATS_ERR_NO_SUCH_PEER;
+}
+
+rats_error_t rats_punch_peer(rats_t node, const char* peer_id_hex) {
+    if (!peer_id_hex) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->punch) return RATS_ERR_NOT_ENABLED;
+    auto id = PeerId::from_hex(peer_id_hex);
+    if (!id) return RATS_ERR_INVALID_ARG;
+    // Every reason a punch is declined is "there is nothing to do or nothing to try
+    // with" — already connected, already punching, in cooldown, or no external
+    // endpoint learned yet. None of them is an error the caller can act on
+    // differently, so they collapse into one answer.
+    return h->punch->punch(*id) ? RATS_OK : RATS_ERR_NO_SUCH_PEER;
+}
+
+int rats_nat_mapping(rats_t node) {
+    switch (node_of(node)->nat_status().udp_mapping()) {
+        case NatMapping::Open:                return RATS_NAT_OPEN;
+        case NatMapping::EndpointIndependent: return RATS_NAT_ENDPOINT_INDEPENDENT;
+        case NatMapping::EndpointDependent:   return RATS_NAT_ENDPOINT_DEPENDENT;
+        case NatMapping::Unknown:             break;
+    }
+    return RATS_NAT_UNKNOWN;
+}
+
+/* — peer enumeration — */
+
+char** rats_peer_ids(rats_t node, size_t* count) {
+    auto infos = node_of(node)->peers();
+    if (count) *count = infos.size();
+    if (infos.empty()) return nullptr;
+    char** ids = static_cast<char**>(std::malloc(infos.size() * sizeof(char*)));
+    if (!ids) { if (count) *count = 0; return nullptr; }
+    for (size_t i = 0; i < infos.size(); ++i) ids[i] = dup_string(infos[i].id.to_hex());
+    return ids;
+}
+
+int rats_peer_transport(rats_t node, const char* peer_id_hex) {
+    if (!peer_id_hex) return -1;
+    auto id = PeerId::from_hex(peer_id_hex);
+    if (!id) return -1;
+    for (const PeerInfo& info : node_of(node)->peers()) {
+        if (info.id != *id) continue;
+        switch (info.transport) {
+            case TransportKind::Udp:   return RATS_TRANSPORT_UDP;
+            case TransportKind::Relay: return RATS_TRANSPORT_RELAY;
+            case TransportKind::Tcp:   break;
+        }
+        return RATS_TRANSPORT_TCP;
+    }
+    return -1;
+}
+
+int rats_peer_transports(rats_t node, const char* peer_id_hex) {
+    if (!peer_id_hex) return -1;
+    auto id = PeerId::from_hex(peer_id_hex);
+    if (!id) return -1;
+    for (const PeerInfo& info : node_of(node)->peers())
+        if (info.id == *id) return static_cast<int>(info.supported_transports);
+    return -1;
+}
+
+void rats_free_peer_ids(char** ids, size_t count) {
+    if (!ids) return;
+    for (size_t i = 0; i < count; ++i) std::free(ids[i]);
+    std::free(ids);
+}
+
+/* — pub/sub — */
+
+rats_error_t rats_enable_pubsub(rats_t node) {
+    auto* h = as_handle(node);
+    if (h->started) return RATS_ERR_ALREADY_STARTED;
+    if (!h->pubsub) h->pubsub = h->node->add_subsystem(std::make_unique<PubSub>());
+    return RATS_OK;
+}
+
+rats_error_t rats_subscribe(rats_t node, const char* topic, rats_topic_cb cb, void* user) {
+    if (!topic || !cb) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->pubsub) return RATS_ERR_NOT_ENABLED;
+    h->pubsub->subscribe(topic,
+        [cb, user](const PeerId& from, const std::string& t, ByteView data) {
+            cb(user, from.to_hex().c_str(), t.c_str(), data.data(), data.size());
+        });
+    return RATS_OK;
+}
+
+rats_error_t rats_unsubscribe(rats_t node, const char* topic) {
+    if (!topic) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->pubsub) return RATS_ERR_NOT_ENABLED;
+    h->pubsub->unsubscribe(topic);
+    return RATS_OK;
+}
+
+rats_error_t rats_publish(rats_t node, const char* topic, const void* data, size_t len) {
+    if (!topic) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->pubsub) return RATS_ERR_NOT_ENABLED;
+    h->pubsub->publish(topic, ByteView(static_cast<const uint8_t*>(data), len));
+    return RATS_OK;
+}
+
+/* — typed JSON messaging — */
+
+rats_error_t rats_enable_json(rats_t node) {
+    auto* h = as_handle(node);
+    if (h->started) return RATS_ERR_ALREADY_STARTED;
+    if (!h->messages) h->messages = h->node->add_subsystem(std::make_unique<MessageJson>());
+    return RATS_OK;
+}
+
+rats_error_t rats_on_json(rats_t node, const char* type, rats_json_cb cb, void* user) {
+    if (!type || !cb) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->messages) return RATS_ERR_NOT_ENABLED;
+    h->messages->on(type, [cb, user](const PeerId& from, const librats::Json& data) {
+        cb(user, from.to_hex().c_str(), data.dump().c_str());
+    });
+    return RATS_OK;
+}
+
+rats_error_t rats_once_json(rats_t node, const char* type, rats_json_cb cb, void* user) {
+    if (!type || !cb) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->messages) return RATS_ERR_NOT_ENABLED;
+    h->messages->once(type, [cb, user](const PeerId& from, const librats::Json& data) {
+        cb(user, from.to_hex().c_str(), data.dump().c_str());
+    });
+    return RATS_OK;
+}
+
+rats_error_t rats_off_json(rats_t node, const char* type) {
+    if (!type) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->messages) return RATS_ERR_NOT_ENABLED;
+    h->messages->off(type);
+    return RATS_OK;
+}
+
+rats_error_t rats_send_json(rats_t node, const char* peer_id_hex, const char* type, const char* json) {
+    if (!peer_id_hex || !type || !json) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->messages) return RATS_ERR_NOT_ENABLED;
+    auto id = PeerId::from_hex(peer_id_hex);
+    if (!id) return RATS_ERR_INVALID_ARG;
+    auto j = librats::Json::parse(json, nullptr, /*allow_exceptions=*/false);
+    if (j.is_discarded()) return RATS_ERR_INVALID_ARG;
+    if (!h->node->peer(*id)) return RATS_ERR_NO_SUCH_PEER;
+    h->messages->send(*id, type, j);
+    return RATS_OK;
+}
+
+rats_error_t rats_broadcast_json(rats_t node, const char* type, const char* json) {
+    if (!type || !json) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->messages) return RATS_ERR_NOT_ENABLED;
+    auto j = librats::Json::parse(json, nullptr, /*allow_exceptions=*/false);
+    if (j.is_discarded()) return RATS_ERR_INVALID_ARG;
+    h->messages->send(type, j);
+    return RATS_OK;
+}
+
+/* — file transfer — */
+
+rats_error_t rats_enable_file_transfer(rats_t node, const char* temp_dir) {
+    auto* h = as_handle(node);
+    if (h->started) return RATS_ERR_ALREADY_STARTED;
+    if (!h->files)
+        h->files = h->node->add_subsystem(std::make_unique<FileTransfer>(temp_dir ? temp_dir : "."));
+    return RATS_OK;
+}
+
+rats_error_t rats_on_file_offer(rats_t node, rats_file_offer_cb cb, void* user) {
+    if (!cb) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->files) return RATS_ERR_NOT_ENABLED;
+    h->files->on_offer([cb, user](const FileTransfer::Offer& o) {
+        cb(user, o.from.to_hex().c_str(), o.id, o.name.c_str(), o.size, o.is_directory ? 1 : 0);
+    });
+    return RATS_OK;
+}
+
+rats_error_t rats_on_file_progress(rats_t node, rats_file_progress_cb cb, void* user) {
+    if (!cb) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->files) return RATS_ERR_NOT_ENABLED;
+    h->files->on_progress([cb, user](const FileTransfer::Progress& p) {
+        cb(user, p.id, p.peer.to_hex().c_str(), p.bytes_transferred, p.total_bytes,
+           static_cast<int>(p.status));
+    });
+    return RATS_OK;
+}
+
+rats_error_t rats_on_file_complete(rats_t node, rats_file_complete_cb cb, void* user) {
+    if (!cb) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->files) return RATS_ERR_NOT_ENABLED;
+    h->files->on_complete([cb, user](uint64_t id, bool success, const std::string& path) {
+        cb(user, id, success ? 1 : 0, path.c_str());
+    });
+    return RATS_OK;
+}
+
+uint64_t rats_send_file(rats_t node, const char* peer_id_hex, const char* path) {
+    if (!peer_id_hex || !path) return 0;
+    auto* h = as_handle(node);
+    if (!h->files) return 0;
+    auto id = PeerId::from_hex(peer_id_hex);
+    if (!id) return 0;
+    return h->files->send_file(*id, path);
+}
+
+uint64_t rats_send_directory(rats_t node, const char* peer_id_hex, const char* dir_path) {
+    if (!peer_id_hex || !dir_path) return 0;
+    auto* h = as_handle(node);
+    if (!h->files) return 0;
+    auto id = PeerId::from_hex(peer_id_hex);
+    if (!id) return 0;
+    return h->files->send_directory(*id, dir_path);
+}
+
+rats_error_t rats_accept_file(rats_t node, const char* peer_id_hex, uint64_t transfer_id,
+                              const char* dest_path) {
+    if (!peer_id_hex || !dest_path) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->files) return RATS_ERR_NOT_ENABLED;
+    auto id = PeerId::from_hex(peer_id_hex);
+    if (!id) return RATS_ERR_INVALID_ARG;
+    h->files->accept(*id, transfer_id, dest_path);
+    return RATS_OK;
+}
+
+rats_error_t rats_reject_file(rats_t node, const char* peer_id_hex, uint64_t transfer_id) {
+    if (!peer_id_hex) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->files) return RATS_ERR_NOT_ENABLED;
+    auto id = PeerId::from_hex(peer_id_hex);
+    if (!id) return RATS_ERR_INVALID_ARG;
+    h->files->reject(*id, transfer_id);
+    return RATS_OK;
+}
+
+rats_error_t rats_cancel_file(rats_t node, const char* peer_id_hex, uint64_t transfer_id) {
+    if (!peer_id_hex) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->files) return RATS_ERR_NOT_ENABLED;
+    auto id = PeerId::from_hex(peer_id_hex);
+    if (!id) return RATS_ERR_INVALID_ARG;
+    return h->files->cancel(*id, transfer_id) ? RATS_OK : RATS_ERR_NO_SUCH_PEER;
+}
+
+rats_error_t rats_pause_file(rats_t node, const char* peer_id_hex, uint64_t transfer_id) {
+    if (!peer_id_hex) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->files) return RATS_ERR_NOT_ENABLED;
+    auto id = PeerId::from_hex(peer_id_hex);
+    if (!id) return RATS_ERR_INVALID_ARG;
+    return h->files->pause(*id, transfer_id) ? RATS_OK : RATS_ERR_NO_SUCH_PEER;
+}
+
+rats_error_t rats_resume_file(rats_t node, const char* peer_id_hex, uint64_t transfer_id) {
+    if (!peer_id_hex) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->files) return RATS_ERR_NOT_ENABLED;
+    auto id = PeerId::from_hex(peer_id_hex);
+    if (!id) return RATS_ERR_INVALID_ARG;
+    return h->files->resume(*id, transfer_id) ? RATS_OK : RATS_ERR_NO_SUCH_PEER;
+}
+
+/* — liveness — */
+
+rats_error_t rats_enable_ping(rats_t node) {
+    auto* h = as_handle(node);
+    if (h->started) return RATS_ERR_ALREADY_STARTED;
+    if (!h->ping) h->ping = h->node->add_subsystem(std::make_unique<PingService>());
+    return RATS_OK;
+}
+
+int64_t rats_peer_rtt_ms(rats_t node, const char* peer_id_hex) {
+    if (!peer_id_hex) return -1;
+    auto* p = as_handle(node)->ping;
+    if (!p) return -1;
+    auto id = PeerId::from_hex(peer_id_hex);
+    if (!id) return -1;
+    auto rtt = p->last_rtt(*id);
+    return rtt ? static_cast<int64_t>(rtt->count()) : -1;
+}
+
+/* — automatic reconnection — */
+
+rats_error_t rats_enable_reconnect(rats_t node) {
+    auto* h = as_handle(node);
+    if (h->started) return RATS_ERR_ALREADY_STARTED;
+    if (!h->reconnect) {
+        ReconnectionService::Config rc;
+        if (!h->data_dir.empty()) rc.store_path = h->data_dir + "/peers.json";
+        h->reconnect = h->node->add_subsystem(std::make_unique<ReconnectionService>(rc));
+    }
+    return RATS_OK;
+}
+
+/* — BitTorrent (only functional when built with RATS_SEARCH_FEATURES) — */
+
+rats_error_t rats_enable_bittorrent(rats_t node, uint16_t listen_port, const char* download_path) {
+#ifdef RATS_SEARCH_FEATURES
+    auto* h = as_handle(node);
+    if (h->started) return RATS_ERR_ALREADY_STARTED;
+    if (!h->bittorrent) {
+        Bittorrent::Config cfg;
+        cfg.client.listen_port   = listen_port;
+        cfg.client.download_path = download_path ? download_path : ".";
+        h->bittorrent = h->node->add_subsystem(std::make_unique<Bittorrent>(cfg));
+    }
+    return RATS_OK;
+#else
+    (void)node; (void)listen_port; (void)download_path;
+    return RATS_ERR_NOT_ENABLED;
+#endif
+}
+
+rats_error_t rats_bt_add_magnet(rats_t node, const char* magnet_uri, const char* save_path) {
+#ifdef RATS_SEARCH_FEATURES
+    if (!magnet_uri) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->bittorrent || !h->bittorrent->is_running()) return RATS_ERR_NOT_ENABLED;
+    auto* c = h->bittorrent->client();
+    // Mutating the client must happen on its reactor thread.
+    c->reactor().post([c, uri = std::string(magnet_uri),
+                       sp = std::string(save_path ? save_path : "")] { c->add_magnet(uri, sp); });
+    return RATS_OK;
+#else
+    (void)node; (void)magnet_uri; (void)save_path;
+    return RATS_ERR_NOT_ENABLED;
+#endif
+}
+
+rats_error_t rats_bt_add_torrent_file(rats_t node, const char* torrent_path, const char* save_path) {
+#ifdef RATS_SEARCH_FEATURES
+    if (!torrent_path) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->bittorrent || !h->bittorrent->is_running()) return RATS_ERR_NOT_ENABLED;
+    auto info = bittorrent::TorrentInfo::from_file(torrent_path);
+    if (!info) return RATS_ERR_INVALID_ARG;
+    auto* c = h->bittorrent->client();
+    c->reactor().post([c, info = *info, sp = std::string(save_path ? save_path : "")] {
+        c->add_torrent(info, sp);
+    });
+    return RATS_OK;
+#else
+    (void)node; (void)torrent_path; (void)save_path;
+    return RATS_ERR_NOT_ENABLED;
+#endif
+}
+
+rats_error_t rats_bt_remove_torrent(rats_t node, const char* info_hash_hex) {
+#ifdef RATS_SEARCH_FEATURES
+    if (!info_hash_hex) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->bittorrent || !h->bittorrent->is_running()) return RATS_ERR_NOT_ENABLED;
+    auto ih = bittorrent::info_hash_from_hex(info_hash_hex);
+    if (!ih) return RATS_ERR_INVALID_ARG;
+    auto* c = h->bittorrent->client();
+    c->reactor().post([c, ih = *ih] { c->remove_torrent(ih); });
+    return RATS_OK;
+#else
+    (void)node; (void)info_hash_hex;
+    return RATS_ERR_NOT_ENABLED;
+#endif
+}
+
+rats_error_t rats_add_reconnect(rats_t node, const char* host, uint16_t port) {
+    if (!host) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->reconnect) return RATS_ERR_NOT_ENABLED;
+    const auto target = resolve_target(host, port);
+    if (!target) return RATS_ERR_INVALID_ARG;  // not a valid literal, and did not resolve
+    h->reconnect->add(*target);
+    return RATS_OK;
+}
+
+rats_error_t rats_remove_reconnect(rats_t node, const char* host, uint16_t port) {
+    if (!host) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->reconnect) return RATS_ERR_NOT_ENABLED;
+    const auto target = resolve_target(host, port);
+    if (!target) return RATS_ERR_INVALID_ARG;
+    h->reconnect->remove(*target);
+    return RATS_OK;
+}
+
+/* — logging — */
+
+void rats_set_log_level(rats_log_level_t level) {
+    Logger::getInstance().set_log_level(static_cast<LogLevel>(level));
+}
+
+void rats_set_log_file(const char* path) {
+    auto& logger = Logger::getInstance();
+    if (path && path[0] != '\0') {
+        logger.set_log_file_path(path);
+        logger.set_file_logging_enabled(true);
+    } else {
+        logger.set_file_logging_enabled(false);
+    }
+}
+
+/* — protocol identity (node-scoped) — */
+
+char* rats_protocol(rats_t node) {
+    return dup_string(node_of(node)->protocol());
+}
+
+/* — library info (process-global) — */
+
+const char* rats_version_string(void) { return version::STRING; }
+
+void rats_version(int* major, int* minor, int* patch, int* build) {
+    if (major) *major = version::MAJOR;
+    if (minor) *minor = version::MINOR;
+    if (patch) *patch = version::PATCH;
+    if (build) *build = version::BUILD;
+}
+
+const char* rats_git_describe(void) { return version::GIT_DESCRIBE; }
+
+uint32_t rats_abi(void) {
+    return (static_cast<uint32_t>(version::MAJOR) << 16) |
+           (static_cast<uint32_t>(version::MINOR) << 8) |
+           (static_cast<uint32_t>(version::PATCH));
+}
+
+/* — utility — */
+
+void rats_string_free(char* str) { std::free(str); }
+
+} // extern "C"