Struct Backups

pub struct Backups { /* private fields */ }

Available on crate feature e2e-encryption only.

The backups manager for the Client.

Implementations

impl Backups

pub async fn create(&self) -> Result<(), Error>

Create a new backup version, encrypted with a new backup recovery key.

The backup recovery key will be persisted locally and shared with trusted devices as m.secret.send to-device messages.

After the backup has been created, all room keys will be uploaded to the homeserver.

Warning: This will overwrite any existing backup.

Examples

let backups = client.encryption().backups();
backups.create().await?;

assert_eq!(backups.state(), BackupState::Enabled);

pub async fn disable(&self) -> Result<(), Error>

Disable and delete the currently active backup only if previously enabled before, otherwise an error will be returned.

For a more aggressive variant see Backups::disable_and_delete which will delete the remote backup without checking the local state.

Examples

let backups = client.encryption().backups();
backups.disable().await?;

assert_eq!(backups.state(), BackupState::Unknown);

pub async fn disable_and_delete(&self) -> Result<(), Error>

Completely disable and delete the active backup both locally and from the backend no matter if previously setup locally or not.

⚠️ This method is mainly used when resetting the crypto identity and for most other use cases its safer Backups::disable counterpart should be used.

It will fetch the current backup version from the backend and delete it before proceeding to disabling local backups as well

Examples

let backups = client.encryption().backups();
backups.disable_and_delete().await?;

assert_eq!(backups.state(), BackupState::Unknown);

pub fn wait_for_steady_state(&self) -> WaitForSteadyState<'_>

Returns a future to wait for room keys to be uploaded.

Awaiting the future will wake up a task to upload room keys which have not yet been uploaded to the homeserver. It will then wait for the task to finish uploading.

Examples

use futures_util::StreamExt;

let backups = client.encryption().backups();
let wait_for_steady_state = backups.wait_for_steady_state();

let mut progress_stream = wait_for_steady_state.subscribe_to_progress();

tokio::spawn(async move {
    while let Some(update) = progress_stream.next().await {
        let Ok(update) = update else { break };

        match update {
            UploadState::Uploading(counts) => {
                println!(
                    "Uploaded {} out of {} room keys.",
                    counts.backed_up, counts.total
                );
            }
            UploadState::Error => break,
            UploadState::Done => break,
            _ => (),
        }
    }
});

wait_for_steady_state.await?;

pub fn state_stream( &self, ) -> impl Stream<Item = Result<BackupState, BroadcastStreamRecvError>>

Get a stream of updates to the BackupState.

This method will send out the current state as the first update.

Examples

use futures_util::StreamExt;

let backups = client.encryption().backups();

let mut state_stream = backups.state_stream();

while let Some(update) = state_stream.next().await {
    let Ok(update) = update else { break };

    match update {
        BackupState::Enabled => {
            println!("Backups have been enabled");
        }
        _ => (),
    }
}

pub fn state(&self) -> BackupState

Get the current BackupState for this Client.

pub async fn are_enabled(&self) -> bool

Are backups enabled for the current Client?

This method will check if we locally have an active backup key and backup version and are ready to upload room keys to a backup.

pub async fn fetch_exists_on_server(&self) -> Result<bool, Error>

Does a backup exist on the server?

This method will request info about the current backup from the homeserver and if a backup exists return true, otherwise false.

pub async fn exists_on_server(&self) -> Result<bool, Error>

Does a backup exist on the server?

This method is identical to Self::fetch_exists_on_server except that we cache the latest answer in memory and only empty the cache if the local device adds or deletes a backup itself.

Do not use this method if you need an accurate answer about whether a backup exists - instead use Self::fetch_exists_on_server. This method is useful when performance is more important than guaranteed accuracy, such as when classifying UTDs.

pub fn room_keys_for_room_stream( &self, room_id: &RoomId, ) -> impl Stream<Item = Result<BTreeMap<String, BTreeSet<String>>, BroadcastStreamRecvError>>

Subscribe to a stream that notifies when a room key for the specified room is downloaded from the key backup.

pub async fn download_room_keys_for_room( &self, room_id: &RoomId, ) -> Result<(), Error>

Download all room keys for a certain room from the server-side key backup.

pub async fn download_room_key( &self, room_id: &RoomId, session_id: &str, ) -> Result<bool, Error>

Download a single room key from the server-side key backup.

Returns true if we managed to download a room key, false or an error if we failed to download it. false indicates that there was no error, we just don’t have backups enabled so we can’t download a room key.

Trait Implementations

impl Clone for Backups

fn clone(&self) -> Backups

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Backups

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

Formats the value using the given formatter.