Crate matrix_sdk
source · [−]Expand description
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.
Getting started
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.
use matrix_sdk::{
Client, config::SyncSettings,
ruma::{user_id, events::room::message::SyncRoomMessageEvent},
};
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let alice = user_id!("@alice:example.org");
let client = Client::builder().user_id(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.
Crate Feature Flags
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 |
Enabling logging
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):
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.
Re-exports
Modules
e2e-encryptionClient::add_event_handler.Structs
Client.sso-loginEnums
ClientBuilder::build.image-procTraits
Send and Sync to have
implemented, while other targets will.Send on non-wasm, empty trait (implemented by everything) on
wasm.Sync on non-wasm, empty trait (implemented by everything) on
wasm.