Skip to content
libratsPublic

About

librats: High-performance, lightweight P2P native library for big networks

Topics

Resources

Contributing

Stars

169 stars

Watchers

9 watching

Forks

Latest commit

Β 

History

955 Commits

Folders and files

Repository files navigation

πŸ€ librats

MIT License C++17 Build Status Release npm vcpkg Conan Center

A high-performance, lightweight peer-to-peer networking library with C++, C, Node.js, Java, Python, React Native, Android, and iOS support

librats is a modern P2P networking library written in C++17, with bindings for C, Node.js, Java, Python, React Native, and Android, plus an iOS build of the core. It's designed to be fast and light enough for low-power and embedded devices, while staying simple to build on: you start with a tiny core and add exactly the features you need β€” nothing more.

Official Website: https://librats.com

Used By

Projects and companies building on librats:

rats-search Β Β  uvnc Β Β  rasync

Using librats in production? Open a PR to add your logo here.

✨ Key Features

Core

  • Native C++17 implementation for maximum performance
  • Cross-platform support (Windows, Linux, macOS, Android, iOS)
  • Shared-nothing reactor transport β€” connections are sharded across reactor threads with no cross-thread locking on the hot path
  • TCP and UDP as equals β€” the same encrypted messages over either wire. The UDP transport is QUIC-shaped on Noise (packets sealed one by one, a stream per traffic lane so a loss in one holds up nothing in another, ACK ranges, RACK, BBRv3, flow control) on one socket shared by all peers, which is what keeps a single NAT mapping open and makes hole punching possible. A dial tries UDP first and races TCP as fallback, so a UDP-hostile network still connects
  • Self-certifying identity: every node has a Curve25519 keypair; its PeerId is its public key, so peers authenticate each other with no PKI or central authority
  • Stable identity persistence: point a node at a data_dir and its keypair (and therefore its PeerId) survives restarts
  • Composable subsystems: opt-in plugins attached to a Node; a bare node neither discovers peers nor reconnects on its own

Discovery & Networking

  • DHT Discovery: peer discovery over a Kademlia DHT, fully compatible with the BitTorrent Mainline DHT β€” the largest distributed hash table in the world, with millions of active nodes (IPv4 + IPv6 / BEP 32)
  • mDNS Discovery: automatic local-network peer discovery with service advertisement
  • IPv4/IPv6 Dual Stack: binds dual-stack by default, so a single node accepts both IPv4 and IPv6 peers
  • Peer Exchange (PEX): peers gossip known addresses to grow the mesh
  • Automatic Reconnection: re-dials dropped peers with exponential backoff; targets persist to disk when a data_dir is set; a peer whose link was lost (not closed) is dialed again where it was last known, for as long as asked
  • Network-change awareness: an optional monitor detects interface/route changes and notifies subsystems so they can re-announce and renew port mappings

Pub/Sub (GossipSub)

  • Scalable publish-subscribe with mesh networking
  • Topic-based communication with per-topic subscriptions
  • Message validation: configurable per-topic validators to accept/reject/ignore messages

I/O Multiplexing

  • Platform-optimal polling behind one abstraction:
    • Linux β€” epoll (O(1) per event)
    • macOS/BSD β€” kqueue (O(1) per event)
    • Windows β€” IOCP (true async completion, O(1) per event)

File Transfer

  • Streaming transfers: files streamed in order over the reliable peer connection β€” bounded memory regardless of file size
  • Directory transfer: whole directory trees sent recursively as one transfer
  • Backpressure: windowed flow control keeps the sender from outrunning the receiver
  • Integrity: per-chunk CRC32 plus a whole-file SHA-256 verified before delivery
  • Atomic delivery: data lands in a temp file and is renamed to its destination only after verification
  • Transfer control: pause, resume, and cancel from either side, with real-time progress callbacks
  • Offer/Accept model: incoming transfers are offered to the application, which accepts (with a destination) or rejects

Security

  • Noise Protocol encryption (Noise_XX): Curve25519 key exchange + ChaCha20-Poly1305 AEAD on every connection by default
  • Mutual authentication: both peers prove possession of the private key behind their PeerId
  • Perfect forward secrecy: per-session ephemeral keys
  • Protocol binding: your app's protocol id (e.g. "myapp/1.0") is bound into the handshake prologue, so nodes from different apps cryptographically cannot cross-connect
  • Plaintext option: select Security::Plaintext for local debugging or trusted networks

NAT Traversal

  • Automatic port forwarding: built-in UPnP IGD and NAT-PMP β€” the PortMappingService asks the router to forward the listen port (for TCP and UDP, which share it) on startup (both backends run in parallel; whichever the router supports wins), so peers behind a NAT can accept inbound connections with zero manual configuration. Mappings are refreshed automatically and removed on stop().
  • UDP hole punching: when no port forwarding is possible, HolePunch reaches a peer behind a NAT by arranging β€” through a peer both sides already have β€” that the two dial each other at the same instant, so each side's outbound packet opens the mapping the other's needs. The rendezvous is timed from the round trip itself (no clock synchronisation), and the node learns the external endpoint to advertise from its own mesh rather than from a STUN server
  • Relaying: for the pairs a punch cannot reach β€” a symmetric NAT, a network that drops UDP and blocks inbound TCP β€” Relay carries the connection itself through a node both ends already reach. It is a byte stream that is relayed, so the Noise handshake still runs end to end and the relay moves ciphertext it cannot read; a circuit that comes up then tries to upgrade itself to a direct link, and the swap costs the application nothing
  • NAT awareness: several peers' independent views of the node's shared UDP socket say whether its mapping is stable enough to punch through at all (endpoint-independent) or per-destination (symmetric, where punching cannot work) β€” see node.nat_status()
  • STUN: public-IP discovery used by the DHT (BEP-42 node-id derivation and external-address reporting)

Distributed Storage (optional, requires RATS_STORAGE)

  • Key-value storage: typed string / int64 / double / binary / JSON values
  • Automatic P2P synchronization across connected peers via GossipSub
  • Last-Write-Wins (LWW) conflict resolution based on timestamps
  • Disk persistence with an efficient binary format
  • Change notifications for local and remote updates

Multi-Language Support

  • Native C++17: core implementation with the full feature set
  • C API (bindings/rats.h): clean opaque-pointer C ABI β€” the foundation for all FFI bindings
  • Node.js: N-API native addon (RatsNode) with TypeScript definitions (npm package)
  • Java/Android: JNI wrapper with a high-level Java API (com.librats.RatsNode)
  • Python: ctypes package with a Pythonic RatsNode
  • React Native: react-native/, a Nitro Modules HybridObject written once in C++ and shared by iOS and Android. Messaging, peer events, file transfer and pub/sub
  • iOS: ios/, the core built as an XCFramework; Swift imports the C ABI directly with import LibRats

πŸš€ Quick Start

One idea runs through the whole library: a small core (Node) plus opt-in subsystems. A bare Node is the secure transport, manual dialing and raw channel messaging. Everything else is a Subsystem you add before start().

librats::NodeConfig config;
config.listen_port = 8080;
librats::Node node(config);

// attach only the capabilities you need
node.add_subsystem(std::make_unique<librats::PubSub>());
node.add_subsystem(std::make_unique<librats::DhtDiscovery>(dht_config));

node.start();

Two transports, one API

A connection runs over TCP or UDP, and nothing above the transport can tell the difference: same Noise handshake, same messages, same guarantees. UDP is not a lossy shortcut here β€” librats runs its own QUIC-shaped protocol on datagrams: the Noise handshake travels in the dial's first packets (so a UDP dial is a round trip shorter than TCP's), every packet after it is sealed on its own under its packet number, with its header masked, and each traffic lane is a stream of its own, so a lost packet holds up only the lane it carried. Loss recovery is RFC 9002-style (ACK ranges, RACK with a reorder timer, probe timeouts), congestion control BBRv3 β€” Reno on request via NodeConfig::congestion_control β€” and flow control a window that auto-tunes from 1 MiB to NodeConfig::udp_receive_window, under one memory budget for every connection.

Both are enabled by default and bind the same port, so one advertised address is dialable either way. A dial tries UDP first and races TCP alongside it if UDP has not come up within transport_fallback_ms β€” the first handshake to complete wins and the other is dropped. The UDP wire carries a version (3 today): a peer on another one ignores the dial, and the two connect over TCP instead.

UDP is the default first choice because it fits peer-to-peer better: every peer shares one socket, so a NAT holds one mapping instead of one per peer; the source port a peer sees is the port it can dial back, which is what makes hole punching possible at all; and no middlebox holds per-connection state that can be exhausted or timed out. TCP remains a first-class equal, and is what the fallback exists for β€” some networks block or throttle UDP outright.

librats::NodeConfig config;
config.enable_tcp            = true;                          // both on by default
config.enable_udp            = true;
config.preferred_transport   = librats::TransportKind::Udp;   // tried first
config.transport_fallback_ms = 1200;                          // 0 = never fall back

librats::Node node(config);
node.start();

node.transports();                 // bitmask of what is actually running
node.peers()[0].transport;         // which wire this peer's link uses

The examples below use the C++ Node API. The equivalent C API (rats_*) is shown in the C API section.

1. Basic P2P connection

#include <librats/node/node.h>
#include <iostream>

using namespace librats;

int main() {
    NodeConfig config;
    config.listen_port = 8080;       // 0 = ephemeral
    config.bind_address = "::";      // dual-stack (IPv6 + IPv4-mapped); the default

    Node node(config);

    // Register events BEFORE start(). They run on a reactor thread.
    node.on_peer_connected([](const Peer& peer) {
        std::cout << "[+] peer connected: " << peer.id().short_hex() << "\n";
    });
    node.on("chat", [](const Peer& peer, ByteView data) {
        std::cout << peer.id().short_hex() << ": "
                  << std::string(reinterpret_cast<const char*>(data.data()), data.size()) << "\n";
    });

    if (!node.start()) {
        std::cerr << "failed to start node\n";
        return 1;
    }
    std::cout << "node " << node.local_id().short_hex()
              << " listening on " << node.listen_port() << "\n";

    // Dial another peer (non-blocking; connects asynchronously).
    node.connect("127.0.0.1", 8081);

    // Send raw bytes on a named channel to every connected peer.
    node.broadcast("chat", ByteView(std::string("Hello from librats!")));

    std::string line;
    while (std::getline(std::cin, line)) node.broadcast("chat", ByteView(line));

    node.stop();
    return 0;
}

2. Custom protocol & stable identity

NodeConfig config;
config.listen_port = 8080;
config.protocol = "my_app/1.0";       // bound into the handshake β€” only peers with
                                      // the same protocol id can connect
config.data_dir = "./node-data";      // persist identity.key β†’ stable PeerId across restarts

Node node(config);
node.start();

std::cout << "protocol: " << node.protocol() << "\n";
std::cout << "peer id:  " << node.local_id().to_hex() << "\n";

Two nodes whose protocol id differs cannot complete a handshake β€” a cheap, cryptographically-enforced way to keep separate apps (or app versions) from cross-connecting. The id is an opaque string compared for exact equality; by convention "<name>/<version>". See Private Network Formation.

3. Typed JSON messaging

Attach the MessageJson subsystem and reach it through node.json().

#include <librats/node/node.h>
#include <librats/subsystems/message_json.h>

Node node(NodeConfig{/*listen_port=*/8080});
node.add_subsystem(std::make_unique<MessageJson>());

// Handlers are additive and keyed by message type. `from` is the authenticated PeerId.
node.json()->on("chat", [](const PeerId& from, const librats::Json& data) {
    std::cout << "[chat] " << from.short_hex() << ": " << data.value("text", "") << "\n";
});

node.start();

// Broadcast / direct send.
node.json()->send("chat", librats::Json{{"text", "Hello, P2P chat!"}});
node.json()->send(some_peer_id, "chat", librats::Json{{"text", "private hi"}});

4. GossipSub publish-subscribe

#include <librats/node/node.h>
#include <librats/subsystems/pubsub.h>

Node node(NodeConfig{8080});
auto* pubsub = node.add_subsystem(std::make_unique<PubSub>());

pubsub->subscribe("news", [](const PeerId& from, const std::string& topic, ByteView data) {
    std::cout << "[" << topic << "] " << from.short_hex() << ": "
              << std::string(reinterpret_cast<const char*>(data.data()), data.size()) << "\n";
});

node.start();

pubsub->publish("news", ByteView(std::string("Breaking: librats is awesome!")));

std::cout << "subscribers in 'news': " << pubsub->peers_for_topic("news").size() << "\n";

5. File and directory transfer

#include <librats/node/node.h>
#include <librats/subsystems/file_transfer.h>

Node node(NodeConfig{8080});
auto* files = node.add_subsystem(std::make_unique<FileTransfer>("./downloads"));  // temp dir

// Incoming offers must be accepted (with a destination) or rejected.
files->on_offer([&](const FileTransfer::Offer& offer) {
    std::cout << "[file] offer from " << offer.from.short_hex() << ": " << offer.name
              << " (" << offer.size << " bytes)\n";
    if (offer.size < 100 * 1024 * 1024)
        files->accept(offer.from, offer.id, "./downloads/" + offer.name);
    else
        files->reject(offer.from, offer.id);
});
files->on_progress([](const FileTransfer::Progress& p) { /* p.bytes_transferred / p.total_bytes */ });
// Transfer ids are allocated by the sender, so a (peer, id) pair is the unique key.
files->on_complete([](const PeerId& peer, uint64_t id, bool ok, const std::string& path) {
    std::cout << "[file] transfer " << id << " from " << peer.short_hex()
              << (ok ? " complete: " : " FAILED: ") << path << "\n";
});

node.start();

// Push a file / directory to a connected peer (returns a transfer id, 0 on failure).
uint64_t id  = files->send_file(peer_id, "my_file.txt");
uint64_t dir = files->send_directory(peer_id, "./my_folder");
// Control either side: files->pause(peer, id) / resume(...) / cancel(...)

6. Security

Encryption is on by default β€” every connection runs Noise_XX (Curve25519 + ChaCha20-Poly1305) with mutual authentication. There is nothing to enable.

NodeConfig config;
config.listen_port = 8080;
config.security = NodeConfig::Security::Noise;   // default; Plaintext for trusted/debug nets
config.data_dir = "./node-data";                 // persist the Noise keypair β†’ stable PeerId

Node node(config);
node.start();
// node.local_id() is derived from the node's static public key; the handshake proves the peer holds the private key.

7. NAT traversal: port mapping, hole punching, relay

Three subsystems form a ladder. Each one exists for the networks the previous rung cannot reach, and they hand off to each other on their own.

Rung 1: port mapping. PortMappingService asks the router to forward the listen port on startup, over UPnP IGD and NAT-PMP in parallel. Both TCP and UDP are mapped, since both transports share one port. Mappings are refreshed automatically and removed on stop().

#include <librats/node/node.h>
#include <librats/subsystems/port_mapping_service.h>

Node node(NodeConfig{8080});
auto* portmap = node.add_subsystem(std::make_unique<PortMappingService>());
node.start();

// Public endpoint as seen from outside the NAT (if a mapping succeeded).
// Each protocol is mapped independently; a router may accept one and refuse the other.
if (auto pub = portmap->mapped_public_address(PortMapProtocol::TCP))
    std::cout << "public tcp: " << pub->first << ":" << pub->second << "\n";
if (auto pub = portmap->mapped_public_address(PortMapProtocol::UDP))
    std::cout << "public udp: " << pub->first << ":" << pub->second << "\n";

Rung 2: hole punching. Where the router forwards nothing (carrier-grade NAT, an office network, UPnP switched off), two peers that cannot be dialed can still reach each other if they dial at the same moment: each side's outbound packet opens the mapping the other side needs. HolePunch arranges that moment through a peer both already have and times it from the relayed round trip, so no clocks need to agree. The node learns the external endpoint to advertise from the peers it already has rather than from a STUN server.

#include <librats/node/node.h>
#include <librats/subsystems/hole_punch.h>

Node node(config);
auto* punch = node.add_subsystem(std::make_unique<HolePunch>());
node.start();

// ... once connected to at least one datagram peer (that is where the node
// learns the external endpoint to advertise) ...

// What the mesh says about our own side of the NAT.
switch (node.nat_status().udp_mapping()) {
    case NatMapping::Open:                break;  // directly dialable; no punch needed
    case NatMapping::EndpointIndependent: break;  // punchable
    case NatMapping::EndpointDependent:   break;  // symmetric NAT β€” a relay is the only way
    case NatMapping::Unknown:             break;  // not enough independent observations yet
}

punch->punch(peer_id);   // non-blocking; success arrives as an ordinary peer-connected event

Every node involved needs the subsystem, including the one carrying the rendezvous (it forwards a few dozen bytes per punch, only to peers it already holds). You rarely call punch() yourself: attach PeerExchange alongside and a PEX-learned peer whose address will not dial is punched automatically.

Rung 3: relay. A symmetric NAT gives a fresh mapping per destination, so no endpoint either side can advertise is the one the other's packets would arrive on. For those pairs Relay routes the connection itself through a node both ends already reach. What is relayed is a byte stream, so it becomes an ordinary Connection: the Noise handshake runs end to end and the relay moves ciphertext it cannot read or forge. Every subsystem works over a relayed peer unchanged; PeerInfo::transport is the only thing that says the path is not direct.

#include <librats/subsystems/relay.h>
#include <librats/subsystems/hole_punch.h>
#include <librats/subsystems/port_mapping_service.h>


Relay::Config relay_config;
relay_config.serve = true;   // ALSO carry other peers' connections; off by default

node.add_subsystem(std::make_unique<Relay>(relay_config));  // provides RelayService
node.add_subsystem(std::make_unique<HolePunch>());          // escalates to it on failure
node.add_subsystem(std::make_unique<PeerExchange>());       // resolves it, if present

Attach both and the ladder runs itself: a punch that cannot work hands the target to the relay, and a circuit that comes up keeps trying to punch over the very circuit carrying it. If a direct link lands, the peer table swaps the route at both ends with no disconnect event.

Serving as a relay is opt-in because it spends real bandwidth on somebody else's traffic. A serving node forwards only between peers it already holds (it never dials, so it cannot become an open reflector), refuses to chain circuits, bounds each circuit with an end-to-end credit window and caps it by bytes and duration. The C ABI mirrors the ladder as rats_enable_port_mapping(), rats_enable_hole_punch() / rats_punch_peer() / rats_nat_mapping() and rats_enable_relay() / rats_connect_via_relay(). See ARCHITECTURE.md for how the pieces fit.

8. Peer discovery (DHT + mDNS) and reconnection

#include <librats/node/node.h>
#include <librats/subsystems/dht_discovery.h>
#include <librats/subsystems/mdns_discovery.h>
#include <librats/subsystems/reconnection.h>

NodeConfig config;
config.listen_port = 8080;
config.data_dir = "./node-data";
Node node(config);

// Wide-area discovery via the BitTorrent Mainline DHT (IPv4 + IPv6).
DhtDiscovery::Config dc;
dc.data_dir = config.data_dir;          // co-locate the routing tables with identity + peers
node.add_subsystem(std::make_unique<DhtDiscovery>(std::move(dc)));

// Local-network discovery.
node.add_subsystem(std::make_unique<MdnsDiscovery>());

// Auto-reconnect dropped peers with exponential backoff; persist targets to disk.
ReconnectionService::Config rc;
rc.store_path = config.data_dir + "/peers.txt";
rc.max_attempts = 10;
rc.lost_for = std::chrono::minutes(2);   // a peer lost (not left) is dialed again this long
auto* reconnect = node.add_subsystem(std::make_unique<ReconnectionService>(rc));
reconnect->on_given_up([](const PeerId& id) { /* lost and not back */ });

node.start();
reconnect->add(Address{"203.0.113.7", 8080});   // keep this target connected

9. Liveness (RTT probing)

#include <librats/subsystems/ping_service.h>

auto* ping = node.add_subsystem(std::make_unique<PingService>());
node.start();
// ...later:
if (auto rtt = ping->last_rtt(peer_id))
    std::cout << "rtt = " << rtt->count() << "ms\n";

10. Live messages (video, audio, anything worth having only while fresh)

using namespace std::chrono_literals;
node.send(peer, "video", ByteView(frame), {150ms});   // live: worth delivering within 150 ms
node.broadcast("video", ByteView(frame), {150ms});
node.on("video", [](const Peer&, ByteView frame) { /* same handler as any message */ });

A message with a lifetime is repaired while the repair can still arrive in time and dropped β€” whole β€” once it cannot: it arrives in time or not at all, never in part or twice. It is ordered with nothing (number your frames), goes ahead of ordinary traffic, and is what keeps a stale backlog from standing in front of fresh frames after a loss burst or an outage. A source asking for more than the path carries loses whole frames, not every frame half sent: one that has not started and could no longer leave in time behind what is queued ahead of it is dropped before it costs anything. Over TCP the same call drops a message that expires before it is sealed. PathStats::live_sent / live_expired say how many the sender had to drop. To hear what became of one in particular, give it a tag: the sender is told the moment it is delivered (acknowledged; over TCP, written to the stream) or given up on β€” sooner than the receiver could say, and for one dropped before a byte of it left, the only word there is:

node.on_live_outcome(MessageType::App, [](const Peer& peer, uint64_t tag, bool delivered) {
    if (!delivered) { /* frame `tag` never reached `peer`: send it a keyframe */ }
});
SendOptions keyframe{150ms};
keyframe.tag = frame_number + 1;   // any nonzero value of the sender's
node.send(peer, "video", ByteView(frame), keyframe);

Live messages leave nearest deadline first β€” unless they are given ranks: a lower rank goes ahead of a higher one whatever their deadlines, so a call's sound need not wait behind a keyframe's few hundred packets, nor a keyframe behind the frames that depend on it:

SendOptions sound{100ms};                      // rank 0, the default: first
SendOptions picture{150ms};
picture.rank = keyframe ? 1 : 2;               // up to SendOptions::kLiveRanks - 1

From C: rats_send(node, peer, "video", data, len, 150); a lifetime of 0 is the ordinary reliable send. (Tags, their outcomes and ranks are C++ only for now.)

11. Distributed storage (requires RATS_STORAGE)

#include <librats/storage/storage.h>

auto* storage = node.add_subsystem(std::make_unique<StorageManager>());
node.start();

storage->put("greeting", "hello");   // replicated to connected peers (Last-Write-Wins)
if (auto v = storage->get_string("greeting")) std::cout << *v << "\n";

On connect the two sides exchange a full snapshot, streamed in bounded chunks paced against each link's send queue, so a database far larger than that queue syncs without the peer being dropped as a slow consumer. StorageConfig tunes the two sizes that matter β€” max_value_size (1 MiB) and sync_batch_bytes (256 KiB); both must stay under a quarter of NodeConfig::send_queue_limit, and both are clamped to that assumption for the default 8 MiB queue.

πŸ“– API Documentation

Node β€” the entry point

Node (in node/node.h) owns the reactor pool, the security provider, the peer directory and the message router. connect/send/broadcast are non-blocking and thread-safe; event callbacks run on a reactor thread, so register them before start().

// Construction
explicit Node(NodeConfig config);

// Lifecycle
bool start();                  // open listener + reactors + subsystems; false if bind fails
void stop();                   // stop subsystems (reverse order), close connections, join

// Identity & protocol
const PeerId&      local_id() const;          // our self-certifying id (derived from the public key)
uint16_t           listen_port() const;       // actual bound port (when config requested 0)
const std::string& protocol() const;          // app protocol id bound into the handshake
uint8_t            transports() const;        // bitmask of the transports actually running
const NatStatus&   nat_status() const;        // what peers report about our own NAT (see Β§7)

// Subsystems (attach BEFORE start(); the node owns them and returns a non-owning pointer)
template <class T> T* add_subsystem(std::unique_ptr<T> subsystem);
template <class T> T* subsystem();            // typed lookup, nullptr if not attached
MessageJson*          json();                 // shortcut for subsystem<MessageJson>()

// Connections
void   connect(const Address& address);
void   connect(const std::string& host, uint16_t port);
size_t peer_count() const;
std::vector<PeerInfo> peers() const;          // snapshot: id, addresses, direction, transport (direct or relayed)
std::optional<Peer>   peer(const PeerId& id);
std::vector<Address>  observed_addresses() const;  // our addresses as peers report them

// Peer admission limit (0 = unlimited; guards inbound, not our own dials)
size_t max_peers() const;
void   set_max_peers(size_t n);
bool   peer_limit_reached() const;

// Messaging (raw bytes on a named channel). The bool is backpressure: false means
// "queued, but stop and wait for on_peer_writable" β€” see Backpressure below.
// SendOptions{lifetime} makes a message live β€” see Live messages below.
bool send(const PeerId& to, std::string_view channel, ByteView payload, SendOptions options = {});
bool broadcast(std::string_view channel, ByteView payload, SendOptions options = {});
bool peer_writable(const PeerId& id) const;      // the same question, without sending
std::optional<PathStats> path_stats(const PeerId& id) const;  // latest path sample, any thread

// Events (additive; run on a reactor thread)
void on_peer_connected(PeerEventHandler cb);     // (const Peer&)
void on_peer_disconnected(PeerDisconnectHandler cb);  // (const PeerId&, CloseReason)
void on_peer_writable(PeerEventHandler cb);      // (const Peer&) β€” room again
void on_peer_rerouted(PeerEventHandler cb);      // (const Peer&) β€” moved to another link; say again what you said on connect
void on_peer_path(PeerPathHandler cb);           // (const Peer&, const PathStats&) β€” see Path statistics
void on_live_outcome(MessageType type, LiveOutcomeHandler cb);  // (const Peer&, tag, delivered) β€” see Live messages
void on_dial_failed(DialFailedHandler cb);       // (const Address&) β€” a connect() that never came up
void on(std::string_view channel, MessageRouter::Handler cb);  // (const Peer&, ByteView)

// Node-scoped coordination shared with subsystems
EventBus&        events();      // fire-and-forget, one→many (e.g. NetworkChanged)
ServiceRegistry& services();    // targeted capability lookup, one→one

Backpressure

Sending is non-blocking, so a peer that reads slower than you write is answered by its queue growing. Three things bound that, and they are the whole contract:

  • send() (and Peer::send()) returns whether there is still room. false means this message was queued like any other, nothing was dropped β€” but stop. It is the queue passing its low-water mark (a quarter of NodeConfig::send_queue_limit, so 2 MiB by default).
  • on_peer_writable says the room is back, and peer_writable() asks the same question without sending β€” for a caller that must wait on a thread of its own.
  • Keep sending regardless and the peer is dropped, with CloseReason::SlowConsumer handed to on_peer_disconnected so you can tell that apart from a peer that simply left. It takes offering another message while the queue is still over send_queue_limit; the mark is never charged against the message that crosses it, so a single message of any size is always queued β€” one large frame on a healthy connection is not a slow consumer. The only hard limit on one message is the 64 MiB wire block, past which send() refuses outright (returning false, connection untouched) because no amount of waiting would ever make it fit.

The same three are in the C ABI: rats_peer_writable(), rats_on_peer_writable(), and the rats_close_reason_t handed to rats_on_peer_disconnected().

Ordering and priority

A connection carries every subsystem's traffic at once, so it keeps one queue per lane β€” your application's messages are one lane, and each subsystem (gossip, file transfer, ping, …) is another. That sets the ordering guarantee:

  • Everything you send with send()/broadcast() arrives in the order you sent it, across all channels β€” a "done" on one channel sent after data on another arrives after that data.
  • Subsystem traffic is scheduled around it. A subsystem's own messages keep their order, but may overtake yours or fall behind them.

Which lane goes next is decided by priority, and within a priority by turns:

Priority Lanes
1 (first) the node's own control plane (identify)
2 ping, hole-punch rendezvous β€” small and timing-sensitive
3 your messages, gossip, typed messages, peer exchange, storage, relayed circuits
4 (last) file transfer

Lanes of the same priority take turns, one message each, so a subsystem with a deep backlog cannot starve your messages (or the other way round).

Over UDP the choice is made for every packet as it is built, and each lane is a stream of its own: a ping queued behind megabytes of file goes out in the next packet, and a lost piece of the file holds up only the file β€” the lanes are delivered independently at the far end too. Over TCP one byte stream carries them all: a message is encrypted only at the moment it is written, which is what keeps everything still queued free to be overtaken, and the socket holds no more than TCP_NOTSENT_LOWAT (128 KiB) unsent β€” so a ping there waits behind that much of a file, not behind the whole send buffer, but a loss on the path still holds up everything behind it.

Path statistics

Backpressure tells a sender it has outrun the link. A live sender β€” an encoder choosing a bitrate β€” needs to know before, and to size itself to the path rather than let the queue find the limit: for a frame with a deadline, waiting in a queue is losing. PathStats is what the transport knows about the path to one peer:

field
bandwidth_bps the congestion controller's estimate (BBR's model; a window per round trip for Reno; the kernel's delivery rate on TCP) β€” what to size a sender to
app_limited the sender was not filling the path, so the estimate is a floor (what was used), not the path's capacity β€” the normal state of a sender that keeps to it
queued_bytes accepted for the peer and not yet sent: what a new message waits behind. queued_bytes * 8 / bandwidth_bps is that wait in seconds
srtt_us, min_rtt_us smoothed and lowest round trip; their difference is the queue standing on the path
loss share of bytes lost over the last sampling interval
pacing_bps, bytes_in_flight, bytes_delivered, bytes_lost the rest of the sender's state

on_peer_path delivers a sample of every connected peer each NodeConfig::path_sample_ms (100 ms when 0) on a reactor thread, and registering it is what turns sampling on; path_stats() answers the latest sample from any thread. Sampling costs nothing when nobody asks. Over UDP the figures are the stream's own; over TCP they come from the kernel (TCP_INFO, Linux only). A TCP peer elsewhere, like one over a relayed byte stream, has no figures for the path itself: they stay 0, and its sample carries only queued_bytes and the live counters, which the sender keeps on every link. C ABI: rats_path_stats(), rats_on_peer_path(), rats_config_t::path_sample_ms. bench_path --realtime measures live video against a modelled path, with a source that steers by these figures and one that does not.

NodeConfig

struct NodeConfig {
    // Listening
    uint16_t    listen_port = 0;            // 0 = ephemeral; ignored if !enable_listen
    bool        enable_listen = true;       // false = dial-only (no listener)
    std::string bind_address = "";          // "" / "::" dual-stack, "0.0.0.0", or an IP literal

    // Transports (see "Two transports, one API")
    bool          enable_tcp = true;
    bool          enable_udp = true;
    TransportKind preferred_transport = TransportKind::Udp;  // tried first
    uint32_t      transport_fallback_ms = 1200;              // start the other one after this; 0 = never

    // Resources
    size_t      reactor_threads = 1;        // 1 handles thousands of peers; more shards cores
    size_t      max_peers = 0;              // 0 = unlimited (guards inbound only)
    size_t      send_queue_limit = 0;       // per-peer send queue before SlowConsumer; 0 = 8 MiB
    size_t      udp_receive_window = 0;     // ceiling one UDP connection's flow-control window grows to; 0 = 16 MiB
    size_t      udp_receive_budget = 0;     // out-of-order bytes all UDP connections may hold; 0 = 64 MiB
    std::chrono::milliseconds udp_idle_timeout{0};  // a silent peer's connection closed as lost; 0 = 45 s
    uint32_t    path_sample_ms = 0;         // path sampling period; 0 = only with on_peer_path (100 ms)

    // Identity & security
    enum class Security { Noise, Plaintext };
    Security    security = Security::Noise; // Noise_XX by default
    std::string protocol = "librats/1.0";   // app id bound into the handshake; must match to connect
    std::string data_dir = "";              // "" = ephemeral identity; else identity.key persists

    bool        enable_network_monitor = true;  // watch host network changes β†’ NetworkChanged
};

Subsystems

Each subsystem is attached with node.add_subsystem(std::make_unique<T>(...)) before start(). A bare node has none of these.

Subsystem Header What it adds
PubSub subsystems/pubsub.h GossipSub topics: subscribe / unsubscribe / publish, per-topic validators
MessageJson subsystems/message_json.h Typed JSON messaging: on / once / off / send; reached via node.json()
FileTransfer subsystems/file_transfer.h Push file/dir transfer: send_file / send_directory / accept / reject / pause / resume / cancel
DhtDiscovery subsystems/dht_discovery.h Wide-area discovery over the BitTorrent Mainline DHT (IPv4 + IPv6)
MdnsDiscovery subsystems/mdns_discovery.h Local-network discovery + advertisement
PingService subsystems/ping_service.h Periodic liveness ping/pong + last_rtt(id)
ReconnectionService subsystems/reconnection.h Auto-reconnect with exponential backoff; persistent targets
PortMappingService subsystems/port_mapping_service.h UPnP IGD + NAT-PMP automatic port forwarding
HolePunch subsystems/hole_punch.h UDP hole punching: two NATed peers dial each other at the same instant, arranged through a peer they share
Relay subsystems/relay.h Last-resort connectivity: the connection itself is carried through a peer both ends reach, still encrypted end to end
PeerExchange subsystems/peer_exchange.h PEX: gossip known peer addresses to grow the mesh
StorageManager storage/storage.h Distributed key-value store (requires RATS_STORAGE)
Bittorrent subsystems/bittorrent.h BitTorrent client sharing the node's DHT: magnets, .torrent files, uTP, MSE/PE (requires RATS_SEARCH_FEATURES; attach after DhtDiscovery)

C API (bindings/rats.h)

The C ABI every language binding is built on. A rats_t is an opaque handle to one node. rats_config_t is zero-initialisable β€” zero in any field is that field's default β€” so rats_create(NULL) or a designated initialiser naming only what you change is a complete config; a config no node could run with makes rats_create() return NULL. Fallible calls return rats_error_t (RATS_OK == 0). Subsystems are enabled with their rats_enable_*() before rats_start(), and node callbacks are registered before it too. Peer ids are 64-char hex; rats_local_id() and the other const char* results belong to the library, and the arrays from rats_peer_ids() / rats_observed_addresses() are freed with rats_strings_free().

#include <librats/bindings/rats.h>
#include <stdio.h>

static void on_connected(void* user, const char* peer_id) {
    printf("[+] connected: %s
", peer_id);
}
static void on_chat(void* user, const char* peer_id, const void* data, size_t len) {
    printf("%s: %.*s
", peer_id, (int)len, (const char*)data);
}

int main(void) {
    rats_config_t cfg = { .listen_port = 8080, .protocol = "chat/1.0" };
    rats_t node = rats_create(&cfg);
    if (!node) return 1;

    rats_on_peer_connected(node, on_connected, NULL);   /* before start */
    rats_on(node, "chat", on_chat, NULL);
    rats_enable_dht(node, 0, NULL);

    if (rats_start(node) != RATS_OK) return 1;

    rats_connect(node, "127.0.0.1", 8081);
    rats_broadcast(node, "chat", "hello", 5, 0);   /* lifetime 0: reliable */

    /* ... run ... */
    rats_destroy(node);   /* stops it first */
    return 0;
}
Area Calls
Lifecycle rats_create, rats_destroy, rats_start / rats_stop
This node rats_local_id, rats_protocol, rats_listen_port, rats_transports, rats_nat_mapping, rats_observed_addresses
Peers rats_connect, rats_disconnect, rats_peer_count, rats_peer_ids, rats_peer_info, rats_set_max_peers
Messaging rats_send / rats_broadcast (reliable or live), rats_peer_writable, rats_path_stats
Callbacks rats_on, rats_on_peer_connected / _disconnected / _writable / _path, rats_on_dial_failed
Discovery, NAT rats_enable_{dht,mdns,peer_exchange,port_mapping,hole_punch,relay}, rats_punch_peer, rats_connect_via_relay
Pub/sub, JSON rats_enable_pubsub, rats_subscribe / rats_publish; rats_enable_json, rats_on_json / rats_send_json / rats_broadcast_json
Files rats_enable_file_transfer, rats_on_file_{offer,progress,complete}, rats_send_file / rats_send_directory, rats_accept_file / rats_reject_file, rats_{cancel,pause,resume}_file
Ping, reconnect rats_enable_ping, rats_peer_rtt_ms; rats_enable_reconnect, rats_add_reconnect / rats_remove_reconnect
BitTorrent rats_enable_bittorrent, rats_bt_add_magnet / rats_bt_add_torrent_file / rats_bt_remove_torrent (RATS_SEARCH_FEATURES builds)

A library built on librats in C++ that offers a C API of its own attaches its subsystem to the caller's node with rats_attach_subsystem() (bindings/rats_extend.h, C++ only), before rats_start() and once per name; the node owns it from then on, and the caller keeps the rest of this API on the same node. | Process-wide | rats_set_log_level / rats_set_log_file, rats_version / rats_version_string / rats_abi, rats_error_str, rats_close_reason_str |

🏒 Architecture

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Application                                                        β”‚
β”‚   composes a Node + exactly the subsystems it needs               β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ Subsystems (opt-in plugins attached to a Node)                    β”‚
β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”       β”‚
β”‚ β”‚  PubSub    β”‚ β”‚ MessageJsonβ”‚ β”‚ FileTransferβ”‚ β”‚ Reconnect  β”‚      β”‚
β”‚ β”‚ (GossipSub)β”‚ β”‚ (typed JSON)β”‚ β”‚  (push)    β”‚ β”‚  Service   β”‚      β”‚
β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜       β”‚
β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”       β”‚
β”‚ β”‚ DhtDiscoveryβ”‚ β”‚MdnsDiscoveryβ”‚ β”‚PingService β”‚ β”‚PortMapping β”‚      β”‚
β”‚ β”‚  (Mainline)β”‚ β”‚  (local)   β”‚ β”‚ (liveness) β”‚ β”‚UPnP/NAT-PMP β”‚      β”‚
β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜       β”‚
β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”       β”‚
β”‚ β”‚ HolePunch  β”‚ β”‚   Relay    β”‚ β”‚PeerExchangeβ”‚ β”‚StorageMgr  β”‚       β”‚
β”‚ β”‚ (UDP punch)β”‚ β”‚ (circuits) β”‚ β”‚   (PEX)    β”‚ β”‚(RATS_STORAGE)β”‚     β”‚
β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜       β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ Node core                                                         β”‚
β”‚   peer directory Β· message router Β· dialer Β· EventBus Β· services  β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ Security  β€” Noise_XX (Curve25519 + ChaCha20-Poly1305) / plaintext β”‚
β”‚             over a self-certifying PeerId                          β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ Transport β€” shared-nothing reactor pool, per-connection state      β”‚
β”‚             machine; framed blocks over TCP or a relayed circuit,  β”‚
β”‚             QUIC-shaped packets with a stream per lane over UDP    β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ I/O multiplexing β€” epoll (Linux) Β· kqueue (macOS/BSD) Β· IOCP (Win) β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ Platform β€” WinSock2/bcrypt (Windows) Β· BSD sockets (Linux/macOS)   β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

The source tree mirrors these layers: src/librats/core, src/librats/util, src/librats/wire, src/librats/transport, src/librats/peer, src/librats/security, src/librats/node, src/librats/subsystems, src/librats/dht, src/librats/mdns, src/librats/nat, src/librats/crypto, src/librats/bittorrent, src/librats/storage, src/librats/bindings.

Frequently Asked Questions (FAQ)

Understanding DHT vs peer connections

librats has two distinct peer systems that serve different purposes:

Layer Protocol Purpose Where
DHT layer UDP (Kademlia) Peer discovery only DhtDiscovery subsystem
Peer connection layer TCP or UDP (Noise) Message exchange Node core: peers(), send, broadcast

Key points:

  • The DHT routing table is NOT your connected peers. It holds DHT nodes (often from the global BitTorrent Mainline DHT) that help you discover peers.
  • Peer connections (node.peers(), node.peer_count()) are the actual authenticated connections used for communication β€” over TCP or over the UDP transport, whichever the dial settled on.
  • The DHT is for discovery, not message routing. For messaging, use the Node core (channels), MessageJson, or PubSub.

Private Network Formation

To create a private overlay limited to your application's peers:

  1. Set a unique protocol id before starting:
NodeConfig config;
config.protocol = "my_private_app/1.0";
Node node(config);
node.add_subsystem(std::make_unique<DhtDiscovery>(dht_config));
node.start();   // discovery uses a hash derived from your protocol identity
  1. How it works:

    • DhtDiscovery derives a discovery hash from your protocol identity and announces under it in the global DHT.
    • Only peers with the same protocol id discover each other β€” and even if a stranger dials you, the protocol identity is bound into the Noise handshake, so the connection cannot complete.
    • Once discovered, peers connect over the authenticated channel (UDP first, TCP as fallback) and grow the mesh via Peer Exchange.
  2. Discovery timing:

    • DHT discovery is asynchronous β€” initial peers typically appear in 1–30 seconds.
    • For fast local testing, attach MdnsDiscovery instead (or as well).

πŸ› οΈ Building

Supported Platforms & Language Bindings

Native C++ Support

Platform Build Environment Compiler Status
Windows MinGW-w64 GCC 7+ βœ… Fully Supported
Windows Visual Studio MSVC 2017+ βœ… Fully Supported
Linux Native GCC 7+, Clang 5+ βœ… Fully Supported
macOS Xcode/Native Clang 10+ βœ… Fully Supported
iOS Xcode + CMake Clang 14+ πŸ”Ά In Development

Language Bindings & Wrappers

Language/Platform Binding Type Status Notes
C/C++ Native Library βœ… Fully Supported Core implementation with the full feature set
Android (NDK) Native C++ βœ… Fully Supported Android NDK integration with JNI bindings
Android (Java) JNI Wrapper βœ… Fully Supported High-level Java API for Android apps
Node.js N-API Addon βœ… Fully Supported RatsNode + TypeScript definitions (npm)
Python ctypes Package βœ… Fully Supported RatsNode with context-manager lifecycle
React Native Nitro Modules (C++) πŸ”Ά In Development One C++ HybridObject for both platforms (react-native/). Messaging, peer events, file transfer, pub/sub; no discovery yet. Verified on simulator + emulator
iOS / Swift C ABI via modulemap πŸ”Ά In Development XCFramework build of the core (ios/); import LibRats reaches the C ABI directly. No idiomatic Swift wrapper yet
Rust FFI Bindings πŸ“‹ Planned Safe bindings with tokio async support
Go CGO Bindings πŸ“‹ Future CGO wrapper for Go applications
C#/.NET P/Invoke πŸ“‹ Future .NET bindings for Windows/Linux/macOS

Legend: βœ… Fully Supported Β· πŸ”Ά In Development Β· πŸ“‹ Planned/Future/Research

Need another language? Anything with a C FFI (Rust, Go, C#, Zig, …) binds rats.h the same way the shipped bindings do: one opaque pointer, no C++ across the boundary.

Prerequisites

  • CMake 3.14+
  • C++17 compatible compiler:
    • GCC 7+ (Linux, MinGW)
    • Clang 5+ (macOS, Linux)
    • MSVC 2017+ (Windows)
  • Git (for dependency management)

Building on Linux/macOS

git clone https://github.com/DEgITx/librats.git
cd librats
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

Building on Windows

git clone https://github.com/DEgITx/librats.git
cd librats
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --config Release

Build Options

# Disable tests
cmake .. -DRATS_BUILD_TESTS=OFF

# Debug build with full logging
cmake .. -DCMAKE_BUILD_TYPE=Debug

# Release build optimized for performance
cmake .. -DCMAKE_BUILD_TYPE=Release

Complete Build Configuration Options

Option Default Description
RATS_BUILD_TESTS ON Build unit tests with GoogleTest
RATS_BUILD_CLIENT ON Build the rats-client reference/demo application
RATS_BUILD_EXAMPLES OFF Build the examples/ programs
RATS_ENABLE_ASAN OFF Enable AddressSanitizer for memory debugging
RATS_ENABLE_TSAN OFF Enable ThreadSanitizer for data-race debugging
RATS_BINDINGS ON Build the C API bindings for FFI support
RATS_CROSSCOMPILING OFF Force cross-compilation flags
RATS_SHARED_LIBRARY OFF Build as shared library (.dll/.so/.dylib)
RATS_STATIC_LIBRARY ON Build as static library (.a/.lib)
RATS_SEARCH_FEATURES OFF Enable the BitTorrent subsystem and DHT spider mode
RATS_STORAGE OFF Enable the distributed key-value storage subsystem
RATS_INSTALL ON Generate install() rules and the rats::rats CMake package

Examples:

# Build as shared library without tests, client or examples
cmake .. -DRATS_SHARED_LIBRARY=ON -DRATS_STATIC_LIBRARY=OFF \
         -DRATS_BUILD_TESTS=OFF -DRATS_BUILD_CLIENT=OFF -DRATS_BUILD_EXAMPLES=OFF

# Build with BitTorrent support and debug symbols
cmake .. -DRATS_SEARCH_FEATURES=ON -DCMAKE_BUILD_TYPE=Debug

# Build with distributed storage support
cmake .. -DRATS_STORAGE=ON -DCMAKE_BUILD_TYPE=Release

# Build with all optional features enabled
cmake .. -DRATS_STORAGE=ON -DRATS_SEARCH_FEATURES=ON -DCMAKE_BUILD_TYPE=Release

# Cross-compile for Android (requires NDK)
cmake .. -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK/build/cmake/android.toolchain.cmake \
         -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=android-21 \
         -DRATS_CROSSCOMPILING=ON -DRATS_BUILD_TESTS=OFF

# Build for iOS -- device + simulator slices and the XCFramework.
# Driven by its own script, not by `cmake ..`, so run it from the repository root.
cd .. && ios/build-xcframework.sh     # -> build/ios/LibRats.xcframework

See ios/README.md for how to consume that from Xcode, and react-native/README.md for the React Native package.

Integrating librats Into Your Application

Method 1: CMake FetchContent (recommended)

cmake_minimum_required(VERSION 3.14)
project(MyP2PApp)
set(CMAKE_CXX_STANDARD 17)

include(FetchContent)
FetchContent_Declare(
    librats
    GIT_REPOSITORY https://github.com/DEgITx/librats.git
    GIT_TAG master  # or a specific version/tag
)
set(RATS_BUILD_TESTS OFF CACHE BOOL "" FORCE)
set(RATS_BUILD_CLIENT OFF CACHE BOOL "" FORCE)
set(RATS_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
FetchContent_MakeAvailable(librats)

add_executable(my_p2p_app main.cpp)
target_link_libraries(my_p2p_app PRIVATE rats)

Method 2: CMake add_subdirectory

# As a git submodule
git submodule add https://github.com/DEgITx/librats.git external/librats
set(RATS_BUILD_TESTS OFF CACHE BOOL "" FORCE)
set(RATS_BUILD_CLIENT OFF CACHE BOOL "" FORCE)
set(RATS_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
add_subdirectory(external/librats)

add_executable(my_p2p_app main.cpp)
target_link_libraries(my_p2p_app PRIVATE rats)
# Include directories are propagated automatically (use #include <librats/node/node.h>).

Method 3: vcpkg

librats is in the official vcpkg registry:

vcpkg install librats
# optional features:
vcpkg install librats[bindings,search-features,storage]
find_package(rats CONFIG REQUIRED)
target_link_libraries(my_p2p_app PRIVATE rats::rats)

(The port lives in ports/librats/ in this repository and can also be used as an overlay port with vcpkg install librats --overlay-ports=<path-to-librats>/ports.)

Method 4: Conan

librats is in the official Conan Center repository:

conan install --requires=librats/2.3.7 --build=missing
# shared library:
conan install --requires=librats/2.3.7 -o "librats/*:shared=True" --build=missing

or in your conanfile.txt:

[requires]
librats/2.3.7

[generators]
CMakeDeps
CMakeToolchain
find_package(rats CONFIG REQUIRED)
target_link_libraries(my_p2p_app PRIVATE rats::rats)

The Conan Center package has the C API (bindings) on and BitTorrent (search_features) and distributed storage (storage) off. To get those, build the package from the conanfile.py in this repository, which exposes them as options:

conan create . --version 2.3.7 -o "librats/*:search_features=True" -o "librats/*:storage=True"

Required System Libraries

When linking against a pre-built librats, add these system libraries:

Platform Required Libraries
Windows ws2_32, iphlpapi, bcrypt, advapi32
Linux pthread (via Threads::Threads)
macOS pthread
Android log
iOS β€” (the XCFramework carries what it needs)

Running Tests

# In the build directory
ctest -j$(nproc) --output-on-failure

# Or run the test binary directly
./bin/librats_tests

Output Files

After building, you'll find:

  • Library: build/lib/librats.a (static library)
  • Executable: build/bin/rats-client (reference/demo application, built by default; disable with RATS_BUILD_CLIENT=OFF)
  • Examples: build/bin/examples/* (the examples/ programs, if RATS_BUILD_EXAMPLES=ON)
  • Tests: build/bin/librats_tests (if RATS_BUILD_TESTS=ON)

🎯 Usage Examples

The reference application

rats-client (built from src/main.cpp, on by default via RATS_BUILD_CLIENT) wires up every subsystem so each capability can be tried from one binary. Everything is on unless switched off:

# Terminal 1: a node on port 8080 with DHT + mDNS discovery, port mapping, hole punching, relay, PEX
./build/bin/rats-client 8080

# Terminal 2: a second node that dials the first (numeric IP), with the DHT switched off
./build/bin/rats-client 8081 --connect 127.0.0.1 8080 --no-dht

Options: --bind <addr>, --data <dir> (stable identity + reconnect store), --connect <ip> <port> (repeatable), --serve-relay (carry other peers' circuits), and --no-dht, --no-mdns, --no-upnp, --no-punch, --no-relay, --no-pex, --no-reconnect, --no-ping to switch a subsystem off (--no-bittorrent, --bt-port with RATS_SEARCH_FEATURES). Type /help once running for the interactive commands: /peers, /connect, /sub, /unsub, /pub, /msg, /file, /punch, /relay, /reconnect, /dhtfind, /quit, and any other line is broadcast as chat.

Runnable examples

The examples/ directory holds small, focused programs β€” one capability each, built on the public Node API. They are off by default; enable them with -DRATS_BUILD_EXAMPLES=ON (add -DRATS_SEARCH_FEATURES=ON for the BitTorrent one). Binaries land in build/bin/examples/.

Program Shows
chat A bare Node: encrypted transport + raw channel messaging, manual dialing
pubsub The PubSub (GossipSub) subsystem β€” a topic mesh that relays across hops
typed_messaging MessageJson typed JSON messages, keyed by the authenticated sender
file_transfer FileTransfer β€” streaming a file with CRC32 / SHA-256 integrity + progress
dht_discovery DhtDiscovery β€” automatic peer discovery over the Kademlia DHT
backpressure Streaming flat out without being dropped: send()'s return value, on_peer_writable, and what ignoring them costs
full_chat "Batteries-included" chat: DHT + mDNS + PEX discovery, the full NAT ladder (port mapping β†’ hole punching β†’ relay), reconnection, ping and pub/sub β€” peers find each other with no addresses typed in, from behind a router
bittorrent_download Downloading a magnet link (requires RATS_SEARCH_FEATURES)
cmake -B build -DRATS_BUILD_EXAMPLES=ON && cmake --build build -j

# find each other automatically in the "lobby" room (LAN via mDNS, WAN via DHT):
./build/bin/examples/full_chat 9000 lobby
./build/bin/examples/full_chat 9001 lobby

See examples/README.md for the full list and per-example usage.

πŸ”§ Persistent State

When a node is given a data_dir, it co-locates its persistent state there:

  • identity.key β€” the node's Noise/Curve25519 private key. Loaded on startup (or generated and saved on first run), giving a stable PeerId across restarts. An empty data_dir means a fresh random identity each run.
  • peers.txt β€” reconnection targets, written by ReconnectionService when configured with a store_path (typically <data_dir>/peers.txt).
  • DHT routing tables β€” persisted by DhtDiscovery when its Config::data_dir is set, so the DHT warm-starts on the next run.

There is no central config.json: configuration is supplied programmatically via NodeConfig and each subsystem's Config.

πŸš€ Benchmark Performance

librats is engineered for resource efficiency, which makes it a good fit for low-power devices, edge computing and embedded systems where memory and CPU are the scarce things.

vs js-libp2p

Environment: Intel Core Ultra 7 265KF (16 cores), 36 GB RAM, Linux, GCC 15.2 -O3, Node.js v24.18.0, js-libp2p 3.3.8. Both sides run TCP + Noise_XX over loopback, 3 runs per cell, median reported.

Metric librats (Node.js binding) js-libp2p librats advantage
Memory, node started 5.0 MB 110.9 MB 22x less
Memory per connected peer 8.1 KB 475.1 KB 59x less
Memory, 100 peers 5.8 MB 158.4 MB 27x less
Cold start 21 ms 188 ms 9x faster
Connection setup 1 746 /s 317 /s 5.5x faster
CPU per handshake 1.61 ms 9.19 ms 5.7x less
Small messages (256 B) 863 517 msg/s 92 711 msg/s 9.3x faster
CPU per small message 2.27 Β΅s 23.38 Β΅s 10x less
Bulk throughput (64 KiB) 600 MB/s 603 MB/s parity
CPU per GB 3.27 s/GB 4.68 s/GB 1.4x less
Runtime dependencies none 139 npm packages, 66 MB β€”

Contributing

We welcome contributions! Please see our Contributing Guide for guidelines on code style, development setup, running tests, and submitting pull requests.

Quick Start for Contributors

git clone https://github.com/DEgITx/librats.git
cd librats
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Debug -DRATS_BUILD_TESTS=ON
make -j$(nproc)
./bin/librats_tests

πŸ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

librats also embeds a few adapted third-party cryptographic and platform-compatibility sources under BSD terms; see THIRD_PARTY_NOTICES.md for the component list and full notices.

πŸ™ Acknowledgments

  • libtorrent: a huge source of inspiration for librats' DHT and BitTorrent stacks. Many algorithmic ideas and improvements β€” the traversal/lookup algorithm, the ordered-bucket routing table, IP-diversity admission and other hardening details β€” are borrowed from its battle-tested design. Big thanks to the libtorrent team for their outstanding work.
  • noise-c by Rhys Weatherley / Southern Storm Software: the reference librats' Noise Protocol implementation was written against. The ChaCha20, SHA-256/512 and BLAKE2b/BLAKE2s primitives in src/librats/crypto/ are derived from it (MIT), as are β€” through it β€” curve25519-donna by Adam Langley (BSD-3-Clause) and poly1305-donna by Andrew Moon (MIT). See THIRD_PARTY_NOTICES.md for provenance and the full notices.
  • nlohmann/json: inspiration for the API surface of librats' own self-contained librats::Json type
  • Contributors: everyone who has helped make librats better

About

librats: High-performance, lightweight P2P native library for big networks

Topics

Resources

Contributing

Stars

169 stars

Watchers

9 watching

Forks

Releases

Packages

Contributors

Languages