tiny.reticulum.carrier

1pub const Memory = struct {2    phase: alloc_phase.capacity.Phase,3    capacity: MemoryCapacity,4    storage: Storage,5    frames: []carrier.Frame,6    start: usize = 0,7    len: usize = 0,89    pub const storage_alignment: usize = 8;10    pub const Storage = []align(storage_alignment) u8;11    pub const Limits: type = MemoryLimits;12    pub const Capacity: type = MemoryCapacity;13    pub const Exhaustion = error{Full};14    pub const InitError = Capacity.DeriveError || error{StorageLengthMismatch};15    pub const work_limits: alloc_phase.capacity.WorkLimits = .{16        .transition_steps_max = 1,17        .cleanup_steps_per_call_max = 0,18        .cleanup_calls_at_capacity_max = 0,19    };20    pub const claim: alloc_phase.capacity.Declaration = .{21        .source = .{22            .id = "reticulum.carrier_memory",23            .kind = .phase_static,24            .limit_source = .caller,25            .storage = .{26                .covered = &.{.{27                    .id = "caller_frame_fifo",28                    .lifetime = .transferred,29                    .detail = "caller storage for a bounded FIFO of inline carrier frames",30                }},31                .excluded = &.{32                    "caller frame inputs and returned frame values",33                    "interface devices and operating-system transport state",34                },35            },36            .capacity = .{37                .inputs = &.{alloc_phase.capacity.bindInput(38                    Limits,39                    "frames_max",40                    "frames_max",41                )},42                .type_selectors = &.{alloc_phase.capacity.bindType(carrier.Frame, "frame")},43                .nodes = &.{44                    .{ .input = 0 },45                    .{ .scale = .{46                        .node = 0,47                        .coefficient = .{ .size_of_concrete_type = 0 },48                    } },49                },50                .assertions = &.{.{51                    .scope = .closure_total,52                    .measure = .retained,53                    .relation = .exact,54                    .expression = 1,55                }},56            },57            .overload = .{58                .kind = .reject_before_mutation,59                .detail = "full frame admission preserves the retained FIFO",60            },61            .risks = .{62                .transitive = .{63                    .status = .excluded,64                    .detail = "carrier memory calls no allocating owner",65                },66                .foreign = .{67                    .status = .excluded,68                    .detail = "carrier memory crosses no operating-system boundary",69                },70            },71            .work = .{ .equation = "push and pop each perform one bounded transition" },72            .obligations = &.{73                .{ .key = "reticulum_carrier_memory_capacity", .role = .capacity_model },74                .{ .key = "reticulum_carrier_memory_overload", .role = .overload },75                .{ .key = "reticulum_carrier_memory_work", .role = .work_bound },76            },77        },78        .bindings = .{79            .owner = @This(),80            .seal = .{81                .family = alloc_phase.capacity.selector(@This().activate),82                .premise = .{ .class = .checked_semantic_fact, .authority = .checker },83            },84            .teardown = .{85                .family = alloc_phase.capacity.selector(@This().deinit),86                .premise = .{ .class = .checked_semantic_fact, .authority = .checker },87            },88        },89    };9091    pub fn init(storage: Storage, limits: Limits) InitError!Memory {92        const capacity = try Capacity.derive(limits);93        if (storage.len != capacity.storage_bytes) return error.StorageLengthMismatch;94        const frames = std.mem.bytesAsSlice(carrier.Frame, storage);95        for (frames) |*frame| frame.* = .{};96        return .{97            .phase = .initialization,98            .capacity = capacity,99            .storage = storage,100            .frames = frames,101        };102    }103104    pub fn activate(self: *Memory) void {105        std.debug.assert(self.phase == .initialization);106        std.debug.assert(self.len == 0);107        self.phase = .steady;108    }109110    pub fn push(self: *Memory, frame: carrier.Frame) Exhaustion!void {111        std.debug.assert(self.phase == .steady);112        std.debug.assert(self.len <= self.capacity.frames_max);113        if (self.len == self.capacity.frames_max) return error.Full;114        const index = (self.start + self.len) % self.capacity.frames_max;115        self.frames[index] = frame;116        self.len += 1;117    }118119    pub fn pop(self: *Memory) ?carrier.Frame {120        std.debug.assert(self.phase == .steady);121        std.debug.assert(self.len <= self.capacity.frames_max);122        if (self.len == 0) return null;123        const frame = self.frames[self.start];124        self.start = (self.start + 1) % self.capacity.frames_max;125        self.len -= 1;126        return frame;127    }128129    pub fn count(self: *const Memory) usize {130        std.debug.assert(self.phase == .steady);131        return self.len;132    }133134    pub fn deinit(self: *Memory) Storage {135        std.debug.assert(self.phase == .steady);136        self.phase = .teardown;137        const storage = self.storage;138        self.* = undefined;139        return storage;140    }141};

1//! The unit of bytes a node hands to one network interface, and an interface2//! that keeps those bytes in memory.3//!4//! A Reticulum node sends over whatever moves bytes, a radio, a serial line, or5//! a socket, so the code above the interface deals in one unit and one index,6//! whatever the device. That unit has to have a size the program knows before7//! it starts, because a node holds those units in storage the caller supplied.8//! Testing a protocol needs an interface that gives the same answer on every9//! run.10//!11//! One unit runs longer than the 500-byte packet inside it, because a closed12//! network appends an authentication code of up to 64 bytes. A real device13//! brings a clock and a driver with it, and both make a test answer differently14//! from one run to the next.15//!16//! The subtree follows Reticulum 1.5.0, the reference implementation, pinned to17//! one upstream commit by the package README and the generated conformance18//! corpus. What it takes is the frame bound of Reticulum@1.5.019//! RNS/Transport.py:1247 and Reticulum@1.5.0 RNS/Reticulum.py:800.20//!21//! Each unit (a *frame*) is one fixed 564-byte value with a length beside it,22//! holding one packet plus at most a 64-byte signature, so a queue of frames is23//! a plain array in caller storage. The in-memory interface is a bounded queue24//! carved out of caller storage, which hands frames back in the order it took25//! them and refuses a frame once it is full, leaving what it holds untouched.26//! The subtree names its pieces: the frame bound, the carrier index, the frame,27//! and the in-memory interface.28//!29//! - *carrier*: one network interface a node sends and receives frames over,30//!   named by a byte index.3132const wire = @import("../wire/root.zig");3334/// 564 bytes, the most one frame holds, a 500-byte packet plus at most a35/// 64-byte Ed25519 signature. A frame is the bytes handed to one network36/// interface. A caller sizes the buffer it reads an arriving frame into, and37/// the storage it hands the in-memory interface, by this bound, following38/// Reticulum@1.5.0 RNS/Transport.py:1247 and Reticulum@1.5.039/// RNS/Reticulum.py:800.40pub const frame_bytes_max: usize = @as(usize, wire.mtu) + 64;4142pub const Index = u8;4344pub const Frame = struct {45    bytes: [frame_bytes_max]u8 = @splat(0),46    len: u16 = 0,4748    pub const InitError = error{TooLong};4950    pub fn init(bytes: []const u8) InitError!Frame {51        if (bytes.len > frame_bytes_max) return error.TooLong;52        var frame = Frame{};53        @memcpy(frame.bytes[0..bytes.len], bytes);54        frame.len = @intCast(bytes.len);55        return frame;56    }5758    pub fn slice(self: *const Frame) []const u8 {59        std.debug.assert(self.len <= frame_bytes_max);60        return self.bytes[0..self.len];61    }62};6364const std = @import("std");6566pub const Memory = @import("memory.zig").Memory;

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