Struct Environments 

pub struct Environments { /* private fields */ }

Engine-owned environment system: definitions + resolution + active-env state.

Implementations

impl Environments

pub fn new(default_env: impl Into<String>) -> Self

Creates an environment system with the given default environment name.

pub fn with_environment( self, name: impl Into<String>, def: EnvironmentDef, ) -> Self

Registers (or replaces) a compiled-in environment definition.

pub fn with_config_file(self, enabled: bool) -> Self

Enables loading <config-dir>/<app_id>/environments.toml during resolution.

pub fn with_app_id(self, app_id: impl Into<String>) -> Self

Sets the application id used to locate the config file.

The consumer must set this to the same app_id passed to CliConfig::new before sharing the Environments with both CliConfig::with_environments and PkceAuthProvider::with_environments (with the pkce-auth feature), or config_file_path returns None and the environments.toml file layer silently resolves empty.

pub fn with_config_file_path_override(self, path: PathBuf) -> Self

Test/advanced seam: force the environments file path.

pub fn default_env(&self) -> &str

The default environment name.

pub fn list(&self) -> Vec<String>

Enumerable environment names (compiled-in + file-defined), sorted.

Any error from reading or parsing the environments file (missing file, permission/read error, or malformed TOML) is silently swallowed and only the compiled-in names are returned. Use resolve when you need those errors surfaced; a fallible listing variant can be added later if needed.

Blocking

When the config-file layer is enabled, this performs synchronous filesystem I/O to read and parse environments.toml (like resolve). Avoid calling it repeatedly on a latency-sensitive async path.

pub fn resolve(&self, name: &str) -> Result<Environment>

Resolves name by merging compiled defaults, the config file, and <ENV>_* env-var overrides (later wins) into an Environment.

When only client_id was set on the matching layer(s), the returned Environment’s oauth.auth_url / oauth.token_url will be empty strings. Consumers should treat empty endpoint strings as “fall back to the provider’s default base endpoints”.

Blocking

When the config-file layer is enabled (via with_config_file), this performs synchronous filesystem I/O to read and parse environments.toml. Resolve the environment once at startup (or off the latency-sensitive path) rather than calling it per request inside an async handler.

Errors

Returns an error when name is not known to any layer or when the environments file exists but cannot be read or parsed.

pub fn config_file_path(&self) -> Option<PathBuf>

Path to environments.toml next to the engine config file, or None when the file layer is disabled or the config dir cannot be determined.

pub fn active_from_config(config: &ConfigFile) -> Option<String>

Reads the persisted active environment from a loaded config file.

pub fn effective_active( &self, flag: Option<&str>, config: &ConfigFile, ) -> String

Resolves the active environment name with precedence: explicit --env override > persisted active > configured default.

pub fn persist_active(&self, name: &str) -> Result<()>

Persists name as the active environment (loads, sets, saves a fresh config file for app_id). Validates that name resolves first.

Errors

Returns an error when name does not resolve to a known environment, or when the config file cannot be written.

Trait Implementations

impl Clone for Environments

fn clone(&self) -> Environments

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Environments

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.