Struct RnsNode 

pub struct RnsNode { /* private fields */ }

A running RNS node.

Implementations

impl RnsNode

pub fn from_config( config_path: Option<&Path>, callbacks: Box<dyn Callbacks>, ) -> Result<Self>

Start the node from a config file path. If config_path is None, uses ~/.reticulum/.

pub fn from_private_config( config_dir: &Path, state_dir: &Path, underlay_mark: Option<u32>, callbacks: Box<dyn Callbacks>, ) -> Result<Self>

Start an application-private node from a dedicated configuration and state root.

Private nodes never expose the shared-instance or management servers, never load hooks, fail on unsupported/malformed enabled interfaces, and force runtime interface failures to stop startup. underlay_mark overrides the value in the Reticulum configuration.

pub fn start(config: NodeConfig, callbacks: Box<dyn Callbacks>) -> Result<Self>

Start the node. Connects all interfaces, starts driver and timer threads.

pub fn query(&self, request: QueryRequest) -> Result<QueryResponse, SendError>

Query the driver for state information.

pub fn attach_interface(&self, name: &str) -> Result<Option<bool>, SendError>

Attach a named interface from the current on-disk configuration.

pub fn detach_interface(&self, name: &str) -> Result<Option<bool>, SendError>

Detach a named interface and its spawned children.

pub fn reload_interface(&self, name: &str) -> Result<Option<bool>, SendError>

Detach and attach a named interface using the current on-disk configuration.

pub fn links(&self) -> Result<Vec<LinkInfoEntry>, SendError>

Snapshot active Link metadata, including the negotiated direct-data MDU.

pub fn query_link( &self, link_id: [u8; 16], ) -> Result<Option<LinkInfoEntry>, SendError>

Snapshot one Link, including local send backlog, or None if unknown.

pub fn state_snapshot(&self) -> Arc<StateSnapshot>

The link and interface statistics the driver last published, read without a driver round trip.

Unlike query, links and query_link, which queue behind every earlier control event and answer exactly at that point, this returns at once even while the driver works through a long backlog or is blocked, for example in a callback. The price is freshness and ordering: the driver republishes on every tick (global.tick_interval_ms, 1 s by default) and as soon as a link or interface changes state, so the snapshot may lag by up to one tick, plus however long the driver has been blocked, and it is not a barrier: events sent before the call, sends included, may not be reflected yet. Before the first publish the snapshot is empty with sequence == 0.

pub fn snapshot_links(&self) -> Vec<LinkInfoEntry>

Links as of the last published state_snapshot.

May lag by up to one tick and is not ordered after earlier events; use links for an exact, ordered answer.

pub fn snapshot_link(&self, link_id: [u8; 16]) -> Option<LinkInfoEntry>

One link as of the last published state_snapshot, or None if it was not known then.

May lag by up to one tick and is not ordered after earlier events; use query_link for an exact, ordered answer.

pub fn snapshot_interfaces(&self) -> InterfaceStatsResponse

Interface statistics as of the last published state_snapshot.

May lag by up to one tick and is not ordered after earlier events; use query(QueryRequest::InterfaceStats) for an exact, ordered answer.

pub fn lowest_interface_bitrate(&self) -> Result<Option<u64>, SendError>

Return the slowest positive bitrate among currently registered interfaces.

Returns Ok(None) when no registered interface advertises a usable bitrate.

pub fn medium_path_timeout(&self) -> Result<f64, SendError>

Return the adaptive medium path timeout advertised by the transport engine.

The estimate covers a full MTU round trip on the slowest registered positive-bitrate interface plus the per-hop allowance, or is zero when no usable bitrate is known.

pub fn begin_drain(&self, timeout: Duration) -> Result<(), SendError>

Enter drain mode and stop admitting new work.

pub fn drain_status(&self) -> Result<DrainStatus, SendError>

Query current drain/lifecycle status.

pub fn send_raw( &self, raw: Vec<u8>, dest_type: u8, attached_interface: Option<InterfaceId>, ) -> Result<(), SendError>

Send a raw outbound packet.

pub fn register_destination( &self, dest_hash: [u8; 16], dest_type: u8, ) -> Result<(), SendError>

Register a local destination with the transport engine.

pub fn deregister_destination( &self, dest_hash: [u8; 16], ) -> Result<(), SendError>

Deregister a local destination.

pub fn deregister_link_destination( &self, dest_hash: [u8; 16], ) -> Result<(), SendError>

Deregister a link destination (stop accepting incoming links).

pub fn register_link_destination( &self, dest_hash: [u8; 16], sig_prv_bytes: [u8; 32], sig_pub_bytes: [u8; 32], resource_strategy: u8, ) -> Result<(), SendError>

Register a link destination that can accept incoming links.

dest_hash: the destination hash sig_prv_bytes: Ed25519 private signing key (32 bytes) sig_pub_bytes: Ed25519 public signing key (32 bytes)

pub fn register_link_destination_with_max_request_size( &self, dest_hash: [u8; 16], sig_prv_bytes: [u8; 32], sig_pub_bytes: [u8; 32], resource_strategy: u8, max_request_size: Option<usize>, ) -> Result<(), SendError>

Register a link destination with an optional maximum accepted request size.

pub fn set_link_cost(&self, dest_hash: [u8; 16], cost: f64) -> f64

Set the required link establishment stamp cost for a destination.

Mirrors Destination.set_link_cost: the cost is clamped to 0..=LINK_COST_CAP and the clamped value is returned. Set it to 0 to disable. The cost is carried in the destination’s announce extension (emitted when destination stamping is on) so initiators grind their link request stamps to it, and, when link request stamps are enforced, incoming link requests whose stamp value is below it are dropped.

pub fn link_cost(&self, dest_hash: &[u8; 16]) -> f64

The link request stamp cost announced and required for a destination.

Mirrors Destination.get_link_cost: the configured cost, or the default LINK_REQUEST_STAMP_COST (Transport.LR_COST) when none was set. Costs are fractional since upstream 796ef2d4 and held on the 1/256 grid they are announced and checked on, so 14.2 reads back as 14.19921875.

pub fn set_link_request_stamps_enforced(&self, enforced: bool)

Override Transport.LR_STAMPS_ENFORCED for this node.

When enabled, incoming link requests whose stamp value is below the destination’s link_cost are dropped. Defaults to rns_core::constants::LR_STAMPS_ENFORCED (off, as upstream).

pub fn link_request_stamps_enforced(&self) -> bool

Whether incoming link request stamps are enforced.

pub fn register_request_handler<F>( &self, path: &str, allowed_list: Option<Vec<[u8; 16]>>, handler: F, ) -> Result<(), SendError>

where F: Fn([u8; 16], &str, &[u8], Option<&([u8; 16], [u8; 64])>) -> Option<Vec<u8>> + Send + 'static,

Register a request handler for a given path on established links.

pub fn register_request_handler_response<F>( &self, path: &str, allowed_list: Option<Vec<[u8; 16]>>, handler: F, ) -> Result<(), SendError>

where F: Fn([u8; 16], &str, &[u8], Option<&([u8; 16], [u8; 64])>) -> Option<RequestResponse> + Send + 'static,

Register a request handler that can return resource responses with metadata.

pub fn register_deferred_request_handler<F>( &self, path: &str, allowed_list: Option<Vec<[u8; 16]>>, handler: F, ) -> Result<(), SendError>

where F: Fn([u8; 16], &str, [u8; 16], &[u8], Option<&([u8; 16], [u8; 64])>) + Send + 'static,

Register a request handler whose response is completed asynchronously with RnsNode::send_deferred_response.

pub fn send_deferred_response( &self, link_id: [u8; 16], request_id: [u8; 16], data: Vec<u8>, ) -> Result<(), SendError>

Complete a request accepted by a deferred request handler.

pub fn create_link( &self, dest_hash: [u8; 16], dest_sig_pub_bytes: [u8; 32], ) -> Result<[u8; 16], SendError>

Create an outbound link to a destination.

Returns the link_id on success.

pub fn send_request( &self, link_id: [u8; 16], path: &str, data: &[u8], ) -> Result<(), SendError>

Send a request on an established link.

pub fn send_request_with_max_response_size( &self, link_id: [u8; 16], path: &str, data: &[u8], max_response_size: Option<usize>, ) -> Result<(), SendError>

Send a request with an optional maximum accepted response size.

pub fn identify_on_link( &self, link_id: [u8; 16], identity_prv_key: [u8; 64], ) -> Result<(), SendError>

Identify on a link (reveal identity to remote peer).

pub fn teardown_link(&self, link_id: [u8; 16]) -> Result<(), SendError>

Tear down a link.

pub fn send_resource( &self, link_id: [u8; 16], data: Vec<u8>, metadata: Option<Vec<u8>>, ) -> Result<(), SendError>

Send a resource on an established link.

pub fn send_resource_with_auto_compress( &self, link_id: [u8; 16], data: Vec<u8>, metadata: Option<Vec<u8>>, auto_compress: bool, ) -> Result<(), SendError>

Send a resource on an established link, controlling automatic compression.

Set auto_compress to false when the application knows its payload is already compressed or encrypted. This skips the compression attempt; link encryption and Resource integrity checks still apply. With true, eligible payloads are fully compressed and the result is used only when smaller. Even a rejected attempt costs CPU, while disabling compression for compressible content can substantially increase transmitted bytes.

Buffered sends of at least 16 KiB that fit one Resource segment can prepare compression on a node-owned worker. Its admission budget is eight jobs and 8 MiB of owned input capacity plus reserved compressed output. Codec workspace and the running job’s temporary input are additional. Saturation, small/split Resources and worker startup failure use synchronous preparation, preserving earlier buffered sends on the same link. This improves responsiveness for eligible sends; it does not provide a latency bound under overload. Reader transfers and request responses keep their existing synchronous preparation paths.

pub fn send_resource_with_options( &self, link_id: [u8; 16], data: Vec<u8>, metadata: Option<Vec<u8>>, options: ResourceSendOptions, ) -> Result<(), SendError>

Send a resource on an established link with explicit send options, including the application flag the receiver sees with the data.

pub fn send_resource_reader<R: Read + Send + 'static>( &self, link_id: [u8; 16], reader: R, declared_length: u64, metadata: Option<Vec<u8>>, auto_compress: bool, ) -> Result<ResourceTransferId, SendError>

Send a Resource from a sequential reader without retaining the full logical payload in memory.

pub fn send_resource_reader_with_options<R: Read + Send + 'static>( &self, link_id: [u8; 16], reader: R, declared_length: u64, metadata: Option<Vec<u8>>, options: ResourceSendOptions, ) -> Result<ResourceTransferId, SendError>

Send a Resource from a sequential reader with explicit send options.

pub fn send_resource_file( &self, link_id: [u8; 16], path: impl AsRef<Path>, metadata: Option<Vec<u8>>, auto_compress: bool, ) -> Result<ResourceTransferId>

Send a file as a bounded-memory streaming Resource.

pub fn set_resource_receive_mode( &self, link_id: [u8; 16], mode: ResourceReceiveMode, ) -> Result<(), SendError>

Select delivery policy for independent incoming Resources on a link.

pub fn set_resource_strategy( &self, link_id: [u8; 16], strategy: u8, ) -> Result<(), SendError>

Set the resource acceptance strategy for a link.

0 = AcceptNone, 1 = AcceptAll, 2 = AcceptApp

pub fn accept_resource( &self, link_id: [u8; 16], resource_hash: Vec<u8>, accept: bool, ) -> Result<(), SendError>

Accept or reject a pending resource (for AcceptApp strategy).

pub fn send_channel_message( &self, link_id: [u8; 16], msgtype: u16, payload: Vec<u8>, ) -> Result<(), SendError>

Send a channel message on a link (compatibility API).

pub fn try_send_channel_message( &self, link_id: [u8; 16], msgtype: u16, payload: Vec<u8>, ) -> Result<(), ChannelSendError>

Attempt to enqueue a channel message, preserving temporary backpressure. A NotReady result means no sequence was reserved; callers can retry the same payload when capacity is available. Other failures are terminal.

pub fn propose_direct_connect(&self, link_id: [u8; 16]) -> Result<(), SendError>

Propose a direct P2P connection to a peer via NAT hole punching.

The link must be active and connected through a backbone node. If successful, a direct UDP connection will be established, bypassing the backbone.

pub fn set_direct_connect_policy( &self, policy: HolePunchPolicy, ) -> Result<(), SendError>

Set the policy for handling incoming direct-connect proposals.

pub async fn send_on_link( &self, link_id: [u8; 16], data: Vec<u8>, context: u8, ) -> Result<(), LinkSendError>

Wait for capacity and transmit a Link packet through its interface writer.

Success means the underlying transport accepted the complete packet, not that the peer received or acknowledged it. Cancellation before admission sends nothing; after admission, dropping this future does not cancel transmission. This future is independent of any async runtime. The driver’s configured event capacity also bounds the total number of admitted confirmed sends (Links, packets and announcements), including frames waiting for an interface or write. A transmission error can follow a partial write; only QueueFull from the try API guarantees that retrying cannot duplicate an admitted packet.

pub fn try_send_on_link( &self, link_id: [u8; 16], data: Vec<u8>, context: u8, ) -> Result<LinkSendReceipt, LinkSendError>

Try to admit a Link send without waiting for capacity.

A successful return is a receipt, not a transmission result. Await the receipt for exactly the same completion contract as send_on_link. QueueFull means nothing was admitted and the caller may retry.

pub fn try_send_link_datagram( &self, link_id: [u8; 16], data: Vec<u8>, context: u8, timeout: Duration, ) -> Result<(), LinkDatagramError>

Admit a best-effort direct Link datagram without blocking on queue space.

Success means the driver accepted and encoded the packet. It does not imply remote delivery, acknowledgement, or interface transmission.

pub fn attach_local_ratchets(&self, owner: Arc<LocalRatchets>) -> Result<()>

Attach the same private ratchet owner used by the application’s receiver. Reattaching that Arc is idempotent; conflicting owners are rejected. The owner remains attached across destination deregistration/re-registration.

pub async fn announce( &self, dest: &Destination, identity: &Identity, app_data: Option<&[u8]>, ) -> Result<(), TransmissionError>

Wait for capacity, then transmit an announcement on all selected local interfaces.

Success means all selected writers accepted the complete packet, not remote delivery or subsequent relay. An error can follow partial delivery on one or more interfaces. No eligible interface returns NoRoute. Cancelling before admission sends nothing; after admission, transmission continues. Shared-client replay metadata travels in the same admitted event as the packet, never in a separate event from a rejected send.

pub fn try_announce( &self, dest: &Destination, identity: &Identity, app_data: Option<&[u8]>, ) -> Result<TransmissionReceipt, TransmissionError>

Try admission immediately; await the receipt for the exact same result as announce. QueueFull guarantees nothing was admitted.

pub async fn send_packet( &self, dest: &Destination, data: &[u8], ) -> Result<PacketHash, TransmissionError>

Wait for capacity and local transmission, returning the hash for proof tracking.

Uses the same all-selected-writers contract as announce and the same admission/completion capacity as send_on_link. No remote delivery is promised; errors may follow partial transmission. Dropping an admitted future does not cancel its send. No async runtime is required.

pub fn try_send_packet( &self, dest: &Destination, data: &[u8], ) -> Result<PacketSendReceipt, TransmissionError>

Try admission immediately. The receipt exposes the packet hash and resolves to the same result as send_packet, after local writes. QueueFull guarantees nothing was admitted and is safe to retry.

pub fn announce_queued( &self, dest: &Destination, identity: &Identity, app_data: Option<&[u8]>, ) -> Result<(), SendError>

Build and broadcast an announce for a destination (queue-only compatibility API).

Success means driver submission, not transmission. Use announce or try_announce for confirmed local transmission.

The identity is used to sign the announce. Must be the identity that owns the destination (i.e. identity.hash() matches dest.identity_hash).

pub fn send_packet_queued( &self, dest: &Destination, data: &[u8], ) -> Result<PacketHash, SendError>

Queue an encrypted (SINGLE) or plaintext (PLAIN) packet to a destination.

Queue-only compatibility API: use send_packet or try_send_packet for confirmed local transmission. The returned hash does not mean sent.

For SINGLE destinations, dest.public_key must be set (OUT direction). Returns the packet hash for proof tracking.

pub fn deliver_decrypted( &self, dest: &Destination, identity: &Identity, ) -> Result<(), SendError>

Deliver single packets addressed to dest, a local destination, decrypted: through Callbacks::on_packet_received in place of on_local_delivery, decrypted on the node’s proof pool when it has one, so a receiver is not bound by decrypting on its own thread. They are decrypted with the destination’s attached ratchets (attach_local_ratchets) when it has them, else with identity, which must hold its private keys. Packets that do not decrypt are dropped and not proved. Deregistering the destination ends it.

pub fn send_packet_deferred( &self, dest: &Destination, data: &[u8], ) -> Result<SendTicket, SendError>

Queue a packet for a SINGLE destination without encrypting it on this thread, unlike send_packet_queued: the node encrypts it (on its proof pool when it has one; on this thread when the process may use one CPU only) and reports the packet hash through Callbacks::on_packet_sent with the returned ticket, before sending it. A sender is then not bound by its own thread’s encryption, one X25519 key generation and exchange per packet.

dest.public_key must be set (OUT direction). Like send_packet_queued, queueing does not mean sent.

pub fn register_destination_with_proof( &self, dest: &Destination, signing_key: Option<[u8; 64]>, ) -> Result<(), SendError>

Register a destination with the transport engine and set its proof strategy.

signing_key is the full 64-byte identity private key (X25519 32 bytes + Ed25519 32 bytes), needed for ProveAll/ProveApp to sign proof packets.

pub fn request_path(&self, dest_hash: &DestHash) -> Result<(), SendError>

Request a path to a destination from the network.

pub fn has_path(&self, dest_hash: &DestHash) -> Result<bool, SendError>

Check if a path exists to a destination (synchronous query).

pub fn hops_to(&self, dest_hash: &DestHash) -> Result<Option<u8>, SendError>

Get hop count to a destination (synchronous query).

pub fn recall_identity( &self, dest_hash: &DestHash, ) -> Result<Option<AnnouncedIdentity>, SendError>

Recall the identity information for a previously announced destination.

pub fn recall_destination_stamp( &self, dest_hash: &DestHash, ) -> Result<Option<DestinationStampInfo>, SendError>

Stamp value and announced link request cost recorded from a known destination’s last announce.

pub fn known_destinations( &self, ) -> Result<Vec<KnownDestinationEntry>, SendError>

List known destinations and their lifecycle state.

pub fn retain_known_destination( &self, dest_hash: &DestHash, ) -> Result<bool, SendError>

Mark a known destination as retained.

pub fn retain_identity( &self, identity_hash: &IdentityHash, ) -> Result<bool, SendError>

Mark all known destinations announced by an identity as retained.

pub fn unretain_known_destination( &self, dest_hash: &DestHash, ) -> Result<bool, SendError>

Clear the retained flag on a known destination.

pub fn mark_known_destination_used( &self, dest_hash: &DestHash, ) -> Result<bool, SendError>

Mark a known destination as used.

pub fn load_hook( &self, name: String, wasm_bytes: Vec<u8>, attach_point: String, priority: i32, ) -> Result<Result<(), String>, SendError>

Load an in-memory WASM hook at runtime.

pub fn load_hook_file( &self, name: String, path: String, hook_type: String, attach_point: String, priority: i32, ) -> Result<Result<(), String>, SendError>

Load a hook from a server-local filesystem path at runtime.

pub fn load_builtin_hook( &self, name: String, builtin_id: String, attach_point: String, priority: i32, ) -> Result<Result<(), String>, SendError>

Load a registered built-in hook at runtime.

pub fn unload_hook( &self, name: String, attach_point: String, ) -> Result<Result<(), String>, SendError>

Unload a hook at runtime.

pub fn reload_hook( &self, name: String, attach_point: String, wasm_bytes: Vec<u8>, ) -> Result<Result<(), String>, SendError>

Reload an in-memory WASM hook at runtime (detach + recompile + reattach with same priority).

pub fn reload_hook_file( &self, name: String, attach_point: String, path: String, hook_type: String, ) -> Result<Result<(), String>, SendError>

Reload a hook from a server-local filesystem path at runtime.

pub fn reload_builtin_hook( &self, name: String, attach_point: String, builtin_id: String, ) -> Result<Result<(), String>, SendError>

Reload a registered built-in hook at runtime.

pub fn set_hook_enabled( &self, name: String, attach_point: String, enabled: bool, ) -> Result<Result<(), String>, SendError>

Enable or disable a loaded hook at runtime.

pub fn set_hook_priority( &self, name: String, attach_point: String, priority: i32, ) -> Result<Result<(), String>, SendError>

Update the priority of a loaded hook at runtime.

pub fn list_hooks(&self) -> Result<Vec<HookInfo>, SendError>

List all loaded hooks.

pub fn event_sender(&self) -> &EventSender

Get the event sender for direct event injection.

pub fn set_tick_interval(&self, ms: u64) -> u64

Set the tick interval in milliseconds. Default is 1000 (1 second). Changes take effect on the next tick cycle. Values are clamped to the range 100..=10000. Returns the actual stored value (which may differ from ms if clamped).

pub fn tick_interval(&self) -> u64

Get the current tick interval in milliseconds.

pub fn shutdown(self)

Shut down the node. Blocks until the driver thread exits.

impl RnsNode

pub fn wants_destination_type(&self, full_name: &str) -> bool

Reticulum.wants_destination_type: this application needs announces of the destination type full_name, such as rncp.receive.

The type is registered with the local transport and, on a shared instance client, with the shared instance, whose answer is returned. Returns false for a blocked type.

pub fn unwants_destination_type(&self, full_name: &str) -> bool

Reticulum.unwants_destination_type: withdraw a need registered with Self::wants_destination_type. Returns whether it was registered.

pub fn unwants_all_destination_types(&self) -> bool

Reticulum.unwants_all_destination_types: withdraw every destination type this application registered.

pub fn required_announces_only(&self, enabled: bool) -> bool

Reticulum.required_announces_only: on a shared instance client, let through only announces of the types this application registered and the shared instance’s own destinations. Other nodes return false, so an application cannot squelch announces for the node as a whole.

pub fn connect_shared( config: SharedClientConfig, callbacks: Box<dyn Callbacks>, ) -> Result<Self>

Connect to an existing shared instance as a client.

The client runs transport_enabled: false — it does no routing, but can register destinations and send/receive packets through the daemon.

pub fn connect_shared_from_config( config_path: Option<&Path>, callbacks: Box<dyn Callbacks>, ) -> Result<Self>

Connect to a shared instance, with config loaded from a config directory.

Reads the config file to determine instance_name and ports.

Trait Implementations

impl Drop for RnsNode

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.