Leyline user guide

Leyline is an HTTP client that mimics browsers on the wire. This guide shows you how to use it, in reading order.

Leyline has two kinds of session:

Session::browser(Browser::default()) impersonates the newest bundled Chrome on Windows. Session::new() and a builder with no browser build a plain client.

1. Quick start: add the dependency, send your first request.
2. Sessions: pick a browser, a platform, and a brand.
3. Choosing a profile: which browser and platform to claim.
4. Requests: methods, headers, bodies, presets, tabs, and downloads.
5. Responses: status, headers, Link pagination, block detection, bodies, timing, audit.
6. Streaming: stream a body in either direction, download a file, or stop a read early.
7. Redirects: the redirect limit and custom redirect policies.
8. Retries and timeouts: retry policies and the four timeouts.
9. Errors: group errors by category, map them to statuses, and find out which errors a retry covers.
10. Proxies: proxy rules, bypass lists, environment discovery.
11. Cookies: the jar, saving it, devices, and connection state.
12. WebSocket: connect over HTTP/2 or HTTP/1.1.
13. HTTP/3: the http3 feature and the protocol policy.
14. TLS trust: roots, certificate pins, client certificates, the TLS version floor.
15. Network: DNS overrides, Happy Eyeballs, socket options.
16. Logging and tracing: tracing targets and request phases.
17. Fingerprints: what a profile pins and how to audit it.
18. Features and targets: cargo features, targets, MSRV.
19. Supported platforms: the six build targets and the tools each one needs.
20. Cancellation: what happens when you drop a request or a body.
21. Testing: local plain and TLS servers, and asserting what was sent.
22. Service integration: Tower, shared sessions, and error mapping in a server.
23. Crawling: host limits, proxy pools, block detection, and tags.
24. Accounts: tabs, saved devices, and the state of a returning browser.

Reference pages beside this guide: profiles and MSRV.

The Rust blocks in these pages are doctests of the leyline-http crate. The Tower block in Requests compiles only with the tower feature. A plain cargo test does not enable it. The pull-request check in CI runs cargo test with --features leyline-http/full,leyline-http/bench-internals, which does. The toml, sh, and js blocks are not compiled. Blocks that open a socket are marked no_run, so they compile but do not send traffic.