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

further split treetest modules and docs

Browse Source
This commit is contained in:
Michael Mikovsky
2026-04-24 17:21:39 -06:00
parent 539d98a9e9
commit 943c820f30
16 changed files with 1450 additions and 1336 deletions
Download Patch File Download Diff File Expand all files Collapse all files
treetest/src/sim/actions.rs
+7 -321
View File
@@ -1,322 +1,8 @@
//! Public action helpers exposed to the UI and tests.
//! Simulator action entry point.
//!
//! Public simulator behavior is split into request-style actions, stepping, and
//! small query helpers so UI code can depend on focused APIs.
use crossbeam_channel::TryRecvError;
use unshell::protocol::tree::Endpoint;
use unshell::protocol::{DataMessage, FaultMessage, PacketHeader, PacketType, decode_frame};
use crate::model::{NodeId, Selection, format_hook_ref, format_leaf_ref, format_path};
use super::types::{ActionResult, RecordedEvent, SimError, Simulation};
impl Simulation {
/// 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();
self.require_leaf(node_id, leaf_name)?;
let node = self.tree.node(node_id).clone();
if let Some(leaf_spec) = node.leaves.iter().find(|leaf| leaf.name == leaf_name) {
self.root_knowledge
.remember_leaf_from_spec(&node, leaf_spec);
}
self.dispatch_root_call(node_path, Some(leaf_name.to_owned()), "", Vec::new())?;
Ok(ActionResult {
label: format!(
"Inspect {}",
format_leaf_ref(&self.node(node_id).path, leaf_name)
),
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 node = self.tree.node(node_id).clone();
let procedures = self.require_leaf(node_id, leaf_name)?.procedures.clone();
if let Some(leaf_spec) = node
.leaves
.iter()
.find(|known_leaf| known_leaf.name == leaf_name)
{
self.root_knowledge
.remember_leaf_from_spec(&node, leaf_spec);
}
let procedure_id =
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 {}",
format_leaf_ref(&self.node(node_id).path, leaf_name)
),
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)?;
let node = self.tree.node(node_id).clone();
if let Some(procedure) = node
.endpoint_procedures
.iter()
.find(|known_procedure| known_procedure.procedure_id == procedure_id)
{
self.root_knowledge
.remember_endpoint_procedure(&node, procedure);
}
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!(
" {}",
format_leaf_ref(&self.node(node_id).path, 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 {}: {text}",
format_hook_ref(self.node(self.root_id).path.as_slice(), hook_id)
),
);
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 {}",
format_path(&to_path),
format_hook_ref(self.node(to_node_id).path.as_slice(), hook_id)
),
);
self.process_local_frame(from_node_id, frame)?;
Ok(ActionResult {
label: format!(
"Inject invalid peer data for {}",
format_hook_ref(self.node(to_node_id).path.as_slice(), 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)
}
/// 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_ref(&self.node(*node_id).path, leaf_name)
}
}
}
}
mod calls;
mod driver;
mod queries;
treetest/src/sim/actions/calls.rs
+234
View File
@@ -0,0 +1,234 @@
//! Root-issued calls and injected traffic.
use crate::model::{NodeId, format_hook_ref, format_leaf_ref, format_path};
use unshell::protocol::{DataMessage, PacketHeader, PacketType};
use super::super::types::{ActionResult, SimError, Simulation};
impl Simulation {
/// Builds and routes an endpoint introspection call from the root.
///
/// # Example
/// ```rust
/// use treetest::{model::NodeId, scenarios::built_in_scenarios, sim::Simulation};
///
/// let scenario = built_in_scenarios().into_iter().next().unwrap();
/// let mut simulation = Simulation::new(scenario).unwrap();
/// let result = simulation.call_endpoint_introspection(NodeId(0)).unwrap();
/// assert!(result.label.contains("Inspect endpoint"));
/// ```
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();
self.require_leaf(node_id, leaf_name)?;
let node = self.tree.node(node_id).clone();
if let Some(leaf_spec) = node.leaves.iter().find(|leaf| leaf.name == leaf_name) {
self.root_knowledge
.remember_leaf_from_spec(&node, leaf_spec);
}
self.dispatch_root_call(node_path, Some(leaf_name.to_owned()), "", Vec::new())?;
Ok(ActionResult {
label: format!(
"Inspect {}",
format_leaf_ref(&self.node(node_id).path, leaf_name)
),
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 node = self.tree.node(node_id).clone();
let procedures = self.require_leaf(node_id, leaf_name)?.procedures.clone();
if let Some(leaf_spec) = node
.leaves
.iter()
.find(|known_leaf| known_leaf.name == leaf_name)
{
self.root_knowledge
.remember_leaf_from_spec(&node, leaf_spec);
}
let procedure_id =
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 {}",
format_leaf_ref(&self.node(node_id).path, leaf_name)
),
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)?;
let node = self.tree.node(node_id).clone();
if let Some(procedure) = node
.endpoint_procedures
.iter()
.find(|known_procedure| known_procedure.procedure_id == procedure_id)
{
self.root_knowledge
.remember_endpoint_procedure(&node, procedure);
}
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!(
" {}",
format_leaf_ref(&self.node(node_id).path, 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 {}: {text}",
format_hook_ref(self.node(self.root_id).path.as_slice(), hook_id)
),
);
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 {}",
format_path(&to_path),
format_hook_ref(self.node(to_node_id).path.as_slice(), hook_id)
),
);
self.process_local_frame(from_node_id, frame)?;
Ok(ActionResult {
label: format!(
"Inject invalid peer data for {}",
format_hook_ref(self.node(to_node_id).path.as_slice(), hook_id)
),
hook_id: Some(hook_id),
})
}
}
treetest/src/sim/actions/driver.rs
+62
View File
@@ -0,0 +1,62 @@
//! Simulator stepping helpers.
use crossbeam_channel::TryRecvError;
use unshell::protocol::decode_frame;
use unshell::protocol::tree::Endpoint;
use crate::model::NodeId;
use super::super::types::{SimError, Simulation};
impl Simulation {
/// 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)
}
/// 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,
crate::model::format_path(&header.src_path),
crate::model::format_path(&header.dst_path),
header.hook_id,
)
}
Err(error) => format!("<invalid frame: {error}>"),
}
}
}
treetest/src/sim/actions/queries.rs
+53
View File
@@ -0,0 +1,53 @@
//! Read-only simulator queries used by tests and UI widgets.
use crate::model::Selection;
use unshell::protocol::FaultMessage;
use super::super::types::{RecordedEvent, Simulation};
impl Simulation {
/// 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 } => {
crate::model::format_leaf_ref(&self.node(*node_id).path, leaf_name)
}
}
}
}
treetest/src/sim/runtime.rs
+4 -452
View File
@@ -1,453 +1,5 @@
//! Internal packet routing and local event handling.
//!
//! This module is where the simulated transport meets the real protocol
//! endpoint runtime. It keeps forwarding logic, local delivery, and root
//! knowledge learning separate from the user-facing action helpers.
//! Runtime entry point for simulator internals.
use unshell::protocol::tree::{Endpoint, Ingress, LocalEvent, RouteDecision};
use unshell::protocol::{
CallMessage, DataMessage, FrameBytes, PacketHeader, deserialize_archived_bytes,
};
use crate::model::{
EndpointProcedureKind, EndpointProcedureSpec, NodeId, format_hook_ref, format_leaf_ref,
format_path,
};
use super::types::{Envelope, HookSnapshot, RecordedEvent, SimError, Simulation};
impl Simulation {
pub(super) 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(),
target_leaf: dst_leaf.clone(),
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!(" {}", format_leaf_ref(&dst_path, leaf)))
.unwrap_or_default()
),
);
self.process_local_frame(self.root_id, frame)
}
pub(super) 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)
}
pub(super) 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 {
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()))?;
}
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()))?;
}
RouteDecision::Local => {
return Err(SimError::Protocol(
"local route leaked into forward list".to_owned(),
));
}
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 {}: {text}",
format_hook_ref(
self.node(node_id).path.as_slice(),
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 node_id == self.root_id {
self.learn_from_root_data(hook_id, &message);
}
}
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 {}: 0x{:02X}",
format_hook_ref(
self.node(node_id).path.as_slice(),
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_ref(&header.dst_path, 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,
super::types::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(),
})
}
pub(super) 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(),
})
}
pub(super) fn require_endpoint_procedure(
&self,
node_id: NodeId,
procedure_id: &str,
) -> Result<(), SimError> {
self.lookup_endpoint_procedure(node_id, procedure_id)
.map(|_| ())
}
pub(super) fn record_trace(&mut self, node_id: NodeId, summary: String) {
let node_path = self.node(node_id).display_path();
self.trace.push_back(super::types::TraceEvent {
tick: self.next_tick,
node_path,
summary,
});
self.next_tick += 1;
while self.trace.len() > 200 {
self.trace.pop_front();
}
}
fn learn_from_root_data(&mut self, hook_id: u64, message: &DataMessage) {
let Some(snapshot) = self.hooks.get(&hook_id).cloned() else {
return;
};
let Some(node_id) = self.tree.find_by_path(&snapshot.peer_path) else {
return;
};
let demo_node = self.node(node_id).clone();
if snapshot.procedure_id.is_empty() {
if snapshot.target_leaf.is_some() {
if let Ok(introspection) = deserialize_archived_bytes::<
unshell::protocol::introspection::ArchivedLeafIntrospection,
unshell::protocol::LeafIntrospection,
>(&message.data)
{
self.root_knowledge
.remember_leaf_introspection(&demo_node, &introspection);
}
} else if let Ok(introspection) = deserialize_archived_bytes::<
unshell::protocol::introspection::ArchivedEndpointIntrospection,
unshell::protocol::EndpointIntrospection,
>(&message.data)
{
self.root_knowledge
.remember_endpoint_introspection(&demo_node, &introspection);
}
return;
}
if let Some(procedure) = demo_node
.endpoint_procedures
.iter()
.find(|procedure| procedure.procedure_id == snapshot.procedure_id)
{
self.root_knowledge
.remember_endpoint_procedure(&demo_node, procedure);
}
if let Some(leaf_name) = &snapshot.target_leaf
&& let Some(leaf_spec) = demo_node.leaves.iter().find(|leaf| &leaf.name == leaf_name)
{
self.root_knowledge
.remember_leaf_from_spec(&demo_node, leaf_spec);
}
}
}
mod dispatch;
mod events;
mod learning;
treetest/src/sim/runtime/dispatch.rs
+156
View File
@@ -0,0 +1,156 @@
//! Packet dispatch and routing glue.
use unshell::protocol::FrameBytes;
use unshell::protocol::tree::{Endpoint, Ingress, RouteDecision};
use crate::model::{NodeId, format_leaf_ref, format_path};
use super::super::types::{Envelope, HookSnapshot, SimError, Simulation, TraceEvent};
impl Simulation {
pub(crate) 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(),
target_leaf: dst_leaf.clone(),
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!(" {}", format_leaf_ref(&dst_path, leaf)))
.unwrap_or_default()
),
);
self.process_local_frame(self.root_id, frame)
}
pub(crate) 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)
}
pub(crate) 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 {
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()))?;
}
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()))?;
}
RouteDecision::Local => {
return Err(SimError::Protocol(
"local route leaked into forward list".to_owned(),
));
}
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(())
}
pub(crate) 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();
}
}
}
treetest/src/sim/runtime/events.rs
+4
View File
@@ -0,0 +1,4 @@
//! Local event handling entry point.
mod application;
mod local;
treetest/src/sim/runtime/events/application.rs
+127
View File
@@ -0,0 +1,127 @@
//! Application-procedure handling layered over protocol calls.
use unshell::protocol::{CallMessage, PacketHeader};
use crate::model::{EndpointProcedureKind, EndpointProcedureSpec, NodeId};
use super::super::super::types::{SimError, Simulation};
impl Simulation {
pub(super) 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,
super::super::super::types::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(())
}
pub(super) 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(),
})
}
pub(crate) 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(),
})
}
pub(crate) fn require_endpoint_procedure(
&self,
node_id: NodeId,
procedure_id: &str,
) -> Result<(), SimError> {
self.lookup_endpoint_procedure(node_id, procedure_id)
.map(|_| ())
}
}
treetest/src/sim/runtime/events/local.rs
+136
View File
@@ -0,0 +1,136 @@
//! Protocol local-event handling.
use unshell::protocol::tree::LocalEvent;
use crate::model::{NodeId, format_hook_ref, format_leaf_ref};
use super::super::super::types::{RecordedEvent, SimError, Simulation};
impl Simulation {
pub(crate) 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 {}: {text}",
format_hook_ref(
self.node(node_id).path.as_slice(),
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 node_id == self.root_id {
self.learn_from_root_data(hook_id, &message);
}
}
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 {}: 0x{:02X}",
format_hook_ref(
self.node(node_id).path.as_slice(),
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_ref(&header.dst_path, 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(())
}
}
treetest/src/sim/runtime/learning.rs
+56
View File
@@ -0,0 +1,56 @@
//! Root-side knowledge learning from returned data.
use unshell::protocol::{
DataMessage, EndpointIntrospection, LeafIntrospection, deserialize_archived_bytes,
};
use super::super::types::Simulation;
impl Simulation {
pub(crate) fn learn_from_root_data(&mut self, hook_id: u64, message: &DataMessage) {
let Some(snapshot) = self.hooks.get(&hook_id).cloned() else {
return;
};
let Some(node_id) = self.tree.find_by_path(&snapshot.peer_path) else {
return;
};
let demo_node = self.node(node_id).clone();
if snapshot.procedure_id.is_empty() {
if snapshot.target_leaf.is_some() {
if let Ok(introspection) = deserialize_archived_bytes::<
unshell::protocol::introspection::ArchivedLeafIntrospection,
LeafIntrospection,
>(&message.data)
{
self.root_knowledge
.remember_leaf_introspection(&demo_node, &introspection);
}
} else if let Ok(introspection) = deserialize_archived_bytes::<
unshell::protocol::introspection::ArchivedEndpointIntrospection,
EndpointIntrospection,
>(&message.data)
{
self.root_knowledge
.remember_endpoint_introspection(&demo_node, &introspection);
}
return;
}
if let Some(procedure) = demo_node
.endpoint_procedures
.iter()
.find(|procedure| procedure.procedure_id == snapshot.procedure_id)
{
self.root_knowledge
.remember_endpoint_procedure(&demo_node, procedure);
}
if let Some(leaf_name) = &snapshot.target_leaf
&& let Some(leaf_spec) = demo_node.leaves.iter().find(|leaf| &leaf.name == leaf_name)
{
self.root_knowledge
.remember_leaf_from_spec(&demo_node, leaf_spec);
}
}
}