rns_hooks/
hooks.rs

1use crate::program::LoadedProgram;
2use crate::result::HookResult;
3
4/// All hook points in the transport pipeline.
5#[repr(usize)]
6#[derive(Debug, Clone, Copy, PartialEq, Eq)]
7pub enum HookPoint {
8    // Packet lifecycle
9    PreIngress = 0,
10    PreDispatch = 1,
11
12    // Announce processing
13    AnnounceReceived = 2,
14    PathUpdated = 3,
15    AnnounceRetransmit = 4,
16
17    // Link lifecycle
18    LinkRequestReceived = 5,
19    LinkEstablished = 6,
20    LinkClosed = 7,
21
22    // Interface lifecycle
23    InterfaceUp = 8,
24    InterfaceDown = 9,
25    InterfaceConfigChanged = 10,
26
27    // Backbone peer lifecycle
28    BackbonePeerConnected = 11,
29    BackbonePeerDisconnected = 12,
30    BackbonePeerIdleTimeout = 13,
31    BackbonePeerWriteStall = 14,
32    BackbonePeerPenalty = 15,
33
34    // Per-action hooks
35    SendOnInterface = 16,
36    BroadcastOnAllInterfaces = 17,
37    DeliverLocal = 18,
38    TunnelSynthesize = 19,
39
40    // Periodic
41    Tick = 20,
42}
43
44impl HookPoint {
45    /// Total number of hook points.
46    pub const COUNT: usize = 21;
47}
48
49/// Context passed to hook functions (host-side only, NOT `repr(C)`).
50///
51/// This enum carries the relevant data for each hook invocation.
52/// The WASM runtime serializes this into the guest's linear memory.
53pub enum HookContext<'a> {
54    Packet {
55        ctx: &'a crate::context::PacketContext,
56        raw: &'a [u8],
57    },
58    Interface {
59        interface_id: u64,
60    },
61    Tick,
62    Announce {
63        destination_hash: [u8; 16],
64        hops: u8,
65        interface_id: u64,
66    },
67    Link {
68        link_id: [u8; 16],
69        interface_id: u64,
70    },
71    BackbonePeer {
72        server_interface_id: u64,
73        peer_interface_id: Option<u64>,
74        peer_ip: std::net::IpAddr,
75        peer_port: u16,
76        connected_for: std::time::Duration,
77        had_received_data: bool,
78        penalty_level: u8,
79        blacklist_for: std::time::Duration,
80    },
81}
82
83/// Function pointer type for hook slot runners.
84pub type HookFn = fn(&HookSlot, &HookContext) -> Option<HookResult>;
85
86/// No-op hook runner — returns `None` immediately.
87///
88/// This is the default for all hook points when no programs are attached.
89pub fn hook_noop(_slot: &HookSlot, _ctx: &HookContext) -> Option<HookResult> {
90    None
91}
92
93/// Placeholder runner for slots that have programs attached.
94///
95/// This function is swapped in when programs are present, serving as a
96/// "something to do" signal. Actual execution goes through `HookManager`.
97fn hook_has_programs(_slot: &HookSlot, _ctx: &HookContext) -> Option<HookResult> {
98    // Execution is handled externally by HookManager.run_chain().
99    // This runner just signals that the slot is active.
100    None
101}
102
103/// A slot for a single hook point, holding its attached programs and runner.
104pub struct HookSlot {
105    pub programs: Vec<LoadedProgram>,
106    /// Function pointer — points to [`hook_noop`] when empty,
107    /// [`hook_has_programs`] when programs are attached.
108    pub runner: HookFn,
109}
110
111impl HookSlot {
112    /// Update the runner pointer based on whether programs are present.
113    pub fn update_runner(&mut self) {
114        if self.programs.is_empty() {
115            self.runner = hook_noop;
116        } else {
117            self.runner = hook_has_programs;
118        }
119    }
120
121    /// Attach a program to this slot. Maintains descending priority order.
122    pub fn attach(&mut self, program: LoadedProgram) {
123        self.programs.push(program);
124        self.programs
125            .sort_by_key(|program| std::cmp::Reverse(program.priority));
126        self.update_runner();
127    }
128
129    /// Detach a program by name. Returns the removed program, if found.
130    pub fn detach(&mut self, name: &str) -> Option<LoadedProgram> {
131        let pos = self.programs.iter().position(|p| p.name == name)?;
132        let prog = self.programs.remove(pos);
133        self.update_runner();
134        Some(prog)
135    }
136
137    /// Returns true if this slot has programs attached (fast check).
138    pub fn has_programs(&self) -> bool {
139        !std::ptr::eq(self.runner as *const (), hook_noop as *const ())
140    }
141}
142
143/// Create an array of [`HookSlot`]s, one per [`HookPoint`], all initialized
144/// with empty program lists and the [`hook_noop`] runner.
145pub fn create_hook_slots() -> [HookSlot; HookPoint::COUNT] {
146    std::array::from_fn(|_| HookSlot {
147        programs: Vec::new(),
148        runner: hook_noop,
149    })
150}
151
152/// Dispatch a hook call through the slot's function pointer.
153///
154/// When the `rns-hooks` feature is enabled in `rns-net`, this macro is used
155/// at each integration point. When no programs are attached, the noop runner
156/// returns `None` immediately.
157///
158/// When `rns-hooks` is **not** enabled, the call site wraps this in
159/// `#[cfg(feature = "rns-hooks")]` so it compiles to nothing.
160#[macro_export]
161macro_rules! run_hook {
162    ($driver:expr, $point:expr, $ctx:expr) => {{
163        ($driver.hook_slots[$point as usize].runner)(&$driver.hook_slots[$point as usize], &$ctx)
164    }};
165}
166
167#[cfg(test)]
168mod tests {
169    use super::*;
170    use crate::result::Verdict;
171
172    #[test]
173    fn test_hook_point_count() {
174        assert_eq!(HookPoint::COUNT, 21);
175        // Verify the last variant matches COUNT - 1
176        assert_eq!(HookPoint::Tick as usize, 20);
177    }
178
179    #[test]
180    fn test_hook_noop_returns_none() {
181        let slot = HookSlot {
182            programs: Vec::new(),
183            runner: hook_noop,
184        };
185        let ctx = HookContext::Tick;
186        assert!(hook_noop(&slot, &ctx).is_none());
187    }
188
189    #[test]
190    fn test_create_hook_slots() {
191        let slots = create_hook_slots();
192        assert_eq!(slots.len(), HookPoint::COUNT);
193        for slot in &slots {
194            assert!(slot.programs.is_empty());
195            // Verify runner is hook_noop by calling it
196            let ctx = HookContext::Tick;
197            assert!((slot.runner)(slot, &ctx).is_none());
198        }
199    }
200
201    #[test]
202    fn test_run_hook_macro() {
203        struct FakeDriver {
204            hook_slots: [HookSlot; HookPoint::COUNT],
205        }
206        let driver = FakeDriver {
207            hook_slots: create_hook_slots(),
208        };
209        let ctx = HookContext::Tick;
210        let result = run_hook!(driver, HookPoint::Tick, ctx);
211        assert!(result.is_none());
212
213        let ctx2 = HookContext::Interface { interface_id: 42 };
214        let result2 = run_hook!(driver, HookPoint::InterfaceUp, ctx2);
215        assert!(result2.is_none());
216    }
217
218    #[test]
219    fn test_verdict_values() {
220        assert_eq!(Verdict::Continue as u32, 0);
221        assert_eq!(Verdict::Drop as u32, 1);
222        assert_eq!(Verdict::Modify as u32, 2);
223        assert_eq!(Verdict::Halt as u32, 3);
224    }
225
226    #[test]
227    fn test_hook_result_helpers() {
228        let drop_r = HookResult::drop_result();
229        assert!(drop_r.is_drop());
230        assert_eq!(drop_r.verdict, Verdict::Drop as u32);
231
232        let cont_r = HookResult::continue_result();
233        assert!(!cont_r.is_drop());
234        assert_eq!(cont_r.verdict, Verdict::Continue as u32);
235        assert_eq!(cont_r.modified_data_len, 0);
236        assert_eq!(cont_r.inject_actions_count, 0);
237        assert_eq!(cont_r.log_len, 0);
238    }
239}
rns_hooks/hooks.rs

rns_hooks/
hooks.rs
