Struct DehydratedDevices 

pub struct DehydratedDevices { /* private fields */ }

Available on crate feature e2e-encryption only.

High-level handle returned by Encryption::dehydrated_devices.

Implementations

impl DehydratedDevices

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

Subscribe to the stream of DehydratedDeviceEvents.

Each call returns a fresh stream. If a subscriber is slow enough to fall behind the channel’s buffer, it receives a BroadcastStreamRecvError reporting the number of skipped events and the stream continues from the most recent event.

Example

let dehydrated = client.encryption().dehydrated_devices();
let mut stream = dehydrated.state_stream();
while let Some(Ok(event)) = stream.next().await {
    println!("dehydrated devices: {event:?}");
}

pub async fn is_supported(&self) -> Result<bool, DehydratedDeviceError>

Return whether the homeserver advertises dehydrated-device support.

Probes by issuing GET /dehydrated_device and inspecting the errcode of the response:

• M_UNRECOGNIZED means the server does not understand the endpoint.
• M_NOT_FOUND or a successful response means the server understands the endpoint (whether or not the user currently has a dehydrated device on file).

Any other transport or API failure is propagated.

pub async fn create( &self, display_name: Option<&str>, pickle_key: &DehydratedDeviceKey, ) -> Result<OwnedDeviceId, DehydratedDeviceError>

Create a fresh dehydrated device and upload it to the homeserver.

The pickle key is used by vodozemac to encrypt the private parts of the device. The application is responsible for safely storing the pickle key (typically in Secret Storage so future sessions can rehydrate the device).

Arguments

• display_name - Optional human-readable name uploaded as the dehydrated device’s initial_device_display_name. Defaults to "Dehydrated device".
• pickle_key - 32-byte key used to encrypt the dehydrated device.

Example

let pickle_key = DehydratedDeviceKey::new();
let device_id = client
    .encryption()
    .dehydrated_devices()
    .create(Some("Offline catcher"), &pickle_key)
    .await?;
println!("Uploaded dehydrated device {device_id}");

pub async fn rehydrate( &self, pickle_key: &DehydratedDeviceKey, ) -> Result<bool, DehydratedDeviceError>

Rehydrate the dehydrated device currently on the server, if any.

Downloads the dehydrated device, decrypts it with pickle_key, drains all queued to-device events to import their room keys, and finally deletes the device from the server.

Returns Ok(false) if the server reports no dehydrated device (M_NOT_FOUND) or does not implement the endpoint (M_UNRECOGNIZED). Returns Ok(true) once the rehydration cycle has completed end to end.

If the drain stops defensively before the server’s queue is exhausted, the device is left on the server and DehydratedDeviceError::DrainTruncated is returned. Calling this method again restarts the drain from the beginning of the queue; room keys imported by the earlier attempt import idempotently.

Example

let rehydrated =
    client.encryption().dehydrated_devices().rehydrate(&pickle_key).await?;
if rehydrated {
    println!("Caught up on offline room keys");
}

pub async fn is_key_stored( &self, secret_store: &SecretStore, ) -> Result<bool, DehydratedDeviceError>

Return whether the pickle key is stored in the given Secret Storage.

The key is looked up by the account-data event type org.matrix.msc3814 (the unstable name reserved by MSC3814).

Example

let stored =
    client.encryption().dehydrated_devices().is_key_stored(&store).await?;

pub async fn reset_key( &self, secret_store: &SecretStore, ) -> Result<DehydratedDeviceKey, DehydratedDeviceError>

Generate a new random pickle key, persist it in Secret Storage, and cache it in the local crypto store.

The previous key (if any) is overwritten in both places. Any dehydrated device that was encrypted with the previous key becomes unrehydratable until rotated.

Example

let fresh_key =
    client.encryption().dehydrated_devices().reset_key(&store).await?;

pub fn start<'a>( &'a self, secret_store: &'a SecretStore, ) -> StartDehydration<'a>

Start using dehydrated devices for this client.

Returns a StartDehydration future. Await it directly for the default behavior, or configure it first with StartDehydration::create_new_key, StartDehydration::skip_rehydration, and StartDehydration::only_if_key_cached.

The caller is expected to have unlocked Secret Storage and bootstrapped cross-signing before this call; otherwise the underlying account-data reads and writes will fail mid-flight.

Awaiting the future performs the following steps:

1. If StartDehydration::only_if_key_cached was set, return early when no pickle key is cached locally.
2. Stop any previously scheduled rotation.
3. Unless StartDehydration::skip_rehydration was set, attempt to rehydrate the existing dehydrated device. Failures are logged and emitted as DehydratedDeviceEvent::RehydrationError but do not abort the start.
4. If StartDehydration::create_new_key was set and the rehydration step succeeded (or was skipped), replace the pickle key in Secret Storage with a fresh random one. A failed rehydration suppresses the reset so the stored key can still recover the existing dehydrated device on another client.
5. Create a new dehydrated device now and schedule rotation once a week.

The rotation task resolves the pickle key from the local crypto store on each tick. The local cache is the only key source available to the task because reopening Secret Storage requires the recovery key, which is not retained. Per-tick failures emit DehydratedDeviceEvent::RotationError without aborting the schedule.

Example

client.encryption().dehydrated_devices().start(&store).await?;

pub fn stop(&self)

Stop the scheduled dehydrated-device rotation, if any.

Has no effect when no rotation is scheduled. Existing dehydrated devices on the server are left in place; pair with Self::delete to clean those up.

pub async fn delete(&self) -> Result<(), DehydratedDeviceError>

Delete the current dehydrated device, if one exists.

Also stops any scheduled rotation, so the next tick will not immediately recreate the device the caller just asked to remove.

Returns Ok(()) silently if no dehydrated device is on the server or the server does not implement the endpoint.

Example

client.encryption().dehydrated_devices().delete().await?;

Trait Implementations

impl Clone for DehydratedDevices

fn clone(&self) -> DehydratedDevices

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for DehydratedDevices

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

Formats the value using the given formatter.