podman_rest_client/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2//! Provides an interface for querying the Podman REST API. Most of the interface is generated from
3//! the official Podman swagger file. It can connect to the Podman API over ssh to a unix socket
4//! and directly to a unix socket. Connections over ssh are  commonly necessary on macOs where the
5//! container runtime runs in a virtual machine accessible over ssh.
6//!
7//!
8//! ## API Compatibility
9//!
10//! Use `podman --version` to determine what version of Podman you are using.
11//!
12//! ### v5 Support
13//!
14//! This crate primarily works with version 5 of the Podman API. There are sufficient differences
15//! between version 3, 4, and 5 that a lot of calls will not work in an older version.
16//!
17//! ### v4 Support (Not in good shape)
18//!
19//! While there is tentative v4 support it's in pretty terrible shape because the official Podman
20//! swagger file is missing all kinds of definitions. Some have been manually created, there is a
21//! lot more to do.
22//!
23//! ## Podman Socket
24//!
25//! Note that podman does not run in a client/server model like docker does so there usually isn't
26//! a socket you can connect to by default. You might need to enable the socket for the library to
27//! connect to. For example on linux you might need to run something like this:
28//!
29//! ```sh
30//! systemctl --user enable --now podman.socket // Enable the podman unix domain socket
31//! ```
32//!
33//! On macOS you might need to invoke something like:
34//!
35//! ```sh
36//! podman machine init // Create your podman virtual machine
37//! podman machine start // Start the machine
38//! ```
39//!
40//! ## Usage
41//!
42//! ### Linux
43//!
44//! On linux you might initialize a client like this
45//!
46//! ```no_run
47//! # #[cfg(feature = "v5")]
48//! # tokio_test::block_on(async {
49//! use podman_rest_client::PodmanRestClient;
50//! use podman_rest_client::Config;
51//!
52//! // Initialize a client
53//! let client = PodmanRestClient::new(Config {
54//!     uri: "unix:///run/user/501/podman/podman.sock".to_string(),
55//!     identity_file: None,
56//! }).await.unwrap();
57//!
58//! // Fetch a list of container images
59//! let images = client.v5().images().image_list_libpod(None).await.unwrap();
60//! # })
61//! ```
62//! ### MacOs
63//!
64//! On macOs you might initialize a client like this with an ssh url and identity file
65//!
66//! ```no_run
67//! # #[cfg(feature = "v5")]
68//! # tokio_test::block_on(async {
69//! # use podman_rest_client::PodmanRestClient;
70//! # use podman_rest_client::Config;
71//! let client = PodmanRestClient::new(Config {
72//!     uri: "ssh://core@127.0.0.1:63169/run/user/501/podman/podman.sock".to_string(),
73//!     identity_file: Some("/path/to/identity_file".into()),
74//! }).await.unwrap();
75//! # })
76//! ```
77//!
78//! ### Config::guess
79//!
80//! You can also use `Config::guess()` which tries to find the default path to the podman
81//! socket depending on the platform you are on.
82//!
83//! ```no_run
84//! # #[cfg(feature = "v5")]
85//! # tokio_test::block_on(async {
86//! # use podman_rest_client::PodmanRestClient;
87//! # use podman_rest_client::Config;
88//! // Setup the default configuration
89//! let config = Config::guess().await.unwrap();
90//!
91//! // Initialize a client
92//! let client = PodmanRestClient::new(config).await.unwrap();
93//!
94//! // Fetch a list of container images
95//! let images = client.v5().images().image_list_libpod(None).await.unwrap();
96//! # })
97//! ```
98//!
99//! ### Client/API Traits
100//!
101//! If you import the `podman_rest_client::v5::Client` trait you  can directly call the api
102//! functions from a client:
103//!
104//! ```
105//! # #[cfg(feature = "v5")]
106//! # tokio_test::block_on(async {
107//! # use podman_rest_client::PodmanRestClient;
108//! # use podman_rest_client::Config;
109//! use podman_rest_client::v5::Client;
110//! # let config = Config::guess().await.unwrap();
111//! # // Initialize a client
112//! # let client = PodmanRestClient::new(config).await.unwrap();
113//! client.images().image_list_libpod(None).await;
114//! # })
115//! ```
116//!
117//! You can also use various api traits like `podman_rest_client::v5::apis::Images` and directly
118//! call the individual request functions:
119//!
120//! ```
121//! # #[cfg(feature = "v5")]
122//! # tokio_test::block_on(async {
123//! # use podman_rest_client::PodmanRestClient;
124//! # use podman_rest_client::Config;
125//! use podman_rest_client::v5::apis::Images;
126//! # let config = Config::guess().await.unwrap();
127//! # // Initialize a client
128//! # let client = PodmanRestClient::new(config).await.unwrap();
129//! client.image_list_libpod(None).await;
130//! # })
131//! ```
132//!
133//!
134//! ## Features
135//!
136//! The default feature set is `["v5", "uds", "ssh"]`.
137//!
138//! - `ssh`: Support for connecting to a podman through an ssh server.
139//! - `uds`: Support for connecting to podman through a unix domain socket.
140//! - `v5`: Support for version 5 of the podman API
141//! - `v4`: Support for version 4 of the podman API. v4 is nowhere near ready for use.
142//!
143
144pub mod cli;
145mod config;
146mod error;
147mod podman_rest_client;
148#[cfg(feature = "ssh")]
149mod ssh;
150#[cfg(feature = "uds")]
151mod unix_socket;
152
153#[cfg_attr(docsrs, doc(cfg(feature = "v4")))]
154#[cfg(feature = "v4")]
155pub mod v4;
156
157mod api_common;
158mod attach_frame_stream;
159
160#[cfg_attr(docsrs, doc(cfg(feature = "v5")))]
161#[cfg(feature = "v5")]
162pub mod v5;
163
164pub use api_common::Error;
165pub use attach_frame_stream::AttachFrame;
166pub use attach_frame_stream::AttachFrameStream;
167pub use config::Config;
168pub use error::ClientError;
169pub use podman_rest_client::PodmanRestClient;
podman_rest_client/lib.rs

podman_rest_client/
lib.rs
