Crate rustic_core

Expand description

A library for deduplicated and encrypted backups, using repositories as specified in the restic repository design.

§Overview

This section gives a brief overview of the primary types in this crate:

The main type is the Repository type which describes a way to access a repository. It can be in different states and allows - depending on the state - various high-level actions to be performed on the repository like listing snapshots, backing up or restoring.

Besides this, various *Option types exist which allow to specify options for accessing a Repository or for the methods used within a Repository. Those types usually offer setter methods as well as implement serde::Serialize and serde::Deserialize.

Other main types are typically result types obtained by Repository methods which sometimes are also needed as input for other Repository method, like computing a PrunePlan and performing it.

There are also lower level data types which represent the stored repository format or help accessing/writing it. Those are collected in the repofile module. These types typically implement serde::Serialize and serde::Deserialize.

§Example - initialize a repository, backup to it and get snapshots

    use rustic_backend::BackendOptions;
    use rustic_core::{BackupOptions, ConfigOptions, KeyOptions, PathList,
        Repository, RepositoryOptions, SnapshotOptions
    };

    // Initialize the repository in a temporary dir
    let repo_dir = tempfile::tempdir().unwrap();

    let repo_opts = RepositoryOptions::default()
        .password("test");

    // Initialize Backends
    let backends = BackendOptions::default()
        .repository(repo_dir.path().to_str().unwrap())
        .to_backends()
        .unwrap();

    let key_opts = KeyOptions::default();

    let config_opts = ConfigOptions::default();

    let _repo = Repository::new(&repo_opts, &backends.clone()).unwrap().init(&key_opts, &config_opts).unwrap();

    // We could have used _repo directly, but open the repository again to show how to open it...
    let repo = Repository::new(&repo_opts, &backends).unwrap().open().unwrap();

    // Get all snapshots from the repository
    let snaps = repo.get_all_snapshots().unwrap();
    // Should be zero, as the repository has just been initialized
    assert_eq!(snaps.len(), 0);

    // Turn repository state to indexed (for backup):
    let repo = repo.to_indexed_ids().unwrap();

    // Pre-define the snapshot-to-backup
    let snap = SnapshotOptions::default()
        .add_tags("tag1,tag2").unwrap()
        .to_snapshot().unwrap();

    // Specify backup options and source
    let backup_opts = BackupOptions::default();
    let source = PathList::from_string("src").unwrap().sanitize().unwrap();

    // run the backup and return the snapshot pointing to the backup'ed data.
    let snap = repo.backup(&backup_opts, &source, snap).unwrap();
    // assert_eq!(&snap.paths, ["src"]);

    // Get all snapshots from the repository
    let snaps = repo.get_all_snapshots().unwrap();
    // Should now be 1, we just created a snapshot
    assert_eq!(snaps.len(), 1);

    assert_eq!(snaps[0], snap);

§Crate features

This crate exposes a few features for controlling dependency usage.

cli - Enables support for CLI features by enabling clap and merge features. This feature is disabled by default.
clap - Enables a dependency on the clap crate and enables parsing from the commandline. This feature is disabled by default.
merge - Enables support for merging multiple values into one, which enables the conflate dependency. This is needed for parsing commandline arguments and merging them into one (e.g. config). This feature is disabled by default.
webdav - Enables a dependency on the dav-server and futures crate. This enables us to run a WebDAV server asynchronously on the commandline. This feature is disabled by default.

Modules§

archiver 🔒
backend 🔒: Module for backend related functionality.
blob 🔒
chunker 🔒
commands 🔒: The commands that can be run by the CLI.
crypto 🔒
error 🔒: Error types and Result module.
id 🔒: The Id type and related functions
index 🔒
progress 🔒
repofile: Structs which are saved in JSON or binary format in the repository
repository 🔒
vfs: Virtual File System support - allows to act on the repository like on a file system

Macros§

define_new_id_struct: Generate newtypes for Ids identifying Repository files
impl_blobid: Generate newtypes for Ids identifying packed blobs
impl_repofile: Generate newtypes for Ids identifying Repository files implementing RepoFile
impl_repoid: Generate newtypes for Ids identifying Repository files

Structs§

BackupOptions: Options for the backup command.
BlobId: An Id identifying a “blob”
BlobInfo: Information about blobs within repoinfo
CheckOptions: Options for the check command
CommandInput: A command to be called which can be given as CLI option as well as in config files CommandInput implements Serialize/Deserialize as well as FromStr.
ConfigOptions: Options for the config command, used to set repository-wide options
CopySnapshot: This struct enhances [SnapshotFile] with the attribute relevant which indicates if the snapshot is relevant for copying.
DataId: An Id identifying a concat! (“blob of type”, stringify! (BlobType::Data))
FileDirStats: Statistics for files or directories
FindMatches: Results from find_matching_nodes
FindNode: Results from find_node_from_path
ForgetGroup: All snapshots of a group with group and forget information
ForgetGroups: A newtype for [Vec<ForgetGroup>]
ForgetSnapshot: This struct enhances [SnapshotFile] with the attributes keep and reasons which indicates if the snapshot should be kept and why.
FullIndex: A full index containing [Id]s and locations for tree and data blobs.
HexId: An Id in hexadecimal format
Id: Id is the hash id of an object.
IndexInfos: Index information from repoinfo
IndexedStatus: The indexed status of a repository
KeepOptions: Options which snapshots should be kept. Used by the forget command.
KeyOptions: Options for the key command. These are used when creating a new key.
LocalDestination: Local destination, used when restoring.
LocalSource: A LocalSource is a source from local paths which is used to be read from (i.e. to backup it).
LocalSourceFilterOptions: LocalSourceFilterOptions allow to filter a local source by various criteria.
LocalSourceSaveOptions: LocalSourceSaveOptions describes how entries from a local source will be saved in the repository.
LsOptions: Options for listing the Nodes of a Tree
NoProgress: A dummy struct which shows no progress but only logs titles and end of a progress.
NoProgressBars: Don’t show progress bars, only log rudimentary progress information.
OpenStatus: Open Status: This repository is open, i.e. the password has been checked and the decryption key is available.
PackInfo: Information about packs within repoinfo
ParentOptions: backup subcommand Options how the backup command uses a parent snapshot.
PathList: PathList is a rustic-internal list of PathBufs. It is used in the crate::Repository::backup command.
PruneOptions: Options for the prune command
PrunePlan: A plan what should be repacked or removed by a prune run
PruneStats: Statistics about a PrunePlan
ReadSourceEntry: Information about an entry to be able to open it.
RepairIndexOptions: Options for the repair index command
RepairSnapshotsOptions: Options for the repair snapshots command
RepoFileInfo: Information about a repository files of a given FileType
RepoFileInfos: Information about repository files
Repository: A Repository allows all kind of actions to be performed.
RepositoryBackends: The backends a repository can be initialized and operated on
RepositoryOptions: Options for using and opening a Repository
RestoreOptions: Options for the restore command
RestorePlan: Information about what will be restored.
RestoreStats: Restore statistics
RusticError: Errors that can result from rustic.
SnapshotGroup: SnapshotGroup specifies the group after a grouping using SnapshotGroupCriterion.
SnapshotGroupCriterion: SnapshotGroupCriterion determines how to group snapshots.
SnapshotOptions: Options for creating a new SnapshotFile structure for a new backup snapshot.
StringList: StringList is a rustic-internal list of Strings. It is used within SnapshotFile
TreeId: An Id identifying a concat! (“blob of type”, stringify! (BlobType::Tree))

Enums§

CommandInputErrorKind: CommandInputErrorKind describes the errors that can be returned from the CommandInput
ErrorKind: ErrorKind describes the errors that can happen while executing a high-level command.
FileType: Type for describing the kind of a file that can occur.
LimitOption: Enum to specify a size limit
ReadSubsetOption: Options to specify which subset of packs will be read
Severity: Severity of an error, ranging from informational to fatal.
Status: Status of an error, indicating whether it is permanent, temporary, or persistent.

Constants§

ALL_FILE_TYPES: All FileTypes which are located in separated directories

Traits§

IndexedFull: A repository which is indexed such that all blob information is fully contained in the index.
IndexedIds: A repository which is indexed such that all tree blobs are contained in the index and additionally the Ids of data blobs are also contained in the index.
IndexedTree: A repository which is indexed such that all tree blobs are contained in the index.
Open: A repository which is open, i.e. the password has been checked and the decryption key is available.
PackedId: A marker trait for Ids which identify Blobs in pack files
Progress: Trait to report progress information for any rustic action which supports that.
ProgressBars: Trait to start progress information report progress information for any rustic action which supports that.
ReadBackend: Trait for backends that can read.
ReadSource: Trait for backends that can read from a source.
ReadSourceOpen: Trait for backends that can read and open sources. This trait is implemented by all backends that can read data and open from a source.
WriteBackend: Trait for backends that can write. This trait is implemented by all backends that can write data.

Functions§

compression_level_range: The accepted range of compression levels.
last_modified_node: An ordering function returning the latest node by mtime
max_compression_level: The maximum compression level allowed by zstd

Type Aliases§

RusticResult: Result type that is being returned from methods that can fail and thus have RusticErrors.