rscni-plugin 0.5.0

CNI plugin library for Rust
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
//! Asynchronous CNI plugin interface.
//!
//! Enable the `async` feature to use this module:
//!
//! ```toml
//! [dependencies]
//! rscni-plugin = { version = "0.5", features = ["async"] }
//! ```

use std::io::Write;

#[cfg(feature = "async")]
use async_trait::async_trait;

use rscni_types::{
    error::Error,
    types::{CNI_COMMAND, CNIResult, Cmd, ErrorResult},
    version::{PluginInfo, SpecVersion},
};

use crate::{
    args::Args,
    util::{Env, Io, OsEnv, StdIo, result_json},
};

/// The core trait for implementing an async CNI plugin.
///
/// Implement this trait to define the behavior of your CNI plugin for the
/// ADD, DEL, CHECK, STATUS and GC operations as specified by the CNI specification.
///
/// # CNI Operations
///
/// - **ADD**: Called when a container is created. Set up the network interface.
/// - **DEL**: Called when a container is deleted. Clean up the network interface.
/// - **CHECK**: Called to verify that the network configuration is as expected.
/// - **STATUS**: Called to check if the plugin is ready to service ADD requests.
/// - **GC**: Called to clean up stale resources not in the valid attachments list.
///
/// # Example
///
/// ```rust,no_run
/// use async_trait::async_trait;
/// use rscni_plugin::{async_cni::Cni, error::Error, types::{Args, CNIResult}};
///
/// struct MyPlugin;
///
/// #[async_trait]
/// impl Cni for MyPlugin {
///     async fn add(&self, args: Args) -> Result<CNIResult, Error> {
///         // Network setup logic
///         Ok(CNIResult::default())
///     }
///
///     async fn del(&self, args: Args) -> Result<(), Error> {
///         // Network cleanup logic
///         Ok(())
///     }
///
///     async fn check(&self, args: Args) -> Result<(), Error> {
///         // Network verification logic
///         Ok(())
///     }
///
///     async fn status(&self, _args: Args) -> Result<(), Error> {
///         // Plugin readiness check
///         Ok(())
///     }
///
///     async fn gc(&self, _args: Args) -> Result<(), Error> {
///         // Garbage collection logic
///         Ok(())
///     }
/// }
/// ```
#[cfg_attr(feature = "async", async_trait)]
pub trait Cni {
    /// Executes the ADD command for the CNI plugin.
    /// <https://github.com/containernetworking/cni/blob/v1.3.0/SPEC.md#add-add-container-to-network-or-apply-modifications>
    ///
    /// This method is called when a container is created and needs network connectivity.
    /// It should set up the network interface, assign IP addresses, configure routes, etc.
    ///
    /// # Errors
    ///
    /// Returns an error if the ADD operation fails.
    async fn add(&self, args: Args) -> Result<CNIResult, Error>;

    /// Executes the DEL command for the CNI plugin.
    /// <https://github.com/containernetworking/cni/blob/v1.3.0/SPEC.md#del-remove-container-from-network-or-un-apply-modifications>
    ///
    /// This method is called when a container is being deleted and should clean up
    /// all network resources that were created during the ADD operation.
    ///
    /// # Errors
    ///
    /// Returns an error if the DEL operation fails.
    async fn del(&self, args: Args) -> Result<(), Error>;

    /// Executes the CHECK command for the CNI plugin.
    /// <https://github.com/containernetworking/cni/blob/v1.3.0/SPEC.md#check-check-containers-networking-is-as-expected>
    ///
    /// This method verifies that the network configuration is still correct and matches
    /// what was configured during ADD.
    ///
    /// # Errors
    ///
    /// Returns an error if the CHECK operation fails.
    async fn check(&self, args: Args) -> Result<(), Error>;

    /// Executes the STATUS command for the CNI plugin.
    /// <https://github.com/containernetworking/cni/blob/v1.3.0/SPEC.md#status-check-plugin-status>
    ///
    /// This method checks if the plugin is ready to service ADD requests.
    /// A plugin must return success (exit with zero) if it is ready.
    /// If the plugin knows that it cannot service ADD requests, it must return an error.
    ///
    /// # Errors
    ///
    /// Returns an error if the plugin is not available:
    /// - [`Error::PluginNotAvailable`] (code 50):
    ///   The plugin cannot service ADD requests.
    /// - [`Error::PluginNotAvailableLimitedConnectivity`] (code 51):
    ///   The plugin cannot service ADD requests, and existing containers may have limited connectivity.
    async fn status(&self, args: Args) -> Result<(), Error>;

    /// Executes the GC (Garbage Collection) command for the CNI plugin.
    /// <https://github.com/containernetworking/cni/blob/v1.3.0/SPEC.md#gc-clean-up-any-stale-resources>
    ///
    /// The GC command provides a way for runtimes to specify the expected set of
    /// attachments to a network. The plugin should remove any resources related to
    /// attachments that do not exist in that set, which arrives in the configuration's
    /// `valid_attachments` field.
    ///
    /// Resources that may be cleaned up include:
    /// - IPAM reservations
    /// - Firewall rules
    ///
    /// # Errors
    ///
    /// Returns an error if the GC operation fails. Plugins should generally complete
    /// a GC action without error. If an error is encountered, the plugin should continue
    /// removing as many resources as possible and report errors back to the runtime.
    async fn gc(&self, args: Args) -> Result<(), Error>;
}

/// Entry point for async CNI plugins.
#[derive(Debug, Default)]
pub struct Plugin {
    info: PluginInfo,
    msg: Option<String>,
}

impl Plugin {
    /// Creates a new `Plugin` with custom CNI version support.
    ///
    /// The ADD success output is serialized in the result layout the negotiated
    /// config version requires: the legacy layout for versions 0.3.0 through 0.4.0,
    /// the current one for 1.0.0 and later. Versions 0.1.0 and 0.2.0 define yet
    /// another, `ip4`/`ip6`-shaped layout the framework does not produce, so listing
    /// them in `versions` produces ADD results consumers of those versions cannot
    /// decode.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use rscni_plugin::{async_cni::Plugin, version::SpecVersion};
    ///
    /// let plugin = Plugin::new(
    ///     SpecVersion::new(1, 1, 0),
    ///     vec![SpecVersion::new(1, 0, 0), SpecVersion::new(1, 1, 0)]
    /// );
    /// ```
    #[must_use]
    pub const fn new(ver: SpecVersion, versions: Vec<SpecVersion>) -> Self {
        Self {
            info: PluginInfo::new(ver, versions),
            msg: None,
        }
    }

    /// Sets a message to display with version information.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use rscni_plugin::async_cni::Plugin;
    ///
    /// let plugin = Plugin::default()
    ///     .msg("AsyncPlugin v1.0.0 - Async I/O support");
    /// ```
    #[must_use]
    pub fn msg(mut self, msg: &str) -> Self {
        self.msg = Some(msg.to_string());
        self
    }

    /// Runs the CNI plugin asynchronously.
    ///
    /// This method processes the CNI command asynchronously and calls the
    /// appropriate method on your `Cni` implementation.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - CNI environment variables are missing or invalid
    /// - Network configuration is invalid
    /// - CNI version is incompatible
    /// - Your `Cni` implementation returns an error
    /// - I/O errors occur
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use async_trait::async_trait;
    /// # use rscni_plugin::{async_cni::{Cni, Plugin}, error::Error, types::{Args, CNIResult}};
    /// #
    /// # struct MyPlugin;
    /// # #[async_trait]
    /// # impl Cni for MyPlugin {
    /// #     async fn add(&self, args: Args) -> Result<CNIResult, Error> { Ok(CNIResult::default()) }
    /// #     async fn del(&self, args: Args) -> Result<(), Error> { Ok(()) }
    /// #     async fn check(&self, args: Args) -> Result<(), Error> { Ok(()) }
    /// #     async fn status(&self, _args: Args) -> Result<(), Error> { Ok(()) }
    /// #     async fn gc(&self, _args: Args) -> Result<(), Error> { Ok(()) }
    /// # }
    /// #
    /// #[tokio::main]
    /// async fn main() {
    ///     let plugin = Plugin::default();
    ///     let my_plugin = MyPlugin;
    ///
    ///     if let Err(e) = plugin.run(&my_plugin).await {
    ///         eprintln!("Plugin failed: {}", e);
    ///         std::process::exit(1);
    ///     }
    /// }
    /// ```
    // `#[async_trait]` already forces implementors to be `Sync`, so these futures are
    // `Send` in practice; clippy cannot see it without a redundant `Cni: Sync` bound.
    #[allow(clippy::future_not_send)]
    pub async fn run<T: Cni>(&self, cni: &T) -> Result<(), Error> {
        self.run_with::<T, OsEnv, StdIo>(cni).await
    }

    /// Renders the JSON this plugin answers `CNI_COMMAND=VERSION` with.
    ///
    /// Here rather than on [`PluginInfo`]: a runtime only ever reads this document,
    /// so the shared types crate should not promise the exact string.
    fn version_json(&self) -> Result<String, Error> {
        serde_json::to_string(&self.info).map_err(|e| Error::FailedToDecode(e.to_string()))
    }

    /// Prints the about text on stderr, which is what a bare invocation asks for.
    /// Without one there is no help to give, so the missing `CNI_COMMAND` is the
    /// error instead.
    fn print_about<I: Io>(&self) -> Result<(), Error> {
        let msg = self
            .msg
            .as_deref()
            .ok_or_else(|| Error::missing_env(&[CNI_COMMAND]))?;
        let help = format!(
            "{msg}\nCNI protocol versions supported: {}\n",
            self.info
                .supported_versions()
                .iter()
                .map(ToString::to_string)
                .collect::<Vec<_>>()
                .join(", ")
        );
        let _ = I::io_err().write_all(help.as_bytes());
        Ok(())
    }

    /// [`run`](Self::run) with its environment and I/O seams exposed, so tests can
    /// assert what actually lands on stdout — the success result and the error
    /// result structure both exist only on this side of `inner_run`.
    // Not `Send`, for the reason given on `run`.
    #[allow(clippy::future_not_send)]
    async fn run_with<C: Cni, E: Env, I: Io>(&self, cni: &C) -> Result<(), Error> {
        // Flushed explicitly: the real stdout is buffered and its exit-time flush
        // discards errors, so a broken stream would otherwise lose the JSON silently.
        match self.inner_run::<C, E, I>(cni).await {
            Ok(res) => {
                let mut out = I::io_out();
                out.write_all(res.as_bytes())
                    .and_then(|()| out.flush())
                    .map_err(|e| Error::IOFailure(e.to_string()))
            }
            Err(err) => {
                // The spec requires a failing plugin to put the error result on stdout
                // alongside the non-zero exit; that JSON is what runtimes parse for
                // diagnostics. Best-effort: the original error must reach the caller
                // either way, and a failed emission leaves a trace on stderr.
                let error_result = ErrorResult::new(self.info.cni_version(), &err);
                let mut out = I::io_out();
                if serde_json::to_writer(&mut out, &error_result).is_err() || out.flush().is_err() {
                    let _ = I::io_err().write_all(b"Error writing error JSON to stdout\n");
                }
                Err(err)
            }
        }
    }

    // Not `Send`, for the reason given on `run`.
    #[allow(clippy::future_not_send)]
    async fn inner_run<C: Cni, E: Env, I: Io>(&self, cni: &C) -> Result<String, Error> {
        // CNI_COMMAND is required for every operation, so unset (or empty, the same
        // thing here) is error code 4 — unless an about text turns the bare
        // invocation into a help request, which succeeds with no stdout output.
        let Some(raw_cmd) = E::get::<String>(CNI_COMMAND)? else {
            self.print_about::<I>()?;
            return Ok(String::new());
        };
        let cmd: Cmd = raw_cmd.parse()?;

        match cmd {
            Cmd::Add => {
                let args = Args::from_env::<E, I>(cmd)?;
                // The spec requires the ADD result to carry a `cniVersion` key echoing
                // the version supplied on input — and for versions before 1.0.0, to
                // use their legacy result layout. Refused before the callback runs, so
                // a version whose layout this crate cannot render fails without
                // leaving the attachment behind.
                let cni_version = self.info.negotiate(args.config(), cmd)?;
                if !cni_version.is_supported() {
                    return Err(Error::IncompatibleVersion(format!(
                        "unsupported CNI result version \"{cni_version}\""
                    )));
                }
                let res = cni.add(args).await?;
                result_json(cni_version, res)
            }
            Cmd::Del => {
                let args = Args::from_env::<E, I>(cmd)?;
                self.info.negotiate(args.config(), cmd)?;
                cni.del(args).await?;
                Ok(String::new())
            }
            Cmd::Check => {
                let args = Args::from_env::<E, I>(cmd)?;
                self.info.negotiate(args.config(), cmd)?;
                cni.check(args).await?;
                Ok(String::new())
            }
            Cmd::Status => {
                let args = Args::from_env::<E, I>(cmd)?;
                self.info.negotiate(args.config(), cmd)?;
                cni.status(args).await?;
                Ok(String::new())
            }
            Cmd::Gc => {
                let args = Args::from_env::<E, I>(cmd)?;
                self.info.negotiate(args.config(), cmd)?;
                cni.gc(args).await?;
                Ok(String::new())
            }
            Cmd::Version => self.version_json(),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::types::{Dns, Interface, IpConfig, Route};
    use rscni_types::ipnet::{IpNet, Ipv4Net};
    use rstest::rstest;
    use std::cell::{Cell, RefCell};
    use std::collections::HashMap;
    use std::io::{Cursor, Read, Write};
    use std::net::{IpAddr, Ipv4Addr};
    use std::str::FromStr;

    // Thread-local storage for mock environment variables
    thread_local! {
        static MOCK_ENV: RefCell<HashMap<String, String>> = RefCell::new(HashMap::new());
    }

    // Mock Env implementation
    struct MockEnv;

    impl Env for MockEnv {
        fn get<T>(name: &str) -> Result<Option<T>, Error>
        where
            T: FromStr,
            T::Err: std::error::Error + 'static,
        {
            MOCK_ENV.with(|env| match env.borrow().get(name) {
                None => Ok(None),
                Some(v) if v.is_empty() => Ok(None),
                Some(v) => v
                    .parse::<T>()
                    .map(Some)
                    .map_err(|e| Error::InvalidEnvValue(e.to_string())),
            })
        }
    }

    // Thread-local storage for mock I/O
    thread_local! {
        static MOCK_INPUT: RefCell<Vec<u8>> = const { RefCell::new(Vec::new()) };
        static MOCK_OUTPUT: RefCell<Vec<u8>> = const { RefCell::new(Vec::new()) };
        static MOCK_OUTPUT_BROKEN: Cell<bool> = const { Cell::new(false) };
    }

    struct MockIo;

    /// Appends to the thread-local output buffer, so tests can assert what the
    /// plugin put on its stdout via [`take_mock_output`] — or fails every write
    /// after [`break_mock_output`], like a closed stdout would.
    struct MockOut;

    impl Write for MockOut {
        fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
            if MOCK_OUTPUT_BROKEN.with(Cell::get) {
                return Err(std::io::Error::new(
                    std::io::ErrorKind::BrokenPipe,
                    "mock stdout is broken",
                ));
            }
            MOCK_OUTPUT.with(|out| out.borrow_mut().extend_from_slice(buf));
            Ok(buf.len())
        }

        fn flush(&mut self) -> std::io::Result<()> {
            Ok(())
        }
    }

    /// Makes every subsequent mock-stdout write fail; [`set_dispatch_env`] arms the
    /// next test with a working one again.
    fn break_mock_output() {
        MOCK_OUTPUT_BROKEN.with(|broken| broken.set(true));
    }

    impl Io for MockIo {
        fn io_in() -> impl Read {
            MOCK_INPUT.with(|input| {
                let data = input.borrow().clone();
                Cursor::new(data)
            })
        }

        fn io_out() -> impl Write {
            MockOut
        }

        fn io_err() -> impl Write {
            Vec::new()
        }
    }

    /// Drains and returns everything written to the mock stdout so far.
    fn take_mock_output() -> String {
        MOCK_OUTPUT.with(|out| String::from_utf8_lossy(&out.borrow_mut().split_off(0)).into_owned())
    }

    // Helper function to set mock environment variable
    fn set_mock_env(key: &str, value: &str) {
        MOCK_ENV.with(|env| {
            env.borrow_mut().insert(key.to_string(), value.to_string());
        });
    }

    // Helper function to set mock input
    fn set_mock_input(data: &str) {
        MOCK_INPUT.with(|input| {
            *input.borrow_mut() = data.as_bytes().to_vec();
        });
    }

    const ADDRESS: IpNet = IpNet::V4(Ipv4Net::new_assert(Ipv4Addr::new(10, 1, 0, 5), 16));
    const DEFAULT_ROUTE: IpNet = IpNet::V4(Ipv4Net::new_assert(Ipv4Addr::UNSPECIFIED, 0));
    const GATEWAY: IpAddr = IpAddr::V4(Ipv4Addr::new(10, 1, 0, 1));

    // Mock Cni implementation
    struct MockCni;

    #[cfg_attr(feature = "async", async_trait)]
    impl Cni for MockCni {
        async fn add(&self, _args: Args) -> Result<CNIResult, Error> {
            Ok(CNIResult {
                interfaces: vec![Interface {
                    name: "eth0".to_string(),
                    mac: "00:11:22:33:44:55".to_string(),
                    sandbox: Some("/var/run/netns/test".to_string()),
                    mtu: None,
                    socket_path: None,
                    pci_id: None,
                }],
                ips: vec![IpConfig {
                    interface: Some(0),
                    address: ADDRESS,
                    gateway: Some(GATEWAY),
                }],
                routes: vec![Route {
                    dst: DEFAULT_ROUTE,
                    gw: Some(GATEWAY),
                    mtu: None,
                    advmss: None,
                    priority: None,
                    table: None,
                    scope: None,
                }],
                dns: Some(Dns {
                    nameservers: vec!["10.1.0.1".to_string()],
                    domain: None,
                    search: None,
                    options: None,
                }),
            })
        }

        async fn del(&self, _args: Args) -> Result<(), Error> {
            Ok(())
        }

        async fn check(&self, _args: Args) -> Result<(), Error> {
            Ok(())
        }

        async fn status(&self, _args: Args) -> Result<(), Error> {
            Ok(())
        }

        async fn gc(&self, _args: Args) -> Result<(), Error> {
            Ok(())
        }
    }

    // Accepted dispatches with no success output (the spec defines success output
    // only for ADD and VERSION), including the exact operation floors — an off-by-one
    // in the gate would reject 1.1.0, the only version a real runtime (libcni) ever
    // issues GC and STATUS with — and CHECK above its floor.
    #[cfg(feature = "async")]
    #[rstest]
    #[case::del("DEL", "1.1.0")]
    #[case::check_at_floor("CHECK", "0.4.0")]
    #[case::check_above_floor("CHECK", "1.1.0")]
    #[case::gc_at_floor("GC", "1.1.0")]
    #[case::status_at_floor("STATUS", "1.1.0")]
    #[tokio::test]
    async fn test_plugin_inner_run_accepted(
        #[case] command: &str,
        #[case] config_version: &str,
    ) -> Result<(), Box<dyn std::error::Error>> {
        set_dispatch_env(command, "test-container", "/var/run/netns/test", "eth0");
        set_mock_env("CNI_PATH", "/opt/cni/bin");
        set_mock_config_version(config_version);

        let output = Plugin::default()
            .inner_run::<MockCni, MockEnv, MockIo>(&MockCni)
            .await
            .map_err(|e| format!("{command} must succeed: {e}"))?;
        assert!(output.is_empty(), "{command} got: {output}");
        Ok(())
    }

    #[cfg(feature = "async")]
    #[rstest]
    #[case("1.0.0", None)]
    #[case("0.4.0", Some("4"))]
    #[tokio::test]
    async fn test_plugin_inner_run_add_echoes_cni_version(
        #[case] version: &str,
        #[case] legacy_ip_family: Option<&str>,
    ) -> Result<(), Box<dyn std::error::Error>> {
        set_dispatch_env("ADD", "test-container", "/var/run/netns/test", "eth0");
        set_mock_config_version(version);

        let plugin = Plugin::default();
        let output = plugin
            .inner_run::<MockCni, MockEnv, MockIo>(&MockCni)
            .await?;

        // The spec: the ADD result must carry the cniVersion supplied on input, and
        // the result's own fields sit beside it at the top level — the wire wrapper
        // is flattened, not nested.
        let parsed: serde_json::Value = serde_json::from_str(&output)?;
        assert_eq!(parsed["cniVersion"], version);
        assert_eq!(parsed["interfaces"][0]["name"], "eth0");
        // Pre-1.0 versions get the legacy layout, recognizable by the mandatory
        // ips[].version; the exact conversion is rscni-types' legacy tests' business.
        assert_eq!(
            parsed["ips"][0].get("version").and_then(|v| v.as_str()),
            legacy_ip_family
        );
        Ok(())
    }

    #[cfg(feature = "async")]
    #[tokio::test]
    async fn test_plugin_inner_run_version() -> Result<(), Box<dyn std::error::Error>> {
        set_dispatch_env("VERSION", "", "", "");

        let plugin = Plugin::default();
        let mock_cni = MockCni;

        let json_output = plugin
            .inner_run::<MockCni, MockEnv, MockIo>(&mock_cni)
            .await?;
        assert!(json_output.contains("cniVersion"));
        assert!(json_output.contains("supportedVersions"));
        Ok(())
    }

    // A missing CNI_COMMAND is a help request when an about text exists — help on
    // stderr, success with no output — and error code 4 otherwise.
    #[cfg(feature = "async")]
    #[tokio::test]
    async fn test_plugin_inner_run_unset_prints_help() -> Result<(), Error> {
        set_dispatch_env("", "", "", "");
        let plugin = Plugin::default().msg("Test Plugin v1.0.0");
        let out = plugin
            .inner_run::<MockCni, MockEnv, MockIo>(&MockCni)
            .await?;
        assert!(out.is_empty());
        Ok(())
    }

    #[cfg(feature = "async")]
    #[tokio::test]
    async fn test_plugin_inner_run_unset_without_about_text_is_code_4() {
        set_dispatch_env("", "", "", "");
        let result = Plugin::default()
            .inner_run::<MockCni, MockEnv, MockIo>(&MockCni)
            .await;
        assert!(
            matches!(result, Err(Error::InvalidEnvValue(_))),
            "got: {result:?}"
        );
    }

    /// Arranges every mock seam from scratch — the single test entry point, so
    /// isolation never leans on the harness giving each test a fresh thread. Empty
    /// variables are omitted, exactly what a spec-strict runtime sends; stdin gets a
    /// well-formed 1.1.0 config. Tests needing more layer overrides on top with
    /// [`set_mock_env`]/[`set_mock_input`].
    fn set_dispatch_env(command: &str, container_id: &str, netns: &str, ifname: &str) {
        MOCK_ENV.with(|env| env.borrow_mut().clear());
        MOCK_OUTPUT.with(|out| out.borrow_mut().clear());
        MOCK_OUTPUT_BROKEN.with(|broken| broken.set(false));
        let vars = [
            ("CNI_COMMAND", command),
            ("CNI_CONTAINERID", container_id),
            ("CNI_NETNS", netns),
            ("CNI_IFNAME", ifname),
        ];
        for (key, value) in vars {
            if !value.is_empty() {
                set_mock_env(key, value);
            }
        }
        set_mock_config_version("1.1.0");
    }

    /// Puts a well-formed config declaring `version` on stdin.
    fn set_mock_config_version(version: &str) {
        set_mock_input(&format!(
            r#"{{"cniVersion":"{version}","name":"test-network","type":"test"}}"#
        ));
    }

    #[cfg(feature = "async")]
    async fn dispatch_with_env(
        command: &str,
        container_id: &str,
        netns: &str,
        ifname: &str,
    ) -> Result<String, Error> {
        set_dispatch_env(command, container_id, netns, ifname);
        Plugin::default()
            .inner_run::<MockCni, MockEnv, MockIo>(&MockCni)
            .await
    }

    // `ArgsBuilder::validate`'s doc carries the spec's full required/optional
    // environment matrix; these tables drive it through dispatch. Every violation is
    // error code 4 naming the missing variable.
    #[cfg(feature = "async")]
    #[rstest]
    #[case::add_without_netns("ADD", "c1", "", "eth0", "CNI_NETNS")]
    #[case::add_without_container_id("ADD", "", "/ns", "eth0", "CNI_CONTAINERID")]
    #[case::del_without_container_id("DEL", "", "", "eth0", "CNI_CONTAINERID")]
    #[case::del_without_ifname("DEL", "c1", "", "", "CNI_IFNAME")]
    #[case::gc_without_path("GC", "", "", "", "CNI_PATH")]
    // Missing variables are reported together, in the reference's wording and order.
    #[case::add_bare("ADD", "", "", "", "[CNI_CONTAINERID,CNI_NETNS,CNI_IFNAME]")]
    #[case::check_bare("CHECK", "", "", "", "[CNI_CONTAINERID,CNI_NETNS,CNI_IFNAME]")]
    // Present values are held to the spec's character rules.
    #[case::invalid_container_id(
        "ADD",
        "bad*id",
        "/ns",
        "eth0",
        "invalid characters in containerID"
    )]
    #[case::invalid_ifname(
        "ADD",
        "c1",
        "/ns",
        "eth0:0",
        "interface name contains / or : or whitespace"
    )]
    #[tokio::test]
    async fn test_plugin_inner_run_env_matrix_rejected(
        #[case] command: &str,
        #[case] container_id: &str,
        #[case] netns: &str,
        #[case] ifname: &str,
        #[case] missing: &str,
    ) {
        match dispatch_with_env(command, container_id, netns, ifname).await {
            Err(Error::InvalidEnvValue(details)) => assert!(
                details.contains(missing),
                "{command}: details must name {missing}, got: {details}"
            ),
            other => panic!("{command} must fail naming {missing}, got: {other:?}"),
        }
    }

    // `run` owns what lands on stdout — the result JSON on success, the spec's error
    // result structure on failure — and a broken stdout must never replace the
    // plugin's own error (the best-effort discard in the error arm), while a failed
    // result write is itself an I/O failure (code 5). An expected code of 0 means
    // success; an empty expectation means nothing must land on stdout.
    #[cfg(feature = "async")]
    #[rstest]
    #[case::success_puts_the_result("c1", false, 0, r#""interfaces""#)]
    #[case::failure_puts_the_error_result("", false, 4, r#""code":4"#)]
    #[case::broken_stdout_keeps_the_plugin_error("", true, 4, "")]
    #[case::broken_stdout_fails_a_success("c1", true, 5, "")]
    #[tokio::test]
    async fn test_plugin_run_writes_stdout(
        #[case] container_id: &str,
        #[case] broken_stdout: bool,
        #[case] code: u32,
        #[case] expected: &str,
    ) {
        set_dispatch_env("ADD", container_id, "/ns", "eth0");
        if broken_stdout {
            break_mock_output();
        }

        let result = Plugin::default()
            .run_with::<MockCni, MockEnv, MockIo>(&MockCni)
            .await;
        let got = result.as_ref().map_or_else(u32::from, |()| 0);
        assert_eq!(got, code, "got: {result:?}");
        let stdout = take_mock_output();
        if expected.is_empty() {
            assert!(stdout.is_empty(), "stdout: {stdout}");
        } else {
            assert!(stdout.contains(expected), "stdout: {stdout}");
        }
    }

    #[cfg(feature = "async")]
    #[rstest]
    #[case::add_required_only("ADD", "c1", "/ns", "eth0")]
    // CNI_NETNS is optional for DEL: teardown must complete after the netns is gone.
    #[case::del_without_netns("DEL", "c1", "", "eth0")]
    // STATUS requires nothing container-specific.
    #[case::status_bare("STATUS", "", "", "")]
    #[tokio::test]
    async fn test_plugin_inner_run_env_matrix_accepted(
        #[case] command: &str,
        #[case] container_id: &str,
        #[case] netns: &str,
        #[case] ifname: &str,
    ) -> Result<(), Error> {
        dispatch_with_env(command, container_id, netns, ifname).await?;
        Ok(())
    }

    // Broken stdin, by error class: a literal `null` decodes to no configuration
    // without failing, so it is a config error (7), as is a bad network name; a
    // version that cannot parse is a decode failure (6).
    #[cfg(feature = "async")]
    #[rstest]
    #[case::null_config("null", 7)]
    #[case::malformed_version(
        r#"{"cniVersion":"not-a-version","name":"test-network","type":"test"}"#,
        6
    )]
    #[case::missing_network_name(r#"{"cniVersion":"1.1.0","type":"test"}"#, 7)]
    #[case::invalid_network_name(r#"{"cniVersion":"1.1.0","name":"bad*name","type":"test"}"#, 7)]
    #[case::non_boolean_capability(
        r#"{"cniVersion":"1.1.0","name":"test-network","type":"test","capabilities":{"portMappings":"true"}}"#,
        6
    )]
    #[tokio::test]
    async fn test_plugin_inner_run_broken_stdin_rejected(#[case] stdin: &str, #[case] code: u32) {
        set_dispatch_env("ADD", "test-container", "/var/run/netns/test", "eth0");
        set_mock_input(stdin);

        let Err(err) = Plugin::default()
            .inner_run::<MockCni, MockEnv, MockIo>(&MockCni)
            .await
        else {
            panic!("ADD must reject this stdin");
        };
        assert_eq!(u32::from(&err), code, "got: {err:?}");
    }

    // Version negotiation rejections, all error code 1. The floor cases use versions
    // from the default plugin's supported list, so what must reject them is the
    // operation floor (CHECK exists only from 0.4.0, GC and STATUS from 1.1.0), not
    // the supported-version membership check; the membership cases are the reverse,
    // and ADD and DEL have no floor, so membership is their only gate.
    #[cfg(feature = "async")]
    #[rstest]
    #[case::check_below_floor(
        Plugin::default(),
        "CHECK",
        "0.3.1",
        "config version does not allow CHECK"
    )]
    #[case::gc_below_floor(Plugin::default(), "GC", "1.0.0", "config version does not allow GC")]
    #[case::status_below_floor(
        Plugin::default(),
        "STATUS",
        "1.0.0",
        "config version does not allow STATUS"
    )]
    #[case::add_unsupported_version(
        Plugin::new(SpecVersion::new(1, 0, 0), vec![SpecVersion::new(1, 0, 0)]),
        "ADD",
        "0.4.0",
        r#"config is "0.4.0""#
    )]
    #[case::del_unsupported_version(
        Plugin::new(SpecVersion::new(1, 0, 0), vec![SpecVersion::new(1, 0, 0)]),
        "DEL",
        "0.4.0",
        r#"config is "0.4.0""#
    )]
    #[tokio::test]
    async fn test_plugin_inner_run_version_rejected(
        #[case] plugin: Plugin,
        #[case] command: &str,
        #[case] config_version: &str,
        #[case] expected_details: &str,
    ) {
        set_dispatch_env(command, "test-container", "/var/run/netns/test", "eth0");
        set_mock_env("CNI_PATH", "/opt/cni/bin");
        set_mock_config_version(config_version);

        match plugin.inner_run::<MockCni, MockEnv, MockIo>(&MockCni).await {
            Err(Error::IncompatibleVersion(details)) => {
                assert!(details.contains(expected_details), "got: {details}");
            }
            other => panic!("expected IncompatibleVersion, got {other:?}"),
        }
    }

    // `cniVersion` was only added to the config format in spec 0.2.0: its absence
    // means 0.1.0, rejected with code 1 — even by a plugin listing 0.1.0 as
    // supported, since this crate cannot produce that version's result layout.
    #[cfg(feature = "async")]
    #[rstest]
    #[case::rejected_without_010_support(Plugin::default(), "plugin supports")]
    #[case::layout_unsupported_despite_010_support(
        Plugin::new(
            SpecVersion::new(1, 1, 0),
            vec![SpecVersion::new(0, 1, 0), SpecVersion::new(1, 1, 0)]
        ),
        "unsupported CNI result version \"0.1.0\""
    )]
    #[tokio::test]
    async fn test_plugin_inner_run_missing_cni_version(
        #[case] plugin: Plugin,
        #[case] details_contain: &str,
    ) {
        set_dispatch_env("ADD", "test-container", "/var/run/netns/test", "eth0");
        set_mock_input(r#"{"name":"test-network","type":"test"}"#);

        let result = plugin.inner_run::<MockCni, MockEnv, MockIo>(&MockCni).await;
        match result {
            Err(Error::IncompatibleVersion(details)) => {
                assert!(details.contains(details_contain), "got: {details}");
            }
            other => panic!("expected IncompatibleVersion, got {other:?}"),
        }
    }
}