Leyline API

This page and the API reference are the public contract of leyline-http (import name leyline). The API reference lists every public item and is generated from the compiler; cargo truesight check fails when it no longer matches the code. This page maps each job to its call and to the guide that explains it, and holds the error kinds and the rules the API follows.

The bench-internals feature and the leyline_unstable_bssl compiler flag expose internals for Leyline’s own tests and the BoringSSL context builder. Neither is part of the contract, and the API reference leaves both out.

Overview

one-off     leyline::get(url)               one GET from a plain session
session     Session::new()                  plain client, cannot fail
            Session::browser(browser)       browser session, cannot fail
            Session::builder() → SessionBuilder → build() → Session   (no browser: plain client)
            session.with_proxy(config)      clone that shares the pool, other proxy
            session.fresh_pool()            clone with a new pool and TLS session cache
            session.with_cookie_jar(jar)    clone that shares the pool, other jar
            session.with_redirect(policy)   clone that shares the pool, other redirect policy
            session.with_identity(id)       clone with another identity, own pool partition
            session.with_base_url(url)      clone that shares the pool, other base URL
            session.tab() → Tab              current page, initiator for each request
            session.shutdown() · is_shut_down()   stop every clone and derived session
            session.state() → SessionState   TLS tickets, Alt-Svc, HSTS
            Device::capture / open / save_to / load_from   one saved account device
            device.autosave(&session, path, interval or DeviceAutosaveOptions) → DeviceAutosave · update / track / device / flush / shutdown
            device.tab(&session) → Tab        tab on the saved page
crawl       SessionBuilder::host_limits(HostLimits) · proxy_pool(ProxyPool) · RequestBuilder::tag
            HostLimits: max_in_flight · per_second · host · max_total_in_flight · pause_on · pause_for · max_pause
            ProxyPool::identified · rotate_on_block · Session::host_stats · BlockRules::statuses
            Session::robots(url, agent) → Robots: allows · allows_use(url, Purpose) · crawl_delay · sitemaps · source
            Session::crawl(seed) → Crawl: respect(Respect) · ignore_robots · scope(Scope) · limit · host_limits · next → CrawlPage · stats → CrawlStats (feature `html`)
request     session.get / post / put / patch / delete / head / request(Method, url) → RequestBuilder
send        RequestBuilder.send() or .await → Response
            RequestBuilder.download(path, limit) → bytes written
            RequestBuilder.pages() → Pages   follows Link rel="next"
            session.execute(http::Request<Body>) for prebuilt requests and tower
read        Response: status · headers · header · text · bytes · json · read_until
            raw: into_stream · copy_to      decoded and capped: into_decoded_stream · copy_decoded_to
            Response: url · redirect_chain · version · timing · attempts · proxy
            Response: link · links · relay_headers(RelayBody) · block · download_to
fail        Error · err.kind() → Kind · err.category() → ErrorCategory · gateway_status()
            RequestBuilder::error_for_status · err.status / body / body_text / headers / header / retry_after / retries_exhausted / attempts / proxy
            Error::find(&dyn std::error::Error)   leyline error under other layers
policy      TimeoutConfig · RetryPolicy · RedirectPolicy   (session default, request override)
            RetryPolicy: retry_if · wait_header · retry_unsent · skip_blocks · max_retry_after
            TimeoutConfig: body · error_body    CompressionConfig: max_body_size · max_error_body
identity    Browser · Platform · ChromiumBrand · Identity
observe     Trace hooks · Trace::summary · trace::Metrics · trace::Fanout · Response::timing · Response::tls · Response::audit
tower       LeylineService (feature `tower`) · relay_headers(&HeaderMap, RelayBody) · redact_url
html        html::forms · Form::find · FormEnctype · Tab::submit_form · html::meta · html::links → Anchor · html::text · html::canonical · html::Directives (feature `html`)
test        testing::TestServer::http / https / http_on · TestResponse::delay / chunks / close
            RecordedRequest: raw · request_line · header_values · header_count · text (feature `test-util`)

One function per job. A setter that takes a config type accepts impl Into<Config> where a shorthand exists, so the common case stays one call:

#![allow(unused)]
fn main() {
use std::time::Duration;

use leyline::{Browser, Family, Platform, ProtocolPolicy, Session, TimeoutConfig};

async fn run() -> leyline::Result<()> {
let session = Session::browser(Browser::default());
let body = session.get("https://example.com/").await?.text().await?;

let session = Session::builder()
    .browser(Browser::latest(Family::Firefox))
    .platform(Platform::MacOS)
    .protocol(ProtocolPolicy::Http2)
    .timeout(Duration::from_secs(15))
    .proxy("http://user:pass@host:8080")
    .build()?;

let resp = session
    .post("https://example.com/api")
    .header("x-trace", "1")
    .json(&serde_json::json!({ "q": 1 }))
    .timeout(TimeoutConfig::new().total(Duration::from_secs(5)))
    .await?;
drop((body, resp));
Ok(())
}
}

Where each job is documented

Sessions and identities

Requests and responses

Policy, transport, and observation

Errors

One error type: leyline::Error, Send + Sync + 'static. Read err.kind() for the Kind below, or err.category() for the ErrorCategory that groups it for logs, metrics, and gateway statuses. Errors covers categories, predicates, attempts, source errors, and status mapping.

The profile loaders return profile::ProfileError, and multipart::Form::file and Part::file return std::io::Result; neither has a Kind.

Features

Default: charset, compression-gzip, compression-brotli, compression-deflate, compression-zstd, multipart, websocket, http3, html. Opt-in: socks, tower, test-util, bench-internals. full enables every feature except test-util and bench-internals. See Features and targets.

API shape

• One function per job, and one owner each for timing, retries, redirects, cookies, and body decoding.
• Config types (TimeoutConfig, RetryPolicy, RedirectPolicy, ProxyConfig, DnsConfig, TlsTrustConfig, PoolConfig, SocketConfig, HappyEyeballsConfig, CompressionConfig, WebSocketConfig) have private fields and consuming setters named after the field, with no with_ prefix. A setter for an optional value takes impl Into<Option<T>>, and None turns the setting off; RetryPolicy::max_retry_after takes a Duration: transient() sets it to 60 s, and none() has no cap. A setter that adds to a list starts with add_ or appends one item (rule, on_status).
• Every SessionBuilder config setter replaces the whole value. Start from ::new(), which carries the defaults. A request setter merges over the session value field by field.
• Public enums, and public structs with public fields, are #[non_exhaustive], Cookie and SameSite included. The exceptions are audit::Ja3Input, Ja4Input, and Ja4hInput, which callers fill with a struct literal.
• Builder input errors surface at build(), send(), or connect(), never eagerly. Identity is a value type, so its checks run at the call.
• IntoUrl is sealed. Session::new() and Session::browser(..) never fail: a trust-store problem fails later requests with Kind::Tls, and an invalid environment proxy fails them with Kind::Proxy.
• A patch release never removes a Browser variant. A retired profile keeps its variant, marked #[deprecated] through its [meta] deprecated note, until a minor release removes it. Browser::latest and Browser::for_platform never return a deprecated profile.
• Browser, Family, Platform, and ChromiumBrand serialize as the stable lowercase id that id() returns, and FromStr reads it back.

Profile schema

BrowserProfile and the leyline::profile types mirror the bundled profiles/<family>/<version>.toml files; field names are the TOML keys. profiles/bare.toml holds the bare profile and profiles/platforms.toml the per-platform TCP values. The [meta] keys capture, variant, hello, platform_browser, deprecated, and verified_at are valid and ignored at runtime; they are not fields of ProfileMeta, and the build reads the first five to generate Browser. The schema is part of the API: a patch release can add fields, and removing or renaming one needs a minor release. See Profiles.

Do not add

• A second constructor for a browser, brand, or platform (Session::chrome(), SessionBuilder::macos()). Use browser, platform, brand.
• A per-field copy of a config type on SessionBuilder or RequestBuilder (connect_timeout, resolve_host, add_root_certificate_der, max_redirects). Add the field to the config type.
• A second setter with other header semantics (append_header, set_header) or a typed shortcut for one header (referer). SessionBuilder::user_agent is the one session shortcut, because it replaces a profile default.
• A second request type. Session::execute takes http::Request<Body>.
• A second middleware model inside the send path. Wrap LeylineService with tower layers.
• A second body reader (text_utf8, into_text, as_bytes) or a second Content-Encoding decoder.
• A second cookie store, such as a per-response cookie map.
• A getter that copies session configuration back out. The exceptions report the state of a built session: Session::identity, Session::proxy_url, Session::cookies, Session::pool_stats, and Session::host_stats.
• A second timing, retry, or redirect owner.
• A browser, version, or brand table in Rust. Profile data owns it.