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().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:

FeatureDefaultDescription
anyhowNoBetter logging for event handlers that return anyhow::Result
e2e-encryptionYesEnd-to-end encryption (E2EE) support
eyreNoBetter logging for event handlers that return eyre::Result
image-procNoImage processing for generating thumbnails
image-rayonNoEnables faster image processing
jsNoEnables JavaScript API usage for things like the current system time on WASM (does nothing on other targets)
markdownNoSupport for sending Markdown-formatted messages
qrcodeYesQR code verification support
sqliteYesPersistent storage of state and E2EE data (optionally, if feature e2e-encryption is enabled), via SQLite available on system
bundled-sqliteNoPersistent storage of state and E2EE data (optionally, if feature e2e-encryption is enabled), via SQLite compiled and bundled with the binary
indexeddbNoPersistent storage of state and E2EE data (optionally, if feature e2e-encryption is enabled) for browsers, via IndexedDB
socksNoSOCKS support in the default HTTP client, reqwest
sso-loginNoSupport 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§

  • Types and traits for attachments.
  • Configuration to change the behaviour of the Client.
  • Helpers for creating std::fmt::Debug implementations.
  • SDK-specific variations of response types from Ruma.
  • encryptione2e-encryption
    End-to-end encryption related types
  • The event cache is an abstraction layer, sitting between the Rust SDK and a final client, that acts as a global observer of all the rooms, gathering and inferring some extra useful information about each room. In particular, this doesn’t require subscribing to a specific room to get access to this information.
  • Types and traits related for event handlers. For usage, see Client::add_event_handler.
  • Abstraction over an executor so we can spawn tasks under WASM the same way we do usually.
  • A TTL cache which can be used to time out repeated operations that might experience intermittent failures.
  • Named futures returned from methods on types in the crate root.
  • Types to interact with the native Matrix authentication API.
  • High-level media API.
  • High-level push notification settings API
  • oidcexperimental-oidc
    High-level OpenID Connect API using the Authorization Code flow.
  • High-level room API
  • Types and traits for working with the Matrix protocol.
  • sliding_syncexperimental-sliding-sync
    Sliding Sync Client implementation of MSC3575 & extensions
  • Collection of small helpers that implement store-based locks.
  • The SDK’s representation of the result of a /sync request.
  • Utility types and traits.
  • widgetexperimental-widgets
    Widget API implementation.

Macros§

Structs§

Enums§

  • An enum over all the possible authentication APIs.
  • A user session using one of the available authentication APIs.
  • Errors that can happen in ClientBuilder::build.
  • The name of the room, either from the metadata or calculated according to matrix specification
  • Internal representation of errors.
  • An HTTP error, representing either a connection error or an error while converting the raw HTTP response into a Matrix response.
  • An error encountered when trying to parse an invalid ID string.
  • ImageErrorimage-proc
    All possible errors that can happen during image processing.
  • Enum controlling if a loop running callbacks should continue or abort.
  • Errors that can occur when manipulating push notification settings.
  • Errors that can happen when refreshing an access token.
  • Enum keeping track in which state the room is, e.g. if our own user is joined, invited, or has left the room.
  • An error response from a Matrix API call, using a client API specific representation if the endpoint is from that.
  • Represents changes that can occur to a Clients Session.
  • Session tokens, for any kind of authentication.
  • State store specific error type.

Constants§

Traits§

  • Super trait that is used for our store traits, this trait will differ if it’s used on WASM. WASM targets will not require Send and Sync to have implemented, while other targets will.
  • SendOutsideWasmNon-WebAssembly
    Alias for Send on non-wasm, empty trait (implemented by everything) on wasm.
  • An abstract state store trait that can be used to implement different stores for the SDK.
  • Convenience functionality for state stores.
  • SyncOutsideWasmNon-WebAssembly
    Alias for Sync on non-wasm, empty trait (implemented by everything) on wasm.

Type Aliases§

Attribute Macros§