Struct figment::Jail

source · [−]

pub struct Jail { /* private fields */ }

Available on crate feature test only.

Expand description

A “sandboxed” environment with isolated env and file system namespace.

Jail creates a pseudo-sandboxed (not actually sandboxed) environment for testing configurations. Specifically, Jail:

Synchronizes all calls to Jail::expect_with() and Jail::try_with() to prevent environment variables races.
Switches into a fresh temporary directory (Jail::directory()) where files can be created with Jail::create_file().
Keeps track of environment variables created with Jail::set_env() and clears them when the Jail exits.
Deletes the temporary directory and all of its contents when exiting.

Additionally, because Jail expects functions that return a Result, the ? operator can be used liberally in a jail:

use figment::{Figment, Jail, providers::{Format, Toml, Env}};

figment::Jail::expect_with(|jail| {
    jail.create_file("Cargo.toml", r#"
      name = "test"
      authors = ["bob"]
      publish = false
    "#)?;

    jail.set_env("CARGO_NAME", "env-test");

    let config: Config = Figment::new()
        .merge(Toml::file("Cargo.toml"))
        .merge(Env::prefixed("CARGO_"))
        .extract()?;

    Ok(())
});

Implementations

source

impl Jail

source

pub fn expect_with<F: FnOnce(&mut Jail) -> Result<()>>(f: F)

Creates a new jail that calls f, passing itself to f.

Panics

Panics if f panics or if Jail::try_with(f) returns an Err; prints the error message.

Example

figment::Jail::expect_with(|jail| {
    /* in the jail */

    Ok(())
});

source

pub fn try_with<F: FnOnce(&mut Jail) -> Result<()>>(f: F) -> Result<()>

Creates a new jail that calls f, passing itself to f. Returns the result from f if f does not panic.

Panics

Panics if f panics.

Example

let result = figment::Jail::try_with(|jail| {
    /* in the jail */

    Ok(())
});

source

pub fn directory(&self) -> &Path

Returns the directory the jail has switched into. The contents of this directory will be cleared when Jail is dropped.

Example

figment::Jail::expect_with(|jail| {
    let tmp_directory = jail.directory();

    Ok(())
});

source

pub fn create_file<P: AsRef<Path>>(&self, path: P, contents: &str) -> Result<File>

Creates a file with contents contents in the jail’s directory. The file will be deleted with the jail is dropped.

Example

figment::Jail::expect_with(|jail| {
    jail.create_file("MyConfig.json", "contents...");
    Ok(())
});

source

pub fn set_env<K: AsRef<str>, V: Display>(&mut self, k: K, v: V)

Set the environment variable k to value v. The variable will be removed when the jail is dropped.

Example

const VAR_NAME: &str = "my-very-special-figment-var";

assert!(std::env::var(VAR_NAME).is_err());

figment::Jail::expect_with(|jail| {
    jail.set_env(VAR_NAME, "value");
    assert!(std::env::var(VAR_NAME).is_ok());
    Ok(())
});

assert!(std::env::var(VAR_NAME).is_err());