gcloud_ctx/
lib.rs

1#![warn(missing_docs)]
2
3//! A Rust implementation of [`gcloud config configurations`](https://cloud.google.com/sdk/gcloud/reference/config/configurations)
4//! for managing different `gcloud` configurations for Google Cloud Platform. This is the library containing the core logic
5//! which is used to build the associated [`gctx`](https://github.com/adamrodger/gctx) command line utility.
6//!
7//! **Note**: `gcloud-ctx` is independent and not affiliated with Google in any way.
8//!
9//! ## Usage
10//!
11//! ```rust
12//! # // use a temp dir so that running doc tests doesn't change your real configurations
13//! # use std::fs::File;
14//! # let tmp = tempfile::tempdir().unwrap();
15//! # File::create(tmp.path().join("active_config")).unwrap();
16//! # let configs = tmp.path().join("configurations");
17//! # std::fs::create_dir(&configs).unwrap();
18//! # File::create(configs.join("config_foo")).unwrap();
19//! # std::env::set_var("CLOUDSDK_CONFIG", tmp.path());
20//! use gcloud_ctx::{ConfigurationStore, ConflictAction};
21//!
22//! let mut store = ConfigurationStore::with_default_location()?;
23//!
24//! // create a new configuration, optionally with a force overwrite
25//! use gcloud_ctx::PropertiesBuilder;
26//! let properties = PropertiesBuilder::default()
27//!     .project("my-project")
28//!     .account("a.user@example.org")
29//!     .zone("europe-west1-d")
30//!     .region("europe-west1")
31//!     .build();
32//!
33//! store.create("foo", &properties, ConflictAction::Overwrite)?;
34//!
35//! // list configurations
36//! for config in store.configurations() {
37//!     println!("{}", config.name());
38//! }
39//!
40//! // activate a configuration by name
41//! store.activate("foo")?;
42//!
43//! // get the active configuration
44//! println!("{}", store.active());
45//!
46//! // copy an existing configuration, with force overwrite
47//! store.copy("foo", "bar", ConflictAction::Overwrite)?;
48//!
49//! // rename an existing configuration, with force overwrite
50//! store.rename("bar", "baz", ConflictAction::Overwrite)?;
51//!
52//! // delete a configuration
53//! store.delete("baz")?;
54//!
55//! // get properties of a configuration
56//! let properties = store.describe("foo")?;
57//! properties.to_writer(std::io::stdout())?;
58//! # Ok::<(), gcloud_ctx::Error>(())
59//! ```
60
61mod configuration;
62mod properties;
63
64pub use configuration::*;
65pub use properties::*;
66
67use std::path::PathBuf;
68use thiserror::Error;
69
70/// gcloud-ctx result
71pub type Result<T> = std::result::Result<T, Error>;
72
73/// gcloud-ctx error
74#[derive(Debug, Error)]
75pub enum Error {
76    /// The configuration directory was not found within the configuration store directory
77    #[error("Unable to locate user configuration directory")]
78    ConfigurationDirectoryNotFound,
79
80    /// Unable to find the gcloud configuration root directory
81    #[error("Unable to find the gcloud configuration directory at {0}\n\nIs gcloud installed?")]
82    ConfigurationStoreNotFound(PathBuf),
83
84    /// Attempted to delete the active configuration
85    #[error("Unable to delete the configuration because it is currently active")]
86    DeleteActiveConfiguration,
87
88    /// Error loading properties from a configuration
89    #[error("Unable to load properties")]
90    LoadingProperties(#[from] serde_ini::de::Error),
91
92    /// The operation would overwrite an existing configuration
93    #[error("A configuration named '{0}' already exists. Use --force to overwrite it")]
94    ExistingConfiguration(String),
95
96    /// The configuration name is invalid
97    #[error("'{0}' is invalid. Configuration names must only contain ASCII letters and numbers")]
98    InvalidName(String),
99
100    /// General I/O error
101    #[error("I/O error")]
102    Io(#[from] std::io::Error),
103
104    /// Not configurations were found in the configuration store
105    #[error("Unable to find any gcloud configurations in {0}")]
106    NoConfigurationsFound(PathBuf),
107
108    /// Error saving properties to a configuration
109    #[error("Unable to save properties")]
110    SavingProperties(#[from] serde_ini::ser::Error),
111
112    /// A configuration with the given name wasn't found
113    #[error("Unable to find configuration '{0}'")]
114    UnknownConfiguration(String),
115}
gcloud_ctx/lib.rs

gcloud_ctx/
lib.rs
