Struct Router 

pub struct Router { /* private fields */ }

Telemetry Router for handling incoming and outgoing telemetry packets. Supports queuing, processing, and dispatching to local endpoint handlers. Thread-safe via internal locking.

Implementations

impl Router

Router implementation

pub fn note_side_link_probe_sample( &self, side: RouterSideId, bytes: usize, duration_ms: u64, ) -> TelemetryResult<()>

Seed adaptive route selection with a transport-measured link probe.

Call this after a side-specific bring-up probe, or whenever the transport already knows the duration for a frame. The router does not emit synthetic probe frames by itself.

pub fn update_network_time_source( &self, source: &str, priority: u64, time: PartialNetworkTime, ttl_ms: Option<u64>, )

Inserts or updates a named network-time source with an optional expiration TTL.

pub fn set_local_network_time(&self, time: PartialNetworkTime)

Sets the local node’s network time using any combination of date, time, and sub-second fields.

pub fn clear_local_network_time(&self)

Removes all locally supplied network-time fragments from the assembled clock.

pub fn set_local_network_date(&self, year: i32, month: u8, day: u8)

Sets only the local calendar date portion of network time.

pub fn set_local_network_time_hm(&self, hour: u8, minute: u8)

Sets the local time of day to hour and minute precision.

pub fn set_local_network_time_hms(&self, hour: u8, minute: u8, second: u8)

Sets the local time of day to second precision.

pub fn set_local_network_time_hms_millis( &self, hour: u8, minute: u8, second: u8, millisecond: u16, )

Sets the local time of day with millisecond precision.

pub fn set_local_network_time_hms_nanos( &self, hour: u8, minute: u8, second: u8, nanosecond: u32, )

Sets the local time of day with nanosecond precision.

pub fn set_local_network_datetime( &self, year: i32, month: u8, day: u8, hour: u8, minute: u8, second: u8, )

Sets a complete local date and time with second precision.

pub fn set_local_network_datetime_millis( &self, year: i32, month: u8, day: u8, hour: u8, minute: u8, second: u8, millisecond: u16, )

Sets a complete local date and time with millisecond precision.

pub fn set_local_network_datetime_nanos( &self, year: i32, month: u8, day: u8, hour: u8, minute: u8, second: u8, nanosecond: u32, )

Sets a complete local date and time with nanosecond precision.

pub fn clear_network_time_source(&self, source: &str)

Removes a previously registered named network-time source.

pub fn set_timesync_config(&self, cfg: Option<TimeSyncConfig>)

Replaces the active time sync configuration and resets runtime state derived from it.

pub fn network_time(&self) -> Option<NetworkTimeReading>

Returns the best currently known network-time reading, if any.

pub fn network_time_ms(&self) -> Option<u64>

Returns the current network time as Unix milliseconds when available.

pub fn poll_timesync(&self) -> TelemetryResult<bool>

Runs one time sync maintenance cycle and queues any required announce or request packets.

pub fn new(cfg: RouterConfig) -> Self

Create a new Router with an internal monotonic clock.

pub fn new_with_clock( cfg: RouterConfig, clock: Box<dyn Clock + Send + Sync>, ) -> Self

Create a new Router with the specified router configuration and clock.

pub fn sender(&self) -> Arc<str>

pub fn current_address(&self) -> NodeAddress

pub fn hostname(&self) -> Arc<str>

pub fn address_book(&self) -> Vec<AddressBookEntry>

pub fn resolve_hostname(&self, hostname: &str) -> Option<AddressBookEntry>

pub fn resolve_address(&self, address: NodeAddress) -> Option<AddressBookEntry>

pub fn bind_p2p_port<F>(&self, port: P2pPort, f: F) -> TelemetryResult<()>

where F: Fn(P2pMessage<'_>) -> TelemetryResult<()> + Send + Sync + 'static,

pub fn clear_p2p_port(&self, port: P2pPort)

pub fn bind_p2p_stream_port<F>( &self, port: P2pPort, f: F, ) -> TelemetryResult<()>

where F: Fn(P2pStreamEvent<'_>) -> TelemetryResult<()> + Send + Sync + 'static,

pub fn clear_p2p_stream_port(&self, port: P2pPort)

pub fn send_p2p_to_hostname( &self, hostname: &str, dst_port: P2pPort, src_port: P2pPort, payload: &[u8], ) -> TelemetryResult<()>

pub fn send_p2p_to_address( &self, address: NodeAddress, dst_port: P2pPort, src_port: P2pPort, payload: &[u8], ) -> TelemetryResult<()>

pub fn open_p2p_stream_to_hostname( &self, hostname: &str, dst_port: P2pPort, src_port: P2pPort, ) -> TelemetryResult<P2pStreamId>

pub fn open_p2p_stream_to_address( &self, address: NodeAddress, dst_port: P2pPort, src_port: P2pPort, ) -> TelemetryResult<P2pStreamId>

pub fn send_p2p_stream( &self, stream_id: P2pStreamId, payload: &[u8], ) -> TelemetryResult<()>

pub fn close_p2p_stream(&self, stream_id: P2pStreamId) -> TelemetryResult<()>

pub fn reset_p2p_stream(&self, stream_id: P2pStreamId) -> TelemetryResult<()>

pub fn set_sender<S: AsRef<str>>(&self, sender: S)

pub fn add_side_packed<F>(&self, name: &'static str, tx: F) -> RouterSideId

where F: Fn(&[u8]) -> TelemetryResult<()> + Send + Sync + 'static,

Register a side whose TX callback consumes packed packet bytes.

name is exported in topology/debug views and does not affect routing semantics. tx is called whenever the router decides to send a packet toward this side.

The default options disable the router’s per-link reliable framing on this side. Use Router::add_side_packed_with_options when this hop should participate in router reliable ACK/retransmit behavior.

pub fn add_side_packed_small_packets<F>( &self, name: &'static str, tx: F, max_frame_bytes: usize, ) -> RouterSideId

where F: Fn(&[u8]) -> TelemetryResult<()> + Send + Sync + 'static,

Register a packed side with the compact small-packet transport preset enabled.

max_frame_bytes == 0 keeps header-template reuse enabled without chunking.

pub fn add_side_packed_with_options<F>( &self, name: &'static str, tx: F, opts: RouterSideOptions, ) -> RouterSideId

where F: Fn(&[u8]) -> TelemetryResult<()> + Send + Sync + 'static,

Register a packed-output side with explicit side options.

opts.reliable_enabled enables the router’s per-hop reliable framing on this side only. That means reliable schema traffic on this side uses router-managed ACKs, packet requests, and retransmits before the bytes reach tx.

opts.link_local_enabled allows link-local-only endpoints and discovery routes to use this side. ingress_enabled and egress_enabled set the initial directional policy.

pub fn add_side_packet<F>(&self, name: &'static str, tx: F) -> RouterSideId

where F: Fn(&Packet) -> TelemetryResult<()> + Send + Sync + 'static,

Register a side whose TX callback receives decoded Packet values.

Packet-output sides do not preserve the packed reliable hop framing, so RouterSideOptions::reliable_enabled only has effect for packed sides.

pub fn add_side_packet_with_options<F>( &self, name: &'static str, tx: F, opts: RouterSideOptions, ) -> RouterSideId

where F: Fn(&Packet) -> TelemetryResult<()> + Send + Sync + 'static,

Register a packet-output side with explicit side options.

opts.reliable_enabled still records the operator’s intent for this side, but packet-based callbacks receive decoded packets rather than the router’s packed reliable hop framing. For router-managed per-link reliable sequencing and ACKs, use a packed side instead.

pub fn remove_side(&self, side: RouterSideId) -> TelemetryResult<()>

Remove a side while keeping existing side IDs stable.

side must be an id returned earlier by one of the add_side_* calls. Removed side IDs are tombstoned rather than renumbered so cached IDs for the remaining sides stay valid.

pub fn set_side_ingress_enabled( &self, side: RouterSideId, enabled: bool, ) -> TelemetryResult<()>

Enable or disable ingress processing for a registered side.

When enabled is false, packets tagged as arriving from side are rejected before local delivery, discovery learning, or forwarding.

pub fn set_side_egress_enabled( &self, side: RouterSideId, enabled: bool, ) -> TelemetryResult<()>

Enable or disable egress toward a registered side.

When enabled is false, the router keeps the side but stops routing packets toward it.

pub fn set_source_route_mode( &self, src: Option<RouterSideId>, mode: RouteSelectionMode, ) -> TelemetryResult<()>

Set the route-selection policy for traffic originating from src.

src == None targets locally-originated router TX. src == Some(side) targets traffic that was received from a specific ingress side. mode only matters when more than one destination side is currently eligible.

pub fn clear_source_route_mode( &self, src: Option<RouterSideId>, ) -> TelemetryResult<()>

Clear any source-specific route-selection override for src.

pub fn set_route_weight( &self, src: Option<RouterSideId>, dst: RouterSideId, weight: u32, ) -> TelemetryResult<()>

Set the weighted-routing weight from src toward dst.

Higher weight values make dst more likely to be chosen when the source route mode is RouteSelectionMode::Weighted. src == None applies to locally-originated TX.

pub fn clear_route_weight( &self, src: Option<RouterSideId>, dst: RouterSideId, ) -> TelemetryResult<()>

Clear a previously configured weighted-routing weight override.

pub fn set_route_priority( &self, src: Option<RouterSideId>, dst: RouterSideId, priority: u32, ) -> TelemetryResult<()>

Set the failover priority from src toward dst.

Lower numeric priority wins when the source route mode is RouteSelectionMode::Failover. src == None applies to locally-originated TX.

pub fn clear_route_priority( &self, src: Option<RouterSideId>, dst: RouterSideId, ) -> TelemetryResult<()>

Clear a previously configured failover priority override.

pub fn set_route( &self, src: Option<RouterSideId>, dst: RouterSideId, enabled: bool, ) -> TelemetryResult<()>

Allow or block routing from src toward dst.

src == None controls locally-originated router TX. enabled == false is the sink-like building block for disabling specific directions without changing router construction mode.

pub fn set_typed_route( &self, src: Option<RouterSideId>, ty: DataType, dst: RouterSideId, enabled: bool, ) -> TelemetryResult<()>

Allow or block routing for a specific DataType from src toward dst.

Typed route rules act as allowlists once any rule exists for the (src, ty) pair. src == None targets locally-originated router TX.

pub fn clear_typed_route( &self, src: Option<RouterSideId>, ty: DataType, dst: RouterSideId, ) -> TelemetryResult<()>

Clear a typed route override for the (src, ty, dst) triple.

pub fn clear_route( &self, src: Option<RouterSideId>, dst: RouterSideId, ) -> TelemetryResult<()>

Clear a non-typed route override so the router falls back to default behavior.

pub fn announce_discovery(&self) -> TelemetryResult<()>

Queue a built-in discovery advertisement describing this router’s local endpoints.

pub fn announce_leave(&self) -> TelemetryResult<()>

Broadcast that this router is leaving so peers can prune topology immediately.

pub fn poll_discovery(&self) -> TelemetryResult<bool>

Queue a discovery advertisement if the adaptive cadence says one is due.

pub fn request_topology(&self) -> TelemetryResult<()>

pub fn request_schema(&self) -> TelemetryResult<()>

pub fn enable_managed_variable(&self, ty: DataType) -> TelemetryResult<()>

Mark a data type as a network-managed variable.

The router caches the latest packet for this type when it is locally transmitted or received from the network. Peers can request the latest cached value and the router will replay the original value packet, so user endpoint handlers see the same API shape as a normal update.

pub fn enable_network_variable( &self, ty: DataType, permissions: NetworkVariablePermissions, ) -> TelemetryResult<()>

Mark a data type as a network variable with local read/write permissions.

Users do not register a separate endpoint for network variables. Values are cached by data type and refreshed through SEDSnet’s internal managed-variable control packets.

pub fn on_network_variable_update<F>( &self, ty: DataType, f: F, ) -> TelemetryResult<()>

where F: Fn(&Packet) -> TelemetryResult<()> + Send + Sync + 'static,

Register a callback that runs when an inbound network update changes this variable cache.

The callback is invoked after the router state lock is released, so it may call back into the router. Local set_network_variable and seed_managed_variable calls update the cache without invoking this network-update callback.

pub fn disable_managed_variable(&self, ty: DataType)

pub fn seed_managed_variable(&self, pkt: Packet) -> TelemetryResult<()>

pub fn cached_managed_variable(&self, ty: DataType) -> Option<Packet>

pub fn set_network_variable(&self, pkt: Packet) -> TelemetryResult<()>

Set a network variable for the whole network, permission policy allowing.

The packet is cached locally and sent as normal user data. Routers that have seen or enabled this variable update their local cache internally; applications do not need to register a managed-variable endpoint.

pub fn get_network_variable( &self, ty: DataType, stale_after_ms: Option<u64>, ) -> TelemetryResult<Option<Packet>>

Read a cached network variable, requesting a refresh if missing or stale.

Returns the cached value when present. If the value is missing, this queues an internal managed-variable request and returns Ok(None). If the value is stale, this queues a refresh request and returns the stale cached value so callers can continue operating while the network catches up.

pub fn get_cached_network_variable( &self, ty: DataType, ) -> TelemetryResult<Option<Packet>>

Read a cached network variable without issuing a network refresh.

pub fn request_managed_variable(&self, ty: DataType) -> TelemetryResult<()>

pub fn request_managed_variable_by_name( &self, ty_name: &str, ) -> TelemetryResult<()>

pub fn export_topology(&self) -> TopologySnapshot

Export the current discovery-driven network topology view.

pub fn client_stats(&self, sender_id: &str) -> Option<ClientStatsSnapshot>

pub fn export_runtime_stats(&self) -> RuntimeStatsSnapshot

pub fn export_memory_layout_json(&self) -> String

Export current router memory usage/layout as JSON for profiling.

pub fn process_tx_queue(&self) -> TelemetryResult<()>

Drain the transmit queue fully.

pub fn process_all_queues(&self) -> TelemetryResult<()>

Drain both TX and RX queues fully (same semantics as *_with_timeout(0)).

pub fn clear_queues(&self)

Clear both the transmit and receive queues without processing.

pub fn clear_rx_queue(&self)

Clear only the receive queue without processing.

pub fn clear_tx_queue(&self)

Clear only the transmit queue without processing.

pub fn process_tx_queue_with_timeout( &self, timeout_ms: u32, ) -> TelemetryResult<()>

Process packets in the transmit queue for up to timeout_ms milliseconds. If timeout_ms == 0, drains the queue fully.

pub fn process_rx_queue_with_timeout( &self, timeout_ms: u32, ) -> TelemetryResult<()>

Process packets in the receive queue for up to timeout_ms milliseconds. If timeout_ms == 0, drains the queue fully.

pub fn process_all_queues_with_timeout( &self, timeout_ms: u32, ) -> TelemetryResult<()>

Process both transmit and receive queues for up to timeout_ms milliseconds. If timeout_ms == 0, drains both queues fully.

pub fn periodic(&self, timeout_ms: u32) -> TelemetryResult<()>

Runs one application-loop maintenance cycle.

This polls built-in time sync and discovery when those features are compiled in, then drains queued TX/RX work for up to timeout_ms milliseconds.

pub fn periodic_no_timesync(&self, timeout_ms: u32) -> TelemetryResult<()>

Runs one application-loop maintenance cycle without polling built-in time sync.

Discovery is still polled when that feature is compiled in, then queued TX/RX work is drained for up to timeout_ms milliseconds.

pub fn process_rx_queue(&self) -> TelemetryResult<()>

Drain the receive queue fully.

pub fn rx_packed_queue(&self, bytes: &[u8]) -> TelemetryResult<()>

Enqueue packed bytes for RX processing as locally-originated input.

pub fn rx_packed_queue_isr(&self, bytes: &[u8]) -> TelemetryResult<()>

ISR-safe, non-blocking enqueue of packed bytes for RX processing.

Returns TelemetryError::Io("rx queue busy") if another context is currently mutating the ISR RX queue.

pub fn rx_queue(&self, pkt: Packet) -> TelemetryResult<()>

Enqueue a decoded packet for RX processing as locally-originated input.

pub fn rx_queue_isr(&self, pkt: Packet) -> TelemetryResult<()>

ISR-safe, non-blocking enqueue of a packet for RX processing.

Returns TelemetryError::Io("rx queue busy") if another context is currently mutating the ISR RX queue.

pub fn rx_queue_from_side( &self, pkt: Packet, side: RouterSideId, ) -> TelemetryResult<()>

Enqueue a decoded packet for RX processing with an explicit ingress side.

pub fn rx_queue_from_side_isr( &self, pkt: Packet, side: RouterSideId, ) -> TelemetryResult<()>

ISR-safe, non-blocking enqueue of a packet with explicit source side.

Returns TelemetryError::Io("rx queue busy") if another context is currently mutating the ISR RX queue.

pub fn rx_packed_queue_from_side( &self, bytes: &[u8], side: RouterSideId, ) -> TelemetryResult<()>

Enqueue packed bytes for RX processing with an explicit ingress side.

pub fn rx_packed_queue_from_side_isr( &self, bytes: &[u8], side: RouterSideId, ) -> TelemetryResult<()>

ISR-safe, non-blocking enqueue of packed bytes with source side.

Returns TelemetryError::Io("rx queue busy") if another context is currently mutating the ISR RX queue.

pub fn rx_packed(&self, bytes: &[u8]) -> TelemetryResult<()>

Process packed bytes immediately as locally-originated input.

If this call occurs while a side TX callback is already on the stack, the bytes are queued instead of being processed re-entrantly.

pub fn rx(&self, pkt: &Packet) -> TelemetryResult<()>

Process a decoded packet immediately as locally-originated input.

If this call occurs while a side TX callback is already on the stack, the packet is queued instead of being processed re-entrantly.

pub fn rx_from_side( &self, pkt: &Packet, side: RouterSideId, ) -> TelemetryResult<()>

Process a decoded packet immediately with an explicit ingress side id.

If this call occurs while a side TX callback is already on the stack, the packet is queued instead of being processed re-entrantly.

pub fn rx_packed_from_side( &self, bytes: &[u8], side: RouterSideId, ) -> TelemetryResult<()>

Process packed bytes immediately with an explicit ingress side id.

If this call occurs while a side TX callback is already on the stack, the bytes are queued instead of being processed re-entrantly.

pub fn tx(&self, pkt: Packet) -> TelemetryResult<()>

Transmit a decoded packet immediately.

The router delivers locally where appropriate and forwards toward eligible sides. If called from inside a side TX callback, the packet is queued instead of being sent re-entrantly.

pub fn tx_packed(&self, pkt: Arc<[u8]>) -> TelemetryResult<()>

Transmit packed bytes immediately.

If called from inside a side TX callback, the bytes are queued instead of being sent re-entrantly.

pub fn tx_queue(&self, pkt: Packet) -> TelemetryResult<()>

Queue a decoded packet for later transmission.

pub fn tx_packed_queue(&self, data: Arc<[u8]>) -> TelemetryResult<()>

Queue packed bytes for later transmission.

pub fn log<T: LeBytes>(&self, ty: DataType, data: &[T]) -> TelemetryResult<()>

Build a packet from typed elements and send it immediately.

ty selects the schema message type and data must match that type’s expected element width and count. If called from inside a side TX callback, the built packet is queued.

pub fn log_queue<T: LeBytes>( &self, ty: DataType, data: &[T], ) -> TelemetryResult<()>

Build a packet from typed elements and queue it for later transmission.

pub fn log_ts<T: LeBytes>( &self, ty: DataType, timestamp: u64, data: &[T], ) -> TelemetryResult<()>

Build a packet with an explicit timestamp and send it immediately.

pub fn log_queue_ts<T: LeBytes>( &self, ty: DataType, timestamp: u64, data: &[T], ) -> TelemetryResult<()>

Build a packet with an explicit timestamp and queue it for later transmission.

Trait Implementations

impl Debug for Router

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.