librats 1.0.2 → 2.2.0

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

@@ -0,0 +1,380 @@
+#pragma once
+
+/**
+ * @file rats.h
+ * @brief The canonical C ABI over Node — the foundation for all language bindings.
+ *
+ * Opaque-pointer style. A `rats_t` wraps a C++ Node. Strings returned by the
+ * library (e.g. peer ids) are heap-allocated and must be released with
+ * rats_string_free(). Peer ids are 64-char lowercase hex of the peer's
+ * self-certifying PeerId.
+ *
+ * Error model: fallible operations return a `rats_error_t` (RATS_OK == 0 on
+ * success). Pure getters return their value directly. Use rats_error_str() for a
+ * static human-readable name. Delivery of messages is asynchronous and
+ * best-effort: a RATS_OK from rats_send()/rats_publish() means the request was
+ * accepted and queued, not that a peer received it.
+ *
+ * Subsystems are explicit and opt-in: discovery, pub/sub, typed messaging, file
+ * transfer and ping must each be turned on with the matching rats_enable_*()
+ * BEFORE rats_start(). Calling a subsystem function before its enable returns
+ * RATS_ERR_NOT_ENABLED; calling an enable after start returns
+ * RATS_ERR_ALREADY_STARTED.
+ *
+ * Threading: callbacks fire on an internal reactor thread — do not block in them.
+ * Register callbacks and enable subsystems BEFORE rats_start().
+ */
+
+#include "librats/util/rats_export.h"
+
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef void* rats_t;
+
+typedef enum {
+    RATS_SECURITY_NOISE     = 0,  /* Noise XX, encrypted + authenticated (default) */
+    RATS_SECURITY_PLAINTEXT = 1   /* unencrypted, ids exchanged in the clear */
+} rats_security_t;
+
+/* Which wire a peer connection runs on. Both carry the identical protocol and
+ * the identical encrypted handshake; they differ only in how the ordered,
+ * reliable byte stream underneath is obtained. */
+typedef enum {
+    RATS_TRANSPORT_TCP   = 0,  /* one kernel socket per peer */
+    RATS_TRANSPORT_UDP   = 1,  /* reliable stream over the shared UDP socket */
+    /* Carried inside another peer's connection (see rats_enable_relay). Reported
+       by rats_peer_transport(); never a value to put in preferred_transport,
+       which chooses what a DIAL tries and a relay is never dialed. */
+    RATS_TRANSPORT_RELAY = 2
+} rats_transport_t;
+
+/* Bitmask of transports (see rats_transports / rats_peer_transports). */
+#define RATS_TRANSPORT_MASK_TCP 0x1u
+#define RATS_TRANSPORT_MASK_UDP 0x2u
+
+/* Result of a fallible operation. RATS_OK is 0; any non-zero value is an error.
+ * NOTE: this inverts the truthiness of the old int-returning calls — test against
+ * RATS_OK, not against zero/non-zero, e.g. `if (rats_start(n) != RATS_OK) …`. */
+typedef enum {
+    RATS_OK                  = 0,
+    RATS_ERR_INVALID_ARG     = 1,  /* null/malformed argument (bad peer id, null ptr, bad json) */
+    RATS_ERR_NOT_STARTED     = 2,  /* operation requires a started node */
+    RATS_ERR_ALREADY_STARTED = 3,  /* enable/attach called after rats_start() */
+    RATS_ERR_NOT_ENABLED     = 4,  /* subsystem not enabled — call the matching rats_enable_* */
+    RATS_ERR_NO_SUCH_PEER    = 5,  /* peer not connected, or transfer id not found */
+    RATS_ERR_BIND            = 6,  /* listen/bind failed during rats_start() */
+    RATS_ERR_INTERNAL        = 7
+} rats_error_t;
+
+/** Static human-readable name of an error code (do not free). */
+RATS_API const char* rats_error_str(rats_error_t err);
+
+/* — construction / lifecycle — */
+
+/** Full node configuration. Obtain a sane-defaults instance with
+ *  rats_config_default(), set the fields you care about, then pass it to
+ *  rats_create_config(). Zero-initialising this struct yourself is NOT safe
+ *  (enable_listen would be 0 → a dial-only node); always start from the default.
+ *  String fields are borrowed only for the duration of the create call; NULL on
+ *  any of them selects the library default shown below. */
+typedef struct {
+    uint16_t        listen_port;      /* inbound port; 0 = ephemeral */
+    int             enable_listen;    /* 0 = dial-only node (no listener) */
+    const char*     bind_address;     /* NULL → "::" dual-stack wildcard */
+    rats_security_t security;         /* RATS_SECURITY_NOISE / _PLAINTEXT */
+    const char*     data_dir;         /* persistent state dir; NULL/"" → ephemeral identity each run */
+    const char*     protocol;         /* handshake app id (e.g. "myapp/1.0"); NULL → "librats/1.0" */
+    size_t          max_peers;        /* established-peer cap; 0 = unlimited */
+
+    /* Transports. Both are enabled by default and bind the SAME port, so one
+     * advertised address is dialable either way. */
+    int              enable_tcp;              /* accept and dial over TCP (default 1) */
+    int              enable_udp;              /* accept and dial over UDP (default 1) */
+    /* Both zero means "both enabled", not "neither": a node with no transport can
+     * neither dial nor accept, so nobody asks for one on purpose — while zeroed
+     * memory (rats_config_t cfg = {0};) asks for it by accident. Prefer
+     * rats_config_default() and change what you need. */
+    rats_transport_t preferred_transport;     /* tried first when dialing (default UDP) */
+    uint32_t         transport_fallback_ms;   /* delay before racing the other transport;
+                                               * 0 = never fall back (default 1200) */
+} rats_config_t;
+
+/** A config pre-filled with the library defaults (listening, Noise, ephemeral
+ *  identity, unlimited peers). Mutate the returned struct and pass to
+ *  rats_create_config(). */
+RATS_API rats_config_t rats_config_default(void);
+
+/** Create a node from a full config (NULL → all defaults). When data_dir is set,
+ *  the identity persists across restarts and subsystems (DHT routing table,
+ *  reconnection store) co-locate their state there. */
+RATS_API rats_t rats_create_config(const rats_config_t* config);
+
+/** Create a listening node (Noise, dual-stack, ephemeral identity, port 0 = ephemeral). */
+RATS_API rats_t rats_create(uint16_t listen_port);
+
+/** Create with basic control. enable_listen=0 makes a dial-only node. For
+ *  data_dir / protocol identity / max_peers use rats_create_config(). */
+RATS_API rats_t rats_create_ex(uint16_t listen_port, int enable_listen,
+                                         const char* bind_address, rats_security_t security);
+
+RATS_API void         rats_destroy(rats_t node);
+RATS_API rats_error_t rats_start(rats_t node);   /* RATS_OK / RATS_ERR_ALREADY_STARTED / RATS_ERR_BIND */
+RATS_API void         rats_stop(rats_t node);
+RATS_API uint16_t     rats_listen_port(rats_t node);
+
+/** Transports this node is actually running, as a RATS_TRANSPORT_MASK_* bitmask.
+ *  May be narrower than the config asked for: a UDP socket that could not be
+ *  bound leaves the node TCP-only rather than failing to start. 0 before
+ *  rats_start() and after rats_stop(). */
+RATS_API uint32_t     rats_transports(rats_t node);
+
+/** Our self-certifying peer id as hex. Caller frees with rats_string_free(). */
+RATS_API char*    rats_local_id(rats_t node);
+
+/** Application protocol identity bound into the handshake (see rats_config_t).
+ *  Two nodes whose protocol differs cannot complete a handshake. Caller frees
+ *  the returned string with rats_string_free(). */
+RATS_API char*    rats_protocol(rats_t node);
+
+/* — connections — */
+
+RATS_API rats_error_t rats_connect(rats_t node, const char* host, uint16_t port);
+RATS_API size_t       rats_peer_count(rats_t node);
+
+/** Cap on established peers (0 = unlimited). Guards inbound; our dials are honored.
+ *  May be set before or after start(). */
+RATS_API void   rats_set_max_peers(rats_t node, size_t max_peers);
+RATS_API size_t rats_max_peers(rats_t node);
+
+/* — messaging (named application channel, raw bytes) — */
+
+RATS_API rats_error_t rats_send(rats_t node, const char* peer_id_hex,
+                                          const char* channel, const void* data, size_t len);
+RATS_API rats_error_t rats_broadcast(rats_t node, const char* channel,
+                                               const void* data, size_t len);
+
+/* — callbacks (register before start; invoked on a reactor thread) — */
+
+typedef void (*rats_peer_cb)(void* user, const char* peer_id_hex);
+typedef void (*rats_message_cb)(void* user, const char* peer_id_hex, const void* data, size_t len);
+
+RATS_API rats_error_t rats_on_peer_connected(rats_t node, rats_peer_cb cb, void* user);
+RATS_API rats_error_t rats_on_peer_disconnected(rats_t node, rats_peer_cb cb, void* user);
+RATS_API rats_error_t rats_on(rats_t node, const char* channel, rats_message_cb cb, void* user);
+
+/* — optional subsystems (enable before start) — */
+
+/** DHT discovery. dht_port 0 = ephemeral; discovery_key namespaces the app
+ *  (NULL → the node's protocol, so only same-protocol peers discover each other). */
+RATS_API rats_error_t rats_enable_dht(rats_t node, uint16_t dht_port, const char* discovery_key);
+/** Local-network mDNS discovery. */
+RATS_API rats_error_t rats_enable_mdns(rats_t node);
+/** Automatic NAT port forwarding for the listen port (UPnP IGD + NAT-PMP).
+ *  Pass non-zero to enable each backend; both run in parallel. */
+RATS_API rats_error_t rats_enable_port_mapping(rats_t node, int enable_upnp, int enable_natpmp);
+
+/** UDP hole punching: reach a peer that no port forwarding made reachable, by
+ *  arranging with a peer both sides already have that the two dial each other at
+ *  the same moment. Call before start(); both punching nodes must have it enabled,
+ *  and so must the node that carries the rendezvous between them.
+ *
+ *  `serve_as_relay` (non-zero) also carries other peers' rendezvous — a few dozen
+ *  forwarded bytes per punch, only ever to peers this node already holds. A mesh in
+ *  which nobody relays cannot punch at all. */
+RATS_API rats_error_t rats_enable_hole_punch(rats_t node, int serve_as_relay);
+
+/** Try to reach `peer_id_hex` by punching. Non-blocking: success arrives as an
+ *  ordinary peer-connected callback. RATS_OK if a rendezvous was started;
+ *  RATS_ERR_NOT_ENABLED if hole punching is off; RATS_ERR_NO_SUCH_PEER if there is
+ *  nothing to do or nothing to try with — the peer is already connected, a punch to
+ *  it is already running, or this node does not yet know an external endpoint of
+ *  its own to advertise (it needs at least one datagram peer first). */
+RATS_API rats_error_t rats_punch_peer(rats_t node, const char* peer_id_hex);
+
+/** Relaying: reach a peer that neither port forwarding nor hole punching could
+ *  make reachable, by routing the connection through a node both ends are already
+ *  connected to. Call before start(). The peer that comes out is ordinary in every
+ *  way — the same end-to-end encryption, the same channels — except that its bytes
+ *  take a detour, which rats_peer_transport() reports as RATS_TRANSPORT_RELAY.
+ *
+ *  `serve_as_relay` (non-zero) also carries OTHER peers' connections. Unlike a
+ *  hole-punch rendezvous, that spends real bandwidth on somebody else's traffic, so
+ *  it is off by default and opted into here; a mesh in which nobody serves cannot
+ *  relay at all. A serving node forwards only between peers it already holds, never
+ *  chains circuits, and caps each one by bytes, duration and count. */
+RATS_API rats_error_t rats_enable_relay(rats_t node, int serve_as_relay);
+
+/** Try to reach `peer_id_hex` through a relay. Non-blocking: success arrives as an
+ *  ordinary peer-connected callback. RATS_OK if an attempt was started;
+ *  RATS_ERR_NOT_ENABLED if relaying is off; RATS_ERR_NO_SUCH_PEER if there is
+ *  nothing to do or nothing to try with — the peer is already connected, an attempt
+ *  is already running, it is in cooldown, or this node has no peer that could carry
+ *  the connection.
+ *
+ *  Usually there is no need to call this: with hole punching enabled too, a punch
+ *  that cannot work hands the target over by itself. */
+RATS_API rats_error_t rats_connect_via_relay(rats_t node, const char* peer_id_hex);
+
+/** What the mesh has shown about this node's own NAT, from the endpoints datagram
+ *  peers report seeing its shared UDP socket at. One of the RATS_NAT_* values;
+ *  RATS_NAT_ENDPOINT_DEPENDENT means punching cannot work from here. */
+RATS_API int rats_nat_mapping(rats_t node);
+
+enum {
+    RATS_NAT_UNKNOWN              = 0,  /* not enough independent observations yet */
+    RATS_NAT_OPEN                 = 1,  /* no NAT in the path */
+    RATS_NAT_ENDPOINT_INDEPENDENT = 2,  /* one external port for every peer — punchable */
+    RATS_NAT_ENDPOINT_DEPENDENT   = 3   /* a fresh mapping per peer (symmetric) — not punchable */
+};
+
+/* — peer enumeration — */
+
+/** Hex ids of currently-connected peers. Writes the count to *count and returns a
+ *  heap array of `count` heap strings; free the whole thing with rats_free_peer_ids().
+ *  Returns NULL (and *count = 0) when there are no peers. */
+RATS_API char** rats_peer_ids(rats_t node, size_t* count);
+RATS_API void   rats_free_peer_ids(char** ids, size_t count);
+
+/** Which transport a connected peer's link runs on, or -1 if not connected. */
+RATS_API int rats_peer_transport(rats_t node, const char* peer_id_hex);
+
+/** Transports a connected peer advertised in its identify message, as a
+ *  RATS_TRANSPORT_MASK_* bitmask. 0 means the peer did not say (an older build),
+ *  which is "no information", not "none". -1 if the peer is not connected. */
+RATS_API int rats_peer_transports(rats_t node, const char* peer_id_hex);
+
+/* — pub/sub (topic-based, raw bytes; enable + subscribe before start) — */
+
+typedef void (*rats_topic_cb)(void* user, const char* peer_id_hex,
+                              const char* topic, const void* data, size_t len);
+
+/** Enable the pub/sub (GossipSub) subsystem. Call before start(). */
+RATS_API rats_error_t rats_enable_pubsub(rats_t node);
+/** Subscribe to `topic`; matching messages invoke `cb` on a reactor thread. */
+RATS_API rats_error_t rats_subscribe(rats_t node, const char* topic, rats_topic_cb cb, void* user);
+RATS_API rats_error_t rats_unsubscribe(rats_t node, const char* topic);
+/** Publish `data` on `topic` to every subscribed peer (and local subscribers). */
+RATS_API rats_error_t rats_publish(rats_t node, const char* topic, const void* data, size_t len);
+
+/* — typed JSON messaging (named message type; payload is JSON text) — */
+
+typedef void (*rats_json_cb)(void* user, const char* peer_id_hex, const char* json);
+
+/** Enable the JSON-messaging subsystem (the C view of MessageJson). Call before start(). */
+RATS_API rats_error_t rats_enable_json(rats_t node);
+/** Register a handler for JSON messages of `type`. `json` is compact JSON text owned
+ *  by the library (valid only for the duration of the call). Additive: multiple
+ *  handlers may coexist. The sender id is the authenticated handshake PeerId. */
+RATS_API rats_error_t rats_on_json(rats_t node, const char* type, rats_json_cb cb, void* user);
+/** Like rats_on_json, but the handler is removed right after it fires once. */
+RATS_API rats_error_t rats_once_json(rats_t node, const char* type, rats_json_cb cb, void* user);
+RATS_API rats_error_t rats_off_json(rats_t node, const char* type);
+/** Send/broadcast a JSON message. `json` must be valid JSON text (invalid → RATS_ERR_INVALID_ARG). */
+RATS_API rats_error_t rats_send_json(rats_t node, const char* peer_id_hex, const char* type, const char* json);
+RATS_API rats_error_t rats_broadcast_json(rats_t node, const char* type, const char* json);
+
+/* — file transfer (push model; enable + register callbacks before start) — */
+
+typedef void (*rats_file_offer_cb)(void* user, const char* peer_id_hex, uint64_t transfer_id,
+                                   const char* name, uint64_t size, int is_directory);
+typedef void (*rats_file_progress_cb)(void* user, uint64_t transfer_id, const char* peer_id_hex,
+                                      uint64_t bytes_transferred, uint64_t total_bytes, int status);
+typedef void (*rats_file_complete_cb)(void* user, uint64_t transfer_id, int success, const char* path);
+
+/** Enable the file-transfer subsystem. `temp_dir` holds in-progress downloads
+ *  (NULL → current directory). Call before start(). */
+RATS_API rats_error_t rats_enable_file_transfer(rats_t node, const char* temp_dir);
+
+RATS_API rats_error_t rats_on_file_offer(rats_t node, rats_file_offer_cb cb, void* user);
+RATS_API rats_error_t rats_on_file_progress(rats_t node, rats_file_progress_cb cb, void* user);
+RATS_API rats_error_t rats_on_file_complete(rats_t node, rats_file_complete_cb cb, void* user);
+
+/** Offer a file / directory tree to a peer. Returns the transfer id (0 on failure,
+ *  e.g. file transfer not enabled or bad peer id). */
+RATS_API uint64_t rats_send_file(rats_t node, const char* peer_id_hex, const char* path);
+RATS_API uint64_t rats_send_directory(rats_t node, const char* peer_id_hex, const char* dir_path);
+
+/** Respond to an offer. For a single file, dest_path is the file path; for a
+ *  directory, the destination directory. (peer_id, transfer_id) names the offer. */
+RATS_API rats_error_t rats_accept_file(rats_t node, const char* peer_id_hex, uint64_t transfer_id, const char* dest_path);
+RATS_API rats_error_t rats_reject_file(rats_t node, const char* peer_id_hex, uint64_t transfer_id);
+
+/** Control a live transfer (either side). RATS_OK if the transfer was found and
+ *  the action applied; RATS_ERR_NO_SUCH_PEER if no matching transfer. */
+RATS_API rats_error_t rats_cancel_file(rats_t node, const char* peer_id_hex, uint64_t transfer_id);
+RATS_API rats_error_t rats_pause_file(rats_t node, const char* peer_id_hex, uint64_t transfer_id);
+RATS_API rats_error_t rats_resume_file(rats_t node, const char* peer_id_hex, uint64_t transfer_id);
+
+/* — liveness (RTT probing) — */
+
+/** Enable periodic ping/pong RTT probing of every peer. Call before start(). */
+RATS_API rats_error_t rats_enable_ping(rats_t node);
+/** Last measured round-trip time to a peer in milliseconds, or -1 if unknown
+ *  (ping not enabled, or no pong received yet). */
+RATS_API int64_t rats_peer_rtt_ms(rats_t node, const char* peer_id_hex);
+
+/* — automatic reconnection — */
+
+/** Enable the reconnection subsystem: re-dials dropped peers with exponential
+ *  backoff. Dialed peers are remembered automatically; when the node has a
+ *  data_dir, targets persist to "<data_dir>/peers.json" across restarts. Call
+ *  before start(). A bare node never reconnects on its own. */
+RATS_API rats_error_t rats_enable_reconnect(rats_t node);
+/** Add an address to keep connected (re-dialed on drop). Persisted if a store is
+ *  configured. May be called before or after start(). */
+RATS_API rats_error_t rats_add_reconnect(rats_t node, const char* host, uint16_t port);
+/** Stop reconnecting to an address and drop it from the store. */
+RATS_API rats_error_t rats_remove_reconnect(rats_t node, const char* host, uint16_t port);
+
+/* — BitTorrent —
+ * Only functional when the library is built with RATS_SEARCH_FEATURES; the calls
+ * otherwise return RATS_ERR_NOT_ENABLED. The client keeps its own transport and,
+ * when DHT is enabled on the node first, shares it. Enable before start(). */
+
+/** Enable BitTorrent. listen_port 0 picks an ephemeral port; download_path is the
+ *  default save directory (NULL = "."). Enable DHT first to share the node's DHT. */
+RATS_API rats_error_t rats_enable_bittorrent(rats_t node, uint16_t listen_port, const char* download_path);
+/** Start downloading a magnet link (metadata is fetched from peers). */
+RATS_API rats_error_t rats_bt_add_magnet(rats_t node, const char* magnet_uri, const char* save_path);
+/** Start a torrent from a .torrent file on disk. */
+RATS_API rats_error_t rats_bt_add_torrent_file(rats_t node, const char* torrent_path, const char* save_path);
+/** Remove a torrent by its 40-char hex info-hash (downloaded files are kept). */
+RATS_API rats_error_t rats_bt_remove_torrent(rats_t node, const char* info_hash_hex);
+
+/* — logging (process-global; no node required) — */
+
+typedef enum {
+    RATS_LOG_DEBUG = 0,
+    RATS_LOG_INFO  = 1,
+    RATS_LOG_WARN  = 2,
+    RATS_LOG_ERROR = 3
+} rats_log_level_t;
+
+RATS_API void rats_set_log_level(rats_log_level_t level);
+/** Mirror logs to `path` (NULL/empty disables file logging). */
+RATS_API void rats_set_log_file(const char* path);
+
+/* — library info (process-global; no node required) — */
+
+/** Library version as a static string, e.g. "1.2.3" (do not free). */
+RATS_API const char* rats_version_string(void);
+/** Library version components. Any out-pointer may be NULL. */
+RATS_API void        rats_version(int* major, int* minor, int* patch, int* build);
+/** Git describe of the build, e.g. "v1.2.3-4-gabcdef" (static; do not free). */
+RATS_API const char* rats_git_describe(void);
+/** Packed ABI id as (major<<16)|(minor<<8)|patch — MAJOR bumps on breaking
+ *  changes, MINOR on additive ones. */
+RATS_API uint32_t    rats_abi(void);
+
+/* — utility — */
+
+RATS_API void rats_string_free(char* str);
+
+#ifdef __cplusplus
+}
+#endif