rscni_plugin/lib.rs
1//! A library for writing CNI plugins in Rust.
2//!
3//! This crate is the *plugin* side of CNI: the process a container runtime invokes.
4//! For the calling side, see `rscni-runtime` (planned).
5//!
6//! Write a type that implements the `Cni` trait, then pass it to `Plugin::run`.
7//! `Plugin::run` reads the `CNI_*` environment variables and stdin, calls the method for
8//! the requested operation, and writes the result. Both `Cni` and `Plugin` are in the
9//! [`cni`] module. The [`async_cni`] module has async versions of both, behind the
10//! `async` feature.
11//!
12//! The specification types both sides exchange live in
13//! [`rscni-types`](https://docs.rs/rscni-types) and are re-exported here, so
14//! `rscni_plugin::types::NetConf` and `rscni_types::types::NetConf` are the same type.
15//!
16//! Complete examples:
17//! [rscni-debug](https://github.com/terassyi/rscni/blob/main/examples/rscni_debug.rs) and
18//! [async-rscni-debug](https://github.com/terassyi/rscni/blob/main/examples/async_rscni_debug.rs).
19//!
20//! # Quick start
21//!
22//! ```rust,no_run
23//! # use rscni_plugin::{
24//! # cni::{Cni, Plugin},
25//! # error::Error,
26//! # types::{Args, CNIResult},
27//! # };
28//! #
29//! # struct MyPlugin;
30//! #
31//! # impl Cni for MyPlugin {
32//! # fn add(&self, args: Args) -> Result<CNIResult, Error> {
33//! # // Implement network setup logic
34//! # Ok(CNIResult::default())
35//! # }
36//! #
37//! # fn del(&self, args: Args) -> Result<(), Error> {
38//! # // Implement network teardown logic
39//! # Ok(())
40//! # }
41//! #
42//! # fn check(&self, args: Args) -> Result<(), Error> {
43//! # // Implement network check logic
44//! # Ok(())
45//! # }
46//! #
47//! # fn status(&self, _args: Args) -> Result<(), Error> {
48//! # // Implement plugin readiness check
49//! # Ok(())
50//! # }
51//! #
52//! # fn gc(&self, _args: Args) -> Result<(), Error> {
53//! # // Implement garbage collection logic
54//! # Ok(())
55//! # }
56//! # }
57//! #
58//! let my_plugin = MyPlugin;
59//! let plugin = Plugin::default();
60//! plugin.run(&my_plugin).expect("Failed to run CNI plugin");
61//! ```
62
63/// The error type returned by every CNI operation.
64///
65/// Re-exported from [`rscni_types::error`].
66pub mod error {
67 #[doc(inline)]
68 pub use rscni_types::error::*;
69}
70
71/// CNI specification types, plus the plugin-side invocation input.
72///
73/// The specification types are re-exported from [`rscni_types::types`];
74/// [`Args`](crate::types::Args) is defined by this crate.
75pub mod types {
76 #[doc(inline)]
77 pub use rscni_types::types::*;
78
79 pub use crate::args::Args;
80}
81
82/// Plugin version reporting and negotiation.
83///
84/// Re-exported from [`rscni_types::version`].
85pub mod version {
86 #[doc(inline)]
87 pub use rscni_types::version::*;
88}
89
90#[cfg(any(feature = "async", doc))]
91pub mod async_cni;
92#[cfg(feature = "std")]
93pub mod cni;
94
95mod args;
96mod util;
97
98#[cfg(any(feature = "test-util", doc))]
99pub mod test_util;