9 releases (5 breaking)

0.6.2 Oct 24, 2022
0.6.1 Oct 24, 2022
0.6.0 Sep 28, 2022
0.5.0 May 11, 2022
0.1.0 May 26, 2020

#1 in #matrix-org

Download history 339/week @ 2023-06-11 644/week @ 2023-06-18 401/week @ 2023-06-25 609/week @ 2023-07-02 513/week @ 2023-07-09 464/week @ 2023-07-16 450/week @ 2023-07-23 294/week @ 2023-07-30 364/week @ 2023-08-06 482/week @ 2023-08-13 318/week @ 2023-08-20 289/week @ 2023-08-27 440/week @ 2023-09-03 410/week @ 2023-09-10 477/week @ 2023-09-17 253/week @ 2023-09-24

1,594 downloads per month
Used in 22 crates

Apache-2.0

1MB
14K SLoC

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.

Dependencies

~13–32MB
~502K SLoC