ruma-client

ruma-client is a low-level Matrix client library for Rust.

Status

This project is a work in progress and not ready for production usage yet. If you are looking to build a client application or a bot, you are likely going to have a better time using the Matrix Rust SDK, which also builds on the other Ruma crates but provides a higher-level API.

lib.rs:

A minimal Matrix client library.

Usage

Begin by creating a Client, selecting one of the type aliases from ruma_client::http_client for the generic parameter. For the client API, there are login and registration methods provided for the client (feature client-api):

# // HACK: "ignore" the doctest here because client.log_in needs client-api feature.
// type HttpClient = ruma_client::http_client::_;
# type HttpClient = ruma_client::http_client::Dummy;
# let work = async {
let homeserver_url = "https://example.com".to_owned();
let client = ruma::Client::builder()
    .homeserver_url(homeserver_url)
    .build::<ruma_client::http_client::Dummy>()
    .await?;

let session = client
    .log_in("@alice:example.com", "secret", None, None)
    .await?;

// You're now logged in! Write the session to a file if you want to restore it later.
// Then start using the API!
# Result::<(), ruma_client::Error<_, _>>::Ok(())
# };

You can also pass an existing access token to the Client constructor to restore a previous session rather than calling log_in. This can also be used to create a session for an application service that does not need to log in, but uses the access_token directly:

#
let homeserver_url = "https://example.com".to_owned();
let client = ruma_client::Client::builder()
    .homeserver_url(homeserver_url)
    .access_token(Some("as_access_token".into()))
    .build::<HttpClient>()
    .await?;

// make calls to the API

The Client type also provides methods for registering a new account if you don't already have one with the given homeserver.

Beyond these basic convenience methods, ruma-client gives you access to the entire Matrix client-server API via the request method. You can pass it any of the Request types found in ruma::api::* and get back a corresponding response from the homeserver.

For example:

use ruma_client_api::alias::get_alias;
use ruma_common::{api::MatrixVersion, owned_room_alias_id, room_id};

let alias = owned_room_alias_id!("#example_room:example.com");
let response = client.send_request(get_alias::v3::Request::new(alias)).await?;

assert_eq!(response.room_id, room_id!("!n8f893n9:example.com"));

Crate features

The following features activate http client types in the http_client module:

• hyper
• hyper-native-tls
• hyper-rustls
• reqwest – if you use the reqwest library already, activate this feature and configure the TLS backend on reqwest directly. If you want to use reqwest but don't depend on it already, use one of the sub-features instead. For details on the meaning of these, see reqwest's documentation:
  • reqwest-native-tls
  • reqwest-native-tls-alpn
  • reqwest-native-tls-vendored
  • reqwest-rustls-manual-roots
  • reqwest-rustls-webpki-roots
  • reqwest-rustls-native-roots