Struct matrix_sdk::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.

Example

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(Arc::new(reqwest_builder.build()?));

Implementations

impl ClientBuilder

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

Set the homeserver URL to use.

This method is mutually exclusive with user_id(), if you set both whatever was set last will be used.

pub fn user_id(self, user_id: &UserId) -> Self

👎Deprecated: Use server_name(user_id.server_name()) instead

Set the user ID to discover the homeserver from.

builder.user_id(id) is a shortcut for builder.server_name(id.server_name()).

This method is mutually exclusive with homeserver_url(), if you set both 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.

This method is mutually exclusive with homeserver_url(), if you set both whatever was set last will be used.

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

Available on crate feature sled only.

Set up the store configuration for a sled store.

This is a shorthand for .store_config(matrix_sdk_sled::make_store_config(path, passphrase)?).

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 the store module or directly from one of the store crates.

Arguments

• store_config - The configuration of the store.

Example

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

let store_config = StoreConfig::new().state_store(custom_state_store);
let client_builder = Client::builder().store_config(store_config);

pub fn state_store(self, store: impl StateStore + 'static) -> Self

👎Deprecated: Use store_config, sled_store or indexeddb_store instead

Set a custom implementation of a StateStore.

The state store should be opened before being set.

pub fn crypto_store(self, store: impl CryptoStore + 'static) -> Self

👎Deprecated: Use store_config, sled_store or indexeddb_store instead

Available on crate feature e2e-encryption only.

Set a custom implementation of a CryptoStore.

The crypto store should be opened before being set.

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

Available on non-WebAssembly only.

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.

Example

use matrix_sdk::Client;

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

pub fn disable_ssl_verification(self) -> Self

Available on non-WebAssembly only.

Disable SSL verification for the HTTP requests.

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

Available on non-WebAssembly only.

Set a custom HTTP user agent for the client.

pub fn http_client(self, client: Arc<dyn HttpSend>) -> Self

Specify an HTTP client to handle sending requests and receiving responses.

Any type that implements the HttpSend trait can be used to send / receive http types.

This method is mutually exclusive with 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 Client::session_tokens_signal() for example, to be able to restore the session later.

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.

const 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.