macltok

public

Star0

Fork 0

Watch0

3 commits 3 branches 0 tags 0 releases3.0 MiB

Commit `31ce2453c82f`

tarball

atagen <boss@atagen.co>2026-09-24 23:43 UTC

32 files changed+5086-6553

engine: answer every command directly and keep the event stream for state

Correlating CommandIds against a shared stream made every client rebuild request and response, and a web backend could not serve media bytes per request at all. Each Command now carries a Responder, and dropping one answers Interrupted, so panics, closed rooms and shutdown need no bookkeeping. Media, profiles and space hierarchies became handle queries, and RoomSummary grew the fields a room list needs, so Malice needs no direct matrix-sdk. One cloneable Error replaces the four error types.

Modified file: Cargo.toml+1−1

@@ -11,7 +11,7 @@ sqlite = ["matrix-sdk/sqlite", "serde", "dep:url"]

1111 bundled-sqlite = ["sqlite", "matrix-sdk/bundled-sqlite"]

1212

1313 [dependencies]

14-futures-util = { version = "0.3.31", default-features = false }

14+futures-util = { version = "0.3.31", default-features = false, features = ["std"] }

1515 http = "1"

1616 matrix-sdk = { version = "0.18.0", default-features = false, features = ["e2e-encryption"] }

1717 matrix-sdk-crypto = { version = "0.18.0", default-features = false }

Modified file: README.md+10 additions−10 deletions@@ -21,16 +21,16 @@ already have remote event IDs.
 
 ## Consuming the engine
 
-Run `Engine::run` and drain its single `EventStream` independently of command
-submission. `ClientHandle::send` returns an enqueue ID; match that ID against
-`CommandSucceeded`, `CommandSucceededWithRoom`, or `CommandFailed` before
-reporting completion. A successful message command only enters the SDK send
-queue; the timeline item's send state reports subsequent network delivery.
-
-Start a timeline from `TimelineReset`, then apply `TimelineChanged` diffs with
-`TimelineDiff::try_apply`. If a diff does not match the current snapshot, stop
-applying diffs for that timeline and send `TimelineCommand::Resync`. Resume only
-after its fresh `TimelineReset`; the reset precedes the command completion.
+spawn `Engine::run`, drain the `EventStream` from its own task, and talk to the
+engine through `ClientHandle`. every command answers once, awaited
+(`handle.send_message(..).await?`) or as a `Pending` you can await later or
+drop. a sent message answers when the sdk send queue has it, delivery shows up
+as the timeline item's send state. reads like `rooms`, `members` and `media`
+go straight to the sdk. the stream only carries state
+
+start a timeline from `TimelineReset`, then apply `TimelineChanged` diffs with
+`TimelineDiff::try_apply`. when one doesn't fit, stop applying, call `resync`,
+and pick up from the next `TimelineReset`
 
 With `sqlite`, persist the initial `Session::record()` separately from its
 encrypted SQLite store. On `SessionTokensChanged`, obtain a new record from

Modified file: docs/design-decisions.md+137 additions−170 deletions@@ -1,172 +1,139 @@
 # macltok design decisions
 
-This document describes the contract implemented in the working tree.
-
-## Engine execution
-
-The engine keeps a contextual task registry. Every spawned task is registered
-with either its command id and kind, a watcher name, or a room id and
-generation. The run loop continuously joins completed tasks and removes their
-context. A command-task panic produces its correlated `CommandFailed` event.
-A watcher or current room-actor panic is terminal to the engine. Shutdown aborts
-and joins the remaining registered tasks.
-
-The engine emits `Authenticated`, then `ConnectionChanged(Connecting)`, before
-starting the sync service. `ConnectionChanged` also represents the later SDK
-states and the final `Stopped` transition. `Engine::run` returns an
-`EngineError` for terminal failure and emits `Failed` before `Stopped` when the
-event stream remains available.
-
-The driver command channel remains lossless and clients must drain
-`EventStream` independently of command submission. `ClientHandle` also exposes
-a `watch` receiver for the current connection state. `RoomsChanged` is an
-invalidation event. Call `ClientHandle::rooms` for current, normalised room
-summaries.
-
-`ClientHandle` sends `Command` values and receives a `CommandId`. Completion is
-reported as `CommandSucceeded`, `CommandSucceededWithRoom`, or
-`CommandFailed`. `CommandFailure` contains the id, outer `CommandKind`, typed
-`CommandErrorKind`, and display message. Direct request and response methods
-return `CommandResultError`, which is either a delivered `CommandFailure` or a
-closed reply channel.
-
-For timeline sends, success means the SDK send queue accepted the event;
-network delivery is reported later through timeline send state.
-
-`send` reports enqueueing, not completion. Consumers retain the returned id
-until a terminal result with that id arrives; they match `CommandFailure::kind`
-rather than parsing its display message. The event stream must be drained while
-commands are submitted, even when several frontend clients share one engine.
-
-## Room lifetime and ordering
-
-An open room has an explicit generation and exactly one of three states.
-
-- `Opening` owns the generation and actor request sender
-- `Open` owns the generation and actor request sender
-- `Closing` owns the generation and a bounded FIFO of deferred open and close commands
-
-An `Open` command starts an actor immediately and returns its terminal result
-only after the actor reports readiness. There is no separate readiness waiter or
-readiness task. Repeated opens while opening are retained by the actor and each
-gets one terminal result. A close changes the room to `Closing`, rejects work
-that needs an open actor, and waits for that generation to exit. Opens and
-closes during closing are queued in order; after exit, each deferred command is
-replayed, with a fresh generation started when needed. Events from earlier
-generations are ignored.
-
-Each room actor serialises its timeline work in FIFO order. Different rooms run
-concurrently. Room mutations which do not require an open timeline use a
-separate keyed FIFO scheduler. Jobs with the same room, target, or direct-chat
-key run in submission order while unrelated keys run concurrently. Notification
-commands and encryption commands each have one dedicated serial worker. The
-encryption worker owns the verification controller and cancels it before
-shutdown completes.
-
-Pagination has a per-timeline mutex gate and a session-owned completion path.
-Pagination tasks are reaped as they finish. Closing a timeline aborts its
-pagination work and emits one terminal result for every still-pending command.
-There is no public pagination handle. The internal result channel is only the
-session completion mechanism and is not an engine-wide routing design.
-
-`TimelineDiff::try_apply` rejects indices that do not match the consumer's
-snapshot without modifying that snapshot. A consumer then stops applying diffs
-for that timeline and sends `TimelineCommand::Resync`. The timeline session
-aborts and joins its old watcher, atomically subscribes to a fresh SDK snapshot
-and diff stream, and emits `TimelineReset` before the resync command succeeds.
-This works for rooms and threads without closing their timelines or pagination.
-
-Timeline diffs and resets carry `TimelineId`, which distinguishes a room from a
-thread by its root event. Thread actors and pagination state belong to the room
-actor. Stateful timeline commands require the room actor. Standalone room
-commands such as typing, receipts, send-queue control, membership actions, and
-moderation use the SDK `Room` directly.
-
-## Account construction and secrets
-
-`Session::login_password`, `Session::begin_oauth`, and `Session::restore` use
-one shared account client builder. It configures encrypted SQLite storage,
-encryption settings, refresh-token handling, and enabled threading without
-thread subscriptions. `Session::build` passes the authenticated client to the
-engine.
-
-Secret-bearing input types do not derive `Clone`. The store passphrase is
-borrowed by the shared builder, password login passes its password by reference,
-and authentication records are cloned only where SDK ownership requires it.
-
-The caller owns durable authentication records. Save `Session::record()` after
-login, then consume `SessionTokensChanged` and atomically replace that saved
-record with `ClientHandle::session_record()`. A previously captured record may
-hold an exhausted refresh token; failing to persist a rotation must be surfaced
-rather than silently treating the stale record as safe to restore. Restore with
-the same `StoreConfig` path and passphrase. logout and a rejected token both
-stop the engine. logout and a hard rejection kill the record and the store, a
-soft logout keeps the store for a same-device login, `Stopped` alone kills
-nothing. Neither cookies nor application-specific secret storage belong in the
-toolkit.
-
-## Notifications and room data
-
-The notification client is constructed lazily in an `OnceCell` and shares the
-engine sync service. It is created only when notification resolution is first
-requested. `PushNotification` exposes typed room and sender metadata and a
-typed `PushNotificationEvent`. The event is `Raw<AnySyncTimelineEvent>` for a
-timeline notification or `Raw<StrippedRoomMemberEvent>` for an invite. SDK UI
-types do not cross the public boundary.
-
-Room summaries are normalised once per `rooms` query. `ClientHandle::rooms_filtered`
-normalises its name search term once before filtering. Summary generation runs
-display-name requests with bounded concurrency. Sorting is descending latest
-event timestamp, then case-insensitive name, then room id as a deterministic tie
-break.
-
-Global and room account data retain typed Matrix event-type parameters and raw
-event content. The handle offers direct raw reads and engine-backed raw writes.
-
-## Commands and errors
-
-`Command` is grouped into `Account`, `Room`, `Timeline`, `Media`,
-`Encryption`, `Notification`, and `Lifecycle` domains. `CommandKind` identifies
-the outer domain in result events.
-
-`RoomCommand::InviteUser` contains only room and user ids. It deliberately does
-not expose a reason because the SDK invite helper accepts none. Kick, ban, and
-unban retain optional reasons where the protocol supports them.
-
-`TimelineCommand::Edit` accepts `MessageEditContent`. Its `Text` and `Emote`
-variants carry `RichText`, so edited text and emotes preserve plain text,
-optional Matrix HTML, and mentions. Empty edited bodies fail with `EmptyBody`.
-
-`VerificationAction` contains `Confirm`, `Reject`, and `Cancel`. Starting a
-verification is a target-bearing encryption command rather than an action.
-Verification progress uses `Waiting`, `Comparison`, `Confirmed`, `Done`,
-`Cancelled`, and typed `Failed(VerificationFailure)`. Request acceptance, SAS
-startup and acceptance failures retain their message, while stream termination
-has dedicated variants. A cancelled verification can be started again.
-The watcher and action paths claim terminal emission so a racing cancellation
-cannot replace `Done` with a local `Cancelled` event.
-
-`CommandErrorKind` is the stable typed failure category. It includes room and
-timeline availability, queue pressure, validation, media, verification,
-authentication, network, server, store, timeline, encryption, and fallback
-categories. The rendered message preserves operation context while internal
-errors retain their source chains.
-
-## Power levels
-
-Power-level reads return the complete local `RoomPowerLevels` mapping.
-`PowerLevelChanges` applies selected common and well-known event thresholds,
-and `SetUserPowerLevel` changes one user mapping.
-
-The SDK trait that applies a power-level event is crate-private. macltok keeps
-an atomic local mapping, applies all requested changes to it, and sends one
-state event. It does not patch upstream and does not send separate events for
-individual fields.
-
-## Public model boundaries
-
-The public model uses owned ruma identifiers and typed data wherever it has a
-stable representation. Raw Matrix event payloads remain `Raw` where arbitrary
-event content must be preserved. Public output models are non-exhaustive where
-they are expected to grow. SDK clients remain available through the handle for
-direct state queries that do not need engine coordination.
+the contract the working tree actually implements. if the code disagrees with
+this, one of them is lying and it should be fixed
+
+## two ways in, one way out
+
+state changes are commands. `ClientHandle::send` queues one and hands back a
+`Pending`, `execute` queues and waits, and there's an awaited convenience method
+for every command. each command answers exactly once with
+`Result<CommandOutput, Error>`. drop the `Pending` if you don't care, the
+command still runs
+
+pure reads skip the engine and ask the sdk directly through the handle. rooms,
+members, power levels, account data, devices, push notification resolution,
+and media bytes all live here
+
+the event stream carries state and only state. timelines, history, typing,
+rooms, connection, encryption, verification, upload progress, session. no
+command results ride on it. drain it from its own task, it's bounded and the
+engine waits for you
+
+one error type for everything, `Error { kind, message, challenge }`. match on
+`kind`. `Interrupted` means the engine stopped, the room closed, or the task
+doing the work died before it could answer. `challenge` turns up with
+`InteractiveAuthRequired`
+
+## engine
+
+the run loop routes and does nothing slow. every task it spawns is registered
+with a context. a command task that panics costs its caller an `Interrupted`
+and gets logged. a watcher or a room actor that panics takes the engine down,
+emitting `Failed` then `Stopped`
+
+sync restarts itself with backoff after an error or an unexpected stop, and
+`ConnectionChanged` shows `Offline` meanwhile. every return to `Online` re-arms
+the send queues, since the sdk parks a room's queue on any send failure and
+never unparks it. a recoverable failure while online gets the room another go
+after a few seconds
+
+logout and a rejected token both stop the engine. `Shutdown` answers once
+`Stopped` has gone out
+
+## rooms
+
+one actor per open room. the engine holds a slot per room, `Active` with a
+sender or `Closing` with a fifo of opens and closes that arrived while it wound
+down. those replay in order once the actor exits. a room you leave, or get
+kicked or banned from, closes itself
+
+opening sends `TimelineReset` on the stream before it answers. opening an
+already open room sends a fresh reset, so a second frontend gets a snapshot
+
+sends, edits and replies run on the actor in order, so they reach the send
+queue in the order they were asked for. redactions, reactions and read
+receipts are network calls, so they run beside the actor and a slow one
+doesn't queue the room behind it. closing lets them finish rather than lie
+
+threads belong to their room's actor. commands for a thread that's still
+opening wait behind the open, up to the actor's queue capacity
+
+pagination runs one request at a time per timeline and emits `HistoryChanged`
+around each. the sdk remembers where history starts, we don't, because a gappy
+sync can unload it again
+
+every task inside an actor is supervised, and a panic in any of them panics the
+actor
+
+## timelines
+
+`TimelineDiff::try_apply` refuses a diff whose indices don't fit your snapshot
+and leaves the snapshot alone. stop applying, `resync`, and carry on from the
+next `TimelineReset`. resync kills the old watcher before the new reset goes
+out, so no stale diff can land after it
+
+`TimelineId` tells a room from a thread by its root event
+
+## mutations
+
+membership, moderation, power levels, room creation and account data writes go
+through one keyed fifo scheduler. same room, same alias, same dm partner or
+same account data type run in order, everything else runs at once.
+`create_direct` hands back the existing dm when there is one
+
+notifications and encryption each get one serial worker. the encryption worker
+owns the verification controller outright
+
+power level changes build one state event from the local mapping, since the
+sdk's own patcher is private
+
+## media
+
+media is a read. `ClientHandle::media` takes a `MediaId` a retained timeline
+handed you, `mxc_media` takes any plain mxc uri. both share one bounded
+download path with the byte cap the sdk's own download lacks, and
+concurrent asks for the same bytes share one flight
+
+the cache holds plaintext, keyed like the sdk keys it, so the sdk and macltok
+can read each other's entries. that's how your own encrypted uploads come back
+
+media ids are registered as timelines render and forgotten when their timeline
+closes, least recently seen first once the cap is hit
+
+uploads are commands that answer once the send queue has them. progress and
+failure arrive as events from one watcher on the sdk's global send queue
+
+## sessions and secrets
+
+`Session::login_password`, `begin_oauth` and `restore` share one client builder
+with encrypted sqlite, refresh tokens and threads. secret-bearing inputs don't
+derive `Clone`
+
+the caller owns the saved record. save `Session::record()` after login and
+replace it atomically with `ClientHandle::session_record()` on every
+`SessionTokensChanged`. logout and a hard rejection kill the record and the
+store. a soft logout keeps the store for a same-device login, or the e2ee keys
+go with it. a bare `Stopped` kills nothing. one store directory per login
+
+## notifications and room data
+
+the notification client is built lazily and shares the engine's sync service.
+sdk ui types stay behind the boundary
+
+`rooms` normalises on demand with bounded concurrency and sorts by latest event,
+then name, then id. `RoomsChanged` is an invalidation, coalesced so one sync
+touching fifty rooms is one event
+
+## verification
+
+`Confirm`, `Reject` and `Cancel`. reject tells the other side the emoji didn't
+match. the watcher and the action paths claim the terminal event, so a racing
+cancel can't turn `Done` into `Cancelled`
+
+## public model
+
+owned ruma ids and typed data wherever there's a stable shape, `Raw` where
+arbitrary content has to survive. anything expected to grow is
+`#[non_exhaustive]`. `Engine::from_client` stays public for people who built
+their own client

Modified file: docs/review-2026-09-24.md+13 additions−11 deletions@@ -68,7 +68,7 @@ ciphertext as if it were the image. The media tests force plaintext rooms
 Fix direction. Cache plaintext, matching the SDK, and keep the byte bound by
 decrypting in a streaming fashion before the write.
 
-### C5. Media single-flight is poisoned by a leader panic. folded into the media query rewrite under q1
+### C5. Media single-flight is poisoned by a leader panic. done, shared-future single flight in the media query
 
 In `spawn_media_fetch` (`src/engine.rs:1870-1911`) followers push their id and
 return at once, trusting the leader to answer for them. If `fetch_media`
@@ -132,7 +132,7 @@ Fix direction. When the room is open, route through the actor and use
 already talk to creates a duplicate every time. `Client::get_dm_room` exists
 for the lookup (`client/mod.rs:1852`).
 
-### C11. Unregistered tasks swallow panics, contradicting the design doc. folded into q1 and the actor restructure
+### C11. Unregistered tasks swallow panics, contradicting the design doc. done, command tasks answer `Interrupted`, actor internals are supervised and panic the actor
 
 The design doc says a watcher panic is terminal. But the timeline watcher
 (`src/engine.rs:589`), pagination worker (`446`), pagination result task
@@ -161,7 +161,7 @@ loaded in a room that is still open are the first evicted, and fetching them
 then fails with `MediaUnknown`. Closed timelines never release their entries,
 so they compete with open ones.
 
-### C14. Smaller correctness issues. mostly done. `open_room` on an open room waits for q1 snapshots, the lagged watcher stays as is
+### C14. Smaller correctness issues. done, bar the lagged session watcher which stays as is
 
 - `CommandResultError::Failed` renders its `Display` through `Debug`
   (`src/transport.rs:840`), so users see a struct dump.
@@ -185,7 +185,7 @@ so they compete with open ones.
 
 ## A. API shape and client-builder friendliness
 
-### A1. Three completion mechanisms, and the useful one is rationed. OPEN
+### A1. Three completion mechanisms, and the useful one is rationed. done, one awaited path and one error type
 
 A client must know which of three patterns each operation uses.
 
@@ -202,7 +202,7 @@ The headless example is mostly bookkeeping of ids. Malice gap 4 comes straight
 from this. The one pattern a web backend can use, an awaited result per
 request, is not offered for most operations.
 
-### A2. Pure reads modelled as commands, against the doc's own rule. OPEN
+### A2. Pure reads modelled as commands, against the doc's own rule. done, `media` and `mxc_media` are handle queries
 
 The design doc says operations are split by whether they change state. Media
 fetch changes no state, yet it is a `MediaCommand` whose bytes arrive as a
@@ -210,7 +210,7 @@ fetch changes no state, yet it is a `MediaCommand` whose bytes arrive as a
 other frontend's image bytes, up to 20 MiB each, and the requester has to
 filter by `MediaId`.
 
-### A3. Every timeline item is a `Message`, with presentation strings in `body`. OPEN
+### A3. Every timeline item is a `Message`, with presentation strings in `body`. open, q3
 
 `normalise_timeline_item` (`src/normalise/timeline.rs`) flattens every event
 into `TimelineMessage`. The consequences for a client are these.
@@ -235,7 +235,7 @@ This needs a content enum, for example `Message { msgtype, ... }`, `Redacted`,
 `UnableToDecrypt`, `Membership`, `ProfileChange`, `RoomState`, `Poll` and
 `Other { event_type }`. It is the largest single rendering gap.
 
-### A4. Timeline commands cannot target local echoes. OPEN
+### A4. Timeline commands cannot target local echoes. open, lands with q3
 
 `Edit`, `Redact` and `ToggleReaction` take an `OwnedEventId` and wrap it in
 `TimelineEventItemId::EventId`. The SDK accepts transaction ids for all three,
@@ -243,13 +243,13 @@ but a client cannot edit, redact or react to a message it sent until the
 server echo arrives. The commands should take the identifier that the model
 already exposes.
 
-### A5. `RoomSummary` is too thin for a room list. OPEN
+### A5. `RoomSummary` is too thin for a room list. open, lands with the malice queries and q2
 
 Missing fields, all cheap SDK reads. Topic, canonical alias, joined and invited
 member counts, heroes, tombstone and successor, inviter for invites, a latest
 event preview, and space parents and children (Malice gap 3).
 
-### A6. No incoming verification. OPEN
+### A6. No incoming verification. open
 
 Only outgoing `StartVerification` exists. A request started from another
 device, which is the normal "verify this new login" flow, is never observed.
@@ -257,7 +257,7 @@ macltok registers no handler for it, and the SDK has no stream, so the app
 pattern is an event handler plus `Encryption::get_verification_request`
 (`encryption/mod.rs:1060`).
 
-### A7. Missing `#[non_exhaustive]`. OPEN
+### A7. Missing `#[non_exhaustive]`. done
 
 Adding the attribute later is itself a breaking change, so it belongs now. Output types that will
 grow are `TimelineItem`, `CommandKind`, `RoomMembership`, `VerificationState`,
@@ -265,7 +265,7 @@ grow are `TimelineItem`, `CommandKind`, `RoomMembership`, `VerificationState`,
 grow need a constructor plus `#[non_exhaustive]`. These are
 `CreateRoomOptions`, `PasswordLogin`, `OAuthLogin` and `UploadThumbnail`.
 
-### A8. Smaller API issues. OPEN
+### A8. Smaller API issues. mostly done. `HistoryState::Failed(String)`, stringly power level events and fixed encryption defaults remain
 
 - `MediaCommand::Upload` duplicates `UploadAttachment`, and the handle exposes
   both `upload_media` and `upload_attachment`.
@@ -284,6 +284,8 @@ grow need a constructor plus `#[non_exhaustive]`. These are
 
 ## D. Duplication and antipatterns
 
+mostly done by the engine split. the actor thread registry, one spawn helper, one responder, one media request path, one test support module. `get_room` lookups went from twenty one hand rolled errors to a helper per module
+
 Line references are from the mechanical inventory taken during this review.
 
 - `RoomActor::run` is about 700 lines. The "queue while the thread is opening,

Modified file: examples/headless.rs+54 additions−54 deletions@@ -1,76 +1,69 @@
 use macltok::{
-    Command, CommandKind, EngineConfig, Event, LifecycleCommand, PasswordLogin, RoomCommand,
-    RoomMembership, Session, StoreConfig, TimelineCommand,
+    EngineConfig, Event, PasswordLogin, RoomMembership, Session, StoreConfig, TimelineId,
+    TimelineItem,
 };
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let homeserver = required("MATRIX_HOMESERVER")?;
-    let username = required("MATRIX_USERNAME")?;
-    let password = required("MATRIX_PASSWORD")?;
-    let store_path = required("MATRIX_STORE_PATH")?;
-    let store_passphrase = required("MATRIX_STORE_PASSPHRASE")?;
     let session = Session::login_password(
-        PasswordLogin {
-            homeserver,
-            username,
-            password,
-            device_display_name: Some("macltok headless example".into()),
-            device_id: None,
-        },
-        StoreConfig::new(store_path, store_passphrase),
+        PasswordLogin::new(
+            required("MATRIX_HOMESERVER")?,
+            required("MATRIX_USERNAME")?,
+            required("MATRIX_PASSWORD")?,
+        )
+        .with_device_display_name("macltok headless example"),
+        StoreConfig::new(
+            required("MATRIX_STORE_PATH")?,
+            required("MATRIX_STORE_PASSPHRASE")?,
+        ),
     )
     .await?;
     let (engine, handle, mut events) = session.build(EngineConfig::default()).await?;
     let running = tokio::spawn(engine.run());
-    let mut room_open_id = None;
-    let mut resync_id = None;
-    let mut timeline_items = Vec::new();
+    let mut opened: Option<TimelineId> = None;
+    let mut items = Vec::new();
+    let mut stale = false;
 
     loop {
         tokio::select! {
             event = events.recv() => {
-                let Some(event) = event else { break; };
+                let Some(event) = event else { break };
                 match event {
-                    Event::RoomsChanged if room_open_id.is_none() => {
-                        if let Some(room) = handle
+                    Event::RoomsChanged if opened.is_none() => {
+                        let Some(room) = handle
                             .rooms()
                             .await
                             .into_iter()
                             .find(|room| room.membership == RoomMembership::Joined)
-                        {
-                            room_open_id = Some(handle
-                                .send(Command::Room(RoomCommand::Open(room.room_id)))
-                                .await?);
-                        }
+                        else {
+                            continue;
+                        };
+                        opened = Some(room.room_id.clone().into());
+                        // answers arrive on their own, the event loop keeps draining meanwhile
+                        let handle = handle.clone();
+                        tokio::spawn(async move {
+                            if let Err(error) = handle.open_room(room.room_id).await {
+                                eprintln!("could not open {error}");
+                            }
+                        });
                     }
-                    Event::TimelineReset { items, .. } => {
-                        timeline_items = items;
-                        resync_id = None;
+                    Event::TimelineReset { timeline_id, items: snapshot }
+                        if opened.as_ref() == Some(&timeline_id) =>
+                    {
+                        items = snapshot;
+                        stale = false;
+                        print_messages(&items);
                     }
-                    Event::TimelineChanged { timeline_id, diffs } if resync_id.is_none() => {
-                        for diff in diffs {
-                            if diff.try_apply(&mut timeline_items).is_err() {
-                                resync_id = Some(handle.send(Command::Timeline(
-                                    TimelineCommand::Resync { timeline_id },
-                                )).await?);
-                                break;
-                            }
-                        }
-                        if resync_id.is_none() {
-                            for item in &timeline_items {
-                                if let macltok::TimelineItem::Message(message) = item {
-                                    println!("{}  {}", message.sender_name, message.body);
-                                }
-                            }
+                    Event::TimelineChanged { timeline_id, diffs }
+                        if !stale && opened.as_ref() == Some(&timeline_id) =>
+                    {
+                        if diffs.into_iter().any(|diff| diff.try_apply(&mut items).is_err()) {
+                            stale = true;
+                            let handle = handle.clone();
+                            tokio::spawn(async move { handle.resync(timeline_id).await });
+                            continue;
                         }
-                    }
-                    Event::CommandSucceeded { id, command: CommandKind::Room }
-                        if room_open_id == Some(id) => println!("room ready"),
-                    Event::CommandFailed(error) if room_open_id == Some(error.id)
-                        || resync_id == Some(error.id) => return Err(error.message.into()),
-                    Event::CommandFailed(error) => {
-                        eprintln!("{:?}  {}", error.command, error.message);
+                        print_messages(&items);
                     }
                     Event::Stopped => break,
                     _ => {}
@@ -78,9 +71,8 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
             }
             result = tokio::signal::ctrl_c() => {
                 result?;
-                handle
-                    .send(Command::Lifecycle(LifecycleCommand::Shutdown))
-                    .await?;
+                let handle = handle.clone();
+                tokio::spawn(async move { handle.shutdown().await });
             }
         }
     }
@@ -88,6 +80,14 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     Ok(())
 }
 
+fn print_messages(items: &[TimelineItem]) {
+    for item in items {
+        if let TimelineItem::Message(message) = item {
+            println!("{}  {}", message.sender_name, message.body);
+        }
+    }
+}
+
 fn required(name: &str) -> Result<String, Box<dyn std::error::Error>> {
     std::env::var(name).map_err(|_| format!("{name} is required").into())
 }

Modified file: src/account.rs+71 additions@@ -27,6 +27,7 @@ pub struct Session {
     record: SessionRecord,
 }
 
+#[non_exhaustive]
 pub struct PasswordLogin {
     pub homeserver: String,
     pub username: String,
@@ -36,6 +37,36 @@ pub struct PasswordLogin {
     pub device_id: Option<OwnedDeviceId>,
 }
 
+impl PasswordLogin {
+    #[must_use]
+    pub fn new(
+        homeserver: impl Into<String>,
+        username: impl Into<String>,
+        password: impl Into<String>,
+    ) -> Self {
+        Self {
+            homeserver: homeserver.into(),
+            username: username.into(),
+            password: password.into(),
+            device_display_name: None,
+            device_id: None,
+        }
+    }
+
+    #[must_use]
+    pub fn with_device_display_name(mut self, name: impl Into<String>) -> Self {
+        self.device_display_name = Some(name.into());
+        self
+    }
+
+    #[must_use]
+    pub fn with_device_id(mut self, device_id: OwnedDeviceId) -> Self {
+        self.device_id = Some(device_id);
+        self
+    }
+}
+
+#[non_exhaustive]
 pub struct OAuthLogin {
     pub homeserver: String,
     pub redirect_uri: String,
@@ -46,7 +77,47 @@ pub struct OAuthLogin {
     pub application_type: OAuthApplicationType,
 }
 
+impl OAuthLogin {
+    #[must_use]
+    pub fn new(
+        homeserver: impl Into<String>,
+        redirect_uri: impl Into<String>,
+        client_uri: impl Into<String>,
+        application_type: OAuthApplicationType,
+    ) -> Self {
+        Self {
+            homeserver: homeserver.into(),
+            redirect_uri: redirect_uri.into(),
+            client_uri: client_uri.into(),
+            client_name: None,
+            client_id: None,
+            device_id: None,
+            application_type,
+        }
+    }
+
+    #[must_use]
+    pub fn with_client_name(mut self, name: impl Into<String>) -> Self {
+        self.client_name = Some(name.into());
+        self
+    }
+
+    /// a statically registered client id, skipping dynamic registration
+    #[must_use]
+    pub fn with_client_id(mut self, client_id: impl Into<String>) -> Self {
+        self.client_id = Some(client_id.into());
+        self
+    }
+
+    #[must_use]
+    pub fn with_device_id(mut self, device_id: OwnedDeviceId) -> Self {
+        self.device_id = Some(device_id);
+        self
+    }
+}
+
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[non_exhaustive]
 pub enum OAuthApplicationType {
     Native,
     Web,

Modified file: src/encryption.rs+88 additions−115 deletions@@ -17,9 +17,9 @@ use ruma::{OwnedDeviceId, UserId};
 use tokio::{sync::Mutex, task::JoinHandle};
 
 use crate::{
-    CommandErrorKind, EncryptionState, Event, KeyBackupState, RecoveryState, VerificationAction,
-    VerificationState as UiState, VerificationTarget, error::CommandError,
-    model::VerificationFailure, transport::EventSender,
+    EncryptionState, Error, ErrorKind, Event, KeyBackupState, RecoveryState, VerificationAction,
+    VerificationState as UiState, VerificationTarget, model::VerificationFailure,
+    transport::EventSender,
 };
 
 pub(crate) fn encryption_state(
@@ -64,10 +64,9 @@ struct VerificationSession {
 impl VerificationController {
     pub(crate) async fn apply(
         &mut self,
-        _client: &Client,
         sender: EventSender,
         action: VerificationAction,
-    ) -> Result<(), CommandError> {
+    ) -> Result<(), Error> {
         match action {
             VerificationAction::Confirm => {
                 // Retain a handle across the operation: the watcher clears
@@ -76,9 +75,7 @@ impl VerificationController {
                 let sas = self.active.lock().await.sas.clone();
                 match self.confirm().await {
                     Ok(()) => Ok(()),
-                    Err(error) if error.kind == CommandErrorKind::VerificationInactive => {
-                        Err(error)
-                    }
+                    Err(error) if error.kind == ErrorKind::VerificationInactive => Err(error),
                     // The confirm advanced local SDK state before its send failed,
                     // so the retained session could report success on retry without
                     // network traffic. Best-effort cancel (no lock held across the
@@ -153,8 +150,8 @@ impl VerificationController {
                                             )))
                                             .await;
                                     }
-                                    return Err(CommandError::new(
-                                        CommandErrorKind::VerificationInactive,
+                                    return Err(Error::new(
+                                        ErrorKind::VerificationInactive,
                                         info.reason().to_owned(),
                                     ));
                                 }
@@ -185,8 +182,8 @@ impl VerificationController {
                         )))
                         .await
                         .map_err(|source| {
-                            CommandError::with_source(
-                                CommandErrorKind::EventReceiverClosed,
+                            Error::with_source(
+                                ErrorKind::Interrupted,
                                 "event receiver has closed",
                                 source,
                             )
@@ -202,14 +199,14 @@ impl VerificationController {
         client: &Client,
         sender: EventSender,
         target: VerificationTarget,
-    ) -> Result<(), CommandError> {
+    ) -> Result<(), Error> {
         client
             .encryption()
             .wait_for_e2ee_initialization_tasks()
             .await;
         let own_user_id = client.user_id().ok_or_else(|| {
-            CommandError::new(
-                CommandErrorKind::Unauthenticated,
+            Error::new(
+                ErrorKind::Unauthenticated,
                 "the Matrix client is not authenticated",
             )
         })?;
@@ -231,15 +228,15 @@ impl VerificationController {
                     .get_device(user_id, device_id)
                     .await
                     .map_err(|source| {
-                        CommandError::with_source(
-                            CommandErrorKind::Encryption,
+                        Error::with_source(
+                            ErrorKind::Encryption,
                             "reading the verification device failed",
                             source,
                         )
                     })?
                     .ok_or_else(|| {
-                        CommandError::new(
-                            CommandErrorKind::VerificationUnsupported,
+                        Error::new(
+                            ErrorKind::VerificationUnsupported,
                             "the verification device is unavailable",
                         )
                     })?;
@@ -247,7 +244,7 @@ impl VerificationController {
                     .request_verification_with_methods(vec![VerificationMethod::SasV1])
                     .await
                     .map_err(|source| {
-                        CommandError::from_sdk("starting device verification failed", source)
+                        Error::from_sdk("starting device verification failed", source)
                     })?
             }
         };
@@ -256,21 +253,13 @@ impl VerificationController {
             .send(Event::VerificationTargetChanged(target))
             .await
             .map_err(|source| {
-                CommandError::with_source(
-                    CommandErrorKind::EventReceiverClosed,
-                    "event receiver has closed",
-                    source,
-                )
+                Error::with_source(ErrorKind::Interrupted, "event receiver has closed", source)
             })?;
         sender
             .send(Event::VerificationChanged(UiState::Waiting))
             .await
             .map_err(|source| {
-                CommandError::with_source(
-                    CommandErrorKind::EventReceiverClosed,
-                    "event receiver has closed",
-                    source,
-                )
+                Error::with_source(ErrorKind::Interrupted, "event receiver has closed", source)
             })?;
         let active = self.active.clone();
         self.task = Some(tokio::spawn(async move {
@@ -279,24 +268,24 @@ impl VerificationController {
         Ok(())
     }
 
-    async fn confirm(&self) -> Result<(), CommandError> {
+    async fn confirm(&self) -> Result<(), Error> {
         let sas = self.active.lock().await.sas.clone().ok_or_else(|| {
-            CommandError::new(
-                CommandErrorKind::VerificationInactive,
+            Error::new(
+                ErrorKind::VerificationInactive,
                 "verification has not reached comparison",
             )
         })?;
         // Report a settled flow truthfully instead of as "not reached
         // comparison": the SDK would no-op the confirm with success.
         if sas.is_done() {
-            return Err(CommandError::new(
-                CommandErrorKind::VerificationInactive,
+            return Err(Error::new(
+                ErrorKind::VerificationInactive,
                 "verification is already complete",
             ));
         }
         if let Some(info) = sas.cancel_info() {
-            return Err(CommandError::new(
-                CommandErrorKind::VerificationInactive,
+            return Err(Error::new(
+                ErrorKind::VerificationInactive,
                 info.reason().to_owned(),
             ));
         }
@@ -304,8 +293,8 @@ impl VerificationController {
         // remote-MAC-arrived state through the same presentable flag, while an
         // early confirm would locally no-op and falsely report success.
         if !sas.can_be_presented() {
-            return Err(CommandError::new(
-                CommandErrorKind::VerificationInactive,
+            return Err(Error::new(
+                ErrorKind::VerificationInactive,
                 "verification has not reached comparison",
             ));
         }
@@ -315,11 +304,11 @@ impl VerificationController {
         let was_done = sas.is_done();
         sas.confirm()
             .await
-            .map_err(|source| CommandError::from_sdk("confirming verification failed", source))?;
+            .map_err(|source| Error::from_sdk("confirming verification failed", source))?;
         if sas.is_done() {
             if was_done {
-                return Err(CommandError::new(
-                    CommandErrorKind::VerificationInactive,
+                return Err(Error::new(
+                    ErrorKind::VerificationInactive,
                     "verification is already complete",
                 ));
             }
@@ -328,52 +317,49 @@ impl VerificationController {
                 .cancel_info()
                 .map(|info| info.reason().to_owned())
                 .unwrap_or_else(|| "verification was cancelled".to_owned());
-            return Err(CommandError::new(
-                CommandErrorKind::VerificationInactive,
-                reason,
-            ));
+            return Err(Error::new(ErrorKind::VerificationInactive, reason));
         }
         Ok(())
     }
 
-    async fn reject(&self) -> Result<(), CommandError> {
+    async fn reject(&self) -> Result<(), Error> {
         let sas = self.active.lock().await.sas.clone().ok_or_else(|| {
-            CommandError::new(
-                CommandErrorKind::VerificationInactive,
+            Error::new(
+                ErrorKind::VerificationInactive,
                 "verification has not reached comparison",
             )
         })?;
         // Report a settled flow truthfully instead of as "not reached
         // comparison": the SDK would no-op the mismatch with success.
         if sas.is_done() {
-            return Err(CommandError::new(
-                CommandErrorKind::VerificationInactive,
+            return Err(Error::new(
+                ErrorKind::VerificationInactive,
                 "verification is already complete",
             ));
         }
         if let Some(info) = sas.cancel_info() {
-            return Err(CommandError::new(
-                CommandErrorKind::VerificationInactive,
+            return Err(Error::new(
+                ErrorKind::VerificationInactive,
                 info.reason().to_owned(),
             ));
         }
         // Rejecting before the comparison stage would cancel a flow the user
         // never compared, so it requires the same presentable state.
         if !sas.can_be_presented() {
-            return Err(CommandError::new(
-                CommandErrorKind::VerificationInactive,
+            return Err(Error::new(
+                ErrorKind::VerificationInactive,
                 "verification has not reached comparison",
             ));
         }
         sas.mismatch()
             .await
-            .map_err(|source| CommandError::from_sdk("rejecting verification failed", source))?;
+            .map_err(|source| Error::from_sdk("rejecting verification failed", source))?;
         // A peer completing the flow concurrently must not be reported as
         // rejected. A remote cancellation racing the send turns the SDK call
         // into a no-op success, so report it instead of a false success.
         if sas.is_done() {
-            return Err(CommandError::new(
-                CommandErrorKind::VerificationInactive,
+            return Err(Error::new(
+                ErrorKind::VerificationInactive,
                 "verification is already complete",
             ));
         }
@@ -382,29 +368,29 @@ impl VerificationController {
             // expected reject path and stays Ok. Only a peer cancel reports an
             // error.
             if !info.cancelled_by_us() {
-                return Err(CommandError::new(
-                    CommandErrorKind::VerificationInactive,
+                return Err(Error::new(
+                    ErrorKind::VerificationInactive,
                     info.reason().to_owned(),
                 ));
             }
         }
         Ok(())
     }
-    pub(crate) async fn cancel(&mut self) -> Result<(), CommandError> {
+    pub(crate) async fn cancel(&mut self) -> Result<(), Error> {
         self.cancel_claimed(None).await.map(|_| ())
     }
 
     /// Return whether this action won the claim for a local cancellation.
     /// The optional sender reports a peer terminal outcome when it races after
     /// the claim; starting a replacement verification does not publish it.
-    async fn cancel_claimed(&mut self, sender: Option<&EventSender>) -> Result<bool, CommandError> {
+    async fn cancel_claimed(&mut self, sender: Option<&EventSender>) -> Result<bool, Error> {
         let (sas, request) = {
             let active = self.active.lock().await;
             (active.sas.clone(), active.request.clone())
         };
         if sas.is_none() && request.is_none() {
-            return Err(CommandError::new(
-                CommandErrorKind::VerificationInactive,
+            return Err(Error::new(
+                ErrorKind::VerificationInactive,
                 "no verification is active",
             ));
         }
@@ -415,27 +401,27 @@ impl VerificationController {
         // SDK no-op success regress Done to "cancelled by this client".
         if let Some(sas) = sas.as_ref() {
             if sas.is_done() {
-                return Err(CommandError::new(
-                    CommandErrorKind::VerificationInactive,
+                return Err(Error::new(
+                    ErrorKind::VerificationInactive,
                     "verification is already complete",
                 ));
             }
             if let Some(info) = sas.cancel_info() {
-                return Err(CommandError::new(
-                    CommandErrorKind::VerificationInactive,
+                return Err(Error::new(
+                    ErrorKind::VerificationInactive,
                     info.reason().to_owned(),
                 ));
             }
         } else if let Some(request) = request.as_ref() {
             if request.is_done() {
-                return Err(CommandError::new(
-                    CommandErrorKind::VerificationInactive,
+                return Err(Error::new(
+                    ErrorKind::VerificationInactive,
                     "verification is already complete",
                 ));
             }
             if let Some(info) = request.cancel_info() {
-                return Err(CommandError::new(
-                    CommandErrorKind::VerificationInactive,
+                return Err(Error::new(
+                    ErrorKind::VerificationInactive,
                     info.reason().to_owned(),
                 ));
             }
@@ -451,33 +437,33 @@ impl VerificationController {
             // flow and must not be disturbed.
             if let Some(sas) = sas.as_ref() {
                 if sas.is_done() {
-                    return Err(CommandError::new(
-                        CommandErrorKind::VerificationInactive,
+                    return Err(Error::new(
+                        ErrorKind::VerificationInactive,
                         "verification is already complete",
                     ));
                 }
                 if let Some(info) = sas.cancel_info() {
-                    return Err(CommandError::new(
-                        CommandErrorKind::VerificationInactive,
+                    return Err(Error::new(
+                        ErrorKind::VerificationInactive,
                         info.reason().to_owned(),
                     ));
                 }
             } else if let Some(request) = request.as_ref() {
                 if request.is_done() {
-                    return Err(CommandError::new(
-                        CommandErrorKind::VerificationInactive,
+                    return Err(Error::new(
+                        ErrorKind::VerificationInactive,
                         "verification is already complete",
                     ));
                 }
                 if let Some(info) = request.cancel_info() {
-                    return Err(CommandError::new(
-                        CommandErrorKind::VerificationInactive,
+                    return Err(Error::new(
+                        ErrorKind::VerificationInactive,
                         info.reason().to_owned(),
                     ));
                 }
             }
-            return Err(CommandError::new(
-                CommandErrorKind::VerificationInactive,
+            return Err(Error::new(
+                ErrorKind::VerificationInactive,
                 "no verification is active",
             ));
         }
@@ -486,8 +472,8 @@ impl VerificationController {
             let result = sas.cancel().await;
             if sas.is_done() {
                 report_claimed_terminal(sender, UiState::Done).await;
-                return Err(CommandError::new(
-                    CommandErrorKind::VerificationInactive,
+                return Err(Error::new(
+                    ErrorKind::VerificationInactive,
                     "verification is already complete",
                 ));
             }
@@ -496,13 +482,10 @@ impl VerificationController {
             {
                 let reason = info.reason().to_owned();
                 report_claimed_terminal(sender, UiState::Cancelled(reason.clone())).await;
-                return Err(CommandError::new(
-                    CommandErrorKind::VerificationInactive,
-                    reason,
-                ));
+                return Err(Error::new(ErrorKind::VerificationInactive, reason));
             }
             if let Err(source) = result {
-                let error = CommandError::from_sdk("cancelling verification failed", source);
+                let error = Error::from_sdk("cancelling verification failed", source);
                 report_claimed_terminal(sender, UiState::Cancelled(error.to_string())).await;
                 return Err(error);
             }
@@ -511,8 +494,8 @@ impl VerificationController {
             let result = request.cancel().await;
             if request.is_done() {
                 report_claimed_terminal(sender, UiState::Done).await;
-                return Err(CommandError::new(
-                    CommandErrorKind::VerificationInactive,
+                return Err(Error::new(
+                    ErrorKind::VerificationInactive,
                     "verification is already complete",
                 ));
             }
@@ -521,13 +504,10 @@ impl VerificationController {
             {
                 let reason = info.reason().to_owned();
                 report_claimed_terminal(sender, UiState::Cancelled(reason.clone())).await;
-                return Err(CommandError::new(
-                    CommandErrorKind::VerificationInactive,
-                    reason,
-                ));
+                return Err(Error::new(ErrorKind::VerificationInactive, reason));
             }
             if let Err(source) = result {
-                let error = CommandError::from_sdk("cancelling verification failed", source);
+                let error = Error::from_sdk("cancelling verification failed", source);
                 report_claimed_terminal(sender, UiState::Cancelled(error.to_string())).await;
                 return Err(error);
             }
@@ -548,37 +528,36 @@ impl VerificationController {
             let _ = task.await;
         }
     }
+}
 
-    pub(crate) async fn stop(&mut self) {
-        // Shutdown path: terminate the watcher without touching the SDK so a
-        // shutdown under lock cannot hang on network sends. No terminal event
-        // is emitted; the session is simply forgotten locally.
-        self.stop_task().await;
-        clear_verification(&self.active).await;
+/// shutdown forgets the flow without telling the sdk, a network send could hang it
+impl Drop for VerificationController {
+    fn drop(&mut self) {
+        if let Some(task) = self.task.take() {
+            task.abort();
+        }
     }
 }
 
 async fn request_identity_verification(
     client: &Client,
     user_id: &UserId,
-) -> Result<VerificationRequest, CommandError> {
+) -> Result<VerificationRequest, Error> {
     let identity = client
         .encryption()
         .request_user_identity(user_id)
         .await
-        .map_err(|source| CommandError::from_sdk("requesting the user identity failed", source))?
+        .map_err(|source| Error::from_sdk("requesting the user identity failed", source))?
         .ok_or_else(|| {
-            CommandError::new(
-                CommandErrorKind::NoCrossSigningIdentity,
+            Error::new(
+                ErrorKind::NoCrossSigningIdentity,
                 "the user has no cross-signing identity",
             )
         })?;
     identity
         .request_verification_with_methods(vec![VerificationMethod::SasV1])
         .await
-        .map_err(|source| {
-            CommandError::from_verification_request("starting verification failed", source)
-        })
+        .map_err(|source| Error::from_verification_request("starting verification failed", source))
 }
 
 async fn follow_request(
@@ -787,12 +766,6 @@ async fn report_claimed_terminal(sender: Option<&EventSender>, state: UiState) {
     }
 }
 
-async fn clear_verification(active: &Arc<Mutex<VerificationSession>>) {
-    let mut active = active.lock().await;
-    active.sas.take();
-    active.request.take();
-}
-
 /// Claim the active session for terminal emission, if one is still present.
 ///
 /// Exactly one party (watcher or action path) wins the claim and may emit the

Deleted file: src/engine.rs−4364 deletions@@ -1,4364 +0,0 @@
-use std::{
-    borrow::Cow,
-    collections::{HashMap, HashSet, VecDeque},
-    future::Future,
-    io::Read as _,
-    panic::AssertUnwindSafe,
-    sync::Arc,
-    time::Duration,
-};
-
-use futures_util::{FutureExt, StreamExt};
-use matrix_sdk::{
-    Client, Room, SessionChange,
-    media::{MediaFormat, MediaRequestParameters, MediaThumbnailSettings},
-    room::edit::EditedContent,
-    room::reply::{EnforceThread, Reply as SdkReply},
-    ruma::{
-        OwnedDeviceId, OwnedEventId, OwnedRoomId, RoomId,
-        api::client::receipt::create_receipt::v3::ReceiptType,
-        events::{
-            AnyGlobalAccountDataEventContent, AnyMessageLikeEventContent,
-            GlobalAccountDataEventType, Mentions, RoomAccountDataEventType,
-            receipt::ReceiptThread,
-            room::message::{
-                AddMentions, MessageType, Relation, ReplyWithinThread,
-                RoomMessageEventContentWithoutRelation,
-            },
-        },
-        serde::Raw,
-    },
-    send_queue::{LocalEchoContent, RoomSendQueueUpdate, SendHandle},
-};
-use matrix_sdk_ui::{
-    sync_service::{State as SyncState, SyncService},
-    timeline::{
-        RoomExt, Timeline, TimelineEventItemId, TimelineFocus, TimelineReadReceiptTracking,
-    },
-};
-use thiserror::Error;
-use tokio::{
-    sync::{Mutex, mpsc, oneshot, watch},
-    task::{AbortHandle, Id as TaskId, JoinHandle, JoinSet},
-};
-
-use crate::{
-    AccountCommand, AttachmentUpload, ClientHandle, Command, CommandErrorKind, CommandFailure,
-    CommandId, CommandKind, ConnectionState, CreateRoomOptions, EncryptionCommand, EngineErrorKind,
-    EngineFailure, Event, EventStream, HistoryState, InteractiveAuth, InteractiveAuthChallenge,
-    InteractiveAuthOutcome, LifecycleCommand, MediaCommand, MediaId, MediaSize, MessageContent,
-    MessageEditContent, MessageMentions, NotificationCommand, PowerLevelChanges, RichText,
-    RoomCommand, RoomNotificationMode, RoomPreset, RoomVisibility, TimelineCommand, TimelineId,
-    TypingState,
-    encryption::{VerificationController, encryption_state},
-    error::{CommandError, classify_sdk_error},
-    normalise::{MediaRegistration, MediaScope, normalise_timeline, normalise_timeline_diffs},
-    transport::{
-        ClientQueryError, CommandEnvelope, CommandResultError, DriverPort, DriverRequest,
-        EventSender, SendEventError, transport_pair,
-    },
-    upload::prepare_upload,
-};
-use matrix_sdk::ruma::api::{Metadata, OutgoingRequest, auth_scheme::SendAccessToken};
-use matrix_sdk_crypto::{AttachmentDecryptor, MediaEncryptionInfo};
-
-#[derive(Clone, Debug, Eq, PartialEq)]
-#[non_exhaustive]
-pub struct EngineConfig {
-    pub command_capacity: usize,
-    pub event_capacity: usize,
-    pub initial_history_limit: u16,
-    pub max_media_bytes: usize,
-    pub max_media_sources: usize,
-}
-
-impl EngineConfig {
-    #[must_use]
-    pub const fn with_command_capacity(mut self, capacity: usize) -> Self {
-        self.command_capacity = capacity;
-        self
-    }
-
-    #[must_use]
-    pub const fn with_event_capacity(mut self, capacity: usize) -> Self {
-        self.event_capacity = capacity;
-        self
-    }
-
-    #[must_use]
-    pub const fn with_initial_history_limit(mut self, limit: u16) -> Self {
-        self.initial_history_limit = limit;
-        self
-    }
-
-    #[must_use]
-    pub const fn with_max_media_bytes(mut self, bytes: usize) -> Self {
-        self.max_media_bytes = bytes;
-        self
-    }
-
-    #[must_use]
-    pub const fn with_max_media_sources(mut self, sources: usize) -> Self {
-        self.max_media_sources = sources;
-        self
-    }
-}
-
-impl Default for EngineConfig {
-    fn default() -> Self {
-        Self {
-            command_capacity: 64,
-            event_capacity: 128,
-            initial_history_limit: 30,
-            max_media_bytes: 20 * 1024 * 1024,
-            max_media_sources: 2_048,
-        }
-    }
-}
-
-#[derive(Debug, Error)]
-pub enum EngineError {
-    #[error("the Matrix client is not authenticated")]
-    Unauthenticated,
-    #[error("command, event, and media source capacities must be nonzero")]
-    ZeroCapacity,
-    #[error("could not build the sync service")]
-    SyncService(#[source] matrix_sdk_ui::sync_service::Error),
-    #[error("the event receiver has closed")]
-    EventReceiverClosed,
-    #[error("engine task {task} panicked")]
-    TaskPanicked { task: String },
-}
-
-impl EngineError {
-    fn failure(&self) -> EngineFailure {
-        EngineFailure {
-            kind: match self {
-                Self::EventReceiverClosed => EngineErrorKind::EventReceiverClosed,
-                Self::Unauthenticated
-                | Self::ZeroCapacity
-                | Self::SyncService(_)
-                | Self::TaskPanicked { .. } => EngineErrorKind::Other,
-            },
-            message: self.to_string(),
-        }
-    }
-}
-
-type UploadWatchers = HashMap<
-    OwnedRoomId,
-    (
-        AbortHandle,
-        watch::Receiver<Option<Result<(), CommandErrorKind>>>,
-    ),
->;
-const SYNC_RESTART_MIN: Duration = Duration::from_secs(1);
-const SYNC_RESTART_MAX: Duration = Duration::from_secs(60);
-const SEND_QUEUE_RETRY: Duration = Duration::from_secs(5);
-
-type MediaFlights = Arc<Mutex<HashMap<(MediaId, MediaSize), Vec<CommandId>>>>;
-
-pub struct Engine {
-    client: Client,
-    sync: Arc<SyncService>,
-    port: DriverPort,
-    rooms: HashMap<OwnedRoomId, RoomActorState>,
-    next_room_generation: u64,
-    room_actor_events: mpsc::UnboundedReceiver<RoomActorEvent>,
-    room_actor_event_sender: mpsc::UnboundedSender<RoomActorEvent>,
-    upload_watchers: UploadWatchers,
-    tasks: TaskRegistry,
-    session_changes: Option<tokio::sync::broadcast::Receiver<SessionChange>>,
-    initial_history_limit: u16,
-    room_command_capacity: usize,
-    max_media_bytes: usize,
-    media: Arc<Mutex<MediaRegistry>>,
-    notification_commands: mpsc::Sender<CommandJob<NotificationCommand>>,
-    notification_command_receiver: Option<mpsc::Receiver<CommandJob<NotificationCommand>>>,
-    encryption_commands: mpsc::Sender<EncryptionWork>,
-    encryption_command_receiver: Option<mpsc::Receiver<EncryptionWork>>,
-    verification: Arc<Mutex<VerificationController>>,
-    room_commands: mpsc::Sender<RoomJob>,
-    room_command_receiver: Option<mpsc::Receiver<RoomJob>>,
-    global_account_gates: HashMap<String, oneshot::Receiver<()>>,
-    room_account_gates: HashMap<(OwnedRoomId, String), oneshot::Receiver<()>>,
-    media_flights: MediaFlights,
-    stop: Arc<tokio::sync::Notify>,
-}
-
-struct CommandJob<T> {
-    id: CommandId,
-    command: T,
-}
-
-enum EncryptionWork {
-    Command(CommandJob<EncryptionCommand>),
-}
-
-struct RoomJob {
-    id: CommandId,
-    command: RoomCommand,
-    reply: Option<oneshot::Sender<Result<OwnedRoomId, CommandResultError>>>,
-}
-
-#[derive(Clone, Debug, Eq, Hash, PartialEq)]
-enum RoomMutationKey {
-    Room(OwnedRoomId),
-    Target(String),
-    Direct(ruma::OwnedUserId),
-    Independent(CommandId),
-}
-
-struct RoomJobCompletion {
-    key: RoomMutationKey,
-    id: CommandId,
-    reply: Option<oneshot::Sender<Result<OwnedRoomId, CommandResultError>>>,
-    result: Result<Option<OwnedRoomId>, CommandError>,
-}
-
-#[derive(Clone)]
-enum TaskContext {
-    Command {
-        id: CommandId,
-        kind: CommandKind,
-    },
-    Watcher(&'static str),
-    RoomActor {
-        room_id: OwnedRoomId,
-        generation: u64,
-    },
-}
-
-impl TaskContext {
-    fn label(&self) -> String {
-        match self {
-            Self::Command { id, kind } => format!("{kind:?} command {}", id.get()),
-            Self::Watcher(name) => (*name).to_owned(),
-            Self::RoomActor {
-                room_id,
-                generation,
-            } => format!("room actor {room_id} generation {generation}"),
-        }
-    }
-}
-
-struct TaskRegistry {
-    tasks: JoinSet<()>,
-    contexts: HashMap<TaskId, TaskContext>,
-}
-
-impl TaskRegistry {
-    fn new() -> Self {
-        Self {
-            tasks: JoinSet::new(),
-            contexts: HashMap::new(),
-        }
-    }
-
-    fn is_empty(&self) -> bool {
-        self.tasks.is_empty()
-    }
-
-    fn spawn(
-        &mut self,
-        context: TaskContext,
-        future: impl Future<Output = ()> + Send + 'static,
-    ) -> AbortHandle {
-        let handle = self.tasks.spawn(future);
-        self.contexts.insert(handle.id(), context);
-        handle
-    }
-
-    async fn join_next(&mut self) -> Option<(TaskContext, Result<(), tokio::task::JoinError>)> {
-        let result = self.tasks.join_next_with_id().await?;
-        let id = match &result {
-            Ok((id, ())) => *id,
-            Err(error) => error.id(),
-        };
-        let context = self
-            .contexts
-            .remove(&id)
-            .expect("every registered task has context");
-        Some((context, result.map(|(_, ())| ())))
-    }
-
-    async fn shutdown(&mut self) {
-        self.tasks.abort_all();
-        while self.tasks.join_next().await.is_some() {}
-        self.contexts.clear();
-    }
-}
-
-enum RoomActorState {
-    Opening {
-        generation: u64,
-        sender: mpsc::Sender<RoomActorRequest>,
-    },
-    Open {
-        generation: u64,
-        sender: mpsc::Sender<RoomActorRequest>,
-    },
-    Closing {
-        generation: u64,
-        pending: VecDeque<DeferredRoomLifecycle>,
-    },
-}
-
-enum DeferredRoomLifecycle {
-    Open(CommandId),
-    Close(CommandId),
-}
-
-impl RoomActorState {
-    const fn generation(&self) -> u64 {
-        match self {
-            Self::Opening { generation, .. }
-            | Self::Open { generation, .. }
-            | Self::Closing { generation, .. } => *generation,
-        }
-    }
-
-    fn sender(&self) -> Option<&mpsc::Sender<RoomActorRequest>> {
-        match self {
-            Self::Opening { sender, .. } | Self::Open { sender, .. } => Some(sender),
-            Self::Closing { .. } => None,
-        }
-    }
-}
-
-enum RoomActorEvent {
-    Ready {
-        room_id: OwnedRoomId,
-        generation: u64,
-    },
-    Exited {
-        room_id: OwnedRoomId,
-        generation: u64,
-    },
-}
-
-enum EngineActivity {
-    Request(Option<Box<DriverRequest>>),
-    Task(Option<(TaskContext, Result<(), tokio::task::JoinError>)>),
-    RoomActor(Option<RoomActorEvent>),
-}
-
-/// least recently seen goes first. stale order slots are skipped by stamp rather than hunted down
-struct MediaRegistry {
-    entries: HashMap<MediaId, (MediaRegistration, u64)>,
-    order: VecDeque<(MediaId, u64)>,
-    next_stamp: u64,
-    limit: usize,
-}
-
-impl MediaRegistry {
-    fn new(limit: usize) -> Self {
-        Self {
-            entries: HashMap::new(),
-            order: VecDeque::new(),
-            next_stamp: 0,
-            limit,
-        }
-    }
-
-    fn get(&self, id: &MediaId) -> Option<&MediaRegistration> {
-        self.entries.get(id).map(|(media, _)| media)
-    }
-
-    fn insert_all(&mut self, media: Vec<MediaRegistration>) {
-        for media in media {
-            let stamp = self.next_stamp;
-            self.next_stamp += 1;
-            self.order.push_back((media.id.clone(), stamp));
-            self.entries.insert(media.id.clone(), (media, stamp));
-        }
-        while self.entries.len() > self.limit {
-            let Some((id, stamp)) = self.order.pop_front() else {
-                break;
-            };
-            if self
-                .entries
-                .get(&id)
-                .is_some_and(|(_, current)| *current == stamp)
-            {
-                self.entries.remove(&id);
-            }
-        }
-        if self.order.len() > self.limit.saturating_mul(4) {
-            let entries = &self.entries;
-            self.order
-                .retain(|(id, stamp)| entries.get(id).is_some_and(|(_, current)| current == stamp));
-        }
-    }
-
-    fn release(&mut self, scope: &MediaScope) {
-        self.entries.retain(|id, _| !scope.owns(id));
-        let entries = &self.entries;
-        self.order.retain(|(id, _)| entries.contains_key(id));
-    }
-}
-
-enum RoomActorRequest {
-    Opened {
-        id: CommandId,
-    },
-    Execute {
-        id: CommandId,
-        command: TimelineCommand,
-    },
-    Close {
-        id: CommandId,
-    },
-}
-
-struct RoomActor {
-    room_id: OwnedRoomId,
-    generation: u64,
-    room: Room,
-    receiver: mpsc::Receiver<RoomActorRequest>,
-    events: EventSender,
-    engine_events: mpsc::UnboundedSender<RoomActorEvent>,
-    media: Arc<Mutex<MediaRegistry>>,
-    initial_history_limit: u16,
-    open_ids: Vec<CommandId>,
-    background: JoinSet<(CommandId, Result<(), CommandError>)>,
-    background_ids: HashMap<TaskId, CommandId>,
-}
-
-type BackgroundResult =
-    Result<(TaskId, (CommandId, Result<(), CommandError>)), tokio::task::JoinError>;
-type BackgroundWork = std::pin::Pin<Box<dyn Future<Output = Result<(), CommandError>> + Send>>;
-
-/// network-bound work runs beside the actor so one slow redaction doesn't queue the room behind it
-enum TimelineOutcome {
-    Done(Result<(), CommandError>),
-    Background(BackgroundWork),
-}
-
-struct TimelineSession {
-    id: TimelineId,
-    timeline: Arc<Timeline>,
-    events: EventSender,
-    watcher: JoinHandle<()>,
-    media: Arc<Mutex<MediaRegistry>>,
-    current_user_id: Option<ruma::OwnedUserId>,
-    scope: MediaScope,
-    pagination_ids: Arc<Mutex<HashSet<CommandId>>>,
-    pagination_sender: mpsc::Sender<PaginationRequest>,
-    pagination_worker: JoinHandle<()>,
-    pagination_results: Option<mpsc::UnboundedSender<(CommandId, Result<(), CommandError>)>>,
-    pagination_result_task: JoinHandle<()>,
-}
-
-struct PaginationRequest {
-    timeline: Arc<Timeline>,
-    events: EventSender,
-    timeline_id: TimelineId,
-    limit: u16,
-    command_id: Option<CommandId>,
-    results: mpsc::UnboundedSender<(CommandId, Result<(), CommandError>)>,
-}
-
-impl TimelineSession {
-    async fn start(
-        id: TimelineId,
-        timeline: Timeline,
-        events: EventSender,
-        media: Arc<Mutex<MediaRegistry>>,
-        current_user_id: Option<ruma::OwnedUserId>,
-        initial_history_limit: u16,
-    ) -> Result<Self, SendEventError> {
-        let timeline = Arc::new(timeline);
-        let scope = MediaScope::new();
-        let watcher = start_timeline_watcher(
-            id.clone(),
-            timeline.clone(),
-            events.clone(),
-            media.clone(),
-            current_user_id.clone(),
-            scope.clone(),
-        )
-        .await?;
-
-        let (pagination_sender, mut pagination_receiver) = mpsc::channel::<PaginationRequest>(32);
-        let pagination_worker = tokio::spawn(async move {
-            while let Some(request) = pagination_receiver.recv().await {
-                let command_id = request.command_id;
-                let results = request.results.clone();
-                if AssertUnwindSafe(run_pagination(request))
-                    .catch_unwind()
-                    .await
-                    .is_err()
-                {
-                    tracing::warn!(?command_id, "pagination task panicked");
-                    if let Some(id) = command_id {
-                        let _ = results.send((
-                            id,
-                            Err(CommandError::new(
-                                CommandErrorKind::Timeline,
-                                "pagination failed",
-                            )),
-                        ));
-                    }
-                }
-            }
-        });
-        let pagination_ids = Arc::new(Mutex::new(HashSet::new()));
-        let (pagination_results, mut result_receiver) = mpsc::unbounded_channel();
-        let result_events = events.clone();
-        let result_ids = pagination_ids.clone();
-        let pagination_result_task = tokio::spawn(async move {
-            while let Some((id, result)) = result_receiver.recv().await {
-                if result_ids.lock().await.remove(&id) {
-                    let _ = emit_command_result(&result_events, id, CommandKind::Timeline, result)
-                        .await;
-                }
-            }
-        });
-
-        let mut session = Self {
-            id,
-            timeline,
-            events,
-            watcher,
-            media,
-            current_user_id,
-            scope,
-            pagination_sender,
-            pagination_worker,
-            pagination_ids,
-            pagination_results: Some(pagination_results),
-            pagination_result_task,
-        };
-        if initial_history_limit > 0 {
-            session.paginate(initial_history_limit, None).await;
-        }
-        Ok(session)
-    }
-
-    async fn resync(&mut self) -> Result<(), SendEventError> {
-        self.watcher.abort();
-        let _ = (&mut self.watcher).await;
-        self.watcher = start_timeline_watcher(
-            self.id.clone(),
-            self.timeline.clone(),
-            self.events.clone(),
-            self.media.clone(),
-            self.current_user_id.clone(),
-            self.scope.clone(),
-        )
-        .await?;
-        Ok(())
-    }
-
-    async fn paginate(&mut self, limit: u16, command_id: Option<CommandId>) {
-        if let Some(id) = command_id {
-            self.pagination_ids.lock().await.insert(id);
-        }
-        let request = PaginationRequest {
-            timeline: self.timeline.clone(),
-            events: self.events.clone(),
-            timeline_id: self.id.clone(),
-            limit,
-            command_id,
-            results: self
-                .pagination_results
-                .as_ref()
-                .expect("pagination session is open")
-                .clone(),
-        };
-        if let Err(error) = self.pagination_sender.try_send(request) {
-            let kind = match error {
-                mpsc::error::TrySendError::Full(_) => CommandErrorKind::QueueFull,
-                mpsc::error::TrySendError::Closed(_) => CommandErrorKind::TimelineNotOpen,
-            };
-            if let Some(id) = command_id {
-                self.pagination_ids.lock().await.remove(&id);
-                let _ = emit_command_result(
-                    &self.events,
-                    id,
-                    CommandKind::Timeline,
-                    Err(CommandError::new(kind, "pagination queue is unavailable")),
-                )
-                .await;
-            }
-        }
-    }
-
-    async fn close(mut self, kind: CommandErrorKind, message: &'static str) {
-        self.media.lock().await.release(&self.scope);
-        self.pagination_worker.abort();
-        let _ = (&mut self.pagination_worker).await;
-        drop(self.pagination_results.take());
-        let _ = (&mut self.pagination_result_task).await;
-        let pending = self.pagination_ids.lock().await.drain().collect::<Vec<_>>();
-        for id in pending {
-            let _ = emit_command_result(
-                &self.events,
-                id,
-                CommandKind::Timeline,
-                Err(CommandError::new(kind, message)),
-            )
-            .await;
-        }
-        self.watcher.abort();
-        let _ = (&mut self.watcher).await;
-    }
-}
-
-async fn start_timeline_watcher(
-    id: TimelineId,
-    timeline: Arc<Timeline>,
-    events: EventSender,
-    media: Arc<Mutex<MediaRegistry>>,
-    current_user_id: Option<ruma::OwnedUserId>,
-    scope: MediaScope,
-) -> Result<JoinHandle<()>, SendEventError> {
-    let (items, mut stream) = timeline.subscribe().await;
-    let normalised = normalise_timeline(items.iter(), current_user_id.as_deref(), &scope);
-    media.lock().await.insert_all(normalised.media);
-    events
-        .send(Event::TimelineReset {
-            timeline_id: id.clone(),
-            items: normalised.items,
-        })
-        .await?;
-    Ok(tokio::spawn(async move {
-        while let Some(diffs) = stream.next().await {
-            let normalised = normalise_timeline_diffs(diffs, current_user_id.as_deref(), &scope);
-            media.lock().await.insert_all(normalised.media);
-            if events
-                .send(Event::TimelineChanged {
-                    timeline_id: id.clone(),
-                    diffs: normalised.diffs,
-                })
-                .await
-                .is_err()
-            {
-                tracing::debug!(
-                    ?id,
-                    "timeline watcher stopped because the event receiver closed"
-                );
-                return;
-            }
-        }
-        tracing::debug!(?id, "timeline watcher stopped");
-    }))
-}
-
-impl Drop for TimelineSession {
-    fn drop(&mut self) {
-        self.watcher.abort();
-        self.pagination_worker.abort();
-        self.pagination_result_task.abort();
-    }
-}
-
-impl Engine {
-    pub async fn from_client(
-        client: Client,
-        config: EngineConfig,
-    ) -> Result<(Self, ClientHandle, EventStream), EngineError> {
-        if client.user_id().is_none() {
-            return Err(EngineError::Unauthenticated);
-        }
-        if config.command_capacity == 0
-            || config.event_capacity == 0
-            || config.max_media_sources == 0
-        {
-            return Err(EngineError::ZeroCapacity);
-        }
-        let session_changes = client.subscribe_to_session_changes();
-        let sync = Arc::new(
-            SyncService::builder(client.clone())
-                .with_offline_mode()
-                .build()
-                .await
-                .map_err(EngineError::SyncService)?,
-        );
-        let (handle, port, events) = transport_pair(
-            client.clone(),
-            sync.clone(),
-            config.command_capacity,
-            config.event_capacity,
-        );
-        client.send_queue().enable_upload_progress(true);
-        let (room_actor_event_sender, room_actor_events) = mpsc::unbounded_channel();
-        let (notification_commands, notification_command_receiver) =
-            mpsc::channel(config.command_capacity);
-        let (encryption_commands, encryption_command_receiver) =
-            mpsc::channel(config.command_capacity);
-        let (room_commands, room_command_receiver) = mpsc::channel(config.command_capacity);
-        Ok((
-            Self {
-                client,
-                sync,
-                port,
-                rooms: HashMap::new(),
-                next_room_generation: 0,
-                room_actor_events,
-                room_actor_event_sender,
-                upload_watchers: HashMap::new(),
-                tasks: TaskRegistry::new(),
-                session_changes: Some(session_changes),
-                initial_history_limit: config.initial_history_limit,
-                room_command_capacity: config.command_capacity,
-                max_media_bytes: config.max_media_bytes,
-                media: Arc::new(Mutex::new(MediaRegistry::new(config.max_media_sources))),
-                notification_commands,
-                notification_command_receiver: Some(notification_command_receiver),
-                encryption_commands,
-                encryption_command_receiver: Some(encryption_command_receiver),
-                verification: Arc::new(Mutex::new(VerificationController::default())),
-                room_commands,
-                room_command_receiver: Some(room_command_receiver),
-                global_account_gates: HashMap::new(),
-                room_account_gates: HashMap::new(),
-                media_flights: Arc::new(Mutex::new(HashMap::new())),
-                stop: Arc::new(tokio::sync::Notify::new()),
-            },
-            handle,
-            events,
-        ))
-    }
-
-    pub async fn run(mut self) -> Result<(), EngineError> {
-        let sender = self.port.event_sender();
-        let user_id = self
-            .client
-            .user_id()
-            .expect("authentication was checked during construction")
-            .to_owned();
-        if sender.send(Event::Authenticated { user_id }).await.is_err() {
-            self.shutdown().await;
-            return Err(EngineError::EventReceiverClosed);
-        }
-        self.port
-            .connection_sender()
-            .send_replace(ConnectionState::Connecting);
-        if sender
-            .send(Event::ConnectionChanged(ConnectionState::Connecting))
-            .await
-            .is_err()
-        {
-            self.shutdown().await;
-            return Err(EngineError::EventReceiverClosed);
-        }
-        self.start_watchers();
-        self.start_domain_workers();
-        self.sync.start().await;
-        let mut terminal_error = None;
-
-        loop {
-            let activity = tokio::select! {
-                biased;
-                _ = sender.closed() => {
-                    terminal_error = Some(EngineError::EventReceiverClosed);
-                    break;
-                }
-                () = self.stop.notified() => break,
-                request = self.port.recv() => EngineActivity::Request(request.map(Box::new)),
-                completed = self.tasks.join_next(), if !self.tasks.is_empty() => {
-                    EngineActivity::Task(completed)
-                }
-                event = self.room_actor_events.recv() => EngineActivity::RoomActor(event),
-            };
-            match activity {
-                EngineActivity::Request(Some(request)) => {
-                    let Some(envelope) = self.dispatch_request(*request).await else {
-                        continue;
-                    };
-                    let id = envelope.id;
-                    let command = envelope.command;
-                    if matches!(command, Command::Lifecycle(LifecycleCommand::Shutdown)) {
-                        let _ =
-                            emit_command_result(&sender, id, CommandKind::Lifecycle, Ok(())).await;
-                        break;
-                    }
-                    let kind = command.kind();
-                    tracing::debug!(?id, ?kind, "dispatching command");
-                    let result = self.execute(id, command).await;
-                    if Self::emit_sync_result(&sender, id, kind, result)
-                        .await
-                        .is_err()
-                    {
-                        terminal_error = Some(EngineError::EventReceiverClosed);
-                        break;
-                    }
-                }
-                EngineActivity::Request(None) => break,
-                EngineActivity::Task(Some((context, result))) => {
-                    if let Err(error) = result
-                        && error.is_panic()
-                    {
-                        match context {
-                            TaskContext::Command { id, kind } => {
-                                if sender
-                                    .send(Event::CommandFailed(CommandFailure {
-                                        id,
-                                        command: kind,
-                                        kind: CommandErrorKind::Other,
-                                        message: "command task panicked".to_owned(),
-                                    }))
-                                    .await
-                                    .is_err()
-                                {
-                                    terminal_error = Some(EngineError::EventReceiverClosed);
-                                    break;
-                                }
-                            }
-                            context => {
-                                terminal_error = Some(EngineError::TaskPanicked {
-                                    task: context.label(),
-                                });
-                                break;
-                            }
-                        }
-                    }
-                }
-                EngineActivity::Task(None) => {}
-                EngineActivity::RoomActor(Some(event)) => {
-                    if let Err(error) = self.handle_room_actor_event(event).await {
-                        terminal_error = Some(error);
-                        break;
-                    }
-                }
-                EngineActivity::RoomActor(None) => {
-                    terminal_error = Some(EngineError::TaskPanicked {
-                        task: "room actor event channel".to_owned(),
-                    });
-                    break;
-                }
-            }
-        }
-
-        if let Some(error) = terminal_error.as_ref() {
-            let _ = sender.send(Event::Failed(error.failure())).await;
-        }
-        self.shutdown().await;
-        let _ = sender.send(Event::Stopped).await;
-        if let Some(error) = terminal_error {
-            Err(error)
-        } else {
-            Ok(())
-        }
-    }
-
-    async fn emit_sync_result(
-        sender: &EventSender,
-        id: CommandId,
-        kind: CommandKind,
-        result: Result<bool, CommandError>,
-    ) -> Result<(), SendEventError> {
-        match result {
-            Ok(true) => Ok(()),
-            Ok(false) => emit_command_result(sender, id, kind, Ok(())).await,
-            Err(error) => {
-                tracing::warn!(?id, ?kind, error = ?error, "command failed");
-                emit_command_result(sender, id, kind, Err(error)).await?;
-                Ok(())
-            }
-        }
-    }
-
-    fn spawn_logout(&mut self, id: CommandId) {
-        let events = self.port.event_sender();
-        let client = self.client.clone();
-        let stop = self.stop.clone();
-        self.tasks.spawn(
-            TaskContext::Command {
-                id,
-                kind: CommandKind::Account,
-            },
-            async move {
-                match client
-                    .logout()
-                    .await
-                    .map(|_| ())
-                    .map_err(|source| CommandError::from_sdk("logout failed", source))
-                {
-                    Ok(()) => {
-                        let _ =
-                            emit_command_result(&events, id, CommandKind::Account, Ok(())).await;
-                        let _ = events.send(Event::LoggedOut).await;
-                        stop.notify_one();
-                    }
-                    Err(error) => {
-                        let _ = emit_command_result(&events, id, CommandKind::Account, Err(error))
-                            .await;
-                    }
-                }
-            },
-        );
-    }
-
-    async fn dispatch_request(&mut self, request: DriverRequest) -> Option<CommandEnvelope> {
-        match request {
-            DriverRequest::Command(command) => Some(command),
-            DriverRequest::DeleteDevices {
-                id,
-                device_ids,
-                auth,
-                reply,
-            } => {
-                self.spawn_delete_devices(id, device_ids, auth, Some(reply));
-                None
-            }
-            DriverRequest::RoomResult { id, command, reply } => {
-                if let Err(error) = self.spawn_room_command_with_reply(id, command, Some(reply)) {
-                    tracing::warn!(?id, error = ?error, "room result request failed");
-                }
-                None
-            }
-            DriverRequest::SetGlobalAccountData {
-                event_type,
-                content,
-                reply,
-            } => {
-                self.spawn_global_account_data_write(event_type, content, reply);
-                None
-            }
-            DriverRequest::SetRoomAccountData {
-                room_id,
-                event_type,
-                content,
-                reply,
-            } => {
-                self.spawn_room_account_data_write(room_id, event_type, content, reply);
-                None
-            }
-        }
-    }
-
-    fn spawn_mark_read(&mut self, id: CommandId, timeline_id: TimelineId, event_id: OwnedEventId) {
-        let events = self.port.event_sender();
-        let client = self.client.clone();
-        self.tasks.spawn(
-            TaskContext::Command {
-                id,
-                kind: CommandKind::Room,
-            },
-            async move {
-                let result = mark_read(&client, &timeline_id, event_id).await;
-                let _ = emit_command_result(&events, id, CommandKind::Room, result).await;
-            },
-        );
-    }
-
-    fn spawn_typing(&mut self, id: CommandId, room_id: OwnedRoomId, typing: bool) {
-        let events = self.port.event_sender();
-        let client = self.client.clone();
-        self.tasks.spawn(
-            TaskContext::Command {
-                id,
-                kind: CommandKind::Room,
-            },
-            async move {
-                let result = set_typing(&client, &room_id, typing).await;
-                let _ = emit_command_result(&events, id, CommandKind::Room, result).await;
-            },
-        );
-    }
-
-    fn spawn_cancel_send(
-        &mut self,
-        id: CommandId,
-        room_id: OwnedRoomId,
-        transaction_id: matrix_sdk::ruma::OwnedTransactionId,
-    ) {
-        let events = self.port.event_sender();
-        let client = self.client.clone();
-        self.tasks.spawn(
-            TaskContext::Command {
-                id,
-                kind: CommandKind::Room,
-            },
-            async move {
-                let result = cancel_send(&client, &room_id, &transaction_id).await;
-                let _ = emit_command_result(&events, id, CommandKind::Room, result).await;
-            },
-        );
-    }
-
-    fn spawn_retry_send(
-        &mut self,
-        id: CommandId,
-        room_id: OwnedRoomId,
-        transaction_id: matrix_sdk::ruma::OwnedTransactionId,
-    ) {
-        let events = self.port.event_sender();
-        let client = self.client.clone();
-        self.tasks.spawn(
-            TaskContext::Command {
-                id,
-                kind: CommandKind::Room,
-            },
-            async move {
-                let result = retry_send(&client, &room_id, &transaction_id).await;
-                let _ = emit_command_result(&events, id, CommandKind::Room, result).await;
-            },
-        );
-    }
-
-    fn spawn_delete_devices(
-        &mut self,
-        id: CommandId,
-        device_ids: Vec<OwnedDeviceId>,
-        auth: Option<InteractiveAuth>,
-        reply: Option<oneshot::Sender<Result<InteractiveAuthOutcome, CommandResultError>>>,
-    ) {
-        let events = self.port.event_sender();
-        let client = self.client.clone();
-        self.tasks.spawn(
-            TaskContext::Command {
-                id,
-                kind: CommandKind::Account,
-            },
-            async move {
-                let auth = match auth {
-                    Some(auth) => match auth.into_sdk(
-                        client
-                            .user_id()
-                            .expect("authentication was checked during construction"),
-                    ) {
-                        Ok(auth) => Some(auth),
-                        Err(message) => {
-                            let failure = CommandFailure {
-                                id,
-                                command: CommandKind::Account,
-                                kind: CommandErrorKind::Other,
-                                message: format!(
-                                    "interactive authentication data is invalid, {message}"
-                                ),
-                            };
-                            if let Some(reply) = reply {
-                                let _ =
-                                    reply.send(Err(CommandResultError::Failed(failure.clone())));
-                            } else {
-                                let _ = events.send(Event::CommandFailed(failure)).await;
-                            }
-                            return;
-                        }
-                    },
-                    None => None,
-                };
-                let result = client.delete_devices(&device_ids, auth).await;
-
-                match result {
-                    Ok(_) => {
-                        if let Some(reply) = reply {
-                            let _ = reply.send(Ok(InteractiveAuthOutcome::Completed));
-                        } else {
-                            let _ = emit_command_result(&events, id, CommandKind::Account, Ok(()))
-                                .await;
-                        }
-                    }
-                    Err(source) => {
-                        if let Some(info) = source.as_uiaa_response() {
-                            let challenge = InteractiveAuthChallenge::from(info);
-                            if let Some(reply) = reply {
-                                let _ =
-                                    reply.send(Ok(InteractiveAuthOutcome::Challenge(challenge)));
-                            } else {
-                                let _ = events
-                                    .send(Event::InteractiveAuthRequired {
-                                        id,
-                                        command: CommandKind::Account,
-                                        challenge: challenge.clone(),
-                                    })
-                                    .await;
-                                let _ = events
-                                    .send(Event::CommandFailed(CommandFailure {
-                                        id,
-                                        command: CommandKind::Account,
-                                        kind: CommandErrorKind::InteractiveAuthRequired,
-                                        message: "interactive authentication is required"
-                                            .to_owned(),
-                                    }))
-                                    .await;
-                            }
-                        } else {
-                            let error = CommandError::from_http("deleting devices failed", source);
-                            let failure = CommandFailure {
-                                id,
-                                command: CommandKind::Account,
-                                kind: error.kind,
-                                message: error.to_string(),
-                            };
-                            if let Some(reply) = reply {
-                                let _ =
-                                    reply.send(Err(CommandResultError::Failed(failure.clone())));
-                            } else {
-                                let _ = events.send(Event::CommandFailed(failure)).await;
-                            }
-                        }
-                    }
-                }
-            },
-        );
-    }
-
-    fn spawn_rename_device(
-        &mut self,
-        id: CommandId,
-        device_id: OwnedDeviceId,
-        display_name: String,
-    ) {
-        let events = self.port.event_sender();
-        let client = self.client.clone();
-        self.tasks.spawn(
-            TaskContext::Command {
-                id,
-                kind: CommandKind::Account,
-            },
-            async move {
-                match client.rename_device(&device_id, &display_name).await {
-                    Ok(_) => {
-                        let _ = events
-                            .send(Event::CommandSucceeded {
-                                id,
-                                command: CommandKind::Account,
-                            })
-                            .await;
-                    }
-                    Err(source) => {
-                        let error = CommandError::from_http("renaming device failed", source);
-                        let _ = events
-                            .send(Event::CommandFailed(CommandFailure {
-                                id,
-                                command: CommandKind::Account,
-                                kind: error.kind,
-                                message: error.to_string(),
-                            }))
-                            .await;
-                    }
-                }
-            },
-        );
-    }
-
-    fn spawn_global_account_data_write(
-        &mut self,
-        event_type: GlobalAccountDataEventType,
-        content: Raw<AnyGlobalAccountDataEventContent>,
-        reply: oneshot::Sender<Result<(), ClientQueryError>>,
-    ) {
-        let (done, next) = oneshot::channel();
-        let previous = self
-            .global_account_gates
-            .insert(event_type.to_string(), next);
-        let client = self.client.clone();
-        self.tasks.spawn(
-            TaskContext::Watcher("global account data writer"),
-            async move {
-                if let Some(previous) = previous {
-                    let _ = previous.await;
-                }
-                let result = client
-                    .account()
-                    .set_account_data_raw(event_type, content)
-                    .await
-                    .map(|_| ())
-                    .map_err(ClientQueryError::Sdk);
-                let _ = reply.send(result);
-                let _ = done.send(());
-            },
-        );
-    }
-
-    fn spawn_room_account_data_write(
-        &mut self,
-        room_id: OwnedRoomId,
-        event_type: RoomAccountDataEventType,
-        content: Raw<matrix_sdk::ruma::events::AnyRoomAccountDataEventContent>,
-        reply: oneshot::Sender<Result<(), ClientQueryError>>,
-    ) {
-        let (done, next) = oneshot::channel();
-        let previous = self
-            .room_account_gates
-            .insert((room_id.clone(), event_type.to_string()), next);
-        let client = self.client.clone();
-        self.tasks.spawn(
-            TaskContext::Watcher("room account data writer"),
-            async move {
-                if let Some(previous) = previous {
-                    let _ = previous.await;
-                }
-                let result = match client.get_room(&room_id) {
-                    Some(room) => room
-                        .set_account_data_raw(event_type, content)
-                        .await
-                        .map(|_| ())
-                        .map_err(ClientQueryError::Sdk),
-                    None => Err(ClientQueryError::RoomUnknown(room_id)),
-                };
-                let _ = reply.send(result);
-                let _ = done.send(());
-            },
-        );
-    }
-
-    fn start_domain_workers(&mut self) {
-        let mut notification_commands = self
-            .notification_command_receiver
-            .take()
-            .expect("notification worker has not started");
-        let notification_client = self.client.clone();
-        let notification_events = self.port.event_sender();
-        self.tasks.spawn(
-            TaskContext::Watcher("notification command worker"),
-            async move {
-                while let Some(CommandJob { id, command }) = notification_commands.recv().await {
-                    let result = AssertUnwindSafe(execute_notification_command(
-                        &notification_client,
-                        command,
-                    ))
-                    .catch_unwind()
-                    .await
-                    .unwrap_or_else(|_| {
-                        Err(CommandError::new(
-                            CommandErrorKind::Other,
-                            "notification command panicked",
-                        ))
-                    });
-                    let _ = emit_command_result(
-                        &notification_events,
-                        id,
-                        CommandKind::Notification,
-                        result,
-                    )
-                    .await;
-                }
-            },
-        );
-
-        let mut encryption_commands = self
-            .encryption_command_receiver
-            .take()
-            .expect("encryption worker has not started");
-        let encryption_client = self.client.clone();
-        let encryption_events = self.port.event_sender();
-        let verification = self.verification.clone();
-        self.tasks.spawn(
-            TaskContext::Watcher("encryption command worker"),
-            async move {
-                while let Some(work) = encryption_commands.recv().await {
-                    match work {
-                        EncryptionWork::Command(CommandJob { id, command }) => {
-                            if matches!(
-                                command,
-                                EncryptionCommand::Recover(_)
-                                    | EncryptionCommand::RecoverKeyBackup(_)
-                            ) {
-                                let result = AssertUnwindSafe(execute_encryption_command(
-                                    &encryption_client,
-                                    &encryption_events,
-                                    &mut VerificationController::default(),
-                                    command,
-                                ))
-                                .catch_unwind()
-                                .await
-                                .unwrap_or_else(|_| {
-                                    Err(CommandError::new(
-                                        CommandErrorKind::Other,
-                                        "encryption command panicked",
-                                    ))
-                                });
-                                let _ = emit_command_result(
-                                    &encryption_events,
-                                    id,
-                                    CommandKind::Encryption,
-                                    result,
-                                )
-                                .await;
-                                continue;
-                            }
-                            let is_key_backup = matches!(
-                                command,
-                                EncryptionCommand::CreateKeyBackup
-                                    | EncryptionCommand::EnableKeyBackup
-                                    | EncryptionCommand::DisableKeyBackup { .. }
-                            );
-                            let result = if is_key_backup {
-                                AssertUnwindSafe(execute_key_backup_command(
-                                    &encryption_client,
-                                    command,
-                                ))
-                                .catch_unwind()
-                                .await
-                                .unwrap_or_else(|_| {
-                                    Err(CommandError::new(
-                                        CommandErrorKind::Other,
-                                        "encryption command panicked",
-                                    ))
-                                })
-                            } else {
-                                let mut verification = verification.lock().await;
-                                let result = AssertUnwindSafe(execute_encryption_command(
-                                    &encryption_client,
-                                    &encryption_events,
-                                    &mut verification,
-                                    command,
-                                ))
-                                .catch_unwind()
-                                .await
-                                .unwrap_or_else(|_| {
-                                    Err(CommandError::new(
-                                        CommandErrorKind::Other,
-                                        "encryption command panicked",
-                                    ))
-                                });
-                                drop(verification);
-                                result
-                            };
-                            let _ = emit_command_result(
-                                &encryption_events,
-                                id,
-                                CommandKind::Encryption,
-                                result,
-                            )
-                            .await;
-                        }
-                    }
-                }
-            },
-        );
-
-        let room_commands = self
-            .room_command_receiver
-            .take()
-            .expect("room command worker has not started");
-        let room_client = self.client.clone();
-        let room_events = self.port.event_sender();
-        self.tasks.spawn(
-            TaskContext::Watcher("room command worker"),
-            run_room_command_worker(
-                room_client,
-                room_events,
-                room_commands,
-                self.room_command_capacity,
-            ),
-        );
-    }
-
-    fn start_watchers(&mut self) {
-        let mut session_changes = self
-            .session_changes
-            .take()
-            .expect("session watcher has not started");
-        let session_sender = self.port.event_sender();
-        let stop = self.stop.clone();
-        self.tasks
-            .spawn(TaskContext::Watcher("session change watcher"), async move {
-                loop {
-                    let event = match session_changes.recv().await {
-                        Ok(SessionChange::TokensRefreshed) => Event::SessionTokensChanged,
-                        Ok(SessionChange::UnknownToken(data)) => {
-                            let _ = session_sender
-                                .send(Event::SessionAccessRejected {
-                                    soft_logout: data.soft_logout,
-                                })
-                                .await;
-                            stop.notify_one();
-                            break;
-                        }
-                        Err(tokio::sync::broadcast::error::RecvError::Lagged(_)) => {
-                            Event::SessionTokensChanged
-                        }
-                        Err(tokio::sync::broadcast::error::RecvError::Closed) => break,
-                    };
-                    if session_sender.send(event).await.is_err() {
-                        break;
-                    }
-                }
-            });
-
-        let mut sync_states = self.sync.state();
-        let state_sender = self.port.event_sender();
-        let connection_sender = self.port.connection_sender();
-        let sync = self.sync.clone();
-        let client = self.client.clone();
-        self.tasks.spawn(
-            TaskContext::Watcher("connection state watcher"),
-            async move {
-                let mut backoff = SYNC_RESTART_MIN;
-                while let Some(state) = sync_states.next().await {
-                    let (state, restart) = match state {
-                        SyncState::Idle => (ConnectionState::Idle, false),
-                        SyncState::Running => {
-                            backoff = SYNC_RESTART_MIN;
-                            // the sdk parks a room queue on any send error and never unparks it
-                            client.send_queue().set_enabled(true).await;
-                            (ConnectionState::Online, false)
-                        }
-                        SyncState::Offline => (ConnectionState::Offline, false),
-                        SyncState::Terminated => (ConnectionState::Offline, true),
-                        SyncState::Error(error) => {
-                            tracing::warn!(error = %error, "sync service reported an error");
-                            (ConnectionState::Offline, true)
-                        }
-                    };
-                    if *connection_sender.borrow() != state {
-                        connection_sender.send_replace(state);
-                        if state_sender
-                            .send(Event::ConnectionChanged(state))
-                            .await
-                            .is_err()
-                        {
-                            break;
-                        }
-                    }
-                    if restart {
-                        tokio::time::sleep(backoff).await;
-                        backoff = (backoff * 2).min(SYNC_RESTART_MAX);
-                        sync.start().await;
-                    }
-                }
-            },
-        );
-
-        let client = self.client.clone();
-        let online = self.port.connection_sender().subscribe();
-        self.tasks
-            .spawn(TaskContext::Watcher("send queue watcher"), async move {
-                let mut errors = client.send_queue().subscribe_errors();
-                let mut retries = JoinSet::new();
-                loop {
-                    let error = tokio::select! {
-                        error = errors.recv() => error,
-                        Some(_) = retries.join_next(), if !retries.is_empty() => continue,
-                    };
-                    match error {
-                        Ok(error) if error.is_recoverable => {
-                            let client = client.clone();
-                            let online = online.clone();
-                            retries.spawn(async move {
-                                tokio::time::sleep(SEND_QUEUE_RETRY).await;
-                                if *online.borrow() == ConnectionState::Online
-                                    && let Some(room) = client.get_room(&error.room_id)
-                                {
-                                    room.send_queue().set_enabled(true);
-                                }
-                            });
-                        }
-                        Ok(_) | Err(tokio::sync::broadcast::error::RecvError::Lagged(_)) => {}
-                        Err(tokio::sync::broadcast::error::RecvError::Closed) => break,
-                    }
-                }
-            });
-
-        let client = self.client.clone();
-        let encryption_sender = self.port.event_sender();
-        self.tasks.spawn(
-            TaskContext::Watcher("encryption state watcher"),
-            async move {
-            let Some(device_id) = client.device_id().map(ToOwned::to_owned) else {
-                tracing::warn!("encryption watcher stopped because the client has no device id");
-                return;
-            };
-            let recovery = client.encryption().recovery();
-            let backups = client.encryption().backups();
-            let mut recovery_stream = recovery.state_stream();
-            let mut backup_stream = backups.state_stream();
-            let mut verification_stream = client.encryption().verification_state();
-            let mut recovery_state = recovery.state();
-            let mut backup_state = backups.state();
-            let mut verification_state = verification_stream.get();
-            if encryption_sender
-                .send(Event::EncryptionChanged(encryption_state(
-                    device_id.clone(),
-                    recovery_state,
-                    verification_state,
-                    backup_state,
-                )))
-                .await
-                .is_err()
-            {
-                tracing::debug!(
-                    "encryption watcher stopped because the event receiver closed"
-                );
-                return;
-            }
-            loop {
-                tokio::select! {
-                    update = recovery_stream.next() => {
-                        let Some(update) = update else {
-                            tracing::debug!("encryption watcher stopped because the recovery stream ended");
-                            break;
-                        };
-                        recovery_state = update;
-                    }
-                    update = verification_stream.next() => {
-                        let Some(update) = update else {
-                            tracing::debug!("encryption watcher stopped because the verification stream ended");
-                            break;
-                        };
-                        verification_state = update;
-                    }
-                    update = backup_stream.next() => {
-                        let Some(update) = update else {
-                            tracing::debug!("backup watcher stopped because the backup state stream ended");
-                            break;
-                        };
-                        backup_state = update.unwrap_or_else(|_| backups.state());
-                    }
-                }
-                if encryption_sender
-                    .send(Event::EncryptionChanged(encryption_state(
-                        device_id.clone(),
-                        recovery_state,
-                        verification_state,
-                        backup_state,
-                    )))
-                    .await
-                    .is_err()
-                {
-                    tracing::debug!(
-                        "encryption watcher stopped because the event receiver closed"
-                    );
-                    break;
-                }
-            }
-            },
-        );
-
-        let client = self.client.clone();
-        let room_sender = self.port.event_sender();
-        self.tasks.spawn(
-            TaskContext::Watcher("room list watcher"),
-            async move {
-            let (_, mut room_stream) = client.rooms_stream();
-            let mut info_stream = client.room_info_notable_update_receiver();
-            if room_sender.send(Event::RoomsChanged).await.is_err() {
-                tracing::debug!("room watcher stopped because the event receiver closed");
-                return;
-            }
-            loop {
-                tokio::select! {
-                    update = room_stream.next() => {
-                        if update.is_none() {
-                            tracing::debug!("room watcher stopped because the room stream ended");
-                            break;
-                        }
-                    }
-                    update = info_stream.recv() => {
-                        if update.is_err() && info_stream.is_closed() {
-                            tracing::debug!("room watcher stopped because the room info stream ended");
-                            break;
-                        }
-                    }
-                }
-                if room_sender.send(Event::RoomsChanged).await.is_err() {
-                    tracing::debug!("room watcher stopped because the event receiver closed");
-                    break;
-                }
-            }
-            },
-        );
-
-        let client = self.client.clone();
-        let notification_sender = self.port.event_sender();
-        self.tasks.spawn(
-            TaskContext::Watcher("notification settings watcher"),
-            async move {
-                let settings = client.notification_settings().await;
-                let mut changes = settings.subscribe_to_changes();
-                while let Ok(()) | Err(tokio::sync::broadcast::error::RecvError::Lagged(_)) =
-                    changes.recv().await
-                {
-                    if notification_sender
-                        .send(Event::NotificationSettingsChanged)
-                        .await
-                        .is_err()
-                    {
-                        break;
-                    }
-                }
-            },
-        );
-    }
-
-    async fn execute(&mut self, id: CommandId, command: Command) -> Result<bool, CommandError> {
-        match command {
-            Command::Account(AccountCommand::Logout) => {
-                self.spawn_logout(id);
-                Ok(true)
-            }
-            Command::Account(AccountCommand::RenameDevice {
-                device_id,
-                display_name,
-            }) => {
-                self.spawn_rename_device(id, device_id, display_name);
-                Ok(true)
-            }
-            Command::Account(AccountCommand::DeleteDevices { device_ids, auth }) => {
-                self.spawn_delete_devices(id, device_ids, auth, None);
-                Ok(true)
-            }
-            Command::Room(RoomCommand::Open(room_id)) => self.open_room(id, room_id).await,
-            Command::Room(RoomCommand::Close(room_id)) => self.close_room(id, &room_id).await,
-            Command::Room(RoomCommand::SetTyping { room_id, typing }) => {
-                self.spawn_typing(id, room_id, typing);
-                Ok(true)
-            }
-            Command::Room(RoomCommand::Join { room, via }) => {
-                self.spawn_room_command(id, RoomCommand::Join { room, via })
-            }
-            Command::Room(RoomCommand::Leave(room_id)) => {
-                self.spawn_room_command(id, RoomCommand::Leave(room_id))
-            }
-            Command::Room(RoomCommand::Forget(room_id)) => {
-                self.spawn_room_command(id, RoomCommand::Forget(room_id))
-            }
-            Command::Room(RoomCommand::AcceptInvite(room_id)) => {
-                self.spawn_room_command(id, RoomCommand::AcceptInvite(room_id))
-            }
-            Command::Room(RoomCommand::RejectInvite(room_id)) => {
-                self.spawn_room_command(id, RoomCommand::RejectInvite(room_id))
-            }
-            Command::Room(command @ RoomCommand::InviteUser { .. })
-            | Command::Room(command @ RoomCommand::KickUser { .. })
-            | Command::Room(command @ RoomCommand::BanUser { .. })
-            | Command::Room(command @ RoomCommand::UnbanUser { .. })
-            | Command::Room(command @ RoomCommand::SetPowerLevels { .. })
-            | Command::Room(command @ RoomCommand::SetUserPowerLevel { .. }) => {
-                self.spawn_room_command(id, command)
-            }
-            Command::Room(RoomCommand::Create(options)) => {
-                self.spawn_room_command(id, RoomCommand::Create(options))
-            }
-            Command::Room(RoomCommand::CreateDirect(user_id)) => {
-                self.spawn_room_command(id, RoomCommand::CreateDirect(user_id))
-            }
-            Command::Room(RoomCommand::CancelSend {
-                room_id,
-                transaction_id,
-            }) => {
-                self.spawn_cancel_send(id, room_id, transaction_id);
-                Ok(true)
-            }
-            Command::Room(RoomCommand::RetrySend {
-                room_id,
-                transaction_id,
-            }) => {
-                self.spawn_retry_send(id, room_id, transaction_id);
-                Ok(true)
-            }
-            Command::Timeline(command) => self.route_timeline(id, command),
-            Command::Media(MediaCommand::Fetch { id: media_id, size }) => {
-                self.spawn_media_fetch(id, media_id, size);
-                Ok(true)
-            }
-            Command::Media(MediaCommand::Upload {
-                timeline_id,
-                filename,
-                mimetype,
-                bytes,
-                caption,
-            }) => {
-                let mut upload = AttachmentUpload::new(timeline_id, filename, mimetype, bytes);
-                upload.caption = caption;
-                self.spawn_media_upload(id, upload).await.map(|()| true)
-            }
-            Command::Media(MediaCommand::UploadAttachment(upload)) => {
-                self.spawn_media_upload(id, upload).await.map(|()| true)
-            }
-            Command::Encryption(command) => {
-                self.encryption_commands
-                    .try_send(EncryptionWork::Command(CommandJob { id, command }))
-                    .map_err(|error| domain_queue_error(error, "encryption"))?;
-                Ok(true)
-            }
-            Command::Notification(command) => {
-                self.notification_commands
-                    .try_send(CommandJob { id, command })
-                    .map_err(|error| domain_queue_error(error, "notification"))?;
-                Ok(true)
-            }
-            Command::Lifecycle(LifecycleCommand::Shutdown) => Ok(false),
-        }
-    }
-
-    async fn open_room(
-        &mut self,
-        id: CommandId,
-        room_id: OwnedRoomId,
-    ) -> Result<bool, CommandError> {
-        match self.rooms.get_mut(&room_id) {
-            Some(RoomActorState::Opening { sender, .. }) => {
-                send_room_actor_request(sender, RoomActorRequest::Opened { id })?;
-                return Ok(true);
-            }
-            Some(RoomActorState::Open { .. }) => return Ok(false),
-            Some(RoomActorState::Closing { pending, .. }) => {
-                if pending.len() >= self.room_command_capacity {
-                    return Err(CommandError::new(
-                        CommandErrorKind::RoomBusy,
-                        "room lifecycle queue is full",
-                    ));
-                }
-                pending.push_back(DeferredRoomLifecycle::Open(id));
-                return Ok(true);
-            }
-            None => {}
-        }
-        self.start_room_actor(room_id, vec![id]).await?;
-        Ok(true)
-    }
-
-    async fn start_room_actor(
-        &mut self,
-        room_id: OwnedRoomId,
-        open_ids: Vec<CommandId>,
-    ) -> Result<(), CommandError> {
-        let room = self.client.get_room(&room_id).ok_or_else(|| {
-            CommandError::new(
-                CommandErrorKind::RoomUnknown,
-                "room is not available in the local store",
-            )
-        })?;
-        self.next_room_generation = self.next_room_generation.wrapping_add(1);
-        let generation = self.next_room_generation;
-        let (sender, receiver) = mpsc::channel(self.room_command_capacity);
-        let actor = RoomActor {
-            room_id: room_id.clone(),
-            generation,
-            room,
-            receiver,
-            events: self.port.event_sender(),
-            engine_events: self.room_actor_event_sender.clone(),
-            media: self.media.clone(),
-            initial_history_limit: self.initial_history_limit,
-            open_ids,
-            background: JoinSet::new(),
-            background_ids: HashMap::new(),
-        };
-        let current_user_id = self.client.user_id().map(ToOwned::to_owned);
-        self.rooms.insert(
-            room_id.clone(),
-            RoomActorState::Opening { generation, sender },
-        );
-        let actor_room_id = room_id.clone();
-        let engine_events = self.room_actor_event_sender.clone();
-        self.tasks.spawn(
-            TaskContext::RoomActor {
-                room_id: room_id.clone(),
-                generation,
-            },
-            async move {
-                actor.run(current_user_id).await;
-                let _ = engine_events.send(RoomActorEvent::Exited {
-                    room_id: actor_room_id,
-                    generation,
-                });
-            },
-        );
-        self.update_room_subscriptions().await;
-        Ok(())
-    }
-
-    fn spawn_room_command(
-        &mut self,
-        id: CommandId,
-        command: RoomCommand,
-    ) -> Result<bool, CommandError> {
-        self.spawn_room_command_with_reply(id, command, None)?;
-        Ok(true)
-    }
-
-    fn spawn_room_command_with_reply(
-        &mut self,
-        id: CommandId,
-        command: RoomCommand,
-        reply: Option<oneshot::Sender<Result<OwnedRoomId, CommandResultError>>>,
-    ) -> Result<(), CommandError> {
-        let job = RoomJob { id, command, reply };
-        self.room_commands.try_send(job).map_err(|error| {
-            let (job, kind, message) = match error {
-                mpsc::error::TrySendError::Full(job) => (
-                    job,
-                    CommandErrorKind::QueueFull,
-                    "room command queue is full",
-                ),
-                mpsc::error::TrySendError::Closed(job) => (
-                    job,
-                    CommandErrorKind::Other,
-                    "room command worker has stopped",
-                ),
-            };
-            let error = CommandError::new(kind, message);
-            if let Some(reply) = job.reply {
-                let _ = reply.send(Err(CommandResultError::Failed(CommandFailure {
-                    id: job.id,
-                    command: CommandKind::Room,
-                    kind: error.kind,
-                    message: error.to_string(),
-                })));
-            }
-            error
-        })
-    }
-
-    fn route_timeline(
-        &mut self,
-        id: CommandId,
-        command: TimelineCommand,
-    ) -> Result<bool, CommandError> {
-        let sender = self
-            .rooms
-            .get(command.room_id())
-            .and_then(RoomActorState::sender)
-            .cloned();
-        match (sender, command) {
-            (Some(sender), command) => {
-                send_room_actor_request(&sender, RoomActorRequest::Execute { id, command })?;
-            }
-            (
-                None,
-                TimelineCommand::MarkRead {
-                    timeline_id,
-                    event_id,
-                },
-            ) => self.spawn_mark_read(id, timeline_id, event_id),
-            (None, _) => {
-                return Err(CommandError::new(
-                    CommandErrorKind::RoomNotOpen,
-                    "room is not open",
-                ));
-            }
-        }
-        Ok(true)
-    }
-
-    async fn close_room(&mut self, id: CommandId, room_id: &RoomId) -> Result<bool, CommandError> {
-        let Some(state) = self.rooms.get_mut(room_id) else {
-            return Ok(false);
-        };
-        if let RoomActorState::Closing { pending, .. } = state {
-            if pending.len() >= self.room_command_capacity {
-                return Err(CommandError::new(
-                    CommandErrorKind::RoomBusy,
-                    "room lifecycle queue is full",
-                ));
-            }
-            pending.push_back(DeferredRoomLifecycle::Close(id));
-            return Ok(true);
-        }
-        let Some(sender) = state.sender().cloned() else {
-            return Ok(false);
-        };
-        let generation = state.generation();
-        send_room_actor_request(&sender, RoomActorRequest::Close { id })?;
-        self.rooms.insert(
-            room_id.to_owned(),
-            RoomActorState::Closing {
-                generation,
-                pending: VecDeque::new(),
-            },
-        );
-        self.update_room_subscriptions().await;
-        Ok(true)
-    }
-
-    async fn handle_room_actor_event(&mut self, event: RoomActorEvent) -> Result<(), EngineError> {
-        match event {
-            RoomActorEvent::Ready {
-                room_id,
-                generation,
-            } => {
-                let stale = self
-                    .rooms
-                    .get(&room_id)
-                    .is_none_or(|state| state.generation() != generation);
-                if stale {
-                    return Ok(());
-                }
-                let Some(state) = self.rooms.remove(&room_id) else {
-                    return Ok(());
-                };
-                match state {
-                    RoomActorState::Opening {
-                        generation: current,
-                        sender,
-                    } if current == generation => {
-                        self.rooms
-                            .insert(room_id, RoomActorState::Open { generation, sender });
-                    }
-                    state => {
-                        self.rooms.insert(room_id, state);
-                    }
-                }
-            }
-            RoomActorEvent::Exited {
-                room_id,
-                generation,
-            } => {
-                if self
-                    .rooms
-                    .get(&room_id)
-                    .is_none_or(|state| state.generation() != generation)
-                {
-                    return Ok(());
-                }
-                let state = self
-                    .rooms
-                    .remove(&room_id)
-                    .expect("room generation was checked");
-                let pending = match state {
-                    RoomActorState::Closing { pending, .. } => pending,
-                    RoomActorState::Opening { .. } | RoomActorState::Open { .. } => VecDeque::new(),
-                };
-                for operation in pending {
-                    let (id, result) = match operation {
-                        DeferredRoomLifecycle::Open(id) => {
-                            (id, self.open_room(id, room_id.clone()).await)
-                        }
-                        DeferredRoomLifecycle::Close(id) => {
-                            (id, self.close_room(id, &room_id).await)
-                        }
-                    };
-                    match result {
-                        Ok(true) => {}
-                        Ok(false) => emit_command_result(
-                            &self.port.event_sender(),
-                            id,
-                            CommandKind::Room,
-                            Ok(()),
-                        )
-                        .await
-                        .map_err(|_| EngineError::EventReceiverClosed)?,
-                        Err(error) => emit_command_result(
-                            &self.port.event_sender(),
-                            id,
-                            CommandKind::Room,
-                            Err(error),
-                        )
-                        .await
-                        .map_err(|_| EngineError::EventReceiverClosed)?,
-                    }
-                }
-                self.update_room_subscriptions().await;
-            }
-        }
-        Ok(())
-    }
-
-    async fn update_room_subscriptions(&self) {
-        let room_ids = self
-            .rooms
-            .iter()
-            .filter(|(_, state)| !matches!(state, RoomActorState::Closing { .. }))
-            .map(|(room_id, _)| room_id.clone())
-            .collect::<Vec<_>>();
-        let room_refs = room_ids.iter().map(AsRef::as_ref).collect::<Vec<_>>();
-        self.sync
-            .room_list_service()
-            .subscribe_to_rooms(&room_refs)
-            .await;
-    }
-
-    fn spawn_media_fetch(&mut self, command_id: CommandId, media_id: MediaId, size: MediaSize) {
-        let client = self.client.clone();
-        let media = self.media.clone();
-        let events = self.port.event_sender();
-        let max_media_bytes = self.max_media_bytes;
-        let flights = self.media_flights.clone();
-        self.tasks.spawn(
-            TaskContext::Command {
-                id: command_id,
-                kind: CommandKind::Media,
-            },
-            async move {
-                let leader = {
-                    let mut flights = flights.lock().await;
-                    let waiters = flights.entry((media_id.clone(), size)).or_default();
-                    waiters.push(command_id);
-                    waiters.len() == 1
-                };
-                if !leader {
-                    return;
-                }
-                let result = fetch_media(
-                    client,
-                    media,
-                    events.clone(),
-                    max_media_bytes,
-                    media_id.clone(),
-                    size,
-                )
-                .await;
-                let waiters = {
-                    let mut flights = flights.lock().await;
-                    flights.remove(&(media_id, size)).unwrap_or_default()
-                };
-                let result = match result {
-                    Ok(()) => Ok(()),
-                    Err(error) => {
-                        let kind = error.kind;
-                        let message = error.to_string();
-                        Err((kind, message))
-                    }
-                };
-                for waiter in waiters {
-                    let waiter_result = match &result {
-                        Ok(()) => Ok(()),
-                        Err((kind, message)) => Err(CommandError::new(*kind, message.clone())),
-                    };
-                    if emit_command_result(&events, waiter, CommandKind::Media, waiter_result)
-                        .await
-                        .is_err()
-                    {
-                        tracing::debug!(?waiter, "media fetch result was not delivered");
-                    }
-                }
-            },
-        );
-    }
-
-    async fn spawn_media_upload(
-        &mut self,
-        command_id: CommandId,
-        upload: AttachmentUpload,
-    ) -> Result<(), CommandError> {
-        let room_id = upload.timeline_id.room_id().clone();
-        let room = self.client.get_room(&room_id).ok_or_else(|| {
-            CommandError::new(
-                CommandErrorKind::RoomUnknown,
-                "room is not available in the local store",
-            )
-        })?;
-        if self
-            .upload_watchers
-            .get(&room_id)
-            .is_some_and(|(watcher, _)| watcher.is_finished())
-        {
-            self.upload_watchers.remove(&room_id);
-        }
-        let ready = if let Some((_, ready)) = self.upload_watchers.get(&room_id) {
-            ready.clone()
-        } else {
-            let (ready_sender, ready) = watch::channel(None);
-            let watched_room_id = room_id.clone();
-            let progress_room_id = room_id.clone();
-            let queued_room = room.clone();
-            let events = self.port.event_sender();
-            let watcher =
-                self.tasks
-                    .spawn(TaskContext::Watcher("media upload watcher"), async move {
-                        let (_, mut updates) = match queued_room.send_queue().subscribe().await {
-                            Ok(subscription) => subscription,
-                            Err(source) => {
-                                tracing::warn!(room_id = %progress_room_id, error = %source, "reading media send queue failed");
-                                ready_sender.send_replace(Some(Err(CommandErrorKind::Store)));
-                                return;
-                            }
-                        };
-                        ready_sender.send_replace(Some(Ok(())));
-                        loop {
-                            match updates.recv().await {
-                                Ok(RoomSendQueueUpdate::MediaUpload {
-                                    related_to,
-                                    file,
-                                    progress,
-                                    ..
-                                }) => {
-                                    if events
-                                        .send(Event::MediaUploadProgress {
-                                            room_id: progress_room_id.clone(),
-                                            transaction_id: related_to,
-                                            uploaded_bytes: progress.current as u64,
-                                            total_bytes: progress.total as u64,
-                                            complete: file.is_some()
-                                                && progress.current == progress.total,
-                                        })
-                                        .await
-                                        .is_err()
-                                    {
-                                        break;
-                                    }
-                                }
-                                Ok(RoomSendQueueUpdate::SendError {
-                                    transaction_id,
-                                    error,
-                                    is_recoverable,
-                                }) => {
-                                    let is_attachment = queued_room
-                                        .send_queue()
-                                        .subscribe()
-                                        .await
-                                        .is_ok_and(|(echoes, _)| {
-                                            echoes.iter().any(|echo| {
-                                                echo.transaction_id == transaction_id
-                                                    && is_attachment_echo(&echo.content)
-                                            })
-                                        });
-                                    if is_attachment
-                                        && events
-                                            .send(Event::MediaUploadFailed {
-                                                room_id: progress_room_id.clone(),
-                                                transaction_id,
-                                                kind: classify_sdk_error(&error),
-                                                recoverable: is_recoverable,
-                                            })
-                                            .await
-                                            .is_err()
-                                    {
-                                        break;
-                                    }
-                                }
-                                Ok(_)
-                                | Err(tokio::sync::broadcast::error::RecvError::Lagged(_)) => {}
-                                Err(tokio::sync::broadcast::error::RecvError::Closed) => break,
-                            }
-                        }
-                    });
-            self.upload_watchers
-                .insert(watched_room_id, (watcher, ready.clone()));
-            ready
-        };
-        let max_media_bytes = self.max_media_bytes;
-        let events = self.port.event_sender();
-        self.tasks.spawn(
-            TaskContext::Command {
-                id: command_id,
-                kind: CommandKind::Media,
-            },
-            async move {
-                let mut ready = ready;
-                let result = async {
-                    loop {
-                        if let Some(result) = *ready.borrow_and_update() {
-                            result.map_err(|kind| {
-                                CommandError::new(kind, "reading media send queue failed")
-                            })?;
-                            break;
-                        }
-                        ready.changed().await.map_err(|_| {
-                            CommandError::new(
-                                CommandErrorKind::Store,
-                                "media send queue watcher stopped",
-                            )
-                        })?;
-                    }
-                    queue_media_upload(room, upload, max_media_bytes).await
-                }
-                .await;
-                if emit_command_result(&events, command_id, CommandKind::Media, result)
-                    .await
-                    .is_err()
-                {
-                    tracing::debug!(?command_id, "media upload result was not delivered");
-                }
-            },
-        );
-        Ok(())
-    }
-
-    async fn shutdown(&mut self) {
-        self.tasks.shutdown().await;
-        self.verification.lock().await.stop().await;
-        self.rooms.clear();
-        self.upload_watchers.clear();
-        let mut media = self.media.lock().await;
-        media.entries.clear();
-        media.order.clear();
-        drop(media);
-        self.sync.stop().await;
-        self.port
-            .connection_sender()
-            .send_replace(ConnectionState::Stopped);
-        let _ = self
-            .port
-            .send(Event::ConnectionChanged(ConnectionState::Stopped))
-            .await;
-    }
-}
-
-async fn mark_read(
-    client: &Client,
-    timeline_id: &TimelineId,
-    event_id: OwnedEventId,
-) -> Result<(), CommandError> {
-    let room = client
-        .get_room(timeline_id.room_id())
-        .ok_or_else(room_unknown)?;
-    let receipt_thread = match timeline_id {
-        TimelineId::Room(_) => ReceiptThread::Main,
-        TimelineId::Thread { root_event_id, .. } => ReceiptThread::Thread(root_event_id.clone()),
-    };
-    room.send_single_receipt(ReceiptType::Read, receipt_thread, event_id.clone())
-        .await
-        .map_err(|source| CommandError::from_sdk("sending read receipt failed", source))?;
-    if matches!(timeline_id, TimelineId::Room(_)) {
-        room.send_single_receipt(ReceiptType::FullyRead, ReceiptThread::Unthreaded, event_id)
-            .await
-            .map_err(|source| {
-                CommandError::from_sdk("sending fully read receipt failed", source)
-            })?;
-    }
-    Ok(())
-}
-
-async fn set_typing(client: &Client, room_id: &RoomId, typing: bool) -> Result<(), CommandError> {
-    let room = client.get_room(room_id).ok_or_else(room_unknown)?;
-    room.typing_notice(typing)
-        .await
-        .map_err(|source| CommandError::from_sdk("typing update failed", source))
-}
-
-fn is_attachment_echo(content: &LocalEchoContent) -> bool {
-    let LocalEchoContent::Event {
-        serialized_event, ..
-    } = content
-    else {
-        return false;
-    };
-    matches!(
-        serialized_event.deserialize(),
-        Ok(AnyMessageLikeEventContent::RoomMessage(content))
-            if matches!(
-                content.msgtype,
-                MessageType::Audio(_) | MessageType::File(_) | MessageType::Image(_) | MessageType::Video(_)
-            )
-    )
-}
-
-async fn send_handle(
-    client: &Client,
-    room_id: &RoomId,
-    transaction_id: &matrix_sdk::ruma::TransactionId,
-) -> Result<SendHandle, CommandError> {
-    let room = client.get_room(room_id).ok_or_else(room_unknown)?;
-    let (echoes, _) = room.send_queue().subscribe().await.map_err(|source| {
-        CommandError::with_source(CommandErrorKind::Store, "reading send queue failed", source)
-    })?;
-    echoes
-        .into_iter()
-        .find_map(|echo| {
-            if echo.transaction_id.as_str() != transaction_id.as_str() {
-                return None;
-            }
-            match echo.content {
-                LocalEchoContent::Event { send_handle, .. } => Some(send_handle),
-                _ => None,
-            }
-        })
-        .ok_or_else(|| {
-            CommandError::new(
-                CommandErrorKind::Other,
-                "send is no longer pending or is not a message",
-            )
-        })
-}
-
-async fn cancel_send(
-    client: &Client,
-    room_id: &RoomId,
-    transaction_id: &matrix_sdk::ruma::TransactionId,
-) -> Result<(), CommandError> {
-    let handle = send_handle(client, room_id, transaction_id).await?;
-    match handle.abort().await {
-        Ok(true) => Ok(()),
-        Ok(false) => Err(CommandError::new(
-            CommandErrorKind::Other,
-            "send could not be cancelled because it has already been sent",
-        )),
-        Err(source) => Err(CommandError::with_source(
-            CommandErrorKind::Store,
-            "cancelling send failed",
-            source,
-        )),
-    }
-}
-
-async fn retry_send(
-    client: &Client,
-    room_id: &RoomId,
-    transaction_id: &matrix_sdk::ruma::TransactionId,
-) -> Result<(), CommandError> {
-    let handle = send_handle(client, room_id, transaction_id).await?;
-    handle.unwedge().await.map_err(|source| {
-        CommandError::with_source(CommandErrorKind::Store, "retrying send failed", source)
-    })?;
-    if let Some(room) = client.get_room(room_id) {
-        room.send_queue().set_enabled(true);
-    }
-    Ok(())
-}
-
-fn send_room_actor_request(
-    sender: &mpsc::Sender<RoomActorRequest>,
-    request: RoomActorRequest,
-) -> Result<(), CommandError> {
-    sender.try_send(request).map_err(|error| match error {
-        mpsc::error::TrySendError::Full(_) => {
-            CommandError::new(CommandErrorKind::RoomBusy, "room command queue is full")
-        }
-        mpsc::error::TrySendError::Closed(_) => {
-            CommandError::new(CommandErrorKind::RoomNotOpen, "room is not open")
-        }
-    })
-}
-
-fn domain_queue_error<T>(error: mpsc::error::TrySendError<T>, domain: &str) -> CommandError {
-    match error {
-        mpsc::error::TrySendError::Full(_) => CommandError::new(
-            CommandErrorKind::QueueFull,
-            format!("{domain} command queue is full"),
-        ),
-        mpsc::error::TrySendError::Closed(_) => CommandError::new(
-            CommandErrorKind::Other,
-            format!("{domain} command worker has stopped"),
-        ),
-    }
-}
-
-async fn run_room_command_worker(
-    client: Client,
-    events: EventSender,
-    mut commands: mpsc::Receiver<RoomJob>,
-    queue_limit: usize,
-) {
-    let mut queues = HashMap::<RoomMutationKey, VecDeque<RoomJob>>::new();
-    let mut running = HashSet::<RoomMutationKey>::new();
-    let mut tasks = JoinSet::<RoomJobCompletion>::new();
-    let mut receiving = true;
-    let mut queued = 0_usize;
-    while receiving || !tasks.is_empty() {
-        tokio::select! {
-            biased;
-            completed = tasks.join_next(), if !tasks.is_empty() => {
-                let completion = match completed {
-                    Some(Ok(completion)) => completion,
-                    Some(Err(error)) => panic!("room command task failed: {error}"),
-                    None => continue,
-                };
-                let key = completion.key.clone();
-                emit_room_job_result(&events, completion).await;
-                let next = queues.get_mut(&key).and_then(VecDeque::pop_front);
-                if next.is_some() {
-                    queued -= 1;
-                }
-                if queues.get(&key).is_some_and(VecDeque::is_empty) {
-                    queues.remove(&key);
-                }
-                if let Some(job) = next {
-                    spawn_room_job(&mut tasks, client.clone(), key, job);
-                } else {
-                    running.remove(&key);
-                }
-            }
-            job = commands.recv(), if receiving => {
-                match job {
-                    Some(job) => {
-                        let key = room_mutation_key(job.id, &job.command);
-                        if running.insert(key.clone()) {
-                            spawn_room_job(&mut tasks, client.clone(), key, job);
-                        } else if queued < queue_limit {
-                            queues.entry(key).or_default().push_back(job);
-                            queued += 1;
-                        } else {
-                            let failure = CommandFailure {
-                                id: job.id,
-                                command: CommandKind::Room,
-                                kind: CommandErrorKind::QueueFull,
-                                message: "room command queue is full".to_owned(),
-                            };
-                            if let Some(reply) = job.reply {
-                                let _ = reply.send(Err(CommandResultError::Failed(failure)));
-                            } else {
-                                let _ = events.send(Event::CommandFailed(failure)).await;
-                            }
-                        }
-                    }
-                    None => receiving = false,
-                }
-            }
-        }
-    }
-}
-
-fn spawn_room_job(
-    tasks: &mut JoinSet<RoomJobCompletion>,
-    client: Client,
-    key: RoomMutationKey,
-    job: RoomJob,
-) {
-    tasks.spawn(async move {
-        let RoomJob { id, command, reply } = job;
-        let result = AssertUnwindSafe(execute_room_command(&client, command))
-            .catch_unwind()
-            .await
-            .unwrap_or_else(|_| {
-                Err(CommandError::new(
-                    CommandErrorKind::Other,
-                    "room command panicked",
-                ))
-            });
-        RoomJobCompletion {
-            key,
-            id,
-            reply,
-            result,
-        }
-    });
-}
-
-fn room_mutation_key(id: CommandId, command: &RoomCommand) -> RoomMutationKey {
-    match command {
-        RoomCommand::Join { room, .. } if room.is_room_id() => RoomMutationKey::Room(
-            OwnedRoomId::try_from(room.clone()).expect("room ID variant was checked"),
-        ),
-        RoomCommand::Join { room, .. } => RoomMutationKey::Target(room.to_string()),
-        RoomCommand::Leave(room_id)
-        | RoomCommand::Forget(room_id)
-        | RoomCommand::AcceptInvite(room_id)
-        | RoomCommand::RejectInvite(room_id)
-        | RoomCommand::InviteUser { room_id, .. }
-        | RoomCommand::KickUser { room_id, .. }
-        | RoomCommand::BanUser { room_id, .. }
-        | RoomCommand::UnbanUser { room_id, .. }
-        | RoomCommand::SetPowerLevels { room_id, .. }
-        | RoomCommand::SetUserPowerLevel { room_id, .. } => RoomMutationKey::Room(room_id.clone()),
-        RoomCommand::CreateDirect(user_id) => RoomMutationKey::Direct(user_id.clone()),
-        _ => RoomMutationKey::Independent(id),
-    }
-}
-
-async fn emit_room_job_result(events: &EventSender, completion: RoomJobCompletion) {
-    let RoomJobCompletion {
-        id, reply, result, ..
-    } = completion;
-    match result {
-        Ok(Some(room_id)) => {
-            if let Some(reply) = reply {
-                let _ = reply.send(Ok(room_id.clone()));
-            } else {
-                let _ = emit_command_result_with_room(events, id, room_id).await;
-            }
-        }
-        Ok(None) => {
-            if let Some(reply) = reply {
-                let _ = reply.send(Err(CommandResultError::Failed(CommandFailure {
-                    id,
-                    command: CommandKind::Room,
-                    kind: CommandErrorKind::Other,
-                    message: "room operation did not return a room ID".to_owned(),
-                })));
-            } else {
-                let _ = emit_command_result(events, id, CommandKind::Room, Ok(())).await;
-            }
-        }
-        Err(error) => {
-            let failure = CommandFailure {
-                id,
-                command: CommandKind::Room,
-                kind: error.kind,
-                message: error.to_string(),
-            };
-            if let Some(reply) = reply {
-                let _ = reply.send(Err(CommandResultError::Failed(failure)));
-            } else {
-                let _ = events.send(Event::CommandFailed(failure)).await;
-            }
-        }
-    }
-}
-
-async fn execute_room_command(
-    client: &Client,
-    command: RoomCommand,
-) -> Result<Option<OwnedRoomId>, CommandError> {
-    match command {
-        RoomCommand::Join { room, via } => client
-            .join_room_by_id_or_alias(&room, &via)
-            .await
-            .map(|room| Some(room.room_id().to_owned()))
-            .map_err(|source| CommandError::from_sdk("joining room failed", source)),
-        RoomCommand::Leave(room_id) => match client.get_room(&room_id) {
-            Some(room) => room
-                .leave()
-                .await
-                .map(|_| None)
-                .map_err(|source| CommandError::from_sdk("leaving room failed", source)),
-            None => Err(room_unknown()),
-        },
-        RoomCommand::Forget(room_id) => match client.get_room(&room_id) {
-            Some(room) => room
-                .forget()
-                .await
-                .map(|_| None)
-                .map_err(|source| CommandError::from_sdk("forgetting room failed", source)),
-            None => Err(room_unknown()),
-        },
-        RoomCommand::AcceptInvite(room_id) => match client.get_room(&room_id) {
-            Some(room) => room
-                .join()
-                .await
-                .map(|_| None)
-                .map_err(|source| CommandError::from_sdk("accepting invite failed", source)),
-            None => Err(room_unknown()),
-        },
-        RoomCommand::RejectInvite(room_id) => match client.get_room(&room_id) {
-            Some(room) => room
-                .leave()
-                .await
-                .map(|_| None)
-                .map_err(|source| CommandError::from_sdk("rejecting invite failed", source)),
-            None => Err(room_unknown()),
-        },
-        RoomCommand::InviteUser { room_id, user_id } => match client.get_room(&room_id) {
-            Some(room) => room
-                .invite_user_by_id(&user_id)
-                .await
-                .map(|()| None)
-                .map_err(|source| CommandError::from_sdk("inviting user failed", source)),
-            None => Err(room_unknown()),
-        },
-        RoomCommand::KickUser {
-            room_id,
-            user_id,
-            reason,
-        } => match client.get_room(&room_id) {
-            Some(room) => room
-                .kick_user(&user_id, reason.as_deref())
-                .await
-                .map(|_| None)
-                .map_err(|source| CommandError::from_sdk("kicking user failed", source)),
-            None => Err(room_unknown()),
-        },
-        RoomCommand::BanUser {
-            room_id,
-            user_id,
-            reason,
-        } => match client.get_room(&room_id) {
-            Some(room) => room
-                .ban_user(&user_id, reason.as_deref())
-                .await
-                .map(|_| None)
-                .map_err(|source| CommandError::from_sdk("banning user failed", source)),
-            None => Err(room_unknown()),
-        },
-        RoomCommand::UnbanUser {
-            room_id,
-            user_id,
-            reason,
-        } => match client.get_room(&room_id) {
-            Some(room) => room
-                .unban_user(&user_id, reason.as_deref())
-                .await
-                .map(|_| None)
-                .map_err(|source| CommandError::from_sdk("unbanning user failed", source)),
-            None => Err(room_unknown()),
-        },
-        RoomCommand::SetPowerLevels { room_id, changes } => match client.get_room(&room_id) {
-            Some(room) => apply_power_level_changes(&room, changes)
-                .await
-                .map(|_| None),
-            None => Err(room_unknown()),
-        },
-        RoomCommand::SetUserPowerLevel {
-            room_id,
-            user_id,
-            level,
-        } => match client.get_room(&room_id) {
-            Some(room) => match matrix_sdk::ruma::Int::try_from(level) {
-                Ok(level) => room
-                    .update_power_levels(vec![(&user_id, level)])
-                    .await
-                    .map(|_| None)
-                    .map_err(|source| {
-                        CommandError::from_sdk("updating user power level failed", source)
-                    }),
-                Err(_) => Err(CommandError::new(
-                    CommandErrorKind::Other,
-                    "power level is outside the Matrix integer range",
-                )),
-            },
-            None => Err(room_unknown()),
-        },
-        RoomCommand::Create(options) => client
-            .create_room(create_room_request(options))
-            .await
-            .map(|room| Some(room.room_id().to_owned()))
-            .map_err(|source| CommandError::from_sdk("creating room failed", source)),
-        RoomCommand::CreateDirect(user_id) => match client.get_dm_room(&user_id) {
-            Some(room) => Ok(Some(room.room_id().to_owned())),
-            None => client
-                .create_dm(&user_id)
-                .await
-                .map(|room| Some(room.room_id().to_owned()))
-                .map_err(|source| CommandError::from_sdk("creating direct room failed", source)),
-        },
-        _ => Err(CommandError::new(
-            CommandErrorKind::Other,
-            "unsupported room command",
-        )),
-    }
-}
-
-fn room_unknown() -> CommandError {
-    CommandError::new(
-        CommandErrorKind::RoomUnknown,
-        "room is not available in the local store",
-    )
-}
-
-const fn sdk_notification_mode(
-    mode: RoomNotificationMode,
-) -> matrix_sdk::notification_settings::RoomNotificationMode {
-    match mode {
-        RoomNotificationMode::AllMessages => {
-            matrix_sdk::notification_settings::RoomNotificationMode::AllMessages
-        }
-        RoomNotificationMode::MentionsAndKeywordsOnly => {
-            matrix_sdk::notification_settings::RoomNotificationMode::MentionsAndKeywordsOnly
-        }
-        RoomNotificationMode::Mute => matrix_sdk::notification_settings::RoomNotificationMode::Mute,
-    }
-}
-
-async fn execute_notification_command(
-    client: &Client,
-    command: NotificationCommand,
-) -> Result<(), CommandError> {
-    use matrix_sdk::notification_settings::{IsEncrypted, IsOneToOne};
-
-    let settings = client.notification_settings().await;
-    let result = match command {
-        NotificationCommand::SetRoomMode { room_id, mode } => {
-            settings
-                .set_room_notification_mode(&room_id, sdk_notification_mode(mode))
-                .await
-        }
-        NotificationCommand::ResetRoomMode(room_id) => {
-            settings.delete_user_defined_room_rules(&room_id).await
-        }
-        NotificationCommand::SetDefaultMode {
-            encrypted,
-            one_to_one,
-            mode,
-        } => {
-            settings
-                .set_default_room_notification_mode(
-                    IsEncrypted::from(encrypted),
-                    IsOneToOne::from(one_to_one),
-                    sdk_notification_mode(mode),
-                )
-                .await
-        }
-        NotificationCommand::AddKeyword(keyword) => settings.add_keyword(keyword).await,
-        NotificationCommand::RemoveKeyword(keyword) => settings.remove_keyword(&keyword).await,
-    };
-    result.map_err(|source| {
-        CommandError::with_source(
-            CommandErrorKind::Server,
-            "updating notification settings failed",
-            source,
-        )
-    })
-}
-
-async fn execute_encryption_command(
-    client: &Client,
-    events: &EventSender,
-    verification: &mut VerificationController,
-    command: EncryptionCommand,
-) -> Result<(), CommandError> {
-    match command {
-        EncryptionCommand::Recover(key) => client
-            .encryption()
-            .recovery()
-            .recover(&key)
-            .await
-            .map_err(|source| CommandError::from_recovery("account recovery failed", source)),
-        EncryptionCommand::StartVerification(target) => {
-            verification.start(client, events.clone(), target).await
-        }
-        EncryptionCommand::Verify(action) => {
-            verification.apply(client, events.clone(), action).await
-        }
-        command => execute_key_backup_command(client, command).await,
-    }
-}
-
-async fn execute_key_backup_command(
-    client: &Client,
-    command: EncryptionCommand,
-) -> Result<(), CommandError> {
-    match command {
-        EncryptionCommand::CreateKeyBackup => client
-            .encryption()
-            .backups()
-            .create()
-            .await
-            .map_err(|source| CommandError::from_sdk("creating key backup failed", source)),
-        EncryptionCommand::EnableKeyBackup => client
-            .encryption()
-            .recovery()
-            .enable_backup()
-            .await
-            .map_err(|source| CommandError::from_recovery("enabling key backup failed", source)),
-        EncryptionCommand::DisableKeyBackup { delete_from_server } => {
-            let backups = client.encryption().backups();
-            if delete_from_server {
-                backups.disable_and_delete().await
-            } else {
-                backups.disable().await
-            }
-            .map_err(|source| CommandError::from_sdk("disabling key backup failed", source))
-        }
-        EncryptionCommand::RecoverKeyBackup(key) => client
-            .encryption()
-            .recovery()
-            .recover_and_fix_backup(&key)
-            .await
-            .map_err(|source| CommandError::from_recovery("recovering key backup failed", source)),
-        _ => unreachable!("only key backup commands are spawned here"),
-    }
-}
-
-async fn apply_power_level_changes(
-    room: &Room,
-    changes: PowerLevelChanges,
-) -> Result<(), CommandError> {
-    use matrix_sdk::ruma::events::{
-        MessageLikeEventType, StateEventType, room::power_levels::RoomPowerLevelsEventContent,
-    };
-
-    let mut levels = room
-        .power_levels()
-        .await
-        .map_err(|source| CommandError::from_sdk("reading power levels failed", source.into()))?;
-    if let Some(value) = changes.ban {
-        levels.ban = matrix_power_level(value)?;
-    }
-    if let Some(value) = changes.invite {
-        levels.invite = matrix_power_level(value)?;
-    }
-    if let Some(value) = changes.kick {
-        levels.kick = matrix_power_level(value)?;
-    }
-    if let Some(value) = changes.redact {
-        levels.redact = matrix_power_level(value)?;
-    }
-    if let Some(value) = changes.events_default {
-        levels.events_default = matrix_power_level(value)?;
-    }
-    if let Some(value) = changes.state_default {
-        levels.state_default = matrix_power_level(value)?;
-    }
-    if let Some(value) = changes.users_default {
-        levels.users_default = matrix_power_level(value)?;
-    }
-    if let Some(value) = changes.room_notification {
-        levels.notifications.room = matrix_power_level(value)?;
-    }
-    for (event_type, value) in [
-        (StateEventType::RoomName.into(), changes.room_name),
-        (StateEventType::RoomAvatar.into(), changes.room_avatar),
-        (StateEventType::RoomTopic.into(), changes.room_topic),
-        (StateEventType::SpaceChild.into(), changes.space_child),
-        (MessageLikeEventType::Beacon.into(), changes.beacon),
-        (StateEventType::BeaconInfo.into(), changes.beacon_info),
-    ] {
-        if let Some(value) = value {
-            levels.events.insert(event_type, matrix_power_level(value)?);
-        }
-    }
-    let content = RoomPowerLevelsEventContent::try_from(levels).map_err(|source| {
-        CommandError::with_source(
-            CommandErrorKind::Other,
-            "normalizing power levels failed",
-            source,
-        )
-    })?;
-    room.send_state_event(content)
-        .await
-        .map(|_| ())
-        .map_err(|source| CommandError::from_sdk("updating power levels failed", source))
-}
-
-fn matrix_power_level(value: i64) -> Result<matrix_sdk::ruma::Int, CommandError> {
-    value.try_into().map_err(|source| {
-        CommandError::with_source(
-            CommandErrorKind::Other,
-            "power level is outside the Matrix integer range",
-            source,
-        )
-    })
-}
-
-fn create_room_request(
-    options: CreateRoomOptions,
-) -> matrix_sdk::ruma::api::client::room::create_room::v3::Request {
-    use matrix_sdk::ruma::api::client::room::{
-        Visibility as SdkVisibility,
-        create_room::v3::{Request, RoomPreset as SdkPreset},
-    };
-    let mut request = Request::new();
-    request.name = options.name;
-    request.topic = options.topic;
-    request.room_alias_name = options.alias_localpart;
-    request.invite = options.invite;
-    request.is_direct = options.direct;
-    request.visibility = match options.visibility {
-        RoomVisibility::Private => SdkVisibility::Private,
-        RoomVisibility::Public => SdkVisibility::Public,
-    };
-    request.preset = options.preset.map(|preset| match preset {
-        RoomPreset::PrivateChat => SdkPreset::PrivateChat,
-        RoomPreset::TrustedPrivateChat => SdkPreset::TrustedPrivateChat,
-        RoomPreset::PublicChat => SdkPreset::PublicChat,
-    });
-    request
-}
-
-async fn queue_media_upload(
-    room: Room,
-    upload: AttachmentUpload,
-    max_media_bytes: usize,
-) -> Result<(), CommandError> {
-    let (upload, mime, mut config) = prepare_upload(upload, max_media_bytes)?;
-    if let TimelineId::Thread { root_event_id, .. } = &upload.timeline_id {
-        config.reply = Some(SdkReply {
-            event_id: root_event_id.clone(),
-            enforce_thread: EnforceThread::Threaded(ReplyWithinThread::No),
-            add_mentions: AddMentions::No,
-        });
-    }
-    room.send_queue()
-        .send_attachment(upload.filename, mime, upload.bytes, config)
-        .await
-        .map(|_| ())
-        .map_err(|source| {
-            CommandError::with_source(
-                CommandErrorKind::MediaUnavailable,
-                "media upload could not be queued",
-                source,
-            )
-        })
-}
-
-async fn fetch_media(
-    client: Client,
-    registry: Arc<Mutex<MediaRegistry>>,
-    events: EventSender,
-    max_media_bytes: usize,
-    media_id: MediaId,
-    size: MediaSize,
-) -> Result<(), CommandError> {
-    let media = registry
-        .lock()
-        .await
-        .get(&media_id)
-        .cloned()
-        .ok_or_else(|| {
-            CommandError::new(
-                CommandErrorKind::MediaUnknown,
-                "media is not registered in a retained timeline",
-            )
-        })?;
-    let (source, format, mimetype, declared_size) = match size {
-        MediaSize::Full => (
-            media.full.source,
-            MediaFormat::File,
-            media.full.mimetype,
-            media.full.declared_size,
-        ),
-        MediaSize::Thumbnail => {
-            if let Some(thumbnail) = media.thumbnail {
-                (
-                    thumbnail.source,
-                    MediaFormat::File,
-                    thumbnail.mimetype,
-                    thumbnail.declared_size,
-                )
-            } else if matches!(
-                media.kind,
-                crate::MediaKind::Image | crate::MediaKind::Video
-            ) && matches!(
-                &media.full.source,
-                matrix_sdk::ruma::events::room::MediaSource::Plain(_)
-            ) {
-                (
-                    media.full.source,
-                    MediaFormat::Thumbnail(MediaThumbnailSettings::new(
-                        800_u32.into(),
-                        800_u32.into(),
-                    )),
-                    media.full.mimetype,
-                    None,
-                )
-            } else {
-                return Err(CommandError::new(
-                    CommandErrorKind::MediaUnavailable,
-                    "the requested media size is unavailable",
-                ));
-            }
-        }
-    };
-    if declared_size.is_some_and(|size| size > max_media_bytes as u64) {
-        return Err(CommandError::new(
-            CommandErrorKind::MediaTooLarge,
-            "media exceeds the configured byte limit",
-        ));
-    }
-    let request = MediaRequestParameters { source, format };
-    if let Some(cached) = cached_media(&client, &request).await? {
-        if cached.len() > max_media_bytes {
-            remove_oversize_media(&client, &request).await;
-            return Err(CommandError::new(
-                CommandErrorKind::MediaTooLarge,
-                "cached media exceeds the configured byte limit",
-            ));
-        }
-        events
-            .send(Event::MediaReady {
-                media_id,
-                size,
-                bytes: Arc::from(cached),
-                mimetype: mimetype.unwrap_or_else(|| "application/octet-stream".into()),
-            })
-            .await
-            .map_err(send_error)?;
-        return Ok(());
-    }
-    let bytes = download_bounded(&client, &request, max_media_bytes).await?;
-    // the sdk caches plaintext under the encrypted key, so we do too or nobody can read anything
-    let bytes = maybe_decrypt_media(bytes, &request, max_media_bytes)?;
-    cache_media(&client, &request, &bytes).await;
-    events
-        .send(Event::MediaReady {
-            media_id,
-            size,
-            bytes: Arc::from(bytes),
-            mimetype: mimetype.unwrap_or_else(|| "application/octet-stream".into()),
-        })
-        .await
-        .map_err(send_error)
-}
-async fn cached_media(
-    client: &Client,
-    request: &MediaRequestParameters,
-) -> Result<Option<Vec<u8>>, CommandError> {
-    client
-        .media_store()
-        .lock()
-        .await
-        .map_err(|source| {
-            CommandError::with_source(
-                CommandErrorKind::Store,
-                "reading media cache failed",
-                source,
-            )
-        })?
-        .get_media_content(request)
-        .await
-        .map_err(|source| {
-            CommandError::with_source(
-                CommandErrorKind::Store,
-                "reading media cache failed",
-                source,
-            )
-        })
-}
-
-async fn remove_oversize_media(client: &Client, request: &MediaRequestParameters) {
-    if let Ok(store) = client.media_store().lock().await {
-        let _ = store.remove_media_content(request).await;
-    }
-}
-
-async fn cache_media(client: &Client, request: &MediaRequestParameters, bytes: &[u8]) {
-    if let Ok(store) = client.media_store().lock().await {
-        let _ = store
-            .add_media_content(
-                request,
-                bytes.to_vec(),
-                matrix_sdk::media::store::IgnoreMediaRetentionPolicy::No,
-            )
-            .await;
-    }
-}
-
-fn maybe_decrypt_media(
-    bytes: Vec<u8>,
-    request: &MediaRequestParameters,
-    max_media_bytes: usize,
-) -> Result<Vec<u8>, CommandError> {
-    let matrix_sdk::ruma::events::room::MediaSource::Encrypted(file) = &request.source else {
-        return Ok(bytes);
-    };
-    let info: MediaEncryptionInfo = (**file).clone().into();
-    let mut cursor = std::io::Cursor::new(bytes);
-    let mut decryptor = AttachmentDecryptor::new(&mut cursor, info).map_err(|source| {
-        CommandError::with_source(
-            CommandErrorKind::MediaUnavailable,
-            "media decryption failed",
-            source,
-        )
-    })?;
-    let mut decrypted = Vec::new();
-    let mut chunk = [0_u8; 8192];
-    loop {
-        match decryptor.read(&mut chunk) {
-            Ok(0) => break,
-            Ok(read) => {
-                if read > max_media_bytes.saturating_sub(decrypted.len()) {
-                    return Err(CommandError::new(
-                        CommandErrorKind::MediaTooLarge,
-                        "decrypted media exceeds the configured byte limit",
-                    ));
-                }
-                decrypted.extend_from_slice(&chunk[..read]);
-            }
-            Err(source) => {
-                return Err(CommandError::with_source(
-                    CommandErrorKind::MediaUnavailable,
-                    "media decryption failed",
-                    source,
-                ));
-            }
-        }
-    }
-    Ok(decrypted)
-}
-
-async fn download_bounded(
-    client: &Client,
-    request: &MediaRequestParameters,
-    max_media_bytes: usize,
-) -> Result<Vec<u8>, CommandError> {
-    if is_local_media(&request.source) {
-        return Err(CommandError::new(
-            CommandErrorKind::MediaUnavailable,
-            "local media is not in the media cache",
-        ));
-    }
-    let mut refreshed = false;
-    let request = loop {
-        let http_request = media_http_request(client, request).await?;
-        let response = client
-            .http_client()
-            .execute(request_from_http(client, http_request)?)
-            .await
-            .map_err(|source| {
-                CommandError::with_source(
-                    CommandErrorKind::Network,
-                    "media download failed",
-                    source,
-                )
-            })?;
-        if response.status() != matrix_sdk::reqwest::StatusCode::UNAUTHORIZED {
-            break response;
-        }
-        if refreshed
-            || client
-                .session_tokens()
-                .is_none_or(|tokens| tokens.refresh_token.is_none())
-        {
-            return Err(CommandError::new(
-                CommandErrorKind::Unauthenticated,
-                "media download was not authorized",
-            ));
-        }
-        client.refresh_access_token().await.map_err(|source| {
-            CommandError::from_refresh_token("refreshing media access token failed", source)
-        })?;
-        refreshed = true;
-    };
-    let status = request.status();
-    if !status.is_success() {
-        return Err(CommandError::new(
-            CommandErrorKind::MediaUnavailable,
-            format!("media download failed with status {status}"),
-        ));
-    }
-    if request
-        .content_length()
-        .is_some_and(|length| length > max_media_bytes as u64)
-    {
-        return Err(CommandError::new(
-            CommandErrorKind::MediaTooLarge,
-            "media exceeds the configured byte limit",
-        ));
-    }
-    let mut stream = request.bytes_stream();
-    let mut bytes = Vec::new();
-    while let Some(chunk) = stream.next().await {
-        let chunk = chunk.map_err(|source| {
-            CommandError::with_source(CommandErrorKind::Network, "media download failed", source)
-        })?;
-        if chunk.len() > max_media_bytes.saturating_sub(bytes.len()) {
-            return Err(CommandError::new(
-                CommandErrorKind::MediaTooLarge,
-                "downloaded media exceeds the configured byte limit",
-            ));
-        }
-        bytes.extend_from_slice(&chunk);
-    }
-    Ok(bytes)
-}
-
-fn is_local_media(source: &matrix_sdk::ruma::events::room::MediaSource) -> bool {
-    let uri = match source {
-        matrix_sdk::ruma::events::room::MediaSource::Plain(uri) => uri,
-        matrix_sdk::ruma::events::room::MediaSource::Encrypted(file) => &file.url,
-    };
-    let Ok(server) = uri.server_name() else {
-        return false;
-    };
-    server.as_str() == "send-queue.localhost"
-}
-
-async fn media_http_request(
-    client: &Client,
-    request: &MediaRequestParameters,
-) -> Result<http::Request<Vec<u8>>, CommandError> {
-    use matrix_sdk::ruma::api::client::{authenticated_media, media};
-
-    let versions = client.supported_versions().await.map_err(|source| {
-        CommandError::with_source(
-            CommandErrorKind::Network,
-            "reading supported server versions failed",
-            source,
-        )
-    })?;
-    let use_auth =
-        authenticated_media::get_content::v1::Request::PATH_BUILDER.is_supported(&versions);
-    let base = client.homeserver().to_string();
-    let token = client.access_token();
-    let build = |request: http::Request<Vec<u8>>| -> Result<http::Request<Vec<u8>>, CommandError> {
-        let mut request = request;
-        if let Some(token) = token.as_deref() {
-            request.headers_mut().insert(
-                http::header::AUTHORIZATION,
-                format!("Bearer {token}").parse().map_err(|_| {
-                    CommandError::new(
-                        CommandErrorKind::Unauthenticated,
-                        "stored access token is invalid",
-                    )
-                })?,
-            );
-        }
-        Ok(request)
-    };
-    match &request.source {
-        matrix_sdk::ruma::events::room::MediaSource::Encrypted(file) => {
-            if use_auth {
-                let endpoint = authenticated_media::get_content::v1::Request::from_uri(&file.url)
-                    .map_err(|source| {
-                    CommandError::with_source(
-                        CommandErrorKind::Other,
-                        "media URI is invalid",
-                        source,
-                    )
-                })?;
-                endpoint
-                    .try_into_http_request::<Vec<u8>>(
-                        &base,
-                        SendAccessToken::IfRequired(token.as_deref().unwrap_or("")),
-                        Cow::Borrowed(&versions),
-                    )
-                    .map_err(|_| {
-                        CommandError::new(
-                            CommandErrorKind::Unauthenticated,
-                            "media request could not be authorized",
-                        )
-                    })
-                    .and_then(build)
-            } else {
-                #[allow(deprecated)]
-                let endpoint =
-                    media::get_content::v3::Request::from_url(&file.url).map_err(|source| {
-                        CommandError::with_source(
-                            CommandErrorKind::Other,
-                            "media URI is invalid",
-                            source,
-                        )
-                    })?;
-                endpoint
-                    .try_into_http_request::<Vec<u8>>(
-                        &base,
-                        SendAccessToken::None,
-                        Cow::Borrowed(&versions),
-                    )
-                    .map_err(|_| {
-                        CommandError::new(CommandErrorKind::Other, "media request is invalid")
-                    })
-                    .and_then(build)
-            }
-        }
-        matrix_sdk::ruma::events::room::MediaSource::Plain(uri) => {
-            if let MediaFormat::Thumbnail(settings) = &request.format {
-                if use_auth {
-                    let mut endpoint =
-                        authenticated_media::get_content_thumbnail::v1::Request::from_uri(
-                            uri,
-                            settings.width,
-                            settings.height,
-                        )
-                        .map_err(|source| {
-                            CommandError::with_source(
-                                CommandErrorKind::Other,
-                                "media URI is invalid",
-                                source,
-                            )
-                        })?;
-                    endpoint.method = Some(settings.method.clone());
-                    endpoint.animated = Some(settings.animated);
-                    endpoint
-                        .try_into_http_request::<Vec<u8>>(
-                            &base,
-                            SendAccessToken::IfRequired(token.as_deref().unwrap_or("")),
-                            Cow::Borrowed(&versions),
-                        )
-                        .map_err(|_| {
-                            CommandError::new(
-                                CommandErrorKind::Unauthenticated,
-                                "media request could not be authorized",
-                            )
-                        })
-                        .and_then(build)
-                } else {
-                    #[allow(deprecated)]
-                    let endpoint = {
-                        let mut endpoint = media::get_content_thumbnail::v3::Request::from_url(
-                            uri,
-                            settings.width,
-                            settings.height,
-                        )
-                        .map_err(|source| {
-                            CommandError::with_source(
-                                CommandErrorKind::Other,
-                                "media URI is invalid",
-                                source,
-                            )
-                        })?;
-                        endpoint.method = Some(settings.method.clone());
-                        endpoint.animated = Some(settings.animated);
-                        endpoint
-                    };
-                    endpoint
-                        .try_into_http_request::<Vec<u8>>(
-                            &base,
-                            SendAccessToken::None,
-                            Cow::Borrowed(&versions),
-                        )
-                        .map_err(|_| {
-                            CommandError::new(CommandErrorKind::Other, "media request is invalid")
-                        })
-                        .and_then(build)
-                }
-            } else if use_auth {
-                let endpoint = authenticated_media::get_content::v1::Request::from_uri(uri)
-                    .map_err(|source| {
-                        CommandError::with_source(
-                            CommandErrorKind::Other,
-                            "media URI is invalid",
-                            source,
-                        )
-                    })?;
-                endpoint
-                    .try_into_http_request::<Vec<u8>>(
-                        &base,
-                        SendAccessToken::IfRequired(token.as_deref().unwrap_or("")),
-                        Cow::Borrowed(&versions),
-                    )
-                    .map_err(|_| {
-                        CommandError::new(
-                            CommandErrorKind::Unauthenticated,
-                            "media request could not be authorized",
-                        )
-                    })
-                    .and_then(build)
-            } else {
-                #[allow(deprecated)]
-                let endpoint =
-                    media::get_content::v3::Request::from_url(uri).map_err(|source| {
-                        CommandError::with_source(
-                            CommandErrorKind::Other,
-                            "media URI is invalid",
-                            source,
-                        )
-                    })?;
-                endpoint
-                    .try_into_http_request::<Vec<u8>>(
-                        &base,
-                        SendAccessToken::None,
-                        Cow::Borrowed(&versions),
-                    )
-                    .map_err(|_| {
-                        CommandError::new(CommandErrorKind::Other, "media request is invalid")
-                    })
-                    .and_then(build)
-            }
-        }
-    }
-}
-
-fn request_from_http(
-    client: &Client,
-    request: http::Request<Vec<u8>>,
-) -> Result<matrix_sdk::reqwest::Request, CommandError> {
-    let (parts, _) = request.into_parts();
-    let mut builder = client.http_client().get(parts.uri.to_string());
-    for (name, value) in parts.headers.iter() {
-        builder = builder.header(name.as_str(), value.as_bytes());
-    }
-    builder
-        .build()
-        .map_err(|_| CommandError::new(CommandErrorKind::Network, "media request is invalid"))
-}
-
-impl RoomActor {
-    async fn finish(
-        &mut self,
-        id: CommandId,
-        outcome: TimelineOutcome,
-    ) -> Result<(), SendEventError> {
-        match outcome {
-            TimelineOutcome::Done(result) => {
-                emit_command_result(&self.events, id, CommandKind::Timeline, result).await
-            }
-            TimelineOutcome::Background(work) => {
-                let task = self.background.spawn(async move { (id, work.await) });
-                self.background_ids.insert(task.id(), id);
-                Ok(())
-            }
-        }
-    }
-
-    async fn reap(&mut self, completed: BackgroundResult) -> Result<(), SendEventError> {
-        let (id, result) = match completed {
-            Ok((task_id, completed)) => {
-                self.background_ids.remove(&task_id);
-                completed
-            }
-            Err(error) => {
-                let Some(id) = self.background_ids.remove(&error.id()) else {
-                    return Ok(());
-                };
-                (
-                    id,
-                    Err(CommandError::new(
-                        CommandErrorKind::Other,
-                        "timeline operation panicked",
-                    )),
-                )
-            }
-        };
-        emit_command_result(&self.events, id, CommandKind::Timeline, result).await
-    }
-
-    async fn run(mut self, current_user_id: Option<ruma::OwnedUserId>) {
-        let timeline = match self
-            .room
-            .timeline_builder()
-            .with_focus(TimelineFocus::Live {
-                hide_threaded_events: true,
-            })
-            .track_read_marker_and_receipts(TimelineReadReceiptTracking::AllEvents)
-            .build()
-            .await
-        {
-            Ok(timeline) => timeline,
-            Err(error) => {
-                tracing::warn!(error = %error, room_id = %self.room_id, "room actor could not build its timeline");
-                let message = format!("room timeline build failed: {error}");
-                for id in self.open_ids.drain(..) {
-                    let _ = emit_command_result(
-                        &self.events,
-                        id,
-                        CommandKind::Room,
-                        Err(CommandError::new(
-                            CommandErrorKind::Timeline,
-                            message.clone(),
-                        )),
-                    )
-                    .await;
-                }
-                self.receiver.close();
-                while let Some(request) = self.receiver.recv().await {
-                    let (id, command) = match request {
-                        RoomActorRequest::Opened { id } | RoomActorRequest::Close { id } => {
-                            (id, CommandKind::Room)
-                        }
-                        RoomActorRequest::Execute { id, .. } => (id, CommandKind::Timeline),
-                    };
-                    let _ = emit_command_result(
-                        &self.events,
-                        id,
-                        command,
-                        Err(CommandError::new(
-                            CommandErrorKind::Timeline,
-                            "room timeline build failed",
-                        )),
-                    )
-                    .await;
-                }
-                return;
-            }
-        };
-        let room_timeline_id = TimelineId::Room(self.room_id.clone());
-        let mut room_timeline = match TimelineSession::start(
-            room_timeline_id,
-            timeline,
-            self.events.clone(),
-            self.media.clone(),
-            current_user_id.clone(),
-            self.initial_history_limit,
-        )
-        .await
-        {
-            Ok(timeline) => timeline,
-            Err(_) => return,
-        };
-        let _ = self.engine_events.send(RoomActorEvent::Ready {
-            room_id: self.room_id.clone(),
-            generation: self.generation,
-        });
-        for id in self.open_ids.drain(..) {
-            if emit_command_result(&self.events, id, CommandKind::Room, Ok(()))
-                .await
-                .is_err()
-            {
-                return;
-            }
-        }
-
-        let (typing_guard, mut typing_rx) = self.room.subscribe_to_typing_notifications();
-        let typing_sender = self.events.clone();
-        let typing_room_id = self.room_id.clone();
-        let mut room_tasks = JoinSet::new();
-        room_tasks.spawn(async move {
-            loop {
-                match typing_rx.recv().await {
-                    Ok(users) => {
-                        let state = TypingState {
-                            room_id: typing_room_id.clone(),
-                            users,
-                        };
-                        if typing_sender
-                            .send(Event::TypingChanged(state))
-                            .await
-                            .is_err()
-                        {
-                            tracing::debug!(
-                                room_id = %typing_room_id,
-                                "typing watcher stopped because the event receiver closed"
-                            );
-                            break;
-                        }
-                    }
-                    Err(tokio::sync::broadcast::error::RecvError::Lagged(skipped)) => {
-                        tracing::warn!(room_id = %typing_room_id, skipped, "typing watcher lagged");
-                    }
-                    Err(tokio::sync::broadcast::error::RecvError::Closed) => {
-                        tracing::debug!(room_id = %typing_room_id, "typing watcher stopped");
-                        break;
-                    }
-                }
-            }
-        });
-
-        enum QueuedThreadCommand {
-            Open {
-                id: CommandId,
-            },
-            Execute {
-                id: CommandId,
-                command: TimelineCommand,
-            },
-        }
-
-        struct OpeningThread {
-            generation: u64,
-            abort: AbortHandle,
-            task_id: TaskId,
-            queued: VecDeque<QueuedThreadCommand>,
-        }
-
-        let mut thread_timelines = HashMap::<OwnedEventId, TimelineSession>::new();
-        let mut opening_threads = HashMap::<OwnedEventId, OpeningThread>::new();
-        let mut thread_task_ids = HashMap::<TaskId, OwnedEventId>::new();
-        let mut thread_open_tasks = JoinSet::new();
-        let mut next_thread_generation = 0_u64;
-        let mut close_id = None;
-        let thread_queue_cap = self.receiver.max_capacity();
-        let mut queued_thread_count = 0;
-
-        let mut room_info = self.room.subscribe_info();
-        'actor: loop {
-            tokio::select! {
-                Some(info) = room_info.next() => {
-                    if matches!(info.state(), matrix_sdk::RoomState::Left | matrix_sdk::RoomState::Banned) {
-                        tracing::debug!(room_id = %self.room_id, "room actor stopped because we left the room");
-                        break 'actor;
-                    }
-                }
-                request = self.receiver.recv() => {
-                    let Some(request) = request else {
-                        tracing::debug!(room_id = %self.room_id, "room actor stopped because its request channel closed");
-                        break;
-                    };
-                    match request {
-                        RoomActorRequest::Opened { id } => {
-                            if emit_command_result(
-                                &self.events,
-                                id,
-                                CommandKind::Room,
-                                Ok(()),
-                            )
-                            .await
-                            .is_err()
-                            {
-                                break;
-                            }
-                        }
-                        RoomActorRequest::Execute { id, command } => {
-                            match command {
-                                TimelineCommand::OpenThread { root_event_id, .. } => {
-                                    if thread_timelines.contains_key(&root_event_id) {
-                                        if emit_command_result(
-                                            &self.events,
-                                            id,
-                                            CommandKind::Timeline,
-                                            Ok(()),
-                                        )
-                                        .await
-                                        .is_err()
-                                        {
-                                            break 'actor;
-                                        }
-                                    } else if let Some(opening) =
-                                        opening_threads.get_mut(&root_event_id)
-                                    {
-                                        if queued_thread_count >= thread_queue_cap {
-                                            if emit_command_result(
-                                                &self.events,
-                                                id,
-                                                CommandKind::Timeline,
-                                                Err(CommandError::new(
-                                                    CommandErrorKind::QueueFull,
-                                                    "thread command queue is full",
-                                                )),
-                                            )
-                                            .await
-                                            .is_err()
-                                            {
-                                                break 'actor;
-                                            }
-                                        } else {
-                                            opening
-                                                .queued
-                                                .push_back(QueuedThreadCommand::Open { id });
-                                            queued_thread_count += 1;
-                                        }
-                                    } else if queued_thread_count >= thread_queue_cap {
-                                        if emit_command_result(
-                                            &self.events,
-                                            id,
-                                            CommandKind::Timeline,
-                                            Err(CommandError::new(
-                                                CommandErrorKind::QueueFull,
-                                                "thread command queue is full",
-                                            )),
-                                        )
-                                        .await
-                                        .is_err()
-                                        {
-                                            break 'actor;
-                                        }
-                                    } else {
-                                        let generation = next_thread_generation;
-                                        next_thread_generation =
-                                            next_thread_generation.wrapping_add(1);
-                                        let task_root = root_event_id.clone();
-                                        let room = self.room.clone();
-                                        let abort = thread_open_tasks.spawn(async move {
-                                            let result = room
-                                                .timeline_builder()
-                                                .with_focus(TimelineFocus::Thread {
-                                                    root_event_id: root_event_id.clone(),
-                                                })
-                                                .track_read_marker_and_receipts(
-                                                    TimelineReadReceiptTracking::AllEvents,
-                                                )
-                                                .build()
-                                                .await;
-                                            (root_event_id, generation, result)
-                                        });
-                                        let task_id = abort.id();
-                                        thread_task_ids.insert(task_id, task_root.clone());
-                                        opening_threads.insert(
-                                            task_root,
-                                            OpeningThread {
-                                                generation,
-                                                abort,
-                                                task_id,
-                                                queued: VecDeque::from([
-                                                    QueuedThreadCommand::Open { id },
-                                                ]),
-                                            },
-                                        );
-                                        queued_thread_count += 1;
-                                    }
-                                }
-                                TimelineCommand::CloseThread { root_event_id, .. } => {
-                                    if let Some(timeline) = thread_timelines.remove(&root_event_id) {
-                                        timeline
-                                            .close(
-                                                CommandErrorKind::TimelineNotOpen,
-                                                "thread closed while pagination was in progress",
-                                            )
-                                            .await;
-                                        if emit_command_result(
-                                            &self.events,
-                                            id,
-                                            CommandKind::Timeline,
-                                            Ok(()),
-                                        )
-                                        .await
-                                        .is_err()
-                                        {
-                                            break 'actor;
-                                        }
-                                    } else if let Some(opening) =
-                                        opening_threads.remove(&root_event_id)
-                                    {
-                                        thread_task_ids.remove(&opening.task_id);
-                                        queued_thread_count -= opening.queued.len();
-                                        opening.abort.abort();
-                                        for queued in opening.queued {
-                                            let queued_id = match queued {
-                                                QueuedThreadCommand::Open { id } => id,
-                                                QueuedThreadCommand::Execute { id, .. } => id,
-                                            };
-                                            let _ = emit_command_result(
-                                                &self.events,
-                                                queued_id,
-                                                CommandKind::Timeline,
-                                                Err(CommandError::new(
-                                                    CommandErrorKind::TimelineNotOpen,
-                                                    "thread was closed before it finished opening",
-                                                )),
-                                            )
-                                            .await;
-                                        }
-                                        if emit_command_result(
-                                            &self.events,
-                                            id,
-                                            CommandKind::Timeline,
-                                            Ok(()),
-                                        )
-                                        .await
-                                        .is_err()
-                                        {
-                                            break 'actor;
-                                        }
-                                    } else if emit_command_result(
-                                        &self.events,
-                                        id,
-                                        CommandKind::Timeline,
-                                        Err(CommandError::new(
-                                            CommandErrorKind::TimelineNotOpen,
-                                            "thread timeline is not open",
-                                        )),
-                                    )
-                                    .await
-                                    .is_err()
-                                    {
-                                        break 'actor;
-                                    }
-                                }
-                                TimelineCommand::Paginate { timeline_id, limit } => {
-                                    match timeline_id {
-                                        TimelineId::Room(_) => {
-                                            room_timeline.paginate(limit, Some(id)).await;
-                                        }
-                                        TimelineId::Thread { room_id, root_event_id } => {
-                                            if let Some(timeline) =
-                                                thread_timelines.get_mut(&root_event_id)
-                                            {
-                                                timeline.paginate(limit, Some(id)).await;
-                                            } else if let Some(opening) =
-                                                opening_threads.get_mut(&root_event_id)
-                                            {
-                                                if queued_thread_count >= thread_queue_cap {
-                                                    if emit_command_result(
-                                                        &self.events,
-                                                        id,
-                                                        CommandKind::Timeline,
-                                                        Err(CommandError::new(
-                                                            CommandErrorKind::QueueFull,
-                                                            "thread command queue is full",
-                                                        )),
-                                                    )
-                                                    .await
-                                                    .is_err()
-                                                    {
-                                                        break 'actor;
-                                                    }
-                                                } else {
-                                                    opening.queued.push_back(
-                                                        QueuedThreadCommand::Execute {
-                                                            id,
-                                                            command:
-                                                                TimelineCommand::Paginate {
-                                                                    timeline_id:
-                                                                        TimelineId::Thread {
-                                                                            room_id,
-                                                                            root_event_id,
-                                                                        },
-                                                                    limit,
-                                                                },
-                                                        },
-                                                    );
-                                                    queued_thread_count += 1;
-                                                }
-                                            } else if emit_command_result(
-                                                &self.events,
-                                                id,
-                                                CommandKind::Timeline,
-                                                Err(CommandError::new(
-                                                    CommandErrorKind::TimelineNotOpen,
-                                                    "timeline is not open",
-                                                )),
-                                            )
-                                            .await
-                                            .is_err()
-                                            {
-                                                break 'actor;
-                                            }
-                                        }
-                                    }
-                                }
-                                command => {
-                                    let thread_target = match command
-                                        .timeline_id()
-                                        .expect("non-lifecycle timeline command has a timeline id")
-                                    {
-                                        TimelineId::Room(_) => None,
-                                        TimelineId::Thread { root_event_id, .. } => {
-                                            Some(root_event_id.clone())
-                                        }
-                                    };
-                                    match thread_target {
-                                        None => {
-                                            let result = execute_timeline_command(
-                                                &mut room_timeline,
-                                                command,
-                                                None,
-                                            )
-                                            .await;
-                                            if self.finish(id, result)
-                                            .await
-                                            .is_err()
-                                            {
-                                                tracing::debug!(room_id = %self.room_id, "room actor stopped because the event receiver closed");
-                                                break;
-                                            }
-                                        }
-                                        Some(root_event_id) => {
-                                            if let Some(timeline) =
-                                                thread_timelines.get_mut(&root_event_id)
-                                            {
-                                                let thread_root =
-                                                    timeline.id.thread_root().cloned();
-                                                let result = execute_timeline_command(
-                                                    timeline,
-                                                    command,
-                                                    thread_root.as_ref(),
-                                                )
-                                                .await;
-                                                if self.finish(id, result)
-                                                .await
-                                                .is_err()
-                                                {
-                                                    tracing::debug!(room_id = %self.room_id, "room actor stopped because the event receiver closed");
-                                                    break;
-                                                }
-                                            } else if let Some(opening) =
-                                                opening_threads.get_mut(&root_event_id)
-                                            {
-                                                if queued_thread_count >= thread_queue_cap {
-                                                    if emit_command_result(
-                                                        &self.events,
-                                                        id,
-                                                        CommandKind::Timeline,
-                                                        Err(CommandError::new(
-                                                            CommandErrorKind::QueueFull,
-                                                            "thread command queue is full",
-                                                        )),
-                                                    )
-                                                    .await
-                                                    .is_err()
-                                                    {
-                                                        break 'actor;
-                                                    }
-                                                } else {
-                                                    opening.queued.push_back(
-                                                        QueuedThreadCommand::Execute { id, command },
-                                                    );
-                                                    queued_thread_count += 1;
-                                                }
-                                            } else if emit_command_result(
-                                                &self.events,
-                                                id,
-                                                CommandKind::Timeline,
-                                                Err(CommandError::new(
-                                                    CommandErrorKind::TimelineNotOpen,
-                                                    "timeline is not open",
-                                                )),
-                                            )
-                                            .await
-                                            .is_err()
-                                            {
-                                                tracing::debug!(room_id = %self.room_id, "room actor stopped because the event receiver closed");
-                                                break;
-                                            }
-                                        }
-                                    }
-                                }
-                            }
-                        }
-                        RoomActorRequest::Close { id } => {
-                            close_id = Some(id);
-                            break 'actor;
-                        }
-                    }
-                }
-                completed = thread_open_tasks.join_next(), if !thread_open_tasks.is_empty() => {
-                    match completed {
-                        Some(Ok((root_event_id, generation, result))) => {
-                            if opening_threads
-                                .get(&root_event_id)
-                                .is_none_or(|opening| opening.generation != generation)
-                            {
-                                continue;
-                            }
-                            let opening = opening_threads
-                                .remove(&root_event_id)
-                                .expect("thread generation was checked");
-                            thread_task_ids.remove(&opening.task_id);
-                            queued_thread_count -= opening.queued.len();
-                            match result {
-                                Ok(timeline) => {
-                                    let timeline_id = TimelineId::thread(
-                                        self.room_id.clone(),
-                                        root_event_id.clone(),
-                                    );
-                                    match TimelineSession::start(
-                                        timeline_id,
-                                        timeline,
-                                        self.events.clone(),
-                                        self.media.clone(),
-                                        current_user_id.clone(),
-                                        self.initial_history_limit,
-                                    )
-                                    .await
-                                    {
-                                        Ok(session) => {
-                                            thread_timelines
-                                                .insert(root_event_id.clone(), session);
-                                            let timeline = thread_timelines
-                                                .get_mut(&root_event_id)
-                                                .expect("thread session was inserted");
-                                            for queued in opening.queued {
-                                                match queued {
-                                                    QueuedThreadCommand::Open { id } => {
-                                                        if emit_command_result(
-                                                            &self.events,
-                                                            id,
-                                                            CommandKind::Timeline,
-                                                            Ok(()),
-                                                        )
-                                                        .await
-                                                        .is_err()
-                                                        {
-                                                            break 'actor;
-                                                        }
-                                                    }
-                                                    QueuedThreadCommand::Execute {
-                                                        id,
-                                                        command,
-                                                    } => match command {
-                                                        TimelineCommand::Paginate {
-                                                            limit,
-                                                            ..
-                                                        } => {
-                                                            timeline
-                                                                .paginate(limit, Some(id))
-                                                                .await;
-                                                        }
-                                                        command => {
-                                                            let thread_root = timeline
-                                                                .id
-                                                                .thread_root()
-                                                                .cloned();
-                                                            let result =
-                                                                execute_timeline_command(
-                                                                    timeline,
-                                                                    command,
-                                                                    thread_root.as_ref(),
-                                                                )
-                                                                .await;
-                                                            if self.finish(id, result)
-                                                            .await
-                                                            .is_err()
-                                                            {
-                                                                break 'actor;
-                                                            }
-                                                        }
-                                                    },
-                                                }
-                                            }
-                                        }
-                                        Err(_) => break 'actor,
-                                    }
-                                }
-                                Err(error) => {
-                                    tracing::warn!(error = %error, room_id = %self.room_id, %root_event_id, "thread timeline build failed");
-                                    let message = format!("thread timeline build failed: {error}");
-                                    for queued in opening.queued {
-                                        let queued_id = match queued {
-                                            QueuedThreadCommand::Open { id } => id,
-                                            QueuedThreadCommand::Execute { id, .. } => id,
-                                        };
-                                        if emit_command_result(
-                                            &self.events,
-                                            queued_id,
-                                            CommandKind::Timeline,
-                                            Err(CommandError::new(
-                                                CommandErrorKind::Timeline,
-                                                message.clone(),
-                                            )),
-                                        )
-                                        .await
-                                        .is_err()
-                                        {
-                                            break 'actor;
-                                        }
-                                    }
-                                }
-                            }
-                        }
-                        Some(Err(error)) => {
-                            if let Some(root_event_id) = thread_task_ids.remove(&error.id()) {
-                                tracing::warn!(error = %error, room_id = %self.room_id, %root_event_id, "thread open task failed");
-                                if let Some(opening) = opening_threads.remove(&root_event_id) {
-                                    queued_thread_count -= opening.queued.len();
-                                    for queued in opening.queued {
-                                        let queued_id = match queued {
-                                            QueuedThreadCommand::Open { id } => id,
-                                            QueuedThreadCommand::Execute { id, .. } => id,
-                                        };
-                                        if emit_command_result(
-                                            &self.events,
-                                            queued_id,
-                                            CommandKind::Timeline,
-                                            Err(CommandError::new(
-                                                CommandErrorKind::Timeline,
-                                                "thread timeline build task failed",
-                                            )),
-                                        )
-                                        .await
-                                        .is_err()
-                                        {
-                                            break 'actor;
-                                        }
-                                    }
-                                }
-                            } else {
-                                tracing::debug!(error = %error, room_id = %self.room_id, "thread open task was aborted");
-                            }
-                        }
-                        None => {}
-                    }
-                }
-                Some(completed) = self.background.join_next_with_id(), if !self.background.is_empty() => {
-                    if self.reap(completed).await.is_err() {
-                        break 'actor;
-                    }
-                }
-                completed = room_tasks.join_next(), if !room_tasks.is_empty() => {
-                    match completed {
-                        Some(Err(error)) => {
-                            tracing::warn!(error = %error, room_id = %self.room_id, "room actor task failed");
-                        }
-                        Some(Ok(())) => {
-                            tracing::warn!(room_id = %self.room_id, "room actor task stopped unexpectedly");
-                        }
-                        None => {}
-                    }
-                }
-            }
-        }
-
-        while let Some(completed) = self.background.join_next_with_id().await {
-            let _ = self.reap(completed).await;
-        }
-        drop(typing_guard);
-        room_tasks.abort_all();
-        while room_tasks.join_next().await.is_some() {}
-        thread_task_ids.clear();
-        let pending_opens = opening_threads
-            .drain()
-            .flat_map(|(_, opening)| opening.queued)
-            .collect::<Vec<_>>();
-        for queued in pending_opens {
-            let queued_id = match queued {
-                QueuedThreadCommand::Open { id } => id,
-                QueuedThreadCommand::Execute { id, .. } => id,
-            };
-            let _ = emit_command_result(
-                &self.events,
-                queued_id,
-                CommandKind::Timeline,
-                Err(CommandError::new(
-                    CommandErrorKind::RoomNotOpen,
-                    "room closed while thread timeline was opening",
-                )),
-            )
-            .await;
-        }
-        thread_open_tasks.abort_all();
-        while thread_open_tasks.join_next().await.is_some() {}
-        for (_, timeline) in thread_timelines {
-            timeline
-                .close(
-                    CommandErrorKind::RoomNotOpen,
-                    "room closed while thread pagination was in progress",
-                )
-                .await;
-        }
-        room_timeline
-            .close(
-                CommandErrorKind::RoomNotOpen,
-                "room closed while pagination was in progress",
-            )
-            .await;
-        if let Some(id) = close_id
-            && emit_command_result(&self.events, id, CommandKind::Room, Ok(()))
-                .await
-                .is_err()
-        {
-            tracing::debug!(room_id = %self.room_id, "room close acknowledgement was not delivered");
-        }
-    }
-}
-
-async fn execute_timeline_command(
-    session: &mut TimelineSession,
-    command: TimelineCommand,
-    thread_root: Option<&OwnedEventId>,
-) -> TimelineOutcome {
-    let timeline = session.timeline.clone();
-    let work: BackgroundWork = match command {
-        TimelineCommand::Redact {
-            event_id, reason, ..
-        } => Box::pin(async move {
-            timeline
-                .redact(&TimelineEventItemId::EventId(event_id), reason.as_deref())
-                .await
-                .map_err(timeline_error)
-        }),
-        TimelineCommand::ToggleReaction { event_id, key, .. } => Box::pin(async move {
-            timeline
-                .toggle_reaction(&TimelineEventItemId::EventId(event_id), &key)
-                .await
-                .map(|_| ())
-                .map_err(timeline_error)
-        }),
-        TimelineCommand::MarkRead { event_id, .. } => {
-            let thread = thread_root.is_some();
-            Box::pin(async move {
-                let receipt_failed =
-                    |source| CommandError::from_sdk("sending read receipt failed", source);
-                timeline
-                    .send_single_receipt(ReceiptType::Read, event_id.clone())
-                    .await
-                    .map_err(receipt_failed)?;
-                if !thread {
-                    timeline
-                        .send_single_receipt(ReceiptType::FullyRead, event_id)
-                        .await
-                        .map_err(receipt_failed)?;
-                }
-                Ok(())
-            })
-        }
-        command => {
-            return TimelineOutcome::Done(
-                execute_serial_timeline_command(session, command, thread_root).await,
-            );
-        }
-    };
-    TimelineOutcome::Background(work)
-}
-
-async fn execute_serial_timeline_command(
-    session: &mut TimelineSession,
-    command: TimelineCommand,
-    thread_root: Option<&OwnedEventId>,
-) -> Result<(), CommandError> {
-    let timeline = &session.timeline;
-    match command {
-        TimelineCommand::OpenThread { .. }
-        | TimelineCommand::CloseThread { .. }
-        | TimelineCommand::Redact { .. }
-        | TimelineCommand::ToggleReaction { .. }
-        | TimelineCommand::MarkRead { .. } => Err(CommandError::new(
-            CommandErrorKind::Other,
-            "timeline command was misrouted",
-        )),
-        TimelineCommand::Resync { .. } => session.resync().await.map_err(|_| {
-            CommandError::new(
-                CommandErrorKind::Timeline,
-                "timeline resync could not emit a reset",
-            )
-        }),
-        TimelineCommand::Paginate { .. } => Ok(()),
-        TimelineCommand::Send { content, .. } => {
-            let body = match &content {
-                MessageContent::Text { content, .. }
-                | MessageContent::Emote { content, .. }
-                | MessageContent::Reply { content, .. } => &content.body,
-            };
-            if body.trim().is_empty() {
-                return Err(CommandError::new(
-                    CommandErrorKind::EmptyBody,
-                    "message body is empty",
-                ));
-            }
-            match content {
-                MessageContent::Text { content, mentions } => timeline
-                    .send(
-                        message_content(content, mentions, false)
-                            .with_relation(None)
-                            .into(),
-                    )
-                    .await
-                    .map(|_| ())
-                    .map_err(timeline_error),
-                MessageContent::Emote { content, mentions } => timeline
-                    .send(
-                        message_content(content, mentions, true)
-                            .with_relation(None)
-                            .into(),
-                    )
-                    .await
-                    .map(|_| ())
-                    .map_err(timeline_error),
-                MessageContent::Reply {
-                    event_id,
-                    content,
-                    mentions,
-                    notify_replied_to,
-                } => {
-                    let content = timeline
-                        .room()
-                        .make_reply_event(
-                            message_content(content, mentions, false),
-                            SdkReply {
-                                event_id,
-                                enforce_thread: if thread_root.is_some() {
-                                    EnforceThread::Threaded(ReplyWithinThread::Yes)
-                                } else {
-                                    EnforceThread::MaybeThreaded
-                                },
-                                add_mentions: if notify_replied_to {
-                                    AddMentions::Yes
-                                } else {
-                                    AddMentions::No
-                                },
-                            },
-                        )
-                        .await
-                        .map_err(|source| {
-                            CommandError::with_source(
-                                CommandErrorKind::Timeline,
-                                "reply operation failed",
-                                source,
-                            )
-                        })?;
-                    if let Some(thread_root) = thread_root
-                        && !matches!(
-                            content.relates_to.as_ref(),
-                            Some(Relation::Thread(thread)) if &thread.event_id == thread_root
-                        )
-                    {
-                        return Err(CommandError::new(
-                            CommandErrorKind::Timeline,
-                            "reply target does not belong to the selected thread",
-                        ));
-                    }
-                    timeline
-                        .send(content.into())
-                        .await
-                        .map(|_| ())
-                        .map_err(timeline_error)
-                }
-            }
-        }
-        TimelineCommand::Edit {
-            event_id, content, ..
-        } => {
-            let (content, mentions, emote) = match content {
-                MessageEditContent::Text { content, mentions } => (content, mentions, false),
-                MessageEditContent::Emote { content, mentions } => (content, mentions, true),
-            };
-            if content.body.trim().is_empty() {
-                return Err(CommandError::new(
-                    CommandErrorKind::EmptyBody,
-                    "message body is empty",
-                ));
-            }
-            timeline
-                .edit(
-                    &TimelineEventItemId::EventId(event_id),
-                    EditedContent::RoomMessage(message_content(content, mentions, emote)),
-                )
-                .await
-                .map_err(timeline_error)
-        }
-    }
-}
-
-fn message_content(
-    content: RichText,
-    mentions: MessageMentions,
-    emote: bool,
-) -> RoomMessageEventContentWithoutRelation {
-    let content = match content.formatted_body {
-        Some(formatted_body) if emote => {
-            RoomMessageEventContentWithoutRelation::emote_html(content.body, formatted_body)
-        }
-        Some(formatted_body) => {
-            RoomMessageEventContentWithoutRelation::text_html(content.body, formatted_body)
-        }
-        None if emote => RoomMessageEventContentWithoutRelation::emote_plain(content.body),
-        None => RoomMessageEventContentWithoutRelation::text_plain(content.body),
-    };
-    let content = content.add_mentions(Mentions::with_user_ids(mentions.user_ids));
-    if mentions.room {
-        content.add_mentions(Mentions::with_room_mention())
-    } else {
-        content
-    }
-}
-
-async fn run_pagination(request: PaginationRequest) {
-    let PaginationRequest {
-        timeline,
-        events,
-        timeline_id,
-        limit,
-        command_id,
-        results,
-    } = request;
-    if events
-        .send(Event::HistoryChanged {
-            timeline_id: timeline_id.clone(),
-            state: HistoryState::Loading,
-        })
-        .await
-        .is_err()
-    {
-        if let Some(id) = command_id {
-            let _ = results.send((
-                id,
-                Err(CommandError::new(
-                    CommandErrorKind::EventReceiverClosed,
-                    "event receiver has closed",
-                )),
-            ));
-        }
-        return;
-    }
-    let result = timeline
-        .paginate_backwards(limit.max(1))
-        .await
-        .map_err(timeline_error);
-    match result {
-        Ok(at_start) => {
-            let _ = events
-                .send(Event::HistoryChanged {
-                    timeline_id,
-                    state: if at_start {
-                        HistoryState::StartReached
-                    } else {
-                        HistoryState::Idle
-                    },
-                })
-                .await;
-            if let Some(id) = command_id {
-                let _ = results.send((id, Ok(())));
-            }
-        }
-        Err(error) => {
-            let _ = events
-                .send(Event::HistoryChanged {
-                    timeline_id,
-                    state: HistoryState::Failed(error.to_string()),
-                })
-                .await;
-            if let Some(id) = command_id {
-                let _ = results.send((id, Err(error)));
-            }
-        }
-    }
-}
-
-async fn emit_command_result_with_room(
-    events: &EventSender,
-    id: CommandId,
-    room_id: OwnedRoomId,
-) -> Result<(), SendEventError> {
-    events
-        .send(Event::CommandSucceededWithRoom {
-            id,
-            command: CommandKind::Room,
-            room_id,
-        })
-        .await
-}
-
-async fn emit_command_result(
-    events: &EventSender,
-    id: CommandId,
-    command: CommandKind,
-    result: Result<(), CommandError>,
-) -> Result<(), SendEventError> {
-    let event = match result {
-        Ok(()) => Event::CommandSucceeded { id, command },
-        Err(error) => {
-            tracing::warn!(?id, ?command, error = ?error, "room actor command failed");
-            Event::CommandFailed(CommandFailure {
-                id,
-                command,
-                kind: error.kind,
-                message: error.to_string(),
-            })
-        }
-    };
-    events.send(event).await
-}
-
-fn send_error(source: SendEventError) -> CommandError {
-    CommandError::with_source(
-        CommandErrorKind::EventReceiverClosed,
-        "event receiver has closed",
-        source,
-    )
-}
-
-fn timeline_error(source: matrix_sdk_ui::timeline::Error) -> CommandError {
-    CommandError::with_source(
-        CommandErrorKind::Timeline,
-        "timeline operation failed",
-        source,
-    )
-}

Added file: src/engine/commands.rs+319 additions@@ -0,0 +1,319 @@
+use std::{future::Future, panic::AssertUnwindSafe};
+
+use futures_util::FutureExt;
+use matrix_sdk::{
+    Client,
+    notification_settings::{IsEncrypted, IsOneToOne, RoomNotificationMode as SdkMode},
+    ruma::{
+        OwnedDeviceId, OwnedEventId, RoomId, TransactionId,
+        api::client::receipt::create_receipt::v3::ReceiptType, events::receipt::ReceiptThread,
+    },
+    send_queue::{LocalEchoContent, SendHandle},
+};
+use tokio::sync::mpsc;
+
+use crate::{
+    EncryptionCommand, Error, ErrorKind, InteractiveAuth, InteractiveAuthChallenge,
+    NotificationCommand, RoomNotificationMode, TimelineId,
+    encryption::VerificationController,
+    transport::{EventSender, Responder},
+};
+
+pub(super) struct Job<T> {
+    pub(super) command: T,
+    pub(super) reply: Responder,
+}
+
+/// a panicking command answers with an error instead of taking its worker down with it
+pub(super) async fn guarded<T>(
+    label: &'static str,
+    work: impl Future<Output = Result<T, Error>>,
+) -> Result<T, Error> {
+    AssertUnwindSafe(work)
+        .catch_unwind()
+        .await
+        .unwrap_or_else(|_| Err(Error::new(ErrorKind::Other, format!("{label} panicked"))))
+}
+
+pub(super) async fn run_notifications(
+    client: Client,
+    mut jobs: mpsc::Receiver<Job<NotificationCommand>>,
+) {
+    while let Some(Job { command, reply }) = jobs.recv().await {
+        reply.done(guarded("notification command", notification(&client, command)).await);
+    }
+}
+
+pub(super) async fn run_encryption(
+    client: Client,
+    events: EventSender,
+    mut jobs: mpsc::Receiver<Job<EncryptionCommand>>,
+) {
+    let mut verification = VerificationController::default();
+    while let Some(Job { command, reply }) = jobs.recv().await {
+        let work = encryption(&client, &events, &mut verification, command);
+        reply.done(guarded("encryption command", work).await);
+    }
+}
+
+async fn encryption(
+    client: &Client,
+    events: &EventSender,
+    verification: &mut VerificationController,
+    command: EncryptionCommand,
+) -> Result<(), Error> {
+    let encryption = client.encryption();
+    match command {
+        EncryptionCommand::Recover(key) => encryption
+            .recovery()
+            .recover(&key)
+            .await
+            .map_err(|source| Error::from_recovery("account recovery failed", source)),
+        EncryptionCommand::RecoverKeyBackup(key) => encryption
+            .recovery()
+            .recover_and_fix_backup(&key)
+            .await
+            .map_err(|source| Error::from_recovery("recovering key backup failed", source)),
+        EncryptionCommand::CreateKeyBackup => encryption
+            .backups()
+            .create()
+            .await
+            .map_err(|source| Error::from_sdk("creating key backup failed", source)),
+        EncryptionCommand::EnableKeyBackup => encryption
+            .recovery()
+            .enable_backup()
+            .await
+            .map_err(|source| Error::from_recovery("enabling key backup failed", source)),
+        EncryptionCommand::DisableKeyBackup { delete_from_server } => {
+            let backups = encryption.backups();
+            if delete_from_server {
+                backups.disable_and_delete().await
+            } else {
+                backups.disable().await
+            }
+            .map_err(|source| Error::from_sdk("disabling key backup failed", source))
+        }
+        EncryptionCommand::StartVerification(target) => {
+            verification.start(client, events.clone(), target).await
+        }
+        EncryptionCommand::Verify(action) => verification.apply(events.clone(), action).await,
+    }
+}
+
+async fn notification(client: &Client, command: NotificationCommand) -> Result<(), Error> {
+    let settings = client.notification_settings().await;
+    match command {
+        NotificationCommand::SetRoomMode { room_id, mode } => {
+            settings
+                .set_room_notification_mode(&room_id, sdk_mode(mode))
+                .await
+        }
+        NotificationCommand::ResetRoomMode(room_id) => {
+            settings.delete_user_defined_room_rules(&room_id).await
+        }
+        NotificationCommand::SetDefaultMode {
+            encrypted,
+            one_to_one,
+            mode,
+        } => {
+            settings
+                .set_default_room_notification_mode(
+                    IsEncrypted::from(encrypted),
+                    IsOneToOne::from(one_to_one),
+                    sdk_mode(mode),
+                )
+                .await
+        }
+        NotificationCommand::AddKeyword(keyword) => settings.add_keyword(keyword).await,
+        NotificationCommand::RemoveKeyword(keyword) => settings.remove_keyword(&keyword).await,
+    }
+    .map_err(|source| {
+        Error::with_source(
+            ErrorKind::Server,
+            "updating notification settings failed",
+            source,
+        )
+    })
+}
+
+const fn sdk_mode(mode: RoomNotificationMode) -> SdkMode {
+    match mode {
+        RoomNotificationMode::AllMessages => SdkMode::AllMessages,
+        RoomNotificationMode::MentionsAndKeywordsOnly => SdkMode::MentionsAndKeywordsOnly,
+        RoomNotificationMode::Mute => SdkMode::Mute,
+    }
+}
+
+fn room(client: &Client, room_id: &RoomId) -> Result<matrix_sdk::Room, Error> {
+    client.get_room(room_id).ok_or_else(Error::room_unknown)
+}
+
+/// the closed-room path. without a timeline nothing stops the marker going backwards
+pub(super) async fn mark_read(
+    client: &Client,
+    timeline_id: &TimelineId,
+    event_id: OwnedEventId,
+) -> Result<(), Error> {
+    let room = room(client, timeline_id.room_id())?;
+    let receipt_failed = |source| Error::from_sdk("sending read receipt failed", source);
+    let thread = match timeline_id.thread_root() {
+        None => ReceiptThread::Main,
+        Some(root) => ReceiptThread::Thread(root.clone()),
+    };
+    room.send_single_receipt(ReceiptType::Read, thread, event_id.clone())
+        .await
+        .map_err(receipt_failed)?;
+    if timeline_id.thread_root().is_none() {
+        room.send_single_receipt(ReceiptType::FullyRead, ReceiptThread::Unthreaded, event_id)
+            .await
+            .map_err(receipt_failed)?;
+    }
+    Ok(())
+}
+
+pub(super) async fn set_typing(
+    client: &Client,
+    room_id: &RoomId,
+    typing: bool,
+) -> Result<(), Error> {
+    room(client, room_id)?
+        .typing_notice(typing)
+        .await
+        .map_err(|source| Error::from_sdk("typing update failed", source))
+}
+
+async fn send_handle(
+    client: &Client,
+    room_id: &RoomId,
+    transaction_id: &TransactionId,
+) -> Result<SendHandle, Error> {
+    let (echoes, _) = room(client, room_id)?
+        .send_queue()
+        .subscribe()
+        .await
+        .map_err(|source| {
+            Error::with_source(ErrorKind::Store, "reading send queue failed", source)
+        })?;
+    echoes
+        .into_iter()
+        .find_map(|echo| match echo.content {
+            LocalEchoContent::Event { send_handle, .. }
+                if echo.transaction_id.as_str() == transaction_id.as_str() =>
+            {
+                Some(send_handle)
+            }
+            _ => None,
+        })
+        .ok_or_else(|| {
+            Error::new(
+                ErrorKind::Invalid,
+                "send is no longer pending or is not a message",
+            )
+        })
+}
+
+pub(super) async fn cancel_send(
+    client: &Client,
+    room_id: &RoomId,
+    transaction_id: &TransactionId,
+) -> Result<(), Error> {
+    match send_handle(client, room_id, transaction_id)
+        .await?
+        .abort()
+        .await
+    {
+        Ok(true) => Ok(()),
+        Ok(false) => Err(Error::new(
+            ErrorKind::Invalid,
+            "send could not be cancelled because it has already been sent",
+        )),
+        Err(source) => Err(Error::with_source(
+            ErrorKind::Store,
+            "cancelling send failed",
+            source,
+        )),
+    }
+}
+
+pub(super) async fn retry_send(
+    client: &Client,
+    room_id: &RoomId,
+    transaction_id: &TransactionId,
+) -> Result<(), Error> {
+    send_handle(client, room_id, transaction_id)
+        .await?
+        .unwedge()
+        .await
+        .map_err(|source| Error::with_source(ErrorKind::Store, "retrying send failed", source))?;
+    room(client, room_id)?.send_queue().set_enabled(true);
+    Ok(())
+}
+
+pub(super) async fn upload_avatar(
+    client: &Client,
+    mimetype: &str,
+    bytes: Vec<u8>,
+    max_bytes: usize,
+) -> Result<(), Error> {
+    if bytes.len() > max_bytes {
+        return Err(Error::new(
+            ErrorKind::MediaTooLarge,
+            "avatar exceeds the configured byte limit",
+        ));
+    }
+    let mimetype: mime::Mime = mimetype
+        .parse()
+        .map_err(|_| Error::new(ErrorKind::Invalid, "avatar MIME type is invalid"))?;
+    if mimetype.type_() != mime::IMAGE {
+        return Err(Error::new(
+            ErrorKind::Invalid,
+            "an avatar has to be an image",
+        ));
+    }
+    client
+        .account()
+        .upload_avatar(&mimetype, bytes)
+        .await
+        .map(drop)
+        .map_err(|source| Error::from_sdk("uploading avatar failed", source))
+}
+
+pub(super) async fn rename_device(
+    client: &Client,
+    device_id: &OwnedDeviceId,
+    display_name: &str,
+) -> Result<(), Error> {
+    client
+        .rename_device(device_id, display_name)
+        .await
+        .map(drop)
+        .map_err(|source| Error::from_http("renaming device failed", source))
+}
+
+pub(super) async fn delete_devices(
+    client: &Client,
+    device_ids: &[OwnedDeviceId],
+    auth: Option<InteractiveAuth>,
+) -> Result<(), Error> {
+    let user_id = client
+        .user_id()
+        .ok_or_else(|| Error::new(ErrorKind::Unauthenticated, "the client is not logged in"))?;
+    let auth = auth
+        .map(|auth| auth.into_sdk(user_id))
+        .transpose()
+        .map_err(|message| {
+            Error::new(
+                ErrorKind::Invalid,
+                format!("interactive authentication data is invalid, {message}"),
+            )
+        })?;
+    match client.delete_devices(device_ids, auth).await {
+        Ok(_) => Ok(()),
+        Err(source) => match source.as_uiaa_response() {
+            Some(info) => Err(Error::interactive_auth(InteractiveAuthChallenge::from(
+                info,
+            ))),
+            None => Err(Error::from_http("deleting devices failed", source)),
+        },
+    }
+}

Added file: src/engine/media.rs+470 additions@@ -0,0 +1,572 @@
+use std::{
+    borrow::Cow,
+    collections::{HashMap, VecDeque},
+    io::Read as _,
+    panic::AssertUnwindSafe,
+    sync::Arc,
+};
+
+use futures_util::{
+    FutureExt, StreamExt,
+    future::{BoxFuture, Shared, WeakShared},
+};
+use matrix_sdk::{
+    Client, Room,
+    media::{MediaFormat, MediaRequestParameters, MediaThumbnailSettings},
+    room::reply::{EnforceThread, Reply as SdkReply},
+    ruma::{
+        api::{
+            Metadata, OutgoingRequest,
+            auth_scheme::SendAccessToken,
+            client::{authenticated_media, media},
+        },
+        events::room::{
+            MediaSource,
+            message::{AddMentions, ReplyWithinThread},
+        },
+    },
+};
+use matrix_sdk_crypto::{AttachmentDecryptor, MediaEncryptionInfo};
+use ruma::MxcUri;
+use tokio::sync::Mutex;
+
+use crate::{
+    AttachmentUpload, Error, ErrorKind, Media, MediaId, MediaKind, MediaSize, TimelineId,
+    normalise::{MediaRegistration, MediaScope},
+    upload::prepare_upload,
+};
+
+/// the uploader's thumbnail is used when there is one, this is only what we ask the server for
+const TIMELINE_THUMBNAIL: u32 = 800;
+
+type FlightFuture = BoxFuture<'static, Result<Media, Error>>;
+type Flight = Shared<FlightFuture>;
+
+/// owns everything needed to turn a media id or an mxc uri into bytes, so the
+/// handle can answer media queries without a trip through the engine
+pub(crate) struct MediaService {
+    client: Client,
+    registry: Mutex<MediaRegistry>,
+    flights: Mutex<HashMap<String, WeakShared<FlightFuture>>>,
+    max_bytes: usize,
+}
+
+impl MediaService {
+    pub(crate) fn new(client: Client, max_bytes: usize, max_sources: usize) -> Self {
+        Self {
+            client,
+            registry: Mutex::new(MediaRegistry::new(max_sources)),
+            flights: Mutex::new(HashMap::new()),
+            max_bytes,
+        }
+    }
+
+    pub(crate) async fn register(&self, media: Vec<MediaRegistration>) {
+        if !media.is_empty() {
+            self.registry.lock().await.insert_all(media);
+        }
+    }
+
+    pub(crate) async fn release(&self, scope: &MediaScope) {
+        self.registry.lock().await.release(scope);
+    }
+
+    pub(crate) async fn clear(&self) {
+        self.registry.lock().await.clear();
+    }
+
+    pub(crate) async fn timeline_media(
+        &self,
+        media_id: &MediaId,
+        size: MediaSize,
+    ) -> Result<Media, Error> {
+        let media = self
+            .registry
+            .lock()
+            .await
+            .get(media_id)
+            .cloned()
+            .ok_or_else(|| {
+                Error::new(
+                    ErrorKind::MediaUnknown,
+                    "media is not registered in a retained timeline",
+                )
+            })?;
+        let (source, format, mimetype, declared_size) = match size {
+            MediaSize::Full => (
+                media.full.source,
+                MediaFormat::File,
+                media.full.mimetype,
+                media.full.declared_size,
+            ),
+            MediaSize::Thumbnail { .. } => match media.thumbnail {
+                Some(thumbnail) => (
+                    thumbnail.source,
+                    MediaFormat::File,
+                    thumbnail.mimetype,
+                    thumbnail.declared_size,
+                ),
+                // the server can only resize what it can read
+                None if matches!(media.kind, MediaKind::Image | MediaKind::Video)
+                    && matches!(media.full.source, MediaSource::Plain(_)) =>
+                {
+                    (
+                        media.full.source,
+                        thumbnail_format(TIMELINE_THUMBNAIL, TIMELINE_THUMBNAIL),
+                        media.full.mimetype,
+                        None,
+                    )
+                }
+                None => {
+                    return Err(Error::new(
+                        ErrorKind::MediaUnavailable,
+                        "the requested media size is unavailable",
+                    ));
+                }
+            },
+        };
+        if declared_size.is_some_and(|size| size > self.max_bytes as u64) {
+            return Err(too_large("media exceeds the configured byte limit"));
+        }
+        self.fetch(MediaRequestParameters { source, format }, mimetype)
+            .await
+    }
+
+    pub(crate) async fn mxc_media(&self, uri: &MxcUri, size: MediaSize) -> Result<Media, Error> {
+        if !uri.is_valid() {
+            return Err(Error::new(ErrorKind::Invalid, "mxc uri is malformed"));
+        }
+        let format = match size {
+            MediaSize::Full => MediaFormat::File,
+            MediaSize::Thumbnail { width, height } => thumbnail_format(width, height),
+        };
+        self.fetch(
+            MediaRequestParameters {
+                source: MediaSource::Plain(uri.to_owned()),
+                format,
+            },
+            None,
+        )
+        .await
+    }
+
+    async fn fetch(
+        &self,
+        request: MediaRequestParameters,
+        mimetype: Option<String>,
+    ) -> Result<Media, Error> {
+        let key = flight_key(&request);
+        let flight = {
+            let mut flights = self.flights.lock().await;
+            flights.retain(|_, flight| flight.upgrade().is_some());
+            match flights.get(&key).and_then(WeakShared::upgrade) {
+                Some(flight) => flight,
+                None => {
+                    let flight: Flight = AssertUnwindSafe(fetch(
+                        self.client.clone(),
+                        request,
+                        mimetype,
+                        self.max_bytes,
+                    ))
+                    .catch_unwind()
+                    .map(|result| {
+                        result.unwrap_or_else(|_| {
+                            Err(Error::new(ErrorKind::Other, "media fetch panicked"))
+                        })
+                    })
+                    .boxed()
+                    .shared();
+                    if let Some(weak) = flight.downgrade() {
+                        flights.insert(key, weak);
+                    }
+                    flight
+                }
+            }
+        };
+        flight.await
+    }
+}
+
+fn thumbnail_format(width: u32, height: u32) -> MediaFormat {
+    MediaFormat::Thumbnail(MediaThumbnailSettings::new(width.into(), height.into()))
+}
+
+fn flight_key(request: &MediaRequestParameters) -> String {
+    let uri = match &request.source {
+        MediaSource::Plain(uri) => uri.as_str(),
+        MediaSource::Encrypted(file) => file.url.as_str(),
+    };
+    match &request.format {
+        MediaFormat::File => uri.to_owned(),
+        MediaFormat::Thumbnail(settings) => format!(
+            "{uri}|{}|{}x{}|{}",
+            settings.method, settings.width, settings.height, settings.animated
+        ),
+    }
+}
+
+fn too_large(message: &'static str) -> Error {
+    Error::new(ErrorKind::MediaTooLarge, message)
+}
+
+async fn fetch(
+    client: Client,
+    request: MediaRequestParameters,
+    mimetype: Option<String>,
+    max_bytes: usize,
+) -> Result<Media, Error> {
+    if let Some(cached) = cached_media(&client, &request).await? {
+        if cached.len() > max_bytes {
+            if let Ok(store) = client.media_store().lock().await {
+                let _ = store.remove_media_content(&request).await;
+            }
+            return Err(too_large("cached media exceeds the configured byte limit"));
+        }
+        return Ok(media(cached, mimetype));
+    }
+    let (bytes, served_mimetype) = download_bounded(&client, &request, max_bytes).await?;
+    // the sdk caches plaintext under the encrypted key, so we do too or nobody can read anything
+    let bytes = maybe_decrypt(bytes, &request, max_bytes)?;
+    if let Ok(store) = client.media_store().lock().await {
+        let _ = store
+            .add_media_content(
+                &request,
+                bytes.clone(),
+                matrix_sdk::media::store::IgnoreMediaRetentionPolicy::No,
+            )
+            .await;
+    }
+    Ok(media(bytes, mimetype.or(served_mimetype)))
+}
+
+fn media(bytes: Vec<u8>, mimetype: Option<String>) -> Media {
+    let mimetype = mimetype
+        .or_else(|| sniff_image(&bytes).map(str::to_owned))
+        .unwrap_or_else(|| "application/octet-stream".to_owned());
+    Media {
+        bytes: Arc::from(bytes),
+        mimetype,
+    }
+}
+
+/// the cache forgets content types, and avatars never declare one. images are the common case
+fn sniff_image(bytes: &[u8]) -> Option<&'static str> {
+    match bytes {
+        [0x89, b'P', b'N', b'G', ..] => Some("image/png"),
+        [0xff, 0xd8, 0xff, ..] => Some("image/jpeg"),
+        [b'G', b'I', b'F', b'8', ..] => Some("image/gif"),
+        [
+            b'R',
+            b'I',
+            b'F',
+            b'F',
+            _,
+            _,
+            _,
+            _,
+            b'W',
+            b'E',
+            b'B',
+            b'P',
+            ..,
+        ] => Some("image/webp"),
+        _ => None,
+    }
+}
+
+async fn cached_media(
+    client: &Client,
+    request: &MediaRequestParameters,
+) -> Result<Option<Vec<u8>>, Error> {
+    fn cache_failed(source: impl std::error::Error + Send + Sync + 'static) -> Error {
+        Error::with_source(ErrorKind::Store, "reading media cache failed", source)
+    }
+    client
+        .media_store()
+        .lock()
+        .await
+        .map_err(cache_failed)?
+        .get_media_content(request)
+        .await
+        .map_err(cache_failed)
+}
+
+fn maybe_decrypt(
+    bytes: Vec<u8>,
+    request: &MediaRequestParameters,
+    max_bytes: usize,
+) -> Result<Vec<u8>, Error> {
+    let MediaSource::Encrypted(file) = &request.source else {
+        return Ok(bytes);
+    };
+    fn decrypt_failed(source: impl std::error::Error + Send + Sync + 'static) -> Error {
+        Error::with_source(
+            ErrorKind::MediaUnavailable,
+            "media decryption failed",
+            source,
+        )
+    }
+    let info: MediaEncryptionInfo = (**file).clone().into();
+    let mut cursor = std::io::Cursor::new(bytes);
+    let mut decryptor = AttachmentDecryptor::new(&mut cursor, info).map_err(decrypt_failed)?;
+    let mut decrypted = Vec::new();
+    let mut chunk = [0_u8; 8192];
+    loop {
+        let read = decryptor.read(&mut chunk).map_err(decrypt_failed)?;
+        if read == 0 {
+            return Ok(decrypted);
+        }
+        if read > max_bytes.saturating_sub(decrypted.len()) {
+            return Err(too_large(
+                "decrypted media exceeds the configured byte limit",
+            ));
+        }
+        decrypted.extend_from_slice(&chunk[..read]);
+    }
+}
+
+/// the sdk's own download has no size cap and no timeout, so we do it by hand
+async fn download_bounded(
+    client: &Client,
+    request: &MediaRequestParameters,
+    max_bytes: usize,
+) -> Result<(Vec<u8>, Option<String>), Error> {
+    let uri = match &request.source {
+        MediaSource::Plain(uri) => uri,
+        MediaSource::Encrypted(file) => &file.url,
+    };
+    if uri
+        .server_name()
+        .is_ok_and(|server| server.as_str() == "send-queue.localhost")
+    {
+        return Err(Error::new(
+            ErrorKind::MediaUnavailable,
+            "local media is not in the media cache",
+        ));
+    }
+    let network_failed =
+        |source| Error::with_source(ErrorKind::Network, "media download failed", source);
+    let mut refreshed = false;
+    let response = loop {
+        let http_request = media_http_request(client, request).await?;
+        let (parts, _) = http_request.into_parts();
+        let mut builder = client.http_client().get(parts.uri.to_string());
+        for (name, value) in &parts.headers {
+            builder = builder.header(name.as_str(), value.as_bytes());
+        }
+        let response = builder.send().await.map_err(network_failed)?;
+        if response.status() != matrix_sdk::reqwest::StatusCode::UNAUTHORIZED {
+            break response;
+        }
+        if refreshed
+            || client
+                .session_tokens()
+                .is_none_or(|tokens| tokens.refresh_token.is_none())
+        {
+            return Err(Error::new(
+                ErrorKind::Unauthenticated,
+                "media download was not authorized",
+            ));
+        }
+        client.refresh_access_token().await.map_err(|source| {
+            Error::from_refresh_token("refreshing media access token failed", source)
+        })?;
+        refreshed = true;
+    };
+    let status = response.status();
+    if !status.is_success() {
+        return Err(Error::new(
+            ErrorKind::MediaUnavailable,
+            format!("media download failed with status {status}"),
+        ));
+    }
+    if response
+        .content_length()
+        .is_some_and(|length| length > max_bytes as u64)
+    {
+        return Err(too_large("media exceeds the configured byte limit"));
+    }
+    let mimetype = response
+        .headers()
+        .get(http::header::CONTENT_TYPE)
+        .and_then(|value| value.to_str().ok())
+        .map(str::to_owned);
+    let mut stream = response.bytes_stream();
+    let mut bytes = Vec::new();
+    while let Some(chunk) = stream.next().await {
+        let chunk = chunk.map_err(network_failed)?;
+        if chunk.len() > max_bytes.saturating_sub(bytes.len()) {
+            return Err(too_large(
+                "downloaded media exceeds the configured byte limit",
+            ));
+        }
+        bytes.extend_from_slice(&chunk);
+    }
+    Ok((bytes, mimetype))
+}
+
+async fn media_http_request(
+    client: &Client,
+    request: &MediaRequestParameters,
+) -> Result<http::Request<Vec<u8>>, Error> {
+    let versions = client.supported_versions().await.map_err(|source| {
+        Error::with_source(
+            ErrorKind::Network,
+            "reading supported server versions failed",
+            source,
+        )
+    })?;
+    let authenticated =
+        authenticated_media::get_content::v1::Request::PATH_BUILDER.is_supported(&versions);
+    let base = client.homeserver().to_string();
+    let token = client.access_token();
+    let invalid_uri =
+        |source| Error::with_source(ErrorKind::Invalid, "media URI is invalid", source);
+    let (uri, thumbnail) = match (&request.source, &request.format) {
+        (MediaSource::Encrypted(file), _) => (&file.url, None),
+        (MediaSource::Plain(uri), MediaFormat::File) => (uri, None),
+        (MediaSource::Plain(uri), MediaFormat::Thumbnail(settings)) => (uri, Some(settings)),
+    };
+    // each endpoint has its own auth input type, so no generic helper can take them all
+    macro_rules! into_http {
+        ($endpoint:expr, $token:expr) => {
+            $endpoint
+                .try_into_http_request::<Vec<u8>>(&base, $token, Cow::Borrowed(&versions))
+                .map_err(|source| {
+                    Error::with_source(ErrorKind::Other, "media request is invalid", source)
+                })?
+        };
+    }
+    let authed = SendAccessToken::IfRequired(token.as_deref().unwrap_or(""));
+    #[allow(deprecated)]
+    let mut http_request = match (thumbnail, authenticated) {
+        (None, true) => into_http!(
+            authenticated_media::get_content::v1::Request::from_uri(uri).map_err(invalid_uri)?,
+            authed
+        ),
+        (None, false) => into_http!(
+            media::get_content::v3::Request::from_url(uri).map_err(invalid_uri)?,
+            SendAccessToken::None
+        ),
+        (Some(settings), true) => {
+            let mut endpoint = authenticated_media::get_content_thumbnail::v1::Request::from_uri(
+                uri,
+                settings.width,
+                settings.height,
+            )
+            .map_err(invalid_uri)?;
+            endpoint.method = Some(settings.method.clone());
+            endpoint.animated = Some(settings.animated);
+            into_http!(endpoint, authed)
+        }
+        (Some(settings), false) => {
+            let mut endpoint = media::get_content_thumbnail::v3::Request::from_url(
+                uri,
+                settings.width,
+                settings.height,
+            )
+            .map_err(invalid_uri)?;
+            endpoint.method = Some(settings.method.clone());
+            en

show full diff (262144 bytes truncated)

macltok

Commit 31ce2453c82f

Commit `31ce2453c82f`