Struct zbox::Repo

pub struct Repo { /* fields omitted */ }

An encrypted repository contains the whole file system.

A Repo represents a secure collection which consists of files, directories and their associated data. Similar to std::fs, Repo provides methods to manipulate the enclosed file system.

Storages

ZboxFS supports a variety of underlying storages, which are listed below.

Storage	URI identifier	Cargo Feature
Memory	"mem://"	N/A
OS file system	"file://"	storage-file
SQLite	"sqlite://"	storage-sqlite
Redis	"redis://"	storage-redis
Zbox Cloud Storage	"zbox://"	storage-zbox-native

* Visit zbox.io to learn more about Zbox Cloud Storage.

By default, only memory storage is enabled. To use other storages, you need to specify it as dependency features in your Cargo.toml.

For example, to use OS file as underlying storage, specify its feature in your project's Cargo.toml file.

[dependencies]
zbox = { version = "0.9.1", features = ["storage-file"] }

Create and open Repo

Repo can be created on different underlying storages using RepoOpener. It uses an URI-like string to specify its storage type and location. The URI string starts with an identifier which specifies the storage type, as shown in above table. You can check more location URI details at: RepoOpener.

Repo can only be opened once at a time. After opened, it keeps locked from other open attempts until it goes out of scope. Once Repo is dropped, any opened files or version readers won't be accessible.

Optionally, Repo can be opened in read-only mode if you only need read access.

Examples

Create an OS file system based repository.

use zbox::{init_env, RepoOpener};

init_env();
let mut repo = RepoOpener::new()
    .create(true)
    .open("file:///path/to/repo", "pwd")?;

Create a memory based repository.

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

Open a repository in read-only mode.

let mut repo = RepoOpener::new()
    .read_only(true)
    .open("file:///path/to/repo", "pwd")?;

Methods

impl Repo

pub fn exists(uri: &str) -> Result<bool>

Returns whether the URI points at an existing repository.

pub fn info(&self) -> Result<RepoInfo>

Get repository metadata information.

pub fn reset_password(
    &mut self,
    old_pwd: &str,
    new_pwd: &str,
    ops_limit: OpsLimit,
    mem_limit: MemLimit
) -> Result<()>

Reset password for the repository.

Note: if this method failed due to IO error, super block might be damaged. If it is the case, use repair_super_block to restore super block before re-opening the repo.

pub fn repair_super_block(uri: &str, pwd: &str) -> Result<()>

Repair possibly damaged super block.

This method will try to repair super block using backup. One scenario is when reset_password failed due to IO error, super block might be damaged. Using this method can restore the damaged super block from backup. If super block is all good, this method is no-op.

This method is not useful for memory-based storage and must be called when repo is closed.

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

Returns whether the path points at an existing entity in repository.

path must be an absolute path.

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

Returns whether the path exists in repository and is pointing at a regular file.

path must be an absolute path.

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

Returns whether the path exists in repository and is pointing at a directory.

path must be an absolute path.

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

Create a file in read-write mode.

This method will create a file if it does not exist, and will truncate it if it does. See the OpenOptions::open method for more details.

path must be an absolute path.

This method is not atomic.

pub fn open_file<P: AsRef<Path>>(&mut self, path: P) -> Result<File>

Attempts to open a file in read-only mode.

path must be an absolute path.

See the OpenOptions::open method for more details.

Errors

This method will return an error if path does not already exist. Other errors may also be returned according to OpenOptions::open.

Examples

let mut f = repo.open_file("foo.txt")?;

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

Creates a new, empty directory at the specified path.

path must be an absolute path.

This method is atomic.

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

Recursively create a directory and all of its parent components if they are missing.

path must be an absolute path.

This method is not atomic in whole, but creating each entry is atomic.

pub fn read_dir<P: AsRef<Path>>(&self, path: P) -> Result<Vec<DirEntry>>

Returns a vector of all the entries within a directory.

path must be an absolute path.

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

Get the metadata about a file or directory at specified path.

path must be an absolute path.

pub fn history<P: AsRef<Path>>(&self, path: P) -> Result<Vec<Version>>

Return a vector of history versions of a regular file at specified path.

path must be an absolute path to a regular file.

pub fn copy<P: AsRef<Path>, Q: AsRef<Path>>(
    &mut self,
    from: P,
    to: Q
) -> Result<()>

Copies the content of one file to another.

This method will overwrite the content of to.

from and to must be absolute paths to regular files.

If from and to both point to the same file, this method is no-op.

This method is not atomic.

pub fn copy_dir_all<P: AsRef<Path>, Q: AsRef<Path>>(
    &mut self,
    from: P,
    to: Q
) -> Result<()>

Copies a directory to another recursively.

This method will overwrite the content of files in to with the files in from which have same relative location.

from and to must be absolute paths to directories.

If to is not empty, the entire directory tree of from will be merged to to.

This method will stop if any errors happened.

If from and to both point to the same directory, this method is no-op.

This method is not atomic.

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

Removes a regular file from the repository.

path must be an absolute path.

This method is atomic.

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

Remove an existing empty directory.

path must be an absolute path.

This method is atomic.

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

Removes a directory at this path, after removing all its children. Use carefully!

path must be an absolute path.

This method is not atomic in whole, but removing each entry is atomic.

pub fn rename<P: AsRef<Path>, Q: AsRef<Path>>(
    &mut self,
    from: P,
    to: Q
) -> Result<()>

Rename a file or directory to a new name, replacing the original file if to already exists.

from and to must be absolute paths.

This method is atomic.

pub fn destroy(uri: &str) -> Result<()>

Permanently destroy a repository specified by uri.

This will permanently delete all files and directories in a repository regardless it is opened or not. Use it with caution.

Trait Implementations

impl Debug for Repo

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

Formats the value using the given formatter.