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-native (default)
• reqwest-rustls
• isahc
• surf

Usage examples are provided below.

reqwest-native and reqwest-rustls

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. Within this crate, you have the choice of configuring reqwest with either reqwest/native-tls or reqwest/rustls-tls.

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

To use the reqwest::Client with the rustls TLS backend, specify the feature as follows:

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

In either case, you can use the ReqwestClient:

use atrium_xrpc_client::reqwest::ReqwestClient;

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

You can also directly specify a reqwest::Client with your own configuration:

[dependencies]
atrium-xrpc-client = { version = "*", default-features = false }
reqwest = { version = "0.11.22", 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.