6b0987385e
When instantiating a room preview, previously it would try to just check if the room exists locally either as joined, invited, knocked, left, etc., and then retrieve the info we cached about it. While this seems fine for most cases, it turns out for non-joined rooms, the info we have locally will **always** be the one we received when the invite/knock/leave action took place and it'll never be updated, so we may have the case where we knock into a room, never receive a response, someone changes the join rule of the room to something else and we'll think about this room as a 'request to join' room until we clear the local cache. To prevent that, we can only use the local data for joined rooms, which are constantly updated, and try to use the room summary API and other fallbacks for the rest, even if they're rooms known to us.
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().server_name(alice.server_name()).build().await?;
// First we need to log in.
client.matrix_auth().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 unless there is an error.
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 |
js |
No | Enables JavaScript API usage on WASM (does nothing on other targets) |
markdown |
No | Support for sending Markdown-formatted messages |
qrcode |
Yes | QR code verification support |
sqlite |
Yes | Persistent storage of state and E2EE data (optionally, if feature e2e-encryption is enabled), via SQLite available on system |
bundled-sqlite |
No | Persistent storage of state and E2EE data (optionally, if feature e2e-encryption is enabled), via SQLite compiled and bundled with the binary |
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.