Crate ruma_client

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 MatrixClient = ruma_client::Client<ruma_client::http_client::_>;
let homeserver_url = "https://example.com".parse().unwrap();
let client = MatrixClient::new(homeserver_url, None);

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 work = async {
    let homeserver_url = "https://example.com".parse().unwrap();
    let client = MatrixClient::new(homeserver_url, Some("as_access_token".into()));

    // 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 std::convert::TryFrom;

use ruma_client_api::r0::alias::get_alias;
use ruma_identifiers::{room_alias_id, room_id};

async {
    let response = client
        .send_request(get_alias::Request::new(&room_alias_id!("#example_room:example.com")))
        .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
• isahc
• 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

Re-exports

pub use self::http_client::DefaultConstructibleHttpClient;

pub use self::http_client::HttpClient;

pub use self::http_client::HttpClientExt;

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.

Enums

Error

An error that can occur during client operations.

Type Definitions

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.