pub struct ClientBuilder { /* private fields */ }
Expand description

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§

source§

impl ClientBuilder

source

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

Set the homeserver URL to use.

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

source

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

Available on crate feature experimental-sliding-sync only.

Set the sliding-sync proxy URL to use.

This value is always used no matter if the homeserver URL was defined with Self::homeserver_url or auto-discovered via Self::server_name, Self::insecure_server_name_no_tls, or Self::server_name_or_homeserver_url - any proxy discovered via the well-known lookup will be ignored.

source

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: homeserver_url() server_name() insecure_server_name_no_tls() server_name_or_homeserver_url(), If you set more than one, then whatever was set last will be used.

source

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: homeserver_url() server_name() insecure_server_name_no_tls() server_name_or_homeserver_url(), If you set more than one, then whatever was set last will be used.

source

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 homeserver_url()), so you can guarantee that the client is ready to use.

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

source

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

Available on crate feature sqlite only.

Set up the store configuration for a SQLite store.

source

pub fn indexeddb_store(self, name: &str, passphrase: Option<&str>) -> Self

Available on crate feature indexeddb only.

Set up the store configuration for a IndexedDB store.

source

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().state_store(custom_state_store);
let client_builder = Client::builder().store_config(store_config);
source

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.

source

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

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

source

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.
§Examples
use matrix_sdk::Client;

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

pub fn disable_ssl_verification(self) -> Self

Available on non-WebAssembly only.

Disable SSL verification for the HTTP requests.

source

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.

source

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

Available on non-WebAssembly only.

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.

source

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 and user_agent().

source

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.

source

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.

source

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

Available on crate feature e2e-encryption only.

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

source

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§

source§

impl Clone for ClientBuilder

source§

fn clone(&self) -> ClientBuilder

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for ClientBuilder

source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> CompatExt for T

§

fn compat(self) -> Compat<T>

Applies the [Compat] adapter by value. Read more
§

fn compat_ref(&self) -> Compat<&T>

Applies the [Compat] adapter by shared reference. Read more
§

fn compat_mut(&mut self) -> Compat<&mut T>

Applies the [Compat] adapter by mutable reference. Read more
source§

impl<T> DynClone for T
where T: Clone,

source§

fn __clone_box(&self, _: Private) -> *mut ()

source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> FutureExt for T

§

fn with_context(self, otel_cx: Context) -> WithContext<Self>

Attaches the provided Context to this type, returning a WithContext wrapper. Read more
§

fn with_current_context(self) -> WithContext<Self>

Attaches the current Context to this type, returning a WithContext wrapper. Read more
§

impl<T, UT> HandleAlloc<UT> for T
where T: Send + Sync,

§

fn new_handle(value: Arc<T>) -> Handle

Create a new handle for an Arc value Read more
§

fn clone_handle(handle: Handle) -> Handle

Clone a handle Read more
§

fn consume_handle(handle: Handle) -> Arc<T>

Consume a handle, getting back the initial Arc<>
§

fn get_arc(handle: Handle) -> Arc<Self>

Get a clone of the Arc<> using a “borrowed” handle. Read more
§

impl<T, W> HasTypeWitness<W> for T
where W: MakeTypeWitness<Arg = T>, T: ?Sized,

§

const WITNESS: W = W::MAKE

A constant of the type witness
§

impl<T> Identity for T
where T: ?Sized,

§

type Type = T

The same type as Self, used to emulate type equality bounds (T == U) with associated type equality constraints (T: Identity<Type = U>).
§

const TYPE_EQ: TypeEq<T, <T as Identity>::Type> = TypeEq::NEW

Proof that Self is the same type as Self::Type, provides methods for casting between Self and Self::Type.
source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

§

impl<T> IntoResult<T> for T

§

type Err = Infallible

§

fn into_result(self) -> Result<T, <T as IntoResult<T>>::Err>

source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

impl<T> Any for T
where T: Any,

source§

impl<T> AsyncTraitDeps for T

source§

impl<T> CloneAny for T
where T: Any + Clone,

source§

impl<T> CloneAnySend for T
where T: Any + Send + Clone,

source§

impl<T> CloneAnySendSync for T
where T: Any + Send + Sync + Clone,

source§

impl<T> CloneAnySync for T
where T: Any + Sync + Clone,

source§

impl<T> SendOutsideWasm for T
where T: Send,

source§

impl<T> SyncOutsideWasm for T
where T: Sync,