tiny.reticulum.node.transport

1/// The eight tables a node needs to carry traffic for others, together with the2/// hash that names it and the flag that turns the carrying on. A caller holds3/// one of these per node, and every transport step reaches its store through4/// it. The eight tables are carved from one block of caller storage whose5/// length has to equal the derived byte count exactly.6pub const State = struct {7    phase: alloc_phase.capacity.Phase,8    capacity: Capacity,9    storage: Storage,10    paths: path.Table,11    announces: announces.Table,12    reverse_entries: reverse.Table,13    tags: packet.hashlist.Table,14    inflight_requests: inflight.Table,15    discoveries: discoveries.Table,16    links: links.Table,17    link_entries: link_entries.Table,18    identity_hash: ?[16]u8 = null,19    enabled: bool = false,2021    pub const storage_alignment: usize = 8;22    pub const Storage = []align(storage_alignment) u8;23    pub const Limits: type = StateLimits;24    pub const Capacity: type = StateCapacity;25    pub const InitError = Capacity.DeriveError || error{StorageLengthMismatch};26    pub const work_limits: alloc_phase.capacity.WorkLimits = .{27        .transition_steps_max = 8,28        .cleanup_steps_per_call_max = 0,29        .cleanup_calls_at_capacity_max = 0,30    };31    pub const claim: alloc_phase.capacity.Declaration = .{32        .source = .{33            .id = "reticulum.transport",34            .kind = .phase_static,35            .limit_source = .caller,36            .storage = .{37                .covered = &.{.{38                    .id = "caller_transport_tables",39                    .lifetime = .transferred,40                    .detail = "caller storage for routing, relay, path request, and link tables",41                }},42                .excluded = &.{"relayed, rebroadcast, request, and link frames in effect storage"},43            },44            .capacity = .{45                .inputs = &.{46                    alloc_phase.capacity.bindInput(Limits, "paths", "paths_max"),47                    alloc_phase.capacity.bindInput(Limits, "announces", "announces_max"),48                    alloc_phase.capacity.bindInput(49                        Limits,50                        "reverse_entries",51                        "reverse_entries_max",52                    ),53                    alloc_phase.capacity.bindInput(54                        Limits,55                        "path_request_tags",56                        "path_request_tags_max",57                    ),58                    alloc_phase.capacity.bindInput(59                        Limits,60                        "inflight_requests",61                        "inflight_requests_max",62                    ),63                    alloc_phase.capacity.bindInput(Limits, "discoveries", "discoveries_max"),64                    alloc_phase.capacity.bindInput(Limits, "links", "links_max"),65                    alloc_phase.capacity.bindInput(66                        Limits,67                        "link_entries",68                        "link_entries_max",69                    ),70                },71                .type_selectors = &.{72                    alloc_phase.capacity.bindType(path.Entry, "path"),73                    alloc_phase.capacity.bindType(announces.Entry, "announce"),74                    alloc_phase.capacity.bindType(reverse.Entry, "reverse_entry"),75                    alloc_phase.capacity.bindType(packet.Hash, "path_request_tag"),76                    alloc_phase.capacity.bindType(inflight.Entry, "inflight_request"),77                    alloc_phase.capacity.bindType(discoveries.Entry, "discovery"),78                    alloc_phase.capacity.bindType(links.Entry, "link"),79                    alloc_phase.capacity.bindType(link_entries.Entry, "link_entry"),80                },81                .nodes = &.{82                    .{ .input = 0 },83                    .{ .scale = .{84                        .node = 0,85                        .coefficient = .{ .size_of_concrete_type = 0 },86                    } },87                    .{ .input = 1 },88                    .{ .scale = .{89                        .node = 2,90                        .coefficient = .{ .size_of_concrete_type = 1 },91                    } },92                    .{ .add = .{ .left = 1, .right = 3 } },93                    .{ .input = 2 },94                    .{ .scale = .{95                        .node = 5,96                        .coefficient = .{ .size_of_concrete_type = 2 },97                    } },98                    .{ .add = .{ .left = 4, .right = 6 } },99                    .{ .input = 3 },100                    .{ .scale = .{101                        .node = 8,102                        .coefficient = .{ .size_of_concrete_type = 3 },103                    } },104                    .{ .add = .{ .left = 7, .right = 9 } },105                    .{ .input = 4 },106                    .{ .scale = .{107                        .node = 11,108                        .coefficient = .{ .size_of_concrete_type = 4 },109                    } },110                    .{ .add = .{ .left = 10, .right = 12 } },111                    .{ .input = 5 },112                    .{ .scale = .{113                        .node = 14,114                        .coefficient = .{ .size_of_concrete_type = 5 },115                    } },116                    .{ .add = .{ .left = 13, .right = 15 } },117                    .{ .input = 6 },118                    .{ .scale = .{119                        .node = 17,120                        .coefficient = .{ .size_of_concrete_type = 6 },121                    } },122                    .{ .add = .{ .left = 16, .right = 18 } },123                    .{ .input = 7 },124                    .{ .scale = .{125                        .node = 20,126                        .coefficient = .{ .size_of_concrete_type = 7 },127                    } },128                    .{ .add = .{ .left = 19, .right = 21 } },129                },130                .assertions = &.{.{131                    .scope = .closure_total,132                    .measure = .retained,133                    .relation = .exact,134                    .expression = 22,135                }},136            },137            .overload = .{138                .kind = .reject_before_seal,139                .detail = "invalid limits and short caller storage reject before activation",140            },141            .risks = .{142                .transitive = .{143                    .status = .witnessed,144                    .detail = "all retained table storage is carved from the transport region",145                },146                .foreign = .{147                    .status = .excluded,148                    .detail = "the transport owner crosses no foreign boundary",149                },150            },151            .work = .{ .equation = "activation and teardown each visit eight subowners" },152            .dependencies = &.{153                "reticulum.paths",154                "reticulum.announces",155                "reticulum.reverse_entries",156                "reticulum.hashlist",157                "reticulum.inflight_requests",158                "reticulum.discoveries",159                "reticulum.links",160                "reticulum.link_entries",161            },162            .obligations = &.{163                .{ .key = "reticulum_transport_capacity", .role = .capacity_model },164                .{ .key = "reticulum_transport_overload", .role = .overload },165                .{ .key = "reticulum_transport_transitive", .role = .transitive_risk },166                .{ .key = "reticulum_transport_work", .role = .work_bound },167            },168        },169        .bindings = .{170            .owner = @This(),171            .seal = .{172                .family = alloc_phase.capacity.selector(@This().activate),173                .premise = .{ .class = .checked_semantic_fact, .authority = .checker },174            },175            .teardown = .{176                .family = alloc_phase.capacity.selector(@This().deinit),177                .premise = .{ .class = .checked_semantic_fact, .authority = .checker },178            },179        },180    };181182    pub fn init(storage: Storage, limits: Limits) InitError!State {183        const capacity = try Capacity.derive(limits);184        if (storage.len != capacity.storage_bytes) return error.StorageLengthMismatch;185        return .{186            .phase = .initialization,187            .capacity = capacity,188            .storage = storage,189            .paths = try path.Table.init(190                region(storage, 0, capacity.paths.storage_bytes),191                .{ .paths_max = limits.paths_max },192            ),193            .announces = try announces.Table.init(194                region(storage, capacity.announces_offset, capacity.announces.storage_bytes),195                .{ .announces_max = limits.announces_max },196            ),197            .reverse_entries = try reverse.Table.init(198                region(199                    storage,200                    capacity.reverse_entries_offset,201                    capacity.reverse_entries.storage_bytes,202                ),203                .{ .reverse_entries_max = limits.reverse_entries_max },204            ),205            .tags = try packet.hashlist.Table.init(206                region(storage, capacity.tags_offset, capacity.tags.storage_bytes),207                .{ .hashes_max = limits.path_request_tags_max },208            ),209            .inflight_requests = try inflight.Table.init(210                region(211                    storage,212                    capacity.inflight_requests_offset,213                    capacity.inflight_requests.storage_bytes,214                ),215                .{ .inflight_requests_max = limits.inflight_requests_max },216            ),217            .discoveries = try discoveries.Table.init(218                region(storage, capacity.discoveries_offset, capacity.discoveries.storage_bytes),219                .{ .discoveries_max = limits.discoveries_max },220            ),221            .links = try links.Table.init(222                region(storage, capacity.links_offset, capacity.links.storage_bytes),223                .{ .links_max = limits.links_max },224            ),225            .link_entries = try link_entries.Table.init(226                region(227                    storage,228                    capacity.link_entries_offset,229                    capacity.link_entries.storage_bytes,230                ),231                .{ .link_entries_max = limits.link_entries_max },232            ),233        };234    }235236    pub fn activate(self: *State) void {237        std.debug.assert(self.phase == .initialization);238        self.paths.activate();239        self.announces.activate();240        self.reverse_entries.activate();241        self.tags.activate();242        self.inflight_requests.activate();243        self.discoveries.activate();244        self.links.activate();245        self.link_entries.activate();246        self.phase = .steady;247    }248249    /// Names this node as a next hop, following Reticulum@1.5.0250    /// RNS/Transport.py:1577-1580,1907. A caller turns the node into one that251    /// carries traffic for others, and gives it the hash that names it to its252    /// neighbors. Every step that carries traffic for others refuses until the253    /// flag is set.254    pub fn configure(self: *State, identity_hash: [16]u8, enabled: bool) void {255        std.debug.assert(self.phase == .steady);256        self.identity_hash = identity_hash;257        self.enabled = enabled;258    }259260    pub fn deinit(self: *State) Storage {261        std.debug.assert(self.phase == .steady);262        _ = self.link_entries.deinit();263        _ = self.links.deinit();264        _ = self.discoveries.deinit();265        _ = self.inflight_requests.deinit();266        _ = self.tags.deinit();267        _ = self.reverse_entries.deinit();268        _ = self.announces.deinit();269        _ = self.paths.deinit();270        self.phase = .teardown;271        const storage = self.storage;272        self.* = undefined;273        return storage;274    }275};

1pub const transport = @import("transport/root.zig");

1//! The state and the steps a node needs to work out where destinations are from2//! the broadcasts it hears, and to move traffic toward them.3//!4//! A node has to find out where destinations are with no directory to ask. A5//! node that carries traffic for others carries it toward destinations for6//! neighbors that cannot reach them directly, and answers a neighbor that7//! asks about a destination it knows. The node also passes another pair's8//! encrypted session across itself.9//!10//! What a node knows arrives as broadcasts, so the same broadcast reaches it11//! more than once, by more than one route, and out of order, and the node needs12//! a rule that picks one without a clock shared with the sender. Repeating13//! every broadcast would flood the mesh. A forwarded packet has to say which14//! node passed it on for any answer to come back. Storage is a fixed number of15//! entries the caller fixes before the node starts, so every store states which16//! entry a new one takes over, and a store that refuses a new entry when it is17//! full says so. The node performs no input or output and reads no clock, so18//! each step takes the current second from its caller and returns the frames to19//! send and the timers to arm.20//!21//! Reticulum 1.5.0, the reference implementation this package is a port of,22//! answers each of these forces, and this subtree is a port of those answers.23//! Every module here cites the reference by file and line. The lineage is24//! checkable in this tree: the package README pins the upstream commit the port25//! follows, and the conformance corpus under src/conformance is generated from26//! that release and drives the differential tests.27//!28//! A destination makes itself known with a broadcast carrying its public keys,29//! a signature and ten random bytes holding the instant it was stamped (an30//! *announce*), so any node that hears the announce learns that destination and31//! how far away it sits. That instant orders two announces from the same32//! destination without a shared clock. The node keeps what it learns from33//! announces about reaching one destination, the network interface to send on,34//! the neighbor to name as the next hop, and how many hops away the35//! destination sits (a *path*). A path keeps the announces it has already36//! taken, so a repeat is recognized and an older one loses. A node that carries37//! traffic for others sends an announce it accepted onward at most twice, stops38//! at 128 hops, and stops as soon as it hears neighbors carrying the same one.39//! A forwarded packet's header grows a field that names the node passing it on40//! by that node's 16-byte hash, and two header shapes, of 19 and of 35 bytes,41//! tell a packet in transport from one at its last hop. The node keeps a record42//! for each packet it forwards, tying it to the network interface it arrived on43//! and the one it left on, so the signed answer that confirms the packet (a44//! *proof*) travels the way the packet came. A node asks its neighbors for a45//! way to reach a destination by sending requests to one well-known46//! destination.47//!48//! Every store here (a *table*) lives in bytes the caller hands over and the49//! node hands back at teardown, with its entry maximum fixed before the node50//! starts and its replacement rule written in the code. Reticulum 1.5.0 grows51//! dictionaries and culls them on a periodic pass. Time is whole seconds, so52//! the reference's fractional waits become the nearest whole second. Nothing53//! sweeps on a fixed interval: an entry stops counting at its own deadline when54//! it is looked up, and for relayed sessions the node asks its caller to wake55//! it at each session's deadline (a *node timer*). A step that turns a packet56//! away names the reason in a record for its caller to read (a *diagnostic*).57//! Reticulum 1.5.0 writes such a reason to a log or raises a protocol58//! violation.59//!60//! The modules below divide the work: `path` holds what the node learned about61//! reaching destinations, `announces` and `retransmit` hold the queue of62//! announces to send on and the sweep that sends them, `relay` with `rewrite`63//! and `reverse` carry one packet onward and bring its proof back, `requests`64//! with `inflight` and `discoveries` ask for a path and answer when asked,65//! `link` and `links` hold the sessions the node carries and the ones it holds66//! an end of, and `state` carves all eight stores from one block of caller67//! storage.68//!69//! - *destination*: the 16-byte hash that names one addressable endpoint on the70//!   network.71//! - *transport node*: a node that carries traffic on behalf of other nodes, as72//!   well as sending and receiving its own.73//! - *link*: an encrypted session between two endpoints, named by a 16-byte74//!   link id that both ends derive from the request packet.75//! - *emission time*: the instant the originator stamped into the ten random76//!   bytes an announce carries, which orders two announces from the same77//!   destination.78//! - *carrier*: one network interface the node sends and receives over, named79//!   by a small integer index.80//! - *transport identity hash*: the 16 bytes a transport node writes into a81//!   packet header so the next node along sees who passed it on.82//! - *next hop*: the neighboring node a packet is handed to on its way, named83//!   in the packet header by its transport identity hash.84//! - *rebroadcast*: the sending onward of an announce a transport node85//!   accepted, so the mesh learns the destination beyond this node.86//! - *hop count*: the byte in the packet header that rises by one at every node87//!   the packet passes through.88//! - *pathfinder maximum*: the hop count of 128, at and above which a packet is89//!   refused.90//! - *reverse entry*: the record that ties a relayed packet to the carrier it91//!   arrived on and the carrier it left on, so the answering proof travels the92//!   way the packet came.93//! - *effect*: a record the node appends to send a frame on a carrier or arm a94//!   timer.95//! - *path request*: a packet asking any node that knows a path to a96//!   destination to answer with one.97//! - *HEADER_1*: the 19-byte header shape, carried by a packet that names no98//!   node it is passing through.99//! - *HEADER_2*: the 35-byte header shape, which carries the 16-byte hash of100//!   the node the packet is passing through.101102pub const announces = @import("announces.zig");103pub const discoveries = @import("discoveries.zig");104pub const inflight = @import("inflight.zig");105pub const link = @import("link/root.zig");106pub const links = @import("links.zig");107pub const path = @import("path.zig");108pub const relay = @import("relay.zig");109pub const requests = @import("requests.zig");110pub const retransmit = @import("retransmit.zig");111pub const reverse = @import("reverse.zig");112pub const rewrite = @import("rewrite.zig");113pub const State = @import("state.zig").State;