cloud_hypervisor_client/
lib.rs

1//!Unofficial Rust crate for accessing the [cloud-hypervisor REST API](https://github.com/cloud-hypervisor/cloud-hypervisor/blob/main/docs/api.md)
2//!
3//!# Overview
4//!
5//!The `cloud-hypervisor-client` crate can be used for managing the endpoints provided by the cloud-hypervisor REST API socket in your Rust project.
6//!
7//!The API client code of this crate has been auto-generated from the [Official OpenAPI Description for the cloud-hypervisor REST API](https://raw.githubusercontent.com/cloud-hypervisor/cloud-hypervisor/master/vmm/src/api/openapi/cloud-hypervisor.yaml) using [OpenAPI Generator](https://openapi-generator.tech/).
8//!
9//!# Example
10//!
11//!Get information about a VM:
12//!
13//!```rust,no_run
14//! use cloud_hypervisor_client::apis::DefaultApi;
15//! use cloud_hypervisor_client::socket_based_api_client;
16//!
17//! #[tokio::main]
18//! async fn main() -> Result<(), String> {
19//!     let client = socket_based_api_client("cloud_hypervisor_vm_socket.sock");
20//!
21//!     let vm_info = client.vm_info_get()
22//!         .await
23//!         .map_err(|err| format!("API call to vm_info_get failed: {:?}", err))?;
24//!
25//!     println!("Received vm info: {vm_info:?}");
26//!
27//!     Ok(())
28//! }
29//!```
30//!
31//! For more examples check out the [examples](https://github.com/lpotthast/cloud-hypervisor-client/tree/main/examples)
32//! folder in the Git repository.
33
34#![allow(unused_imports)]
35#![allow(clippy::too_many_arguments)]
36
37extern crate futures;
38extern crate hyper;
39extern crate serde;
40extern crate serde_json;
41extern crate serde_repr;
42extern crate url;
43
44use crate::apis::DefaultApiClient;
45use crate::apis::configuration::Configuration;
46use std::path::Path;
47use std::sync::Arc;
48
49pub mod apis;
50pub mod models;
51
52/// A [`DefaultApiClient`] wired up to talk to the cloud-hypervisor VMM over a Unix domain socket.
53///
54/// Construct one with [`socket_based_api_client`].
55pub type SocketBasedApiClient = DefaultApiClient<hyperlocal::UnixConnector>;
56
57/// Builds a client for the cloud-hypervisor REST API exposed at the given Unix domain socket path.
58///
59/// This is the main entrypoint of the crate. Cloud-hypervisor exposes its API over a local Unix
60/// socket (typically configured via the VMM's `--api-socket` flag); pass that socket's path here
61/// and the returned [`SocketBasedApiClient`] can drive any endpoint of the [`DefaultApi`] trait.
62///
63/// The `vmm_socket_path` is not opened here. The connection is established lazily by `hyper` on the
64/// first request. A non-existent or unreachable socket therefore surfaces as an error from the
65/// first API call rather than from this function.
66///
67/// [`DefaultApi`]: apis::DefaultApi
68///
69/// # Example
70///
71/// ```rust,no_run
72/// use cloud_hypervisor_client::apis::DefaultApi;
73/// use cloud_hypervisor_client::socket_based_api_client;
74///
75/// #[tokio::main]
76/// async fn main() -> Result<(), String> {
77///     let client = socket_based_api_client("cloud_hypervisor_vm_socket.sock");
78///
79///     let vm_info = client.vm_info_get()
80///         .await
81///         .map_err(|err| format!("API call to vm_info_get failed: {:?}", err))?;
82///
83///     println!("Received vm info: {vm_info:?}");
84///
85///     Ok(())
86/// }
87/// ```
88pub fn socket_based_api_client(vmm_socket_path: impl AsRef<Path>) -> SocketBasedApiClient {
89    use hyperlocal::UnixClientExt;
90
91    let uri: hyper::Uri = hyperlocal::Uri::new(vmm_socket_path, "/api/v1").into();
92    let client = hyper_util::client::legacy::Client::unix();
93    let configuration = Configuration {
94        base_path: uri.to_string(),
95        user_agent: None,
96        client,
97    };
98    DefaultApiClient::new(Arc::new(configuration))
99}
cloud_hypervisor_client/lib.rs

cloud_hypervisor_client/
lib.rs
