Struct Jail

pub struct Jail { /* private fields */ }

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

impl Jail

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(())
});

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(())
});

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(())
});

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

Creates a file with contents contents within the jail’s directory. The file is deleted when the jail is dropped.

Errors

An error is returned if path is not relative or is outside of the jail’s directory. I/O errors while creating the file are returned.

Example

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

pub fn create_binary<P: AsRef<Path>>( &self, path: P, bytes: &[u8], ) -> Result<File>

Creates a file with binary contents bytes within the jail’s directory. The file is deleted when the jail is dropped.

Errors

An error is returned if path is not relative or is outside of the jail’s directory. I/O errors while creating the file are returned.

Example

figment::Jail::expect_with(|jail| {
    jail.create_binary("file.bin", &[0xFF, 0x4F, 0xFF, 0x51])?;
    Ok(())
});

pub fn create_dir<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>

Creates a directory at path within the jail’s directory and returns the relative path to the subdirectory in the jail. Recursively creates directories for all of its parent components if they are missing.

The directory and all of its contents are deleted when the jail is dropped.

Errors

An error is returned if path is not relative or is outside of the jail’s directory. Any I/O errors encountered while creating the subdirectory are returned.

Example

use std::path::Path;

figment::Jail::expect_with(|jail| {
    let dir = jail.create_dir("subdir")?;
    jail.create_file(dir.join("config.json"), "{ foo: 123 }")?;

    let dir = jail.create_dir("subdir/1/2")?;
    jail.create_file(dir.join("secret.toml"), "secret = 1337")?;

    Ok(())
});

pub fn change_dir<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>

Sets the jail’s current working directory to path if path is within Jail::directory(). Otherwise returns an error.

Errors

An error is returned if path is not relative or is outside of the jail’s directory. Any I/O errors encountered while creating the subdirectory are returned.

Example

use std::path::Path;

figment::Jail::expect_with(|jail| {
    assert_eq!(std::env::current_dir().unwrap(), jail.directory());

    let subdir = jail.create_dir("subdir")?;
    jail.change_dir(&subdir)?;
    assert_eq!(std::env::current_dir().unwrap(), jail.directory().join(subdir));

    let file = jail.create_file("foo.txt", "contents")?;
    assert!(!jail.directory().join("foo.txt").exists());
    assert!(jail.directory().join("subdir").join("foo.txt").exists());

    jail.change_dir(jail.directory())?;
    assert_eq!(std::env::current_dir().unwrap(), jail.directory());

    Ok(())
});

pub fn clear_env(&mut self)

Remove all environment variables. All variables will be restored when the jail is dropped.

Example

let init_count = std::env::vars_os().count();

figment::Jail::expect_with(|jail| {
    // We start with _something_ in the env vars.
    assert!(std::env::vars_os().count() != 0);

    // Clear them all, and it's empty!
    jail.clear_env();
    assert!(std::env::vars_os().count() == 0);

    // Set a value.
    jail.set_env("FIGMENT_SPECIAL_JAIL_VALUE", "value");
    assert!(std::env::vars_os().count() == 1);

    // If we clear again, the new values are removed.
    jail.clear_env();
    assert!(std::env::vars_os().count() == 0);

    Ok(())
});

// After the drop, we have our original env vars.
assert!(std::env::vars_os().count() == init_count);
assert!(std::env::var("FIGMENT_SPECIAL_JAIL_VALUE").is_err());

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());

Trait Implementations

impl Drop for Jail

fn drop(&mut self)

Executes the destructor for this type.