Struct zbox::RepoOpener

pub struct RepoOpener { /* fields omitted */ }

A builder used to create a repository Repo in various manners.

This builder exposes the ability to configure how a Repo is opened and what operations are permitted on the opened repository.

Generally speaking, when using RepoOpener, you'll first call new, then chain calls to methods to set each option, then call open, passing the URI of the repository and password you're trying to open. This will give you a Result with a Repo inside that you can further operate on.

Examples

Opening a repository and creating it if it doesn't exist.

use zbox::RepoOpener;

let mut repo = RepoOpener::new().create(true).open("mem://foo", "pwd")?;

Specify options for creating a repository.

use zbox::{RepoOpener, OpsLimit, MemLimit, Cipher};

let mut repo = RepoOpener::new()
    .ops_limit(OpsLimit::Moderate)
    .mem_limit(MemLimit::Interactive)
    .cipher(Cipher::Xchacha)
    .create(true)
    .open("mem://foo", "pwd")?;

Methods

impl RepoOpener

pub fn new() -> Self

Creates a blank new set of options ready for configuration.

Important traits for &'a mut R

impl<'a, R> Read for &'a mut R where
    R: Read + ?Sized, impl<'a, W> Write for &'a mut W where
    W: Write + ?Sized, impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

pub fn ops_limit(&mut self, ops_limit: OpsLimit) -> &mut Self

Sets the password hash operation limit.

This option is only used for creating a repository. OpsLimit::Interactive is the default.

Important traits for &'a mut R

impl<'a, R> Read for &'a mut R where
    R: Read + ?Sized, impl<'a, W> Write for &'a mut W where
    W: Write + ?Sized, impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

pub fn mem_limit(&mut self, mem_limit: MemLimit) -> &mut Self

Sets the password hash memory limit.

This option is only used for creating a repository. MemLimit::Interactive is the default.

Important traits for &'a mut R

impl<'a, R> Read for &'a mut R where
    R: Read + ?Sized, impl<'a, W> Write for &'a mut W where
    W: Write + ?Sized, impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

pub fn cipher(&mut self, cipher: Cipher) -> &mut Self

Sets the crypto cipher encrypts the repository.

This option is only used for creating a repository. Cipher::Aes is the default if hardware supports AES-NI instructions, otherwise it will fall back to Cipher::Xchacha.

Important traits for &'a mut R

impl<'a, R> Read for &'a mut R where
    R: Read + ?Sized, impl<'a, W> Write for &'a mut W where
    W: Write + ?Sized, impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

pub fn create(&mut self, create: bool) -> &mut Self

Sets the option for creating a new repository.

This option indicates whether a new repository will be created if the repository does not yet already exist.

Important traits for &'a mut R

impl<'a, R> Read for &'a mut R where
    R: Read + ?Sized, impl<'a, W> Write for &'a mut W where
    W: Write + ?Sized, impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

pub fn create_new(&mut self, create_new: bool) -> &mut Self

Sets the option to always create a new repository.

This option indicates whether a new repository will be created. No repository is allowed to exist at the target location.

Important traits for &'a mut R

impl<'a, R> Read for &'a mut R where
    R: Read + ?Sized, impl<'a, W> Write for &'a mut W where
    W: Write + ?Sized, impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

pub fn compress(&mut self, compress: bool) -> &mut Self

Sets the option for data compression.

This options indicates whether the LZ4 compression should be used in the repository. Default is false.

Important traits for &'a mut R

impl<'a, R> Read for &'a mut R where
    R: Read + ?Sized, impl<'a, W> Write for &'a mut W where
    W: Write + ?Sized, impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

pub fn version_limit(&mut self, version_limit: u8) -> &mut Self

Sets the default maximum number of file version.

The version_limit must be within [1, 255], 10 is the default. This setting is a repository-wise setting, indivisual file can overwrite it by setting version_limit in OpenOptions.

Important traits for &'a mut R

impl<'a, R> Read for &'a mut R where
    R: Read + ?Sized, impl<'a, W> Write for &'a mut W where
    W: Write + ?Sized, impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

pub fn dedup_chunk(&mut self, dedup_chunk: bool) -> &mut Self

Sets the default option for file data chunk deduplication.

This option indicates whether data chunk should be deduped when writing data to a file. This setting is a repository-wise setting, indivisual file can overwrite it by setting dedup_chunk in OpenOptions. Default is true.

Important traits for &'a mut R

impl<'a, R> Read for &'a mut R where
    R: Read + ?Sized, impl<'a, W> Write for &'a mut W where
    W: Write + ?Sized, impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

pub fn read_only(&mut self, read_only: bool) -> &mut Self

Sets the option for read-only mode.

This option cannot be true with either create or create_new is true.

pub fn open(&self, uri: &str, pwd: &str) -> Result<Repo>

Opens a repository at URI with the password and options specified by self.

Supported storage:

• OS file system based storage, location prefix is file://

  After the prefix is the path to a directory on OS file system. It can be a relative or absolute path.

• Memory based storage, location prefix is mem://

  As memory stoage is volatile, it is always be used with create option. It doesn't make sense to open an existing memory storage, thus the string after prefix is arbitrary.

• SQLite based storage, location prefix is sqlite://

  After the prefix is the path to a SQLite database file. It can also be a in-memory SQLite database, that is, the path can be ":memory:". This storage can be enabled by feature storage-sqlite.

• Redis based storage, location prefix is redis://

  After the prefix is the path to a Redis instance. Unix socket is supported. The URI format is:

  redis://[+unix+][:<passwd>@]<hostname>[:port][/<db>]

  This storage can be enabled by feature storage-redis.

After a repository is opened, all of the other functions provided by Zbox will be thread-safe.

The application should destroy the password as soon as possible after calling this function.

Errors

Open a memory based repository without enable create option will return an error.

Trait Implementations

impl Debug for RepoOpener

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

Formats the value using the given formatter.

impl Default for RepoOpener

fn default() -> RepoOpener

Returns the "default value" for a type.