Struct PubkyHttpClient 

pub struct PubkyHttpClient { /* private fields */ }

Transport client for Pubky homeserver APIs and generic HTTP, with PKARR-aware URL handling.

PubkyHttpClient is the low-level engine the higher-level actors (PubkySession, PubkyStorage, Pkdns, PubkyAuthFlow) are built on. It owns:

• A pkarr DHT client (for resolving pkdns endpoints and publishing records).
• One or more reqwest HTTP clients (platform-specific).

What it does

• Detects pkarr public-key hosts and resolves them to concrete endpoints.
• Internally, uses a unified cross_request(..) that works the same on native rust and WASM (WASM performs endpoint resolution & header injection; native is a thin wrapper).

What it doesn’t do

• It is not session/identity aware. No cookies, no per-user scoping. For authenticated per-user flows use crate::PubkySession.

When to use

• You want direct control over the PubkyHttpClient (power users, libs).
• You’re wiring custom flows/tests and don’t need the high-level ergonomics.

Construction

Use PubkyHttpClient::builder() to tweak timeouts, relays, or user-agent; or pick sensible defaults via PubkyHttpClient::new(). A PubkyHttpClient::testnet() helper configures a local test network.

Platform notes

• Native (rust, not WASM target):
  • ICANN domains use standard X.509 TLS via the icann_http client.
  • Pubky/PKDNS hosts (public-key hostnames or _pubky.<pk> domains) use PubkyTLS (TLS with RFC 7250 Raw Public Keys), verifying the connection against the target public key—no CA chain involved.
• WASM:
  • All requests use the browser’s standard X.509 TLS stack.
  • For Pubky/PKDNS hosts, private method cross_request(..) resolves the endpoint via PKARR, rewrites the URL (including testnet/localhost mapping), and may add a pubky-host header to convey the intended public-key host.

Examples

Basic construction. Works out of the box for mainline DHT pkarr endpoints.

let client = PubkyHttpClient::new()?;

Fetching a standard ICANN URL or any URL with request:

let client = PubkyHttpClient::new()?;
let url = Url::parse("https://example.com")?;
let resp = client.request(Method::GET, &url)
    .send().await?;
assert!(resp.status().is_success());

Note: request(..) is available on native targets. On WASM, use the high-level actors (e.g., Pubky, SessionStorage, PublicStorage) or the JS bindings’ client.fetch(..) provided in bindings/js.

Fetching a Pubky resource via its transport URL:

let client = PubkyHttpClient::new()?;
// Pubky App profile of user Pubky https://pubky.app/profile/ihaqcthsdbk751sxctk849bdr7yz7a934qen5gmpcbwcur49i97y
let user = "ihaqcthsdbk751sxctk849bdr7yz7a934qen5gmpcbwcur49i97y";
let url = format!("https://_pubky.{user}/pub/pubky.app/profile.json");
let resp = client.request(Method::GET, &url).send().await?;
let info = resp.text().await?;

Tip: For authenticated reads/writes, prefer session.storage().get(...), which automatically scopes paths and attaches the right session cookie.

Implementations

impl PubkyHttpClient

pub fn new() -> Result<Self, BuildError>

Creates a client configured for public mainline DHT and pkarr relays.

Errors

• Returns BuildError if the underlying HTTP clients cannot be constructed or configured.

pub fn builder() -> PubkyHttpClientBuilder

Returns a builder to edit settings before creating PubkyHttpClient. Prefer this when you need to control PKARR/DHT inputs (relays, bootstrap); resolution itself remains automatic during requests.

pub fn testnet() -> Result<Self, BuildError>

Creates a PubkyHttpClient preconfigured to talk to a locally running Pubky testnet.

What this configures

On non wasm targets (not(target_arch = "wasm32")):

• DHT bootstrap to the local testnet node at: "localhost:6881"
• PKARR relay base URL: "http://localhost:15411"

On WASM targets:

• Browser environments can’t dial UDP DHT; the builder is adjusted to use the testnet HTTP endpoints suitable for the browser (no UDP bootstrap). PKARR HTTP relay still points at http://localhost:15411 unless you override it.

Requirements

You must have pubky-testnet binary running locally (it provides a homeserver, a DHT bootstrap, and a PKARR relay on the ports above). For example:

# From the pubky repo:
cargo run -p pubky-testnet

Examples

use pubky::PubkyHttpClient;

let client = PubkyHttpClient::testnet()?;
// Now all https://_pubky.<pubkey>/... requests resolve via the local testnet
// DHT/PKARR, and hit the local homeserver.

See also

• PubkyHttpClientBuilder::testnet to tweak additional settings first.
• PubkyHttpClientBuilder::testnet_with_host to target a non-localhost host.

Errors

• Returns BuildError if the underlying HTTP clients cannot be constructed or configured for the testnet settings.

pub const fn pkarr(&self) -> &Client

Returns a reference to the internal Pkarr Client.

impl PubkyHttpClient

pub async fn prepare_request(&self, url: &mut Url) -> Result<Option<String>>

Detect pubky hosts and return the z32 public key when applicable.

Native builds do not rewrite URLs; we only detect pubky hosts and return the pubky-host value when applicable.

Errors

Returns RequestError::Validation if the host uses a pubky prefix.

pub fn request<U: IntoUrl>(&self, method: Method, url: &U) -> RequestBuilder

Start building a Request with the Method and Url (native-only).

Returns a RequestBuilder, which will allow setting headers and the request body before sending.

Differs from reqwest::Client::request, in that it can make requests to:

1. HTTPS URLs with a crate::PublicKey as top-level domain, by resolving corresponding endpoints, and verifying TLS certificates accordingly. (example: https://o4dksfbqk85ogzdb5osziw6befigbuxmuxkuxq8434q89uj56uyy)
2. _pubky.<public-key> URLs like https://_pubky.o4dksfbqk85ogzdb5osziw6befigbuxmuxkuxq8434q89uj56uyy

Errors

This method fails whenever the supplied Url cannot be parsed.

Trait Implementations

impl Clone for PubkyHttpClient

fn clone(&self) -> PubkyHttpClient

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for PubkyHttpClient

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

Formats the value using the given formatter.