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 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
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.
With sqlite, persist the initial Session::record() separately from its
encrypted SQLite store. On SessionTokensChanged, obtain a new record from
ClientHandle::session_record() and replace the saved record atomically in
protected storage. Restore with the same store path and passphrase. Delete the
saved credentials after LoggedOut or SessionAccessRejected, but keep them
after Stopped so a restart can restore the session. The headless example is
login-only; it does not persist sessions across runs.
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. Media decoding belongs to the consumer.
Verification
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