Skip to main content

gateflow_macros/
lib.rs

1//! Procedural macro companion to the `gateflow` crate.
2//!
3//! See the `gateflow` crate's own docs for what this actually does; this
4//! crate only expands the attribute — `gateflow::Sandbox::new().enter(..)`
5//! does the real work.
6
7use proc_macro::TokenStream;
8use proc_macro2::TokenStream as TokenStream2;
9use quote::quote;
10use syn::{
11    Error, Expr, Ident, ItemFn, Result, Token, parse::Parse, parse::ParseStream, parse_macro_input,
12};
13
14#[derive(Default)]
15struct ChaosArgs {
16    delay_ms: Option<Expr>,
17    jitter_ms: Option<Expr>,
18    loss_percent: Option<Expr>,
19    reorder_percent: Option<Expr>,
20    corrupt_percent: Option<Expr>,
21    duplicate_percent: Option<Expr>,
22}
23
24impl Parse for ChaosArgs {
25    fn parse(input: ParseStream<'_>) -> Result<Self> {
26        let mut args = Self::default();
27
28        while !input.is_empty() {
29            let key: Ident = input.parse()?;
30            input.parse::<Token![=]>()?;
31            let value: Expr = input.parse()?;
32
33            let slot = match key.to_string().as_str() {
34                "delay_ms" => &mut args.delay_ms,
35                "jitter_ms" => &mut args.jitter_ms,
36                "loss_percent" => &mut args.loss_percent,
37                "reorder_percent" => &mut args.reorder_percent,
38                "corrupt_percent" => &mut args.corrupt_percent,
39                "duplicate_percent" => &mut args.duplicate_percent,
40                _ => {
41                    return Err(Error::new(
42                        key.span(),
43                        "unknown gateflow chaos parameter; expected one of: delay_ms, jitter_ms, loss_percent, reorder_percent, corrupt_percent, duplicate_percent",
44                    ));
45                }
46            };
47
48            if slot.is_some() {
49                return Err(Error::new(key.span(), "duplicate gateflow chaos parameter"));
50            }
51            *slot = Some(value);
52
53            if input.peek(Token![,]) {
54                input.parse::<Token![,]>()?;
55            } else if !input.is_empty() {
56                return Err(input.error("expected `,` between gateflow chaos parameters"));
57            }
58        }
59
60        Ok(args)
61    }
62}
63
64/// Wraps a test function so its body runs inside a freshly created,
65/// unprivileged network namespace instead of the host's.
66///
67/// # Requirements
68///
69/// The `gateflow` crate must be a dependency named `gateflow` (its default
70/// extern crate name) with the `macros` feature enabled, since the
71/// expanded code refers to it by the absolute path `::gateflow`.
72///
73/// # Chaos parameters
74///
75/// The optional parameters configure real kernel `tc netem` chaos on the
76/// sandbox's loopback interface. Values are compile-time Rust expressions;
77/// durations are in milliseconds and percentages are in the range `0.0..=100.0`.
78/// Supported parameters are `delay_ms`, `jitter_ms`, `loss_percent`,
79/// `reorder_percent`, `corrupt_percent`, and `duplicate_percent`.
80///
81/// ```ignore
82/// #[gateflow::isolated_net(delay_ms = 100, loss_percent = 1.0)]
83/// fn tolerates_a_slow_lossy_loopback() {
84///     // Runs inside a namespace whose loopback has real kernel netem applied.
85/// }
86/// ```
87///
88/// `reorder_percent` requires `delay_ms` because that is a kernel netem
89/// requirement. The underlying `Percent` constructor clamps percentages to
90/// `0.0..=100.0`.
91///
92/// # Known limitation
93///
94/// If the test body's final expression is a `#[must_use]` value without a
95/// trailing `;`, expansion still compiles but that value's `must_use`
96/// warning fires (the expression becomes a discarded block statement) —
97/// end test bodies with `;`-terminated statements or `assert!`/`panic!`
98/// calls, not a bare trailing expression, until this is addressed.
99///
100/// # Example
101///
102/// ```ignore
103/// #[gateflow::isolated_net]
104/// fn sees_its_own_namespace() {
105///     // runs as uid 0 inside a network namespace nothing else can see
106/// }
107/// ```
108#[proc_macro_attribute]
109pub fn isolated_net(attr: TokenStream, item: TokenStream) -> TokenStream {
110    let args = parse_macro_input!(attr as ChaosArgs);
111    let input = parse_macro_input!(item as ItemFn);
112    expand(input, args).into()
113}
114
115fn expand(input: ItemFn, args: ChaosArgs) -> TokenStream2 {
116    let ItemFn {
117        attrs,
118        vis,
119        sig,
120        block,
121        ..
122    } = input;
123
124    let mut netem = quote!(::gateflow::chaos::NetemConfig::new());
125    let mut has_chaos = false;
126
127    if let Some(value) = args.delay_ms {
128        has_chaos = true;
129        netem = quote! {
130            #netem.delay(::std::time::Duration::from_millis(#value))
131        };
132    }
133    if let Some(value) = args.jitter_ms {
134        has_chaos = true;
135        netem = quote! {
136            #netem.jitter(::std::time::Duration::from_millis(#value))
137        };
138    }
139    for (value, method) in [
140        (args.loss_percent, quote!(loss)),
141        (args.reorder_percent, quote!(reorder)),
142        (args.corrupt_percent, quote!(corrupt)),
143        (args.duplicate_percent, quote!(duplicate)),
144    ] {
145        if let Some(value) = value {
146            has_chaos = true;
147            netem = quote! {
148                #netem.#method(::gateflow::chaos::Percent::new((#value) as f64))
149            };
150        }
151    }
152
153    let sandbox = if has_chaos {
154        quote! {
155            ::gateflow::Sandbox::new().chaos(#netem.build())
156        }
157    } else {
158        quote! { ::gateflow::Sandbox::new() }
159    };
160
161    quote! {
162        #[test]
163        #(#attrs)*
164        #vis #sig {
165            let __gateflow_exit_code = #sandbox
166                .enter(move || {
167                    #block
168                    0
169                })
170                .expect("Sandbox::new().enter failed before the sandboxed body could run");
171
172            assert_eq!(
173                __gateflow_exit_code,
174                0,
175                "sandboxed test body failed (see child process stderr above)"
176            );
177        }
178    }
179}
180
181#[cfg(test)]
182mod tests {
183    use syn::parse_quote;
184
185    use super::{ChaosArgs, expand};
186
187    #[test]
188    fn wraps_body_in_sandbox_enter() {
189        let input: syn::ItemFn = parse_quote! {
190            fn my_test() {
191                assert!(true);
192            }
193        };
194
195        let expanded = expand(input, Default::default()).to_string();
196
197        assert!(expanded.contains("Sandbox :: new"));
198        assert!(expanded.contains(". enter"));
199        assert!(expanded.contains("assert_eq"));
200    }
201
202    #[test]
203    fn expands_chaos_parameters_into_netem_builder() {
204        let input: syn::ItemFn = parse_quote! {
205            fn lossy_test() {
206                assert!(true);
207            }
208        };
209        let args: ChaosArgs = syn::parse_str(
210            "delay_ms = 100, jitter_ms = 20, loss_percent = 1.5, reorder_percent = 2.0",
211        )
212        .expect("chaos parameters should parse");
213
214        let expanded = expand(input, args).to_string();
215
216        assert!(expanded.contains("NetemConfig :: new"));
217        assert!(expanded.contains("from_millis (100)"));
218        assert!(expanded.contains("from_millis (20)"));
219        assert!(expanded.contains("Percent :: new"));
220        assert!(expanded.contains(". chaos"));
221    }
222
223    #[test]
224    fn rejects_unknown_chaos_parameters() {
225        let error = match syn::parse_str::<ChaosArgs>("latency_ms = 100") {
226            Ok(_) => panic!("unknown chaos parameter should be rejected"),
227            Err(error) => error,
228        };
229        assert!(
230            error
231                .to_string()
232                .contains("unknown gateflow chaos parameter")
233        );
234    }
235}