Crate client

Available on crate feature client only.

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

// type HttpClient = ruma_client::http_client::_;
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!

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

Modules

• http_client
  This module contains an abstraction for HTTP clients as well as friendly-named re-exports of client types that implement this trait.

Structs

• Client
  A client for the Matrix client-server API.
• ClientBuilder
  A Client builder.

Enums

• Error
  An error that can occur during client operations.

Traits

• DefaultConstructibleHttpClient
  An HTTP client that has a default configuration.
• HttpClient
  An HTTP client that can be used to send requests to a Matrix homeserver.
• HttpClientExt
  Convenience functionality on top of HttpClient.

Type Aliases

• ResponseError
  The error type for sending the request R with the http client C.
• ResponseResult
  The result of sending the request R with the http client C.