RNS::Transport
The routing and packet delivery engine for Reticulum. Transport manages the full lifecycle of packets: outbound routing via path and link tables, inbound processing (validation, announce handling, link requests, data delivery, and proof forwarding), and periodic maintenance of routing state. All state is held at the module level and accessed through class methods.
Constants
─── App name ──────────────────────────────────────────────────
Transport type constants: identify how a packet traverses the network. BROADCAST is a direct, one-hop delivery; TRANSPORT uses multi-hop routing; RELAY and TUNNEL provide indirect forwarding paths.
─── Announce table entry indices ──────────────────────────────
─── Link table entry indices ──────────────────────────────────
Path table entry indices: positional offsets used when interoperating with the Python-format path table arrays.
─── Reverse table entry indices ───────────────────────────────
─── Tunnel table entry indices ────────────────────────────────
Job interval constants: how often each periodic maintenance task runs.
Link timeout derived from Link stale time
Path request constants: control timing and rate-limiting for on-demand path discovery requests.
Pathfinder constants: govern path discovery and announce propagation limits, including maximum hop count, retry policy, and path expiry.
Reachability constants: describe how a destination can be reached. DIRECT means the destination is on a locally attached interface; TRANSPORT means it is reachable via multi-hop routing.
Timeout and capacity limits for routing table entries, receipts, and in-memory caches. LINK_TIMEOUT is set after Link is defined; use class method for now
Path state constants: track responsiveness of known destinations.
Class methods
Activates a link by moving it from pending to active. The link must be in pending_links and have ACTIVE status.
Extracts the announce emission timebase from a packet's data.
Blackhole an identity so that its announces and packets are dropped. Returns true on success, nil if already blackholed, false on error. Matches Python Transport.blackhole_identity().
Caches a packet to storage. Packets are stored exactly as they arrived over their interface (hop count not yet incremented). When force_cache is false, should_cache() is consulted.
Caches a packet to storage.
Requests a cached packet either from local cache or from the network.
Handles a cache request packet. Retrieves the requested packet from the local cache and replays it to Transport.
Checks announce rate limiting for a destination. Returns true if the announce should be rate-blocked.
Cleans the announce file cache. Removes cached announce files that are no longer referenced by the path table or tunnel table.
Removes a previously registered destination from Transport.
Drops all announce queues on all interfaces. Currently a no-op since interface objects are not yet implemented.
Exit handler: persists all transport state to disk. Should be called before shutdown.
Expires the path to the specified destination by setting its timestamp to 0, which will cause it to be culled on the next jobs pass. Returns true if a path existed, false otherwise.
Finds the best active link for a destination hash. Currently returns the first match; future versions may score links by quality metrics.
Utility to find an interface hash in the interfaces list.
Finds an active link matching the given destination hash (link_id).
Returns the first hop timeout for the specified destination. Without interface bitrate info (not yet available), returns DEFAULT_PER_HOP_TIMEOUT.
Retrieves a cached packet from storage. Returns the packet if found, nil otherwise.
Handles a tunnel establishment or restoration. For new tunnels, creates an entry in the tunnels table. For existing tunnels, restores paths and updates the interface.
Returns the number of hops to the specified destination, or PATHFINDER_M if the number of hops is unknown.
Processes a raw inbound packet received from a network interface. Validates IFAC flags, unpacks the packet, checks for duplicates, and dispatches to the appropriate handler: announce processing, link request/proof handling, data delivery to local destinations, or multi-hop forwarding via the path and link tables. Backward-compatible overload accepting an interface hash (for tests and call sites that don't have the interface object).
Processes an inbound announce packet. This is the core of the announce handling logic from RNS/Transport.py's inbound() method.
Returns true if the announce was valid and processed, false otherwise.
Invokes registered announce handler callbacks for a processed announce.
Checks if an interface hash corresponds to a local client interface.
Checks if an interface object corresponds to a local client interface.
Loads the path table from disk. Returns the number of entries loaded, or -1 on error.
Loads the tunnel table from disk. Returns the number of tunnel entries loaded, or -1 on error.
Marks the path to the specified destination as responsive.
Marks the path for a destination as unknown, used when the announce table entry should be reconsidered.
Marks the path to the specified destination as unknown state.
Marks the path to the specified destination as unresponsive.
Returns the next hop hash for the specified destination, or nil if unknown.
Returns the receiving interface hash for the specified destination, or nil if unknown.
Routes an outbound packet for delivery. Consults the path table,
link table, and tunnel table to determine the correct next-hop
interface. Handles broadcast, transport, and direct destination
types. Returns true if the packet was successfully sent.
Filters packets for deduplication and validity. Returns true if the packet should be processed.
Checks if a packet hash is in the deduplication hashlist.
Returns true if the path to the specified destination is marked as unresponsive.
Processes the announce retransmission table. Called periodically by the Transport jobs loop. Returns an array of packets to send.
Registers a destination with Transport so it can receive packets.
Sets the destination's MTU and ensures no duplicate inbound
destinations are registered (raises KeyError on conflict).
Hash-only overload for backward compatibility (used by some specs).
Register an interface. Stores both the hash (for broadcast iteration) and the object (for transmit resolution and inbound dispatch).
Registers a link. Initiator links go to pending_links, responder links go directly to active_links.
Removes a path table entry for the given destination hash. Returns true if the entry existed, false otherwise.
Requests a path to the destination from the network. Creates a path request packet and broadcasts it.
Saves the packet hashlist to disk using MessagePack.
Saves the path table to disk using MessagePack serialization. Each entry is serialized as: [destination_hash, timestamp, received_from, hops, expires, random_blobs, interface_hash, packet_hash]
Saves the tunnel table to disk using MessagePack.
Determines whether a packet should be cached. Currently returns false — the Python implementation has this disabled with a TODO to rework the caching system.
Initializes and starts the Transport layer. Creates or loads the transport identity, loads persisted state (packet hashlist, path table, tunnel table), sets up control destinations, and starts the periodic job fiber.
Creates and returns a tunnel synthesis packet data payload. Returns {tunnel_id, data} or nil if no identity is set.
Extracts a timebase value from a random blob (bytes 5..9). The random blob is 10 bytes; bytes 5..9 encode an emission timestamp.
Extracts the maximum timebase from an array of random blobs.
Transmits raw data on an interface (identified by hash). Resolves the interface object from @@interface_objects, applies IFAC masking if the interface has IFAC enabled, and calls process_outgoing.
Validates and processes a tunnel synthesis request. Called when a tunnel synthesis DATA packet is received. data format: public_key + interface_hash + random_hash + signature
Remove an identity from the blackhole list. Returns true on success, nil if not blackholed, false on error. Matches Python Transport.unblackhole_identity().