Work on implementing interface.

src/interface/mod.rs

@@ -1 +1,406 @@
+use alloc::{collections::BTreeMap, vec::Vec};
 
+use crate::protocol::{EndpointError, HookID, Packet, SessionStatus};
+
+/// Caller-owned view and packet-flow store for interface frontends.
+///
+/// Generated leaves receive a mutable reference to this store during interface-aware
+/// updates. They decide which leaf/session/procedure keys to touch, but the storage
+/// itself stays with the renderer or application shell so protocol state remains
+/// headless and reusable.
+pub struct InterfaceStore {
+    next_sequence: u64,
+    now_ns: Option<u64>,
+    events: Vec<InterfaceEvent>,
+    sessions: BTreeMap<SessionKey, SessionView>,
+    procedures: BTreeMap<ProcedureKey, ProcedureView>,
+}
+
+impl InterfaceStore {
+    /// Creates an empty caller-owned interface store.
+    pub fn new() -> Self {
+        Self {
+            next_sequence: 0,
+            now_ns: None,
+            events: Vec::new(),
+            sessions: BTreeMap::new(),
+            procedures: BTreeMap::new(),
+        }
+    }
+
+    /// Sets the timestamp attached to later events.
+    ///
+    /// The core crate stays `no_std`, so the caller supplies time from its runtime.
+    /// Passing `None` keeps event ordering without pretending the protocol owns a
+    /// clock.
+    pub fn set_now_ns(&mut self, now_ns: Option<u64>) {
+        self.now_ns = now_ns;
+    }
+
+    /// Returns the timestamp that will be attached to new events.
+    pub fn now_ns(&self) -> Option<u64> {
+        self.now_ns
+    }
+
+    /// Returns all recorded events in insertion order.
+    pub fn events(&self) -> &[InterfaceEvent] {
+        &self.events
+    }
+
+    /// Returns all session views keyed by leaf, procedure, and hook id.
+    pub fn session_views(&self) -> &BTreeMap<SessionKey, SessionView> {
+        &self.sessions
+    }
+
+    /// Returns all procedure views keyed by leaf and procedure id.
+    pub fn procedure_views(&self) -> &BTreeMap<ProcedureKey, ProcedureView> {
+        &self.procedures
+    }
+
+    /// Returns or creates the view for a hook-backed session.
+    pub fn session_view_mut(
+        &mut self,
+        leaf_id: u32,
+        procedure_id: u32,
+        hook_id: HookID,
+    ) -> &mut SessionView {
+        self.sessions
+            .entry(SessionKey {
+                leaf_id,
+                procedure_id,
+                hook_id,
+            })
+            .or_insert_with(SessionView::new)
+    }
+
+    /// Returns or creates the view for a one-shot procedure family.
+    pub fn procedure_view_mut(&mut self, leaf_id: u32, procedure_id: u32) -> &mut ProcedureView {
+        self.procedures
+            .entry(ProcedureKey {
+                leaf_id,
+                procedure_id,
+            })
+            .or_insert_with(ProcedureView::new)
+    }
+
+    /// Records a packet delivered to a generated leaf.
+    pub fn record_inbound(&mut self, leaf_id: u32, packet: &Packet) {
+        let index = self.push_event(
+            leaf_id,
+            InterfaceEventKind::Inbound {
+                packet: packet.clone(),
+            },
+        );
+        self.link_packet_event(leaf_id, packet, index);
+    }
+
+    /// Records that a packet was queued for an existing session inbox.
+    pub fn record_session_packet_queued(
+        &mut self,
+        leaf_id: u32,
+        procedure_id: u32,
+        hook_id: HookID,
+    ) {
+        let index = self.push_event(
+            leaf_id,
+            InterfaceEventKind::SessionPacketQueued {
+                procedure_id,
+                hook_id,
+            },
+        );
+        self.session_view_mut(leaf_id, procedure_id, hook_id)
+            .events
+            .push(index);
+    }
+
+    /// Records successful creation of a new session state.
+    pub fn record_session_created(
+        &mut self,
+        leaf_id: u32,
+        procedure_id: u32,
+        hook_id: HookID,
+        started_ns: Option<u64>,
+    ) {
+        let index = self.push_event(
+            leaf_id,
+            InterfaceEventKind::SessionCreated {
+                procedure_id,
+                hook_id,
+                started_ns,
+                finished_ns: self.now_ns,
+            },
+        );
+        let view = self.session_view_mut(leaf_id, procedure_id, hook_id);
+        view.status = SessionViewStatus::Running;
+        view.events.push(index);
+    }
+
+    /// Records rejection of a packet that could not create a session.
+    pub fn record_session_rejected(
+        &mut self,
+        leaf_id: u32,
+        procedure_id: u32,
+        hook_id: HookID,
+        started_ns: Option<u64>,
+    ) {
+        let index = self.push_event(
+            leaf_id,
+            InterfaceEventKind::SessionRejected {
+                procedure_id,
+                hook_id,
+                started_ns,
+                finished_ns: self.now_ns,
+            },
+        );
+        let view = self.session_view_mut(leaf_id, procedure_id, hook_id);
+        view.status = SessionViewStatus::Rejected;
+        view.events.push(index);
+    }
+
+    /// Records one session update tick.
+    pub fn record_session_update(
+        &mut self,
+        leaf_id: u32,
+        procedure_id: u32,
+        hook_id: HookID,
+        status: SessionStatus,
+        started_ns: Option<u64>,
+    ) {
+        let index = self.push_event(
+            leaf_id,
+            InterfaceEventKind::SessionUpdated {
+                procedure_id,
+                hook_id,
+                status,
+                started_ns,
+                finished_ns: self.now_ns,
+            },
+        );
+        let view = self.session_view_mut(leaf_id, procedure_id, hook_id);
+        view.status = SessionViewStatus::from_session_status(status);
+        view.events.push(index);
+    }
+
+    /// Records one procedure call.
+    pub fn record_procedure_call(
+        &mut self,
+        leaf_id: u32,
+        procedure_id: u32,
+        hook_id: HookID,
+        started_ns: Option<u64>,
+    ) {
+        let index = self.push_event(
+            leaf_id,
+            InterfaceEventKind::ProcedureCalled {
+                procedure_id,
+                hook_id,
+                started_ns,
+                finished_ns: self.now_ns,
+            },
+        );
+        self.procedure_view_mut(leaf_id, procedure_id)
+            .events
+            .push(index);
+    }
+
+    /// Records a packet emitted by leaf logic before route retry handling.
+    pub fn record_outbound_queued(&mut self, leaf_id: u32, packet: &Packet) {
+        let index = self.push_event(
+            leaf_id,
+            InterfaceEventKind::OutboundQueued {
+                packet: packet.clone(),
+            },
+        );
+        self.link_packet_event(leaf_id, packet, index);
+    }
+
+    /// Records a route attempt for a queued outbound packet.
+    pub fn record_route_attempt(&mut self, leaf_id: u32, packet: &Packet) {
+        let index = self.push_event(
+            leaf_id,
+            InterfaceEventKind::RouteAttempt {
+                packet: packet.clone(),
+            },
+        );
+        self.link_packet_event(leaf_id, packet, index);
+    }
+
+    /// Records a successful route attempt.
+    pub fn record_route_success(&mut self, leaf_id: u32, packet: &Packet) {
+        let index = self.push_event(
+            leaf_id,
+            InterfaceEventKind::RouteSuccess {
+                packet: packet.clone(),
+            },
+        );
+        self.link_packet_event(leaf_id, packet, index);
+    }
+
+    /// Records a failed route attempt without removing the packet from retry state.
+    pub fn record_route_failure(&mut self, leaf_id: u32, packet: &Packet, error: EndpointError) {
+        let index = self.push_event(
+            leaf_id,
+            InterfaceEventKind::RouteFailure {
+                packet: packet.clone(),
+                error,
+            },
+        );
+        self.link_packet_event(leaf_id, packet, index);
+    }
+
+    fn push_event(&mut self, leaf_id: u32, kind: InterfaceEventKind) -> usize {
+        let sequence = self.next_sequence;
+        self.next_sequence = self.next_sequence.wrapping_add(1);
+        let index = self.events.len();
+
+        self.events.push(InterfaceEvent {
+            sequence,
+            time_ns: self.now_ns,
+            leaf_id,
+            kind,
+        });
+
+        index
+    }
+
+    fn link_packet_event(&mut self, leaf_id: u32, packet: &Packet, index: usize) {
+        self.session_view_mut(leaf_id, packet.procedure_id, packet.hook_id)
+            .events
+            .push(index);
+    }
+}
+
+impl Default for InterfaceStore {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// Reborrows an optional interface store for one helper call.
+///
+/// Generated leaf templates pass the same optional store through several helper
+/// calls in one update. This small function keeps that reborrow explicit and avoids
+/// every generated call site having to spell out `Option<&mut &mut T>` plumbing.
+pub fn borrow_store<'a>(
+    store: &'a mut Option<&mut InterfaceStore>,
+) -> Option<&'a mut InterfaceStore> {
+    store.as_mut().map(|store| &mut **store)
+}
+
+/// Stable identity for one generated session view.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub struct SessionKey {
+    pub leaf_id: u32,
+    pub procedure_id: u32,
+    pub hook_id: HookID,
+}
+
+/// Stable identity for one generated procedure view.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub struct ProcedureKey {
+    pub leaf_id: u32,
+    pub procedure_id: u32,
+}
+
+/// Ordered event stored by [`InterfaceStore`].
+pub struct InterfaceEvent {
+    pub sequence: u64,
+    pub time_ns: Option<u64>,
+    pub leaf_id: u32,
+    pub kind: InterfaceEventKind,
+}
+
+/// Interface-visible event emitted by generated helpers.
+pub enum InterfaceEventKind {
+    Inbound {
+        packet: Packet,
+    },
+    SessionPacketQueued {
+        procedure_id: u32,
+        hook_id: HookID,
+    },
+    SessionCreated {
+        procedure_id: u32,
+        hook_id: HookID,
+        started_ns: Option<u64>,
+        finished_ns: Option<u64>,
+    },
+    SessionRejected {
+        procedure_id: u32,
+        hook_id: HookID,
+        started_ns: Option<u64>,
+        finished_ns: Option<u64>,
+    },
+    SessionUpdated {
+        procedure_id: u32,
+        hook_id: HookID,
+        status: SessionStatus,
+        started_ns: Option<u64>,
+        finished_ns: Option<u64>,
+    },
+    ProcedureCalled {
+        procedure_id: u32,
+        hook_id: HookID,
+        started_ns: Option<u64>,
+        finished_ns: Option<u64>,
+    },
+    OutboundQueued {
+        packet: Packet,
+    },
+    RouteAttempt {
+        packet: Packet,
+    },
+    RouteSuccess {
+        packet: Packet,
+    },
+    RouteFailure {
+        packet: Packet,
+        error: EndpointError,
+    },
+}
+
+/// Caller-owned render view for one hook-backed session.
+pub struct SessionView {
+    pub status: SessionViewStatus,
+    pub events: Vec<usize>,
+}
+
+impl SessionView {
+    fn new() -> Self {
+        Self {
+            status: SessionViewStatus::Pending,
+            events: Vec::new(),
+        }
+    }
+}
+
+/// Caller-owned render view for one one-shot procedure family.
+pub struct ProcedureView {
+    pub events: Vec<usize>,
+}
+
+impl ProcedureView {
+    fn new() -> Self {
+        Self { events: Vec::new() }
+    }
+}
+
+/// Interface lifecycle state for one session view.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SessionViewStatus {
+    Pending,
+    Running,
+    Closing,
+    Closed,
+    Rejected,
+}
+
+impl SessionViewStatus {
+    fn from_session_status(status: SessionStatus) -> Self {
+        match status {
+            SessionStatus::Running => Self::Running,
+            SessionStatus::Closing => Self::Closing,
+            SessionStatus::Closed => Self::Closed,
+        }
+    }
+}