Rustic Core

https://docs.rs/rustic_core/
Admin
Rustic Core is a Rust library for creating deduplicated and encrypted backups using...
Tokens:861,326
Snippets:5,572
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Setup Mock Backend for Snapshot Tests

Source: https://docs.rs/rustic_core/latest/src/rustic_core/repofile/snapshotfile.rs.html

Initializes a mock backend with predefined snapshot data and keys. This setup is used for testing snapshot file retrieval functions.

```rust
fn setup_mock_backend() -> (DecryptBackend, [SnapshotId; 3]) {
        let key = vec![0u8; 32];
        let snapshot_files = HashMap::from([
            (
                id1,
                Timestamp::from_second(1_752_483_600)
                    .unwrap()
                    .to_zoned(TimeZone::UTC),
            ),
            (
                id2,
                Timestamp::from_second(1_752_483_700)
                    .unwrap()
                    .to_zoned(TimeZone::UTC),
            ),
            // this is the latest
            (
                id3,
                Timestamp::from_second(1_752_483_800)
                    .unwrap()
                    .to_zoned(TimeZone::UTC),
            ),
        ]);
        let mut back = MockBackend::new();
        let _ = back.expect_list_with_size().returning(move |_| {
            // unordered ids
            Ok(vec![(id2, 0), (id3, 0), (id1, 0)])
        });
        let _ = back
            .expect_read_full()
            .returning(move |_tpe, id| Ok(snapshot_files.get(id).unwrap().clone()));

        let mut be = DecryptBackend::new(Arc::new(back), key);
        be.set_zstd(None);

        (be, [id1, id2, id3])
    }
```

--------------------------------

### RepoId Implementations

Source: https://docs.rs/rustic_core/latest/rustic_core/repofile/trait.RepoId.html

Examples of implementing the RepoId trait for various repository file types.

```rust
impl RepoId for ConfigId {
    const TYPE: FileType = FileType::Config
}
```

```rust
impl RepoId for IndexId {
    const TYPE: FileType = FileType::Index
}
```

```rust
impl RepoId for KeyId {
    const TYPE: FileType = FileType::Key
}
```

```rust
impl RepoId for PackId {
    const TYPE: FileType = FileType::Pack
}
```

```rust
impl RepoId for SnapshotId {
    const TYPE: FileType = FileType::Snapshot
}
```

--------------------------------

### Initialize and use a repository

Source: https://docs.rs/rustic_core/latest/src/rustic_core/lib.rs.html

Demonstrates initializing a new repository, opening it, and performing a backup operation. Ensure credentials are saved securely in production environments.

```rust
    use rustic_backend::BackendOptions;
    use rustic_core::{repofile::MasterKey, BackupOptions, ConfigOptions, Credentials,
        KeyOptions, PathList, Repository, RepositoryOptions, SnapshotOptions,
    };

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

    let repo_opts = RepositoryOptions::default();
     // In real life, make sure to save this credential!
    let credentials = Credentials::Masterkey(MasterKey::new());

    // 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)
        .unwrap()
        .init(&credentials, &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(&credentials).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);
```

--------------------------------

### match_indices: Iterate over matches and their start indices

Source: https://docs.rs/rustic_core/latest/rustic_core/struct.HexId.html

Use `match_indices` to get an iterator over all non-overlapping occurrences of a pattern and their starting indices within the string. The pattern can be a string slice, char, or a closure.

```rust
let v: Vec<_> = "abcXXXabcYYYabc".match_indices("abc").collect();
assert_eq!(v, [(0, "abc"), (6, "abc"), (12, "abc")]);
```

```rust
let v: Vec<_> = "1abcabc2".match_indices("abc").collect();
assert_eq!(v, [(1, "abc"), (4, "abc")]);
```

```rust
let v: Vec<_> = "ababa".match_indices("aba").collect();
assert_eq!(v, [(0, "aba")]); // only the first `aba`
```

--------------------------------

### Get Repository Progress (Bytes)

Source: https://docs.rs/rustic_core/latest/rustic_core/struct.Repository.html

Starts a new progress bar specifically designed for counting bytes, with a given prefix.

```rust
pub fn progress_bytes(&self, prefix: &str) -> Progress
```

--------------------------------

### POST /init_with_config

Source: https://docs.rs/rustic_core/latest/rustic_core/struct.Repository.html

Initialize a new repository with a provided password and a ready ConfigFile.

```APIDOC
## POST /init_with_config

### Description
Initialize a new repository with given password and a ready ConfigFile. This returns an open repository which can be directly used.

### Parameters
#### Request Body
- **password** (str) - Required - The password to use
- **key_opts** (KeyOptions) - Required - The options to use for the key
- **config** (ConfigFile) - Required - The config file to use
```

--------------------------------

### Get Repository Progress (Counter)

Source: https://docs.rs/rustic_core/latest/rustic_core/struct.Repository.html

Starts a new progress counter with a specified prefix, used for counting arbitrary events.

```rust
pub fn progress_counter(&self, prefix: &str) -> Progress
```

--------------------------------

### Initialize a new repository with init

Source: https://docs.rs/rustic_core/latest/rustic_core/commands/init/fn.init.html

Initializes a repository with the specified state, credentials, and configuration options. Returns a tuple containing the key, optional key ID, and the configuration file.

```rust
pub(crate) fn init<S>(
    repo: &Repository<S>,
    credentials: &Credentials,
    key_opts: &KeyOptions,
    config_opts: &ConfigOptions,
) -> RusticResult<(Key, Option<KeyId>, ConfigFile)>
```

--------------------------------

### Initialize repository with configuration

Source: https://docs.rs/rustic_core/latest/rustic_core/commands/init/fn.init_with_config.html

Initializes a new repository using the specified ConfigFile, credentials, and key options.

```rust
pub(crate) fn init_with_config<S>(
    repo: &Repository<S>,
    credentials: &Credentials,
    key_opts: &KeyOptions,
    config: &ConfigFile,
) -> RusticResult<(Key, Option<KeyId>)>
```

--------------------------------

### Get Repository Progress (Spinner)

Source: https://docs.rs/rustic_core/latest/rustic_core/struct.Repository.html

Starts a new progress spinner with a given prefix. This progress type does not have a defined length and is not advanced, only finished.

```rust
pub fn progress_spinner(&self, prefix: &str) -> Progress
```

--------------------------------

### GET /cat_file

Source: https://docs.rs/rustic_core/latest/rustic_core/struct.Repository.html

Get the content of the decrypted repository file given by id and FileType.

```APIDOC
## GET /cat_file

### Description
Get the content of the decrypted repository file given by id and FileType.

### Parameters
#### Query Parameters
- **tpe** (FileType) - Required - The type of the file to get
- **id** (str) - Required - The id of the file to get

### Errors
- If the string is not a valid hexadecimal string
- If no id could be found
- If the id is not unique
```

--------------------------------

### POST /init

Source: https://docs.rs/rustic_core/latest/rustic_core/struct.Repository.html

Initialize a new repository with given credentials and options, returning an open repository.

```APIDOC
## POST /init

### Description
Initialize a new repository with given credentials and options. This returns an open repository which can be directly used.

### Parameters
#### Request Body
- **credentials** (Credentials) - Required - The credentials
- **key_opts** (KeyOptions) - Required - The options to use for the key
- **config_opts** (ConfigOptions) - Required - The options to use for the config

### Errors
- If a config file already exists
- If listing the repository config file failed
- If there is more than one repository config file
```

--------------------------------

### POST /init

Source: https://docs.rs/rustic_core/latest/src/rustic_core/repository.rs.html

Initializes a new repository with the provided credentials, key options, and configuration options. It checks for existing configuration files before proceeding.

```APIDOC
## POST /init

### Description
Initializes a new repository with given credentials and options. Returns an open repository ready for use.

### Parameters
#### Request Body
- **credentials** (Credentials) - Required - The credentials for the repository
- **key_opts** (KeyOptions) - Required - The options to use for the key
- **config_opts** (ConfigOptions) - Required - The options to use for the config

### Response
#### Success Response (200)
- **Repository<OpenStatus>** - The initialized and open repository object
```

--------------------------------

### Get Key-Value Pair

Source: https://docs.rs/rustic_core/latest/rustic_core/commands/check/type.IndexPacks.html

Retrieves a key-value pair corresponding to the supplied key. This is useful for key types where non-identical keys can be considered equal, for getting the stored key value from a borrowed lookup key, or for getting a reference to a key with the same lifetime as the collection.

```APIDOC
## GET /api/btreemap/get_key_value

### Description
Retrieves the key-value pair corresponding to the supplied key.

### Method
GET

### Endpoint
`/api/btreemap/get_key_value`

### Parameters
#### Query Parameters
- **k** (string) - Required - The key to search for.

### Response
#### Success Response (200)
- **key** (string) - The key found in the map.
- **value** (string) - The value associated with the key.

#### Response Example
```json
{
  "key": "example_key",
  "value": "example_value"
}
```
```

--------------------------------

### Get Metadata with Path and Handle Errors

Source: https://docs.rs/rustic_core/latest/rustic_core/error/type.RusticResult.html

Shows how to get file metadata using Path and handle potential errors like 'NotFound' using Result methods.

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

--------------------------------

### Repository Initialization, Backup, and Snapshot Retrieval

Source: https://docs.rs/rustic_core/latest/rustic_core/index.html

This example demonstrates how to initialize a new repository, perform a backup, and retrieve snapshots. It covers setting up backend options, credentials, and various configuration options.

```APIDOC
## Example - Initialize a repository, backup to it and get snapshots

### Description
This example demonstrates the core workflow of initializing a repository, backing up data to it, and then retrieving the created snapshots. It covers setting up backend options, credentials, and various configuration options required for these operations.

### Method
This is a procedural example demonstrating a sequence of operations rather than a single HTTP method.

### Endpoint
N/A (Local operations using the rustic_core library)

### Parameters
N/A (Parameters are handled via Rust structs and methods)

### Request Example
```rust
    use rustic_backend::BackendOptions;
    use rustic_core::{repofile::MasterKey, BackupOptions, ConfigOptions, Credentials,
        KeyOptions, PathList, Repository, RepositoryOptions, SnapshotOptions,
    };

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

    let repo_opts = RepositoryOptions::default();
     // In real life, make sure to save this credential!
    let credentials = Credentials::Masterkey(MasterKey::new());

    // 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)
        .unwrap()
        .init(&credentials, &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(&credentials).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);
```

### Response
#### Success Response (200)
N/A (This is a code example, not an API response)

#### Response Example
N/A (This is a code example, not an API response)
```

--------------------------------

### Initialize a new repository

Source: https://docs.rs/rustic_core/latest/src/rustic_core/commands/init.rs.html

Initializes a repository by creating a configuration file and setting up the encryption key. Returns a tuple containing the key, optional key ID, and the configuration file.

```rust
pub(crate) fn init<S>(
    repo: &Repository<S>,
    credentials: &Credentials,
    key_opts: &KeyOptions,
    config_opts: &ConfigOptions,
) -> RusticResult<(Key, Option<KeyId>, ConfigFile)> {
    // Create config first to allow catching errors from here without writing anything
    let repo_id = RepositoryId::from(Id::random());
    let chunker_poly = random_poly()?;
    let mut config = ConfigFile::new(2, repo_id, chunker_poly);
    if repo.be_hot.is_some() {
        // for hot/cold repository, `config` must be identical to the config file which is read by the backend, i.e. the one saved in the hot repo.
        // Note: init_with_config does handle the is_hot config correctly for the hot and the cold repo.
        config.is_hot = Some(true);
    }
    config_opts.apply(&mut config)?;

    let (key, key_id) = init_with_config(repo, credentials, key_opts, &config)?;
    info!("repository {repo_id} successfully created.");

    Ok((key, key_id, config))
}
```

--------------------------------

### Initialize a new repository

Source: https://docs.rs/rustic_core/latest/src/rustic_core/repository.rs.html

Initializes a new repository with the provided credentials, key options, and configuration options. Returns an error if a configuration file already exists.

```rust
pub fn init(
        self,
        credentials: &Credentials,
        key_opts: &KeyOptions,
        config_opts: &ConfigOptions,
    ) -> RusticResult<Repository<OpenStatus>> {
        let config_exists = self.config_id_with_backend(&self.be)?.is_some();
        let hot_config_exists = match self.be_hot {
            None => false,
            Some(ref be) => self.config_id_with_backend(be)?.is_some(),
        };
        if config_exists || hot_config_exists {
            return Err(RusticError::new(
                ErrorKind::Configuration,
                "Config file already exists for `{name}`. Please check the repository.",
            )
            .attach_context("name", self.name));
        }

        let (key, key_id, config) =
            commands::init::init(&self, credentials, key_opts, config_opts)?;

        self.open_raw(key, key_id, config)
    }
```

--------------------------------

### Find Ids Starting With Strings from Iterator

Source: https://docs.rs/rustic_core/latest/src/rustic_core/id.rs.html

Searches an iterator of Ids for those that start with any of the provided strings. This function requires the `FindUniqueMultiple` trait and `RusticResult`. It returns an error if no id is found or if an id is not unique for any request.

```rust
pub fn find_starts_with_from_iter<T: AsRef<str>, I: IntoIterator<Item = Self>>(
        vec: &[T],
        iter: I,
    ) -> RusticResult<Vec<Self>> {
        iter.into_iter()
            .find_unique_multiple(|id: &Self, v: &T| id.to_hex().starts_with(v.as_ref()), vec)
            .assert_found(vec)
    }
```

--------------------------------

### GET /tree

Source: https://docs.rs/rustic_core/latest/src/rustic_core/repository.rs.html

Retrieves a Tree object by its ID.

```APIDOC
## GET /tree

### Description
Get a Tree by Id from the repository.

### Method
GET

### Parameters
#### Query Parameters
- **id** (TreeId) - Required - The Id of the tree
```

--------------------------------

### Create SnapshotFile from Options

Source: https://docs.rs/rustic_core/latest/src/rustic_core/repofile/snapshotfile.rs.html

Initializes a SnapshotFile using provided SnapshotOptions. Handles hostname resolution and potential errors during setup.

```rust
impl SnapshotFile {
    /// Create a [`SnapshotFile`] from [`SnapshotOptions`].
    ///
    /// # Arguments
    ///
    /// * `opts` - The [`SnapshotOptions`] to use
    ///
    /// # Errors
    ///
    /// * If the hostname is not valid unicode
    /// * If the delete time is not in the range of `Local::now()`
    /// * If the description file could not be read
    ///
    /// # Note
    ///
    /// This is the preferred way to create a new [`SnapshotFile`] to be used within [`crate::Repository::backup`].
    pub fn from_options(opts: &SnapshotOptions) -> RusticResult<Self> {
        let hostname = if let Some(host) = &opts.host {
            host.clone()
        } else {
            let hostname = gethostname();
            hostname
                .to_str()
                .ok_or_else(|| {
                    RusticError::new(
                        ErrorKind::InvalidInput,

```

--------------------------------

### Get All Snapshots

Source: https://docs.rs/rustic_core/latest/src/rustic_core/repository.rs.html

Retrieves all snapshots available in the repository.

```APIDOC
## GET /api/snapshots/all

### Description
Retrieves all snapshots stored in the repository. The order of the returned snapshots is not guaranteed.

### Method
GET

### Endpoint
/api/snapshots/all

### Response
#### Success Response (200)
- **snapshots** (array of SnapshotFile) - A list of all SnapshotFile objects in the repository.

#### Response Example
```json
{
  "snapshots": [
    {
      "id": "snapshot_id_1",
      "timestamp": "2023-10-27T10:00:00Z",
      "files": [...] 
    },
    {
      "id": "snapshot_id_2",
      "timestamp": "2023-10-27T11:00:00Z",
      "files": [...] 
    }
  ]
}
```
```

--------------------------------

### init_with_config

Source: https://docs.rs/rustic_core/latest/rustic_core/commands/init/fn.init_with_config.html

Initializes a new repository using the provided configuration file, credentials, and key options.

```APIDOC
## init_with_config

### Description
Initializes a new repository using the given ConfigFile.

### Parameters
#### Arguments
- **repo** (Repository<S>) - Required - The repository to initialize.
- **credentials** (Credentials) - Required - The credentials to use.
- **key_opts** (KeyOptions) - Required - The options to create the key with.
- **config** (ConfigFile) - Required - The config to use.

### Returns
- **(Key, Option<KeyId>)** - The key used to encrypt the config.
```

--------------------------------

### Initialize repository with existing config

Source: https://docs.rs/rustic_core/latest/src/rustic_core/repository.rs.html

Initializes a repository using provided credentials and an existing ConfigFile instance.

```rust
pub fn init_with_config(
        self,
        credentials: &Credentials,
        key_opts: &KeyOptions,
        config: ConfigFile,
    ) -> RusticResult<Repository<OpenStatus>> {
        let (key, key_id) =
            commands::init::init_with_config(&self, credentials, key_opts, &config)?;
        info!("repository {} successfully created.", config.id);
        self.open_raw(key, key_id, config)
    }
```

--------------------------------

### get

Source: https://docs.rs/rustic_core/latest/rustic_core/commands/check/type.IndexPacks.html

Returns a reference to the value corresponding to the key.

```APIDOC
## get

### Description
Returns a reference to the value corresponding to the key.

### Parameters
#### Request Body
- **key** (&Q) - Required - The key to search for.
```

--------------------------------

### init

Source: https://docs.rs/rustic_core/latest/rustic_core/commands/init/index.html

Initializes a new repository.

```APIDOC
## init

### Description
Initializes a new repository.

### Method
Internal Function

### Endpoint
rustic_core::commands::init
```

--------------------------------

### Iterator Length

Source: https://docs.rs/rustic_core/latest/rustic_core/blob/tree/struct.TreeStreamerOnce.html

Method to get the length of an iterator.

```APIDOC
## fn try_len(&self) -> Result<usize, (usize, Option<usize>)>

### Description
Returns the length of the iterator if one exists. Otherwise, returns `self.size_hint()`.

### Method
N/A (Method on Iterator trait)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **usize** - The length of the iterator if known.

#### Error Response
- **(usize, Option<usize>)** - A tuple containing the lower and upper bounds of the iterator's size hint if the length is not known.

#### Response Example
None
```

--------------------------------

### match_indices

Source: https://docs.rs/rustic_core/latest/rustic_core/struct.HexId.html

Returns an iterator over matches and their starting indices.

```APIDOC
## match_indices

### Description
Returns an iterator over the disjoint matches of a pattern within this string slice as well as the index that the match starts at.

### Parameters
- **pat** (Pattern) - Required - The pattern to search for.
```

--------------------------------

### Initialize, Backup, and Get Snapshots with Rustic Core

Source: https://docs.rs/rustic_core/latest/index.html

Demonstrates initializing a repository, performing a backup, and retrieving snapshots. Ensure credentials are saved securely in production. The repository state is transitioned to indexed for backup operations.

```rust
    use rustic_backend::BackendOptions;
    use rustic_core::{repofile::MasterKey, BackupOptions, ConfigOptions,
        Credentials,
        KeyOptions,
        PathList,
        Repository,
        RepositoryOptions,
        SnapshotOptions,
    };

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

    let repo_opts = RepositoryOptions::default();
     // In real life, make sure to save this credential!
    let credentials = Credentials::Masterkey(MasterKey::new());

    // 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)
        .unwrap()
        .init(&credentials, &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(&credentials).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);

```

--------------------------------

### Initialize Repository

Source: https://docs.rs/rustic_core/latest/src/rustic_core/repository.rs.html

Methods to create a new repository instance, with or without custom progress bars.

```rust
impl Repository<()> {
    /// Create a new repository from the given [`RepositoryOptions`] (without progress bars)
    ///
    /// # Arguments
    ///
    /// * `opts` - The options to use for the repository
    /// * `backends` - The backends to create/access a repository on
    ///
    /// # Errors
    ///
    /// * If no repository is given
    /// * If the warm-up command does not contain `%id`
    /// * If the specified backend cannot be loaded, e.g. is not supported
    pub fn new(opts: &RepositoryOptions, backends: &RepositoryBackends) -> RusticResult<Self> {
        Self::new_with_progress(opts, backends, NoProgressBars {})
    }

    /// Create a new repository from the given [`RepositoryOptions`] with given progress bars
    ///
    /// # Type Parameters
    ///
    /// * `P` - The type of the progress bar
    ///
    /// # Arguments
    ///
    /// * `opts` - The options to use for the repository
    /// * `backends` - The backends to create/access a repository on
    /// * `pb` - The progress bars to use
    ///
    /// # Errors
    ///
    /// * If no repository is given
    /// * If the warm-up command does not contain `%id`
    /// * If the specified backend cannot be loaded, e.g. is not supported
    pub fn new_with_progress<P: ProgressBars>(
        opts: &RepositoryOptions,
        backends: &RepositoryBackends,
        pb: P,
    ) -> RusticResult<Self> {
        let mut be = backends.repository();
        let be_hot = backends.repo_hot();

        if let Some(warm_up) = &opts.warm_up_command {
            let _ = warm_up.uses_plural_placeholders()?;

            info!(
                "using warm-up command {warm_up} with batch size {}",
                opts.warm_up_batch.unwrap_or(1)
            );
        }

        let be_cold = be.clone();

        if opts.warm_up {
            be = WarmUpAccessBackend::new_warm_up(be);
        }

        let mut name = be.location();
        if let Some(be_hot) = &be_hot {
            be = Arc::new(HotColdBackend::new(be, be_hot.clone()));
            name.push('#');
            name.push_str(&be_hot.location());
        }

        Ok(Self {
            name,
            be,
            be_hot,
            be_cold,
            opts: opts.clone(),
            pb: Arc::new(pb),
            status: (),
        })
    }
}
```

--------------------------------

### Iterate Over a Sub-Range of BTreeMap Elements

Source: https://docs.rs/rustic_core/latest/rustic_core/commands/check/type.IndexPacks.html

Constructs a double-ended iterator over a sub-range of elements. Supports various range syntaxes like `min..max` or `(Bound<T>, Bound<T>)`. Panics if range start > end or if start == end with both bounds excluded.

```rust
use std::collections::BTreeMap;
use std::ops::Bound::Included;

let mut map = BTreeMap::new();
map.insert(3, "a");
map.insert(5, "b");
map.insert(8, "c");
for (&key, &value) in map.range((Included(&4), Included(&8))) {
    println!("{key}: {value}");
}
assert_eq!(Some((&5, &"b")), map.range(4..).next());

```

--------------------------------

### GET /index_entry

Source: https://docs.rs/rustic_core/latest/src/rustic_core/repository.rs.html

Retrieves an IndexEntry for a given blob ID.

```APIDOC
## GET /index_entry

### Description
Get the IndexEntry of the given blob.

### Method
GET

### Parameters
#### Query Parameters
- **id** (PackedId) - Required - The id of the blob
```

--------------------------------

### Function: init

Source: https://docs.rs/rustic_core/latest/rustic_core/commands/init/fn.init.html

Initializes a new repository with the provided credentials and configuration options.

```APIDOC
## init

### Description
Initializes a new repository. This function sets up the necessary keys and configuration files for a rustic repository.

### Method
Rust Function Call

### Parameters
- **repo** (Repository<S>) - Required - The repository to initialize.
- **credentials** (Credentials) - Required - The credentials to use.
- **key_opts** (KeyOptions) - Required - The options to create the key with.
- **config_opts** (ConfigOptions) - Required - The options to create the config with.

### Errors
- If no polynomial could be found in one million tries.

### Returns
A tuple containing the Key, an optional KeyId, and the ConfigFile.
```

--------------------------------

### GET /config_id

Source: https://docs.rs/rustic_core/latest/src/rustic_core/repository.rs.html

Retrieves the ID of the repository configuration file.

```APIDOC
## GET /config_id

### Description
Returns the Id of the config file for the repository. Returns None if no config file is found.

### Response
#### Success Response (200)
- **ConfigId** (Option<ConfigId>) - The id of the config file or None if not found.
```

--------------------------------

### init_with_config

Source: https://docs.rs/rustic_core/latest/rustic_core/commands/init/index.html

Initializes a new repository using the given ConfigFile.

```APIDOC
## init_with_config

### Description
Initializes a new repository using the given ConfigFile.

### Method
Internal Function

### Endpoint
rustic_core::commands::init_with_config

### Parameters
#### Request Body
- **ConfigFile** (object) - Required - The configuration file object used to initialize the repository.
```

--------------------------------

### impl<T> Any for T

Source: https://docs.rs/rustic_core/latest/rustic_core/backend/node/struct.Node.html

Provides the `type_id` method to get the `TypeId` of an object.

```APIDOC
## GET /api/any

### Description
Retrieves the unique type identifier for an object.

### Method
GET

### Endpoint
`/api/any/{object_id}`

### Parameters
#### Path Parameters
- **object_id** (string) - Required - The unique identifier of the object.

### Response
#### Success Response (200)
- **type_id** (string) - The TypeId of the object.

#### Response Example
```json
{
  "type_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```
```

--------------------------------

### Get Subsection

Source: https://docs.rs/rustic_core/latest/rustic_core/archiver/tree/struct.TreeIterator.html

Returns an iterator over a subsection of the original iterator.

```APIDOC
## fn get<R>(self, index: R) -> <R as IteratorIndex<Self>>::Output

### Description
Returns an iterator over a subsection of the iterator.

### Method
N/A (Method on Iterator trait)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
An iterator over a subsection.

#### Response Example
None
```

--------------------------------

### Initialize repository with existing config

Source: https://docs.rs/rustic_core/latest/src/rustic_core/commands/init.rs.html

Initializes a repository using a provided ConfigFile. This function handles backend creation, key initialization based on credentials, and saving the configuration.

```rust
pub(crate) fn init_with_config<S>(
    repo: &Repository<S>,
    credentials: &Credentials,
    key_opts: &KeyOptions,
    config: &ConfigFile,
) -> RusticResult<(Key, Option<KeyId>)> {
    repo.be.create()?;
    let (key, id) = match credentials {
        Credentials::Password(password) => {
            let (key, id) = init_key(repo, key_opts, password)?;
            info!("key {id} successfully added.");
            (key, Some(id))
        }
        Credentials::Masterkey(key) => (key.key(), None),
    };
    save_config(repo, config.clone(), key)?;

    Ok((key, id))
}
```

--------------------------------

### Commands Init Functions

Source: https://docs.rs/rustic_core/latest/rustic_core/all.html

Functions for initializing a new repository.

```APIDOC
## commands::init::init

### Description
Initializes a new repository.

### Method
N/A (Function)

### Endpoint
N/A

## commands::init::init_with_config

### Description
Initializes a new repository with a specified configuration.

### Method
N/A (Function)

### Endpoint
N/A
```

--------------------------------

### GET /node_from_path

Source: https://docs.rs/rustic_core/latest/src/rustic_core/repository.rs.html

Retrieves a Node from a root tree and a specific path.

```APIDOC
## GET /node_from_path

### Description
Traverses into the path to get the node from a root tree.

### Method
GET

### Parameters
#### Query Parameters
- **root_tree** (TreeId) - Required - The TreeId of the root tree
- **path** (Path) - Required - The path to traverse
```

--------------------------------

### Get Matching Snapshots

Source: https://docs.rs/rustic_core/latest/src/rustic_core/repository.rs.html

Retrieves snapshots that match a given filter.

```APIDOC
## GET /api/snapshots/matching

### Description
Retrieves snapshots from the repository that satisfy a given filter condition. The result is not sorted and may come in random order.

### Method
GET

### Endpoint
/api/snapshots/matching

### Query Parameters
- **filter** (function) - Required - A function that takes a SnapshotFile and returns true if it should be included.

### Response
#### Success Response (200)
- **snapshots** (array of SnapshotFile) - A list of SnapshotFile objects that match the filter.

#### Response Example
```json
{
  "snapshots": [
    {
      "id": "snapshot_id_1",
      "timestamp": "2023-10-27T10:00:00Z",
      "files": [...] 
    }
  ]
}
```
```

--------------------------------

### Create New Repository (No Progress Bars)

Source: https://docs.rs/rustic_core/latest/rustic_core/struct.Repository.html

Initializes a new Repository instance using provided options and backends, without progress bar integration. Errors can occur if no repository is specified, the warm-up command is invalid, or a backend fails to load.

```rust
pub fn new( opts: &RepositoryOptions,
 backends: &RepositoryBackends,
 ) -> RusticResult<Self>
```

--------------------------------

### Create Snapshot From Options

Source: https://docs.rs/rustic_core/latest/src/rustic_core/repofile/snapshotfile.rs.html

Constructs a SnapshotFile from provided options, including handling descriptions from files and setting tags. Ensure the description file exists and is readable if `description_from` is specified.

```rust
        let mut snap = Self {
            time,
            hostname,
            label: opts.label.clone().unwrap_or_default(),
            delete,
            summary: Some(SnapshotSummary {
                command,
                ..Default::default()
            }),
            description: opts.description.clone(),
            ..Default::default()
        };

        // use description from description file if it is given
        if let Some(ref path) = opts.description_from {
            snap.description = Some(std::fs::read_to_string(path).map_err(|err| {
                RusticError::with_source(
                    ErrorKind::InvalidInput,
                    "Failed to read description file `{path}`. Please make sure the file exists and is readable.",
                    err,
                )
                .attach_context("path", path.to_string_lossy().to_string())
            })?);
        }

        _ = snap.set_tags(opts.tags.clone());

        Ok(snap)
    }
```

--------------------------------

### GET /snapshots

Source: https://docs.rs/rustic_core/latest/src/rustic_core/repository.rs.html

Retrieves multiple snapshots based on a list of IDs.

```APIDOC
## GET /snapshots

### Description
Retrieves multiple snapshots based on a list of IDs or aliases.

### Parameters
#### Query Parameters
- **ids** (Vec<string>) - Required - A list of snapshot IDs or aliases.
- **filter** (FnMut) - Optional - A filter function to apply to the snapshot search.
```

--------------------------------

### Repository Initialization

Source: https://docs.rs/rustic_core/latest/src/rustic_core/repository.rs.html

Methods for creating a new repository instance with optional progress bar support.

```APIDOC
## Repository::new

### Description
Creates a new repository instance from the provided options and backends without progress bars.

### Parameters
- **opts** (RepositoryOptions) - Required - The configuration options for the repository.
- **backends** (RepositoryBackends) - Required - The backends to access the repository.

### Response
- **RusticResult<Self>** - Returns the initialized Repository or an error if initialization fails.

## Repository::new_with_progress

### Description
Creates a new repository instance with custom progress bar implementation.

### Parameters
- **opts** (RepositoryOptions) - Required - The configuration options for the repository.
- **backends** (RepositoryBackends) - Required - The backends to access the repository.
- **pb** (P: ProgressBars) - Required - The progress bar implementation to use.

### Response
- **RusticResult<Self>** - Returns the initialized Repository or an error if initialization fails.
```

--------------------------------

### GET /snapshots/{id}

Source: https://docs.rs/rustic_core/latest/src/rustic_core/repository.rs.html

Retrieves a single snapshot by its ID or alias.

```APIDOC
## GET /snapshots/{id}

### Description
Retrieves a single snapshot. The ID can be a partial hexadecimal string, 'latest', or 'latest~N'.

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID or alias of the snapshot to retrieve.

#### Query Parameters
- **filter** (FnMut) - Optional - A filter function to apply to the snapshot search.
```

--------------------------------

### GET /snapshots

Source: https://docs.rs/rustic_core/latest/rustic_core/struct.Repository.html

Retrieves snapshots based on provided identifiers or filters.

```APIDOC
## GET /snapshots

### Description
Retrieve snapshots from the repository.

### Method
GET

### Endpoint
/snapshots

### Parameters
#### Query Parameters
- **id** (str) - Optional - The id of the snapshot to get
- **ids** (Vec<T>) - Optional - List of snapshot ids to retrieve

### Errors
- If the string is not a valid hexadecimal string
- If no id could be found
- If the id is not unique.
```

--------------------------------

### Setup Mock Backend for Decryption

Source: https://docs.rs/rustic_core/latest/src/rustic_core/repofile/snapshotfile.rs.html

Sets up a mock `DecryptBackend` with a generated key and three distinct snapshot IDs. It then populates this backend with fake encrypted snapshot files using the `fake_snapshot_file_with_id_time` helper function.

```rust
fn setup_mock_backend() -> (DecryptBackend<Key>, [Id; 3]) {
        let key = Key::new();

        let id1 = Id::from_str("0011223344556677001122334455667700112233445566770000000000000001")
            .unwrap();
        let id2 = Id::from_str("0021223344556677001122334455667700112233445566770000000000000002")
            .unwrap();
        let id3 = Id::from_str("0031223344556677001122334455667700112233445566770000000000000003")
            .unwrap();

        let snapshot_files = fake_snapshot_file_with_id_time(
            vec![
                (
                    id1,

```

--------------------------------

### GET /key_id

Source: https://docs.rs/rustic_core/latest/rustic_core/struct.Repository.html

Retrieves the KeyId of the key used to open the repository.

```APIDOC
## GET /key_id

### Description
Get the KeyId of the key used to open the repository.

### Method
GET

### Endpoint
/key_id
```

--------------------------------

### Create New ConfigFile

Source: https://docs.rs/rustic_core/latest/rustic_core/repofile/struct.ConfigFile.html

Initializes a new ConfigFile with the specified version, repository ID, and chunker polynomial.

```rust
pub fn new(version: u32, id: RepositoryId, poly: u64) -> Self
```

--------------------------------

### Create FileArchiver Instance

Source: https://docs.rs/rustic_core/latest/src/rustic_core/archiver/file_archiver.rs.html

Initializes a new FileArchiver with the specified backend, index, indexer, and configuration. Requires a ConfigFile and supports BlobType::Data.

```rust
pub(crate) fn new(
        be: BE,
        index: &'a I,
        indexer: SharedIndexer<BE>,
        config: &ConfigFile,
    ) -> RusticResult<Self> {
        let pack_sizer = 
            PackSizer::from_config(config, BlobType::Data, index.total_size(BlobType::Data));
        let data_packer = Packer::new(be, BlobType::Data, indexer, pack_sizer)?;

        Ok(Self {
            index,
            data_packer,
            config: config.clone(),
        })
    }
```

--------------------------------

### Iterator Length Hint

Source: https://docs.rs/rustic_core/latest/rustic_core/index/binarysorted/struct.PackIndexes.html

Method to get the length of an iterator if available.

```APIDOC
## fn try_len(&self) -> Result<usize, (usize, Option<usize>)>

### Description
Returns the length of the iterator if one exists. Otherwise returns `self.size_hint()`.

### Method
N/A (Iterator method)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **usize** - The exact length of the iterator if known.

#### Error Response
- **(usize, Option<usize>)** - The lower and upper bounds of the iterator's length if the exact length is not known.

#### Response Example
N/A
```

--------------------------------

### Initialize New Repository

Source: https://docs.rs/rustic_core/latest/src/rustic_core/commands/init.rs.html

Initializes a new repository with provided credentials, key options, and configuration options. This is the primary function for creating a new repository.

```APIDOC
## POST /api/repository/init

### Description
Initializes a new repository. This function handles the creation of the repository ID, chunker polynomial, and configuration file, then proceeds to initialize the key and save the configuration.

### Method
POST

### Endpoint
/api/repository/init

### Parameters
#### Request Body
- **credentials** (Credentials) - Required - The credentials to use for initializing the repository.
- **key_opts** (KeyOptions) - Required - Options for creating the encryption key.
- **config_opts** (ConfigOptions) - Required - Options for configuring the repository.

### Request Example
```json
{
  "credentials": {
    "type": "Password",
    "value": "your_password"
  },
  "key_opts": {
    "bits": 256,
    "rounds": 100000
  },
  "config_opts": {
    "version": 2,
    "chunker_poly": "some_polynomial_value"
  }
}
```

### Response
#### Success Response (200)
- **key** (Key) - The encryption key for the repository.
- **key_id** (Option<KeyId>) - The ID of the encryption key, if applicable.
- **config_file** (ConfigFile) - The generated configuration file.

#### Response Example
```json
{
  "key": "encrypted_key_data",
  "key_id": "key_identifier_if_any",
  "config_file": {
    "version": 2,
    "repository_id": "repo_uuid",
    "chunker_polynomial": "polynomial_data",
    "is_hot": true
  }
}
```
```

--------------------------------

### GET /snapshot/id

Source: https://docs.rs/rustic_core/latest/rustic_core/repofile/snapshotfile/struct.SnapshotFile.html

Retrieves a snapshot file by its ID or partial ID.

```APIDOC
## GET /snapshot/id

### Description
Get a `SnapshotFile` from the backend by (part of the) id.

### Parameters
#### Request Body
- **be** (DecryptReadBackend) - Required - The backend to use
- **id** (str) - Required - The (part of the) id of the snapshot

### Response
#### Success Response (200)
- **SnapshotFile** (Object) - The requested snapshot file

### Errors
- If the string is not a valid hexadecimal string
- If no id could be found
- If the id is not unique
```

--------------------------------

### Create New Repository (With Progress Bars)

Source: https://docs.rs/rustic_core/latest/rustic_core/struct.Repository.html

Initializes a new Repository instance with specified options, backends, and a progress bar implementation. This method is generic over the progress bar type `P`. Errors are similar to the `new` method.

```rust
pub fn new_with_progress<P: ProgressBars>( opts: &RepositoryOptions,
 backends: &RepositoryBackends,
 pb: P,
 ) -> RusticResult<Self>
```

--------------------------------

### Get Length of PruneIndex

Source: https://docs.rs/rustic_core/latest/rustic_core/commands/prune/struct.PruneIndex.html

Returns the number of packs within the PruneIndex.

```rust
fn len(&self) -> usize
```

--------------------------------

### ContentStartpoints Methods

Source: https://docs.rs/rustic_core/latest/rustic_core/vfs/struct.ContentStartpoints.html

Methods for initializing and using ContentStartpoints to calculate offsets.

```APIDOC
## ContentStartpoints Methods

### Description
Provides methods to create a ContentStartpoints instance from sizes and compute specific start offsets.

### Methods
- **from_sizes(sizes: impl IntoIterator<Item = RusticResult<usize>>) -> RusticResult<Self>**
  - Creates a new ContentStartpoints instance from an iterator of sizes.
- **compute_start(&self, offset: usize) -> (usize, usize)**
  - Computes the start point for a given offset.
```

--------------------------------

### Get Repository Backend

Source: https://docs.rs/rustic_core/latest/rustic_core/backend/struct.RepositoryBackends.html

Retrieves the main repository backend from RepositoryBackends.

```rust
pub fn repository(&self) -> Arc<dyn WriteBackend>
```

--------------------------------

### Any::type_id Method

Source: https://docs.rs/rustic_core/latest/rustic_core/archiver/struct.Archiver.html

Gets the `TypeId` of `self`. This is a blanket implementation for any type `T`.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### Repository Initialization

Source: https://docs.rs/rustic_core/latest/rustic_core/struct.Repository.html

Methods for creating and initializing a new repository instance.

```APIDOC
## POST /repository/new

### Description
Creates a new repository instance from provided options and backends without progress bars.

### Method
POST

### Parameters
#### Request Body
- **opts** (RepositoryOptions) - Required - The options to use for the repository
- **backends** (RepositoryBackends) - Required - The backends to create/access a repository on

### Response
#### Success Response (200)
- **Repository** (Object) - The initialized repository instance

---

## POST /repository/new_with_progress

### Description
Creates a new repository instance with support for progress bars.

### Method
POST

### Parameters
#### Request Body
- **opts** (RepositoryOptions) - Required - The options to use for the repository
- **backends** (RepositoryBackends) - Required - The backends to create/access a repository on
- **pb** (ProgressBars) - Required - The progress bars to use
```
Tokens:
Raw