Crate matrix_sdk

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.

Re-exports

• pub use authentication::AuthApi;
• pub use authentication::AuthSession;
• pub use authentication::SessionTokens;
• pub use media::Media;
• pub use pusher::Pusher;
• pub use room::Room;
• pub use sliding_sync::SlidingSync;
• pub use sliding_sync::SlidingSyncBuilder;
• pub use sliding_sync::SlidingSyncList;
• pub use sliding_sync::SlidingSyncListBuilder;
• pub use sliding_sync::SlidingSyncListLoadingState;
• pub use sliding_sync::SlidingSyncMode;
• pub use sliding_sync::SlidingSyncRoom;
• pub use sliding_sync::UpdateSummary;
• pub use bytes;
• pub use matrix_sdk_base::crypto;
• pub use reqwest;

Modules

• attachment
  Types and traits for attachments.
• authentication
  Types and functions related to authentication in Matrix.
• config
  Configuration to change the behaviour of the Client.
• debug
  Helpers for creating std::fmt::Debug implementations.
• deserialized_responses
  SDK-specific variations of response types from Ruma.
• encryption
  End-to-end encryption related types
• event_cache
  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.
• event_handler
  Types and traits related for event handlers. For usage, see Client::add_event_handler.
• executor
  Abstraction over an executor so we can spawn tasks under WASM the same way we do usually.
• failures_cache
  A TTL cache which can be used to time out repeated operations that might experience intermittent failures.
• futures
  Named futures returned from methods on types in the crate root.
• linked_chunk
  A linked chunk is the underlying data structure that holds all events.
• live_location_share
  Types for live location sharing.
• locks
  Simplified locks hat panic instead of returning a Result when the lock is poisoned.
• media
  High-level media API.
• notification_settings
  High-level push notification settings API
• pusher
  High-level pusher API.
• ring_buffer
• room
  High-level room API
• room_directory_search
  Types for searching the public room directory.
• room_preview
  Preview of a room, whether we’ve joined it/left it/been invited to it, or not.
• ruma
  Types and traits for working with the Matrix protocol.
• send_queue
  A send queue facility to serializing queuing and sending of messages.
• sleep
• sliding_sync
  Sliding Sync Client implementation of MSC3575 & extensions
• store
  The state store holds the overall state for rooms, users and their profiles and their timelines. It is an overall cache for faster access and convenience- accessible through Store.
• store_locks
  Collection of small helpers that implement store-based locks.
• sync
  The SDK’s representation of the result of a /sync request.
• timeout
• tracing_timer
• ttl_cache
  A TTL cache which can be used to time out repeated operations that might experience intermittent failures.
• utils
  Utility types and traits.

Macros

• boxed_into_future
• timer
  Macro to create a RAII timer that will log a tracing event once it’s dropped.

Structs

• Account
  A high-level API to manage the client owner’s account.
• BaseRoom
  The underlying room data structure collecting state for joined, left and invited rooms.
• BaseRoomMember
  A member of a room.
• Client
  An async/await enabled Matrix client.
• ClientBuilder
  Builder that allows creating and configuring various parts of a Client.
• ComposerDraft
  Current draft of the composer for the room.
• MemoryStore
  In-memory, non-persistent implementation of the StateStore.
• OwnedServerName
  Owned variant of ServerName
• RoomCreateWithCreatorEventContent
  The content of an m.room.create event, with a required creator field.
• RoomHero
  Information about a member considered to be a room hero.
• RoomInfo
  The underlying pure data structure for joined and left rooms.
• RoomMemberships
  Room membership filter as a bitset.
• ServerName
  A Matrix-spec compliant server name.
• SessionMeta
  The Matrix user session info.
• SqliteCryptoStore
  A sqlite based cryptostore.
• SqliteEventCacheStore
  A SQLite-based event cache store.
• SqliteStateStore
  A sqlite based cryptostore.
• StateChanges
  Store state changes and pass them to the StateStore.
• TransmissionProgress
  Progress of sending or receiving a payload.

Enums

• ClientBuildError
  Errors that can happen in ClientBuilder::build.
• ComposerDraftType
  The type of draft of the composer.
• EncryptionState
  Represents the state of a room encryption.
• Error
  Internal representation of errors.
• HttpError
  An HTTP error, representing either a connection error or an error while converting the raw HTTP response into a Matrix response.
• IdParseError
  An error encountered when trying to parse an invalid ID string.
• LoopCtrl
  Enum controlling if a loop running callbacks should continue or abort.
• NotificationSettingsError
  Errors that can occur when manipulating push notification settings.
• QueueWedgeError
  Represents a failed to send unrecoverable error of an event sent via the send queue.
• RefreshTokenError
  Errors that can happen when refreshing an access token.
• RoomDisplayName
  The name of the room, either from the metadata or calculated according to matrix specification
• RoomState
  Enum keeping track in which state the room is, e.g. if our own user is joined, RoomState::Invited, or has left the room.
• RumaApiError
  An error response from a Matrix API call, using a client API specific representation if the endpoint is from that.
• SessionChange
  Represents changes that can occur to a Clients Session.
• StoreError
  State store specific error type.

Constants

• LEASE_DURATION_MS
  Amount of time a lease of the lock should last, in milliseconds.

Traits

• AsyncTraitDeps
  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.
• SendOutsideWasm
  Alias for Send on non-wasm, empty trait (implemented by everything) on wasm.
• StateStore
  An abstract state store trait that can be used to implement different stores for the SDK.
• StateStoreExt
  Convenience functionality for state stores.
• SyncOutsideWasm
  Alias for Sync on non-wasm, empty trait (implemented by everything) on wasm.

Functions

• sanitize_server_name
  Creates a server name from a user supplied string. The string is first sanitized by removing whitespace, the http(s) scheme and any trailing slashes before being parsed.

Type Aliases

• BoxFuture
• DynStateStore
  A type-erased StateStore.
• HttpResult
  Result type of a pure HTTP request.
• Result
  Result type of the matrix-sdk.

Attribute Macros

• async_trait