Initial import: ICE-NET research docs and Rust workspace (v0.4)
Some checks failed
rust-ci / checks (push) Has been cancelled

- Rust workspace: 7 library crates, icenetd CLI, icenet-city (Slint GUI)
- Sim: fix false Delivered after a route cut, derive traffic class from
  payload size, per-link airtime slots (link capacity, queueing)
- Docs: single docs/STATUS.md for all figures, remove v0.2/egui leftovers,
  drop unimplemented seed claims, uncheck store-and-forward
- License: LGPL-3.0-or-later (LICENSE, LICENSES/GPL-3.0.txt)
This commit is contained in:
Loki 2026-11-13 12:28:48 +01:00
commit 2e61688eb3
Signed by: boba
GPG key ID: 6CDE87BC9A778D97
141 changed files with 13993 additions and 0 deletions

View file

@ -0,0 +1,101 @@
//! Link capacity: transmissions share a link in FIFO order instead of overlapping.
use icenet_core::{LinkKind, NodeId, TrafficClass};
use icenet_sim::{City, DeliveryState, DeviceRole, metrics};
fn pair(kind: LinkKind) -> (City, NodeId, NodeId) {
let mut city = City::empty();
let a = city.add_device("a".to_owned(), DeviceRole::Client);
let b = city.add_device("b".to_owned(), DeviceRole::Client);
assert!(city.add_link(a, b, kind));
(city, a, b)
}
fn delivered(city: &City) -> usize {
city.messages
.iter()
.filter(|m| m.status == DeliveryState::Delivered)
.count()
}
#[test]
fn texts_queue_behind_each_other_on_one_slow_link() {
let (mut city, a, b) = pair(LinkKind::SlowRadio);
// 200 B at 1 kbit/s is 1600 ms of airtime plus 10 ms overhead each.
for _ in 0..100 {
city.send(a, b, TrafficClass::Text, 200);
}
city.tick(2_000);
assert_eq!(delivered(&city), 1, "only one 1610 ms frame fits in 2 s");
city.tick(161_000 - 2_000);
assert_eq!(delivered(&city), 100);
}
#[test]
fn due_times_are_strictly_ordered_by_link_reservation() {
let (mut city, a, b) = pair(LinkKind::SlowRadio);
let first = city.send(a, b, TrafficClass::Text, 200);
let second = city.send(a, b, TrafficClass::Text, 200);
let due = |id| {
city.messages
.iter()
.find(|m| m.id == id)
.and_then(|m| m.due_ms)
};
assert_eq!(due(first), Some(1_610));
assert_eq!(due(second), Some(3_220));
}
#[test]
fn an_idle_link_does_not_delay_the_next_message() {
let (mut city, a, b) = pair(LinkKind::SlowRadio);
city.send(a, b, TrafficClass::Text, 200);
city.tick(10_000);
let id = city.send(a, b, TrafficClass::Text, 200);
let message = city.messages.iter().find(|m| m.id == id).expect("message");
assert_eq!(message.due_ms, Some(10_000 + 1_610));
}
#[test]
fn backlog_can_push_a_message_past_its_ttl() {
let (mut city, a, b) = pair(LinkKind::SlowRadio);
for _ in 0..3 {
city.send(a, b, TrafficClass::Text, 200);
}
let late = city.send_with_ttl(a, b, TrafficClass::Text, 200, 5_000);
city.tick(5_000);
let status = city
.messages
.iter()
.find(|m| m.id == late)
.expect("late")
.status;
assert_eq!(
status,
DeliveryState::Expired,
"airtime backlog ate the TTL"
);
}
#[test]
fn oversized_text_never_consumes_slow_radio_airtime() {
let (mut city, a, b) = pair(LinkKind::SlowRadio);
let id = city.send(a, b, TrafficClass::Text, 5_000_000);
let status = city
.messages
.iter()
.find(|m| m.id == id)
.expect("message")
.status;
assert_eq!(status, DeliveryState::Queued);
assert_eq!(city.link_airtime_ms(LinkKind::SlowRadio), 0);
assert_eq!(metrics::summarize(&city).slow_radio_airtime_ms, 0);
}
#[test]
fn airtime_is_reported_per_link_kind() {
let (mut city, a, b) = pair(LinkKind::SlowRadio);
city.send(a, b, TrafficClass::Text, 200);
assert_eq!(city.link_airtime_ms(LinkKind::SlowRadio), 1_610);
assert_eq!(city.link_airtime_ms(LinkKind::Wired), 0);
assert_eq!(metrics::summarize(&city).slow_radio_airtime_ms, 1_610);
}

View file

@ -0,0 +1,140 @@
use icenet_core::{LinkKind, NodeId, TrafficClass};
use icenet_sim::{City, DeliveryState, DeviceRole, metrics};
#[test]
fn bulk_is_queued_when_only_slow_links_remain() {
let mut city = City::demo();
assert!(city.set_link_enabled(2, false));
let id = city.send(NodeId(1), NodeId(3), TrafficClass::Bulk, 5_000_000);
assert_eq!(
city.messages.iter().find(|m| m.id == id).unwrap().status,
DeliveryState::Queued
);
}
#[test]
fn message_delivers_after_virtual_time_advance() {
let mut city = City::demo();
city.send(NodeId(1), NodeId(3), TrafficClass::Bulk, 50_000);
city.tick(200_000);
assert_eq!(city.messages[0].status, DeliveryState::Delivered);
}
#[test]
fn queued_message_recovers_when_fast_link_returns() {
let mut city = City::demo();
city.set_link_enabled(2, false);
city.send(NodeId(1), NodeId(3), TrafficClass::Bulk, 100);
assert_eq!(city.messages[0].status, DeliveryState::Queued);
city.set_link_enabled(2, true);
city.tick(1);
assert_eq!(city.messages[0].status, DeliveryState::InFlight);
}
#[test]
fn slower_link_kind_reschedules_an_in_flight_message() {
let mut city = City::demo();
let id = city.send(NodeId(1), NodeId(3), TrafficClass::Bulk, 5_000_000);
let before = city.messages[0].due_ms.expect("scheduled");
assert!(city.set_link_kind(3, LinkKind::Internet));
city.tick(1);
let after = city.messages[0].due_ms.expect("still scheduled");
assert!(after > before, "due {after} must move past {before}");
assert_eq!(city.messages[0].id, id);
}
#[test]
fn first_route_timestamp_is_not_restamped_after_requeue() {
let mut city = City::demo();
assert!(city.set_link_enabled(2, false));
city.send(NodeId(1), NodeId(3), TrafficClass::Bulk, 100);
city.tick(1_000);
assert!(city.set_link_enabled(2, true));
city.tick(1);
let first = city.messages[0].first_route_ms;
assert_eq!(first, Some(1_001));
assert!(city.set_link_enabled(2, false));
city.tick(1);
assert_eq!(city.messages[0].status, DeliveryState::Queued);
assert!(city.set_link_enabled(2, true));
city.tick(1);
assert_eq!(city.messages[0].first_route_ms, first);
}
#[test]
fn empty_city_has_no_devices_links_or_messages() {
let city = City::empty();
assert!(city.devices.is_empty());
assert!(city.links.is_empty());
assert!(city.messages.is_empty());
assert_eq!(city.now_ms, 0);
}
#[test]
fn identical_action_scripts_produce_byte_identical_exports() {
let first = run_script();
let second = run_script();
assert_eq!(
metrics::messages_csv(&first),
metrics::messages_csv(&second)
);
assert_eq!(
metrics::scenario_json(&first),
metrics::scenario_json(&second)
);
assert_eq!(metrics::summarize(&first), metrics::summarize(&second));
}
fn run_script() -> City {
let mut city = City::demo();
assert!(city.set_link_enabled(2, false));
city.send(NodeId(1), NodeId(3), TrafficClass::Bulk, 5_000_000);
city.send(NodeId(1), NodeId(3), TrafficClass::Text, 128);
city.tick(1_000);
assert!(city.set_link_enabled(2, true));
city.tick(120_000);
let extra = city.add_device("Extra".to_owned(), DeviceRole::Client);
assert!(city.add_link(extra, NodeId(5), LinkKind::Internet));
city.send_with_ttl(extra, NodeId(6), TrafficClass::Bulk, 1_000, 1);
city.tick(10);
city
}
#[test]
fn cutting_the_route_before_a_coarse_tick_never_yields_delivered() {
let mut city = City::demo();
let id = city.send(NodeId(1), NodeId(3), TrafficClass::Bulk, 5_000_000);
for index in 0..city.links.len() {
assert!(city.set_link_enabled(index, false));
}
// One huge step jumps far past `due_ms`; the cut still happened first.
city.tick(1_000_000);
let status = city.messages.iter().find(|m| m.id == id).unwrap().status;
assert_eq!(status, DeliveryState::Queued);
}
#[test]
fn taking_a_relay_offline_before_arrival_does_not_deliver() {
let mut city = City::demo();
city.send(NodeId(1), NodeId(3), TrafficClass::Bulk, 5_000_000);
assert!(city.set_device_online(NodeId(5), false));
city.tick(1_000_000);
assert_ne!(city.messages[0].status, DeliveryState::Delivered);
}
#[test]
fn a_still_valid_route_is_delivered_normally_after_a_coarse_tick() {
let mut city = City::demo();
city.send(NodeId(1), NodeId(3), TrafficClass::Bulk, 5_000_000);
city.tick(1_000_000);
assert_eq!(city.messages[0].status, DeliveryState::Delivered);
}
#[test]
fn a_cut_that_is_repaired_before_the_tick_reroutes_without_false_delivery() {
let mut city = City::demo();
city.send(NodeId(1), NodeId(3), TrafficClass::Bulk, 5_000_000);
assert!(city.set_link_enabled(3, false));
city.tick(1);
assert_ne!(city.messages[0].status, DeliveryState::Delivered);
}

View file

@ -0,0 +1,114 @@
//! Deterministic metrics and export formats for offline experiments.
use icenet_core::{LinkKind, NodeId, TrafficClass};
use icenet_sim::{City, DeliveryState, metrics};
#[test]
fn summary_counts_states_and_excludes_expired_from_delivery_ratio() {
let mut city = City::demo();
for index in [2, 3, 4] {
assert!(city.set_link_enabled(index, false));
}
city.send_with_ttl(NodeId(1), NodeId(3), TrafficClass::Bulk, 5_000_000, 1_000);
city.send(NodeId(1), NodeId(3), TrafficClass::Text, 128);
city.tick(5_000);
let summary = metrics::summarize(&city);
assert_eq!(summary.created, 2);
assert_eq!(summary.delivered, 1);
assert_eq!(summary.expired, 1);
assert_eq!(summary.queued, 0);
assert!((summary.delivery_ratio() - 0.5).abs() < f64::EPSILON);
assert!(summary.first_route_p50_ms.is_some());
assert!(summary.first_route_p95_ms.is_some());
}
#[test]
fn nearest_rank_percentiles_are_deterministic() {
let mut samples = [40, 10, 30, 20];
assert_eq!(metrics::percentile(&mut samples, 50), Some(20));
assert_eq!(metrics::percentile(&mut samples, 95), Some(40));
assert_eq!(metrics::percentile(&mut [], 50), None);
assert_eq!(metrics::percentile(&mut [7], 99), Some(7));
}
#[test]
fn control_airtime_is_counted_from_the_last_route() {
let mut city = City::demo();
let id = city.send(NodeId(1), NodeId(3), TrafficClass::Control, 100);
city.tick(60_000);
assert_eq!(status_of(&city, id), DeliveryState::Delivered);
assert!(metrics::summarize(&city).control_airtime_ms > 0);
}
#[test]
fn csv_export_has_stable_header_and_one_row_per_message() {
let mut city = City::demo();
city.send(NodeId(1), NodeId(3), TrafficClass::Text, 128);
let csv = metrics::messages_csv(&city);
let mut lines = csv.lines();
assert_eq!(
lines.next(),
Some("id,from,to,class,bytes,status,created_ms,expires_ms,first_route_ms,due_ms,route")
);
assert_eq!(lines.clone().count(), 1);
assert!(lines.next().is_some_and(|row| row.contains(",Text,")));
}
#[test]
fn json_scenario_is_deterministic_and_escapes_labels() {
let mut first = City::demo();
first.devices[0].label = "A \"quoted\" \\ path".to_owned();
first.send(NodeId(1), NodeId(3), TrafficClass::Text, 128);
let mut second = first.clone();
second.tick(1_000);
let first_json = metrics::scenario_json(&first);
let first_again = metrics::scenario_json(&first);
assert_eq!(first_json, first_again);
assert!(first_json.contains(r#""label":"A \"quoted\" \\ path""#));
assert!(first_json.contains(r#""status":"InFlight""#));
assert!(second_json_after_tick(&second).contains("Delivered"));
}
#[test]
fn json_escapes_control_characters() {
let mut city = City::demo();
city.devices[0].label = "a\u{1}b".to_owned();
let json = metrics::scenario_json(&city);
assert!(json.contains(r#""label":"a\u0001b""#), "json: {json}");
}
#[test]
fn json_uses_null_for_non_finite_coordinates() {
let mut city = City::demo();
city.devices[0].x = f32::NAN;
city.devices[0].y = f32::INFINITY;
let json = metrics::scenario_json(&city);
assert!(json.contains("\"x\":null,\"y\":null"), "json: {json}");
}
#[test]
fn json_encodes_every_supported_link_kind() {
for kind in [
LinkKind::SlowRadio,
LinkKind::FastWireless,
LinkKind::Wired,
LinkKind::Internet,
] {
let mut city = City::demo();
city.links[0].kind = kind;
let json = metrics::scenario_json(&city);
assert!(json.contains(&format!("\"kind\":\"{kind:?}\"")));
}
}
fn status_of(city: &City, id: u64) -> DeliveryState {
city.messages
.iter()
.find(|message| message.id == id)
.expect("recorded message")
.status
}
fn second_json_after_tick(city: &City) -> String {
metrics::scenario_json(city)
}

View file

@ -0,0 +1,68 @@
//! Scale smoke tests: 100 and 1000 virtual nodes on a deterministic grid.
use std::time::Instant;
use icenet_core::{LinkKind, NodeId, TrafficClass};
use icenet_sim::{City, DeliveryState, DeviceRole, metrics};
#[test]
fn hundred_node_grid_delivers_bulk_with_full_ratio() {
let mut city = grid(10, 10);
let source = city.devices.first().expect("grid nodes").id;
let destination = city.devices.last().expect("grid nodes").id;
let id = city.send(source, destination, TrafficClass::Bulk, 5_000_000);
city.tick(200_000);
assert_eq!(status_of(&city, id), DeliveryState::Delivered);
let summary = metrics::summarize(&city);
assert_eq!(summary.created, 1);
assert!((summary.delivery_ratio() - 1.0).abs() < f64::EPSILON);
}
#[test]
fn thousand_node_grid_reports_route_latency() {
let city = grid(40, 25);
let nodes: Vec<NodeId> = city.devices.iter().map(|device| device.id).collect();
let mut samples = Vec::with_capacity(200);
let mut state = 0x2545_f491_4f6c_dd1d_u64;
for _ in 0..200 {
state = state
.wrapping_mul(6_364_136_223_846_793_005)
.wrapping_add(1);
let from = nodes[(state as usize) % nodes.len()];
let to = nodes[((state >> 32) as usize) % nodes.len()];
let started = Instant::now();
let path = city.route(from, to, TrafficClass::Text, 128);
samples.push(u64::try_from(started.elapsed().as_micros()).unwrap_or(u64::MAX));
assert!(path.is_some(), "grid must stay connected");
}
let p50 = metrics::percentile(&mut samples.clone(), 50).expect("samples");
let p95 = metrics::percentile(&mut samples, 95).expect("samples");
println!("1000-node route search (release-independent debug build): p50={p50}us p95={p95}us");
assert!(p50 <= p95);
}
fn grid(columns: usize, rows: usize) -> City {
let mut city = City::empty();
let ids: Vec<NodeId> = (0..columns * rows)
.map(|index| city.add_device(format!("n{index}"), DeviceRole::Relay))
.collect();
for row in 0..rows {
for column in 0..columns {
let index = row * columns + column;
if column + 1 < columns {
assert!(city.add_link(ids[index], ids[index + 1], LinkKind::FastWireless));
}
if row + 1 < rows {
assert!(city.add_link(ids[index], ids[index + columns], LinkKind::FastWireless));
}
}
}
city
}
fn status_of(city: &City, id: u64) -> DeliveryState {
city.messages
.iter()
.find(|message| message.id == id)
.expect("recorded message")
.status
}

View file

@ -0,0 +1,83 @@
//! Store-and-forward lifetime behaviour: queued work must expire, never fake delivery.
use icenet_core::{NodeId, TrafficClass};
use icenet_sim::{City, DeliveryState};
fn city_without_bulk_path() -> City {
let mut city = City::demo();
for index in [2, 3, 4] {
assert!(city.set_link_enabled(index, false));
}
city
}
#[test]
fn queued_message_expires_after_its_ttl() {
let mut city = city_without_bulk_path();
let id = city.send_with_ttl(NodeId(1), NodeId(3), TrafficClass::Bulk, 5_000_000, 5_000);
city.tick(4_999);
assert_eq!(message_status(&city, id), DeliveryState::Queued);
city.tick(1);
assert_eq!(message_status(&city, id), DeliveryState::Expired);
}
#[test]
fn in_flight_message_expires_when_ttl_is_shorter_than_transfer() {
let mut city = City::demo();
let id = city.send_with_ttl(NodeId(1), NodeId(3), TrafficClass::Bulk, 5_000_000, 10);
city.tick(11);
assert_eq!(message_status(&city, id), DeliveryState::Expired);
}
#[test]
fn arrival_at_expiry_is_delivered_but_one_ms_earlier_expires() {
let mut delivered = City::demo();
let estimate = delivered
.route(NodeId(1), NodeId(3), TrafficClass::Text, 128)
.expect("route")
.estimated_ms;
let id = delivered.send_with_ttl(NodeId(1), NodeId(3), TrafficClass::Text, 128, estimate);
delivered.tick(estimate);
assert_eq!(message_status(&delivered, id), DeliveryState::Delivered);
let mut expired = City::demo();
let id = expired.send_with_ttl(NodeId(1), NodeId(3), TrafficClass::Text, 128, estimate - 1);
expired.tick(estimate - 1);
assert_eq!(message_status(&expired, id), DeliveryState::Expired);
}
#[test]
fn expired_message_never_revives_when_a_path_returns() {
let mut city = city_without_bulk_path();
let id = city.send_with_ttl(NodeId(1), NodeId(3), TrafficClass::Bulk, 5_000_000, 1_000);
city.tick(2_000);
assert_eq!(message_status(&city, id), DeliveryState::Expired);
assert!(city.set_link_enabled(2, true));
city.tick(60_000);
assert_eq!(message_status(&city, id), DeliveryState::Expired);
}
#[test]
fn zero_ttl_gets_the_shortest_positive_lifetime() {
let mut city = City::demo();
let id = city.send_with_ttl(NodeId(1), NodeId(3), TrafficClass::Text, 128, 0);
city.tick(0);
assert_eq!(message_status(&city, id), DeliveryState::InFlight);
city.tick(1);
assert_eq!(message_status(&city, id), DeliveryState::Expired);
}
#[test]
fn default_send_uses_the_documented_default_ttl() {
let mut city = City::demo();
let id = city.send(NodeId(1), NodeId(3), TrafficClass::Text, 128);
let message = city.messages.iter().find(|m| m.id == id).expect("message");
assert_eq!(message.expires_ms, City::DEFAULT_TTL_MS);
}
fn message_status(city: &City, id: u64) -> DeliveryState {
city.messages
.iter()
.find(|message| message.id == id)
.expect("recorded message")
.status
}