Struct ClientBuilder

pub struct ClientBuilder { /* private fields */ }

Builder that allows creating and configuring various parts of a Client.

When setting the StateStore it is up to the user to open/connect the storage backend before client creation.

Examples

use matrix_sdk::Client;
// To pass all the request through mitmproxy set the proxy and disable SSL
// verification

let client_builder = Client::builder()
    .proxy("http://localhost:8080")
    .disable_ssl_verification();

Example for using a custom http client

Note: setting a custom http client will ignore user_agent, proxy, and disable_ssl_verification - you’d need to set these yourself if you want them.

use std::sync::Arc;

use matrix_sdk::Client;

// setting up a custom http client
let reqwest_builder = reqwest::ClientBuilder::new()
    .https_only(true)
    .no_proxy()
    .user_agent("MyApp/v3.0");

let client_builder =
    Client::builder().http_client(reqwest_builder.build()?);

Implementations

impl ClientBuilder

pub fn homeserver_url(self, url: impl AsRef<str>) -> Self

Set the homeserver URL to use.

The following methods are mutually exclusive: Self::homeserver_url, Self::server_name Self::insecure_server_name_no_tls, Self::server_name_or_homeserver_url. If you set more than one, then whatever was set last will be used.

pub fn server_name(self, server_name: &ServerName) -> Self

Set the server name to discover the homeserver from.

We assume we can connect in HTTPS to that server. If that’s not the case, prefer using Self::insecure_server_name_no_tls.

The following methods are mutually exclusive: Self::homeserver_url, Self::server_name Self::insecure_server_name_no_tls, Self::server_name_or_homeserver_url. If you set more than one, then whatever was set last will be used.

pub fn insecure_server_name_no_tls(self, server_name: &ServerName) -> Self

Set the server name to discover the homeserver from, assuming an HTTP (not secured) scheme. This also relaxes OIDC discovery checks to allow HTTP schemes.

The following methods are mutually exclusive: Self::homeserver_url, Self::server_name Self::insecure_server_name_no_tls, Self::server_name_or_homeserver_url. If you set more than one, then whatever was set last will be used.

pub fn server_name_or_homeserver_url( self, server_name_or_url: impl AsRef<str>, ) -> Self

Set the server name to discover the homeserver from, falling back to using it as a homeserver URL if discovery fails. When falling back to a homeserver URL, a check is made to ensure that the server exists (unlike Self::homeserver_url, so you can guarantee that the client is ready to use.

The following methods are mutually exclusive: Self::homeserver_url, Self::server_name Self::insecure_server_name_no_tls, Self::server_name_or_homeserver_url. If you set more than one, then whatever was set last will be used.

pub fn sliding_sync_version_builder( self, version_builder: SlidingSyncVersionBuilder, ) -> Self

Set sliding sync to a specific version.

pub fn sqlite_store( self, path: impl AsRef<Path>, passphrase: Option<&str>, ) -> Self

Set up the store configuration for a SQLite store.

pub fn sqlite_store_with_cache_path( self, path: impl AsRef<Path>, cache_path: impl AsRef<Path>, passphrase: Option<&str>, ) -> Self

Set up the store configuration for a SQLite store with cached data separated out from state/crypto data.

pub fn store_config(self, store_config: StoreConfig) -> Self

Set up the store configuration.

The easiest way to get a StoreConfig is to use the make_store_config method from one of the store crates.

Arguments

• store_config - The configuration of the store.

Examples

use matrix_sdk::{config::StoreConfig, Client};

let store_config =
    StoreConfig::new("cross-process-store-locks-holder-name".to_owned())
        .state_store(custom_state_store);
let client_builder = Client::builder().store_config(store_config);

pub fn respect_login_well_known(self, value: bool) -> Self

Update the client’s homeserver URL with the discovery information present in the login response, if any.

pub fn request_config(self, request_config: RequestConfig) -> Self

Set the default timeout, fail and retry behavior for all HTTP requests.

pub fn proxy(self, proxy: impl AsRef<str>) -> Self

Set the proxy through which all the HTTP requests should go.

Note, only HTTP proxies are supported.

Arguments

• proxy - The HTTP URL of the proxy.

Examples

use matrix_sdk::Client;

let client_config = Client::builder().proxy("http://localhost:8080");

pub fn disable_ssl_verification(self) -> Self

Disable SSL verification for the HTTP requests.

pub fn user_agent(self, user_agent: impl AsRef<str>) -> Self

Set a custom HTTP user agent for the client.

pub fn add_root_certificates(self, certificates: Vec<Certificate>) -> Self

Add the given list of certificates to the certificate store of the HTTP client.

These additional certificates will be trusted and considered when establishing a HTTP request.

Internally this will call the reqwest::ClientBuilder::add_root_certificate() method.

pub fn disable_built_in_root_certificates(self) -> Self

Don’t trust any system root certificates, only trust the certificates provided through add_root_certificates.

pub fn http_client(self, client: Client) -> Self

Specify a reqwest::Client instance to handle sending requests and receiving responses.

This method is mutually exclusive with proxy(), disable_ssl_verification, add_root_certificates, disable_built_in_root_certificates, and user_agent().

pub fn server_versions( self, value: impl IntoIterator<Item = MatrixVersion>, ) -> Self

Specify the Matrix versions supported by the homeserver manually, rather than build() doing it using a get_supported_versions request.

This is helpful for test code that doesn’t care to mock that endpoint.

pub fn handle_refresh_tokens(self) -> Self

Handle refreshing access tokens automatically.

By default, the Client forwards any error and doesn’t handle errors with the access token, which means that Client::refresh_access_token() needs to be called manually to refresh access tokens.

Enabling this setting means that the Client will try to refresh the token automatically, which means that:

• If refreshing the token fails, the error is forwarded, so any endpoint can return HttpError::RefreshToken. If an UnknownToken error is encountered, it means that the user needs to be logged in again.

• The access token and refresh token need to be watched for changes, using the authentication API’s session_tokens_stream() for example, to be able to restore the session later.

pub fn with_encryption_settings(self, settings: EncryptionSettings) -> Self

Enables specific encryption settings that will persist throughout the entire lifetime of the Client.

pub fn with_room_key_recipient_strategy(self, strategy: CollectStrategy) -> Self

Set the strategy to be used for picking recipient devices, when sending an encrypted message.

pub fn with_decryption_trust_requirement( self, trust_requirement: TrustRequirement, ) -> Self

Set the trust requirement to be used when decrypting events.

pub fn cross_process_store_locks_holder_name(self, holder_name: String) -> Self

Set the cross-process store locks holder name.

The SDK provides cross-process store locks (see matrix_sdk_common::store_locks::CrossProcessStoreLock). The holder_name will be the value used for all cross-process store locks used by the Client being built.

If 2 concurrent Clients are running in 2 different process, this method must be called with different hold_name values.

pub async fn build(self) -> Result<Client, ClientBuildError>

Create a Client with the options set on this builder.

Errors

This method can fail for two general reasons:

• Invalid input: a missing or invalid homeserver URL or invalid proxy URL
• HTTP error: If you supplied a user ID instead of a homeserver URL, a server discovery request is made which can fail; if you didn’t set server_versions(false), that amounts to another request that can fail

Trait Implementations

impl Clone for ClientBuilder

fn clone(&self) -> ClientBuilder

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ClientBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.