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 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 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_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_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 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 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 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.