A high-level, batteries-included Matrix client library written in Rust.
This crate seeks to be a general-purpose library for writing software using the Matrix Client-Server API to communicate with a Matrix homeserver. If you're writing a typical Matrix client or bot, this is likely the crate you need.
However, the crate is designed in a modular way and depends on several other lower-level crates. If you're attempting something more custom, you might be interested in these:
matrix_sdk_base
]: A no-network-IO client state machine which can be used
to embed a Matrix client into an existing network stack or to build a new
Matrix client library on top.matrix_sdk_crypto
:
A no-network-IO encryption state machine which can be used to add Matrix E2EE
support into an existing client or library.The central component you'll be interacting with is the [Client
]. A basic use
case will include instantiating the client, logging in as a user, registering
some event handlers and then syncing.
This is demonstrated in the example below.
```rust,norun use matrixsdk::{ Client, config::SyncSettings, ruma::{user_id, events::room::message::SyncRoomMessageEvent}, };
async fn main() -> anyhow::Result<()> { let alice = userid!("@alice:example.org"); let client = Client::builder().userid(alice).build().await?;
// First we need to log in.
client.login_username(alice, "password").send().await?;
client.add_event_handler(|ev: SyncRoomMessageEvent| async move {
println!("Received a message {:?}", ev);
});
// Syncing is important to synchronize the client state with the server.
// This method will never return.
client.sync(SyncSettings::default()).await;
Ok(())
} ```
More examples can be found in the [examples] directory.
The following crate feature flags are available:
| Feature | Default | Description |
| ------------------- | :-----: | -------------------------------------------------------------------------------------------------------------------------- |
| anyhow
| No | Better logging for event handlers that return anyhow::Result
|
| e2e-encryption
| Yes | End-to-end encryption (E2EE) support |
| eyre
| No | Better logging for event handlers that return eyre::Result
|
| image-proc
| No | Image processing for generating thumbnails |
| image-rayon
| No | Enables faster image processing |
| js
| No | Enables JavaScript API usage for things like the current system time on WASM (does nothing on other targets) |
| markdown
| No | Support for sending Markdown-formatted messages |
| qrcode
| Yes | QR code verification support |
| sled
| Yes | Persistent storage of state and E2EE data (optionally, if feature e2e-encryption
is enabled), via Sled |
| indexeddb
| No | Persistent storage of state and E2EE data (optionally, if feature e2e-encryption
is enabled) for browsers, via IndexedDB |
| socks
| No | SOCKS support in the default HTTP client, [reqwest
] |
| sso-login
| No | Support for SSO login with a local HTTP server |
Users of the matrix-sdk crate can enable log output by depending on the
tracing-subscriber
crate and including the following line in their
application (e.g. at the start of main
):
rust
tracing_subscriber::fmt::init();
The log output is controlled via the RUST_LOG
environment variable by
setting it to one of the error
, warn
, info
, debug
or trace
levels.
The output is printed to stdout.
The RUST_LOG
variable also supports a more advanced syntax for filtering
log output more precisely, for instance with crate-level granularity. For
more information on this, check out the [tracing_subscriber documentation].