matrix-sdk

Crates.iomatrix-sdk
lib.rsmatrix-sdk
version0.7.1
sourcesrc
created_at2020-05-26 19:43:47.517962
updated_at2024-01-22 10:38:35.982857
descriptionA high level Matrix client-server library.
homepagehttps://github.com/matrix-org/matrix-rust-sdk
repositoryhttps://github.com/matrix-org/matrix-rust-sdk
max_upload_size
id246328
size1,760,212
Rust (github:matrix-org:rust)

documentation

README

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
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
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.

Commit count: 8826

cargo fmt