astatin3/unshell
1
0
Fork 0
mirror of https://github.com/Astatin3/unshell.git synced 2026-06-08 22:38:01 -06:00
Code Issues Packages Projects Releases Wiki Activity

add treetest protocol simulator and ui

Browse Source
This commit is contained in:
Michael Mikovsky
2026-04-24 16:19:42 -06:00
parent 555663bd3d
commit 2b633ce019
31 changed files with 2760 additions and 4254 deletions
Download Patch File Download Diff File Expand all files Collapse all files
treetest/Cargo.toml
+26
View File
@@ -0,0 +1,26 @@
[package]
name = "treetest"
version.workspace = true
edition.workspace = true
authors.workspace = true
license.workspace = true
repository.workspace = true
[dependencies]
crossbeam-channel = "0.5.15"
crossterm = "0.29.0"
ratatui = { version = "0.30.0", default-features = false, features = ["crossterm_0_29"] }
thiserror = { workspace = true }
unshell = { path = ".." }
[lints.rust]
elided_lifetimes_in_paths = "warn"
future_incompatible = { level = "warn", priority = -1 }
nonstandard_style = { level = "warn", priority = -1 }
rust_2018_idioms = { level = "warn", priority = -1 }
rust_2021_prelude_collisions = "warn"
semicolon_in_expressions_from_macros = "warn"
unsafe_op_in_unsafe_fn = "warn"
unused_import_braces = "warn"
unused_lifetimes = "warn"
trivial_casts = "allow"
treetest/src/app.rs
+603
View File
@@ -0,0 +1,603 @@
//! Ratatui application shell for the protocol demo.
use std::{io, time::Duration};
use crossterm::{
event::{self, Event, KeyCode, KeyEventKind},
execute,
terminal::{EnterAlternateScreen, LeaveAlternateScreen, disable_raw_mode, enable_raw_mode},
};
use ratatui::{
DefaultTerminal, Frame,
layout::{Constraint, Direction, Layout, Rect},
style::{Modifier, Style, Stylize},
text::{Line, Text},
widgets::{Block, Borders, List, ListItem, Paragraph, Wrap},
};
use crate::{
model::{Selection, format_path},
scenarios::built_in_scenarios,
sim::{RecordedEvent, Simulation},
};
/// Errors returned by the TUI application.
#[derive(Debug, thiserror::Error)]
pub enum AppError {
#[error(transparent)]
Io(#[from] io::Error),
#[error(transparent)]
Sim(#[from] crate::sim::SimError),
}
/// Starts the TUI application.
pub fn run() -> Result<(), AppError> {
enable_raw_mode()?;
let mut stdout = io::stdout();
execute!(stdout, EnterAlternateScreen)?;
let terminal = ratatui::init();
let result = App::new()?.run(terminal);
ratatui::restore();
disable_raw_mode()?;
execute!(io::stdout(), LeaveAlternateScreen)?;
result
}
#[derive(Debug)]
struct App {
scenarios: Vec<crate::model::ScenarioDefinition>,
scenario_index: usize,
simulation: Simulation,
selection_index: usize,
selections: Vec<Selection>,
status: String,
}
impl App {
fn new() -> Result<Self, AppError> {
let scenarios = built_in_scenarios();
let simulation = Simulation::new(scenarios[0].clone())?;
let selections = build_selections(&simulation);
let selection_index = selections
.iter()
.position(|selection| *selection == simulation.initial_selection())
.unwrap_or(0);
Ok(Self {
scenarios,
scenario_index: 0,
simulation,
selection_index,
selections,
status: "Use arrows to move, Enter to switch scenarios, q to quit.".to_owned(),
})
}
fn run(mut self, mut terminal: DefaultTerminal) -> Result<(), AppError> {
loop {
terminal.draw(|frame| self.render(frame))?;
if event::poll(Duration::from_millis(100))?
&& let Event::Key(key) = event::read()?
&& key.kind == KeyEventKind::Press
&& !self.handle_key(key.code)?
{
break;
}
}
Ok(())
}
fn handle_key(&mut self, code: KeyCode) -> Result<bool, AppError> {
match code {
KeyCode::Char('q') => return Ok(false),
KeyCode::Up => {
if self.selection_index > 0 {
self.selection_index -= 1;
}
}
KeyCode::Down => {
if self.selection_index + 1 < self.selections.len() {
self.selection_index += 1;
}
}
KeyCode::Left => {
if self.scenario_index > 0 {
self.load_scenario(self.scenario_index - 1)?;
}
}
KeyCode::Right => {
if self.scenario_index + 1 < self.scenarios.len() {
self.load_scenario(self.scenario_index + 1)?;
}
}
KeyCode::Enter => {
let next = (self.scenario_index + 1) % self.scenarios.len();
self.load_scenario(next)?;
}
KeyCode::Char('i') => {
self.perform_introspection()?;
}
KeyCode::Char('e') => {
self.perform_echo()?;
}
KeyCode::Char('p') => {
self.perform_ping()?;
}
KeyCode::Char('c') => {
self.perform_chunked()?;
}
KeyCode::Char('h') => {
self.perform_chat_call()?;
}
KeyCode::Char('d') => {
self.perform_chat_data()?;
}
KeyCode::Char('b') => {
self.perform_chat_bye()?;
}
KeyCode::Char('f') => {
self.perform_invalid_fault_demo()?;
}
KeyCode::Char('s') => {
let processed = self.simulation.step()?;
self.status = if processed {
"Processed one queued frame.".to_owned()
} else {
"Network already idle.".to_owned()
};
}
KeyCode::Char('a') => {
let steps = self.simulation.drain()?;
self.status = format!("Drained {steps} queued frames.");
}
_ => {}
}
Ok(true)
}
fn load_scenario(&mut self, index: usize) -> Result<(), AppError> {
self.scenario_index = index;
self.simulation = Simulation::new(self.scenarios[index].clone())?;
self.selections = build_selections(&self.simulation);
self.selection_index = self
.selections
.iter()
.position(|selection| *selection == self.simulation.initial_selection())
.unwrap_or(0);
self.status = format!("Loaded scenario: {}", self.scenarios[index].name);
Ok(())
}
fn selected(&self) -> &Selection {
&self.selections[self.selection_index]
}
fn perform_introspection(&mut self) -> Result<(), AppError> {
match self.selected().clone() {
Selection::Node(node_id) => {
let result = self.simulation.call_endpoint_introspection(node_id)?;
let steps = self.simulation.drain()?;
self.status = format!("{} ({steps} steps)", result.label);
}
Selection::Leaf { node_id, leaf_name } => {
let result = self
.simulation
.call_leaf_introspection(node_id, &leaf_name)?;
let steps = self.simulation.drain()?;
self.status = format!("{} ({steps} steps)", result.label);
}
}
Ok(())
}
fn perform_echo(&mut self) -> Result<(), AppError> {
if let Selection::Leaf { node_id, leaf_name } = self.selected().clone() {
let result =
self.simulation
.call_echo_leaf(node_id, &leaf_name, "demo echo from root")?;
let steps = self.simulation.drain()?;
self.status = format!("{} ({steps} steps)", result.label);
} else {
self.status = "Select a leaf first, then press e.".to_owned();
}
Ok(())
}
fn perform_ping(&mut self) -> Result<(), AppError> {
if let Selection::Node(node_id) = self.selected().clone() {
if let Some(procedure_id) = self
.simulation
.node(node_id)
.endpoint_procedures
.first()
.map(|procedure| procedure.procedure_id.clone())
{
let result = self.simulation.call_endpoint_procedure(
node_id,
&procedure_id,
b"ping".to_vec(),
)?;
let steps = self.simulation.drain()?;
self.status = format!("{} ({steps} steps)", result.label);
} else {
self.status = "Selected node has no endpoint procedures.".to_owned();
}
} else {
self.status = "Select a node first, then press p.".to_owned();
}
Ok(())
}
fn perform_chunked(&mut self) -> Result<(), AppError> {
if let Selection::Node(node_id) = self.selected().clone() {
if let Some(procedure_id) = self
.simulation
.node(node_id)
.endpoint_procedures
.iter()
.find(|procedure| {
procedure.description.contains("chunk")
|| procedure.procedure_id.contains("chunked")
})
.map(|procedure| procedure.procedure_id.clone())
{
let result = self.simulation.call_endpoint_procedure(
node_id,
&procedure_id,
b"chunk please".to_vec(),
)?;
let steps = self.simulation.drain()?;
self.status = format!("{} ({steps} steps)", result.label);
} else {
self.status = "Selected node has no chunked procedure.".to_owned();
}
} else {
self.status = "Select a node first, then press c.".to_owned();
}
Ok(())
}
fn perform_chat_call(&mut self) -> Result<(), AppError> {
if let Selection::Node(node_id) = self.selected().clone() {
if let Some(procedure_id) = self
.simulation
.node(node_id)
.endpoint_procedures
.iter()
.find(|procedure| procedure.procedure_id.contains("chat"))
.map(|procedure| procedure.procedure_id.clone())
{
let result = self.simulation.call_endpoint_procedure(
node_id,
&procedure_id,
b"open chat".to_vec(),
)?;
let steps = self.simulation.drain()?;
self.status = format!("{} ({steps} steps)", result.label);
} else {
self.status = "Selected node has no chat procedure.".to_owned();
}
} else {
self.status = "Select a node first, then press h.".to_owned();
}
Ok(())
}
fn perform_chat_data(&mut self) -> Result<(), AppError> {
if let Some(hook_id) = self.simulation.hook_ids().last().copied() {
let result =
self.simulation
.send_root_hook_data(hook_id, "hello from the root", false)?;
let steps = self.simulation.drain()?;
self.status = format!("{} ({steps} steps)", result.label);
} else {
self.status = "No known hook yet. Press h to open chat first.".to_owned();
}
Ok(())
}
fn perform_chat_bye(&mut self) -> Result<(), AppError> {
if let Some(hook_id) = self.simulation.hook_ids().last().copied() {
let result = self.simulation.send_root_hook_data(hook_id, "bye", true)?;
let steps = self.simulation.drain()?;
self.status = format!("{} ({steps} steps)", result.label);
} else {
self.status = "No known hook yet. Press h to open chat first.".to_owned();
}
Ok(())
}
fn perform_invalid_fault_demo(&mut self) -> Result<(), AppError> {
if let Some(hook_id) = self.simulation.hook_ids().last().copied() {
let root_id = crate::model::NodeId(0);
if self.simulation.tree.nodes.len() > 1 {
let attacker = crate::model::NodeId(1);
let result = self.simulation.inject_invalid_peer_data(
attacker,
root_id,
hook_id,
"demo.endpoint.v1.chat.session",
"spoofed data",
)?;
let steps = self.simulation.drain()?;
self.status = format!("{} ({steps} steps)", result.label);
} else {
self.status =
"This scenario has no second node for invalid-peer traffic.".to_owned();
}
} else {
self.status = "Open a hook first before injecting invalid traffic.".to_owned();
}
Ok(())
}
fn render(&self, frame: &mut Frame<'_>) {
let chunks = Layout::default()
.direction(Direction::Vertical)
.constraints([
Constraint::Length(3),
Constraint::Min(14),
Constraint::Length(8),
])
.split(frame.area());
self.render_header(frame, chunks[0]);
self.render_body(frame, chunks[1]);
self.render_footer(frame, chunks[2]);
}
fn render_header(&self, frame: &mut Frame<'_>, area: Rect) {
let title = format!(
"treetest | scenario {} / {}: {}",
self.scenario_index + 1,
self.scenarios.len(),
self.scenarios[self.scenario_index].name
);
frame.render_widget(
Paragraph::new(title).block(Block::default().borders(Borders::ALL).title("Scenario")),
area,
);
}
fn render_body(&self, frame: &mut Frame<'_>, area: Rect) {
let columns = Layout::default()
.direction(Direction::Horizontal)
.constraints([
Constraint::Length(34),
Constraint::Percentage(36),
Constraint::Percentage(32),
])
.split(area);
let scenario_items = self
.scenarios
.iter()
.enumerate()
.map(|(index, scenario)| {
let label = if index == self.scenario_index {
format!("> {}", scenario.name)
} else {
format!(" {}", scenario.name)
};
ListItem::new(label)
})
.collect::<Vec<_>>();
frame.render_widget(
List::new(scenario_items)
.block(Block::default().borders(Borders::ALL).title("Scenarios")),
columns[0],
);
let center = Layout::default()
.direction(Direction::Vertical)
.constraints([Constraint::Percentage(54), Constraint::Percentage(46)])
.split(columns[1]);
self.render_selection_list(frame, center[0]);
self.render_inspector(frame, center[1]);
let right = Layout::default()
.direction(Direction::Vertical)
.constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
.split(columns[2]);
self.render_trace(frame, right[0]);
self.render_hooks(frame, right[1]);
}
fn render_selection_list(&self, frame: &mut Frame<'_>, area: Rect) {
let items = self
.selections
.iter()
.enumerate()
.map(|(index, selection)| {
let label = match selection {
Selection::Node(node_id) => {
let node = self.simulation.node(*node_id);
format!(
"{} {}",
if index == self.selection_index {
">"
} else {
" "
},
node.display_path()
)
}
Selection::Leaf { node_id, leaf_name } => {
format!(
"{} {} :: {}",
if index == self.selection_index {
">"
} else {
" "
},
self.simulation.node(*node_id).display_path(),
leaf_name
)
}
};
ListItem::new(label)
})
.collect::<Vec<_>>();
frame.render_widget(
List::new(items).block(Block::default().borders(Borders::ALL).title("Tree")),
area,
);
}
fn render_inspector(&self, frame: &mut Frame<'_>, area: Rect) {
let selection = self.selected();
let body = match selection {
Selection::Node(node_id) => {
let node = self.simulation.node(*node_id);
let mut lines = vec![
Line::from(node.title.clone()).bold(),
Line::from(node.description.clone()),
Line::from(format!("Path: {}", node.display_path())),
Line::from(format!("Children: {}", node.children.len())),
Line::from(format!("Leaves: {}", node.leaves.len())),
Line::from(format!(
"Endpoint procedures: {}",
node.endpoint_procedures.len()
)),
Line::default(),
Line::from("Endpoint procedures:"),
];
lines.extend(
node.endpoint_procedures
.iter()
.map(|procedure| Line::from(format!("- {}", procedure.procedure_id))),
);
lines.extend(
node.leaves
.iter()
.map(|leaf| Line::from(format!("- leaf {}", leaf.name))),
);
Text::from(lines)
}
Selection::Leaf { node_id, leaf_name } => {
let node = self.simulation.node(*node_id);
let leaf = node
.leaves
.iter()
.find(|leaf| &leaf.name == leaf_name)
.expect("selection should stay valid");
Text::from(vec![
Line::from(format!("Leaf {}", leaf.name)).bold(),
Line::from(leaf.description.clone()),
Line::from(format!("Node: {}", node.display_path())),
Line::from(format!("Procedures: {}", leaf.procedures.join(", "))),
])
}
};
frame.render_widget(
Paragraph::new(body)
.block(Block::default().borders(Borders::ALL).title("Inspector"))
.wrap(Wrap { trim: true }),
area,
);
}
fn render_trace(&self, frame: &mut Frame<'_>, area: Rect) {
let items = self
.simulation
.trace
.iter()
.rev()
.take(12)
.map(|event| {
ListItem::new(format!(
"#{:03} {} | {}",
event.tick, event.node_path, event.summary
))
})
.collect::<Vec<_>>();
frame.render_widget(
List::new(items).block(Block::default().borders(Borders::ALL).title("Trace")),
area,
);
}
fn render_hooks(&self, frame: &mut Frame<'_>, area: Rect) {
let items = self
.simulation
.hooks
.values()
.map(|hook| {
let status = if hook.closed { "closed" } else { "open" };
ListItem::new(format!(
"#{} {} -> {} [{}] {}",
hook.hook_id,
format_path(&hook.host_path),
format_path(&hook.peer_path),
status,
hook.last_message,
))
})
.collect::<Vec<_>>();
frame.render_widget(
List::new(items).block(Block::default().borders(Borders::ALL).title("Hooks")),
area,
);
}
fn render_footer(&self, frame: &mut Frame<'_>, area: Rect) {
let help = vec![
Line::from(self.status.clone()).style(Style::default().add_modifier(Modifier::BOLD)),
Line::from(
"Keys: arrows move selection/scenario | i introspect | e echo leaf | p ping | c chunked | h open chat | d chat data | b chat bye | f invalid peer | s step | a autoplay | q quit",
),
Line::from(format!(
"Current selection: {}",
self.simulation.selection_summary(self.selected())
)),
Line::from(match self.simulation.recorded_events.last() {
Some(RecordedEvent::Data {
node_path, message, ..
}) => {
format!(
"Last local event: Data at {node_path} ({})",
String::from_utf8_lossy(&message.data)
)
}
Some(RecordedEvent::Fault {
node_path, message, ..
}) => {
format!(
"Last local event: Fault at {node_path} (0x{:02X})",
message.fault.0
)
}
Some(RecordedEvent::Call {
node_path, message, ..
}) => {
format!(
"Last local event: Call at {node_path} ({})",
message.procedure_id
)
}
None => "Last local event: none yet".to_owned(),
}),
];
frame.render_widget(
Paragraph::new(Text::from(help))
.block(Block::default().borders(Borders::ALL).title("Status"))
.wrap(Wrap { trim: true }),
area,
);
}
}
fn build_selections(simulation: &Simulation) -> Vec<Selection> {
let mut selections = Vec::new();
for node in &simulation.tree.nodes {
selections.push(Selection::Node(node.id));
for leaf in &node.leaves {
selections.push(Selection::Leaf {
node_id: node.id,
leaf_name: leaf.name.clone(),
});
}
}
selections
}
treetest/src/lib.rs
+12
View File
@@ -0,0 +1,12 @@
//! Interactive UnShell protocol demo crate.
//!
//! This crate intentionally keeps protocol logic in the root `unshell` crate and
//! uses that implementation as a consumer would: by building endpoint topologies,
//! simulating packet transport, and rendering an inspector UI around the results.
pub mod app;
pub mod model;
pub mod scenarios;
pub mod sim;
pub use app::run;
treetest/src/main.rs
+5
View File
@@ -0,0 +1,5 @@
//! Binary entry point for the protocol demo.
fn main() -> Result<(), treetest::app::AppError> {
treetest::run()
}
treetest/src/model.rs
+184
View File
@@ -0,0 +1,184 @@
//! Static tree and scenario metadata used by the simulator and UI.
//!
//! The protocol runtime already owns routing and hook validation state. This
//! module adds a second, UI-friendly model so the demo can keep titles,
//! descriptions, selection ids, and behavior metadata without polluting the core
//! protocol implementation.
use std::collections::BTreeMap;
/// Stable identifier for a node in a demo tree.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct NodeId(pub usize);
/// Supported demo leaf kinds.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum LeafKind {
/// Uses the built-in echo leaf behavior from `unshell`.
Echo,
}
/// Static leaf declaration used to build a protocol endpoint and describe it in the UI.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LeafSpec {
pub name: String,
pub description: String,
pub kind: LeafKind,
pub procedures: Vec<String>,
}
/// Demo-only endpoint procedure behaviors.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum EndpointProcedureKind {
/// Single response that completes the hook immediately.
Ping,
/// Multi-packet response used to demonstrate chunking and finalization.
ChunkedGreeting,
/// Bidirectional hook that remains active until one side sends `bye`.
Chat,
}
/// Static endpoint procedure definition.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EndpointProcedureSpec {
pub procedure_id: String,
pub description: String,
pub kind: EndpointProcedureKind,
}
/// Recursive scenario node specification.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct NodeSpec {
/// Empty for the root endpoint.
pub segment: String,
pub title: String,
pub description: String,
pub leaves: Vec<LeafSpec>,
pub endpoint_procedures: Vec<EndpointProcedureSpec>,
pub children: Vec<NodeSpec>,
}
/// Concrete node metadata used after scenario construction.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DemoNode {
pub id: NodeId,
pub parent: Option<NodeId>,
pub children: Vec<NodeId>,
pub path: Vec<String>,
pub title: String,
pub description: String,
pub leaves: Vec<LeafSpec>,
pub endpoint_procedures: Vec<EndpointProcedureSpec>,
}
impl DemoNode {
/// Returns a display path that keeps the root easy to recognize in the UI.
pub fn display_path(&self) -> String {
format_path(&self.path)
}
}
/// Fully flattened tree metadata used by the simulator and UI.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DemoTree {
pub root: NodeId,
pub nodes: Vec<DemoNode>,
path_index: BTreeMap<Vec<String>, NodeId>,
}
impl DemoTree {
/// Builds a flattened tree from a recursive specification.
pub fn from_root(spec: &NodeSpec) -> Self {
let mut nodes = Vec::new();
let mut path_index = BTreeMap::new();
let root = Self::push_node(spec, None, &[], &mut nodes, &mut path_index);
Self {
root,
nodes,
path_index,
}
}
fn push_node(
spec: &NodeSpec,
parent: Option<NodeId>,
base_path: &[String],
nodes: &mut Vec<DemoNode>,
path_index: &mut BTreeMap<Vec<String>, NodeId>,
) -> NodeId {
let id = NodeId(nodes.len());
let path = if spec.segment.is_empty() {
base_path.to_vec()
} else {
let mut next = base_path.to_vec();
next.push(spec.segment.clone());
next
};
nodes.push(DemoNode {
id,
parent,
children: Vec::new(),
path: path.clone(),
title: spec.title.clone(),
description: spec.description.clone(),
leaves: spec.leaves.clone(),
endpoint_procedures: spec.endpoint_procedures.clone(),
});
path_index.insert(path.clone(), id);
let child_ids = spec
.children
.iter()
.map(|child| Self::push_node(child, Some(id), &path, nodes, path_index))
.collect::<Vec<_>>();
nodes[id.0].children = child_ids;
id
}
/// Returns the node with the given id.
pub fn node(&self, id: NodeId) -> &DemoNode {
&self.nodes[id.0]
}
/// Resolves an absolute path to a node id.
pub fn find_by_path(&self, path: &[String]) -> Option<NodeId> {
self.path_index.get(path).copied()
}
}
/// Root-focused interaction target shown in the inspector.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Selection {
Node(NodeId),
Leaf { node_id: NodeId, leaf_name: String },
}
impl Selection {
/// Returns the owning node of this selection.
pub fn node_id(&self) -> NodeId {
match self {
Self::Node(node_id) => *node_id,
Self::Leaf { node_id, .. } => *node_id,
}
}
}
/// User-facing scenario definition.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ScenarioDefinition {
pub name: String,
pub description: String,
pub highlights: Vec<String>,
pub root: NodeSpec,
pub initial_selection: Selection,
}
/// Formats a path the same way throughout the UI and tests.
pub fn format_path(path: &[String]) -> String {
if path.is_empty() {
"/".to_owned()
} else {
format!("/{}", path.join("/"))
}
}
treetest/src/scenarios.rs
+310
View File
@@ -0,0 +1,310 @@
//! Demo scenarios ranging from simple introspection to multi-hop hooks.
use crate::model::{
EndpointProcedureKind, EndpointProcedureSpec, LeafKind, LeafSpec, NodeId, NodeSpec,
ScenarioDefinition, Selection,
};
const PROC_PING: &str = "demo.endpoint.v1.control.ping";
const PROC_CHUNKED: &str = "demo.endpoint.v1.stream.chunked_greeting";
const PROC_CHAT: &str = "demo.endpoint.v1.chat.session";
const PROC_ECHO: &str = "demo.leaf.v1.echo.invoke";
/// Returns all built-in demo scenarios.
pub fn built_in_scenarios() -> Vec<ScenarioDefinition> {
vec![
local_introspection(),
echo_leaf(),
branch_routing(),
bidirectional_chat(),
fault_showcase(),
complex_tree(),
]
}
fn local_introspection() -> ScenarioDefinition {
ScenarioDefinition {
name: "Local Introspection".to_owned(),
description:
"Inspect the root and its immediate child using the required empty procedure id."
.to_owned(),
highlights: vec![
"Blank procedure calls map to protocol introspection.".to_owned(),
"Leaf introspection uses the same hook path as endpoint introspection.".to_owned(),
],
root: NodeSpec {
segment: String::new(),
title: "Root".to_owned(),
description: "The operator-controlled root endpoint.".to_owned(),
leaves: Vec::new(),
endpoint_procedures: vec![EndpointProcedureSpec {
procedure_id: PROC_PING.to_owned(),
description: "Single-packet endpoint response for baseline testing.".to_owned(),
kind: EndpointProcedureKind::Ping,
}],
children: vec![NodeSpec {
segment: "alpha".to_owned(),
title: "Alpha".to_owned(),
description: "A minimal child endpoint with one echo leaf.".to_owned(),
leaves: vec![LeafSpec {
name: "echo".to_owned(),
description: "Echoes bytes back through the declared hook.".to_owned(),
kind: LeafKind::Echo,
procedures: vec![PROC_ECHO.to_owned()],
}],
endpoint_procedures: Vec::new(),
children: Vec::new(),
}],
},
initial_selection: Selection::Node(NodeId(0)),
}
}
fn echo_leaf() -> ScenarioDefinition {
ScenarioDefinition {
name: "Echo Leaf".to_owned(),
description: "Call a concrete leaf and watch the hook finish normally.".to_owned(),
highlights: vec![
"The leaf uses the built-in `Echo` behavior from the core runtime.".to_owned(),
"The final response sets `end_hook = true`.".to_owned(),
],
root: NodeSpec {
segment: String::new(),
title: "Root".to_owned(),
description: "The operator origin for all demo calls.".to_owned(),
leaves: Vec::new(),
endpoint_procedures: Vec::new(),
children: vec![NodeSpec {
segment: "services".to_owned(),
title: "Services".to_owned(),
description: "Hosts protocol-visible demo leaves.".to_owned(),
leaves: vec![LeafSpec {
name: "echo".to_owned(),
description: "Simple echo leaf.".to_owned(),
kind: LeafKind::Echo,
procedures: vec![PROC_ECHO.to_owned()],
}],
endpoint_procedures: vec![EndpointProcedureSpec {
procedure_id: PROC_CHUNKED.to_owned(),
description: "Three response packets with a clear final chunk.".to_owned(),
kind: EndpointProcedureKind::ChunkedGreeting,
}],
children: Vec::new(),
}],
},
initial_selection: Selection::Leaf {
node_id: NodeId(1),
leaf_name: "echo".to_owned(),
},
}
}
fn branch_routing() -> ScenarioDefinition {
ScenarioDefinition {
name: "Branch Routing".to_owned(),
description: "Demonstrates longest-prefix routing across sibling branches.".to_owned(),
highlights: vec![
"Packets descend through the most specific child path.".to_owned(),
"Responses route back upward and then down into the hook host subtree.".to_owned(),
],
root: NodeSpec {
segment: String::new(),
title: "Root".to_owned(),
description: "The routing apex.".to_owned(),
leaves: Vec::new(),
endpoint_procedures: Vec::new(),
children: vec![
NodeSpec {
segment: "alpha".to_owned(),
title: "Alpha".to_owned(),
description: "Intermediate branch.".to_owned(),
leaves: Vec::new(),
endpoint_procedures: Vec::new(),
children: vec![NodeSpec {
segment: "beta".to_owned(),
title: "Beta".to_owned(),
description: "Nested endpoint for longest-prefix routing.".to_owned(),
leaves: vec![LeafSpec {
name: "echo".to_owned(),
description: "Nested echo leaf.".to_owned(),
kind: LeafKind::Echo,
procedures: vec![PROC_ECHO.to_owned()],
}],
endpoint_procedures: vec![EndpointProcedureSpec {
procedure_id: PROC_PING.to_owned(),
description: "Checks routed endpoint procedures.".to_owned(),
kind: EndpointProcedureKind::Ping,
}],
children: Vec::new(),
}],
},
NodeSpec {
segment: "gamma".to_owned(),
title: "Gamma".to_owned(),
description: "Sibling endpoint used to make the route tree non-trivial."
.to_owned(),
leaves: vec![LeafSpec {
name: "echo".to_owned(),
description: "Sibling echo leaf.".to_owned(),
kind: LeafKind::Echo,
procedures: vec![PROC_ECHO.to_owned()],
}],
endpoint_procedures: Vec::new(),
children: Vec::new(),
},
],
},
initial_selection: Selection::Node(NodeId(2)),
}
}
fn bidirectional_chat() -> ScenarioDefinition {
ScenarioDefinition {
name: "Bidirectional Chat".to_owned(),
description: "Keeps a hook active so the root can continue sending `Data` packets.".to_owned(),
highlights: vec![
"After activation, either side may send hook data first.".to_owned(),
"The chat handler exists outside the core runtime so the demo can show application-level behavior without changing the protocol.".to_owned(),
],
root: NodeSpec {
segment: String::new(),
title: "Root".to_owned(),
description: "The operator-controlled hook host.".to_owned(),
leaves: Vec::new(),
endpoint_procedures: Vec::new(),
children: vec![NodeSpec {
segment: "chat".to_owned(),
title: "Chat Host".to_owned(),
description: "Endpoint with a long-lived hook-backed chat procedure.".to_owned(),
leaves: Vec::new(),
endpoint_procedures: vec![EndpointProcedureSpec {
procedure_id: PROC_CHAT.to_owned(),
description: "Bidirectional hook that replies until it sees `bye`.".to_owned(),
kind: EndpointProcedureKind::Chat,
}],
children: Vec::new(),
}],
},
initial_selection: Selection::Node(NodeId(1)),
}
}
fn fault_showcase() -> ScenarioDefinition {
ScenarioDefinition {
name: "Fault Showcase".to_owned(),
description: "Use valid and invalid calls to trigger protocol-level faults.".to_owned(),
highlights: vec![
"Unknown leaf and unknown procedure faults are attributed to the declared hook."
.to_owned(),
"Packets with an invalid hook peer are rejected and faulted locally.".to_owned(),
],
root: NodeSpec {
segment: String::new(),
title: "Root".to_owned(),
description: "Runs fault-focused experiments.".to_owned(),
leaves: Vec::new(),
endpoint_procedures: Vec::new(),
children: vec![NodeSpec {
segment: "faults".to_owned(),
title: "Fault Lab".to_owned(),
description: "One endpoint with one known leaf and one known procedure.".to_owned(),
leaves: vec![LeafSpec {
name: "echo".to_owned(),
description: "Valid leaf used to contrast unknown-leaf failures.".to_owned(),
kind: LeafKind::Echo,
procedures: vec![PROC_ECHO.to_owned()],
}],
endpoint_procedures: vec![EndpointProcedureSpec {
procedure_id: PROC_PING.to_owned(),
description: "Known procedure for contrast against unknown procedures."
.to_owned(),
kind: EndpointProcedureKind::Ping,
}],
children: Vec::new(),
}],
},
initial_selection: Selection::Node(NodeId(1)),
}
}
fn complex_tree() -> ScenarioDefinition {
ScenarioDefinition {
name: "Complex Tree".to_owned(),
description: "A larger topology that combines leaf calls, endpoint procedures, and nested routing.".to_owned(),
highlights: vec![
"Use this as a sandbox after learning the smaller scenarios.".to_owned(),
"The tree contains both leaf and endpoint interactions so the UI inspector stays interesting.".to_owned(),
],
root: NodeSpec {
segment: String::new(),
title: "Root".to_owned(),
description: "Primary operator endpoint.".to_owned(),
leaves: Vec::new(),
endpoint_procedures: vec![EndpointProcedureSpec {
procedure_id: PROC_PING.to_owned(),
description: "Root-local endpoint procedure for comparison with remote calls.".to_owned(),
kind: EndpointProcedureKind::Ping,
}],
children: vec![
NodeSpec {
segment: "alpha".to_owned(),
title: "Alpha".to_owned(),
description: "Left branch.".to_owned(),
leaves: vec![LeafSpec {
name: "echo".to_owned(),
description: "Echo leaf on alpha.".to_owned(),
kind: LeafKind::Echo,
procedures: vec![PROC_ECHO.to_owned()],
}],
endpoint_procedures: vec![EndpointProcedureSpec {
procedure_id: PROC_CHUNKED.to_owned(),
description: "Chunked endpoint response.".to_owned(),
kind: EndpointProcedureKind::ChunkedGreeting,
}],
children: vec![NodeSpec {
segment: "deep".to_owned(),
title: "Alpha Deep".to_owned(),
description: "Nested node for multi-hop traffic.".to_owned(),
leaves: vec![LeafSpec {
name: "echo".to_owned(),
description: "Deep nested echo leaf.".to_owned(),
kind: LeafKind::Echo,
procedures: vec![PROC_ECHO.to_owned()],
}],
endpoint_procedures: Vec::new(),
children: Vec::new(),
}],
},
NodeSpec {
segment: "beta".to_owned(),
title: "Beta".to_owned(),
description: "Right branch.".to_owned(),
leaves: Vec::new(),
endpoint_procedures: vec![EndpointProcedureSpec {
procedure_id: PROC_CHAT.to_owned(),
description: "Long-lived chat procedure.".to_owned(),
kind: EndpointProcedureKind::Chat,
}],
children: vec![NodeSpec {
segment: "gamma".to_owned(),
title: "Gamma".to_owned(),
description: "Nested branch with its own ping procedure.".to_owned(),
leaves: vec![LeafSpec {
name: "echo".to_owned(),
description: "Gamma echo leaf.".to_owned(),
kind: LeafKind::Echo,
procedures: vec![PROC_ECHO.to_owned()],
}],
endpoint_procedures: vec![EndpointProcedureSpec {
procedure_id: PROC_PING.to_owned(),
description: "Nested ping procedure.".to_owned(),
kind: EndpointProcedureKind::Ping,
}],
children: Vec::new(),
}],
},
],
},
initial_selection: Selection::Node(NodeId(0)),
}
}
treetest/src/sim.rs
+842
View File
@@ -0,0 +1,842 @@
//! Crossbeam-backed protocol simulation.
//!
//! The simulator never opens real sockets. Each endpoint gets a mailbox, and
//! forwarded frames are pushed into the next hop's queue. That makes routing and
//! hook behavior deterministic enough for tests while still feeling like traffic.
use std::collections::{BTreeMap, VecDeque};
use crossbeam_channel::{Receiver, Sender, TryRecvError, unbounded};
use thiserror::Error;
use unshell::protocol::tree::{
ChildRoute, ConnectionState, Endpoint, Ingress, LeafBehavior, LocalEvent, ProtocolEndpoint,
};
use unshell::protocol::{
CallMessage, DataMessage, FaultMessage, FrameBytes, PacketHeader, PacketType, decode_frame,
};
use crate::model::{
DemoTree, EndpointProcedureKind, EndpointProcedureSpec, LeafKind, NodeId, ScenarioDefinition,
Selection, format_path,
};
/// User-facing outcome of a root-originated action.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ActionResult {
pub label: String,
pub hook_id: Option<u64>,
}
/// Snapshot of a hook interaction observed by the demo.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HookSnapshot {
pub hook_id: u64,
pub host_path: Vec<String>,
pub peer_path: Vec<String>,
pub procedure_id: String,
pub closed: bool,
pub last_message: String,
}
/// Trace entry shown in the UI and asserted in tests.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TraceEvent {
pub tick: u64,
pub node_path: String,
pub summary: String,
}
/// Summary of one local protocol event.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum RecordedEvent {
Data {
node_path: String,
header: PacketHeader,
message: DataMessage,
},
Fault {
node_path: String,
header: PacketHeader,
message: FaultMessage,
},
Call {
node_path: String,
header: PacketHeader,
message: CallMessage,
},
}
#[derive(Debug)]
struct SimNode {
parent: Option<NodeId>,
children: Vec<NodeId>,
endpoint: ProtocolEndpoint,
tx: Sender<Envelope>,
rx: Receiver<Envelope>,
}
#[derive(Debug, Clone)]
struct Envelope {
ingress: Ingress,
frame: FrameBytes,
}
#[derive(Debug, Clone, PartialEq, Eq)]
struct ChatSession {
node_id: NodeId,
hook_id: u64,
host_path: Vec<String>,
procedure_id: String,
}
/// Errors raised by the demo simulator.
#[derive(Debug, Error)]
pub enum SimError {
#[error("node {0} was not found")]
UnknownNode(String),
#[error("leaf {leaf_name} was not found on {node_path}")]
UnknownLeaf {
node_path: String,
leaf_name: String,
},
#[error("procedure {procedure_id} was not found on {node_path}")]
UnknownProcedure {
node_path: String,
procedure_id: String,
},
#[error("hook {0} was not found")]
UnknownHook(u64),
#[error("protocol runtime error: {0}")]
Protocol(String),
}
/// Fully built simulation for one scenario.
#[derive(Debug)]
pub struct Simulation {
pub scenario: ScenarioDefinition,
pub tree: DemoTree,
nodes: Vec<SimNode>,
root_id: NodeId,
next_tick: u64,
pub trace: VecDeque<TraceEvent>,
pub recorded_events: Vec<RecordedEvent>,
pub hooks: BTreeMap<u64, HookSnapshot>,
chat_sessions: BTreeMap<u64, ChatSession>,
}
impl Simulation {
/// Creates a fresh simulation from a scenario definition.
pub fn new(scenario: ScenarioDefinition) -> Result<Self, SimError> {
let tree = DemoTree::from_root(&scenario.root);
let mut nodes = Vec::with_capacity(tree.nodes.len());
for demo_node in &tree.nodes {
let (tx, rx) = unbounded();
let children = demo_node
.children
.iter()
.map(|child_id| ChildRoute {
path: tree.node(*child_id).path.clone(),
state: ConnectionState::Registered,
})
.collect::<Vec<_>>();
let leaves = demo_node
.leaves
.iter()
.map(|leaf| unshell::protocol::tree::LeafSpec {
name: leaf.name.clone(),
procedures: leaf.procedures.clone(),
behavior: match leaf.kind {
LeafKind::Echo => LeafBehavior::Echo,
},
})
.collect::<Vec<_>>();
let parent_path = demo_node
.parent
.map(|parent_id| tree.node(parent_id).path.clone());
let mut endpoint =
ProtocolEndpoint::new(demo_node.path.clone(), parent_path, children, leaves);
for procedure in &demo_node.endpoint_procedures {
endpoint
.add_endpoint_procedure(procedure.procedure_id.clone())
.map_err(|error| SimError::Protocol(error.to_string()))?;
}
nodes.push(SimNode {
parent: demo_node.parent,
children: demo_node.children.clone(),
endpoint,
tx,
rx,
});
}
Ok(Self {
scenario,
tree,
nodes,
root_id: NodeId(0),
next_tick: 1,
trace: VecDeque::new(),
recorded_events: Vec::new(),
hooks: BTreeMap::new(),
chat_sessions: BTreeMap::new(),
})
}
/// Returns the scenario's initial selection.
pub fn initial_selection(&self) -> Selection {
self.scenario.initial_selection.clone()
}
/// Returns a node by id.
pub fn node(&self, id: NodeId) -> &crate::model::DemoNode {
self.tree.node(id)
}
/// Builds and routes an endpoint introspection call from the root.
pub fn call_endpoint_introspection(
&mut self,
node_id: NodeId,
) -> Result<ActionResult, SimError> {
let path = self.tree.node(node_id).path.clone();
self.dispatch_root_call(path.clone(), None, "", Vec::new())?;
Ok(ActionResult {
label: format!("Inspect endpoint {}", format_path(&path)),
hook_id: self.hooks.last_key_value().map(|(hook_id, _)| *hook_id),
})
}
/// Builds and routes a leaf introspection call from the root.
pub fn call_leaf_introspection(
&mut self,
node_id: NodeId,
leaf_name: &str,
) -> Result<ActionResult, SimError> {
let node_path = self.tree.node(node_id).path.clone();
let node_display = self.tree.node(node_id).display_path();
self.require_leaf(node_id, leaf_name)?;
self.dispatch_root_call(node_path, Some(leaf_name.to_owned()), "", Vec::new())?;
Ok(ActionResult {
label: format!("Inspect leaf {} on {}", leaf_name, node_display),
hook_id: self.hooks.last_key_value().map(|(hook_id, _)| *hook_id),
})
}
/// Calls a leaf echo procedure using the selected payload.
pub fn call_echo_leaf(
&mut self,
node_id: NodeId,
leaf_name: &str,
text: &str,
) -> Result<ActionResult, SimError> {
let node_path = self.tree.node(node_id).path.clone();
let node_display = self.tree.node(node_id).display_path();
let leaf = self.require_leaf(node_id, leaf_name)?;
let procedure_id =
leaf.procedures
.first()
.cloned()
.ok_or_else(|| SimError::UnknownProcedure {
node_path: node_display.clone(),
procedure_id: "<missing>".to_owned(),
})?;
self.dispatch_root_call(
node_path,
Some(leaf_name.to_owned()),
&procedure_id,
text.as_bytes().to_vec(),
)?;
Ok(ActionResult {
label: format!("Echo via {leaf_name} on {}", node_display),
hook_id: self.hooks.last_key_value().map(|(hook_id, _)| *hook_id),
})
}
/// Calls an endpoint-level procedure.
pub fn call_endpoint_procedure(
&mut self,
node_id: NodeId,
procedure_id: &str,
data: Vec<u8>,
) -> Result<ActionResult, SimError> {
let node_path = self.tree.node(node_id).path.clone();
let node_display = self.tree.node(node_id).display_path();
self.require_endpoint_procedure(node_id, procedure_id)?;
self.dispatch_root_call(node_path, None, procedure_id, data)?;
Ok(ActionResult {
label: format!("Call {procedure_id} on {}", node_display),
hook_id: self.hooks.last_key_value().map(|(hook_id, _)| *hook_id),
})
}
/// Sends a raw call without demo-side validation so tests can exercise
/// remote `UnknownLeaf` and `UnknownProcedure` fault behavior.
pub fn call_unchecked(
&mut self,
node_id: NodeId,
dst_leaf: Option<&str>,
procedure_id: &str,
data: Vec<u8>,
) -> Result<ActionResult, SimError> {
let node_path = self.tree.node(node_id).path.clone();
let node_display = self.tree.node(node_id).display_path();
self.dispatch_root_call(node_path, dst_leaf.map(str::to_owned), procedure_id, data)?;
Ok(ActionResult {
label: format!(
"Call {} on {}{}",
if procedure_id.is_empty() {
"<introspection>"
} else {
procedure_id
},
node_display,
dst_leaf
.map(|leaf_name| format!(" leaf {leaf_name}"))
.unwrap_or_default()
),
hook_id: self.hooks.last_key_value().map(|(hook_id, _)| *hook_id),
})
}
/// Sends more hook data from the root side.
pub fn send_root_hook_data(
&mut self,
hook_id: u64,
text: &str,
end_hook: bool,
) -> Result<ActionResult, SimError> {
let snapshot = self
.hooks
.get(&hook_id)
.cloned()
.ok_or(SimError::UnknownHook(hook_id))?;
let frame = self.nodes[self.root_id.0]
.endpoint
.make_data(
snapshot.peer_path.clone(),
hook_id,
snapshot.procedure_id.clone(),
text.as_bytes().to_vec(),
end_hook,
)
.map_err(|error| SimError::Protocol(error.to_string()))?;
self.record_trace(
self.root_id,
format!("root queued hook data for hook #{hook_id}: {text}"),
);
self.process_local_frame(self.root_id, frame)?;
Ok(ActionResult {
label: format!("Send hook data #{hook_id}"),
hook_id: Some(hook_id),
})
}
/// Injects intentionally invalid traffic to demonstrate `InvalidHookPeer`.
pub fn inject_invalid_peer_data(
&mut self,
from_node_id: NodeId,
to_node_id: NodeId,
hook_id: u64,
procedure_id: &str,
text: &str,
) -> Result<ActionResult, SimError> {
let from_path = self.tree.node(from_node_id).path.clone();
let to_path = self.tree.node(to_node_id).path.clone();
let header = PacketHeader {
packet_type: PacketType::Data,
src_path: from_path.clone(),
dst_path: to_path.clone(),
dst_leaf: None,
hook_id: Some(hook_id),
};
let message = DataMessage {
procedure_id: procedure_id.to_owned(),
data: text.as_bytes().to_vec(),
end_hook: false,
};
let frame = unshell::protocol::encode_packet(&header, &message)
.map_err(|error| SimError::Protocol(error.to_string()))?;
self.record_trace(
from_node_id,
format!(
"injected invalid peer data toward {} for hook #{hook_id}",
format_path(&to_path)
),
);
self.process_local_frame(from_node_id, frame)?;
Ok(ActionResult {
label: format!("Inject invalid peer data for hook #{hook_id}"),
hook_id: Some(hook_id),
})
}
/// Processes one queued frame if available.
pub fn step(&mut self) -> Result<bool, SimError> {
for node_id in 0..self.nodes.len() {
match self.nodes[node_id].rx.try_recv() {
Ok(envelope) => {
self.record_trace(
NodeId(node_id),
format!("received frame via {:?}", envelope.ingress),
);
let outcome = self.nodes[node_id]
.endpoint
.receive(&envelope.ingress, envelope.frame)
.map_err(|error| SimError::Protocol(error.to_string()))?;
self.process_outcome(NodeId(node_id), outcome)?;
return Ok(true);
}
Err(TryRecvError::Disconnected) => {
return Err(SimError::Protocol("mailbox disconnected".to_owned()));
}
Err(TryRecvError::Empty) => {}
}
}
Ok(false)
}
/// Runs frames until the network becomes idle.
pub fn drain(&mut self) -> Result<usize, SimError> {
let mut steps = 0;
while self.step()? {
steps += 1;
}
Ok(steps)
}
fn dispatch_root_call(
&mut self,
dst_path: Vec<String>,
dst_leaf: Option<String>,
procedure_id: &str,
data: Vec<u8>,
) -> Result<(), SimError> {
let hook_id = self.nodes[self.root_id.0].endpoint.allocate_hook_id();
let frame = self.nodes[self.root_id.0]
.endpoint
.make_call(
dst_path.clone(),
dst_leaf.clone(),
procedure_id.to_owned(),
Some(hook_id),
data,
)
.map_err(|error| SimError::Protocol(error.to_string()))?;
self.hooks.insert(
hook_id,
HookSnapshot {
hook_id,
host_path: Vec::new(),
peer_path: dst_path.clone(),
procedure_id: procedure_id.to_owned(),
closed: false,
last_message: format!("created for {}", format_path(&dst_path)),
},
);
self.record_trace(
self.root_id,
format!(
"root queued Call {} toward {}{}",
if procedure_id.is_empty() {
"<introspection>"
} else {
procedure_id
},
format_path(&dst_path),
dst_leaf
.as_ref()
.map(|leaf| format!(" leaf {leaf}"))
.unwrap_or_default()
),
);
self.process_local_frame(self.root_id, frame)
}
fn process_local_frame(&mut self, node_id: NodeId, frame: FrameBytes) -> Result<(), SimError> {
let outcome = self.nodes[node_id.0]
.endpoint
.receive(&Ingress::Local, frame)
.map_err(|error| SimError::Protocol(error.to_string()))?;
self.process_outcome(node_id, outcome)
}
fn process_outcome(
&mut self,
node_id: NodeId,
outcome: unshell::protocol::tree::EndpointOutcome,
) -> Result<(), SimError> {
if outcome.dropped {
self.record_trace(node_id, "packet dropped".to_owned());
}
for (route, frame) in outcome.forwards {
match route {
unshell::protocol::tree::RouteDecision::Child(index) => {
let child_id = self.nodes[node_id.0]
.children
.get(index)
.copied()
.ok_or_else(|| {
SimError::Protocol(format!("missing child index {index}"))
})?;
self.record_trace(
node_id,
format!(
"forwarded frame to child {}",
self.node(child_id).display_path()
),
);
self.nodes[child_id.0]
.tx
.send(Envelope {
ingress: Ingress::Parent,
frame,
})
.map_err(|error| SimError::Protocol(error.to_string()))?;
}
unshell::protocol::tree::RouteDecision::Parent => {
let parent_id = self.nodes[node_id.0]
.parent
.ok_or_else(|| SimError::Protocol("missing parent route".to_owned()))?;
let child_path = self.node(node_id).path.clone();
self.record_trace(
node_id,
format!(
"forwarded frame to parent {}",
self.node(parent_id).display_path()
),
);
self.nodes[parent_id.0]
.tx
.send(Envelope {
ingress: Ingress::Child(child_path),
frame,
})
.map_err(|error| SimError::Protocol(error.to_string()))?;
}
unshell::protocol::tree::RouteDecision::Local => {
return Err(SimError::Protocol(
"local route leaked into forward list".to_owned(),
));
}
unshell::protocol::tree::RouteDecision::Drop => {
self.record_trace(node_id, "route decision dropped frame".to_owned());
}
}
}
for event in outcome.events {
self.handle_local_event(node_id, event)?;
}
Ok(())
}
fn handle_local_event(&mut self, node_id: NodeId, event: LocalEvent) -> Result<(), SimError> {
let node_path = self.node(node_id).display_path();
match event {
LocalEvent::Data { header, message } => {
let text = String::from_utf8_lossy(&message.data).to_string();
self.record_trace(
node_id,
format!(
"local Data on hook #{}: {text}",
header.hook_id.unwrap_or(0)
),
);
if let Some(hook_id) = header.hook_id {
if let Some(snapshot) = self.hooks.get_mut(&hook_id) {
snapshot.last_message = if text.is_empty() {
format!("binary payload ({} bytes)", message.data.len())
} else {
text.clone()
};
if message.end_hook {
snapshot.closed = true;
}
}
}
if let Some(session) = self
.chat_sessions
.get(&header.hook_id.unwrap_or(0))
.cloned()
.filter(|session| session.node_id == node_id)
{
// Rationale: chat responses are implemented here instead of in the
// core endpoint so the protocol crate stays generic. The simulator
// acts as the application layer sitting above validated hook traffic.
let reply = if text.eq_ignore_ascii_case("bye") {
Some(("chat session closed".to_owned(), true))
} else if !text.is_empty() {
Some((format!("chat ack: {}", text.to_uppercase()), false))
} else {
None
};
if let Some((reply, end_hook)) = reply {
let frame = self.nodes[session.node_id.0]
.endpoint
.make_data(
session.host_path.clone(),
session.hook_id,
session.procedure_id.clone(),
reply.clone().into_bytes(),
end_hook,
)
.map_err(|error| SimError::Protocol(error.to_string()))?;
self.record_trace(session.node_id, format!("chat handler sent: {reply}"));
self.process_local_frame(session.node_id, frame)?;
if end_hook {
self.chat_sessions.remove(&session.hook_id);
}
}
}
self.recorded_events.push(RecordedEvent::Data {
node_path,
header,
message,
});
}
LocalEvent::Fault { header, message } => {
self.record_trace(
node_id,
format!(
"local Fault on hook #{}: 0x{:02X}",
header.hook_id.unwrap_or(0),
message.fault.0
),
);
if let Some(hook_id) = header.hook_id {
if let Some(snapshot) = self.hooks.get_mut(&hook_id) {
snapshot.closed = true;
snapshot.last_message = format!("fault 0x{:02X}", message.fault.0);
}
self.chat_sessions.remove(&hook_id);
}
self.recorded_events.push(RecordedEvent::Fault {
node_path,
header,
message,
});
}
LocalEvent::Call { header, message } => {
self.record_trace(
node_id,
format!(
"local Call {} on {}",
message.procedure_id,
header
.dst_leaf
.as_ref()
.map(|leaf| format!("leaf {leaf}"))
.unwrap_or_else(|| "endpoint".to_owned())
),
);
self.handle_application_call(node_id, &header, &message)?;
self.recorded_events.push(RecordedEvent::Call {
node_path,
header,
message,
});
}
}
Ok(())
}
fn handle_application_call(
&mut self,
node_id: NodeId,
_header: &PacketHeader,
message: &CallMessage,
) -> Result<(), SimError> {
let Some(hook) = &message.response_hook else {
return Ok(());
};
let procedure = self
.lookup_endpoint_procedure(node_id, &message.procedure_id)?
.clone();
match procedure.kind {
EndpointProcedureKind::Ping => {
let reply = format!("pong from {}", self.node(node_id).display_path());
let frame = self.nodes[node_id.0]
.endpoint
.make_data(
hook.return_path.clone(),
hook.hook_id,
procedure.procedure_id.clone(),
reply.clone().into_bytes(),
true,
)
.map_err(|error| SimError::Protocol(error.to_string()))?;
self.record_trace(node_id, format!("endpoint sent ping reply: {reply}"));
self.process_local_frame(node_id, frame)?;
}
EndpointProcedureKind::ChunkedGreeting => {
for (index, text) in [
"chunk 1: hello from the endpoint",
"chunk 2: routing stayed path-based",
"chunk 3: hook complete",
]
.iter()
.enumerate()
{
let frame = self.nodes[node_id.0]
.endpoint
.make_data(
hook.return_path.clone(),
hook.hook_id,
procedure.procedure_id.clone(),
text.as_bytes().to_vec(),
index == 2,
)
.map_err(|error| SimError::Protocol(error.to_string()))?;
self.record_trace(node_id, format!("endpoint sent chunk {}", index + 1));
self.process_local_frame(node_id, frame)?;
}
}
EndpointProcedureKind::Chat => {
self.chat_sessions.insert(
hook.hook_id,
ChatSession {
node_id,
hook_id: hook.hook_id,
host_path: hook.return_path.clone(),
procedure_id: procedure.procedure_id.clone(),
},
);
let frame = self.nodes[node_id.0]
.endpoint
.make_data(
hook.return_path.clone(),
hook.hook_id,
procedure.procedure_id.clone(),
b"chat ready".to_vec(),
false,
)
.map_err(|error| SimError::Protocol(error.to_string()))?;
self.record_trace(node_id, "chat handler opened session".to_owned());
self.process_local_frame(node_id, frame)?;
}
}
Ok(())
}
fn lookup_endpoint_procedure(
&self,
node_id: NodeId,
procedure_id: &str,
) -> Result<&EndpointProcedureSpec, SimError> {
self.node(node_id)
.endpoint_procedures
.iter()
.find(|procedure| procedure.procedure_id == procedure_id)
.ok_or_else(|| SimError::UnknownProcedure {
node_path: self.node(node_id).display_path(),
procedure_id: procedure_id.to_owned(),
})
}
fn require_leaf(
&self,
node_id: NodeId,
leaf_name: &str,
) -> Result<&crate::model::LeafSpec, SimError> {
self.node(node_id)
.leaves
.iter()
.find(|leaf| leaf.name == leaf_name)
.ok_or_else(|| SimError::UnknownLeaf {
node_path: self.node(node_id).display_path(),
leaf_name: leaf_name.to_owned(),
})
}
fn require_endpoint_procedure(
&self,
node_id: NodeId,
procedure_id: &str,
) -> Result<(), SimError> {
self.lookup_endpoint_procedure(node_id, procedure_id)
.map(|_| ())
}
fn record_trace(&mut self, node_id: NodeId, summary: String) {
let node_path = self.node(node_id).display_path();
self.trace.push_back(TraceEvent {
tick: self.next_tick,
node_path,
summary,
});
self.next_tick += 1;
while self.trace.len() > 200 {
self.trace.pop_front();
}
}
/// Returns a compact description of a frame for debugging.
pub fn describe_frame(frame: &[u8]) -> String {
match decode_frame(frame) {
Ok(parsed) => {
let header = parsed.header();
format!(
"{:?} {} -> {} hook {:?}",
header.packet_type,
format_path(&header.src_path),
format_path(&header.dst_path),
header.hook_id,
)
}
Err(error) => format!("<invalid frame: {error}>"),
}
}
/// Returns the latest fault observed at the root, if any.
pub fn latest_root_fault(&self) -> Option<&FaultMessage> {
self.recorded_events
.iter()
.rev()
.find_map(|event| match event {
RecordedEvent::Fault {
node_path, message, ..
} if node_path == "/" => Some(message),
_ => None,
})
}
/// Returns the latest root data message as utf-8 for tests and status text.
pub fn latest_root_data_text(&self) -> Option<String> {
self.recorded_events
.iter()
.rev()
.find_map(|event| match event {
RecordedEvent::Data {
node_path, message, ..
} if node_path == "/" => Some(String::from_utf8_lossy(&message.data).to_string()),
_ => None,
})
}
/// Returns all hook ids known to the demo in ascending order.
pub fn hook_ids(&self) -> Vec<u64> {
self.hooks.keys().copied().collect()
}
/// Builds a human-readable description of the current selection.
pub fn selection_summary(&self, selection: &Selection) -> String {
match selection {
Selection::Node(node_id) => {
let node = self.node(*node_id);
format!("{}: {}", node.display_path(), node.title)
}
Selection::Leaf { node_id, leaf_name } => {
format!("{} leaf {}", self.node(*node_id).display_path(), leaf_name)
}
}
}
}
treetest/tests/faults.rs
+80
View File
@@ -0,0 +1,80 @@
use treetest::{model::NodeId, scenarios::built_in_scenarios, sim::Simulation};
use unshell::protocol::ProtocolFault;
#[test]
fn unknown_leaf_and_unknown_procedure_fault_to_root() {
let scenarios = built_in_scenarios();
let mut simulation = Simulation::new(scenarios[4].clone()).expect("scenario should build");
simulation
.call_unchecked(
NodeId(1),
Some("missing_leaf"),
"demo.leaf.v1.echo.invoke",
Vec::new(),
)
.expect("unknown leaf call should start");
simulation.drain().expect("network should drain");
assert_eq!(
simulation
.latest_root_fault()
.expect("root should observe unknown-leaf fault")
.fault,
ProtocolFault::UNKNOWN_LEAF
);
simulation
.call_unchecked(
NodeId(1),
None,
"demo.endpoint.v1.control.missing",
Vec::new(),
)
.expect("unknown procedure call should start");
simulation.drain().expect("network should drain");
assert_eq!(
simulation
.latest_root_fault()
.expect("root should observe unknown-procedure fault")
.fault,
ProtocolFault::UNKNOWN_PROCEDURE
);
}
#[test]
fn invalid_hook_peer_faults_an_active_chat_hook() {
let scenarios = built_in_scenarios();
let mut simulation = Simulation::new(scenarios[5].clone()).expect("scenario should build");
simulation
.call_endpoint_procedure(NodeId(3), "demo.endpoint.v1.chat.session", b"open".to_vec())
.expect("chat call should start");
simulation.drain().expect("network should drain");
let hook_id = *simulation.hook_ids().last().expect("hook should exist");
simulation
.inject_invalid_peer_data(
NodeId(1),
NodeId(0),
hook_id,
"demo.endpoint.v1.chat.session",
"spoof",
)
.expect("invalid peer injection should enqueue");
simulation.drain().expect("network should drain");
assert_eq!(
simulation
.latest_root_fault()
.expect("root should observe a fault")
.fault,
ProtocolFault::INVALID_HOOK_PEER
);
assert!(
simulation
.hooks
.get(&hook_id)
.expect("hook snapshot should exist")
.closed
);
}
treetest/tests/hooks.rs
+50
View File
@@ -0,0 +1,50 @@
use treetest::{model::NodeId, scenarios::built_in_scenarios, sim::Simulation};
#[test]
fn bidirectional_chat_remains_active_until_bye() {
let scenarios = built_in_scenarios();
let mut simulation = Simulation::new(scenarios[3].clone()).expect("scenario should build");
simulation
.call_endpoint_procedure(NodeId(1), "demo.endpoint.v1.chat.session", b"open".to_vec())
.expect("chat call should start");
simulation.drain().expect("network should drain");
let hook_id = *simulation.hook_ids().last().expect("hook should exist");
assert!(
!simulation
.hooks
.get(&hook_id)
.expect("hook snapshot should exist")
.closed
);
assert_eq!(
simulation.latest_root_data_text().as_deref(),
Some("chat ready")
);
simulation
.send_root_hook_data(hook_id, "hello there", false)
.expect("chat data should send");
simulation.drain().expect("network should drain");
assert_eq!(
simulation.latest_root_data_text().as_deref(),
Some("chat ack: HELLO THERE")
);
simulation
.send_root_hook_data(hook_id, "bye", true)
.expect("chat close should send");
simulation.drain().expect("network should drain");
assert!(
simulation
.hooks
.get(&hook_id)
.expect("hook snapshot should exist")
.closed
);
assert_eq!(
simulation.latest_root_data_text().as_deref(),
Some("chat session closed")
);
}
treetest/tests/protocol_basics.rs
+43
View File
@@ -0,0 +1,43 @@
use treetest::{scenarios::built_in_scenarios, sim::Simulation};
#[test]
fn endpoint_and_leaf_introspection_complete_successfully() {
let scenarios = built_in_scenarios();
let mut simulation = Simulation::new(scenarios[0].clone()).expect("scenario should build");
simulation
.call_endpoint_introspection(treetest::model::NodeId(1))
.expect("endpoint introspection should start");
simulation.drain().expect("network should drain");
assert!(simulation.latest_root_data_text().is_some());
simulation
.call_leaf_introspection(treetest::model::NodeId(1), "echo")
.expect("leaf introspection should start");
simulation.drain().expect("network should drain");
assert!(simulation.latest_root_data_text().is_some());
}
#[test]
fn echo_leaf_round_trips_user_payload() {
let scenarios = built_in_scenarios();
let mut simulation = Simulation::new(scenarios[1].clone()).expect("scenario should build");
simulation
.call_echo_leaf(treetest::model::NodeId(1), "echo", "hello from test")
.expect("echo call should start");
simulation.drain().expect("network should drain");
assert_eq!(
simulation.latest_root_data_text().as_deref(),
Some("hello from test")
);
let hook_id = *simulation.hook_ids().last().expect("hook should exist");
assert!(
simulation
.hooks
.get(&hook_id)
.expect("hook snapshot should exist")
.closed
);
}
treetest/tests/routing.rs
+51
View File
@@ -0,0 +1,51 @@
use treetest::{model::NodeId, scenarios::built_in_scenarios, sim::Simulation};
#[test]
fn nested_route_uses_longest_prefix_path() {
let scenarios = built_in_scenarios();
let mut simulation = Simulation::new(scenarios[2].clone()).expect("scenario should build");
simulation
.call_echo_leaf(NodeId(2), "echo", "nested")
.expect("echo call should start");
simulation.drain().expect("network should drain");
let trace_text = simulation
.trace
.iter()
.map(|event| event.summary.clone())
.collect::<Vec<_>>()
.join("\n");
assert!(trace_text.contains("forwarded frame to child /alpha"));
assert!(trace_text.contains("forwarded frame to child /alpha/beta"));
assert_eq!(
simulation.latest_root_data_text().as_deref(),
Some("nested")
);
}
#[test]
fn chunked_endpoint_procedure_returns_multiple_packets() {
let scenarios = built_in_scenarios();
let mut simulation = Simulation::new(scenarios[1].clone()).expect("scenario should build");
simulation
.call_endpoint_procedure(
NodeId(1),
"demo.endpoint.v1.stream.chunked_greeting",
b"go".to_vec(),
)
.expect("procedure call should start");
simulation.drain().expect("network should drain");
let root_data_count = simulation
.recorded_events
.iter()
.filter(|event| matches!(event, treetest::sim::RecordedEvent::Data { node_path, .. } if node_path == "/"))
.count();
assert!(root_data_count >= 3);
assert_eq!(
simulation.latest_root_data_text().as_deref(),
Some("chunk 3: hook complete")
);
}