Struct Jail

Source

pub struct Jail { /* private fields */ }

Available on crate features 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 figment2::{Figment, Jail, providers::{Format, Toml, Env}};

figment2::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

figment2::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 = figment2::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

figment2::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 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

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

Source

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

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

Source

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;

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

Source

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;

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

Source

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

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

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

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