ATrium XRPC Client

This library provides clients that implement the XrpcClient defined in atrium-xrpc. To accommodate a wide range of use cases, four feature flags are provided to allow developers to choose the best asynchronous HTTP client library for their project as a backend.

Features

• reqwest-default-tls (default)
• reqwest
• isahc
• surf

Usage examples are provided below.

reqwest

If you are using tokio as your asynchronous runtime, you may find it convenient to utilize the reqwest backend with this feature, which is a high-level asynchronous HTTP Client. By default, transport layer security (TLS) with reqwest's default-tls feature is used.

[dependencies]
atrium-xrpc-client = "*"

use atrium_xrpc_client::reqwest::ReqwestClient;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = ReqwestClient::new("https://bsky.social");
    Ok(())
}

If you want to use the rustls TLS backend, or use reqwest::Client with your own configuration, you can directly specify with the ReqwestClientBuilder:

[dependencies]
atrium-xrpc-client = { version = "*", default-features = false, features = ["reqwest"] }
reqwest = { version = "0.11.24", default-features = false, features = ["rustls-tls"] }

use atrium_xrpc_client::reqwest::ReqwestClientBuilder;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = ReqwestClientBuilder::new("https://bsky.social")
        .client(
            reqwest::ClientBuilder::new()
                .timeout(std::time::Duration::from_millis(1000))
                .use_rustls_tls()
                .build()?,
        )
        .build();
    Ok(())
}

For more details, refer to the reqwest documentation.

isahc

The reqwest client may not work on asynchronous runtimes other than tokio. As an alternative, we offer the feature that uses isahc as the backend.

[dependencies]
atrium-xrpc-client = { version = "*", default-features = false, features = ["isahc"]}

use atrium_xrpc_client::isahc::IsahcClient;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = IsahcClient::new("https://bsky.social");
    Ok(())
}

Similarly, you can directly specify an isahc::HttpClient with your own settings:

[dependencies]
atrium-xrpc-client = { version = "*", default-features = false, features = ["isahc"]}
isahc = "1.7.2"

use atrium_xrpc_client::isahc::IsahcClientBuilder;
use isahc::config::Configurable;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = IsahcClientBuilder::new("https://bsky.social")
        .client(
            isahc::HttpClientBuilder::new()
                .timeout(std::time::Duration::from_millis(1000))
                .build()?,
        )
        .build();
    Ok(())
}

For more details, refer to the isahc documentation.

surf

For cases such as using rustls with asynchronous runtimes other than tokio, we also provide a feature that uses surf built with async-std as a backend.

Using DefaultClient with surf is complicated by the various feature flags. Therefore, unlike the first two options, you must always specify surf::Client when creating a client with this module.

[dependencies]
atrium-xrpc-client = { version = "*", default-features = false, features = ["surf"]}
surf = { version = "2.3.2", default-features = false, features = ["h1-client-rustls"] }

use atrium_xrpc_client::surf::SurfClient;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = SurfClient::new("https://bsky.social", surf::Client::new());
    Ok(())
}

Using http_client and its bundled implementation may clarify which backend you are using:

[dependencies]
atrium-xrpc-client = { version = "*", default-features = false, features = ["surf"]}
surf = { version = "2.3.2", default-features = false }
http-client = { version = "6.5.3", default-features = false, features = ["h1_client", "rustls"] }

use atrium_xrpc_client::surf::SurfClient;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = SurfClient::new(
        "https://bsky.social",
        surf::Client::with_http_client(http_client::h1::H1Client::try_from(
            http_client::Config::default()
                .set_timeout(Some(std::time::Duration::from_millis(1000))),
        )?),
    );
    Ok(())
}

For more details, refer to the surf documentation.

WASM support

When the target_arch is wasm32, only reqwest::* will be enabled, and its client implementation automatically switches to the WASM one .