Crate rustic_core

Source
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.