macltok

# macltok

`macltok` is a compact Rust application backend built above `matrix-sdk` and

`matrix-sdk-ui`. It aims to provide the stateful behavior needed by a useful

Matrix client without depending on a GUI toolkit or inventing another protocol

SDK.

The crate currently provides

- typed commands, owned UI-safe events and bounded per-client transport

- Sliding Sync with normalized connection and room-list state

- independently retained live room timelines and backwards pagination

- text, emote, reply, edit, redaction, reaction, receipt and typing operations

- raw encrypted or unencrypted media acquisition with configurable byte limits

- encryption state, recovery-key import and SAS verification

- password login and session restoration with caller-owned encrypted SQLite or

  IndexedDB stores

Matrix room, event, user, device and transaction identifiers remain strongly

typed. A toolkit timeline identity covers local echoes without pretending they

already have remote event IDs.

## Consuming the engine

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

some commands put an event on the stream before they answer. `Open`, `Close`,

`OpenThread`, `CloseThread`, `Resync`, `Paginate`, `Logout` and the

verification actions all do. the stream is bounded, so a task that drains it

and awaits one of those answers deadlocks once it fills. from the draining

task, `try_send` the command and drop the `Pending`, the events tell you how it

went

start a timeline from `TimelineReset`, then apply each `TimelineChanged` whole

with `TimelineDiff::try_apply_all`. snapshots are `imbl::Vector`s, re-exported

as `macltok::imbl`, so a copy costs nothing. when a batch doesn't fit none of it

lands. stop applying, call `resync`, and pick up from the next `TimelineReset`

with `sqlite` or `indexeddb`, a `SessionStore` holds one login's record and its

store. `EncryptedSessionStore` seals the record with the store's passphrase, in a

file you pick natively or an IndexedDB database beside the store in a browser.

logging in saves the first record and `Session::restore` loads it. from then on

the engine the `Session` builds keeps it current. every token rotation is saved

before `SessionTokensChanged` goes out, and a save that fails says so with

`SessionSaveFailed`. natively `EncryptedSessionStore` writes from inside the

sdk's refresh, before the new refresh token is ever used, and a store of your

own gets the same by implementing `SessionStore::save_blocking`. in a browser

the save can only follow the refresh, so a tab killed in between wakes with a

spent token. `Session::without_persistence` hands the job back, and then it's

yours to save `ClientHandle::session_record()` on every `SessionTokensChanged`

`Engine::run` resolves to a `Termination` saying why it stopped, and

`Termination::retain` says what to do about it. after `LoggedOut` or

`AccessRevoked` the record and the store are dead, `discard` them once the

client is dropped, since an open store won't go quietly. `SoftLoggedOut` wants

the store kept and a fresh login as the same device, or the e2ee keys go with

it. `soft_log_out` swaps the record for one naming that device, so a restart

gets `Restore::SoftLoggedOut` and `SoftLogout::password_login` rather than

nothing, and the login overwrites it with a live record. `ShutDown` and

`HandlesDropped` keep everything. an `Err` is a real failure and kills nothing.

one store directory per login, the sdk won't share a crypto store between

devices

## The mirror

the loop above is easy to get subtly wrong, so the `mirror` feature ships one.

`Mirror::new` takes a `ClientHandle` and the events, and `Mirror::run` drains

them into one `State` with the rooms, every open timeline, connection,

encryption, verification, typing, uploads and where the session stands. spawn

it the way you spawn `Engine::run`. it takes any stream of events, so wrap the

`EventStream` if you want to watch the raw ones go past

`MirrorHandle` is cheap to clone, one per frontend. `snapshot` hands back the

current `State`, and `subscribe` opens with the whole `State` and then every

`Update` after it, numbered, with nothing missed and nothing twice. a timeline

update carries its diffs and the items they left, so apply the diffs or

re-render the list, whichever suits. a subscriber that falls behind gets a fresh

`State` instead of an error

a batch that doesn't fit leaves the timeline diverged at its last good items.

the mirror asks for the resync itself, off the draining path, and keeps asking

until the reset or a close turns up. rooms are refetched on `RoomsChanged`, one

fetch at a time with at most one more owed

with a store feature, `with_session_store` saves the record on every

`SessionTokensChanged` before the next event is touched, and a failed save shows

up as an update. without one, catch `SessionTokensChanged` on the raw stream

and save it yourself, a subscriber that lags could miss it. `save` is all the

mirror calls. `soft_log_out` and `discard` wait for `Engine::run`'s `Termination`

once the client is gone

## wasm

macltok builds for `wasm32-unknown-unknown`. the `indexeddb` feature gives you

`StoreConfig::indexeddb` in place of `StoreConfig::sqlite`, and asking for either

on the wrong target won't compile. `Engine::run` hands back a `LocalBoxFuture`

there, so spawn it with `wasm_bindgen_futures::spawn_local`

getrandom picks its browser backend from a cfg flag, and `.cargo/config.toml`

only reaches this crate's own builds. every cdylib that pulls macltok in needs

it too

```toml

[target.wasm32-unknown-unknown]

rustflags = ["--cfg", "getrandom_backend=\"wasm_js\""]

```

what's different in a browser

- a panic doesn't abort anything. it traps the task mid poll and the rest of

  the engine carries on in an undefined state and goes quiet, no `Failed` and no

  `Stopped`. register `macltok::on_panic` and have it tear the worker down and

  start another. natively a panicking command just costs its caller an

  `Interrupted`

- `MediaUploadProgress` only ever reports completion, the sdk's wasm http path

  has no upload progress

- the sdk doesn't retry requests or time them out individually. sync still

  restarts itself with backoff, that part is ours

- two tabs or workers on one store each need `StoreConfig::with_lock_holder`

  with a name of their own, or they both think they hold the crypto store

## Dependency policy

UI frameworks, image decoders, application-directory discovery and logging

subscribers do not belong in this crate. SQLite remains optional through the

`sqlite` and `bundled-sqlite` features, IndexedDB through `indexeddb`. Media

decoding belongs to the consumer.

## Verification

```sh

nix develop --command cargo fmt -- --check

nix develop --command cargo test --all-targets

nix develop --command cargo test --all-targets --features sqlite

nix develop --command cargo clippy --all-targets -- -D warnings

nix develop --command cargo clippy --all-targets --features sqlite -- -D warnings

nix flake check

```

`--all-features` doesn't build and isn't meant to. `sqlite` and `indexeddb` each

belong to one target and refuse the other