# httpcloak — Full Documentation

This file is the entire httpcloak documentation site, concatenated for easy AI-agent consumption. Sections are listed in the same order as the sidebar at https://httpcloak.dev/. Source: https://github.com/sardanioss/httpcloak/tree/main/docs/docs

---



<!-- source: docs/docs/index.md -->

# httpcloak

httpcloak is a Go HTTP client that puts the same wire bytes on the line as a real browser, across HTTP/1.1, HTTP/2, and HTTP/3. The Go core handles TLS (uTLS), HTTP/2, HTTP/3 (QUIC), proxying (HTTP CONNECT, SOCKS5, MASQUE), and per-resource RFC 7540 / RFC 9218 stream priorities. Python, Node.js, and .NET get the same API through a shared cgo library.

## Quickstart



<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
	"context"
	"fmt"

	"github.com/sardanioss/httpcloak"
)

func main() {
	s := httpcloak.NewSession("chrome-latest")
	defer s.Close()

	resp, _ := s.Get(context.Background(), "https://example.com/")
	fmt.Println(resp.StatusCode)
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

with httpcloak.Session(preset="chrome-latest") as s:
    resp = s.get("https://example.com/")
    print(resp.status_code)
```

</TabItem>
<TabItem value="node" label="Node.js">

```js
const { Session } = require('httpcloak');

const s = new Session({ preset: 'chrome-latest' });
const resp = await s.get('https://example.com/');
console.log(resp.statusCode);
s.close();
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var s = new Session(preset: "chrome-latest");
var resp = await s.GetAsync("https://example.com/");
Console.WriteLine(resp.StatusCode);
```

</TabItem>
</Tabs>

## Features

### Connection lifecycle

- **`Refresh()`**: drops every live connection but keeps TLS session
  tickets, the way a browser tab does on reload. Next request resumes
  0-RTT on the same preset.
- **`RefreshWithProtocol()` / `WithSwitchProtocol`**: hop between H1, H2,
  and H3 mid-session and re-handshake on the new transport.
- **`Save()` / `LoadSession()`**: persists the session (tickets, cookies,
  preset state) to disk so you can resume across processes.
- **`Warmup(ctx, url)`**: multi-hop browser-style warmup before the real
  request. Pre-populates cookies, ECH state, and session tickets.

### Fingerprint customization

- **JSON preset describe / load**: `describe_preset(name)` dumps the full
  preset spec as JSON. `load_preset_from_json(json)` registers a mutated
  copy at runtime. Round-trips byte-for-byte.
- **Per-resource priority table**: RFC 7540 stream weights and RFC 9218
  `priority:` headers picked per request from `Sec-Fetch-Dest`. Every RFC
  7540 preset inherits a 14-dest default table, overridable per preset.
- **Custom JA3 + Akamai shorthand**: `WithCustomFingerprint` takes a JA3
  string and an Akamai HTTP/2 fingerprint string. Fine-grained override
  without writing a whole preset.
- **Cookie jar opt-out**: `WithoutCookieJar()` kills the internal jar.
  You handle cookies via per-request headers.

### Privacy and advanced TLS

- **ECH (Encrypted Client Hello)**: on by default. Encrypts SNI on the
  wire. `WithDisableECH()` skips the DNS lookup. `WithECHFrom(domain)`
  borrows an ECH config from another domain (e.g. `cloudflare-ech.com`).
- **MASQUE**: HTTP/3 CONNECT-UDP proxy support. Tunnels QUIC over a
  remote endpoint.
- **Speculative TLS for proxy CONNECT**: `WithEnableSpeculativeTLS()`
  pipelines the CONNECT request with the inner ClientHello. Saves one
  RTT on every proxied connection.
- **TLS keylog**: `WithKeyLogFile(path)` writes a Wireshark-compatible
  SSLKEYLOGFILE so you can decrypt offline.

### Network and proxy

- **Proxy types**: HTTP CONNECT, SOCKS5, SOCKS5 with UDP ASSOCIATE, and
  MASQUE. Split-config works via `WithSessionTCPProxy` +
  `WithSessionUDPProxy` (e.g. HTTP proxy for H1/H2, MASQUE for H3).
- **Source-address binding**: `WithLocalAddress(string)` and
  `WithLocalAddrIP(net.IP)` pin every dial socket to a chosen local IP.
  `IP_FREEBIND` / `IPV6_FREEBIND` gets set on Linux so addresses you
  haven't configured on the interface (routed IPv6 prefix rotation, say)
  work without `CAP_NET_ADMIN`.
- **`WithSessionPreferIPv4()`**: skips Happy Eyeballs and forces v4.

### Presets

- **Chrome**: 133, 141, 143, 144, 145, 146, 147, 148, with per-OS variants
  (Windows / Linux / macOS / Android / iOS) where they actually differ.
- **Firefox**: 133, 148.
- **Safari**: 18 (desktop), 17 / 18 (iOS).
- **`chrome-latest` aliases**: `chrome-latest`, `chrome-latest-windows`,
  `chrome-latest-linux`, `chrome-latest-macos`, `chrome-latest-android`,
  `chrome-latest-ios`. Auto-track the newest shipped Chrome major.

### Bindings

- **Go**: `go get github.com/sardanioss/httpcloak`
- **Python**: `pip install httpcloak`
- **Node.js**: `npm install httpcloak`
- **.NET**: `dotnet add package HttpCloak`

## Where to next

- New here? Start with [Getting Started](/getting-started).
- Looking up something specific? Hit the [Reference](/reference).
- Need a proxy? See [Proxies](/proxies).
- Want to dial in the fingerprint? See [Fingerprinting](/fingerprinting).
- Long-running session, Refresh, Warmup, Save/Restore? See [Connection Lifecycle](/connection-lifecycle).
- ECH, keylog, speculative TLS? See [Advanced TLS](/advanced-tls).
- End-to-end patterns for real builds? See [Recipes](/recipes).


---


<!-- source: docs/docs/installation.md -->

# Installation

Pick your binding. Once it is installed, head to [First Request](./getting-started/first-request) to send something.



<Tabs groupId="lang">
<TabItem value="go" label="Go">

```sh
go get github.com/sardanioss/httpcloak
```

Requires Go 1.22+. The Go core has no cgo dependency.

</TabItem>
<TabItem value="python" label="Python">

```sh
pip install httpcloak
```

Wheels ship for `linux-x64`, `linux-arm64`, `darwin-x64`, `darwin-arm64`, `win32-x64`. Python 3.9+.

</TabItem>
<TabItem value="node" label="Node.js">

```sh
npm install httpcloak
```

Node 18+. Optional native deps auto-resolve to your platform; ESM and CJS both supported.

</TabItem>
<TabItem value="dotnet" label=".NET">

```sh
dotnet add package HttpCloak
```

.NET 8+ on the same five platforms as Python. Uses P/Invoke to call into the shared library.

</TabItem>
</Tabs>

Next: [send your first request](./getting-started/first-request).


---


<!-- source: docs/docs/getting-started/index.md -->

# Getting Started

Fire off your first request, see how presets work, and get a feel for the day-to-day knobs you'll actually touch.

## In this section

- [First Request](./first-request): your first call with the default Chrome preset
- [Presets Explained](./presets-explained): what a preset bundles, how to pick one
- [Common Options](./common-options): timeouts, redirects, retries, the boring but essential stuff


---


<!-- source: docs/docs/getting-started/first-request.md -->

# First Request

httpcloak puts the same bytes on the wire as a real browser. Same TLS ClientHello, same HTTP/2 SETTINGS frame, same header order, same priority frames. If a site fingerprints your client, you show up looking like Chrome (or Firefox, or Safari) instead of Go's `net/http` or Python `requests`.

This page is the four-line "does it work" check. Pick your language, copy the snippet, run it. You should get a 200 back from `tls.peet.ws/api/all` with a Chrome-shaped fingerprint in the response.

## The snippet

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
	"context"
	"fmt"
	"time"

	"github.com/sardanioss/httpcloak"
)

func main() {
	sess := httpcloak.NewSession("chrome-latest",
		httpcloak.WithSessionTimeout(30*time.Second),
	)
	defer sess.Close()

	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	resp, err := sess.Get(ctx, "https://tls.peet.ws/api/all")
	if err != nil {
		panic(err)
	}
	defer resp.Close()

	fmt.Println("status:", resp.StatusCode)
	fmt.Println("protocol:", resp.Protocol)

	body, _ := resp.Text()
	fmt.Println(body)
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

with httpcloak.Session(preset="chrome-latest", timeout=30) as session:
    r = session.get("https://tls.peet.ws/api/all")
    print("status:", r.status_code)
    print("protocol:", r.http_version)
    print(r.text)
```

</TabItem>
<TabItem value="node" label="Node.js">

```javascript
const { Session } = require("httpcloak");

(async () => {
  const session = new Session({ preset: "chrome-latest", timeout: 30 });
  try {
    const r = await session.get("https://tls.peet.ws/api/all");
    console.log("status:", r.statusCode);
    console.log("protocol:", r.httpVersion);
    console.log(r.text);
  } finally {
    session.close();
  }
})();
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var session = new Session(preset: "chrome-latest", timeout: 30);
var r = session.Get("https://tls.peet.ws/api/all");
Console.WriteLine($"status: {r.StatusCode}");
Console.WriteLine($"protocol: {r.HttpVersion}");
Console.WriteLine(r.Text);
```

</TabItem>
</Tabs>

## What you should see

The full response is a chunky JSON blob with TLS, HTTP/2, and header data. Here's the trimmed version with the parts that actually matter:

```json
{
  "http_version": "h2",
  "tls": {
    "ja3_hash": "55ecc08008f90a8b2a5c5289ab0f8b69",
    "ja4": "t13d1516h2_8daaf6152771_d8a2da3f94cd"
  },
  "http2": {
    "akamai_fingerprint": "1:65536;2:0;4:6291456;6:262144|15663105|0|m,a,s,p",
    "akamai_fingerprint_hash": "52d84b11737d980aef856699f885ca86"
  },
  "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36"
}
```

A few things worth flagging:

- `http_version` is `h2`. Chrome speaks HTTP/2 by default to anything ALPN-capable, so you do too. HTTP/3 kicks in if the server advertises it via Alt-Svc. Pin one with `WithForceHTTP2()` or `WithForceHTTP3()` if you'd rather not let it negotiate.
- `ja4` is stable across runs on the same preset. `ja3_hash` isn't, because Chrome shuffles GREASE extension values on every ClientHello and that bleeds into the JA3 string. JA4 strips GREASE. Match against JA4, ignore JA3.
- `akamai_fingerprint_hash` rolls up H2 SETTINGS, WINDOW_UPDATE, PRIORITY, and pseudo-header order into one value. It should line up with what real Chrome 148 ships.

:::tip tls.peet.ws is your friend
Bookmark `tls.peet.ws/api/all`. Anytime you tweak a preset, drop in a custom JA3, or wonder why a target's still flagging you, hit this endpoint and diff the response against a real browser. DevTools won't even show you the request header order, so this is the easiest source of truth.
:::

## Where to next

- [Presets Explained](./presets-explained) for what `chrome-latest` actually bundles and how to pick something else.
- [Common Options](./common-options) for timeouts, retries, redirects, and the boring stuff every client has.
- [Fingerprinting overview](/fingerprinting) when you want to start hand-tuning the wire bytes.


---


<!-- source: docs/docs/getting-started/presets-explained.md -->

# Presets Explained

A preset is the whole bundle of wire-level fingerprint data for one specific browser build. When you write `NewSession("chrome-148-windows")`, here's what loads:

- The TLS ClientHello: cipher list, extension order, supported groups, ALPN, signature algorithms, key shares, GREASE positions, ECH config, the whole lot.
- HTTP/2 SETTINGS frame values, the WINDOW_UPDATE delta, PRIORITY frame defaults, and the pseudo-header order on every request.
- Default request headers in the exact order Chrome sends them. `sec-ch-ua`, `accept`, `sec-fetch-*`, all of it.
- Per-resource priority (RFC 7540 stream weights for H2, RFC 9218 `priority` headers for H2/H3) keyed off `sec-fetch-dest`.
- For HTTP/3: the QUIC initial parameters and the same H3 SETTINGS frame Chrome ships with.

You don't pick TLS and headers separately. You pick a browser and a build, and the whole bundle moves together. That's the only way to stay self-consistent. A Chrome 148 ClientHello with Firefox header order is going to look busted to anyone fingerprinting hard.

## How to pick one

Start with `chrome-latest`. It tracks the newest Chrome that's shipped. If you need a specific OS variant (some sites gate on `sec-ch-ua-platform`), grab `chrome-latest-windows`, `chrome-latest-linux`, `chrome-latest-macos`, `chrome-latest-android`, or `chrome-latest-ios`.

Need to pin a specific build? Say a target's blocking Chrome 148 specifically and you'd rather look like Chrome 144. Use the explicit version string: `chrome-144-windows`.

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
// Default desktop Chrome, OS picked by the latest alias map
sess := httpcloak.NewSession("chrome-latest")

// Mobile UA + matching TLS for a phone-shaped fingerprint
mobile := httpcloak.NewSession("chrome-148-android")

// Pinned to an older build
old := httpcloak.NewSession("chrome-144-windows")
```

</TabItem>
<TabItem value="python" label="Python">

```python
session = httpcloak.Session(preset="chrome-latest")
mobile  = httpcloak.Session(preset="chrome-148-android")
old     = httpcloak.Session(preset="chrome-144-windows")
```

</TabItem>
<TabItem value="node" label="Node.js">

```javascript
const session = new Session({ preset: "chrome-latest" });
const mobile  = new Session({ preset: "chrome-148-android" });
const old     = new Session({ preset: "chrome-144-windows" });
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using var session = new Session(preset: "chrome-latest");
using var mobile  = new Session(preset: "chrome-148-android");
using var old     = new Session(preset: "chrome-144-windows");
```

</TabItem>
</Tabs>

## What's available

Every preset family ships per-OS variants wherever the underlying browser actually differs by OS. Chrome differs across Windows, Linux, macOS, Android, and iOS (iOS Chrome is WebKit under the hood, totally different stack). Firefox barely differs across desktop OSes, so there's one desktop build.

**Chrome desktop**: 133, 141, 143, 144, 145, 146, 147, 148. Each has `-windows`, `-linux`, `-macos` suffixes (so `chrome-148-windows` and friends). Bare `chrome-148` aliases to whatever OS the library defaults to.

**Chrome mobile**: `chrome-143-android` through `chrome-148-android`, and `chrome-143-ios` through `chrome-148-ios`. Mobile Chrome has its own UA, its own sec-ch-ua values, and on iOS a completely different TLS stack (WebKit again).

**Firefox**: 133 and 148 desktop. No per-OS split.

**Safari**: `safari-18` desktop, `safari-17-ios`, `safari-18-ios`.

**Latest aliases**: `chrome-latest`, `chrome-latest-windows`, `chrome-latest-linux`, `chrome-latest-macos`, `chrome-latest-android`, `chrome-latest-ios`, `firefox-latest`, `safari-latest`, `safari-latest-ios`. These re-point to the newest shipped major on every release. Use them when you don't care about pinning to an exact build.

For the full list with protocol support per preset, see [Reference: Presets](/reference/presets).

## Inheritance: the `based_on` chain

Presets aren't standalone JSON blobs. They form a chain. Crack open `fingerprint/embedded/chrome-148-windows.json` and you'll see something like this:

```json
{
  "version": 1,
  "preset": {
    "name": "chrome-148-windows",
    "based_on": "chrome-147-windows",
    "headers": {
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36",
      "values": {
        "sec-ch-ua": "\"Chromium\";v=\"148\", \"Google Chrome\";v=\"148\", \"Not/A)Brand\";v=\"99\""
      }
    }
  }
}
```

That's the whole file. Chrome 148 windows is just "Chrome 147 windows but bump the UA and sec-ch-ua to 148". TLS settings, H2 settings, header order, priority table, all inherited verbatim.

It's deliberate. Real Chrome rarely changes its TLS or H2 wire format between minor versions. Most of what's "new in Chrome 148" is JS engine and rendering, not network. So a delta only ships when the wire actually changes (cipher reordering, new extension, SETTINGS bump, that kind of thing). Everything else is a UA bump on top of the `based_on` chain.

The chain bottoms out at a "root" preset that carries the full TLS/H2 spec. Loading `chrome-148-windows` walks the chain at startup and merges layer by layer.

Want to see the resolved bundle (post-merge)? There's a describe API. From Go: `fingerprint.Describe("chrome-148-windows")`. From Python: `httpcloak.describe_preset("chrome-148-windows")`.

## Building your own

Drop a JSON file in your app, point httpcloak at it, and you've got a custom preset. Handy when you've captured a real browser session and want to ship that exact fingerprint without hand-editing Go code.

Shape is the same as the embedded files. `based_on` is optional: point it at any registered preset to inherit, or omit it and supply the full TLS+H2 spec yourself.

See [JSON Preset Builder](/fingerprinting/json-preset-builder) for the full schema and a worked example.

## Where to next

- [Reference: Presets](/reference/presets) for the full table of what each preset supports (H1/H2/H3, OS, mobile/desktop).
- [What is TLS Fingerprinting](/fingerprinting/what-is-tls-fingerprinting) for context on why these wire bytes matter.
- [Custom JA3](/fingerprinting/custom-ja3) when you want to override individual TLS bits without rebuilding a whole preset.


---


<!-- source: docs/docs/getting-started/common-options.md -->

# Common Options

Every HTTP client has the same handful of knobs. Timeouts, redirects, retries, default headers, cookies. This page covers those for httpcloak. Nothing fancy, just the everyday stuff you'll reach for in week one.

For the full option surface, including everything that's not on this page, see [Reference: Options](/reference/options).

## Timeout

`WithSessionTimeout` is the default timeout for every request on the session. You can override it per-request via the `Timeout` field on `Request` (or the `timeout` kwarg on the bindings).

The session timeout covers the whole request: DNS, connect, TLS handshake, request send, response read. It doesn't cover reading the body once `Get`/`Do` has returned. You handle that yourself.

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
sess := httpcloak.NewSession("chrome-latest",
	httpcloak.WithSessionTimeout(10*time.Second),
)
```

</TabItem>
<TabItem value="python" label="Python">

```python
session = httpcloak.Session(preset="chrome-latest", timeout=10)
```

</TabItem>
<TabItem value="node" label="Node.js">

```javascript
const session = new Session({ preset: "chrome-latest", timeout: 10 });
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using var session = new Session(preset: "chrome-latest", timeout: 10);
```

</TabItem>
</Tabs>

In Go, the timeout is also bounded by the `context.Context` you pass to `Get`/`Do`. Whichever fires first wins. Use the context for caller cancellation, the session timeout as a backstop.

## Redirects

httpcloak follows redirects by default, up to 10 hops. You can kill that entirely, or just change the cap.

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
// Don't follow at all
noRedir := httpcloak.NewSession("chrome-latest", httpcloak.WithoutRedirects())

// Follow but cap at 5
capped := httpcloak.NewSession("chrome-latest", httpcloak.WithRedirects(true, 5))
```

</TabItem>
<TabItem value="python" label="Python">

```python
no_redir = httpcloak.Session(preset="chrome-latest", allow_redirects=False)
capped   = httpcloak.Session(preset="chrome-latest", max_redirects=5)
```

</TabItem>
<TabItem value="node" label="Node.js">

```javascript
const noRedir = new Session({ preset: "chrome-latest", allowRedirects: false });
const capped  = new Session({ preset: "chrome-latest", maxRedirects: 5 });
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using var noRedir = new Session(preset: "chrome-latest", allowRedirects: false);
using var capped  = new Session(preset: "chrome-latest", maxRedirects: 5);
```

</TabItem>
</Tabs>

When redirects are followed, the response object hands you the full chain via `response.History` (Go), `r.history` (Python), `r.history` (Node), `Response.History` (.NET). Each entry has the status, URL, and headers of the intermediate hop. The final URL lands on `FinalURL` / `final_url` / `finalUrl` / `FinalUrl`.

When redirects are off, a 301/302 (or whatever) just comes back as the response, body and all. No magic.

## Retries

Retries are off by default. Flip them on with `WithRetry(n)` for sane defaults, or reach for `WithRetryConfig` to tune the backoff window and the trigger status codes. Default retry-on-status when you enable retries is `[429, 500, 502, 503, 504]`.

Heads up: retries on POST/PUT/PATCH bodies need the body to be re-readable. Pass a `bytes.Buffer` or a `[]byte`-backed reader, not a one-shot stream, otherwise the retry has nothing to send.

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
// 3 retries with default 500ms-10s exponential backoff on default statuses
sess := httpcloak.NewSession("chrome-latest", httpcloak.WithRetry(3))

// Custom: 5 retries, 1s-30s backoff, only 429 and 503
tuned := httpcloak.NewSession("chrome-latest",
	httpcloak.WithRetryConfig(5, 1*time.Second, 30*time.Second, []int{429, 503}),
)
```

</TabItem>
<TabItem value="python" label="Python">

```python
session = httpcloak.Session(preset="chrome-latest", retry=3)

tuned = httpcloak.Session(
    preset="chrome-latest",
    retry=5,
    retry_wait_min=1000,   # ms
    retry_wait_max=30000,  # ms
    retry_on_status=[429, 503],
)
```

</TabItem>
<TabItem value="node" label="Node.js">

```javascript
const session = new Session({ preset: "chrome-latest", retry: 3 });

const tuned = new Session({
  preset: "chrome-latest",
  retry: 5,
  retryWaitMin: 1000,
  retryWaitMax: 30000,
  retryOnStatus: [429, 503],
});
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using var session = new Session(preset: "chrome-latest", retry: 3);

using var tuned = new Session(
    preset: "chrome-latest",
    retry: 5,
    retryWaitMin: 1000,
    retryWaitMax: 30000,
    retryOnStatus: new[] { 429, 503 });
```

</TabItem>
</Tabs>

## Custom headers

Presets ship with a default header set in the right order. You don't want to touch this most of the time, the whole point is to look like Chrome. But you'll usually need to tack on an `Authorization`, `Cookie`, `Referer`, or some app-specific header.

Just add them per-request. They get merged into the preset's order at the correct slot (httpcloak knows where Chrome puts `authorization` vs `accept` and so on).

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
resp, err := sess.Do(ctx, &httpcloak.Request{
	Method: "GET",
	URL:    "https://httpbin.org/headers",
	Headers: map[string][]string{
		"Authorization": {"Bearer abc123"},
		"X-Request-Id":  {"42"},
	},
})
```

</TabItem>
<TabItem value="python" label="Python">

```python
r = session.get(
    "https://httpbin.org/headers",
    headers={"Authorization": "Bearer abc123", "X-Request-Id": "42"},
)
```

</TabItem>
<TabItem value="node" label="Node.js">

```javascript
const r = await session.get("https://httpbin.org/headers", {
  headers: { Authorization: "Bearer abc123", "X-Request-Id": "42" },
});
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
var r = session.Get("https://httpbin.org/headers", headers: new() {
    ["Authorization"] = "Bearer abc123",
    ["X-Request-Id"]  = "42",
});
```

</TabItem>
</Tabs>

Need to override the preset's header order entirely? That's a separate concern (`SetHeaderOrder` on the session, see [Reference: Options](/reference/options)).

## Cookies

The session has a built-in cookie jar. It captures `Set-Cookie` from every response and replays the right cookies on subsequent requests, scoped to domain and path the way browsers do.

It just works out of the box. No opt-in needed. If you want to inspect or seed the jar, see [Cookies and State](/cookies-and-state).

If your app already manages cookies somewhere else (shared store across many sessions, or you're proxying for another tool that owns the jar), turn the internal jar off:

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
sess := httpcloak.NewSession("chrome-latest", httpcloak.WithoutCookieJar())
```

</TabItem>
<TabItem value="python" label="Python">

```python
session = httpcloak.Session(preset="chrome-latest", without_cookie_jar=True)
```

</TabItem>
<TabItem value="node" label="Node.js">

```javascript
const session = new Session({ preset: "chrome-latest", withoutCookieJar: true });
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using var session = new Session(preset: "chrome-latest", withoutCookieJar: true);
```

</TabItem>
</Tabs>

With the jar off, `Set-Cookie` values from responses aren't stored, and nothing gets auto-injected on later requests. You handle the `Cookie` header yourself per-request. See [Disabling the Cookie Jar](/cookies-and-state/disabling-cookie-jar) for the full pattern.

## Local source address

Got an IPv6 prefix routed to your host (cheap rotating egress) or multiple IPv4 addresses on one box? You can pin a session to a specific source IP. Linux freebind kicks in automatically so you don't have to configure each address on the interface, which is a low-key huge time saver.

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
sess := httpcloak.NewSession("chrome-latest",
	httpcloak.WithLocalAddress("2001:db8::1234"),
)
```

</TabItem>
<TabItem value="python" label="Python">

```python
session = httpcloak.Session(preset="chrome-latest", local_address="2001:db8::1234")
```

</TabItem>
<TabItem value="node" label="Node.js">

```javascript
const session = new Session({ preset: "chrome-latest", localAddress: "2001:db8::1234" });
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using var session = new Session(preset: "chrome-latest", localAddress: "2001:db8::1234");
```

</TabItem>
</Tabs>

Works for IPv4 too. For rotation patterns and freebind details, see [Source Address Binding](/proxies/source-address-binding).

## What's not on this page

- Proxies (HTTP CONNECT, SOCKS5, MASQUE, split TCP/UDP): see [Proxies](/proxies).
- Fingerprint customization (custom JA3, Akamai shorthand, JSON presets): see [Fingerprinting](/fingerprinting).
- Advanced TLS knobs (ECH, key logging, session resumption): see [Advanced TLS](/advanced-tls).
- Streaming uploads/downloads, multipart, redirect history details: see [Requests and Responses](/requests-and-responses).

:::info Full option list
What's here is the everyday set. For everything else (`WithForceHTTP3`, `WithKeyLogFile`, `WithECHFrom`, `WithCustomFingerprint`, `WithSessionCache`, and friends), see [Reference: Options](/reference/options).
:::


---


<!-- source: docs/docs/proxies/index.md -->

# Proxies

httpcloak speaks HTTP CONNECT, SOCKS5, SOCKS5 with UDP, and MASQUE. Pick whichever one your upstream actually offers and your protocol mix needs.

## In this section

- [Overview](./overview): when to pick what, what each protocol carries, what it solves.
- [HTTP CONNECT](./http-connect): the classic. Plain HTTPS tunneling.
- [SOCKS5](./socks5): the residential-provider workhorse, with auth.
- [SOCKS5 UDP](./socks5-udp): UDP ASSOCIATE for pushing HTTP/3 through SOCKS5.
- [MASQUE](./masque): HTTP/3 CONNECT-UDP. QUIC inside QUIC.
- [Source Address Binding](./source-address-binding): pin every dial to a local IP you pick.


---


<!-- source: docs/docs/proxies/overview.md -->

# Overview

Four proxy protocols. Pick the one that matches your upstream and the kind of traffic you're routing.

## What we support

| Type | URL scheme | Carries | Auth | Best for |
|---|---|---|---|---|
| HTTP CONNECT | `http://`, `https://` | TCP (HTTP/1.1, HTTP/2) | Basic | The classic. Datacenter proxies, corporate egress, anything fronting as a normal HTTP proxy. |
| SOCKS5 | `socks5://`, `socks5h://` | TCP (HTTP/1.1, HTTP/2) | none, user/pass | Residential providers default to this. BrightData, Smartproxy, Oxylabs, SOAX. |
| SOCKS5 with UDP ASSOCIATE | `socks5://` (UDP slot) | UDP (HTTP/3 over QUIC) | none, user/pass | Routing H3 through a SOCKS5 server that supports UDP relay. Less common, not every provider does it. |
| MASQUE (CONNECT-UDP) | `masque://`, `https://` | UDP inside HTTP/3 | Basic | The new kid. Tunnels QUIC inside QUIC. Cloudflare WARP and a few residential providers ship this for H3. |

If you've never thought about which to grab: HTTP CONNECT for HTTP/1.1 and HTTP/2, SOCKS5 if your residential provider handed you a SOCKS5 endpoint, and add a UDP proxy (SOCKS5 UDP or MASQUE) only when you actually want HTTP/3 to ride through the proxy too.

## Split-config: TCP and UDP separately

You can configure the TCP proxy and the UDP proxy independently. Two options on the same session:

- `WithSessionTCPProxy(url)` sends HTTP/1.1 and HTTP/2 through this proxy.
- `WithSessionUDPProxy(url)` sends HTTP/3 (QUIC) through this proxy.

You'd want this when your TCP proxy can't do UDP. Common shapes:

```go
// HTTP CONNECT for H1/H2 + MASQUE for H3
s := httpcloak.NewSession("chrome-latest",
    httpcloak.WithSessionTCPProxy("http://user:pass@proxy.example.com:8080"),
    httpcloak.WithSessionUDPProxy("masque://user:pass@proxy.example.com:443"),
)

// SOCKS5 for everything (only works if SOCKS5 server supports UDP ASSOCIATE)
s := httpcloak.NewSession("chrome-latest",
    httpcloak.WithSessionTCPProxy("socks5://user:pass@proxy.example.com:1080"),
    httpcloak.WithSessionUDPProxy("socks5://user:pass@proxy.example.com:1080"),
)

// HTTP CONNECT only, kill H3 because no UDP route
s := httpcloak.NewSession("chrome-latest",
    httpcloak.WithSessionTCPProxy("http://user:pass@proxy.example.com:8080"),
    httpcloak.WithDisableHTTP3(),
)
```

Set only `WithSessionTCPProxy` and skip the UDP slot? H3 will dial direct. Most of the time that's fine. If your network blocks outbound UDP/443, pair it with `WithDisableHTTP3()` so the session sticks to H1/H2.

There's also `WithSessionProxy(url)`, the old single-proxy option. It still works and applies the URL to both slots based on scheme. New code should prefer the split form, it's just clearer about what's going where.

## Auth

Auth lives in the URL. All three forms work:

- `http://user:pass@host:port`
- `socks5://user:pass@host:port`
- `masque://user:pass@host:port`

For HTTP CONNECT and MASQUE, this becomes a `Proxy-Authorization: Basic <base64>` header. For SOCKS5 it goes through RFC 1929 username/password sub-negotiation. URL-encode the password if it has special chars, that's standard URL parsing.

## Source-address binding

Independent of any proxy choice, you can pin every dial to a specific local IP. Use `WithLocalAddress("203.0.113.10")` or `WithLocalAddrIP(net.IP)` and httpcloak binds every outgoing socket (direct or through a proxy) to that address. On Linux it sets `IP_FREEBIND` so addresses from a routed prefix that aren't on any interface still work without `CAP_NET_ADMIN`.

See [Source Address Binding](./source-address-binding) for the full shape, IPv6 prefix rotation tricks, and platform notes.

## Picking the right one

A rough decision tree:

- Datacenter or corporate proxy gave you a host:port and HTTP basic auth: HTTP CONNECT.
- Residential provider gave you a SOCKS5 endpoint: [SOCKS5](./socks5).
- Same residential provider, you want H3 to also go through the proxy and they advertise UDP support: [SOCKS5 UDP](./socks5-udp).
- You want H3 traffic specifically tunneled through Cloudflare WARP or a custom MASQUE server: [MASQUE](./masque).
- You want a single source IP no matter the proxy choice: [Source Address Binding](./source-address-binding).

## Bindings

Same options exist in Python (`tcp_proxy=`, `udp_proxy=`, `local_address=`), Node.js (`tcpProxy`, `udpProxy`, `localAddress`), and .NET (`tcpProxy:`, `udpProxy:`, `localAddress:`). The chapters that follow show 4-language tabs wherever the API differs.


---


<!-- source: docs/docs/proxies/http-connect.md -->

# HTTP CONNECT

The OG HTTP proxy. Your client opens TCP to the proxy, sends `CONNECT host:port HTTP/1.1`, the proxy comes back with `200 Connection established`, and from there the socket is just a raw tunnel. Your real TLS handshake then runs through that tunnel like the proxy isn't even there.

This is what HTTPS-through-an-HTTP-proxy actually looks like on the wire. Squid, mitmproxy in upstream mode, every datacenter proxy provider, almost every corporate egress proxy: all HTTP CONNECT.

## URL shape

```
http://user:pass@proxy.example.com:8080
https://user:pass@proxy.example.com:8443
```

Use `https://` when the connection from your client to the proxy itself should be TLS. It's not super common, but some providers offer it. The inner request is always TLS regardless, because that's the target site's TLS, decrypted only at the target.

## Setting it up



<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "context"
    "fmt"

    "github.com/sardanioss/httpcloak"
)

func main() {
    s := httpcloak.NewSession("chrome-latest",
        httpcloak.WithSessionTCPProxy("http://user:pass@proxy.example.com:8080"),
    )
    defer s.Close()

    resp, err := s.Get(context.Background(), "https://httpbin.org/ip")
    if err != nil {
        panic(err)
    }
    fmt.Println(resp.StatusCode, string(resp.Body))
    // {"origin": "<the proxy's egress IP>"}
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

with httpcloak.Session(
    preset="chrome-latest",
    tcp_proxy="http://user:pass@proxy.example.com:8080",
) as s:
    r = s.get("https://httpbin.org/ip")
    print(r.status_code, r.text)
    # {"origin": "<the proxy's egress IP>"}
```

</TabItem>
<TabItem value="node" label="Node.js">

```js
const { Session } = require('httpcloak');

const s = new Session({
  preset: 'chrome-latest',
  tcpProxy: 'http://user:pass@proxy.example.com:8080',
});

const r = await s.get('https://httpbin.org/ip');
console.log(r.statusCode, r.body);
s.close();
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var s = new Session(
    preset: "chrome-latest",
    tcpProxy: "http://user:pass@proxy.example.com:8080");

var r = await s.GetAsync("https://httpbin.org/ip");
Console.WriteLine($"{r.StatusCode} {r.Body}");
```

</TabItem>
</Tabs>

## What's on the wire

A normal request through an HTTP CONNECT proxy goes:

1. TCP open to `proxy.example.com:8080`.
2. Client sends `CONNECT httpbin.org:443 HTTP/1.1` plus `Proxy-Authorization: Basic <base64(user:pass)>` and a host header.
3. Proxy replies `HTTP/1.1 200 Connection established`.
4. Client sends the TLS ClientHello on the same socket. From here the proxy is just forwarding bytes.
5. TLS handshake completes against `httpbin.org`. Client sends `GET /ip`.

That's two round-trips before TLS even starts (TCP handshake, then CONNECT exchange), then one or two more for TLS depending on resumption.

## Saving an RTT with speculative TLS

httpcloak can pipeline the CONNECT request with the inner ClientHello. Same socket, both writes coalesced before any read. Saves one full round-trip on every fresh proxied connection.

```go
s := httpcloak.NewSession("chrome-latest",
    httpcloak.WithSessionTCPProxy("http://user:pass@proxy.example.com:8080"),
    httpcloak.WithEnableSpeculativeTLS(),
)
```

It's off by default because some proxies (older Squid configs, a handful of debugging tools) freak out when bytes show up before the 200 is fully read. Test it on your provider first. Full details and trade-offs in [Speculative TLS](/advanced-tls/speculative-tls).

## H3 with an HTTP CONNECT TCP proxy

HTTP CONNECT only carries TCP. If you set just `WithSessionTCPProxy` with an HTTP URL, H3 will dial direct to the target (no proxy on UDP). Three options:

- Let H3 dial direct (the default). Fine on most networks.
- Add a UDP proxy: `WithSessionUDPProxy("masque://...")` or a SOCKS5 endpoint that supports UDP ASSOCIATE.
- Disable H3: `WithDisableHTTP3()` so the session sticks to H1/H2 and everything goes through the HTTP CONNECT proxy.

## Auth

Basic auth is handled for you when the credentials are in the URL. httpcloak base64-encodes `user:pass` and adds `Proxy-Authorization: Basic ...` to the CONNECT request. Password has special characters? URL-encode them:

```
http://user:p%40ss%21@proxy.example.com:8080
```

(That's `p@ss!`.)

## Common errors

- `407 Proxy Authentication Required`: credentials missing or wrong. Check the URL has `user:pass@`.
- `403 Forbidden`: proxy reached you but rejected the target. Some providers block specific destinations. Try a different target to confirm.
- `502 Bad Gateway`: proxy couldn't reach the target. Often the proxy's upstream having a bad day.
- `failed to resolve proxy host ...`: your DNS can't resolve the proxy hostname itself. Most often a typo.

## Provider quirks

Some HTTP CONNECT providers are picky about the order or presence of headers in the CONNECT request. httpcloak sends a minimal CONNECT (method line, Host header, optional Proxy-Authorization). If a provider needs a specific User-Agent or extra header on the CONNECT line itself, that's not currently configurable. File an issue with the provider name if you hit this.


---


<!-- source: docs/docs/proxies/socks5.md -->

# SOCKS5

SOCKS5 is the residential-proxy workhorse. The client connects to the SOCKS5 server, runs a short version + auth handshake, asks the server to CONNECT to the target host, and from there the socket is a TCP tunnel. httpcloak runs its real TLS handshake through that tunnel.

It's basically the SOCKS5 cousin of HTTP CONNECT, just with a binary handshake and an auth scheme that does username/password as a proper sub-protocol.

:::info
SOCKS5 is the residential workhorse. Most providers (BrightData, Smartproxy, Oxylabs, SOAX, IPRoyal etc) ship SOCKS5 endpoints by default. If you bought "rotating residential proxies" from someone in the last few years, what they handed you was almost certainly SOCKS5.
:::

## URL shapes

```
socks5://proxy.example.com:1080
socks5://user:pass@proxy.example.com:1080
socks5h://proxy.example.com:1080
```

`socks5` and `socks5h` both work. httpcloak always sends hostname targets to the proxy as a SOCKS5 domain ATYP (address type 3), which means DNS resolution of the *target* happens at the proxy. The *proxy's own hostname* is always resolved client-side, that part you can't avoid.

If your URL has an IP literal as the target host (rare, you'd build that yourself), httpcloak sends an IPv4 or IPv6 ATYP instead.

## Setting it up



<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "context"
    "fmt"

    "github.com/sardanioss/httpcloak"
)

func main() {
    s := httpcloak.NewSession("chrome-latest",
        httpcloak.WithSessionTCPProxy("socks5://user:pass@proxy.example.com:1080"),
    )
    defer s.Close()

    resp, err := s.Get(context.Background(), "https://httpbin.org/ip")
    if err != nil {
        panic(err)
    }
    fmt.Println(resp.StatusCode, string(resp.Body))
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

with httpcloak.Session(
    preset="chrome-latest",
    tcp_proxy="socks5://user:pass@proxy.example.com:1080",
) as s:
    r = s.get("https://httpbin.org/ip")
    print(r.status_code, r.text)
```

</TabItem>
<TabItem value="node" label="Node.js">

```js
const { Session } = require('httpcloak');

const s = new Session({
  preset: 'chrome-latest',
  tcpProxy: 'socks5://user:pass@proxy.example.com:1080',
});

const r = await s.get('https://httpbin.org/ip');
console.log(r.statusCode, r.body);
s.close();
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var s = new Session(
    preset: "chrome-latest",
    tcpProxy: "socks5://user:pass@proxy.example.com:1080");

var r = await s.GetAsync("https://httpbin.org/ip");
Console.WriteLine($"{r.StatusCode} {r.Body}");
```

</TabItem>
</Tabs>

## Auth schemes

httpcloak negotiates the auth method based on what's in the URL.

- No `user:pass` in the URL: client offers `0x00` (NO AUTHENTICATION REQUIRED) only. If the proxy demands auth it'll fail the handshake.
- `user:pass` in the URL: client offers both no-auth and `0x02` (USERNAME/PASSWORD, RFC 1929). Server picks one. If it picks username/password, httpcloak runs the sub-negotiation.

So an authenticated URL works fine against an open proxy too, the server just picks no-auth and the credentials sit unused. URL-encode special characters in the password the same way you'd do it for HTTP CONNECT:

```
socks5://user:p%40ss%21@proxy.example.com:1080
```

GSSAPI (auth method `0x01`) isn't supported. If your provider needs it, raise an issue.

## SOCKS5 vs SOCKS5h

`socks5h://` is a curl-ism that means "delegate DNS to the proxy". httpcloak treats both schemes identically because it always sends hostname targets as a SOCKS5 domain ATYP, which is exactly the "DNS-at-proxy" behavior. The scheme suffix is accepted but doesn't change anything you'd notice on the wire.

If you really want to force client-side DNS for the target, you'd resolve the hostname yourself before building the URL. Usually not what you want with residential providers, since the proxy's DNS view is part of why you're using it.

## H3 through SOCKS5

A vanilla `WithSessionTCPProxy("socks5://...")` only routes TCP. H3 (QUIC over UDP) will dial direct to the target. If you want H3 through the SOCKS5 server too, the server needs to support UDP ASSOCIATE and you have to wire a UDP proxy. See [SOCKS5 UDP](./socks5-udp).

## Common errors

- `SOCKS5 handshake failed: failed to read auth response`: usually the proxy closed the socket. Check the URL host/port and credentials.
- `proxy rejected all authentication methods`: server didn't accept no-auth or user/pass. You probably need to add credentials.
- `authentication failed: invalid credentials`: self-explanatory, typo or bad creds.
- `CONNECT failed: connection refused (reply=5)`: target host or port refused the connection. Try a different target.
- `CONNECT failed: host unreachable (reply=4)`: target DNS resolved at the proxy to something unroutable, or the proxy can't reach it.

The `reply=N` codes follow RFC 1928 section 6, useful when grepping provider docs.

## Source-IP binding combined with SOCKS5

`WithLocalAddress` works with SOCKS5 too. The local address binds the socket from your machine to the SOCKS5 server. The proxy still picks its own egress IP for the upstream side, you don't get to influence that from the client. Use this when your machine has multiple public IPs and you want to route the SOCKS5 control connection out a specific one.


---


<!-- source: docs/docs/proxies/socks5-udp.md -->

# SOCKS5 UDP

SOCKS5 has a `UDP ASSOCIATE` command (RFC 1928 section 4) that lets the client send and receive UDP datagrams through the proxy. httpcloak uses this to push HTTP/3 (QUIC over UDP) through a SOCKS5 server.

The flow is two-part:

1. A TCP control connection to the SOCKS5 server, doing the normal greeting + auth, then sending a UDP ASSOCIATE request.
2. The proxy replies with a relay address (a UDP host:port). The client opens a local UDP socket and sends every datagram to that relay address, wrapped in a small SOCKS5 UDP header carrying the real target. Replies come back the same way.

QUIC packets get wrapped, sent through the relay, unwrapped on the proxy, forwarded to the target, replies wrapped on the way back. To QUIC it just looks like a regular UDP socket.

## Wiring it up

You need both a TCP proxy (for the H1/H2 path) and a UDP proxy (for the H3 path) on the same SOCKS5 endpoint. Set both:



<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "context"
    "fmt"

    "github.com/sardanioss/httpcloak"
)

func main() {
    proxyURL := "socks5://user:pass@proxy.example.com:1080"

    s := httpcloak.NewSession("chrome-latest",
        httpcloak.WithSessionTCPProxy(proxyURL),
        httpcloak.WithSessionUDPProxy(proxyURL),
        httpcloak.WithForceHTTP3(),
    )
    defer s.Close()

    resp, err := s.Get(context.Background(), "https://httpbin.org/ip")
    if err != nil {
        panic(err)
    }
    fmt.Println(resp.StatusCode, string(resp.Body))
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

proxy = "socks5://user:pass@proxy.example.com:1080"

with httpcloak.Session(
    preset="chrome-latest",
    tcp_proxy=proxy,
    udp_proxy=proxy,
    http_version="h3",
) as s:
    r = s.get("https://httpbin.org/ip")
    print(r.status_code, r.text)
```

</TabItem>
<TabItem value="node" label="Node.js">

```js
const { Session } = require('httpcloak');

const proxy = 'socks5://user:pass@proxy.example.com:1080';

const s = new Session({
  preset: 'chrome-latest',
  tcpProxy: proxy,
  udpProxy: proxy,
  httpVersion: 'h3',
});

const r = await s.get('https://httpbin.org/ip');
console.log(r.statusCode, r.body);
s.close();
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

const string proxy = "socks5://user:pass@proxy.example.com:1080";

using var s = new Session(
    preset: "chrome-latest",
    tcpProxy: proxy,
    udpProxy: proxy,
    httpVersion: "h3");

var r = await s.GetAsync("https://httpbin.org/ip");
Console.WriteLine($"{r.StatusCode} {r.Body}");
```

</TabItem>
</Tabs>

You can also mix: HTTP CONNECT for TCP, SOCKS5 UDP ASSOCIATE for the UDP slot. That's a legal combo as long as both proxies actually exist and reach the same target.

:::warning UDP ASSOCIATE is not universal
Not every SOCKS5 server supports `UDP_ASSOCIATE`. The RFC says servers MAY support it, not MUST. Plenty of residential providers don't, and on a load-balanced endpoint you might land on a server that doesn't even when others on the same hostname do.

If a server doesn't speak UDP, it replies with `reply=7` (Command not supported) or `reply=1` (general SOCKS server failure). httpcloak retries up to 5 times on `reply=1` because that's the typical load-balancer-hits-a-bad-server symptom. After that it gives up.

Test before trusting it for H3 routing. Simplest test: configure `udp_proxy`, force H3 against `https://httpbin.org/ip`. If it errors with "UDP ASSOCIATE failed" you don't have UDP support.
:::

## What the SOCKS5 UDP header looks like

Every datagram sent to the relay is prefixed with:

```
+----+------+------+----------+----------+----------+
|RSV | FRAG | ATYP | DST.ADDR | DST.PORT |   DATA   |
+----+------+------+----------+----------+----------+
| 2  |  1   |  1   | Variable |    2     | Variable |
+----+------+------+----------+----------+----------+
```

`FRAG` is always 0. httpcloak doesn't fragment, and it refuses to read fragmented datagrams from the proxy because reassembly is messy and basically never happens in practice. The address is the *target* host:port. ATYP follows the same enum as the TCP path: 1 IPv4, 3 domain, 4 IPv6.

## Keepalive on the control channel

Per RFC 1928, when the TCP control connection closes, the UDP relay goes away with it. httpcloak enables TCP keepalive on the control connection (15s period) and runs a goroutine that reads from the control socket so dropped connections get noticed quickly.

For long-lived QUIC connections this matters. If you start an H3 request and the SOCKS5 control channel dies 30 seconds in, your QUIC connection silently stops getting packets through. That's the kind of hang you'd debug for an hour before realizing the control socket dropped.

## Common errors

- `UDP ASSOCIATE failed: command not supported`: server doesn't speak UDP relay. Pick a different provider or a different server.
- `UDP ASSOCIATE failed: general SOCKS server failure`: usually means you hit a load-balanced backend that doesn't do UDP. httpcloak retries up to 5 times before giving up.
- `fragmented packets not supported (frag=N)`: a proxy is sending fragmented datagrams, which is rare and usually a misconfiguration.
- QUIC handshake timeout after UDP ASSOCIATE succeeds: the relay exists but isn't actually forwarding packets. Some proxies advertise UDP and then silently drop everything. Annoying but real. Try a different endpoint.

## When MASQUE is the better answer

If your provider also offers a MASQUE endpoint, that's usually a smoother way to tunnel H3. SOCKS5 UDP works but the ecosystem is patchy and the per-datagram header overhead is real. See [MASQUE](./masque) for the H3-native alternative.


---


<!-- source: docs/docs/proxies/masque.md -->

# MASQUE

MASQUE is the new kid: HTTP/3's answer to "I want to tunnel UDP through a proxy". The client opens an HTTP/3 connection to the proxy, sends an Extended CONNECT request with `:protocol = connect-udp` against the well-known path, and on success uses HTTP/3 Datagrams (RFC 9297) to push UDP payload bytes back and forth.

In practice for httpcloak, the inner UDP payload is QUIC packets aimed at the real target. So you get QUIC inside QUIC. The outer QUIC encrypts your tunnel to the proxy, the inner QUIC encrypts your traffic to the target.

The relevant RFCs:

- RFC 9298: CONNECT-UDP (the method, the well-known path, the framing)
- RFC 9297: HTTP/3 Datagrams (the carrier for inner UDP)
- RFC 9484: the MASQUE WG output document tying it together

## URL shapes

```
masque://proxy.example.com:443
masque://user:pass@proxy.example.com:443
https://user:pass@proxy.example.com:443    # auto-detected for known providers
```

`masque://` is just a scheme hint. Internally it gets normalized to `https://` because the proxy connection is plain HTTPS-over-H3. If the hostname matches a known MASQUE provider (BrightData, Oxylabs, Smartproxy, SOAX), `https://` is auto-detected as MASQUE. For any other provider use `masque://` explicitly so httpcloak doesn't try to treat the URL as a regular HTTPS proxy.

Default port is 443. The proxy must speak HTTP/3 with Extended CONNECT and HTTP/3 Datagrams enabled.

## Setting it up



<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "context"
    "fmt"

    "github.com/sardanioss/httpcloak"
)

func main() {
    s := httpcloak.NewSession("chrome-latest",
        httpcloak.WithSessionUDPProxy("masque://user:pass@proxy.example.com:443"),
        httpcloak.WithForceHTTP3(),
    )
    defer s.Close()

    resp, err := s.Get(context.Background(), "https://httpbin.org/ip")
    if err != nil {
        panic(err)
    }
    fmt.Println(resp.StatusCode, string(resp.Body))
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

with httpcloak.Session(
    preset="chrome-latest",
    udp_proxy="masque://user:pass@proxy.example.com:443",
    http_version="h3",
) as s:
    r = s.get("https://httpbin.org/ip")
    print(r.status_code, r.text)
```

</TabItem>
<TabItem value="node" label="Node.js">

```js
const { Session } = require('httpcloak');

const s = new Session({
  preset: 'chrome-latest',
  udpProxy: 'masque://user:pass@proxy.example.com:443',
  httpVersion: 'h3',
});

const r = await s.get('https://httpbin.org/ip');
console.log(r.statusCode, r.body);
s.close();
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var s = new Session(
    preset: "chrome-latest",
    udpProxy: "masque://user:pass@proxy.example.com:443",
    httpVersion: "h3");

var r = await s.GetAsync("https://httpbin.org/ip");
Console.WriteLine($"{r.StatusCode} {r.Body}");
```

</TabItem>
</Tabs>

If you also need H1/H2 to go through a proxy, pair `udp_proxy` with `tcp_proxy`. The common shape: HTTP CONNECT for TCP, MASQUE for UDP.

## What's on the wire

1. UDP socket open, QUIC handshake to `proxy.example.com:443`. ALPN is `h3`, datagram support negotiated, Extended CONNECT confirmed via `SETTINGS_ENABLE_CONNECT_PROTOCOL`.
2. Client opens an HTTP/3 request stream and sends:
   ```
   :method = CONNECT
   :protocol = connect-udp
   :scheme = https
   :authority = proxy.example.com:443
   :path = /.well-known/masque/udp/<target_host>/<target_port>/
   capsule-protocol = ?1
   proxy-authorization = Basic <base64>     # if creds present
   ```
3. Proxy replies with a 2xx status. The request stream stays open.
4. Every QUIC packet for the real target gets wrapped in an HTTP/3 Datagram with context ID 0 (per RFC 9298), sent on the same QUIC connection. Replies come back the same way.

The inner QUIC connection runs an entirely separate handshake against the actual target host. The proxy can't read it.

## Provider auto-detection

httpcloak ships a small list of known MASQUE-capable providers in [proxy/masque_providers.go](https://github.com/sardanioss/httpcloak/blob/main/proxy/masque_providers.go). If your `https://` URL matches one of those hostnames it gets handled as MASQUE automatically. For any other provider, use `masque://` explicitly. That's the unambiguous form.

You can extend the list at runtime:

```go
import "github.com/sardanioss/httpcloak/proxy"

proxy.AddMASQUEProvider("my-custom-masque.example.com")
```

After that, `https://my-custom-masque.example.com:443` will be treated as MASQUE. Process-wide, applied immediately to subsequent sessions.

## QUIC config knobs that matter

- `EnableDatagrams` is forced on for the proxy connection. Required.
- `InitialPacketSize` defaults to 1350 to leave room for the outer QUIC frame plus inner QUIC's ~1200 MTU. Don't set it lower.
- The browser preset's QUIC fingerprint applies to the outer connection (the one to the proxy). The inner connection to the target also uses the preset, so the target sees a normal browser QUIC handshake.

## Common errors

- `proxy doesn't support Extended CONNECT`: the proxy isn't a MASQUE server. You're hitting a regular HTTPS endpoint or an H3 server that hasn't enabled Extended CONNECT. Check the URL.
- `proxy doesn't support HTTP/3 Datagrams`: same family, datagrams weren't negotiated. Provider misconfig or just not a MASQUE endpoint.
- `proxy responded with 407`: auth failed. Check `user:pass` in the URL.
- `proxy responded with 403`: target blocked by the proxy.
- `proxy responded with 502/503`: proxy can't reach the target over UDP, or the target's QUIC ALPN handshake failed.

## When to pick MASQUE over SOCKS5 UDP

MASQUE was designed from scratch for tunneling UDP. The framing is clean, congestion control is the outer QUIC's problem, and providers that ship it usually take it seriously. SOCKS5 UDP_ASSOCIATE works but the ecosystem support is patchy and the framing is per-datagram.

If your provider offers both, prefer MASQUE for H3.


---


<!-- source: docs/docs/proxies/source-address-binding.md -->

# Source Address Binding

Sometimes you need every outgoing socket to leave from a specific local IP. Reasons:

- Your machine has multiple public IPs and you want to pick one.
- You've got a routed IPv6 prefix (`/64` or wider) and want to rotate source IPs per request out of a huge pool.
- Audit / compliance requires a known egress IP.
- You're testing IPv6 behavior on a dual-stack box.

httpcloak gives you two options for this. They both set the same internal field, pick whichever ergonomic fits your code.

## The options

`WithLocalAddress(string)` takes a string IP. Both v4 and v6 work:

```go
httpcloak.WithLocalAddress("192.168.1.100")
httpcloak.WithLocalAddress("2001:db8::dead:beef")
```

`WithLocalAddrIP(net.IP)` takes a parsed `net.IP`. Useful when you've got an IP from a pool or a randomizer and you don't want to round-trip through a string. Nil is a no-op so you can safely write `opts = append(opts, httpcloak.WithLocalAddrIP(maybeNil))` without clobbering a previously-set address.

```go
ip := pickRandomFromPool() // returns net.IP
httpcloak.WithLocalAddrIP(ip)
```

There's also `WithSessionPreferIPv4()`, which is unrelated to local binding but commonly comes up next to it. It opts the dialer out of Happy Eyeballs and forces v4 lookups. Use it on networks where IPv6 is half-broken.

## What it does at the socket layer

Every outgoing socket (direct dial, dial-to-proxy, UDP for QUIC) gets `LocalAddr` set to the chosen IP with port 0 (kernel picks the ephemeral port). The kernel then tries to bind that source address before the connect.

On Linux, httpcloak also calls `setsockopt(IP_FREEBIND)` and `setsockopt(IPV6_FREEBIND)` on the raw socket before the bind. Why this matters next.

## Linux `IP_FREEBIND`: bind addresses you don't "own"

By default a Linux box won't let you bind to an IP that isn't configured on any of its interfaces. You'd get `EADDRNOTAVAIL`. `IP_FREEBIND` (and the IPv6 equivalent) skip that check. The kernel trusts that you know what you're doing.

This is the magic that makes IPv6 prefix rotation cheap. Your hoster routes a `/64` (or `/56`, or `/48`) to your box. You don't have to configure 18 quintillion addresses on the interface. You just bind to whichever address you want from the prefix and `IP_FREEBIND` lets the bind succeed. Outgoing packets carry that source address, return packets get routed back because the upstream router knows the prefix is yours. Pretty slick.

httpcloak applies `FREEBIND` unconditionally on Linux. Failures get silently ignored. If the kernel rejects it, the bind would have worked anyway because the address was locally configured, and we don't want to fail the simple case.

:::tip IPv6 /64 rotation
If you have a `/64` (or wider) routed to your box and want a fresh source IP per request, generate a random suffix and pass it to `WithLocalAddrIP`. Linux freebind handles the rest, no `ip addr add` required.
:::

## Permissions on Linux

`IP_FREEBIND` works without root in two cases:

- Per-process: granted via `CAP_NET_ADMIN` (rare for userland).
- System-wide: `sysctl net.ipv4.ip_nonlocal_bind=1` and the IPv6 equivalent `net.ipv6.ip_nonlocal_bind=1`.

Most production setups go with the sysctl. Drop this in `/etc/sysctl.d/`:

```
net.ipv4.ip_nonlocal_bind = 1
net.ipv6.ip_nonlocal_bind = 1
```

Without one of these, binding to a non-configured address still fails even with `FREEBIND` set. The setsockopt is necessary but not sufficient on stock kernels.

## Platform notes

- **Linux**: Full support. `IP_FREEBIND` + sysctl as above.
- **macOS / Darwin**: Bind works for addresses configured on an interface. Non-local bind isn't a thing the way Linux does it.
- **Windows**: Same as macOS.
- **Other Unix**: `freebind_other.go` is a no-op. The bind goes through but non-local addresses will fail at the kernel.

If you run on Linux and your code is portable, design for the Linux behavior and accept the other platforms as best-effort.

## Examples

### Pin to a specific IPv4



<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
s := httpcloak.NewSession("chrome-latest",
    httpcloak.WithLocalAddress("203.0.113.10"),
)
```

</TabItem>
<TabItem value="python" label="Python">

```python
s = httpcloak.Session(
    preset="chrome-latest",
    local_address="203.0.113.10",
)
```

</TabItem>
<TabItem value="node" label="Node.js">

```js
const s = new Session({
  preset: 'chrome-latest',
  localAddress: '203.0.113.10',
});
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using var s = new Session(
    preset: "chrome-latest",
    localAddress: "203.0.113.10");
```

</TabItem>
</Tabs>

### Bind to a specific IPv6

```go
import "net"

s := httpcloak.NewSession("chrome-latest",
    httpcloak.WithLocalAddrIP(net.ParseIP("2001:db8::1")),
)
```

### Rotating IPv6 from a /64

```go
import (
    "crypto/rand"
    "net"
)

func randomFromPrefix64(prefix net.IP) net.IP {
    suffix := make([]byte, 8)
    _, _ = rand.Read(suffix)
    out := make(net.IP, 16)
    copy(out[:8], prefix.To16()[:8])
    copy(out[8:], suffix)
    return out
}

prefix := net.ParseIP("2001:db8:abcd:1234::") // your routed /64
ip := randomFromPrefix64(prefix)

s := httpcloak.NewSession("chrome-latest",
    httpcloak.WithLocalAddrIP(ip),
)
defer s.Close()

resp, _ := s.Get(ctx, "https://httpbin.org/ip")
// returns the random v6 address you picked
```

You'd run that for each fresh request (a new session per IP, or pool the sessions by IP). The session itself caches one local address for its lifetime. Rotation happens at session-construction time.

### Combined with a proxy

Local binding and proxy options compose. The local address binds the *client to proxy* socket; the proxy still picks its own egress for the target connection.

```go
s := httpcloak.NewSession("chrome-latest",
    httpcloak.WithSessionTCPProxy("socks5://user:pass@proxy.example.com:1080"),
    httpcloak.WithLocalAddress("203.0.113.10"),
)
```

This makes sense when your machine has multiple egress IPs and you want the SOCKS5 control connection to leave from a known one (routing, firewall ACLs, etc).


---


<!-- source: docs/docs/cookies-and-state/index.md -->

# Cookies & State

The session jar handles cookies for you. This section covers how it works, when you'd want to switch it off, and how to hand-roll a `Cookie` header for one-off calls.

## In this section

- [Cookie Jar](./cookie-jar): how the internal jar works, what gets stored, when it sends what
- [Disabling the Cookie Jar](./disabling-cookie-jar): WithoutCookieJar() and when to actually do that
- [Per-Request Cookies](./per-request-cookies): ad-hoc Cookie headers for one-off calls
- [Domain and Path Matching](./domain-and-path-matching): the quirks of cookies matching the next URL


---


<!-- source: docs/docs/cookies-and-state/cookie-jar.md -->

# Cookie Jar

The cookie jar is on by default. It stores `Set-Cookie` values, replays them on matching follow-up requests, just like a browser tab does.

You don't have to flip anything on. It's already running.

## What gets stored

When a response comes back with `Set-Cookie` headers, httpcloak parses each one and saves the full attribute set:

- `name` and `value`
- `domain` (with the host-only flag tracked separately)
- `path`
- `expires` and `max-age`
- `secure`
- `httpOnly`
- `sameSite`

The jar also tracks creation time so cookies with longer paths and older creation timestamps come first when building the `Cookie` header. That's the RFC 6265 sort order browsers use.

## When the jar sends what

On the next request, the jar walks its stored cookies and picks the ones that match:

- the request **host** (host-only cookies need an exact match, domain cookies match the domain and any subdomain)
- the request **path** (cookie path must be a prefix of the request path with a `/` boundary)
- the request **scheme** (secure cookies only ride HTTPS)
- the **expiry** (anything past its expiry gets skipped)

The matches get glued together into a single `Cookie:` header and sent.

See [Domain and Path Matching](./domain-and-path-matching) for the full rules and the gotchas.

## Lifecycle

Cookies live in memory for as long as the `Session` lives. Close the session and the jar goes with it.

If you want cookies to survive across processes, use `Save()` and `LoadSession()`. They serialize the jar (along with TLS resumption tickets and a few other bits) to a file you can reload later. See [Session save & restore](/connection-lifecycle/session-save-restore) for the full flow.

## Quick example

The example below sets a cookie via `httpbin.org/cookies/set`, then reads `httpbin.org/cookies` to show the jar replayed it on the second request.



<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
	"context"
	"fmt"
	"io"

	"github.com/sardanioss/httpcloak"
)

func main() {
	s := httpcloak.NewSession("chrome-146")
	defer s.Close()

	ctx := context.Background()

	r1, _ := s.Get(ctx, "https://httpbin.org/cookies/set?demo=hello")
	r1.Close()

	r2, _ := s.Get(ctx, "https://httpbin.org/cookies")
	body, _ := io.ReadAll(r2.Body)
	r2.Close()
	fmt.Println(string(body))
	// {"cookies": {"demo": "hello"}}
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

with httpcloak.Session(preset="chrome-146") as s:
    s.get("https://httpbin.org/cookies/set?demo=hello")
    r = s.get("https://httpbin.org/cookies")
    print(r.json())
    # {'cookies': {'demo': 'hello'}}
```

</TabItem>
<TabItem value="nodejs" label="Node.js">

```js
const httpcloak = require("httpcloak");

const s = new httpcloak.Session({ preset: "chrome-146" });
try {
  await s.get("https://httpbin.org/cookies/set?demo=hello");
  const r = await s.get("https://httpbin.org/cookies");
  console.log(r.json());
  // { cookies: { demo: 'hello' } }
} finally {
  s.close();
}
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var s = new Session(preset: "chrome-146");

s.Get("https://httpbin.org/cookies/set?demo=hello");
var r = s.Get("https://httpbin.org/cookies");
Console.WriteLine(r.Text);
// {"cookies": {"demo": "hello"}}
```

</TabItem>
</Tabs>

## Inspecting the jar

The session exposes the current jar contents so you can poke at it:

- `GetCookies()` returns the full list with domain, path, expiry, flags
- `SetCookie(...)` adds or updates a cookie programmatically
- `DeleteCookie(name, domain)` removes one (pass empty domain to wipe across all domains)
- `ClearCookies()` empties the jar

Handy for tests, debugging, or when you want to seed the jar before the first request.

:::info DoStream parity
`DoStream()` also pulls cookies out of streamed responses (fixed in 1.6.6). Older versions you'll find in tutorials online didn't, so if you copy old code, double-check the version. Streaming and non-streaming requests now feed the same jar.
:::

## What the jar does NOT do

- It doesn't enforce `__Host-` and `__Secure-` cookie name prefixes with the strict RFC checks. The flags (`Secure`, host-only) are still respected, but the prefix rules aren't enforced separately.
- It doesn't do anything with `SameSite` other than store it. There's no cross-site request tracking, so cookies always go out on requests you make.
- It doesn't garbage-collect expired cookies on every read. They get filtered at send time and during `ClearExpired()`. If you keep a long-lived session and want a clean snapshot, call `ClearExpired()` yourself.

## When you don't want the jar

If you'd rather drive cookies yourself, drop the jar entirely with `WithoutCookieJar()`. See [Disabling the Cookie Jar](./disabling-cookie-jar).


---


<!-- source: docs/docs/cookies-and-state/disabling-cookie-jar.md -->

# Disabling the Cookie Jar

Sometimes you don't want the session managing cookies for you. Maybe you've got a database acting as your single source of truth. Maybe you want every request fully isolated. Or maybe you're debugging and the auto-replay is getting in the way.

`WithoutCookieJar()` (added in 1.6.6) flips the jar off. With it set:

- `Set-Cookie` headers from responses are **not** stored
- The jar is **not** consulted when building the next request's `Cookie` header
- `GetCookies()` returns an empty list

Caller-provided `Cookie` headers still pass through untouched. Only the auto-injection from the internal jar is suppressed.

## When to actually do this

A few real reasons to turn it off:

- **You manage cookies yourself.** App-level cookie store in Redis, Postgres, whatever. You read from there, build the `Cookie` header per request, and don't want the lib doing anything else.
- **You want each request fully independent.** Useful for fan-out crawling where two requests on the same session shouldn't share state.
- **You're debugging.** When you're trying to figure out why a response sets a weird cookie, having the jar silently swallow and replay it makes things harder. Turn it off, watch the raw headers.

If none of those apply, leave the jar on. It's there for a reason.

## Code



<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
	"context"
	"fmt"
	"io"

	"github.com/sardanioss/httpcloak"
)

func main() {
	s := httpcloak.NewSession("chrome-146", httpcloak.WithoutCookieJar())
	defer s.Close()

	ctx := context.Background()

	r1, _ := s.Get(ctx, "https://httpbin.org/cookies/set?demo=hello")
	r1.Close()

	r2, _ := s.Get(ctx, "https://httpbin.org/cookies")
	body, _ := io.ReadAll(r2.Body)
	r2.Close()
	fmt.Println(string(body))
	// {"cookies": {}} (jar didn't store anything)

	fmt.Println(s.GetCookies()) // []
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

with httpcloak.Session(preset="chrome-146", without_cookie_jar=True) as s:
    s.get("https://httpbin.org/cookies/set?demo=hello")
    r = s.get("https://httpbin.org/cookies")
    print(r.json())
    # {'cookies': {}}
```

</TabItem>
<TabItem value="nodejs" label="Node.js">

```js
const httpcloak = require("httpcloak");

const s = new httpcloak.Session({
  preset: "chrome-146",
  withoutCookieJar: true,
});
try {
  await s.get("https://httpbin.org/cookies/set?demo=hello");
  const r = await s.get("https://httpbin.org/cookies");
  console.log(r.json());
  // { cookies: {} }
} finally {
  s.close();
}
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var s = new Session(preset: "chrome-146", withoutCookieJar: true);

s.Get("https://httpbin.org/cookies/set?demo=hello");
var r = s.Get("https://httpbin.org/cookies");
Console.WriteLine(r.Text);
// {"cookies": {}}
```

</TabItem>
</Tabs>

## Managing cookies yourself

With the jar off, you're driving. Two main patterns:

1. **Send a `Cookie` header per request.** Build the string yourself, attach it to the request headers. See [Per-Request Cookies](./per-request-cookies) for examples.
2. **Pull `Set-Cookie` out of the response.** Each `Response` exposes its raw headers; parse `Set-Cookie` yourself and stash the result wherever you want.

:::info Headers still pass through
Even with the jar off, the `Cookie` header you set on a request still goes out as you wrote it. The flag only suppresses the lib's auto-injection, not your manual headers.
:::

## Mixing modes

You can't toggle `WithoutCookieJar` mid-session. It's a session option, set once at construction. If you need both modes (jar-on for one workflow, jar-off for another), spin up two sessions.

If you need shared TLS state across the two, use `Fork()` to create a sibling that carries the same TLS resumption cache but starts fresh on cookies. Heads up: forks share the same cookie jar pointer, so if you fork from a jar-enabled parent, both share the jar. To genuinely separate the cookie state, build a fresh session.


---


<!-- source: docs/docs/cookies-and-state/per-request-cookies.md -->

# Per-Request Cookies

Sometimes you just want to slap a `Cookie` header onto a single request without touching the session jar. Maybe you're testing one specific cookie. Maybe you've already got the value from somewhere else. Maybe the jar is off and you're driving manually.

httpcloak passes the `Cookie` header through unchanged. Whatever string you give it goes on the wire.

## Setting it on a request



<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
req := &httpcloak.Request{
	Method: "GET",
	URL:    "https://httpbin.org/cookies",
	Headers: map[string][]string{
		"Cookie": {"session=abc; lang=en"},
	},
}
r, _ := s.Do(ctx, req)
defer r.Close()
```

</TabItem>
<TabItem value="python" label="Python">

```python
# Option A: explicit Cookie header
r = s.get(
    "https://httpbin.org/cookies",
    headers={"Cookie": "session=abc; lang=en"},
)

# Option B: cookies kwarg (joined into a single Cookie header for you)
r = s.get(
    "https://httpbin.org/cookies",
    cookies={"session": "abc", "lang": "en"},
)
```

</TabItem>
<TabItem value="nodejs" label="Node.js">

```js
// Option A: explicit Cookie header
let r = await s.get("https://httpbin.org/cookies", {
  headers: { Cookie: "session=abc; lang=en" },
});

// Option B: cookies option
r = await s.get("https://httpbin.org/cookies", {
  cookies: { session: "abc", lang: "en" },
});
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
// Option A: explicit Cookie header
var headers = new Dictionary<string, string> {
    { "Cookie", "session=abc; lang=en" }
};
var r = s.Get("https://httpbin.org/cookies", headers: headers);

// Option B: cookies parameter
var cookies = new Dictionary<string, string> {
    { "session", "abc" },
    { "lang", "en" }
};
var r2 = s.Get("https://httpbin.org/cookies", cookies: cookies);
```

</TabItem>
</Tabs>

## How this interacts with the jar

If the jar is on, the lib **merges** your per-request `Cookie` header with whatever the jar would have sent. Your header comes first, jar contents come after, joined with `; `.

That's usually what you want. But if your goal is "use only this one cookie, ignore the jar," you've got two clean options:

1. Disable the jar with [`WithoutCookieJar()`](./disabling-cookie-jar) for that whole session.
2. Call `ClearCookies()` on the session right before the request, then attach your header.

Don't try to fight the merge by setting `Cookie: ""`. The lib treats empty as "no per-request cookie," not "send nothing," so the jar will still inject.

## Cookie order matters for fingerprinting

The order of cookies in the `Cookie` header is part of your client's fingerprint. Real browsers sort consistently (longer path first, then by creation time, per RFC 6265). httpcloak preserves whatever you give it byte-for-byte.

So if you're hand-rolling cookies and you want to look like a browser, sort them yourself. Don't shuffle them across requests, don't rely on `dict` iteration order in scripts, and double-check your sort matches the order the jar would have produced. Anti-bot vendors absolutely watch for cookie order drift between requests.

If the jar is doing the work for you, you don't have to think about this. The jar handles the sort. This only matters when you're driving the `Cookie` header manually.

## When per-request beats the jar

A few situations where reaching for a per-request header makes more sense than touching the jar:

- **One-off auth.** A single API call needs a special token cookie that shouldn't stick around for follow-ups.
- **Replaying a captured session.** You've got a `Cookie` string from a browser export; just paste it.
- **Cross-host scenarios.** You want the same cookie sent to two different hosts that the jar's domain rules wouldn't cover automatically.

For everything else, let the jar do its job.


---


<!-- source: docs/docs/cookies-and-state/domain-and-path-matching.md -->

# Domain and Path Matching

The jar runs four checks before a cookie rides along: domain, path, secure, expiry. Get any of them wrong and the cookie either leaks where it shouldn't or silently goes missing where it should have been sent.

This page covers the rules httpcloak's jar follows and the surprises that catch most people out.

## Domain matching

A cookie's domain is set in one of two ways:

- **No `Domain` attribute on `Set-Cookie`.** The cookie is **host-only**. It only goes back to the exact host that set it.
- **`Domain=foo.example.com` (with or without leading dot).** The cookie is a **domain cookie**. It goes back to `foo.example.com` and any subdomain.

Examples with a request to `https://api.example.com/`:

| Stored `Domain` | Type | Sent? |
|---|---|---|
| (none, set by `api.example.com`) | host-only | yes |
| (none, set by `example.com`) | host-only | no |
| `.example.com` | domain | yes |
| `example.com` | domain | yes (modern, see note) |
| `.api.example.com` | domain | yes |
| `.other.com` | domain | no |

:::caution Leading dot, RFC vs reality
Strict RFC 2109 said `Domain=example.com` (no leading dot) meant "exactly example.com." RFC 6265 and every modern browser treat it as if you wrote `.example.com`, so it includes subdomains. When httpcloak parses `Set-Cookie` from a response, it follows the modern behavior: stored with the leading dot internally, matches subdomains.

Heads up: when you call the programmatic `SetCookie()` / `set_cookie()` API yourself, the same string `Domain="example.com"` (no leading dot) is currently stored as **host-only** instead, which is the older RFC 2109 reading. Asymmetry with response-header parsing. If you want a domain cookie via the API, write the leading dot explicitly: `Domain=".example.com"`.
:::

You also can't set a cookie for a domain you don't control. If `api.example.com` returns `Set-Cookie: x=1; Domain=other.com`, the jar rejects it. The request host has to equal the cookie domain or be a subdomain of it.

## Path matching

The path rule is a prefix match with a `/` boundary. A cookie set for `Path=/api` matches:

- `/api` (exact)
- `/api/` (cookie path is a prefix and the next char is `/`)
- `/api/foo`
- `/api/foo/bar`

It does **not** match:

- `/apixyz` (next char isn't `/`)
- `/foo/api` (cookie path isn't a prefix)
- `/` (request path is shorter)

If the cookie path ends in `/`, like `Path=/api/`, the slash boundary is implicit and any request path with that exact prefix matches.

If `Set-Cookie` doesn't include `Path`, httpcloak defaults it to `/`, which matches every request to that domain.

## Secure flag

A cookie with `Secure` only goes out on HTTPS. Period. Even if everything else matches, a plain `http://` request won't see it.

This works the other way too: a server can only **set** a `Secure` cookie over HTTPS. If `Set-Cookie: x=1; Secure` arrives over plain HTTP, the jar rejects it.

## Expiry

The jar checks expiry at send time. A cookie with an `Expires` in the past gets skipped. A session cookie (no `Expires`, no `Max-Age`) lives until the session is closed or `ClearCookies()` is called.

The jar doesn't sweep expired cookies eagerly. Call `ClearExpired()` if you want a clean snapshot.

## Worked example



<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
s := httpcloak.NewSession("chrome-146")
defer s.Close()

// host-only scoping: bare domain via the API stores as host-only
s.SetCookie(httpcloak.CookieInfo{
	Name: "scoped", Value: "yes",
	Domain: "httpbin.org", Path: "/cookies",
})

ctx := context.Background()

r1, _ := s.Get(ctx, "https://httpbin.org/cookies")
// matches → {"cookies": {"scoped": "yes"}}
r1.Close()

r2, _ := s.Get(ctx, "https://httpbin.org/anything")
// path /anything doesn't match /cookies → cookie not sent
r2.Close()
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

with httpcloak.Session(preset="chrome-146") as s:
    s.set_cookie(
        name="scoped",
        value="yes",
        domain="httpbin.org",
        path="/cookies",
    )

    r1 = s.get("https://httpbin.org/cookies")
    print(r1.json())
    # {'cookies': {'scoped': 'yes'}}

    r2 = s.get("https://httpbin.org/anything")
    # cookie not sent, path /anything doesn't match /cookies
```

</TabItem>
<TabItem value="nodejs" label="Node.js">

```js
const httpcloak = require("httpcloak");

const s = new httpcloak.Session({ preset: "chrome-146" });
try {
  s.setCookie("scoped", "yes", {
    domain: "httpbin.org",
    path: "/cookies",
  });

  let r = await s.get("https://httpbin.org/cookies");
  console.log(r.json());
  // { cookies: { scoped: 'yes' } }

  r = await s.get("https://httpbin.org/anything");
  // cookie not sent
} finally {
  s.close();
}
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var s = new Session(preset: "chrome-146");

s.SetCookie("scoped", "yes", domain: "httpbin.org", path: "/cookies");

var r1 = s.Get("https://httpbin.org/cookies");
Console.WriteLine(r1.Text);
// {"cookies": {"scoped": "yes"}}

var r2 = s.Get("https://httpbin.org/anything");
// cookie not sent
```

</TabItem>
</Tabs>

## Common gotchas

- **You meant host-only but typed `Domain`.** Setting `Domain=example.com` makes the cookie ride out to every subdomain. If you only want `example.com` itself, omit `Domain` entirely.
- **Path looks like it matches but doesn't.** `/api` does not match `/apiv2`. The boundary check requires a `/` (or exact equality).
- **Secure cookie set over HTTP.** Some local dev setups proxy through plain HTTP. The jar won't store a `Secure` cookie if the response wasn't HTTPS.
- **Setting `Domain` for someone else's domain.** A response from `a.com` setting `Domain=b.com` gets rejected. Cross-site cookie injection isn't a thing the jar will help you with.
- **Forgetting expiry on long-lived sessions.** A cookie with `Max-Age=10` is gone in ten seconds. The jar will quietly stop sending it. If a server-side flow seems to log you out for no reason, check the cookie expiry first.

:::warning Don't leak cookies to subdomains
If you set `Domain` in your `Cookie` header without thinking, you can leak cookies to subdomains you didn't mean to hit. Match the browser's behavior: leave `Domain` empty on cookies you set yourself when you only want host-only matching. Adding the attribute opts you into subdomain delivery for the rest of the cookie's life.
:::


---


<!-- source: docs/docs/fingerprinting/index.md -->

# Fingerprinting

Pick a preset and you're done. Or tweak the JSON, override one knob, feed in a raw JA3. Whatever the job needs.

## In this section

- [What is TLS Fingerprinting](./what-is-tls-fingerprinting): a fast primer on JA3, JA4, akamai H2 hashes
- [Presets](./presets): the full preset list and how to pick the right one
- [JSON Preset Builder](./json-preset-builder): describe_preset, mutate JSON, load_preset_from_json. The customization path you'll actually reach for
- [Custom JA3](./custom-ja3): WithCustomFingerprint with a raw JA3 string
- [Akamai Shorthand](./akamai-shorthand): H2 shorthand format, change one knob without rebuilding the whole preset
- [Per-Resource Priority](./per-resource-priority): RFC 7540 weights and RFC 9218 priority headers from Sec-Fetch-Dest


---


<!-- source: docs/docs/fingerprinting/what-is-tls-fingerprinting.md -->

# What is TLS Fingerprinting

A TLS fingerprint is just the shape of your TLS handshake on the wire. The ClientHello is a packed, ordered message: cipher list, extension list, supported groups, signature algorithms, all laid out in a specific sequence. Different clients pick different orders, so their ClientHellos look different byte-for-byte. Hash the bytes and you've got a fingerprint.

Anti-bot vendors keep an allowlist of known-browser hashes. Match one, you pass. Don't match, you're flagged. That's basically the whole game.

The same trick applies at the H2 layer. Once the handshake's done, the connection opens with a SETTINGS frame, a WINDOW_UPDATE, sometimes PRIORITY frames, and a fixed pseudo-header order on your first request. Every browser does this a little differently, so the H2 layer hashes too.

## The fingerprint formats you'll meet

### JA3

The OG. MD5 over five comma-separated lists pulled from the ClientHello:

```
TLSVersion,CipherSuites,Extensions,EllipticCurves,PointFormats
```

Chrome 148 example:

```
771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,0-5-10-11-13-16-17613-18-23-27-35-43-45-51-65037-65281,29-23-24,0
```

JA3 is basically dead. Modern Chrome shuffles its TLS extension order on every single connection, so the raw JA3 string and the `ja3_hash` change every time even though the actual browser version hasn't moved. Most defenders dropped JA3 ages ago. Don't waste energy matching it.

### JA4

The replacement everyone uses now. Compound and way more granular:

```
t13d1516h2_8daaf6152771_d8a2da3f94cd
```

Decoding:

- `t13`: TLS 1.3
- `d`: TCP (`q` if you're on QUIC)
- `1516`: 15 ciphers, 16 extensions
- `h2`: ALPN h2
- middle hash: sorted cipher suites
- last hash: sorted extensions and sig algs

JA4 sorts extensions before hashing, which kills Chrome's shuffle problem. This is the one you actually want to verify against.

### Akamai HTTP/2 hash

A separate fingerprint, one layer up. Hashes a tiny string with four parts:

```
SETTINGS|WINDOW_UPDATE|PRIORITY|PSEUDO_HEADER_ORDER
```

Chrome 148 looks like:

```
1:65536;2:0;4:6291456;6:262144|15663105|0|m,a,s,p
```

That string captures the initial window size, the header table size, the connection-level window update, and the order Chrome sends `:method`, `:authority`, `:scheme`, `:path` in. Chrome and Safari ship a different pseudo-header order. Firefox lays out SETTINGS differently. All of it lands in one akamai hash, so a single value tells you a lot.

## Why default Go gets blocked

`net/http` builds its ClientHello with Go's standard `crypto/tls`. Cipher list, extensions, supported curves, all bog-standard Go defaults. No real browser produces that handshake. The JA4 hash for default Go matches zero browsers, anywhere.

So the bot vendor blocks by exclusion. Hash isn't on the allowlist, request is presumed bot, you eat a 403. Simple.

This is also why cranking `curl --tls-cipher` to reorder ciphers won't save you. Chrome isn't just sending a different cipher list. It's sending a different extension order, a different curve list, different sig algs, different ALPN, different cert compression. The whole packet is different. Reproducing all of that end-to-end is what httpcloak exists to do.

httpcloak puts ClientHello bytes on the wire that are byte-identical to a real Chrome / Firefox / Safari handshake. H2 SETTINGS, WINDOW_UPDATE, pseudo-header order all match. So does the order of regular HTTP headers Chrome sends on the first request, because Chrome being a lil bitch won't show you that order in DevTools, you can check `tls.peet.ws/api/all` for it.

## See for yourself

Hit `tls.peet.ws/api/all` with the `chrome-latest` preset and look at the JA4:

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "context"
    "fmt"
    "io"

    "github.com/sardanioss/httpcloak"
)

func main() {
    s := httpcloak.NewSession("chrome-latest")
    defer s.Close()

    resp, err := s.Get(context.Background(), "https://tls.peet.ws/api/all")
    if err != nil { panic(err) }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

with httpcloak.Session(preset="chrome-latest") as s:
    r = s.get("https://tls.peet.ws/api/all")
    print(r.text)
```

</TabItem>
<TabItem value="node" label="Node.js">

```js
const { Session } = require("httpcloak");

const s = new Session({ preset: "chrome-latest" });
const r = await s.get("https://tls.peet.ws/api/all");
console.log(r.text);
s.close();
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var s = new Session(preset: "chrome-latest");
var r = await s.GetAsync("https://tls.peet.ws/api/all");
Console.WriteLine(r.Text);
```

</TabItem>
</Tabs>

What comes back (Chrome 148, captured 2026-05):

```text
ja4:                     t13d1516h2_8daaf6152771_d8a2da3f94cd
peetprint_hash:          1d4ffe9b0e34acac0bd883fa7f79d7b5
akamai_fingerprint_hash: 52d84b11737d980aef856699f885ca86
```

Those three match real Chrome 148 desktop. Run the same code through `net/http` and you'd see something like `t13d1517h2_acb858a92679_eb4d4c4c4f4f` for JA4, which matches no browser that ever shipped.

Heads up: `ja3_hash` won't be stable across runs because of Chrome's extension shuffle. `ja4` and `peetprint_hash` are stable. Verify against those two.

:::info
`tls.peet.ws/api/all` is the workhorse. It reflects everything back: TLS, H2, headers, and the order each piece arrived in. `cf.erika.cool` and `browserleaks.com` are useful when you specifically want to see what Cloudflare's edge sees. All three are safe to test against, no C&D risk.
:::

## What's next in this section

- [Presets](./presets): the bundled Chrome / Firefox / Safari profiles you can pick by name.
- [JSON Preset Builder](./json-preset-builder): dump a preset to JSON, mutate it, load it back as a new preset. The customization path you'll actually use.
- [Custom JA3](./custom-ja3): when you only want to override the JA3 string, this is the lightweight one.
- [Akamai Shorthand](./akamai-shorthand): same idea but for the H2 fingerprint.
- [Per-Resource Priority](./per-resource-priority): RFC 7540 stream weights and RFC 9218 priority headers driven by `Sec-Fetch-Dest`.


---


<!-- source: docs/docs/fingerprinting/presets.md -->

# Presets

A preset is the whole fingerprint bundle for one browser version on one platform. It packs:

- TLS ClientHello (cipher list, extension list, supported groups, signature algorithms, ALPN, cert compression).
- HTTP/2 SETTINGS values, WINDOW_UPDATE, pseudo-header order.
- Default HTTP headers in the exact order Chrome / Firefox / Safari ships them.
- RFC 7540 stream priorities and the RFC 9218 priority table per Sec-Fetch-Dest.
- HTTP/3 / QUIC transport parameters (only on presets that support h3).
- TCP/IP fingerprint hints (TTL, MSS, window size, for OS-level matching).

Pick one by name, send a request, done. The wire bytes match the real browser.

## Picking the right preset

- **Default to `chrome-latest`.** Works against the widest range of targets. Auto-tracks the newest Chrome we've shipped.
- **Reach for `android-chrome-latest` if you need a mobile UA.** Mobile traffic gets scored differently on most anti-bot stacks. TLS handshake's identical to desktop Chrome, but the User-Agent and `sec-ch-ua-mobile: ?1` flag the mobile path.
- **Use `ios-safari-18` (or `safari-18-ios`) if you need an iPhone fingerprint.** Different cipher list, different pseudo-header order, no RFC 7540 priorities, smaller QUIC stream window. Targets that profile iOS users will spot a Chrome preset pretending to be an iPhone in seconds.
- **Pick `firefox-148` if the target only accepts Firefox.** Different cipher list, different SETTINGS layout (smaller initial window, smaller max frame size), different pseudo-header order (`m,p,a,s` vs Chrome's `m,a,s,p`).

## Available preset families

### Chrome

Versions 133, 141, 143, 144, 145, 146, 147, 148. Each version has per-OS variants:

| Family | Variants |
|---|---|
| Desktop | `chrome-148`, `chrome-148-windows`, `chrome-148-linux`, `chrome-148-macos` |
| Android | `chrome-148-android` (alias: `android-chrome-148`) |
| iOS     | `chrome-148-ios` (alias: `ios-chrome-148`) |

Bare `chrome-148` resolves to the host OS at runtime via `runtime.GOOS`. So on a Linux box, `chrome-148` gives you `chrome-148-linux`. Want the same platform UA no matter where the code runs? Use the explicit variant.

### Chrome -latest aliases

Aliases that auto-track the newest shipped Chrome:

```
chrome-latest          → chrome-148
chrome-latest-windows  → chrome-148-windows
chrome-latest-linux    → chrome-148-linux
chrome-latest-macos    → chrome-148-macos
chrome-latest-android  → chrome-148-android
chrome-latest-ios      → chrome-148-ios
```

When Chrome 149 ships, those aliases bump in lockstep. Code on `chrome-latest` keeps rolling. Code that pinned `chrome-148-windows` stays on the same fingerprint.

### Firefox

`firefox-133`, `firefox-148`, `firefox-latest`. No per-OS variants, Firefox doesn't bake enough OS info into its fingerprint for that to matter. No h3 yet either, Firefox has its own h3 quirks we haven't built out.

### Safari

| Preset | Notes |
|---|---|
| `safari-18` (`safari-latest`) | Desktop macOS Safari 18, supports h3 |
| `safari-17-ios` (`ios-safari-17`) | iPhone Safari 17, h2 only |
| `safari-18-ios` (`ios-safari-18`, `safari-latest-ios`) | iPhone Safari 18, supports h3 |

Safari sets `NoRFC7540Priorities=true`, so it never emits the H2 PRIORITY frame. RFC 9218 priority headers carry the signal instead. That's the single biggest tell that splits a Safari fingerprint from a Chrome one at the H2 layer, even though both ALPN as h2.

### Backwards-compat aliases

The older `<os>-<browser>-<version>` naming still works for folks on older docs:

```
ios-chrome-148        → chrome-148-ios
ios-safari-18         → safari-18-ios
android-chrome-148    → chrome-148-android
```

Both forms resolve to the same preset.

## Inheritance: how a new Chrome version ships in 30 seconds

Each Chrome minor bump is usually pure UA + sec-ch-ua delta. TLS fingerprint, H2 SETTINGS, header order, priority table, all the same as the version before. So Chrome 148 isn't a from-scratch Go file. It's a JSON delta over Chrome 147:

```json
{
  "version": 1,
  "preset": {
    "name": "chrome-148-windows",
    "based_on": "chrome-147-windows",
    "headers": {
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36",
      "values": {
        "sec-ch-ua": "\"Chromium\";v=\"148\", \"Google Chrome\";v=\"148\", \"Not/A)Brand\";v=\"99\""
      },
      "order": [
        {"key": "sec-ch-ua", "value": "\"Chromium\";v=\"148\", \"Google Chrome\";v=\"148\", \"Not/A)Brand\";v=\"99\""},
        {"key": "sec-ch-ua-mobile", "value": "?0"},
        ...
      ]
    }
  }
}
```

That's the whole patch. TLS bytes come from chrome-147-windows (which itself inherits TLS bytes from chrome-146-windows because nothing changed in 147). H2 SETTINGS, priority table, everything else, all inherited.

You can do the same. Pick a preset, dump it, change three fields, register the result. See [JSON Preset Builder](./json-preset-builder).

## Verification

Hit `tls.peet.ws/api/all` with each preset and you'll see the matching JA4 / Akamai hash:

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "context"
    "fmt"
    "io"

    "github.com/sardanioss/httpcloak"
)

func main() {
    for _, name := range []string{"chrome-latest", "android-chrome-148", "firefox-148", "safari-18-ios"} {
        s := httpcloak.NewSession(name)
        resp, _ := s.Get(context.Background(), "https://tls.peet.ws/api/all")
        body, _ := io.ReadAll(resp.Body)
        resp.Body.Close()
        s.Close()
        fmt.Println(name, string(body))
    }
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

for name in ["chrome-latest", "android-chrome-148", "firefox-148", "safari-18-ios"]:
    with httpcloak.Session(preset=name) as s:
        r = s.get("https://tls.peet.ws/api/all")
        print(name, r.json())
```

</TabItem>
<TabItem value="node" label="Node.js">

```js
const { Session } = require("httpcloak");

for (const name of ["chrome-latest", "android-chrome-148", "firefox-148", "safari-18-ios"]) {
  const s = new Session({ preset: name });
  const r = await s.get("https://tls.peet.ws/api/all");
  console.log(name, r.json());
  s.close();
}
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

foreach (var name in new[] { "chrome-latest", "android-chrome-148", "firefox-148", "safari-18-ios" }) {
    using var s = new Session(preset: name);
    var r = await s.GetAsync("https://tls.peet.ws/api/all");
    Console.WriteLine($"{name} {r.Text}");
}
```

</TabItem>
</Tabs>

Captured fingerprints (run on 2026-05, against `tls.peet.ws/api/all`):

```text
chrome-latest        ja4=t13d1516h2_8daaf6152771_d8a2da3f94cd  peetprint_hash=1d4ffe9b0e34acac0bd883fa7f79d7b5  akamai_fingerprint_hash=52d84b11737d980aef856699f885ca86
chrome-148-windows   ja4=t13d1516h2_8daaf6152771_d8a2da3f94cd  peetprint_hash=1d4ffe9b0e34acac0bd883fa7f79d7b5  akamai_fingerprint_hash=52d84b11737d980aef856699f885ca86
chrome-148-linux     ja4=t13d1516h2_8daaf6152771_d8a2da3f94cd  peetprint_hash=1d4ffe9b0e34acac0bd883fa7f79d7b5  akamai_fingerprint_hash=52d84b11737d980aef856699f885ca86
chrome-148-macos     ja4=t13d1516h2_8daaf6152771_d8a2da3f94cd  peetprint_hash=1d4ffe9b0e34acac0bd883fa7f79d7b5  akamai_fingerprint_hash=52d84b11737d980aef856699f885ca86
android-chrome-148   ja4=t13d1516h2_8daaf6152771_d8a2da3f94cd  peetprint_hash=1d4ffe9b0e34acac0bd883fa7f79d7b5  akamai_fingerprint_hash=52d84b11737d980aef856699f885ca86
firefox-148          ja4=t13d1717h2_5b57614c22b0_3cbfd9057e0d  peetprint_hash=89d89662b21018947a9a46658c4f5ede  akamai_fingerprint_hash=6ea73faa8fc5aac76bded7bd238f6433
safari-18            ja4=t13d2013h2_a09f3c656075_7f0f34a4126d  peetprint_hash=62b834de729e78a9f0ebd1dd099314a7  akamai_fingerprint_hash=90d8353e47699c4c38ecd773e9b5a089
safari-18-ios        ja4=t13d2013h2_a09f3c656075_7f0f34a4126d  peetprint_hash=62b834de729e78a9f0ebd1dd099314a7  akamai_fingerprint_hash=90d8353e47699c4c38ecd773e9b5a089
chrome-148-ios       ja4=t13d2013h2_a09f3c656075_7f0f34a4126d  peetprint_hash=62b834de729e78a9f0ebd1dd099314a7  akamai_fingerprint_hash=c52879e43202aeb92740be6e8c86ea96
```

Things to spot:

- Every Chrome desktop variant lands on the same JA4 / peetprint / akamai. The TLS handshake is genuinely identical across Windows / Linux / macOS Chrome. Only the User-Agent and `sec-ch-ua-platform` header tell you which OS you're on.
- Android Chrome shares the same fingerprint as desktop Chrome too. Same TLS, same H2. The wire-level difference is the UA string (Mobile Safari/537.36) and `sec-ch-ua-mobile: ?1`.
- Chrome on iOS shows up as Safari at the wire level, because iOS WebKit forces every browser onto the system networking stack. So `chrome-148-ios` shares its TLS handshake and JA4 hash with `safari-18-ios`. They split only on H2 SETTINGS values (chrome-148-ios advertises `2,3,4,9` vs Safari's `2,4,3,5,9`) and the User-Agent.
- Firefox and Safari each get their own JA4 / peetprint / akamai. Different cipher list, different SETTINGS, different pseudo-header order.

:::tip
The bare `ja3_hash` field won't be stable for Chrome presets across runs. Chrome shuffles its TLS extension order on every connection, so the raw JA3 string changes and the MD5 changes with it. JA4 sorts the extension list before hashing, that's why it's stable. Always verify against `ja4` and `peetprint_hash`, never `ja3_hash`.
:::

## Full preset catalog

69 preset names total (counting -latest aliases and the old `<os>-<browser>` naming). For the exhaustive table with version numbers, supported protocols, and platform tags, see the [Presets reference](../reference/presets).


---


<!-- source: docs/docs/fingerprinting/json-preset-builder.md -->

# JSON Preset Builder

This is the customization workflow you'll actually want.

Take any built-in preset, dump it as fully-resolved JSON, mutate the fields you care about, load the mutated JSON back as a new preset under a fresh name. No Go code change, no rebuild. Three function calls and you're done.

## The three functions

| Function | What it does |
|---|---|
| `describe_preset(name)` | Returns the full preset spec as JSON. Inheritance is flattened. H2 / H3 default values are emitted explicitly. |
| `load_preset_from_json(json)` | Parses + builds a preset from JSON, registers it under the name in the JSON. |
| `unregister_preset(name)` | Drops a custom registration. Built-ins can't be unregistered. |

## Round-trip is byte-identical

Call `describe_preset`, then `load_preset_from_json`, then `describe_preset` again, you get byte-for-byte identical JSON. We lean on that property internally, it's why our embedded Chrome 148 presets are JSON files instead of Go code. Tested for every shipped preset.

What this means for you: describe, edit, load, describe, diff. The diff shows exactly what changed. No surprise drift from defaults getting dropped.

## Use cases

- **Spoof a Chrome version we haven't shipped yet.** Grab `chrome-latest`, override the User-Agent and sec-ch-ua brand list, register as `chrome-149-windows`. Five minutes.
- **Pin a UA OS that doesn't match your runtime.** A Linux box can ship the `chrome-148-windows` UA without touching the TLS handshake.
- **Remove or add a single TLS extension.** Override `tls.signature_algorithms` or `tls.alpn` without rebuilding the whole ClientHello.
- **Tweak one HTTP/2 SETTINGS value.** Bump `initial_window_size`, leave everything else alone.
- **Swap in a captured ClientHello from a real browser session.** See the [Build a custom preset from a tls.peet.ws capture](/recipes/build-custom-chrome-from-tls-peet) recipe.

## Walkthrough: dump, mutate, load, send

Take `chrome-148-windows`, change the User-Agent, register the result as `my-chrome-mutant`, fire a request through it.

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "context"
    "encoding/json"
    "fmt"
    "io"

    "github.com/sardanioss/httpcloak"
    "github.com/sardanioss/httpcloak/fingerprint"
)

func main() {
    // 1. Dump chrome-148-windows as JSON.
    desc, err := fingerprint.Describe("chrome-148-windows")
    if err != nil { panic(err) }

    // 2. Parse it, mutate the User-Agent and the preset name.
    var pf fingerprint.PresetFile
    if err := json.Unmarshal([]byte(desc), &pf); err != nil { panic(err) }
    pf.Preset.Name = "my-chrome-mutant"
    pf.Preset.Headers.UserAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) " +
        "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/200.0.0.0 Safari/537.36"
    out, _ := json.MarshalIndent(&pf, "", "  ")

    // 3. Load it back. This builds + registers under the new name.
    p, err := fingerprint.LoadAndBuildPresetFromJSON(out)
    if err != nil { panic(err) }
    fingerprint.Register(p.Name, p)

    // 4. Use it.
    s := httpcloak.NewSession("my-chrome-mutant")
    defer s.Close()
    resp, _ := s.Get(context.Background(), "https://tls.peet.ws/api/all")
    body, _ := io.ReadAll(resp.Body)
    resp.Body.Close()
    fmt.Println(string(body))
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import json
import httpcloak

# 1. Dump chrome-148-windows as JSON.
desc = httpcloak.describe_preset("chrome-148-windows")

# 2. Parse, mutate, re-serialize.
pf = json.loads(desc)
pf["preset"]["name"] = "my-chrome-mutant"
pf["preset"]["headers"]["user_agent"] = (
    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
    "(KHTML, like Gecko) Chrome/200.0.0.0 Safari/537.36"
)

# 3. Load back. Returns the registered name.
name = httpcloak.load_preset_from_json(json.dumps(pf))

# 4. Use it.
with httpcloak.Session(preset=name) as s:
    r = s.get("https://tls.peet.ws/api/all")
    print(r.text)
```

</TabItem>
<TabItem value="node" label="Node.js">

```js
const { Session, describePreset, loadPresetFromJSON } = require("httpcloak");

// 1. Dump chrome-148-windows as JSON.
const desc = describePreset("chrome-148-windows");

// 2. Parse, mutate, re-serialize.
const pf = JSON.parse(desc);
pf.preset.name = "my-chrome-mutant";
pf.preset.headers.user_agent =
  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 " +
  "(KHTML, like Gecko) Chrome/200.0.0.0 Safari/537.36";

// 3. Load back. Returns the registered name.
const name = loadPresetFromJSON(JSON.stringify(pf));

// 4. Use it.
const s = new Session({ preset: name });
const r = await s.get("https://tls.peet.ws/api/all");
console.log(r.text);
s.close();
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using System.Text.Json;
using HttpCloak;

// 1. Dump chrome-148-windows as JSON.
var desc = CustomPresets.Describe("chrome-148-windows");

// 2. Parse, mutate, re-serialize.
var doc = JsonNode.Parse(desc)!;
doc["preset"]!["name"] = "my-chrome-mutant";
doc["preset"]!["headers"]!["user_agent"] =
    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 " +
    "(KHTML, like Gecko) Chrome/200.0.0.0 Safari/537.36";

// 3. Load back. Returns the registered name.
var name = CustomPresets.LoadFromJson(doc.ToJsonString());

// 4. Use it.
using var s = new Session(preset: name);
var r = await s.GetAsync("https://tls.peet.ws/api/all");
Console.WriteLine(r.Text);
```

</TabItem>
</Tabs>

What `tls.peet.ws/api/all` reflects back:

```text
user_agent:              Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/200.0.0.0 Safari/537.36
ja4:                     t13d1516h2_8daaf6152771_d8a2da3f94cd
peetprint_hash:          1d4ffe9b0e34acac0bd883fa7f79d7b5
akamai_fingerprint_hash: 52d84b11737d980aef856699f885ca86
```

The User-Agent's our custom value. The TLS / H2 fingerprint is byte-identical to the original `chrome-148-windows`. Mutation lands on exactly the field we touched, nothing else drifted.

## What `describe_preset` returns

A complete `PresetFile` with everything resolved:

```json
{
  "version": 1,
  "preset": {
    "name": "chrome-148-windows",
    "tls": {
      "client_hello": "chrome-146-windows",
      "psk_client_hello": "chrome-146-windows-psk",
      "quic_client_hello": "chrome-146-quic",
      "quic_psk_client_hello": "chrome-146-quic-psk"
    },
    "http2": {
      "header_table_size": 65536,
      "enable_push": false,
      "max_concurrent_streams": 0,
      "initial_window_size": 6291456,
      "max_frame_size": 0,
      "max_header_list_size": 262144,
      "connection_window_update": 15663105,
      "stream_weight": 256,
      "stream_exclusive": true,
      "no_rfc7540_priorities": false,
      "settings_order": [1, 2, 4, 6],
      "pseudo_order": [":method", ":authority", ":scheme", ":path"],
      "hpack_indexing_policy": "chrome",
      "stream_priority_mode": "chrome",
      "disable_cookie_split": true,
      "priority_table": {
        "document":  {"urgency": 0, "incremental": true,  "emit_header": true},
        "style":     {"urgency": 0, "incremental": false, "emit_header": true},
        "script":    {"urgency": 1, "incremental": false, "emit_header": true},
        "image":     {"urgency": 2, "incremental": true,  "emit_header": true},
        ...
      }
    },
    "http3": { ... },
    "headers": {
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36",
      "values": { "sec-ch-ua": "\"Chromium\";v=\"148\", ...", ... },
      "order": [
        {"key": "sec-ch-ua", "value": "..."},
        {"key": "sec-ch-ua-mobile", "value": "?0"},
        ...
      ]
    },
    "tcp": { "ttl": 128, "mss": 1460, "window_size": 64240, "window_scale": 8, "df_bit": true },
    "protocols": { "http3": true }
  }
}
```

Worth noting:

- Inheritance is flattened. Even though `chrome-148-windows` is internally based on `chrome-147-windows` which is based on `chrome-146-windows`, the describe output has no `based_on` field. Every value's emitted explicitly. You don't need to chase the chain.
- `tls.client_hello` says `chrome-146-windows`. That's the underlying utls ClientHelloID we use. TLS bytes haven't actually changed since Chrome 146 desktop, only the User-Agent and sec-ch-ua values have. That's correct.
- Every H2 SETTINGS value shows up, even the zero ones (`max_concurrent_streams: 0`, `max_frame_size: 0`). Zero means "don't emit this SETTINGS entry on the wire", and that info survives the round-trip.
- The full RFC 7540 priority table lands under `http2.priority_table`. Chrome 147+ ships its real per-Sec-Fetch-Dest urgencies. Presets that opt out (Safari, iOS Chrome, iOS Safari) skip this block.

For the full schema with every field documented, see the [JSON Preset Spec](../reference/json-preset-spec).

## Inheritance with `based_on`

You don't have to dump and edit. You can write a thin patch JSON that lists only what you want to change, with `based_on` pointing at the parent:

```json
{
  "version": 1,
  "preset": {
    "name": "my-chrome-mutant",
    "based_on": "chrome-148-windows",
    "headers": {
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/200.0.0.0 Safari/537.36"
    }
  }
}
```

That's what our embedded `chrome-148-windows.json` does, a 28-line patch on top of `chrome-147-windows`. Inheritance is recursive with a loop guard, so cycles get caught at load time.

When to use which:

- `based_on` patches are tiny and readable. Prefer them for "I want N+1 of an existing browser version" cases.
- Full describe, mutate, load is mandatory if you need to override a field that's normally inherited (like clearing a sec-ch-ua brand the parent set). Setting a field to its zero value in a `based_on` patch is the same as not setting it, so you have to dump and edit instead.

## Strict registration vs overwrite

`load_preset_from_json` registers the preset by name and silently overwrites any existing custom registration with the same name. Built-in names are blocked, you can't shadow `chrome-latest`.

Want hard collision errors instead of silent overwrites? The Go API has `RegisterStrict`:

```go
p, _ := fingerprint.BuildPreset(spec)
if err := fingerprint.RegisterStrict(p.Name, p); err != nil {
    // name already taken, bail
}
```

Bindings (Python / Node / .NET) only expose the silent-overwrite path right now.

:::tip
This is how you support a Chrome version we haven't shipped yet. Take `chrome-latest` as the base, override the sec-ch-ua brand list and User-Agent, you've got `chrome-N+1` in five minutes. TLS handshake stays correct because Chrome rarely changes the TLS layer between minor versions, and when it does we'll ship a new preset within a release cycle.
:::


---


<!-- source: docs/docs/fingerprinting/custom-ja3.md -->

# Custom JA3

`WithCustomFingerprint` takes a raw JA3 string. The preset still drives HTTP/2 SETTINGS, headers, and the priority table, but the TLS ClientHello gets rebuilt from your JA3 on every connection.

## When to use this

Reach for `WithCustomFingerprint` (JA3 only) when:

- You captured a JA3 from a real browser session and want to mirror that ClientHello exactly.
- You're testing what JA3 hashes look like for a given cipher / extension / curve permutation.
- You only care about TLS, the preset's headers and H2 are fine.

Reach for the [JSON Preset Builder](./json-preset-builder) instead when:

- You need to tweak HTTP/2 SETTINGS along with the JA3.
- You want to change the User-Agent, sec-ch-ua list, or any other HTTP header.
- You want the change saved as a named preset for reuse.

JA3 is a one-liner. The JSON builder's a few more, but worth it the second you need anything beyond TLS.

## JA3 string format

```
TLSVersion,CipherSuites,Extensions,EllipticCurves,PointFormats
```

Five comma-separated lists. Inside each list, values are dash-separated decimal IDs. Chrome 148 example:

```
771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513-21,29-23-24,0
```

- `771`: TLS 1.2 protocol field (everything modern advertises TLS 1.2, then upgrades to 1.3 inside extensions).
- `4865-4866-...`: cipher suite IDs (`TLS_AES_128_GCM_SHA256` is 4865, etc).
- `0-23-65281-...`: TLS extension IDs (0=server_name, 23=session_ticket, 65281=renegotiation_info, etc). Order matters for the JA3 hash, but real Chrome shuffles this list per connection.
- `29-23-24`: supported groups / curves (29=x25519, 23=secp256r1, 24=secp384r1).
- `0`: EC point formats (0=uncompressed).

:::caution
DevTools straight-up won't show you what TLS extensions Chrome put on the wire, and the order it shows is a lie since Chrome shuffles per connection. Capture from `tls.peet.ws` or a passive observer if you want the truth.
:::

## API

`CustomFingerprint` carries the JA3 plus a few uTLS-level extras. Setting `JA3` flips the session into TLS-only mode automatically. Preset HTTP headers stop being applied, so you supply your own per request.

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "context"
    "fmt"
    "io"

    "github.com/sardanioss/httpcloak"
)

func main() {
    s := httpcloak.NewSession("chrome-148-windows",
        httpcloak.WithCustomFingerprint(httpcloak.CustomFingerprint{
            JA3: "771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513-21,29-23-24,0",
            // optional uTLS extras:
            ALPN:                []string{"h2", "http/1.1"},
            SignatureAlgorithms: []string{"ecdsa_secp256r1_sha256", "rsa_pss_rsae_sha256", "rsa_pkcs1_sha256"},
            CertCompression:     []string{"brotli"},
        }),
    )
    defer s.Close()

    resp, _ := s.Get(context.Background(), "https://tls.peet.ws/api/all")
    body, _ := io.ReadAll(resp.Body)
    resp.Body.Close()
    fmt.Println(string(body))
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

with httpcloak.Session(
    preset="chrome-148-windows",
    ja3="771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513-21,29-23-24,0",
    extra_fp={
        "tls_alpn":                 ["h2", "http/1.1"],
        "tls_signature_algorithms": ["ecdsa_secp256r1_sha256", "rsa_pss_rsae_sha256", "rsa_pkcs1_sha256"],
        "tls_cert_compression":     ["brotli"],
    },
) as s:
    r = s.get("https://tls.peet.ws/api/all")
    print(r.json())
```

</TabItem>
<TabItem value="node" label="Node.js">

```js
const { Session } = require("httpcloak");

const s = new Session({
  preset: "chrome-148-windows",
  ja3: "771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513-21,29-23-24,0",
  extraFp: {
    tls_alpn:                 ["h2", "http/1.1"],
    tls_signature_algorithms: ["ecdsa_secp256r1_sha256", "rsa_pss_rsae_sha256", "rsa_pkcs1_sha256"],
    tls_cert_compression:     ["brotli"],
  },
});

const r = await s.get("https://tls.peet.ws/api/all");
console.log(r.json());
s.close();
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var s = new Session(
    preset: "chrome-148-windows",
    ja3: "771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513-21,29-23-24,0",
    extraFp: new Dictionary<string, object> {
        ["tls_alpn"]                 = new[] { "h2", "http/1.1" },
        ["tls_signature_algorithms"] = new[] { "ecdsa_secp256r1_sha256", "rsa_pss_rsae_sha256", "rsa_pkcs1_sha256" },
        ["tls_cert_compression"]     = new[] { "brotli" },
    });

var r = await s.GetAsync("https://tls.peet.ws/api/all");
Console.WriteLine(r.Text);
```

</TabItem>
</Tabs>

## Verification

Send the request, read the response, look at `tls.ja3` and `tls.ja3_hash`. They mirror your input exactly:

```text
INPUT JA3:        771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513-21,29-23-24,0
INPUT akamai:     1:65536;2:0;4:6291456;6:262144|15663105|0|m,a,s,p

OUTPUT ja3:        771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513-21,29-23-24,0
OUTPUT ja3_hash:   cd08e31494f9531f560d64c695473da9
OUTPUT ja4:        t13d1516h2_8daaf6152771_f37e75b10bcc
OUTPUT akamai:     1:65536;2:0;4:6291456;6:262144|15663105|0|m,a,s,p
OUTPUT akamai_hash: 52d84b11737d980aef856699f885ca86
```

The reflected `ja3` is byte-identical to the input. `ja3_hash` is a stable MD5 of that string, so it stays stable across runs (unlike preset Chrome where extensions shuffle). `ja4` differs from the underlying `chrome-148-windows` (`d8a2da3f94cd` vs `f37e75b10bcc`) because we used a different extension list. That's expected and proves the override took effect.

## TLS-only mode is automatic

Setting `JA3` flips the session into TLS-only mode. The preset's HTTP headers go away, the preset's `User-Agent` goes away, and you set everything per request:

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
req := &httpcloak.Request{
    Method: "GET",
    URL:    "https://tls.peet.ws/api/all",
    Headers: map[string][]string{
        "User-Agent":      {"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36"},
        "Accept":          {"text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"},
        "Accept-Language": {"en-US,en;q=0.9"},
    },
}
resp, _ := s.Do(context.Background(), req)
```

</TabItem>
<TabItem value="python" label="Python">

```python
r = s.get(
    "https://tls.peet.ws/api/all",
    headers={
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36",
        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
        "Accept-Language": "en-US,en;q=0.9",
    },
)
```

</TabItem>
</Tabs>

Want JA3 override **and** preset headers? Use the JSON Preset Builder approach instead. Describe the preset, override `tls.ja3` in the JSON, leave `headers` alone, register, send.

## Limitations

- JA3 is deprecated for a reason. Modern anti-bot stacks key on JA4 / peetprint / akamai. Mirroring a Chrome JA3 while inheriting Chrome's H2 SETTINGS gets you the right JA4 / peetprint / akamai too, that's the case shown above. But if your JA3 says one browser and your H2 says another, you're inconsistent and easy to flag.
- Setting `JA3` clears the preset's `client_hello` ID. The session rebuilds a ClientHello from the JA3 every connection. uTLS handles it, but it's lossy compared to a real browser ClientHelloID. JA3 doesn't capture extension data like ALPS, key share groups, application-settings, so the resulting handshake is close-but-not-identical to real Chrome. For byte-exact Chrome bytes, use a preset.
- The `extras` (ALPN, SignatureAlgorithms, CertCompression, PermuteExtensions) are uTLS-specific knobs that ride alongside the JA3. They don't show up inside the JA3 string itself, but they do hit the wire.


---


<!-- source: docs/docs/fingerprinting/akamai-shorthand.md -->

# Akamai Shorthand

The Akamai HTTP/2 fingerprint is a compact string that captures how a client opens an H2 connection. It's the H2 equivalent of a JA3. Anti-bot vendors hash it and check against a known-browser allowlist, same playbook as JA3.

## Format

Four pipe-separated fields:

```
SETTINGS|WINDOW_UPDATE|PRIORITY|PSEUDO_HEADER_ORDER
```

Real Chrome 148:

```
1:65536;2:0;4:6291456;6:262144|15663105|0|m,a,s,p
```

Real Firefox 148:

```
1:65536;2:0;4:131072;5:16384|12517377|0|m,p,a,s
```

Real iOS Safari 18:

```
2:0;4:2097152;3:100;5:16384;9:1|10485760|0|m,s,p,a
```

### SETTINGS

Semicolon-separated `id:value` pairs from the SETTINGS frame. Standard H2 IDs:

| ID | Name | Notes |
|---|---|---|
| 1 | HEADER_TABLE_SIZE | Chrome 65536, Firefox 65536, Safari omits |
| 2 | ENABLE_PUSH | All browsers send 0 |
| 3 | MAX_CONCURRENT_STREAMS | Safari 100, Chrome / Firefox omit |
| 4 | INITIAL_WINDOW_SIZE | Chrome 6291456, Firefox 131072, Safari 2097152 |
| 5 | MAX_FRAME_SIZE | Firefox 16384, Safari 16384, Chrome omits |
| 6 | MAX_HEADER_LIST_SIZE | Chrome 262144, others omit |
| 9 | NO_RFC7540_PRIORITIES | Safari 1, others omit |

Pair order in the string matches wire-frame order. Chrome ships `1, 2, 4, 6`. Firefox: `1, 2, 4, 5`. Safari: `2, 4, 3, 5, 9`. iOS Chrome's slightly different: `2, 3, 4, 9`. Match the order or your akamai hash won't.

### WINDOW_UPDATE

The connection-level WINDOW_UPDATE increment sent right after SETTINGS. Chrome 148: 15663105. Firefox 148: 12517377. Safari 18: 10485760.

### PRIORITY

The H2 PRIORITY frame value. `0` means no PRIORITY frame goes out, which is what Chrome / Firefox / Safari all do as of 2026. They signal priority via the priority HTTP header instead. Older Chrome versions used to send a stream weight here.

### PSEUDO_HEADER_ORDER

Comma-separated single-char identifiers for the order of pseudo-headers in the first HEADERS frame:

- `m` = `:method`
- `a` = `:authority`
- `s` = `:scheme`
- `p` = `:path`

Chrome: `m,a,s,p`. Firefox: `m,p,a,s`. Safari: `m,s,p,a`. iOS Chrome: `m,s,a,p`. Every browser's different and the akamai hash captures it.

## When to override

Use the akamai shorthand override when you want to keep the preset's TLS handshake but tweak the H2 fingerprint. Common cases:

- A target rejects the default Chrome H2 settings but takes a slightly larger initial window.
- You captured an akamai string from a real browser and want to mirror it exactly.
- You're spoofing a Chrome version we haven't shipped yet that bumped a single SETTINGS value.

Need anything beyond H2 SETTINGS, like overriding the priority table, the HPACK header order, or per-request priorities? Hop to the [JSON Preset Builder](./json-preset-builder).

## API

`WithCustomFingerprint` accepts a JA3 and an akamai string. Set one, the other, or both.

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "context"
    "fmt"
    "io"

    "github.com/sardanioss/httpcloak"
)

func main() {
    s := httpcloak.NewSession("chrome-148-windows",
        httpcloak.WithCustomFingerprint(httpcloak.CustomFingerprint{
            // Keep Chrome's TLS, override only H2.
            Akamai: "1:65536;2:0;4:8388608;6:262144|15663105|0|m,a,s,p",
        }),
    )
    defer s.Close()

    resp, _ := s.Get(context.Background(), "https://tls.peet.ws/api/all")
    body, _ := io.ReadAll(resp.Body)
    resp.Body.Close()
    fmt.Println(string(body))
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

with httpcloak.Session(
    preset="chrome-148-windows",
    akamai="1:65536;2:0;4:8388608;6:262144|15663105|0|m,a,s,p",
) as s:
    r = s.get("https://tls.peet.ws/api/all")
    print(r.json())
```

</TabItem>
<TabItem value="node" label="Node.js">

```js
const { Session } = require("httpcloak");

const s = new Session({
  preset: "chrome-148-windows",
  akamai: "1:65536;2:0;4:8388608;6:262144|15663105|0|m,a,s,p",
});

const r = await s.get("https://tls.peet.ws/api/all");
console.log(r.json());
s.close();
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var s = new Session(
    preset: "chrome-148-windows",
    akamai: "1:65536;2:0;4:8388608;6:262144|15663105|0|m,a,s,p");

var r = await s.GetAsync("https://tls.peet.ws/api/all");
Console.WriteLine(r.Text);
```

</TabItem>
</Tabs>

## How shorthand interacts with the preset

When you set `Akamai`, the parser fills in only the slots that appear in your string. Slots you skip keep the preset's value.

- SETTINGS pairs you list overwrite the preset's same-ID values.
- SETTINGS IDs you don't list keep the preset's value.
- A non-empty `WINDOW_UPDATE` overrides, empty keeps the preset.
- A non-zero `PRIORITY` weight enables the H2 PRIORITY frame, zero disables it.
- A non-empty pseudo-header order overrides, empty keeps the preset's.

So you can write a minimal patch and the rest of the H2 state stays correct:

```
1::|||
```

That's a valid akamai string that says "set HEADER_TABLE_SIZE to its default, leave everything else alone". In practice you'll want three or four fields for it to be useful.

## Verifying

Send a request through the override, read `tls.peet.ws`'s `http2.akamai_fingerprint` field. It matches what you sent:

```text
input akamai:           1:65536;2:0;4:8388608;6:262144|15663105|0|m,a,s,p
output akamai (peet):   1:65536;2:0;4:8388608;6:262144|15663105|0|m,a,s,p
output akamai_hash:     <stable MD5 over the string>
```

If the reflected akamai string doesn't match exactly, the parser dropped a field. Most common cause: typo in the SETTINGS pair list. `1:65536;2:0` is fine, `1=65536,2=0` is not. The parser expects colon-separated pairs joined by semicolons.

:::warning
`akamai_fingerprint_hash` is an MD5 of the akamai string with sorted SETTINGS keys. Two strings that differ only in SETTINGS order produce the same hash. So `1:65536;4:6291456` and `4:6291456;1:65536` hash identically even though the strings differ. Wire-level SETTINGS frame order still matters for the H2 fingerprinters that look past the basic akamai hash, those care about the unsorted string. Always send fields in the order the real browser does.
:::


---


<!-- source: docs/docs/fingerprinting/per-resource-priority.md -->

# Per-Resource Priority

Real browsers don't ask for every resource at the same priority. The HTML document is highest, the main stylesheet right behind it, deferred scripts way at the back, images somewhere in the middle. The browser signals this in two places:

- **RFC 7540 stream weights** on the H2 PRIORITY frame attached to HEADERS. Numeric weight 1 to 256.
- **RFC 9218 priority HTTP header** on every H2 / H3 request. Format `u=N, i` where N is urgency 0-7 and `i` is the incremental flag.

Chrome 147+ desktop emits both. The header carries urgency, and the wire weight is derived from urgency by `weight = 256 - (urgency * 73) / 2`. So urgency 0 lands on weight 256, urgency 1 on 220, urgency 2 on 183, urgency 3 on 147 (Chrome's default), urgency 4 on 110.

Anti-bot vendors watch this because a single-weight H2 PRIORITY frame on every request is a dead giveaway. Real Chrome traffic varies the weight per resource type. A bot client that pumps weight 256 (or weight 1) on every request looks nothing like Chrome.

## How httpcloak picks the priority

The transport reads `Sec-Fetch-Dest` from the outgoing request and looks it up in a 14-destination table:

| Sec-Fetch-Dest | Urgency | Incremental | Header sent |
|---|---|---|---|
| `document` | 0 | true  | `u=0, i` |
| `style`    | 0 | false | `u=0` |
| `script`   | 1 | false | `u=1` |
| `image`    | 2 | true  | `u=2, i` |
| `font`     | 1 | false | `u=1` |
| `manifest` | 2 | false | `u=2` |
| `audio`    | 3 | true  | `i` |
| `video`    | 3 | true  | `i` |
| `embed`    | 0 | true  | `u=0, i` |
| `iframe`   | 0 | true  | `u=0, i` |
| `empty`    | 1 | true  | `u=1, i` |
| `object`   | 0 | true  | `u=0, i` |
| `track`    | 3 | true  | `i` |
| `worker`   | 4 | true  | `u=4, i` |

Captured from real Chrome 147+ desktop traffic. Each Chrome / Firefox / Safari preset can override it via the `priority_table` field in the JSON spec. Presets that opt out entirely (Safari, iOS Chrome, iOS Safari, `no_rfc7540_priorities: true`) skip the H2 PRIORITY frame and only emit the priority header.

The wire weight on the H2 HEADERS frame comes from the urgency. So `Sec-Fetch-Dest: image` lands on wire weight 183 (urgency 2), `Sec-Fetch-Dest: style` lands on wire weight 256 (urgency 0). The priority HTTP header carries the same urgency value.

## What you set, what you get

Send three requests with three different `Sec-Fetch-Dest` values:

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "context"
    "io"

    "github.com/sardanioss/httpcloak"
)

func main() {
    s := httpcloak.NewSession("chrome-148-windows")
    defer s.Close()

    for _, dest := range []string{"document", "style", "script", "image", "empty"} {
        req := &httpcloak.Request{
            Method: "GET",
            URL:    "https://tls.peet.ws/api/all",
            Headers: map[string][]string{
                "Sec-Fetch-Dest": {dest},
                "Sec-Fetch-Mode": {"no-cors"},
                "Sec-Fetch-Site": {"same-origin"},
            },
        }
        resp, _ := s.Do(context.Background(), req)
        io.ReadAll(resp.Body)
        resp.Body.Close()
    }
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

with httpcloak.Session(preset="chrome-148-windows") as s:
    for dest in ["document", "style", "script", "image", "empty"]:
        s.get(
            "https://tls.peet.ws/api/all",
            headers={
                "Sec-Fetch-Dest": dest,
                "Sec-Fetch-Mode": "no-cors",
                "Sec-Fetch-Site": "same-origin",
            },
        )
```

</TabItem>
<TabItem value="node" label="Node.js">

```js
const { Session } = require("httpcloak");

const s = new Session({ preset: "chrome-148-windows" });
for (const dest of ["document", "style", "script", "image", "empty"]) {
  await s.get("https://tls.peet.ws/api/all", {
    headers: {
      "Sec-Fetch-Dest": dest,
      "Sec-Fetch-Mode": "no-cors",
      "Sec-Fetch-Site": "same-origin",
    },
  });
}
s.close();
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var s = new Session(preset: "chrome-148-windows");
foreach (var dest in new[] { "document", "style", "script", "image", "empty" }) {
    await s.GetAsync("https://tls.peet.ws/api/all", headers: new Dictionary<string, string> {
        ["Sec-Fetch-Dest"] = dest,
        ["Sec-Fetch-Mode"] = "no-cors",
        ["Sec-Fetch-Site"] = "same-origin",
    });
}
```

</TabItem>
</Tabs>

The `priority` HTTP header reflected back from `tls.peet.ws/api/all` (read from `http2.sent_frames[].headers`) for each value:

```text
Sec-Fetch-Dest=document  -> priority: u=0, i
Sec-Fetch-Dest=style     -> priority: u=0
Sec-Fetch-Dest=script    -> priority: u=1
Sec-Fetch-Dest=image     -> priority: u=2, i
Sec-Fetch-Dest=empty     -> priority: u=1, i
```

The H2 wire stream weight on each HEADERS frame matches: 256 for document, 256 for style, 220 for script, 183 for image, 220 for empty. Real Chrome traffic ships this exact mapping.

:::info
Skip `Sec-Fetch-Dest` and httpcloak's auto-detect sets it for you. Top-level navigations get `document`, XHR / fetch() requests get `empty`, sub-resource loads (image / script / stylesheet tags) keep whatever value you passed. Most sites don't actually check H2 PRIORITY weight per request, but Cloudflare and Akamai do at the H2 / H3 layer. Seeing CF challenges that don't show up in a real browser test? Priority weight mismatch is a likely culprit.
:::

## Capturing the wire-level frame

The HTTP header's easy to verify, `tls.peet.ws/api/all` reflects it. The H2 PRIORITY frame on the wire takes more work. It's piggy-backed inside the HEADERS frame, not a separate frame, and `tls.peet.ws` doesn't expose it. To see the actual wire weight you'll need a Wireshark capture with the TLS keylog file, or one of the H2 fingerprinting test sites like `cf.erika.cool` that decode and reflect the priority frame.

For keylog setup, see [TLS Keylog](../advanced-tls/tls-keylog).

## Overriding the priority table per preset

The default 14-dest table is what every Chrome preset inherits. To override:

1. Describe the preset.
2. Edit the `http2.priority_table` block in the JSON.
3. Load the result back as a custom preset.

Example: clamp every resource to urgency 1 (so all wire weights become 220 and the header is `u=1, i` for incremental, `u=1` for non-incremental):

```json
{
  "version": 1,
  "preset": {
    "name": "chrome-148-flat-priority",
    "based_on": "chrome-148-windows",
    "http2": {
      "priority_table": {
        "document": {"urgency": 1, "incremental": true,  "emit_header": true},
        "style":    {"urgency": 1, "incremental": false, "emit_header": true},
        "script":   {"urgency": 1, "incremental": false, "emit_header": true},
        "image":    {"urgency": 1, "incremental": true,  "emit_header": true},
        "font":     {"urgency": 1, "incremental": false, "emit_header": true},
        "manifest": {"urgency": 1, "incremental": false, "emit_header": true},
        "audio":    {"urgency": 1, "incremental": true,  "emit_header": true},
        "video":    {"urgency": 1, "incremental": true,  "emit_header": true},
        "embed":    {"urgency": 1, "incremental": true,  "emit_header": true},
        "iframe":   {"urgency": 1, "incremental": true,  "emit_header": true},
        "empty":    {"urgency": 1, "incremental": true,  "emit_header": true},
        "object":   {"urgency": 1, "incremental": true,  "emit_header": true},
        "track":    {"urgency": 1, "incremental": true,  "emit_header": true},
        "worker":   {"urgency": 1, "incremental": true,  "emit_header": true}
      }
    }
  }
}
```

Flip `emit_header: false` on any resource where you want the priority HTTP header suppressed but the wire frame still going out. Chrome does this for async / defer scripts, the wire weight stays 147 (urgency 3) but the priority header drops.

Want per-resource priority off entirely on a preset (every request gets the static `stream_weight` from H2 SETTINGS)? Set `priority_table` to an empty object `{}`. The transport falls back to the static weight.

## Per-preset behaviour

| Preset family | RFC 7540 PRIORITY frame | RFC 9218 priority header | Default table |
|---|---|---|---|
| Chrome desktop 147+ (incl. 148) | yes | yes | 14-dest table above |
| Chrome desktop 146 and below | yes (static weight 256, exclusive) | no | n/a |
| Chrome Android 148 | yes | yes | 14-dest table above |
| Firefox 148 | yes | yes (different urgencies, currently uses Chrome table, capture pending) | inherits Chrome table |
| Safari 18 desktop | no | yes | inherits Chrome table for header values; never emits H2 PRIORITY frame |
| iOS Chrome / iOS Safari | no | yes | same |

Build a custom preset and you get the 14-dest table for free unless you override it. Want to opt out of RFC 7540 entirely (no PRIORITY frame on the wire)? Set `http2.no_rfc7540_priorities: true`. The priority HTTP header still fires unless you flip `emit_header: false` on every entry too.

## Why this matters

A constant H2 stream weight on every request is one of the easiest H2 fingerprint giveaways. Cloudflare and Akamai both check it. The priority header check is newer, RFC 9218 only stabilized in 2022, but it's becoming standard at major edge providers. httpcloak handles both as long as your preset is a modern one (Chrome 147+, Firefox 148+, Safari 18+).

Seeing edge-vendor challenges that don't reproduce in a real browser session? Capture the wire-level H2 frames from both, diff the priority weights, check if your preset's `priority_table` matches. Chrome 146 and below ship a constant `weight=256, exclusive=true` on every request. That's our oldest behaviour and modern Cloudflare flags it. For new code, stick with `chrome-latest` or any 147+.


---


<!-- source: docs/docs/connection-lifecycle/index.md -->

# Connection Lifecycle

How a session lives over time. Refresh it, warm it up, switch protocols, save it for later. All here.

## In this section

- [Refresh](./refresh): drop every live connection but keep tickets, like a browser tab reload
- [Warmup](./warmup): multi-hop browser-style warmup before the actual request
- [Protocol Switching](./protocol-switching): switch H1 / H2 / H3 mid-session
- [Session Save and Restore](./session-save-restore): persist the whole session to disk, resume in another process


---


<!-- source: docs/docs/connection-lifecycle/refresh.md -->

# Refresh

`Refresh()` drops every live connection on a session and keeps the rest of your state. Cookies stay in the jar. TLS tickets stay cached. ECH config doesn't move. The preset name and any fingerprint overrides you set are still there. Only the wires get pulled.

Think of it as a browser tab reload. The next request opens fresh TCP or QUIC sockets, the TLS handshake reuses a stored ticket so it goes 0-RTT, and the cookie header on the new connection is byte-identical to the old one. The server can't easily tell a refresh from a brand-new tab on the same browser. That's the whole point.

## Why this exists

Plenty of anti-bot stacks track connection age. Real browsers don't keep a TCP socket open for hours. The keep-alive timer expires, a new connection opens for the next page load. A scraper that holds one connection alive for six hours sticks out like a sore thumb.

`Refresh()` lets you mimic that without throwing away your cookies or tickets. Run it on a timer. Every two or three minutes is fine. Other times you'll want it: a connection's gone stale, the server's misbehaving, or you want to switch protocols (see [Protocol Switching](./protocol-switching)).

## What survives a Refresh

| State | Survives |
| --- | --- |
| Cookies (full jar with metadata) | Yes |
| TLS 1.3 session tickets | Yes |
| TLS 1.2 session IDs | Yes |
| ECH config cache | Yes |
| Preset name and fingerprint overrides | Yes |
| Header order | Yes |
| Proxy config | Yes |
| Cache-validation headers (ETag / Last-Modified) | Yes |
| Live TCP / QUIC connections | No, all closed |
| In-flight requests | No, cancelled |
| Open streaming responses | No, terminated |

If you call `Refresh()` while a streaming download is mid-flight, that stream dies. There's no graceful drain. Hold onto streaming responses and finish them before refreshing.

## The 0-RTT story

Tickets stay in the cache, so the next handshake after `Refresh()` resumes from the previous TLS state. On TLS 1.3 that's a 0-RTT early-data path. On TLS 1.2 it's session-ID resumption (skips the cert roundtrip but doesn't ship request bytes early). The first request after a refresh is dramatically faster than the first request on a brand-new session.

:::tip
Most long-running scrapers should call `Refresh()` every few minutes. Real browsers do too. A connection that's been alive for hours is one of the cheaper signals an anti-bot stack can use against you.
:::

## Code

The shape's the same in every binding: send some requests, call `Refresh()`, send more.



<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
s := httpcloak.NewSession("chrome-latest")
defer s.Close()
ctx := context.Background()

// Round 1 on the original connection.
for i := 0; i < 3; i++ {
	r, _ := s.Get(ctx, "https://tls.peet.ws/api/all")
	fmt.Printf("round1 #%d status=%d\n", i, r.StatusCode)
	r.Close()
}

// Cut the wire. Tickets, cookies, fingerprint state all survive.
s.Refresh()

// Round 2 picks up fresh sockets with TLS resumption.
for i := 0; i < 3; i++ {
	r, _ := s.Get(ctx, "https://tls.peet.ws/api/all")
	fmt.Printf("round2 #%d status=%d\n", i, r.StatusCode)
	r.Close()
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

with httpcloak.Session(preset="chrome-latest") as s:
    # Round 1
    for i in range(3):
        r = s.get("https://tls.peet.ws/api/all")
        print(f"round1 #{i} status={r.status_code}")

    # Cut every connection. Cookies and tickets stay.
    s.refresh()

    # Round 2 picks up clean sockets with TLS resumption.
    for i in range(3):
        r = s.get("https://tls.peet.ws/api/all")
        print(f"round2 #{i} status={r.status_code}")
```

</TabItem>
<TabItem value="nodejs" label="Node.js">

```javascript
const httpcloak = require("httpcloak");

const s = new httpcloak.Session({ preset: "chrome-latest" });
try {
  for (let i = 0; i < 3; i++) {
    const r = await s.get("https://tls.peet.ws/api/all");
    console.log(`round1 #${i} status=${r.statusCode}`);
  }

  s.refresh();

  for (let i = 0; i < 3; i++) {
    const r = await s.get("https://tls.peet.ws/api/all");
    console.log(`round2 #${i} status=${r.statusCode}`);
  }
} finally {
  s.close();
}
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var s = new Session(preset: "chrome-latest");

for (int i = 0; i < 3; i++)
{
    var r = s.Get("https://tls.peet.ws/api/all");
    Console.WriteLine($"round1 #{i} status={r.StatusCode}");
}

s.Refresh();

for (int i = 0; i < 3; i++)
{
    var r = s.Get("https://tls.peet.ws/api/all");
    Console.WriteLine($"round2 #{i} status={r.StatusCode}");
}
```

</TabItem>
</Tabs>

## What's NOT preserved

- **Live connections.** Every TCP socket, every QUIC connection, gone.
- **Active requests.** Anything in flight gets cancelled. The caller sees a context-cancelled or connection-closed error.
- **Streaming responses.** Body reads fail partway. Drain or close streams before refreshing.

Everything else (jar, tickets, ECH, header order, custom JA3, preset, proxy) sticks around. A save before and after `Refresh()` would only differ in the timestamp.

## When NOT to use it

If you want a totally fresh session (no cookies, no tickets, nothing), don't `Refresh()`. Just close and build a new one. `Refresh()` is the "keep my identity, drop my sockets" tool. For "drop my identity" you build a new `NewSession`.

Heads up: after `Refresh()` the session adds `cache-control: max-age=0` to the next request, mimicking a real browser F5. That hits servers like a deliberate cache-bust. If you don't want that signal, use a fresh session instead.

`Refresh()` and `Close()` both use a timeout-bounded close path on QUIC, so a misbehaving H3 peer can't hang the call forever.


---


<!-- source: docs/docs/connection-lifecycle/warmup.md -->

# Warmup

`Warmup(ctx, url)` runs a multi-hop preflight that mimics what a real browser does when you type a URL and hit enter. It loads the HTML, parses out the stylesheets, scripts, images and fonts the page references, then fetches them in parallel with browser-style headers and timing. By the time it returns, your session has cookies, cache validators, TLS tickets and ECH state that look like a tab someone's already used.

## Why bother

Cold-start fingerprinting is real. The very first request from a session has patterns that are hard to fake. Header order's fine, JA3's fine, but the *timing* and the *request graph* are bare. There's no Referer chain. The cookie jar's empty. No cache-validation headers. No subresource fetches. The site never set an `Accept-CH` so you're not sending high-entropy client hints. None of this individually screams bot, but together it paints a "this connection just opened to grab one specific endpoint" picture, which is exactly what bots do.

`Warmup` papers over a lot of that in one call. It:

- Fetches the navigation HTML with proper Sec-Fetch headers.
- Parses the HTML for `<link>`, `<script>`, `<img>` and `<link rel="preload">` references.
- Splits them into priority groups: CSS and fonts first, then scripts, then images.
- Fires each batch concurrently (up to 6 in flight, matching Chrome's per-host H1 connection limit), with realistic 50-300ms gaps between batches.
- Picks up Set-Cookie headers along the way.
- Records `Accept-CH` headers from any host that asks for client hints.
- Caches ETag and Last-Modified so the next request to the same URL ships conditional headers.
- Lets the TLS layer cache session tickets for every host hit.

After `Warmup` returns, your follow-up request looks like the user clicked the next link. Not like the connection just popped into existence.

## Common pattern

Warm up on the home page, then go after the actual endpoint you care about.



<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
s := httpcloak.NewSession("chrome-latest")
defer s.Close()
ctx := context.Background()

// Warm up against the target. Loads HTML, fetches CSS/JS/images,
// grabs whatever cookies the site sets.
if err := s.Warmup(ctx, "https://tls.peet.ws/api/all"); err != nil {
	panic(err)
}
fmt.Printf("cookies: %d\n", len(s.GetCookies()))

// Now the actual request, with tickets, cookies and a believable history
// already in place.
r, _ := s.Get(ctx, "https://tls.peet.ws/api/all")
defer r.Close()
fmt.Printf("status=%d proto=%s\n", r.StatusCode, r.Protocol)
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

with httpcloak.Session(preset="chrome-latest") as s:
    s.warmup("https://tls.peet.ws/api/all", timeout=60000)
    print("cookies:", len(s.get_cookies()))

    r = s.get("https://tls.peet.ws/api/all")
    print(r.status_code, r.headers.get("content-type"))
```

</TabItem>
<TabItem value="nodejs" label="Node.js">

```javascript
const httpcloak = require("httpcloak");

const s = new httpcloak.Session({ preset: "chrome-latest" });
try {
  s.warmup("https://tls.peet.ws/api/all", { timeout: 60000 });
  console.log("cookies:", s.getCookies().length);

  const r = await s.get("https://tls.peet.ws/api/all");
  console.log(r.statusCode);
} finally {
  s.close();
}
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var s = new Session(preset: "chrome-latest");

s.Warmup("https://tls.peet.ws/api/all", timeoutMs: 60000);
Console.WriteLine($"cookies: {s.GetCookies().Length}");

var r = s.Get("https://tls.peet.ws/api/all");
Console.WriteLine($"status={r.StatusCode}");
```

</TabItem>
</Tabs>

## What gets populated

| State after Warmup | Source |
| --- | --- |
| Cookies | Set-Cookie from the page and every subresource |
| TLS session tickets | One per origin touched during warmup |
| ECH config cache | DNS HTTPS records seen during the navigation |
| Cache validators (ETag, Last-Modified) | Per-URL response headers |
| Client hints map | `Accept-CH` headers from any host |
| Header order memory | Already preset-driven, no drift |
| Cookie jar size | Whatever the site sets, often 5-20 |

If the warmed page redirects (301/302), the redirect chain is followed and cookies set along the way all land in the jar with proper domain scoping.

## Edge cases worth knowing

Warmup caps at 50 subresources. Big news sites reference 200+ images on a single page, so we stop at 50 to stop the call running forever. Subresource fetch failures are silent (matches browser behaviour, one broken image shouldn't kill the whole page load). If the navigation URL returns something other than `text/html`, warmup returns nil after the navigation. TLS and cookies still get populated, just no subresource crawl.

The inter-batch delays (50-150ms before scripts, 100-300ms before images) are randomised per call, so back-to-back warmups don't share an identical timing fingerprint.

## When NOT to warmup

- The endpoint you want is on a different origin from any plausible home page. Site A's warmup cookies won't help when you're hitting site B.
- You're in a tight retry loop. Warming up before each retry is overkill.
- The target's a JSON-only API that never sets cookies. The request graph just costs you bandwidth.

In those cases skip `Warmup`, or call it once at session creation and never again.

## Warmup vs Refresh

These aren't interchangeable. `Refresh()` cuts connections without touching state. `Warmup()` does the opposite: leaves connections alone and pumps state into the session. Common pipeline is `Warmup` once at start, then periodic `Refresh()` calls.

`Warmup` respects the context. Cancel it and the call returns the context error after the in-flight batch finishes.


---


<!-- source: docs/docs/connection-lifecycle/protocol-switching.md -->

# Protocol Switching

Sessions can hop between HTTP/1.1, HTTP/2, and HTTP/3 mid-flight. `RefreshWithProtocol("h1" | "h2" | "h3" | "auto")` drops every live connection then re-handshakes on whatever protocol you ask for. The setting sticks, so future plain `Refresh()` calls also use the new protocol until you switch again.

For sessions that should never auto-negotiate in the first place, pass `WithSwitchProtocol("h2")` (or h1 / h3) to `NewSession`. Calling `Refresh()` on that session always lands on the configured protocol.

## Why you'd want this

**Force H2 because the target's H3 is broken.** Some CDNs ship garbage on their HTTP/3 endpoint while H2 works fine. The auto-negotiator picks H3 when it's available, so you'd never know unless you forced H2.

**Force H3 because the target's H2 blocks you.** Common on Cloudflare. The H2 path runs through more middleware where bot detection lives, while H3 often gets lighter filtering, especially on plans where the operator hasn't enabled Bot Management for HTTP/3.

**Test which protocol gets through.** Anti-bot tooling sometimes treats H1, H2 and H3 differently. Lock to one and rerun the same scrape to isolate the variable.

Bonus pattern: warm tickets on H3, then switch to H2 for the workload. The kept ticket means H2 starts from a resumed handshake.

:::info
The auto-negotiation logic (`raceH3H2` internally) races H3 and H2 in parallel and picks whichever wins. Great for latency, unpredictable across runs. Lock to one protocol if you need predictable behaviour, or if you're debugging a site-specific issue and need to know exactly which path the next request will take.
:::

## Code



<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
s := httpcloak.NewSession("chrome-latest")
defer s.Close()
ctx := context.Background()

// Auto-negotiate first. Most likely picks H2.
r, _ := s.Get(ctx, "https://tls.peet.ws/api/all")
fmt.Printf("auto: %s\n", r.Protocol)
r.Close()

// Force H2. Useful when a site's H3 is flaky.
s.RefreshWithProtocol("h2")
r, _ = s.Get(ctx, "https://tls.peet.ws/api/all")
fmt.Printf("h2: %s\n", r.Protocol)
r.Close()

// Force H1. Heavy, slow, sometimes the only path that works.
s.RefreshWithProtocol("h1")
r, _ = s.Get(ctx, "https://tls.peet.ws/api/all")
fmt.Printf("h1: %s\n", r.Protocol)
r.Close()

// Back to auto.
s.RefreshWithProtocol("auto")
```

</TabItem>
<TabItem value="python" label="Python">

```python
with httpcloak.Session(preset="chrome-latest") as s:
    s.get("https://tls.peet.ws/api/all")          # auto
    s.refresh(switch_protocol="h2")
    s.get("https://tls.peet.ws/api/all")          # h2
    s.refresh(switch_protocol="h1")
    s.get("https://tls.peet.ws/api/all")          # h1
```

</TabItem>
<TabItem value="nodejs" label="Node.js">

```javascript
const s = new httpcloak.Session({ preset: "chrome-latest" });
try {
  await s.get("https://tls.peet.ws/api/all");     // auto
  s.refresh("h2");
  await s.get("https://tls.peet.ws/api/all");     // h2
  s.refresh("h1");
  await s.get("https://tls.peet.ws/api/all");     // h1
} finally {
  s.close();
}
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using var s = new Session(preset: "chrome-latest");
s.Get("https://tls.peet.ws/api/all");             // auto
s.Refresh(switchProtocol: "h2");
s.Get("https://tls.peet.ws/api/all");             // h2
s.Refresh(switchProtocol: "h1");
s.Get("https://tls.peet.ws/api/all");             // h1
```

</TabItem>
</Tabs>

## Lock at construction time

To skip auto-negotiation entirely, set the protocol when you build the session. `Refresh()` then always lands on that protocol.

```go
s := httpcloak.NewSession("chrome-latest", httpcloak.WithSwitchProtocol("h2"))
```

Python: `Session(preset=..., switch_protocol="h2")`. Node.js: `new Session({ preset, switchProtocol: "h2" })`. .NET: `new Session(preset, switchProtocol: "h2")`.

There's also `WithForceHTTP1`, `WithForceHTTP2`, `WithForceHTTP3` and `WithDisableHTTP3` that pin the protocol from request one (no `Refresh()` needed). Use those for a session that never speaks anything but the chosen protocol.

## H3 caveats

Three things to know before you `RefreshWithProtocol("h3")`:

- The preset has to support H3. If it doesn't, you get `preset %q does not support HTTP/3` and the switch is refused.
- The host has to actually serve H3. Forcing H3 against a host that doesn't advertise it just times out. There's no automatic fallback when forced.
- H3 over a UDP-blocking proxy is a non-starter. Most corporate networks and plenty of SOCKS5 proxies don't pass UDP. Use `WithForceHTTP2` instead.

If you want H3 sometimes and H2 other times, keep two sessions rather than toggling. Every switch throws away the active connection.

## Protocol values

`RefreshWithProtocol` accepts: `"h1"`/`"http1"`/`"1"` for HTTP/1.1, `"h2"`/`"http2"`/`"2"` for HTTP/2, `"h3"`/`"http3"`/`"3"` for HTTP/3, and `"auto"` (or empty string) to race H3 vs H2 with fallback to H1. Anything else returns an error.


---


<!-- source: docs/docs/connection-lifecycle/session-save-restore.md -->

# Session Save and Restore

`Save(path)` writes your entire session state to disk as JSON. `LoadSession(path)` reads it back into a fully working session. Cookies, TLS session tickets, ECH configs, the preset name, custom fingerprint overrides, proxy config, all of it survives the round trip.

## Why this exists

**Long-running scrapers that survive restarts.** Process crashes, server reboots, deploys. Without persistence the new process starts cold: empty jar, no tickets, fresh handshake to every host. Save on shutdown, load on startup, you're warm again.

**Distributing a warmed-up session.** One process does auth and warmup, saves, then N workers `LoadSession` the same blob. Every worker starts with the same identity and ticket cache. No repeated logins.

**Caching for fast cold-start.** CLI tools that connect once and exit can save to disk so the next invocation isn't a full TLS handshake from scratch.

## File format

It's JSON, UTF-8 text, valid for any JSON parser. Schema version is 5; v3 and v4 files still load fine. Top-level keys: `version`, `created_at`, `updated_at`, `config`, `cookies` (keyed by domain), `tls_sessions` (keyed by `h1:`/`h2:`/`h3:` plus origin) and `ech_configs` (base64-encoded per host).

The file gets written with `0600` permissions because it's carrying live session credentials. Don't commit these to git, don't ship them around in cleartext, treat them like a password. We've seen people upload these to public S3 buckets. Don't do that.

## Code



<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
// Save phase
s := httpcloak.NewSession("chrome-latest")
ctx := context.Background()
r, _ := s.Get(ctx, "https://httpbin.org/cookies/set/my-id/abc123")
r.Close()
if err := s.Save("session.json"); err != nil {
	panic(err)
}
s.Close()

// Load phase, possibly in a different process
s2, err := httpcloak.LoadSession("session.json")
if err != nil {
	panic(err)
}
defer s2.Close()
// The cookie jar already has my-id=abc123 from the previous run.
r2, _ := s2.Get(ctx, "https://httpbin.org/cookies")
defer r2.Close()
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

# In one process:
with httpcloak.Session(preset="chrome-latest") as s:
    r = s.get("https://httpbin.org/cookies/set/my-id/abc123")
    s.save("session.json")

# Later, in a fresh process:
s = httpcloak.Session.load("session.json")
try:
    r = s.get("https://httpbin.org/cookies")
    print(r.text)  # my-id=abc123 still there
finally:
    s.close()
```

</TabItem>
<TabItem value="nodejs" label="Node.js">

```javascript
const httpcloak = require("httpcloak");

// Save phase
{
  const s = new httpcloak.Session({ preset: "chrome-latest" });
  await s.get("https://httpbin.org/cookies/set/my-id/abc123");
  s.save("session.json");
  s.close();
}

// Load phase (could be a totally separate process)
{
  const s = httpcloak.Session.load("session.json");
  const r = await s.get("https://httpbin.org/cookies");
  console.log(await r.text());
  s.close();
}
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

// Save phase
using (var s = new Session(preset: "chrome-latest"))
{
    s.Get("https://httpbin.org/cookies/set/my-id/abc123");
    s.Save("session.json");
}

// Load phase
using (var s = Session.Load("session.json"))
{
    var r = s.Get("https://httpbin.org/cookies");
    Console.WriteLine(r.Text);
}
```

</TabItem>
</Tabs>

## In-memory variant

Don't want a file on disk (writing to a database, shipping bytes across the network, embedding in a config blob)? Use `Marshal()` and `UnmarshalSession()` instead. Same data, returned as a JSON string or byte slice. Every binding has the pair: `Marshal()` / `Unmarshal()` in Go and .NET, `marshal()` / `Session.unmarshal()` in Python and Node.

```go
blob, err := s.Marshal()
// store blob in your DB / cache / wherever

s2, err := httpcloak.UnmarshalSession(blob)
defer s2.Close()
```

## What survives, what doesn't

| State | Survives Save/Load |
| --- | --- |
| Cookies (with domain, path, expiry, samesite, etc) | Yes |
| TLS 1.3 session tickets | Yes |
| TLS 1.2 session IDs | Yes |
| ECH config cache | Yes |
| Preset name and config | Yes |
| Proxy URL | Yes |
| Custom JA3, Akamai fingerprint, header order | Yes |
| Live connections | No, the load creates a fresh transport |
| In-flight requests | No, obvious |
| Cache-validation headers (ETag, Last-Modified) | No, currently per-session memory only |
| The session ID | New one is generated on load |

The cache validators are a known gap. If you lean heavily on If-None-Match to look browser-like, you'll re-fetch full responses on the first hit after a load. Fine for most use cases.

## Ticket expiry caveat

TLS session tickets have a server-controlled lifetime. Most CDNs hand out tickets that expire in 24 hours or less. Save a session today, load it a week later, the tickets are stale. Stale tickets don't error, they just downgrade to a full handshake on the next request. Cookies have their own server-set expiry and the session honours that.

So the further you load from the save, the less benefit you get from the ticket cache. After a couple of days on aggressive CDNs the tickets are mostly dead weight, but the cookie jar is still useful.

## Versioning and safety

The save format is versioned. v5 is current; v3 and v4 still load. A newer file in an older library returns `session file version N is newer than supported version 5`. Use `ValidateSessionFile(path)` (or its binding equivalent) for a cheap pre-load sanity check.

Don't load session files from untrusted sources. The saved blob carries the preset config (proxy URL, ECH domain, fingerprint overrides) which gets applied verbatim. A malicious file could pivot your session in ways you didn't intend. Treat these like config files in your own repo, not user input.


---


<!-- source: docs/docs/connection-lifecycle/fork.md -->

# Fork (Sibling Sessions)

`Fork(n)` hands you N sibling sessions that share cookies and TLS state with the parent but get their own connection pools. Use it when you want a pack of workers hitting a site in parallel under one logged-in identity, without all of them fighting over the same sockets.

Picture it as N browser tabs from the same browser window. Same login. Same cookie jar. Same fingerprint. But each tab opens its own TCP and QUIC connections, so they're not blocking each other.

## What's shared

Forked siblings share the live state that defines who you are:

- **Cookie jar.** Same pointer. A `Set-Cookie` from any sibling lands in the jar that all siblings (and the parent) read from. Login on the parent, fork, every child is logged in.
- **TLS resumption tickets.** The H1, H2 and H3 session caches are shared. First handshake on a fresh fork resumes from a ticket the parent already cached, so it goes 0-RTT.
- **ECH config cache.** Same encrypted-ClientHello blobs, no re-discovery needed.
- **Custom fingerprint state.** Custom JA3, custom H2 settings, custom pseudo-header order, custom TCP fingerprint, header order. The whole fingerprint surface copies over on fork.
- **Cache validators.** ETag and Last-Modified entries snapshot at fork time so siblings start with believable conditional-request headers.

## What's NOT shared

Each fork gets its own:

- **Connection pool.** Brand new transport. New TCP sockets, new QUIC connections. Siblings don't queue behind each other.
- **In-flight requests.** A request on one fork can't block or cancel a request on another.
- **Idle timer and stats.** `LastUsed`, `RequestCount`, idle close timers are per-fork.
- **Key log writer.** Forks don't get the parent's TLS keylog, so they can't double-close it. Set up your own if you need one per fork.

## Common pattern: warm up, log in, fork, scrape

The typical flow is: hit the home page on the parent so cookies and tickets land, log in, fork into N workers, hand each worker a slice of URLs.



<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
s := httpcloak.NewSession("chrome-latest")
defer s.Close()
ctx := context.Background()

// Warm up so the parent has cookies and TLS tickets cached.
if err := s.Warmup(ctx, "https://example.com/"); err != nil {
    panic(err)
}

// Pretend we logged in here. Cookie jar now has the session token.
_, _ = s.Post(ctx, "https://example.com/login", loginBody, nil)

// Fork into 4 siblings. Each gets its own connection pool but
// inherits the cookie jar and TLS tickets from the parent.
forks := s.Fork(4)

urls := []string{
    "https://example.com/page/1",
    "https://example.com/page/2",
    "https://example.com/page/3",
    "https://example.com/page/4",
}

var wg sync.WaitGroup
for i, f := range forks {
    wg.Add(1)
    go func(idx int, fs *httpcloak.Session) {
        defer wg.Done()
        defer fs.Close()
        r, err := fs.Get(ctx, urls[idx])
        if err != nil { return }
        defer r.Close()
        fmt.Printf("worker[%d] status=%d\n", idx, r.StatusCode)
    }(i, f)
}
wg.Wait()
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak
from concurrent.futures import ThreadPoolExecutor

with httpcloak.Session(preset="chrome-latest") as s:
    s.warmup("https://example.com/")
    s.post("https://example.com/login", body=login_body)

    forks = s.fork(4)

    urls = [
        "https://example.com/page/1",
        "https://example.com/page/2",
        "https://example.com/page/3",
        "https://example.com/page/4",
    ]

    def hit(args):
        idx, fs = args
        try:
            r = fs.get(urls[idx])
            print(f"worker[{idx}] status={r.status_code}")
        finally:
            fs.close()

    with ThreadPoolExecutor(max_workers=4) as pool:
        list(pool.map(hit, enumerate(forks)))
```

</TabItem>
<TabItem value="nodejs" label="Node.js">

```javascript
const httpcloak = require("httpcloak");

const s = new httpcloak.Session({ preset: "chrome-latest" });
try {
  await s.warmup("https://example.com/");
  await s.post("https://example.com/login", { body: loginBody });

  const forks = s.fork(4);
  const urls = [
    "https://example.com/page/1",
    "https://example.com/page/2",
    "https://example.com/page/3",
    "https://example.com/page/4",
  ];

  await Promise.all(
    forks.map(async (fs, idx) => {
      try {
        const r = await fs.get(urls[idx]);
        console.log(`worker[${idx}] status=${r.statusCode}`);
      } finally {
        fs.close();
      }
    })
  );
} finally {
  s.close();
}
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var s = new Session(preset: "chrome-latest");
s.Warmup("https://example.com/");
s.Post("https://example.com/login", loginBody);

var forks = s.Fork(4);
var urls = new[] {
    "https://example.com/page/1",
    "https://example.com/page/2",
    "https://example.com/page/3",
    "https://example.com/page/4",
};

await Task.WhenAll(forks.Select((fs, idx) => Task.Run(() => {
    try
    {
        var r = fs.Get(urls[idx]);
        Console.WriteLine($"worker[{idx}] status={r.StatusCode}");
    }
    finally
    {
        fs.Dispose();
    }
})));
```

</TabItem>
</Tabs>

What you'll see: every fork ships requests with the same logged-in cookies, every fork resumes TLS from the parent's tickets, and they all carry an identical JA4 because the fingerprint state copied over. Verified locally with three forks against `tls.peet.ws`, all three returned `t13d1517h2_8daaf6152771_b6f405a00624`.

## Lifecycle

Forks are independent siblings, not children with a leash to the parent.

- Closing the parent doesn't close the forks. They keep working.
- Closing a fork doesn't affect siblings. The shared cookie jar stays alive as long as anyone holds a reference.
- A `Set-Cookie` on any sibling propagates to every other sibling and the parent, instantly. Same pointer.
- Fingerprint state copies once at fork time. If you mutate the parent's header order after forking, the existing forks won't see the change. New forks made after the mutation will.

If you want a fork to have its own cookie jar, you don't fork. Build a fresh `NewSession` instead.

## Fork vs LoadSession

Both clone session state, but they solve different problems:

| | `Fork(n)` | `Save` / `LoadSession` |
| --- | --- | --- |
| Where it works | One process | Across processes, machines, restarts |
| Cookie jar | Shared live pointer | Snapshot at save time |
| TLS tickets | Shared live cache | Snapshot, serialised to disk |
| ECH config | Shared live cache | Snapshot, base64 in JSON |
| Connection pools | Independent per fork | New session, fresh pool |
| Use when | Parallel workers in one binary | Persisting login across restarts |

Fork is for live fan-out. LoadSession is for resuming yesterday's session. They don't compete, and you'll often use both: load a saved session at startup, fork it for parallel work, save the parent again at shutdown.

:::tip
Pick a fork count your network can actually feed. 10-50 is the typical sweet spot. Going past that and you're just building a queue: every fork is racing for the same NIC, same DNS resolver, same upstream socket budget. You'll burn CPU rebuilding TLS handshakes you can't ship fast enough. If the target's running per-IP rate limits, more forks won't help anyway, you'll need real proxies behind each fork.
:::

## Test it yourself

The test below confirms forks share TLS state. Three forks hit `tls.peet.ws/api/all` in parallel, and you should see all three return 200 with the same JA4 hash. If the JA4 differs across forks, fingerprint state didn't copy and that's a bug.

```go
package main

import (
    "context"
    "encoding/json"
    "fmt"
    "io"
    "sync"

    "github.com/sardanioss/httpcloak"
)

func main() {
    s := httpcloak.NewSession("chrome-latest")
    defer s.Close()
    ctx := context.Background()

    // Warm up the parent so it has TLS tickets to share.
    if _, err := s.Get(ctx, "https://tls.peet.ws/api/all"); err != nil {
        panic(err)
    }

    forks := s.Fork(3)
    results := make([]string, 3)

    var wg sync.WaitGroup
    for i, f := range forks {
        wg.Add(1)
        go func(idx int, fs *httpcloak.Session) {
            defer wg.Done()
            defer fs.Close()
            r, err := fs.Get(ctx, "https://tls.peet.ws/api/all")
            if err != nil { return }
            defer r.Close()
            body, _ := io.ReadAll(r.Body)
            var parsed struct {
                TLS struct{ JA4 string `json:"ja4"` } `json:"tls"`
            }
            _ = json.Unmarshal(body, &parsed)
            results[idx] = fmt.Sprintf("status=%d ja4=%s", r.StatusCode, parsed.TLS.JA4)
        }(i, f)
    }
    wg.Wait()

    for i, r := range results {
        fmt.Printf("fork[%d] %s\n", i, r)
    }
}
```

Sample output (Chrome latest, captured 2026-05):

```text
fork[0] status=200 ja4=t13d1517h2_8daaf6152771_b6f405a00624
fork[1] status=200 ja4=t13d1517h2_8daaf6152771_b6f405a00624
fork[2] status=200 ja4=t13d1517h2_8daaf6152771_b6f405a00624
```

Same JA4 across all three. That's proof the TLS fingerprint state actually shares, not just the cookie jar.


---


<!-- source: docs/docs/http-protocols/index.md -->

# HTTP Protocols

H1, H2, H3, and how the lib decides which one to use.

## In this section

- [HTTP/1.1](./http1): when H1's forced, what we negotiate, the rare cases.
- [HTTP/2](./http2): the default for most modern hosts. How SETTINGS and PRIORITY look on the wire.
- [HTTP/3 (QUIC)](./http3-quic): QUIC over UDP, why we ride sardanioss/quic-go, what 0-RTT gets you.
- [Auto-Negotiation](./auto-negotiation): how the lib picks H1 vs H2 vs H3, and how to force one.


---


<!-- source: docs/docs/http-protocols/http1.md -->

# HTTP/1.1

H1 is the fallback. Almost every modern host has moved on to H2 or H3, but H1's still alive for legacy targets, internal services, and any case where ALPN refuses to hand you anything else. httpcloak speaks H1 when it has to, and lets you force it when you want.

## When the lib picks H1

Three paths land you on H1:

- The target's TLS server hello returns `http/1.1` in ALPN. No `h2` advertised, no `h3` Alt-Svc. You get H1.
- The auto-negotiation race finds H2 fails with an `ALPNMismatchError`. The lib reuses that same TLS connection and drops to H1 instead of redoing the handshake.
- You forced it. Either `WithForceHTTP1()` at construction or `RefreshWithProtocol("h1")` mid-session.

Why force it? Two reasons. First, predictable behavior in tests. Second, some boxes in front of the origin (older WAFs, internal mTLS gateways) only speak H1, and you don't want the lib burning RTTs trying H2 first.

## What the H1 transport actually does

Raw TCP, then a uTLS handshake with `http/1.1` as the only ALPN entry, then a plain `Request-Line + headers + CRLF + body`. No multiplexing, no header compression, no priority frames. One request per connection at a time, optionally pipelined with `Connection: keep-alive`.

The transport lives in `transport/http1_transport.go`. The interesting part is what gets fingerprinted.

## What gets fingerprinted at H1

Three layers, top to bottom:

1. **TLS handshake**. Same uTLS-backed ClientHello as H2/H3, just with the ALPN extension rewritten to `["http/1.1"]` only. JA3, JA4, peetprint all still apply. See [TLS fingerprinting](/fingerprinting/what-is-tls-fingerprinting).
2. **Header order**. H1's plain text, so header order is exactly the order of bytes you put on the wire. The preset's header order list drives this. Heads up: DevTools won't show you the real order Chrome sends, so check `tls.peet.ws/api/all` if you need ground truth.
3. **`Connection` header behavior**. `keep-alive` vs `close` vs `Upgrade: websocket` is a real fingerprint signal. Chrome on H1 sends `Connection: keep-alive` by default, and the preset matches.

H1 has no SETTINGS, no WINDOW_UPDATE, no PRIORITY frames. So the Akamai H2 hash is empty when you're on H1, and any check that relies on those signals just can't fire.

:::info H1 is also the websocket upgrade path
WebSocket starts as an H1 request with `Upgrade: websocket`. If you need the upgrade flow, you need H1. See [streaming and upgrades](/connection-lifecycle).
:::

## Code: force H1 and verify

Hit `tls.peet.ws/api/all`, assert `http_version` is `HTTP/1.1`, print the JA3.

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
	"context"
	"encoding/json"
	"fmt"
	"time"

	"github.com/sardanioss/httpcloak"
)

func main() {
	sess := httpcloak.NewSession("chrome-latest",
		httpcloak.WithForceHTTP1(),
		httpcloak.WithSessionTimeout(30*time.Second),
	)
	defer sess.Close()

	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	resp, err := sess.Get(ctx, "https://tls.peet.ws/api/all")
	if err != nil {
		panic(err)
	}
	defer resp.Close()

	body, _ := resp.Bytes()
	var pr struct {
		HTTPVersion string `json:"http_version"`
		TLS         struct {
			JA3Hash string `json:"ja3_hash"`
		} `json:"tls"`
	}
	json.Unmarshal(body, &pr)

	fmt.Println("resp.Protocol:", resp.Protocol)
	fmt.Println("peet http_version:", pr.HTTPVersion)
	fmt.Println("ja3:", pr.TLS.JA3Hash)
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

with httpcloak.Session(preset="chrome-latest", force_http1=True, timeout=30) as sess:
    r = sess.get("https://tls.peet.ws/api/all")
    body = r.json()
    print("resp protocol:", r.http_version)
    print("peet http_version:", body["http_version"])
    print("ja3:", body["tls"]["ja3_hash"])
```

</TabItem>
<TabItem value="node" label="Node.js">

```javascript
const { Session } = require("httpcloak");

(async () => {
  const sess = new Session({ preset: "chrome-latest", forceHttp1: true, timeout: 30 });
  try {
    const r = await sess.get("https://tls.peet.ws/api/all");
    const body = JSON.parse(r.text);
    console.log("resp protocol:", r.httpVersion);
    console.log("peet http_version:", body.http_version);
    console.log("ja3:", body.tls.ja3_hash);
  } finally {
    sess.close();
  }
})();
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;
using System.Text.Json;

using var sess = new Session(preset: "chrome-latest", forceHttp1: true, timeout: 30);
var r = sess.Get("https://tls.peet.ws/api/all");
var body = JsonDocument.Parse(r.Text).RootElement;
Console.WriteLine($"resp protocol: {r.HttpVersion}");
Console.WriteLine($"peet http_version: {body.GetProperty("http_version").GetString()}");
Console.WriteLine($"ja3: {body.GetProperty("tls").GetProperty("ja3_hash").GetString()}");
```

</TabItem>
</Tabs>

Expected output:

```
resp.Protocol: h1
peet http_version: HTTP/1.1
ja3: fe202172df94b322cc6e1e888a464d43
```

`resp.Protocol` is the lib's internal label (`h1`, `h2`, `h3`). `http_version` from `tls.peet.ws` is what the server actually saw, so that's your source of truth.

## Switching mid-session

Warm up on H2, then drop to H1 for one specific endpoint with `RefreshWithProtocol`:

```go
sess := httpcloak.NewSession("chrome-latest")
defer sess.Close()

// First request: default auto-negotiation, will land on H2.
sess.Get(ctx, "https://example.com/")

// Switch to H1 for a legacy upgrade-only endpoint.
sess.RefreshWithProtocol("h1")
sess.Get(ctx, "https://legacy.example.com/api/upgrade")
```

`RefreshWithProtocol` drops the existing connection pool. Cookies and the TLS session ticket cache survive the switch.

:::caution H1 with HTTP proxies
If you're going through an HTTP `CONNECT` proxy and the upstream only speaks H1, the lib's speculative-TLS optimization still applies. The ClientHello rides on the same packet as `CONNECT`, saving you an RTT. See [HTTP CONNECT proxies](/proxies/http-connect).
:::


---


<!-- source: docs/docs/http-protocols/http2.md -->

# HTTP/2

Most modern hosts speak H2 by default. ALPN negotiates `h2`, the lib opens one TCP connection, multiplexes streams over it, compresses headers with HPACK, and frames everything binary instead of plain text. If a target advertises `h2` in its server hello, you land here.

H2 is also where most modern bot products do their heaviest checking. Header order, SETTINGS values, WINDOW_UPDATE deltas, stream priorities, and the pseudo-header order (`:method`, `:authority`, `:scheme`, `:path`) all collapse into the Akamai H2 hash. Get any of those wrong and you stick out.

## httpcloak's H2 stack

The transport is a custom `http2.ClientConn` from the `sardanioss/net` fork. Same surface as Go's stdlib `net/http2`, with the bits you need for fingerprinting bolted on:

- Per-preset SETTINGS frame values (initial window size, max frame size, max concurrent streams, header table size, enable push, max header list size).
- Configurable initial WINDOW_UPDATE on the connection. Real Chrome bumps this right after SETTINGS.
- RFC 7540 stream priority weight + dependency tree per request.
- RFC 9218 priority headers (`priority: u=N, i`) per request, with per-resource-type values driven by the preset's priority table.
- Pseudo-header order matching the preset.

The fork lives in `transport/http2_transport.go`. SETTINGS and priority data live in the preset (see [Akamai shorthand](/fingerprinting/akamai-shorthand)).

## What gets fingerprinted at H2

Six signals, roughly in the order an Akamai-style fingerprinter parses them:

1. **SETTINGS frame**. Values in your first SETTINGS, in the order you send them. Chrome ships `HEADER_TABLE_SIZE=65536`, `ENABLE_PUSH=0`, `INITIAL_WINDOW_SIZE=6291456`, `MAX_HEADER_LIST_SIZE=262144`. Different browsers ship different values and different orders.
2. **WINDOW_UPDATE delta**. Right after SETTINGS, Chrome fires a connection-level `WINDOW_UPDATE` of `15663105` bytes. The exact number's a fingerprint signal.
3. **Stream priorities (RFC 7540)**. The classic priority-frame format with weight and dependency. Deprecated by spec, but Chrome still emits them for back-compat, and fingerprinters still check.
4. **Priority headers (RFC 9218)**. The newer `priority: u=N, i` HTTP header. httpcloak picks the value per resource type via the priority table. See [per-resource priority](/fingerprinting/per-resource-priority).
5. **Pseudo-header order**. `:method`, `:authority`, `:scheme`, `:path`. Chrome's order is `m,a,s,p`. Some libs ship `m,s,p,a` or `m,p,s,a` and that one mistake is enough to flag them.
6. **Regular header order**. Same as H1, but on H2 the order survives HPACK and stays visible to anyone parsing the wire. Custom headers you add are part of this.

The Akamai H2 hash collapses items 1, 2, 3, and 5 into one short string. See [Akamai shorthand](/fingerprinting/akamai-shorthand) for the exact format.

:::info RFC 7540 vs RFC 9218 priorities
RFC 7540 stream priorities (weight + dependency tree) are deprecated in favor of RFC 9218 priority headers. httpcloak ships both, so you stay compatible with old and new servers. Real Chrome 100+ also ships both, same reason. If you're rolling your own preset, don't drop either.
:::

## Code: capture the H2 fingerprint

Default `chrome-latest` session against `tls.peet.ws/api/all`. The response shows `http_version=h2` plus the H2-specific fields the fingerprinter pulled out.

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
	"context"
	"encoding/json"
	"fmt"
	"time"

	"github.com/sardanioss/httpcloak"
)

func main() {
	sess := httpcloak.NewSession("chrome-latest",
		httpcloak.WithSessionTimeout(30*time.Second),
	)
	defer sess.Close()

	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	resp, err := sess.Get(ctx, "https://tls.peet.ws/api/all")
	if err != nil {
		panic(err)
	}
	defer resp.Close()

	body, _ := resp.Bytes()
	var pr struct {
		HTTPVersion string `json:"http_version"`
		HTTP2       struct {
			AkamaiFingerprint     string `json:"akamai_fingerprint"`
			AkamaiFingerprintHash string `json:"akamai_fingerprint_hash"`
		} `json:"http2"`
	}
	json.Unmarshal(body, &pr)

	fmt.Println("resp.Protocol:", resp.Protocol)
	fmt.Println("http_version:", pr.HTTPVersion)
	fmt.Println("akamai_text:", pr.HTTP2.AkamaiFingerprint)
	fmt.Println("akamai_hash:", pr.HTTP2.AkamaiFingerprintHash)
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

with httpcloak.Session(preset="chrome-latest", timeout=30) as sess:
    r = sess.get("https://tls.peet.ws/api/all")
    body = r.json()
    print("resp protocol:", r.http_version)
    print("http_version:", body["http_version"])
    print("akamai_text:", body["http2"]["akamai_fingerprint"])
    print("akamai_hash:", body["http2"]["akamai_fingerprint_hash"])
```

</TabItem>
<TabItem value="node" label="Node.js">

```javascript
const { Session } = require("httpcloak");

(async () => {
  const sess = new Session({ preset: "chrome-latest", timeout: 30 });
  try {
    const r = await sess.get("https://tls.peet.ws/api/all");
    const body = JSON.parse(r.text);
    console.log("resp protocol:", r.httpVersion);
    console.log("http_version:", body.http_version);
    console.log("akamai_text:", body.http2.akamai_fingerprint);
    console.log("akamai_hash:", body.http2.akamai_fingerprint_hash);
  } finally {
    sess.close();
  }
})();
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;
using System.Text.Json;

using var sess = new Session(preset: "chrome-latest", timeout: 30);
var r = sess.Get("https://tls.peet.ws/api/all");
var body = JsonDocument.Parse(r.Text).RootElement;
Console.WriteLine($"resp protocol: {r.HttpVersion}");
Console.WriteLine($"http_version: {body.GetProperty("http_version").GetString()}");
var h2 = body.GetProperty("http2");
Console.WriteLine($"akamai_text: {h2.GetProperty("akamai_fingerprint").GetString()}");
Console.WriteLine($"akamai_hash: {h2.GetProperty("akamai_fingerprint_hash").GetString()}");
```

</TabItem>
</Tabs>

Expected output:

```
resp.Protocol: h2
http_version: h2
akamai_text: 1:65536;2:0;4:6291456;6:262144|15663105|0|m,a,s,p
akamai_hash: 52d84b11737d980aef856699f885ca86
```

Reading that `akamai_text` left to right:

- `1:65536;2:0;4:6291456;6:262144` is the SETTINGS frame. Setting 1 (`HEADER_TABLE_SIZE`), 2 (`ENABLE_PUSH`), 4 (`INITIAL_WINDOW_SIZE`), 6 (`MAX_HEADER_LIST_SIZE`).
- `15663105` is the connection-level `WINDOW_UPDATE` increment Chrome sends right after SETTINGS.
- `0` is the priority-frame block. Empty on chrome-148+ because Chrome stopped emitting RFC 7540 priority frames on streams it owns. Older presets put `1:1:0:256,...` here.
- `m,a,s,p` is the pseudo-header order: `:method`, `:authority`, `:scheme`, `:path`.

The hash at the end is just MD5 of the text. Match it against a known-good Chrome capture and you're good.

## Forcing H2

The lib picks H2 on its own most of the time. Force it when you want predictable behavior in tests, or when the target's H3 is busted:

```go
sess := httpcloak.NewSession("chrome-latest", httpcloak.WithForceHTTP2())
```

If you just want to kill H3 but keep the H2/H1 fallback chain, use `WithDisableHTTP3()` instead. That's what most production code actually wants, because it covers servers that mis-advertise `h3` in Alt-Svc.

```go
sess := httpcloak.NewSession("chrome-latest", httpcloak.WithDisableHTTP3())
```

## Switching mid-session

Same shape as H1. `RefreshWithProtocol("h2")` drops the pool and forces H2 from the next request on. Cookies and TLS tickets survive.

:::tip Diff your H2 fingerprint
After every preset change, hit `tls.peet.ws/api/all` and diff the `akamai_fingerprint` text against a real Chrome capture. The hash is fine for a quick sanity check, but the text shows you exactly which knob drifted. Field order inside the SETTINGS block is part of the fingerprint, so a swap of `4` and `6` won't always show up in the hash if both values stayed the same.
:::


---


<!-- source: docs/docs/http-protocols/http3-quic.md -->

# HTTP/3 (QUIC)

H3 is H2 semantics riding on QUIC, which is TLS 1.3 plus a streaming transport built on UDP. The framing looks like H2 (streams, frames, HPACK-shaped header compression via QPACK), but the transport underneath is a different beast. No TCP, no head-of-line blocking when one stream's packet drops, faster cold start with 0-RTT, and connection migration when your IP shifts.

httpcloak speaks H3 when the target advertises it (Alt-Svc on a previous H2 response, or a DNS HTTPS record) or when you force it.

## httpcloak's H3 stack

The H3 transport rides `sardanioss/quic-go`, a fork of upstream `quic-go` with the fingerprinting hooks we need plus our own bug fixes. Currently pinned at v1.2.25 (the bump that shipped the PRIORITY_UPDATE fix below).

What our fork adds on top of upstream:

- Configurable QUIC transport parameters in the INITIAL packet (idle timeout, max UDP payload, initial max data, initial max streams, etc).
- Configurable QUIC version order in the INITIAL packet's version-negotiation list.
- HTTP/3 SETTINGS frame values that line up with the H2 preset.
- HTTP/3 PRIORITY_UPDATE frames on the control stream, with the prioritized stream ID and priority field value matching real Chrome.
- 0-RTT session resumption that actually preserves the early-data flag across reconnects.

The transport lives in `transport/http3_transport.go` and uses `http3.Transport` from the fork.

## ALPN and discovery

The H3 ALPN ID is `h3`. The lib gets there one of two ways:

- **Alt-Svc**. The H2 response carried `alt-svc: h3=":443"; ma=86400`. The lib remembers that for the cache window, and the next request to that host can race H3 against H2. See [auto-negotiation](./auto-negotiation).
- **DNS HTTPS RR**. The HTTPS DNS record (RFC 9460) advertises ALPN values directly. If the resolver returns one with `h3` in it, the lib can try H3 on the first request without needing a previous H2 hit. Whether HTTPS RR fires depends on your DNS config (see `dns/`).

Force H3 on a host that doesn't actually serve it and you'll hit a QUIC handshake timeout. Default budget is around 5 seconds before the lib bails.

## 0-RTT resumption

If the lib has a TLS session ticket from a previous successful handshake to the same host, it can attach the first request as 0-RTT data on the same UDP packet as the QUIC INITIAL. Saves a full round trip on the cold path.

The ticket cache is per-session by default. Want it to survive process restarts? Plug in a `SessionCacheBackend` via `WithSessionCache(...)`.

0-RTT comes with the usual replay caveat. The server decides what's safe (RFC 9001 says only idempotent methods should ride 0-RTT). httpcloak just sends what you hand it, so make sure your first request after a fresh session is a `GET` or some other safe method.

## What gets fingerprinted at H3

Stacked from packet level up:

1. **QUIC INITIAL packet**. The first UDP packet carries the QUIC version, version-negotiation list, source/destination connection IDs, and the TLS 1.3 ClientHello inside the CRYPTO frame. The transport parameters in the ClientHello extension are part of the fingerprint too.
2. **TLS 1.3 ClientHello**. Same uTLS-backed handshake as H2, with `h3` in ALPN.
3. **HTTP/3 SETTINGS frame**. Same role as H2 SETTINGS but different setting IDs. Sent on the control stream (stream ID 2 from client).
4. **PRIORITY_UPDATE frames**. RFC 9218 priority signaling at the H3 layer. Real Chrome emits one PRIORITY_UPDATE on the control stream per request, referencing the request's actual stream ID.
5. **Pseudo-header order, header order, QPACK encoding**. Same surface as H2, just encoded with QPACK instead of HPACK.

The H3 fingerprint at `tls.peet.ws/api/all` lands as `h3_text` and `h3_hash`. It rolls up SETTINGS values, the PRIORITY_UPDATE wire bytes, QPACK literal hints, and the pseudo-header order.

## Recent fix: PRIORITY_UPDATE on the control stream (1.6.6)

Worth calling out, because this was a long-standing bug only visible on H3-aware fingerprinters.

Before 1.6.6:

- The PRIORITY_UPDATE frame's `prioritized_stream_id` was hardcoded to `0`.
- The priority field value was hardcoded to `"u=0, i"`.

Real Chrome never emits PRIORITY_UPDATE for stream 0. Chrome's 0-RTT probe burns that bidi ID, so the first real request lands on stream 4. Fingerprinters that parsed RFC 9218 silently dropped our PRIORITY_UPDATE as malformed, and the diff against real Chrome failed.

After 1.6.6:

- PRIORITY_UPDATE goes out lazily, right before the first request's HEADERS frame.
- `prioritized_stream_id` matches the actual stream the request is on.
- The priority field value comes from the request's `priority:` header, which the priority table sets per resource type.

Net wire change: `h3_text` now contains the visible `|984832|` token between `GREASE` and the pseudo-order, matching real Chrome 147+ H3 captures byte for byte.

## Code: force H3 and verify

`tls.peet.ws` advertises `h3` in Alt-Svc, but its UDP/443 port is closed in practice. Use a host that actually serves H3, like `www.cloudflare.com`, when you want a live H3 check.

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
	"context"
	"fmt"
	"time"

	"github.com/sardanioss/httpcloak"
)

func main() {
	sess := httpcloak.NewSession("chrome-latest",
		httpcloak.WithForceHTTP3(),
		httpcloak.WithSessionTimeout(30*time.Second),
	)
	defer sess.Close()

	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	resp, err := sess.Get(ctx, "https://www.cloudflare.com/")
	if err != nil {
		panic(err)
	}
	defer resp.Close()

	fmt.Println("resp.Protocol:", resp.Protocol) // h3
	fmt.Println("status:", resp.StatusCode)
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

with httpcloak.Session(preset="chrome-latest", force_http3=True, timeout=30) as sess:
    r = sess.get("https://www.cloudflare.com/")
    print("resp protocol:", r.http_version)
    print("status:", r.status_code)
```

</TabItem>
<TabItem value="node" label="Node.js">

```javascript
const { Session } = require("httpcloak");

(async () => {
  const sess = new Session({ preset: "chrome-latest", forceHttp3: true, timeout: 30 });
  try {
    const r = await sess.get("https://www.cloudflare.com/");
    console.log("resp protocol:", r.httpVersion);
    console.log("status:", r.statusCode);
  } finally {
    sess.close();
  }
})();
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var sess = new Session(preset: "chrome-latest", forceHttp3: true, timeout: 30);
var r = sess.Get("https://www.cloudflare.com/");
Console.WriteLine($"resp protocol: {r.HttpVersion}");
Console.WriteLine($"status: {r.StatusCode}");
```

</TabItem>
</Tabs>

Expected output:

```
resp.Protocol: h3
status: 200
```

For an H3 host that returns the full peet-style fingerprint payload, swap in your own H3 reflector or one of the `cf.*` reflectors that returns JSON.

## H3 over proxies: read this before debugging

A lot of SOCKS5 proxies don't support `UDP_ASSOCIATE`, the SOCKS5 verb for tunneling UDP. Without it, H3 over SOCKS5 just doesn't work because QUIC needs UDP end to end. Plain HTTP `CONNECT` proxies are TCP-only by definition, so they can't carry H3 either.

:::warning H3 needs a UDP-capable proxy
For H3 over a proxy you need either a SOCKS5 server that supports `UDP_ASSOCIATE` ([SOCKS5 UDP](/proxies/socks5-udp)) or a MASQUE proxy ([MASQUE](/proxies/masque)). HTTP `CONNECT` won't work because it doesn't carry UDP. Stuck on a TCP-only proxy and want H3-shaped fingerprints? You can't have them. Move to MASQUE or accept H2 as your wire.
:::

If the lib spots that the configured proxy can't carry UDP, forced-H3 requests fail fast with `HTTP/3 requires a SOCKS5 or MASQUE proxy (current proxy does not support UDP)`. Auto-negotiation just falls back to H2/H1 silently in that case.

## Knobs you might want

- `WithQuicIdleTimeout(d)` overrides the QUIC idle timeout. Default's conservative.
- `WithKeyLogFile(path)` writes TLS keys for Wireshark decryption. Works for H3 too, both the QUIC handshake and the inner application data.
- `WithSessionCache(...)` plugs in a persistent ticket store so 0-RTT survives process restarts.

## Switching mid-session

Same shape as H1 and H2:

```go
sess := httpcloak.NewSession("chrome-latest")
defer sess.Close()
sess.Get(ctx, "https://example.com/")          // auto-negotiated H2
sess.RefreshWithProtocol("h3")
sess.Get(ctx, "https://www.cloudflare.com/")   // forced H3 from here
```

`RefreshWithProtocol("h3")` refuses if the active preset doesn't support H3 (some legacy presets are H2-only on purpose).


---


<!-- source: docs/docs/http-protocols/auto-negotiation.md -->

# Auto-Negotiation

By default you don't pick a protocol. The lib does. It races H3 and H2 in parallel, takes whichever connects first, and falls back to H1 only if H2 actually fails ALPN. Call it the "I don't care, just give me Chrome-shaped bytes on the right protocol" mode.

## What `doAuto` actually does

The dispatcher in `transport/transport.go` is one function called `doAuto`. Steps:

1. Look up the host in the `protocolSupport` cache. If we already learned this host's best protocol from a prior request, skip the race and just dial that.
2. Otherwise fire two goroutines: one dials H3 over UDP via QUIC, the other dials H2 over TCP+TLS.
3. Take the first success. Cancel the loser.
4. If H2's TLS handshake came back with `http/1.1` in ALPN (`ALPNMismatchError`), reuse that same TLS connection for an H1 request. No second handshake.
5. If both attempts time out (default budget around 6 seconds), the lib tries H2 directly as a last resort, then H1.
6. Cache the winning protocol in `protocolSupport[host]` so the next request to the same host skips the race.

The race lives in `raceH3H2`. It exists to dodge the 5-second wall you'd hit if you tried H3 first and the network silently swallowed UDP/443. With the race, H2 fills in the moment TCP comes back, usually under 200ms.

## How H3 gets discovered

Two ways:

- **Alt-Svc**. The first H2 response from a host carries `alt-svc: h3=":443"; ma=86400`. The lib parses it, the `protocolSupport` cache learns "this host speaks H3", and the next request can race H3 against H2. H3 usually wins because the QUIC handshake finishes in fewer round trips.
- **DNS HTTPS RR**. RFC 9460 HTTPS records advertise ALPN values directly in DNS. If the resolver returns one with `h3` in it, the lib can skip the H2 detour entirely. Whether this fires depends on your DNS config in `dns/`.

If neither hint mentions H3, the race still includes H3 on the first try, but H3's handshake is unlikely to land first.

## When H1 actually shows up

H1's the boring fallback. You land here when:

- The TLS server hello returns `http/1.1` in ALPN. The `ALPNMismatchError` path reuses the connection.
- Both H3 and H2 attempts fail outright and the lib has to try H1 on a fresh TCP connection.
- You forced it with `WithForceHTTP1()` or `RefreshWithProtocol("h1")`.

For normal browsing-shaped traffic against modern hosts, H1 should be rare.

## Forcing one protocol

Three options at session construction:

- `WithForceHTTP1()`: lock to H1. Skips H2/H3 entirely.
- `WithForceHTTP2()`: lock to H2. Skips H3 and won't fall back to H1 unless ALPN drags it there.
- `WithForceHTTP3()`: lock to H3. Hard fails if the host doesn't speak H3.

Plus one for the common middle case:

- `WithDisableHTTP3()`: keep auto-negotiation but never try H3. Basically the "old-school client" knob.

For mid-session changes:

- `RefreshWithProtocol("h1" | "h2" | "h3")` drops the connection pool and forces the named protocol from the next request.
- `WithSwitchProtocol("h2")` at construction time queues a protocol switch on the next `Refresh()`. Handy for the warmup-on-H3, serve-on-H2 pattern when you want to share a TLS ticket across protocols.

## Why force one

A handful of real reasons:

- **Tests**. You want predictable behavior. Auto-negotiation can land on H2 or H3 depending on what the target's edge feels like advertising today.
- **Broken H3 at the target**. Some hosts advertise `h3` in Alt-Svc but their UDP port is firewalled, or the QUIC stack's busted. Auto-negotiation handles this by losing the race, but if you're slamming the same host millions of times you might as well skip the H3 attempt entirely with `WithDisableHTTP3()`.
- **Policy**. Your network only allows TCP/443. Force H2.
- **Fingerprint surface**. You specifically want to test the H3 fingerprint your preset emits. Force H3 against a known H3-capable target.

## Code: default vs forced

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
	"context"
	"fmt"
	"time"

	"github.com/sardanioss/httpcloak"
)

func hit(label string, opts ...httpcloak.SessionOption) {
	sess := httpcloak.NewSession("chrome-latest", opts...)
	defer sess.Close()

	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	resp, err := sess.Get(ctx, "https://tls.peet.ws/api/all")
	if err != nil {
		fmt.Printf("[%s] err: %v\n", label, err)
		return
	}
	defer resp.Close()
	fmt.Printf("[%s] resp.Protocol=%s status=%d\n", label, resp.Protocol, resp.StatusCode)
}

func main() {
	hit("default")                              // h2 against tls.peet
	hit("force-h2", httpcloak.WithForceHTTP2()) // h2
	hit("disable-h3", httpcloak.WithDisableHTTP3())
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

def hit(label, **kwargs):
    with httpcloak.Session(preset="chrome-latest", timeout=30, **kwargs) as sess:
        r = sess.get("https://tls.peet.ws/api/all")
        print(f"[{label}] protocol={r.http_version} status={r.status_code}")

hit("default")
hit("force-h2", force_http2=True)
hit("disable-h3", disable_http3=True)
```

</TabItem>
<TabItem value="node" label="Node.js">

```javascript
const { Session } = require("httpcloak");

async function hit(label, opts) {
  const sess = new Session({ preset: "chrome-latest", timeout: 30, ...opts });
  try {
    const r = await sess.get("https://tls.peet.ws/api/all");
    console.log(`[${label}] protocol=${r.httpVersion} status=${r.statusCode}`);
  } finally {
    sess.close();
  }
}

(async () => {
  await hit("default", {});
  await hit("force-h2", { forceHttp2: true });
  await hit("disable-h3", { disableHttp3: true });
})();
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

void Hit(string label, Action<SessionOptions>? configure = null) {
    var opts = new SessionOptions { Preset = "chrome-latest", Timeout = 30 };
    configure?.Invoke(opts);
    using var sess = new Session(opts);
    var r = sess.Get("https://tls.peet.ws/api/all");
    Console.WriteLine($"[{label}] protocol={r.HttpVersion} status={r.StatusCode}");
}

Hit("default");
Hit("force-h2", o => o.ForceHttp2 = true);
Hit("disable-h3", o => o.DisableHttp3 = true);
```

</TabItem>
</Tabs>

Expected output, hitting `tls.peet.ws`:

```
[default] resp.Protocol=h2 status=200
[force-h2] resp.Protocol=h2 status=200
[disable-h3] resp.Protocol=h2 status=200
```

All three land on H2 because tls.peet.ws's UDP/443 port is closed in practice, so the lib never gets an H3 path to win the race.

## Per-host learning

Once a request to `example.com` comes back on H3, the lib caches that fact. The next request to `example.com` skips the race and dials H3 directly. The cache is keyed by hostname (no port, no path) and lives in `protocolSupport`. If the host stops responding on H3 later, you'll need to recreate the session or call `RefreshWithProtocol("h2")` to evict the cached choice.

There's a planned `BrokenAltSvc` circuit breaker that suppresses H3 attempts after repeated failures to a specific host without forcing a restart. Tracked in our internal docs, not landed yet.

:::tip Auto vs forced for production
For production traffic where you don't care which protocol you land on, leave it auto. The lib handles Alt-Svc, the H3 race, and ALPN fallback for you. For automation aimed at specific bot products, force the protocol your preset is shaped for. Most `chrome-148` presets are tuned for H2 and H3 side by side, but if you're matching against a capture that was specifically H3, force H3 so you don't accidentally diff an H2 fingerprint against an H3 capture.
:::

## See also

- [HTTP/1.1](./http1) for what H1 negotiates and when it's the right call.
- [HTTP/2](./http2) for the SETTINGS, WINDOW_UPDATE, and Akamai signals on H2.
- [HTTP/3 (QUIC)](./http3-quic) for the QUIC INITIAL packet and PRIORITY_UPDATE.
- [Akamai shorthand](/fingerprinting/akamai-shorthand) for tweaking H2 fingerprint values without rebuilding a preset.


---


<!-- source: docs/docs/advanced-tls/index.md -->

# Advanced TLS

The deeper TLS knobs. ECH, speculative CONNECT, keylogging for Wireshark, and domain fronting. You won't reach for these every day, but when you need them, you really need them.

## In this section

- [ECH](./ech): Encrypted Client Hello. On by default, opt out with `WithDisableECH`.
- [Speculative TLS](./speculative-tls): pipeline CONNECT and ClientHello, save one RTT on every proxied dial.
- [TLS Keylog](./tls-keylog): dump `SSLKEYLOGFILE` for Wireshark when you need to see what's actually on the wire.
- [Domain Fronting](./domain-fronting): when SNI isn't Host, here's how to wire it up.


---


<!-- source: docs/docs/advanced-tls/ech.md -->

# ECH

ECH stands for Encrypted Client Hello. Without it, the SNI in your TLS handshake sits in plaintext on the wire. Your ISP, a corporate middlebox, a curious nation-state, anyone watching can read which hostname you're hitting even though the rest of the handshake is encrypted. ECH wraps the real ClientHello inside a second handshake aimed at an ECH provider's outer name, so all an observer sees is something generic like `cloudflare-ech.com`. The actual target stays hidden inside.

httpcloak ships with ECH on by default. If the target host publishes an ECH config in its DNS HTTPS RR, the lib grabs it, drops the ECH extension into the ClientHello, and the inner SNI gets encrypted. If the host doesn't publish one, you fall back to a plain ClientHello and the request still goes through. Nothing breaks just because ECH isn't available.

:::info
ECH is still rolling out. Plenty of sites haven't published HTTPS RR records yet, so the fallback kicks in often. No failure when the record's missing, just a normal SNI on the wire.
:::

## How httpcloak picks the ECH config

The order's pretty simple:

1. If you set `WithECHFrom(domain)`, fetch the HTTPS RR for that alternate domain and use its ECH config.
2. Otherwise, fetch the HTTPS RR for the target host and use whatever it publishes.
3. If nothing's there, send a normal ClientHello with plaintext SNI.

For H3, this lookup runs in parallel with the A/AAAA DNS resolution, so it adds basically zero latency on the first connection. For H2, the ECH lookup only runs when you opt in via `WithECHFrom`. (See the H2 caveat below.)

## Default session, ECH on



<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "context"
    "fmt"

    "github.com/sardanioss/httpcloak"
)

func main() {
    s := httpcloak.NewSession("chrome-latest")
    defer s.Close()

    resp, err := s.Get(context.Background(), "https://example.com/")
    if err != nil {
        panic(err)
    }
    fmt.Println(resp.StatusCode, resp.Protocol)
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

with httpcloak.Session(preset="chrome-latest") as s:
    r = s.get("https://example.com/")
    print(r.status_code, r.protocol)
```

</TabItem>
<TabItem value="node" label="Node.js">

```js
const { Session } = require('httpcloak');

const s = new Session({ preset: 'chrome-latest' });
const r = await s.get('https://example.com/');
console.log(r.statusCode, r.protocol);
s.close();
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var s = new Session(preset: "chrome-latest");
var r = await s.GetAsync("https://example.com/");
Console.WriteLine($"{r.StatusCode} {r.Protocol}");
```

</TabItem>
</Tabs>

That's the whole opt-in. No flag needed. If `example.com` published an ECH config (it doesn't, today), you'd get an encrypted SNI. Since it doesn't, you get a plain handshake and the request still works.

## Turning ECH off

`WithDisableECH` kills the DNS HTTPS RR lookup entirely. The session won't include the ECH extension in the ClientHello, won't run the parallel HTTPS RR fetch, won't even try. Handy when you want to shave a few ms off the first connection in a known-no-ECH environment, or when you're debugging and want a plain SNI to stare at.

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
s := httpcloak.NewSession("chrome-latest",
    httpcloak.WithDisableECH(),
)
```

</TabItem>
<TabItem value="python" label="Python">

```python
with httpcloak.Session(preset="chrome-latest", disable_ech=True) as s:
    ...
```

</TabItem>
<TabItem value="node" label="Node.js">

```js
const s = new Session({ preset: 'chrome-latest', disableEch: true });
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using var s = new Session(preset: "chrome-latest", disableEch: true);
```

</TabItem>
</Tabs>

There's no security hit from turning ECH off. You just lose the SNI privacy bit. Everything else about the handshake is identical.

## Borrowing an ECH config from another domain

Some hosts don't publish their own HTTPS RR but they sit behind a CDN that does. Cloudflare in particular runs a public ECH endpoint at `cloudflare-ech.com`. Any Cloudflare-proxied origin can be reached using that ECH config, because the outer handshake terminates at Cloudflare's edge regardless of which inner hostname you're after.

`WithECHFrom(domain)` tells the lib to fetch the HTTPS RR from `domain` instead of from the target host. The fetched config gets used for any request on that session.

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
s := httpcloak.NewSession("chrome-latest",
    httpcloak.WithECHFrom("cloudflare-ech.com"),
)
defer s.Close()

resp, _ := s.Get(context.Background(), "https://example.com/")
fmt.Println(resp.StatusCode)
```

</TabItem>
<TabItem value="python" label="Python">

```python
with httpcloak.Session(
    preset="chrome-latest",
    ech_from="cloudflare-ech.com",
) as s:
    r = s.get("https://example.com/")
    print(r.status_code)
```

</TabItem>
<TabItem value="node" label="Node.js">

```js
const s = new Session({
  preset: 'chrome-latest',
  echFrom: 'cloudflare-ech.com',
});
const r = await s.get('https://example.com/');
console.log(r.statusCode);
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using var s = new Session(
    preset: "chrome-latest",
    echFrom: "cloudflare-ech.com");

var r = await s.GetAsync("https://example.com/");
Console.WriteLine(r.StatusCode);
```

</TabItem>
</Tabs>

## Verifying ECH actually fired

Yeah, this is the annoying part. There's no public reflector that prints "yes, you used ECH". You've got a few options:

- Capture the connection in Wireshark with the [keylog trick](./tls-keylog) and look for the `encrypted_client_hello` extension (type `0xfe0d`) in the ClientHello. The outer SNI will be the ECH provider's name, not your target.
- Read your own DNS lookup. The `dns` package exposes `FetchECHConfigsBase64(ctx, host)` if you import it directly. Non-empty base64 means the host publishes ECH and the lib will use it.
- Trust the fallback. If `WithECHFrom` is set and the target's Cloudflare-fronted, ECH almost certainly fired.

Quick sanity probe in Go:

```go
import hcdns "github.com/sardanioss/httpcloak/dns"

b64, _ := hcdns.FetchECHConfigsBase64(ctx, "cf.erika.cool")
fmt.Println("ECH config len:", len(b64))
```

Empty means the host doesn't publish (or your DNS path's broken). Non-empty means the lib has a real config to plug into the ClientHello.

## Caveats

- **ECH on H1/H2 is opt-in only.** The H3 dial path auto-fetches the target's HTTPS RR. The H2 path only consults `WithECHFrom` and `WithECHConfig`, it doesn't auto-probe the target. The H1 path doesn't touch ECH at all. If your session's forced to H1/H2, set `WithECHFrom` explicitly. (There's a bug filed against this in the project's internal tracker.)
- ECH requires TLS 1.3. The lib bumps `MinVersion` to 1.3 automatically when an ECH config is present.
- The HTTPS RR lookup is cached per host for the configured TTL, so repeated requests don't re-resolve.
- ECH config rotation: providers rotate keys every few hours. httpcloak handles this transparently. If a stale config gets cached and rejected, the next dial refetches.


---


<!-- source: docs/docs/advanced-tls/speculative-tls.md -->

# Speculative TLS

Going through an HTTP CONNECT proxy normally costs you two round-trips before any TLS bytes hit the wire:

1. Client opens TCP to the proxy.
2. Client writes `CONNECT target:443 HTTP/1.1` and waits.
3. Proxy writes `HTTP/1.1 200 Connection established` and waits.
4. Client writes the TLS ClientHello.
5. Proxy relays it. Server replies. Handshake continues.

Steps 2-3 burn one full RTT. Steps 4 onward are the actual TLS handshake. On a 50ms-RTT proxy, that's 50ms of dead air doing nothing useful, every time you make a fresh proxied dial.

`WithEnableSpeculativeTLS` collapses that. The CONNECT request and the inner ClientHello get written to the socket in the same burst, before the proxy's even had a chance to reply with its 200. A well-behaved proxy reads the CONNECT, sets up the upstream tunnel, and immediately starts forwarding the bytes that came after the `\r\n\r\n`. The 200 still comes back, but the ClientHello overlaps with it instead of waiting for it. One round-trip saved.

:::tip
Free win for any proxy-heavy workload. If you're making lots of fresh proxied dials, flip this on.
:::

## What it looks like on the wire

A non-speculative dial sends two distinct write bursts to the proxy:

```
burst 1: CONNECT httpbin.org:443 HTTP/1.1\r\nHost: httpbin.org:443\r\n\r\n
[wait for 200]
burst 2: \x16\x03\x01... (TLS ClientHello)
```

A speculative dial coalesces them:

```
burst 1: CONNECT httpbin.org:443 HTTP/1.1\r\nHost: httpbin.org:443\r\n\r\n\x16\x03\x01... (CONNECT + ClientHello in the same write)
[200 comes back overlapping with the upstream forwarding]
```

The lib still parses the proxy's 200 response correctly, the proxy still sees a valid CONNECT request. The only thing that changes is the timing.

## Turning it on



<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "context"
    "fmt"

    "github.com/sardanioss/httpcloak"
)

func main() {
    s := httpcloak.NewSession("chrome-latest",
        httpcloak.WithSessionTCPProxy("http://user:pass@proxy.example.com:8080"),
        httpcloak.WithEnableSpeculativeTLS(),
    )
    defer s.Close()

    resp, err := s.Get(context.Background(), "https://httpbin.org/ip")
    if err != nil {
        panic(err)
    }
    fmt.Println(resp.StatusCode)
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

with httpcloak.Session(
    preset="chrome-latest",
    tcp_proxy="http://user:pass@proxy.example.com:8080",
    enable_speculative_tls=True,
) as s:
    r = s.get("https://httpbin.org/ip")
    print(r.status_code)
```

</TabItem>
<TabItem value="node" label="Node.js">

```js
const { Session } = require('httpcloak');

const s = new Session({
  preset: 'chrome-latest',
  tcpProxy: 'http://user:pass@proxy.example.com:8080',
  enableSpeculativeTls: true,
});

const r = await s.get('https://httpbin.org/ip');
console.log(r.statusCode);
s.close();
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var s = new Session(
    preset: "chrome-latest",
    tcpProxy: "http://user:pass@proxy.example.com:8080",
    enableSpeculativeTls: true);

var r = await s.GetAsync("https://httpbin.org/ip");
Console.WriteLine(r.StatusCode);
```

</TabItem>
</Tabs>

## When it doesn't help

- **No proxy.** Speculative TLS is a proxy CONNECT optimization. Direct dials don't have a CONNECT exchange to fold into the ClientHello, so the option's a no-op.
- **SOCKS5 proxies.** SOCKS has its own framing and the lib doesn't apply the speculative trick on the SOCKS path. Stick with HTTP CONNECT for this win.
- **Already-warm connections.** The savings only land on the first dial. Once the H2 or H1 connection's in the pool, requests reuse it and there's no proxy handshake to optimize.

## When it can break

Some proxies are picky. They expect to read the CONNECT, write the 200, and only then start reading more bytes. If the client sends extra bytes before the 200 is fully written, the proxy might:

- Buffer the speculative ClientHello correctly and forward it upstream once the tunnel's up. Common case.
- Reject the CONNECT outright with a parse error. Rare, but seen on older Squid setups and a handful of debugging tools.
- Drop the speculative bytes silently, leaving the inner TLS handshake stuck waiting for the server's reply. This is the worst case.

If you suspect the proxy's misbehaving, turn the option off and re-test. If a fresh dial without speculative works and with speculative hangs or errors, that's your answer. Write the proxy brand down somewhere so future you remembers.

## Compatibility status by proxy class

- Modern commercial residential and datacenter proxies: works. Squid 4+, Tinyproxy, mitmproxy in upstream mode, Bright Data, Oxylabs, the usual suspects. Verified in production.
- Squid 3.x with old defaults: hit or miss. Test before you trust.
- Corporate egress proxies (BlueCoat, Zscaler, Forcepoint): mostly untested in this project. Some inspect the CONNECT carefully and may not like extra bytes.
- TLS-terminating MITM proxies: doesn't matter. They terminate inside the proxy and re-originate, so the ClientHello you sent isn't the one that reaches the target anyway.

## Pairing with other features

Speculative TLS plays nice with everything else in the lib:

- Works with H1, H2, and H3-over-MASQUE alike (when the dial path is HTTP CONNECT, which for H3 means MASQUE specifically).
- Works with `WithECHFrom`. The ECH-wrapped ClientHello is what gets pipelined.
- Works with custom JA3 / JA4 fingerprints.
- Works with session resumption. The speculative ClientHello can carry a PSK and resume in one round-trip.

Stack speculative TLS, session resumption, and ECH on a proxy-heavy workload and you've got a fully private one-RTT-to-data first request. That's a Chrome-class profile that very few clients ship with by default.


---


<!-- source: docs/docs/advanced-tls/tls-keylog.md -->

# TLS Keylog

Sometimes you need to see what's actually on the wire, not what the lib *thinks* it sent. Wireshark's your friend, but TLS-encrypted traffic in a capture is just noise unless you've got the keys to decrypt it. The standard trick across Chrome, curl, and httpcloak is to dump TLS keys into a file in `SSLKEYLOGFILE` format, then point Wireshark at it. Wireshark uses the keys to decrypt the session live in the UI.

`WithKeyLogFile(path)` opens the named file in append mode and feeds every TLS handshake's per-connection secrets into it. Each new handshake adds a few lines. The format's simple: ASCII, one secret per line.

## Format

Each line is space-separated:

```
<label> <client_random_hex> <secret_hex>
```

The label tells Wireshark which secret this is. For TLS 1.3 you'll see (per connection):

```
CLIENT_HANDSHAKE_TRAFFIC_SECRET <client_random> <secret>
SERVER_HANDSHAKE_TRAFFIC_SECRET <client_random> <secret>
CLIENT_TRAFFIC_SECRET_0         <client_random> <secret>
SERVER_TRAFFIC_SECRET_0         <client_random> <secret>
EXPORTER_SECRET                 <client_random> <secret>
```

For TLS 1.2 connections you get a single line:

```
CLIENT_RANDOM <client_random> <master_secret>
```

`<client_random>` is 64 hex chars (32 bytes). `<secret>` is 64 or 96 hex chars depending on the cipher suite. Wireshark matches lines to captured connections by the client_random field.

## Setup



<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "context"
    "fmt"
    "os"

    "github.com/sardanioss/httpcloak"
)

func main() {
    keylog := "/tmp/httpcloak-keys.txt"
    _ = os.Remove(keylog) // start fresh

    s := httpcloak.NewSession("chrome-latest",
        httpcloak.WithKeyLogFile(keylog),
    )
    defer s.Close()

    resp, err := s.Get(context.Background(), "https://example.com/")
    if err != nil {
        panic(err)
    }
    fmt.Println("status:", resp.StatusCode)

    data, _ := os.ReadFile(keylog)
    fmt.Printf("keylog (%d bytes):\n%s", len(data), string(data))
}
```

Run it and you'll see something like:

```
status: 200
keylog (632 bytes):
CLIENT_HANDSHAKE_TRAFFIC_SECRET 2bb1...4f SERVER_HANDSHAKE_TRAFFIC_SECRET ...
CLIENT_TRAFFIC_SECRET_0 ...
SERVER_TRAFFIC_SECRET_0 ...
```

</TabItem>
</Tabs>

(Bindings get the same keylog support via the equivalent `key_log_file` / `keyLogFile` option, but the workflow's identical. The Go example above is the canonical one for Wireshark debugging.)

## Pointing Wireshark at the file

1. Edit > Preferences > Protocols > TLS.
2. Find the field `(Pre)-Master-Secret log filename`.
3. Browse to the path you passed to `WithKeyLogFile`.
4. Click OK.

Wireshark watches the file. New lines appended while a capture's open get picked up live. Start a capture, run a request that writes a new key, then check the TLS stream in Wireshark and you'll see a "Decrypted TLS" tab on the packet detail showing plaintext HTTP/2 frames or the H1 request line.

For H3 (QUIC), the same keys get written but the Wireshark setting to enable is QUIC TLS Decryption. As of Wireshark 4.x, pointing the TLS keylog at your file is enough, QUIC inherits from it.

## Override priority

`WithKeyLogFile` overrides the global `SSLKEYLOGFILE` env var for that specific session. If both are set, the explicit path wins. If only the env var's set, every session writes to it. You can have one session keylogging while another doesn't, just by toggling the option per session.

## Per-session vs global

| Setup                                | Behavior                                |
| :----------------------------------- | :-------------------------------------- |
| `SSLKEYLOGFILE=/tmp/k.log` env var   | Every session writes there              |
| `WithKeyLogFile("/tmp/s1.log")` only | Only that session writes, others silent |
| Both set                             | The explicit option wins for that session |
| Neither set                          | No keylog                               |

## When you actually need this

- Verifying ECH actually fired. Decrypt the inner ClientHello and inspect the `encrypted_client_hello` extension.
- Checking that header order on the wire matches what you set. DevTools won't show you raw header order, but if you want byte-level proof from your own request, decrypt the capture.
- Debugging a server's H2 frame layout when something doesn't add up. Wireshark's HTTP/2 dissector is genuinely good and will tell you which frame the server sent and in what order.
- Reproducing a Chromium DevTools-style waterfall but with raw bytes underneath. Useful for benchmarking and for proving correctness of a custom fingerprint.

## When you don't need this

- Way more often the question is "the server's response is wrong, why". For that, just print the response headers and body. Keylogging's for when the disagreement's below the HTTP layer.
- Production. Don't ship `WithKeyLogFile` enabled into prod. The file holds material that lets anyone with read access decrypt your live traffic. If you have to log to disk, log to a path that's tightly permissioned and rotated.

## Related recipes

For a step-by-step Wireshark walkthrough including capture filters and TLS decryption setup, see [Debugging with Wireshark](/recipes/debug-with-wireshark).


---


<!-- source: docs/docs/advanced-tls/domain-fronting.md -->

# Domain Fronting

Domain fronting is the trick where the SNI in your TLS handshake points at one host (call it host A, the "front") and the `Host:` header inside the encrypted HTTP request points at a different host (host B, the real target). The CDN edge sees host A in the ClientHello, terminates TLS, then routes the inner request based on the Host header to host B's backend.

Historical use cases:

- Reaching a CDN-fronted service when host A is on a non-blocked domain and host B's the actual target.
- Censorship circumvention. Block host B at the network layer, and the SNI for host A still goes through cleanly.
- Internal routing where the public DNS for B doesn't exist but B's reachable as a virtual host on A's edge.

:::warning
Domain fronting is deeply CDN-specific. Cloudflare blocks it. AWS CloudFront blocks it. Fastly blocks it on most plans. Some Azure Front Door and GCP Load Balancer setups still allow it. Read your CDN provider's policy before relying on this in production.
:::

## Two related primitives in httpcloak

httpcloak hands you two things that look similar but solve different problems.

### `WithConnectTo(requestHost, connectHost)`, IP-level rerouting

This maps a request hostname to a different TCP-connect target. The TLS SNI and the Host header both stay as `requestHost`. Only the IP the lib dials changes.

Think curl's `--resolve` flag, or manually editing `/etc/hosts`. You're saying "when I ask for host A, open the TCP socket to host B's IP, but otherwise pretend nothing changed". Useful for hitting a specific CDN edge node, testing a new origin, or pinning to a known-good IP.

### Per-request `Host` header, classic SNI != Host fronting

For real domain fronting (SNI=A, Host=B), set the `Host` header explicitly on the request. The URL you pass picks the TCP dial target and the SNI. The Host header you set is what the CDN edge sees inside the decrypted HTTP request.

Both can be combined. Dial a specific CDN IP via `WithConnectTo`, terminate TLS with SNI = a "safe" front domain, and send `Host: real-target.example.com` in the encrypted request.

## Classic fronting setup



<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "context"
    "fmt"

    "github.com/sardanioss/httpcloak"
)

func main() {
    s := httpcloak.NewSession("chrome-latest")
    defer s.Close()

    // URL.Host = front-domain.example.com  -> TCP dial + TLS SNI = front-domain.example.com
    // Host header = real-target.example.com -> what the CDN routes by, after decrypting TLS
    req := &httpcloak.Request{
        Method: "GET",
        URL:    "https://front-domain.example.com/",
        Headers: map[string][]string{
            "Host": {"real-target.example.com"},
        },
    }
    resp, err := s.Do(context.Background(), req)
    if err != nil {
        panic(err)
    }
    body, _ := resp.Bytes()
    fmt.Println(resp.StatusCode, len(body))
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

with httpcloak.Session(preset="chrome-latest") as s:
    r = s.get(
        "https://front-domain.example.com/",
        headers={"Host": "real-target.example.com"},
    )
    print(r.status_code, len(r.body))
```

</TabItem>
<TabItem value="node" label="Node.js">

```js
const { Session } = require('httpcloak');

const s = new Session({ preset: 'chrome-latest' });
const r = await s.get('https://front-domain.example.com/', {
  headers: { Host: 'real-target.example.com' },
});
console.log(r.statusCode, r.body.length);
s.close();
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var s = new Session(preset: "chrome-latest");
var r = await s.GetAsync(
    "https://front-domain.example.com/",
    headers: new() { { "Host", "real-target.example.com" } });
Console.WriteLine($"{r.StatusCode} {r.Body.Length}");
```

</TabItem>
</Tabs>

What goes on the wire:

- TCP open to `front-domain.example.com`
- ClientHello with SNI = `front-domain.example.com`
- Encrypted HTTP/2 frame with `:authority: real-target.example.com` (or `Host: real-target.example.com` for HTTP/1.1)
- CDN routes to the real-target backend if its config allows it.

## IP-level rerouting (the WithConnectTo path)

Different goal, often confused with the above. `WithConnectTo` pins the TCP target while keeping SNI and Host the same as the request URL.

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
s := httpcloak.NewSession("chrome-latest",
    // Asking for example.com, but actually open the socket to example.org's IP.
    // SNI stays "example.com", Host header stays "example.com".
    httpcloak.WithConnectTo("example.com", "example.org"),
)
defer s.Close()

resp, _ := s.Get(context.Background(), "https://example.com/")
fmt.Println(resp.StatusCode)
```

</TabItem>
<TabItem value="python" label="Python">

```python
with httpcloak.Session(
    preset="chrome-latest",
    connect_to={"example.com": "example.org"},
) as s:
    r = s.get("https://example.com/")
    print(r.status_code)
```

</TabItem>
<TabItem value="node" label="Node.js">

```js
const s = new Session({
  preset: 'chrome-latest',
  connectTo: { 'example.com': 'example.org' },
});
const r = await s.get('https://example.com/');
console.log(r.statusCode);
s.close();
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using var s = new Session(
    preset: "chrome-latest",
    connectTo: new Dictionary<string, string> {
        { "example.com", "example.org" }
    });
var r = await s.GetAsync("https://example.com/");
Console.WriteLine(r.StatusCode);
```

</TabItem>
</Tabs>

This only succeeds if the IP you're connecting to actually serves a cert matching the SNI in the handshake. With most public sites, dialing example.org's IP and asking for SNI = example.com will trip cert validation. It works when the front and the target share a wildcard cert or a SAN list.

## What works on which CDN

Reality as of recent testing:

- **Cloudflare**: classic SNI != Host fronting blocked at the edge. The edge checks SNI against the Host header and rejects mismatches. ECH-aware fronting via the Cloudflare ECH endpoint is a different beast and does work, see [ECH](./ech) and `WithECHFrom`.
- **AWS CloudFront**: blocked since 2018. The edge requires SNI match.
- **Fastly**: blocked on most public plans. Some enterprise SKUs permit it.
- **Azure Front Door**: SNI != Host still works on standard tiers in many regions. Verify with your tenant.
- **GCP HTTPS LB / Cloud CDN**: works on classic load balancers in some configs. The newer global LBs are stricter.
- **Older / smaller CDN-like setups (Akamai aside)**: case by case. Test before you assume.

If your front and target are different services on the *same* origin (one ALB, one set of certs, multiple vhosts), fronting works out of the box because there's no edge inspection layer rejecting the mismatch. That's the most reliable use case today.

## When fronting fails

You'll see one of:

- TLS handshake error: cert doesn't cover the front SNI on the edge node you reached.
- 421 Misdirected Request: the edge accepted TLS but rejected the Host header because the connection wasn't authorized for that vhost.
- 403 / 421 from the CDN with a vendor-specific error page: most CDNs that block fronting return an explicit error.
- Empty 200 with a "blocked by security policy" body: rare, mostly on enterprise CDN tiers with deep inspection.

If you hit any of these, the CDN's enforcing SNI=Host. There's no client-side trick to get around it. The block's at the edge.

## ECH as a modern alternative

ECH (covered in [ECH](./ech)) is the spec-blessed successor to domain fronting. Instead of hoping a CDN doesn't check, ECH wraps the inner ClientHello (and so the inner SNI) in a second encrypted handshake. The outer SNI is the ECH provider's name, the real target is invisible to the network. CDN providers explicitly support this, so it doesn't break their AUP.

If your goal is "hide the SNI from middleboxes", reach for ECH. If your goal is "reach a backend the network thinks I shouldn't", domain fronting is the older, riskier, increasingly rare path.


---


<!-- source: docs/docs/advanced-tls/cert-pinning.md -->

# Certificate Pinning

Cert pinning means: trust this exact cert (or its public key), nobody else. Even if a CA somewhere in the chain gets popped, even if a corporate proxy injects its own root, even if your friendly anti-bot vendor is silently MITMing every request you send, the handshake fails because the key on the wire isn't the one you nailed down.

That last case is the one that bites red teamers. Plenty of "transparent" inspection boxes on internal networks own a trusted root, so the standard cert chain validates fine. Pin the SPKI and the whole game falls apart for them.

## Pin types

Two flavors:

| Type | What it hashes | When to use |
|---|---|---|
| `PinTypeSHA256` | SHA256 of the cert's Subject Public Key Info (SPKI) | Default. Survives cert renewals as long as the keypair stays the same. |
| `PinTypeCertificate` | SHA256 of the full DER cert | Stricter. Breaks the second the cert renews, even with the same key. |

SPKI hashing is what HPKP and Chrome's static pin list use. Stick with SPKI unless you have a reason not to.

There's also a file-based path: load a PEM cert off disk and httpcloak grabs the SPKI for you. Same pin type under the hood, just less copy-pasting hashes around.

## Client-level pinning

The fastest way. The `*client.Client` exposes pin methods directly:

```go
import "github.com/sardanioss/httpcloak/client"

c := client.NewClient("chrome-latest")

// Pin by base64 SPKI hash
c.PinCertificate("YSxNUV05SLc2H4Z6kOXWCsUPPMenylyBVtogFlUiByE=", client.ForHost("example.com"))

// Or load it from a PEM file
_ = c.PinCertificateFromFile("/etc/ssl/example.com.crt", client.ForHost("example.com"))

// Drop everything
c.ClearPins()

// Get the underlying pinner if you want raw control
pinner := c.CertPinner()
```

`PinCertificate` is the one you'll reach for 90% of the time. Pass the base64 SPKI hash, optionally scope it with `ForHost(...)` and `IncludeSubdomains()`, done.

`PinCertificateFromFile` parses a PEM cert and extracts the SPKI for you. Useful when you've got the cert sitting in a file and don't want to pipe it through openssl.

`ClearPins` wipes every pin on the client. `CertPinner` hands you the pinner so you can call `AddPin`, `GetPins`, `HasPins` directly.

## Standalone CertPinner

You can also build a pinner outside any client:

```go
p := client.NewCertPinner()

p.AddPin("YSxNUV05SLc2H4Z6kOXWCsUPPMenylyBVtogFlUiByE=",
    client.ForHost("example.com"),
    client.IncludeSubdomains(),
)

_ = p.AddPinFromCertFile("/etc/ssl/backup.crt", client.ForHost("example.com"))

_ = p.AddPinFromPEM(pemBytes, client.ForHost("api.example.com"))

// Verify yourself, given a chain
err := p.Verify("example.com", peerCerts)
```

When do you reach for the standalone version vs Client-attached? Use Client-attached when httpcloak is doing the request and you want pinning enforced automatically on every response. Use standalone when you're verifying chains from somewhere else (a stored cert dump, a different transport, a custom dial) and you want to call `Verify` yourself.

`AddPin` takes flexible input. You can pass `sha256/...` prefixes, raw hex, or base64. The lib normalizes it down to base64 internally:

```go
p.AddPin("sha256/YSxNUV05SLc2H4Z6kOXWCsUPPMenylyBVtogFlUiByE=")  // works (with prefix)
p.AddPin("612c4d51 5d3948b7 361f867a 90e5d60a c50f3cc7 a7ca5c81 56da2016 55220721")  // works (hex, after stripping spaces)
p.AddPin("YSxNUV05SLc2H4Z6kOXWCsUPPMenylyBVtogFlUiByE=")  // works (raw base64)
```

## Pin scoping with PinOption

Pins default to "all hosts". Almost always wrong. Two options narrow scope:

| Option | Effect |
|---|---|
| `client.ForHost("example.com")` | Pin only fires when `host == "example.com"` |
| `client.IncludeSubdomains()` | Pin also fires for `*.example.com` (used together with `ForHost`) |

Combine them:

```go
c.PinCertificate(spkiHash,
    client.ForHost("example.com"),
    client.IncludeSubdomains(),
)
```

Skip both options and the pin applies globally. Every TLS connection through this client checks against it. That's almost never what you want.

## Pin failure handling

When verification fails, you get back a `*client.CertPinError` with the host and both sides of the mismatch:

```go
resp, err := c.Do(ctx, req)
if err != nil {
    var pinErr *client.CertPinError
    if errors.As(err, &pinErr) {
        fmt.Printf("pin failure on %s\n", pinErr.Host)
        fmt.Printf("expected: %v\n", pinErr.ExpectedHashes)
        fmt.Printf("actual:   %v\n", pinErr.ActualHashes)
    }
}
```

The `ActualHashes` list contains the SPKI hash of every cert in the peer chain, leaf first. Handy for figuring out whether the wrong cert showed up, or whether the right cert just rotated to a new key.

## How to capture a pin

The one-liner. Pipe the cert into openssl, extract the public key, hash the DER, base64-encode it:

```bash
echo | openssl s_client -servername example.com -connect example.com:443 2>/dev/null \
  | openssl x509 -pubkey -noout \
  | openssl pkey -pubin -outform DER \
  | openssl dgst -sha256 -binary \
  | base64
```

Output (example.com, captured 2026-05-10):

```
YSxNUV05SLc2H4Z6kOXWCsUPPMenylyBVtogFlUiByE=
```

That's the value you feed `PinCertificate`. Run it once per target, stash the hash somewhere, ship it.

## End-to-end example

This Go program captures example.com's SPKI on the fly via openssl, pins it, and confirms the request lands. Then it swaps in a bogus pin and checks the verification fails:

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "context"
    "errors"
    "fmt"
    "io"
    "os/exec"
    "strings"

    "github.com/sardanioss/httpcloak/client"
)

func captureSPKI(host string) (string, error) {
    cmd := exec.Command("bash", "-c", fmt.Sprintf(
        `echo | openssl s_client -servername %s -connect %s:443 2>/dev/null `+
            `| openssl x509 -pubkey -noout `+
            `| openssl pkey -pubin -outform DER `+
            `| openssl dgst -sha256 -binary `+
            `| base64`, host, host))
    out, err := cmd.Output()
    if err != nil {
        return "", err
    }
    return strings.TrimSpace(string(out)), nil
}

func main() {
    ctx := context.Background()
    host := "example.com"

    spki, err := captureSPKI(host)
    if err != nil {
        panic(err)
    }
    fmt.Printf("captured SPKI: %s\n", spki)

    // Pin the real hash, request should succeed
    c := client.NewClient("chrome-latest")
    c.PinCertificate(spki, client.ForHost(host))

    req := &client.Request{Method: "GET", URL: "https://" + host + "/"}
    resp, err := c.Do(ctx, req)
    if err != nil {
        panic(err)
    }
    io.Copy(io.Discard, resp.Body)
    resp.Body.Close()
    fmt.Printf("pinned request: status=%d\n", resp.StatusCode)

    // Swap to a bogus pin, request should fail with CertPinError
    c.ClearPins()
    c.PinCertificate("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=", client.ForHost(host))

    _, err = c.Do(ctx, req)
    var pinErr *client.CertPinError
    if errors.As(err, &pinErr) {
        fmt.Printf("pin failure on %s\n", pinErr.Host)
        fmt.Printf("expected: %v\n", pinErr.ExpectedHashes)
        fmt.Printf("got:      %v\n", pinErr.ActualHashes)
    } else {
        fmt.Println("expected CertPinError, got:", err)
    }
}
```

</TabItem>
<TabItem value="python" label="Python">

Pinning is Go-only right now. The Python binding doesn't surface `PinCertificate` yet. If you need pinning from Python, run a local httpcloak proxy with pinning configured on the Go side and point Python at it. Tracking issue if you want to bump priority: open a GH issue.

</TabItem>
<TabItem value="node" label="Node.js">

Same as Python. The Node binding doesn't expose pin APIs yet. Wrap a Go-side httpcloak local proxy with pins enforced and route Node traffic through it.

</TabItem>
<TabItem value="dotnet" label=".NET">

.NET binding doesn't expose pin APIs yet either. Same workaround applies: Go-side local proxy with pins, .NET points at it.

</TabItem>
</Tabs>

Sample output, run against example.com on 2026-05-10:

```text
captured SPKI: YSxNUV05SLc2H4Z6kOXWCsUPPMenylyBVtogFlUiByE=
pinned request: status=200
pin failure on example.com
expected: [AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=]
got:      [YSxNUV05SLc2H4Z6kOXWCsUPPMenylyBVtogFlUiByE= Kt2bkYM55rPaGBFYxTLlq8AIJqapRcc1eKjai8GUPO0= OXyj9ngbqO9cjLeO/+t9Ggl2EP4JTnVWHq4LEwhFM9w= G/ANXI8TwJTdF+AFBM8IiIUPEv0Gf6H5LA/b9guG4yE=]
```

First request: 200, pin matched. Second: `CertPinError`, peer chain hashes leaked into `ActualHashes` so you can see exactly what showed up.

:::warning
Pins go stale. Sites rotate certs, sometimes on a schedule (Let's Encrypt is 90 days), sometimes after an incident, and your hardcoded SPKI hash dies the moment the keypair changes. Build a refresh path: re-capture the hash on a cron, or pin multiple SPKIs (current + next) at once, or fall back gracefully when `CertPinError` shows up. A pinned client that 100% fails after cert rotation is worse than no pin at all.
:::


---


<!-- source: docs/docs/requests-and-responses/index.md -->

# Requests & Responses

Headers, bodies, streaming, errors. The day-to-day stuff you'll actually touch.

## In this section

- [Headers](./headers): why header order matters, setting custom ones, what each preset ships by default
- [JSON Bodies](./json-bodies): sending and parsing JSON, the shortcuts and the gotchas
- [Form Data and Multipart](./form-data-and-multipart): url-encoded and multipart/form-data, with file uploads
- [Streaming Responses](./streaming-responses): DoStream(), reading chunks, cookie jar parity
- [Error Handling](./error-handling): network errors vs real 5xx, and how to tell them apart


---


<!-- source: docs/docs/requests-and-responses/headers.md -->

# Headers

Header order matters. Not just the values, the **order** they hit the wire.

Chrome ships its headers in a fixed sequence: `sec-ch-ua` first, then `sec-ch-ua-mobile`, then `sec-ch-ua-platform`, then `upgrade-insecure-requests`, then `user-agent`, then `accept`, and so on down the list. That sequence is part of your fingerprint. Anti-bot vendors hash it. Send the same headers in a different order (or add one Chrome wouldn't, or skip one Chrome always sends) and you stand out.

httpcloak bakes the canonical order into each preset. Your custom headers slot into preset-reserved positions so adding `Authorization` or `X-Anything-Custom` doesn't blow up the fingerprint.

:::tip
DevTools won't show you header order, so you're flying blind there. Hit [tls.peet.ws/api/all](https://tls.peet.ws/api/all) and check the `http2.sent_frames[].headers` array. That's the actual wire order.
:::

## What ships by default

Every preset carries its own browser header set. For `chrome-148-linux` (today's default), the request goes out as:

| Position | Header | Example value |
|---|---|---|
| 1 | `sec-ch-ua` | `"Chromium";v="148", "Google Chrome";v="148", "Not/A)Brand";v="99"` |
| 2 | `sec-ch-ua-mobile` | `?0` |
| 3 | `sec-ch-ua-platform` | `"Linux"` |
| 4 | `upgrade-insecure-requests` | `1` |
| 5 | `user-agent` | `Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 ...` |
| 6 | `accept` | `text/html,application/xhtml+xml,...` |
| 7 | `sec-fetch-site` | `none` |
| 8 | `sec-fetch-mode` | `navigate` |
| 9 | `sec-fetch-user` | `?1` |
| 10 | `sec-fetch-dest` | `document` |
| 11 | `accept-encoding` | `gzip, deflate, br, zstd` |
| 12 | `accept-language` | `en-US,en;q=0.9` |
| 13 | `priority` | `u=0, i` |

Different presets ship different defaults. Firefox skips `sec-ch-ua-*` entirely, Safari sends a different `accept-language`, mobile presets flip `sec-ch-ua-mobile` to `?1`, and so on. Want the full list? Peek at `fingerprint/embedded/<preset>.json`.

The lib also auto-rewrites the `sec-fetch-*` cluster based on what kind of request you're firing. POST/PUT/PATCH and most XHR-shaped GETs get flipped from navigation mode (`navigate`/`document`/`?1`) to CORS mode (`cors`/`empty`/cross-site, no `sec-fetch-user`). Real browsers do the same, so you don't end up looking like a bot hitting an API endpoint with navigation-style headers.

## Setting custom headers

Two scopes: per-request, or session-wide as a default.

### Per-request

Drop a `Headers` map on the request. Whatever you set merges into the preset defaults. If your key matches a preset header, yours wins (single-value Set semantics).



<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "context"
    "fmt"

    httpcloak "github.com/sardanioss/httpcloak"
)

func main() {
    s := httpcloak.NewSession("chrome-latest")
    defer s.Close()

    req := &httpcloak.Request{
        Method: "GET",
        URL:    "https://httpbin.org/headers",
        Headers: map[string][]string{
            "X-My-Header":   {"hello-world"},
            "Authorization": {"Bearer xxx"},
        },
    }
    resp, _ := s.Do(context.Background(), req)
    defer resp.Close()

    body, _ := resp.Text()
    fmt.Println(body)
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

s = httpcloak.Session(preset="chrome-latest")

r = s.get(
    "https://httpbin.org/headers",
    headers={
        "X-My-Header": "hello-world",
        "Authorization": "Bearer xxx",
    },
)
print(r.text)
```

</TabItem>
<TabItem value="nodejs" label="Node.js">

```js
const { Session } = require("httpcloak");

const s = new Session({ preset: "chrome-latest" });

const r = await s.get("https://httpbin.org/headers", {
  headers: {
    "X-My-Header": "hello-world",
    "Authorization": "Bearer xxx",
  },
});
console.log(r.text);
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var s = new Session(new SessionOptions { Preset = "chrome-latest" });

var headers = new Dictionary<string, string> {
    { "X-My-Header", "hello-world" },
    { "Authorization", "Bearer xxx" }
};
var r = s.Get("https://httpbin.org/headers", headers: headers);
Console.WriteLine(r.Text);
```

</TabItem>
</Tabs>

httpbin echoes back the headers it saw. You'll spot your `X-My-Header: hello-world` plus the full preset cluster (User-Agent, Accept, sec-ch-ua, the lot).

### Session-wide defaults

If a header should ride on every request in a session (auth tokens, an `X-API-Key`, a static `Referer`), set it once and forget about it.

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
// Go has no built-in WithHeaders for session defaults.
// Closure-wrap the session and inject headers in your wrapper:
type apiClient struct {
    s    *httpcloak.Session
    auth string
}

func (c *apiClient) Get(ctx context.Context, url string) (*httpcloak.Response, error) {
    return c.s.Do(ctx, &httpcloak.Request{
        Method: "GET",
        URL:    url,
        Headers: map[string][]string{
            "Authorization": {c.auth},
        },
    })
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
s = httpcloak.Session(preset="chrome-latest")
s.headers.update({"Authorization": "Bearer xxx"})

# now every s.get / s.post / s.request includes the Authorization header
r = s.get("https://httpbin.org/headers")
```

</TabItem>
<TabItem value="nodejs" label="Node.js">

```js
const s = new Session({ preset: "chrome-latest" });
s.headers["Authorization"] = "Bearer xxx";

const r = await s.get("https://httpbin.org/headers");
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
// .NET binding doesn't expose a session-default headers bag. Pass headers per request
// or wrap the session in your own class that injects defaults.
```

</TabItem>
</Tabs>

## How merge works

Merge order: **preset defaults first, your custom headers second**. If your key collides with a preset key (case-insensitive), your value wins. New keys land at whatever position the preset reserved for them, or at the end if the preset doesn't reserve a slot.

The reserved-slot bit is what matters. The preset's full HPACK position table (separate from the smaller "always emit" set) carves out spots for situational headers like `cache-control`, `content-type`, `content-length`, `cookie`, `origin`, `referer`. So when you add `Content-Type: application/json` on a POST, it lands at the same offset Chrome would've placed it. Skip that and your custom headers just pile up after `priority`, which is exactly the kind of small drift fingerprinters love.

## Things that don't behave the way you'd expect

- **Casing.** HTTP/2 and HTTP/3 are lowercase on the wire. The preset stores everything lowercase. Pass `User-Agent: foo` and the lib normalizes it to `user-agent: foo` for H2/H3. On HTTP/1.1, casing is preserved per the request map.
- **Removing a preset header.** Need to drop a default header (say, `Accept-Encoding`)? Set it to `""` in your headers map. The lib won't emit it.
- **Custom headers vs each other.** Add five custom headers the preset doesn't reserve slots for, and they all pile up at the end in the order you added them.
- **Cookie.** Don't set `Cookie` directly unless you've thought it through. The session jar handles it. See [Per-Request Cookies](../cookies-and-state/per-request-cookies) if you really need to override.

## Inspecting what actually went out

Cleanest verification path: send to [tls.peet.ws/api/all](https://tls.peet.ws/api/all) and read the `http2.sent_frames` array. Each HEADERS frame lists the headers in the exact order they hit the wire. That's the ground truth.

httpbin.org/headers is fine for "did my custom header show up?" checks, but it gives you a Python dict, not the wire order. For order, use peet.

## Header order overrides

If you really know what you're doing and want to reorder how headers get emitted (different preset baseline, custom mobile order, whatever), the session exposes `SetHeaderOrder()` and `GetHeaderOrder()`. Pass a list of lowercase header names. Pass `nil` or an empty slice to reset to the preset's default.

```go
s := httpcloak.NewSession("chrome-latest")
defer s.Close()

s.SetHeaderOrder([]string{
    "user-agent",
    "accept",
    "accept-language",
    "accept-encoding",
    "x-my-header",
})
```

Nuclear option. Don't reach for it unless your target is running some weirdo-specific order check that no shipped preset matches. 99% of the time the preset's order is what you want, and changing it just makes you stand out.


---


<!-- source: docs/docs/requests-and-responses/json-bodies.md -->

# JSON Bodies

Most APIs talk JSON. Send a body, parse a body. Bread and butter stuff.

## Sending JSON

The shape: pass a struct (Go) or a dict / object (Python, Node, .NET), the lib serializes it, sets `Content-Type: application/json`, and ships it out.



<Tabs groupId="lang">
<TabItem value="go" label="Go">

In Go you build the body yourself with `encoding/json` and pass an `io.Reader`. The Go API stays explicit so you can stream big payloads instead of buffering them whole.

```go
package main

import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"

    httpcloak "github.com/sardanioss/httpcloak"
)

func main() {
    s := httpcloak.NewSession("chrome-latest")
    defer s.Close()

    payload := map[string]any{"hello": "world", "n": 42}
    body, _ := json.Marshal(payload)

    req := &httpcloak.Request{
        Method: "POST",
        URL:    "https://httpbin.org/post",
        Headers: map[string][]string{
            "Content-Type": {"application/json"},
        },
        Body: bytes.NewReader(body),
    }
    resp, _ := s.Do(context.Background(), req)
    defer resp.Close()

    var parsed struct {
        JSON map[string]any `json:"json"`
    }
    resp.JSON(&parsed)
    fmt.Println(parsed.JSON) // map[hello:world n:42]
}
```

The non-session client has a shortcut too: `client.PostJSON(ctx, url, bodyBytes)` sets the Content-Type for you.

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

s = httpcloak.Session(preset="chrome-latest")

r = s.post(
    "https://httpbin.org/post",
    json={"hello": "world", "n": 42},
)

print(r.json()["json"])  # {"hello": "world", "n": 42}
```

The `json=` kwarg handles serialization and sets `Content-Type: application/json`. Already serialized the body? Use `data=` and set the header yourself.

</TabItem>
<TabItem value="nodejs" label="Node.js">

```js
const { Session } = require("httpcloak");

const s = new Session({ preset: "chrome-latest" });

const r = await s.post("https://httpbin.org/post", {
  json: { hello: "world", n: 42 },
});

console.log(r.json().json); // { hello: "world", n: 42 }
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var s = new Session(new SessionOptions { Preset = "chrome-latest" });

var payload = new { hello = "world", n = 42 };
var r = s.PostJson("https://httpbin.org/post", payload);

Console.WriteLine(r.Text);
```

`PostJson` uses `System.Text.Json` under the hood and sets the Content-Type header for you. No ceremony.

</TabItem>
</Tabs>

## Reading JSON

Responses come back as bytes you can parse on demand.

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
resp, _ := s.Get(ctx, "https://httpbin.org/json")
defer resp.Close()

var data struct {
    Slideshow struct {
        Title string `json:"title"`
    } `json:"slideshow"`
}
if err := resp.JSON(&data); err != nil {
    // not valid JSON, or read error
}
fmt.Println(data.Slideshow.Title)
```

`resp.JSON(&v)` reads the full body and unmarshals into `v`. The body's buffered after the first read, so you can call `resp.Bytes()` or `resp.Text()` afterward and get the same payload back.

</TabItem>
<TabItem value="python" label="Python">

```python
r = s.get("https://httpbin.org/json")
data = r.json()
print(data["slideshow"]["title"])
```

</TabItem>
<TabItem value="nodejs" label="Node.js">

```js
const r = await s.get("https://httpbin.org/json");
const data = r.json();
console.log(data.slideshow.title);
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
var r = s.Get("https://httpbin.org/json");
using var doc = JsonDocument.Parse(r.Text);
var title = doc.RootElement
    .GetProperty("slideshow")
    .GetProperty("title")
    .GetString();
```

</TabItem>
</Tabs>

## Pitfalls worth knowing

### Content-Type sniffing

Send a body with no `Content-Type` and something downstream might sniff it and pick one for you. JSON requests **must** carry `Content-Type: application/json`, otherwise:

- Some servers treat the body as form data and 400 you back.
- Some WAFs flag the request as suspicious.

The shortcut wrappers (`PostJson`, `post(json=...)`, etc.) set this for you. Build the request by hand and you're on your own.

### Encoding

JSON is always UTF-8 on the wire. Don't try Latin-1 or UTF-16 even if the server "would accept it." Real browsers send UTF-8. Anti-bot products expect UTF-8.

### Big responses

If you're pulling something multi-MB or bigger, don't buffer it whole. Use the streaming API instead. See [Streaming Responses](./streaming-responses).

`resp.JSON()` and `resp.Bytes()` both pull the entire body into memory. For a 200MB JSON dump, that's gonna hurt.

### Numbers

Go: JSON numbers default to `float64`. Got integer IDs over 2^53 (snowflake IDs and friends)? Use `json.Number` or string-encode them. Python and Node native ints don't have this issue. .NET's `JsonElement.GetInt64()` handles 64-bit cleanly.

### Trailing newlines, BOMs

httpbin and most decent servers don't send these, but if you hit a server that prefixes its JSON with a UTF-8 BOM (`\xef\xbb\xbf`), most parsers choke. Strip the BOM before parsing. Rare, but it pops up on some old Java backends.

## A test pattern that just works

The httpbin echo endpoints are perfect for verifying your client serializes correctly:

- `POST https://httpbin.org/post` echoes the request as JSON, including a parsed `json` field if you sent JSON.
- `PUT https://httpbin.org/put`, `DELETE https://httpbin.org/delete`, `PATCH https://httpbin.org/patch` all do the same for their methods.

So if your client should be sending `{"hello": "world"}`, hit `/post` and check that `response.json["hello"] == "world"`. Missing or wrong type? The lib didn't serialize what you thought, or the Content-Type was off.


---


<!-- source: docs/docs/requests-and-responses/form-data-and-multipart.md -->

# Form Data and Multipart

Two flavors of form posting. Pick based on what you're shipping:

- **`application/x-www-form-urlencoded`** for plain key/value text fields. Small, simple, no binary.
- **`multipart/form-data`** for file uploads, mixed text + file fields, or anything binary.

Browsers pick the same way. `<form>` with `enctype="multipart/form-data"` for uploads, default url-encoded otherwise.

## URL-encoded

The body's just `key1=val1&key2=val2`, with values percent-encoded. Content-Type is `application/x-www-form-urlencoded`.



<Tabs groupId="lang">
<TabItem value="go" label="Go">

Go gives you `net/url.Values` to build the body, then you ship the bytes.

```go
package main

import (
    "bytes"
    "context"
    "fmt"
    "net/url"

    httpcloak "github.com/sardanioss/httpcloak"
)

func main() {
    s := httpcloak.NewSession("chrome-latest")
    defer s.Close()

    form := url.Values{}
    form.Set("user", "alice")
    form.Set("token", "abc 123")

    req := &httpcloak.Request{
        Method: "POST",
        URL:    "https://httpbin.org/post",
        Headers: map[string][]string{
            "Content-Type": {"application/x-www-form-urlencoded"},
        },
        Body: bytes.NewReader([]byte(form.Encode())),
    }
    resp, _ := s.Do(context.Background(), req)
    defer resp.Close()

    body, _ := resp.Text()
    fmt.Println(body) // "form": {"user": "alice", "token": "abc 123"}
}
```

The non-session client has `client.PostForm(ctx, url, bodyBytes)` too, which sets the Content-Type for you.

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

s = httpcloak.Session(preset="chrome-latest")

r = s.post(
    "https://httpbin.org/post",
    data={"user": "alice", "token": "abc 123"},
)

print(r.json()["form"])  # {"user": "alice", "token": "abc 123"}
```

When `data=` is a dict, the binding url-encodes it and sets the Content-Type for you. Pass `data=` a string or bytes and it ships them as-is, with whatever Content-Type you put in `headers`.

</TabItem>
<TabItem value="nodejs" label="Node.js">

```js
const { Session } = require("httpcloak");

const s = new Session({ preset: "chrome-latest" });

const r = await s.post("https://httpbin.org/post", {
  form: { user: "alice", token: "abc 123" },
});

console.log(r.json().form);
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var s = new Session(new SessionOptions { Preset = "chrome-latest" });

var formData = new Dictionary<string, string> {
    { "user", "alice" },
    { "token", "abc 123" }
};
var r = s.PostForm("https://httpbin.org/post", formData);
Console.WriteLine(r.Text);
```

</TabItem>
</Tabs>

Things to keep in mind:

- **Encoding is fixed.** Always UTF-8 percent-encoded. Don't try Latin-1 in form bodies even if a server "would accept it."
- **Repeated keys.** url-encoded supports the same key twice (`a=1&a=2`). Most builders give you a list-valued helper. In Go: `form.Add("a", "1"); form.Add("a", "2")`.
- **Length limits.** Some servers cap form bodies around 1MB. If you're shipping more than a kilobyte of text, multipart is usually the better fit. Megabytes? You almost certainly want multipart for file fields, or just JSON.

## Multipart

Multipart wraps each field in its own MIME part with a boundary string. You get a Content-Type like `multipart/form-data; boundary=----WebKitFormBoundaryAbCdEf123`. The body looks roughly like:

```
------WebKitFormBoundaryAbCdEf123
Content-Disposition: form-data; name="comment"

hello there
------WebKitFormBoundaryAbCdEf123
Content-Disposition: form-data; name="file"; filename="note.txt"
Content-Type: text/plain

file body bytes
------WebKitFormBoundaryAbCdEf123--
```

You almost never want to write this by hand. Use the helpers, that's what they're for.

<Tabs groupId="lang">
<TabItem value="go" label="Go">

httpcloak ships `MultipartField` and `BuildMultipart` for the common case.

```go
package main

import (
    "bytes"
    "context"
    "fmt"

    httpcloak "github.com/sardanioss/httpcloak"
)

func main() {
    s := httpcloak.NewSession("chrome-latest")
    defer s.Close()

    fields := []httpcloak.MultipartField{
        {Name: "comment", Value: "hello there"},
        {
            Name:        "file",
            Filename:    "note.txt",
            Content:     []byte("file body bytes"),
            ContentType: "text/plain",
        },
    }
    body, contentType, err := httpcloak.BuildMultipart(fields)
    if err != nil {
        panic(err)
    }

    req := &httpcloak.Request{
        Method: "POST",
        URL:    "https://httpbin.org/post",
        Headers: map[string][]string{
            "Content-Type": {contentType},
        },
        Body: bytes.NewReader(body),
    }
    resp, _ := s.Do(context.Background(), req)
    defer resp.Close()

    body2, _ := resp.Text()
    fmt.Println(body2)
    // form: { "comment": "hello there" }
    // files: { "file": "file body bytes" }
}
```

`BuildMultipart` handles boundary generation, MIME headers per part, and the trailing `--`. The Content-Type it returns is the full string with the boundary parameter, drop it straight into your headers.

For really large file uploads, building the whole body in memory is a bad idea. Use `mime/multipart.Writer` directly with `io.Pipe` and stream into the request via `Body: pipeReader`. Your RAM will thank you.

</TabItem>
<TabItem value="python" label="Python">

```python
r = s.post(
    "https://httpbin.org/post",
    data={"comment": "hello there"},
    files={"file": ("note.txt", b"file body bytes", "text/plain")},
)

result = r.json()
print(result["form"])   # {"comment": "hello there"}
print(result["files"])  # {"file": "file body bytes"}
```

The `files=` kwarg accepts:

- `{"name": file_object}`: open file, the binding pulls filename and bytes.
- `{"name": (filename, bytes_or_str)}`: explicit filename, content-type sniffed.
- `{"name": (filename, bytes_or_str, content_type)}`: full control.

</TabItem>
<TabItem value="nodejs" label="Node.js">

```js
const r = await s.post("https://httpbin.org/post", {
  form: { comment: "hello there" },
  files: {
    file: {
      filename: "note.txt",
      content: Buffer.from("file body bytes"),
      contentType: "text/plain",
    },
  },
});

console.log(r.json().form);   // { comment: "hello there" }
console.log(r.json().files);  // { file: "file body bytes" }
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var s = new Session(new SessionOptions { Preset = "chrome-latest" });

var fields = new Dictionary<string, string> {
    { "comment", "hello there" }
};
var files = new Dictionary<string, MultipartFile> {
    { "file", new MultipartFile {
        Filename = "note.txt",
        Content = System.Text.Encoding.UTF8.GetBytes("file body bytes"),
        ContentType = "text/plain"
    }}
};

var r = s.PostMultipart("https://httpbin.org/post", fields: fields, files: files);
Console.WriteLine(r.Text);
```

</TabItem>
</Tabs>

## Order of fields

Multipart preserves the order you list fields. For most servers that doesn't matter (they parse into a map). But occasionally:

- A server rejects an upload if the file part comes before a CSRF token field.
- A server expects a specific field order baked into its form validation.

Seeing weird "field missing" or "invalid form" errors when the values look fine? Try reordering. Drop the file last, drop the token first. The browser-emitted order is whatever the `<form>` markup says, which is usually text fields then file inputs.

## Boundary string

Browsers use boundaries like `----WebKitFormBoundaryAbCdEf123456`. Go's stdlib (and therefore httpcloak's `BuildMultipart`) generates random boundaries that look different. For 99% of servers this doesn't matter, the boundary is just a delimiter. If you hit a strict WAF that pattern-matches on browser-style boundaries, you can build the body yourself with `mime/multipart.Writer.SetBoundary()` and pass a Chrome-shaped one. Rare scenario though.

## Verify with httpbin

`POST https://httpbin.org/post` is the one-stop shop for verifying multipart serialization. The response gives you:

- `form`: text fields
- `files`: file fields, with the file content inlined as a string
- `headers["Content-Type"]`: the Content-Type you sent (verify the boundary)

If `files` is empty but you sent a file, your boundary or part headers are busted. If the file content looks like garbage, your encoding's off.


---


<!-- source: docs/docs/requests-and-responses/streaming-responses.md -->

# Streaming Responses

`DoStream()` returns a response whose body you read incrementally. Use it for:

- **Big downloads.** Don't buffer a 2 GB file in RAM.
- **Server-Sent Events.** Long-lived connections that drip events.
- **NDJSON / line-delimited streams.** Read one record at a time.
- **Anything chunked.** When the server doesn't know the content length up front.

Plain `Do()` reads the full body into memory before returning. `DoStream()` returns the moment the response headers arrive, and you pull the body yourself.

:::info
Pre-1.6.6, `DoStream` didn't update the cookie jar from the response. On an older version? Upgrade, or extract Set-Cookie headers by hand. Bug fixed in 1.6.6.
:::

## The shape



<Tabs groupId="lang">
<TabItem value="go" label="Go">

`Session.DoStream(ctx, req)` returns a `*StreamResponse`. It implements `io.Reader`, so anything that takes a Reader works: bufio.Scanner, json.Decoder, io.Copy, all of it.

```go
package main

import (
    "bufio"
    "context"
    "fmt"

    httpcloak "github.com/sardanioss/httpcloak"
)

func main() {
    s := httpcloak.NewSession("chrome-latest")
    defer s.Close()

    stream, err := s.GetStream(context.Background(), "https://httpbin.org/stream/10")
    if err != nil {
        panic(err)
    }
    defer stream.Close()

    fmt.Println("status:", stream.StatusCode)
    fmt.Println("content-length:", stream.ContentLength) // -1 if chunked

    scanner := bufio.NewScanner(stream)
    n := 0
    for scanner.Scan() {
        n++
        fmt.Printf("chunk %d: %s\n", n, scanner.Text())
    }
    fmt.Printf("got %d lines\n", n)
}
```

`Close()` is mandatory. Defer it the second you have the stream. Skip it and you leak the underlying connection, which means it never goes back to the pool and you eat the dial cost on the next request.

</TabItem>
<TabItem value="python" label="Python">

The Python binding folds streaming into `get(stream=True)`:

```python
import httpcloak

s = httpcloak.Session(preset="chrome-latest")

with s.get("https://httpbin.org/stream/10", stream=True) as r:
    print("status:", r.status_code)
    n = 0
    for line in r.iter_lines():
        n += 1
        print(f"chunk {n}: {line.decode()}")
    print(f"got {n} lines")
```

`iter_lines()` and `iter_content(chunk_size=N)` both work. The `with` block calls Close for you when the body's done.

</TabItem>
<TabItem value="nodejs" label="Node.js">

`session.getStream()` returns a StreamResponse you can iterate with `for await`:

```js
const { Session } = require("httpcloak");

const s = new Session({ preset: "chrome-latest" });

const stream = s.getStream("https://httpbin.org/stream/10");
console.log("status:", stream.statusCode);

let n = 0;
for await (const chunk of stream) {
  n++;
  console.log(`chunk ${n}: ${chunk.toString()}`);
}
stream.close();
console.log(`got ${n} chunks`);
```

Always call `stream.close()` after iterating, otherwise the connection leaks.

</TabItem>
<TabItem value="dotnet" label=".NET">

`Session.GetStream()` (and `RequestStream` for non-GET) returns a `StreamResponse` with a `Stream` body:

```csharp
using HttpCloak;

using var s = new Session(new SessionOptions { Preset = "chrome-latest" });

using var stream = s.GetStream("https://httpbin.org/stream/10");
Console.WriteLine($"status: {stream.StatusCode}");

using var content = stream.GetContentStream();
using var reader = new StreamReader(content);
int n = 0;
string? line;
while ((line = reader.ReadLine()) != null)
{
    n++;
    Console.WriteLine($"chunk {n}: {line}");
}
Console.WriteLine($"got {n} lines");
```

The `using` on the StreamResponse handles Close.

</TabItem>
</Tabs>

## What you can read it as

The body's just bytes coming off the wire. You decide how to split them.

- **Line-delimited.** `bufio.Scanner` (Go), `iter_lines()` (Python), readline loop (Node).
- **Fixed-size chunks.** `Read(buf)` (Go), `iter_content(chunk_size=N)` (Python), `read(N)` (Node).
- **JSON streams.** Wrap in a JSON decoder. Go: `json.NewDecoder(stream).Decode(&v)` in a loop for NDJSON. Python: `for line in r.iter_lines(): obj = json.loads(line)`.
- **Pipe to a file.** Go: `io.Copy(file, stream)`. Python: `for chunk in r.iter_content(8192): f.write(chunk)`.

## Lifetime and Close

The contract: **caller must call Close when done**. There's no GC fallback because the stream wraps real syscall resources: a TCP socket, an H2 stream window, an H3 stream.

Common ways to forget:

- Returning early from a function on an error path without `defer stream.Close()`. Always defer right after the err check.
- Iterating partway and bailing without closing.
- In Python, skipping `with`. The non-with form needs an explicit `r.close()`.

Closing partway through is totally fine. The lib reads-and-discards the rest in the background to keep the underlying connection clean for reuse, or hard-aborts the H2/H3 stream if there's a lot left.

## ContentLength and chunked

`stream.ContentLength` (or `content_length` / `contentLength` in the bindings) is `-1` when the server uses chunked transfer encoding (or H2/H3 without an explicit content-length frame). Don't assume it's positive when sizing a download progress bar.

Need to know the size up front? Fire a `HEAD` request first, read `Content-Length` from the response headers, then `DoStream()` the GET. Most servers send a length on HEAD even when they'd switch to chunked on GET.

## Cookie jar parity (since 1.6.6)

Streaming responses now go through the same cookie extraction path as regular ones. `Set-Cookie` headers from the response (or any in-stream redirect the lib resolved before handing you the body) land in the session jar.

Before 1.6.6, streaming bypassed the jar update and you'd silently miss cookies from streamed endpoints. The fix landed in [#5491c85](../changelog), so `Do` and `DoStream` now behave identically.

Stuck on an older version and can't upgrade?

```go
// Manual cookie extraction from a streamed response, pre-1.6.6 workaround.
for _, sc := range stream.Headers["Set-Cookie"] {
    // parse sc with net/http or store as raw and inject on next request
}
```

## A note on H2 and H3

Stream over HTTP/2 or HTTP/3 and the underlying transport still rides on a single multiplexed connection. So `stream.Close()` doesn't kill the connection itself, just the one stream on it. You can run multiple streaming requests in flight on the same H2 connection at once, which is great for SSE + an API call running side by side.

On HTTP/1.1, a streaming response holds the whole TCP connection until you close. Concurrent requests need separate connections. The lib handles connection pooling either way so you don't have to think about it, but heads up: 100 concurrent streams on H1 means 100 TCP connections.


---


<!-- source: docs/docs/requests-and-responses/error-handling.md -->

# Error Handling

Errors come in two flavors and they're really not the same thing:

1. **Network / protocol errors.** DNS failed, connection refused, TLS handshake blew up, the request timed out before a response. Either it never made it, or it made it and the server never replied. These come back as Go `error` / Python exception / Node thrown error / .NET exception.

2. **Real responses with a non-2xx status.** The server got your request, processed it, didn't like it, and sent back `404` or `500` or whatever. The HTTP exchange is done. These come back as **normal Response objects**. You check `StatusCode`.

Mixing them up is the most common bug in this space. A 500 isn't a network error. The server told you no. The connection's fine.

## The split, with code



<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
resp, err := s.Get(ctx, url)
if err != nil {
    // Network / protocol / context error. No response.
    return err
}
defer resp.Close()

if resp.StatusCode >= 500 {
    // Server-side error. The exchange completed.
    return fmt.Errorf("server error: %d", resp.StatusCode)
}
if resp.StatusCode >= 400 {
    // Client-side error. You sent something the server rejected.
    return fmt.Errorf("client error: %d", resp.StatusCode)
}

// 2xx. We're good.
body, _ := resp.Bytes()
```

</TabItem>
<TabItem value="python" label="Python">

```python
try:
    r = s.get(url)
except httpcloak.HTTPCloakError as e:
    # Network / protocol / context error
    raise

if r.status_code >= 500:
    raise RuntimeError(f"server error: {r.status_code}")
if r.status_code >= 400:
    raise RuntimeError(f"client error: {r.status_code}")
```

</TabItem>
<TabItem value="nodejs" label="Node.js">

```js
let r;
try {
  r = await s.get(url);
} catch (e) {
  // Network / protocol error
  throw e;
}

if (r.statusCode >= 500) throw new Error(`server error: ${r.statusCode}`);
if (r.statusCode >= 400) throw new Error(`client error: ${r.statusCode}`);
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
Response r;
try {
    r = s.Get(url);
} catch (HttpCloakException e) {
    // Network / protocol error
    throw;
}

if (r.StatusCode >= 500) throw new Exception($"server error: {r.StatusCode}");
if (r.StatusCode >= 400) throw new Exception($"client error: {r.StatusCode}");
```

</TabItem>
</Tabs>

## Common error shapes

Things that come back as a real error (not a Response):

### DNS failure

```
dns_resolve nope.example: lookup nope.example: no such host
```

In Go, this wraps a `*net.DNSError`. Check `IsNotFound`, `IsTemporary`, `IsTimeout` on it.

```go
var dnsErr *net.DNSError
if errors.As(err, &dnsErr) {
    if dnsErr.IsNotFound { /* domain doesn't exist */ }
    if dnsErr.IsTimeout  { /* DNS server didn't reply in time */ }
}
```

In other bindings the message string contains `dns_resolve` or `lookup`.

### Connection refused

```
dial example.com: dial tcp 1.2.3.4:443: connect: connection refused
```

Server isn't listening, or a firewall's dropping it. Same shape across all bindings.

### TLS handshake failure

```
tls: handshake failure
remote error: tls: protocol_version
```

Could be a cert mismatch, expired cert, the server only speaks TLS 1.3 and your config disabled it, or an anti-bot system rejecting your fingerprint at TLS level. The message usually has a hint, but they're not always easy to read.

### Timeout

```
context deadline exceeded
i/o timeout
```

In Go: `errors.Is(err, context.DeadlineExceeded)` returns true when the request didn't finish before your context deadline. There's also a wrapped `*net.OpError` with `Timeout() == true` for raw socket timeouts.

```go
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

_, err := s.Get(ctx, "https://httpbin.org/delay/10")
if errors.Is(err, context.DeadlineExceeded) {
    // we hit our timeout
}
```

### Cancellation

```
context canceled
```

Same as timeout but voluntary. `errors.Is(err, context.Canceled)`.

## What's a real response (not an error)

These all come back as a populated `Response` with a status code, **not** as an error:

- `4xx`: Bad Request, Unauthorized, Forbidden, Not Found, Method Not Allowed, the usual suspects.
- `5xx`: Server errors, Bad Gateway, Service Unavailable, Gateway Timeout.
- `3xx` redirects (when the lib stops following them, e.g. with `WithoutRedirects()`).
- Empty bodies, weird Content-Types, malformed JSON in the body.

The HTTP exchange completed. The server replied. Whether you treat it as a failure is business logic, not a transport concern.

## Retry guidance

:::warning
Don't retry on 4xx. The server told you no for a reason. Retrying just hammers them and won't change the outcome. Fix the request.
:::

Rough rules:

| Situation | Retry? |
|---|---|
| Network error (DNS, refused, reset) | Yes, with backoff |
| Timeout | Yes, but bump the deadline if the upstream is slow |
| TLS handshake failure | No, fix the config |
| 4xx | No |
| 5xx + idempotent verb (GET, HEAD, PUT, DELETE) | Yes |
| 5xx + POST/PATCH | Only if you're sure the server didn't already process it. POST is **not** idempotent. |
| 429 Too Many Requests | Yes, but back off harder. Honor `Retry-After` if present. |

The session has built-in retry support. Default is **off** (issue #57 flipped the default from 3 to 0, because the old behavior silently retried POSTs on 5xx and broke idempotency assumptions):

```go
s := httpcloak.NewSession("chrome-latest",
    httpcloak.WithRetry(3),
    // or fine-grained:
    httpcloak.WithRetryConfig(3, 500*time.Millisecond, 10*time.Second, []int{500, 502, 503, 504}),
)
```

Pass status codes you actually want to retry on. Don't blindly retry on 4xx.

## A timeout test

Easiest way to verify your timeout handling: hit `httpbin.org/delay/N` with a context shorter than N.

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()

_, err := s.Get(ctx, "https://httpbin.org/delay/10")
fmt.Println(err)
// dial httpbin.org [h1]: dial tcp4 ...: i/o timeout
fmt.Println(errors.Is(err, context.DeadlineExceeded))
// true
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

s = httpcloak.Session(preset="chrome-latest", timeout=2)
try:
    r = s.get("https://httpbin.org/delay/10")
except httpcloak.HTTPCloakError as e:
    print("timed out:", e)
```

</TabItem>
<TabItem value="nodejs" label="Node.js">

```js
const s = new Session({ preset: "chrome-latest", timeout: 2 });
try {
  await s.get("https://httpbin.org/delay/10");
} catch (e) {
  console.log("timed out:", e.message);
}
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using var s = new Session(new SessionOptions {
    Preset = "chrome-latest",
    Timeout = 2,
});
try {
    s.Get("https://httpbin.org/delay/10");
} catch (HttpCloakException e) {
    Console.WriteLine($"timed out: {e.Message}");
}
```

</TabItem>
</Tabs>

`/delay/10` makes the server sit on the request for 10 seconds. With a 2-second timeout you'll get back a deadline-exceeded error, no Response.

## Logging tip

When debugging unknown failures in prod, log three things:

1. The full error message (don't strip the wrap chain).
2. The error's Go type (or Python class) so you can pattern-match later.
3. If you got a Response: the status code and a tail of the body.

The error message alone isn't always enough to tell DNS-failed from timeout-on-DNS-server. The type usually is.


---


<!-- source: docs/docs/requests-and-responses/auth.md -->

# Authentication

You can hand-roll an `Authorization` header just fine. But for anything more interesting than a static value, the auth helpers carry their weight: they know the wire format, they keep the header at the right offset Chrome would put it, and Digest actually does the challenge-response loop for you. Three flavors ship: Basic, Bearer, and Digest.

The Authorization header is also one of those headers fingerprinters watch for ordering drift. Build it through the helpers and it lands in the slot the preset reserved, not bolted onto the end like an afterthought.

## The Auth interface

Every helper satisfies the same tiny interface:

```go
type Auth interface {
    Apply(req *http.Request) error
    HandleChallenge(resp *http.Response, req *http.Request) (bool, error)
}
```

`Apply` writes the Authorization header onto the outgoing request. `HandleChallenge` is the second-pass hook: when the server hits you with a 401, the client calls `HandleChallenge` so the auth scheme can read `WWW-Authenticate`, work out what to send back, and tell the client whether to retry. Basic and Bearer don't have a challenge dance, so their `HandleChallenge` always returns `false`. Digest does the whole nonce-and-cnonce thing.

## Basic

Username and password, base64-encoded, slapped behind `Basic `. That's it.

```go
auth := client.NewBasicAuth("user", "passwd")
// or, on the client itself:
c.SetBasicAuth("user", "passwd")
```

`SetBasicAuth` is the shortcut: it builds a `BasicAuth` and parks it on the client so every request from that point gets the header. `NewBasicAuth` returns the value if you'd rather scope it per-request via `Request.Auth`.

## Bearer

Same shape, different scheme. Pass the token in, get `Authorization: Bearer <token>` on every request.

```go
auth := client.NewBearerAuth("eyJhbGc...")
// or:
c.SetBearerAuth("eyJhbGc...")
```

:::tip
Tokens expire. If yours rotates (OAuth refresh, short-lived JWTs, signed STS creds), don't bake the token into the client at construction. Wrap your refresh logic and call `SetBearerAuth` again whenever the token rolls. Or, if requests come from different identities, skip the session setter entirely and stamp `Request.Auth = client.NewBearerAuth(token)` on each call so a stale token never leaks into the wrong request.
:::

## Digest

Digest is the picky one. The server hands you a `WWW-Authenticate: Digest realm=..., nonce=..., qop=...` on the first 401. You hash username + password + realm into HA1, hash method + URI into HA2, then hash those together with the nonce, a counter, and a cnonce you generate. That hash goes back as the `Authorization: Digest response="..."`. The client does the second leg automatically:

```go
auth := client.NewDigestAuth("user", "passwd")
c.SetAuth(auth)
```

Flow on the wire:

1. Request fires with no Authorization header (Digest doesn't pre-emptively send).
2. Server replies 401 with the `WWW-Authenticate` challenge.
3. `HandleChallenge` parses realm, nonce, qop, opaque, algorithm.
4. Client retries the same request, this time with the computed `Digest response=...`.
5. Server returns the real response.

The nonce-counter (`nc`) increments on every reuse, so the same `DigestAuth` value can ride multiple requests without re-challenging. Discard it once the credentials change.

## Custom schemes via SetAuth

If your target speaks something weird (HMAC-SHA256 signed requests, AWS SigV4, a custom token-and-timestamp scheme), implement the `Auth` interface yourself and hand it to `SetAuth`:

```go
type myAuth struct { secret string }

func (a *myAuth) Apply(req *http.Request) error {
    sig := sign(req, a.secret)
    req.Header.Set("Authorization", "MyScheme "+sig)
    return nil
}

func (a *myAuth) HandleChallenge(resp *http.Response, req *http.Request) (bool, error) {
    return false, nil
}

c.SetAuth(&myAuth{secret: "..."})
```

`Apply` runs once per request right before send. If your signature depends on the body, hash it from the request before Apply returns. If it depends on a timestamp, generate a fresh one each call.

## Try it: Basic auth against httpbin

httpbin's `/basic-auth/user/passwd` endpoint returns 401 without credentials and 200 with the right ones. Quick way to confirm the helper's actually wiring the header.

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "context"
    "fmt"
    "io"

    "github.com/sardanioss/httpcloak/client"
)

func main() {
    c := client.NewClient("chrome-latest")
    defer c.Close()

    ctx := context.Background()

    // Without auth: 401
    resp, _ := c.Get(ctx, "https://httpbin.org/basic-auth/user/passwd", nil)
    fmt.Println("no-auth:", resp.StatusCode)
    resp.Body.Close()

    // With BasicAuth: 200
    c.SetBasicAuth("user", "passwd")
    resp, _ = c.Get(ctx, "https://httpbin.org/basic-auth/user/passwd", nil)
    fmt.Println("with-auth:", resp.StatusCode)
    body, _ := io.ReadAll(resp.Body)
    resp.Body.Close()
    fmt.Println(string(body))
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

with httpcloak.Session(preset="chrome-latest") as s:
    # Without auth: 401
    r = s.get("https://httpbin.org/basic-auth/user/passwd")
    print("no-auth:", r.status_code)

    # With auth tuple: 200
    r = s.get(
        "https://httpbin.org/basic-auth/user/passwd",
        auth=("user", "passwd"),
    )
    print("with-auth:", r.status_code)
    print(r.text)
```

</TabItem>
<TabItem value="nodejs" label="Node.js">

```js
const { Session } = require("httpcloak");

const s = new Session({ preset: "chrome-latest" });

// Without auth: 401
let r = await s.get("https://httpbin.org/basic-auth/user/passwd");
console.log("no-auth:", r.status);

// With Authorization header: 200
const creds = Buffer.from("user:passwd").toString("base64");
r = await s.get("https://httpbin.org/basic-auth/user/passwd", {
  headers: { Authorization: `Basic ${creds}` },
});
console.log("with-auth:", r.status);
console.log(r.text);

s.close();
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;
using System;
using System.Text;

using var s = new Session(new SessionOptions { Preset = "chrome-latest" });

// Without auth: 401
var r = s.Get("https://httpbin.org/basic-auth/user/passwd");
Console.WriteLine($"no-auth: {r.StatusCode}");

// With auth header: 200
var creds = Convert.ToBase64String(Encoding.ASCII.GetBytes("user:passwd"));
var headers = new Dictionary<string, string> {
    { "Authorization", $"Basic {creds}" }
};
r = s.Get("https://httpbin.org/basic-auth/user/passwd", headers: headers);
Console.WriteLine($"with-auth: {r.StatusCode}");
Console.WriteLine(r.Text);
```

</TabItem>
</Tabs>

Run the Go example and you'll see:

```text
no-auth: 401
with-auth: 200
{
  "authenticated": true,
  "user": "user"
}
```

## Per-request vs session-level

Two scopes, same idea as headers.

**Session-level** (the `Set*Auth` family on the client) parks an Auth on the client. Every request from that point on gets it applied automatically. Good for "this whole script is one identity" situations.

**Per-request** (the `Auth` field on `Request`) overrides the session-level Auth for one call. If you set both, the request-level wins. Use it when one client juggles multiple identities, or when most of your traffic is anonymous and only a few endpoints need credentials.

```go
// session default
c.SetBearerAuth("anon-token")

// this single request uses a different token
resp, _ := c.Do(ctx, &client.Request{
    Method: "GET",
    URL:    "https://api.example.com/admin",
    Auth:   client.NewBearerAuth("admin-token"),
})
```

One safety bit baked into the redirect handler: if a redirect crosses origins, the client drops `Authorization` (and `Proxy-Authorization`) before following. Same rule for HTTPS to HTTP downgrades. Real browsers do this and so does httpcloak, so credentials don't leak to whatever domain the response decided to bounce you to.


---


<!-- source: docs/docs/requests-and-responses/hooks.md -->

# Hooks

Hooks are middleware. PreRequest fires right before a request hits the wire, PostResponse fires right after the response lands. Use them to mutate, log, transform, or kill a request at the gate. Same idea as Express middleware or `requests.Session.hooks`, just with httpcloak's types.

Two slots:

- **PreRequest**: gets the outgoing request. Mutate headers, attach a request ID, or return an error to abort.
- **PostResponse**: gets the parsed response. Inspect status, pull a token out of a header, log timing.

## PreRequestHook

```go
type PreRequestHook func(req *http.Request) error
```

You get the actual `*http.Request` (the `sardanioss/http` one) right before the transport ships it. Anything you change lands on the wire: headers, URL, method, body. Return a non-nil error and the whole request gets cancelled before a single byte goes out. The error bubbles back to the caller wrapped as `pre-request hook failed: <your err>`.

What you'll typically do here:

- Inject a correlation header like `X-Request-ID` or a tracing span ID
- Refresh a bearer token if it's near expiry
- Block the request based on a URL allowlist (return an error)
- Log the outbound URL and method for telemetry

## PostResponseHook

```go
type PostResponseHook func(resp *Response) error
```

Fires once the response is fully built (status, headers, body buffered or streaming). You can read `resp.StatusCode`, `resp.Headers`, `resp.Timing`, `resp.Protocol`, the lot. Returning an error here is purely advisory. Hooks are observability, not control flow, so the response still flows back to the caller untouched. If you want to fail loud on a 5xx, do it in your call site, not the hook.

What you'll typically do here:

- Log status + timing for every response
- Extract a `X-Auth-Token` from response headers and stash it
- Warn or page on 4xx / 5xx clusters
- Buffer the body for a debug capture (call `resp.Bytes()` inside the hook)

## Order and chaining

Hooks fire in the order you registered them. Add three PreRequest hooks and they run 1, 2, 3 every request. PreRequest hooks short-circuit on the first error, so if hook 2 returns an error, hook 3 never fires and the request never goes out.

Same deal for PostResponse, except errors don't stop anything. Each hook runs to completion regardless.

## Wiping hooks

`ClearHooks()` drops everything. Useful between test cases when you want a clean slate.

```go
c.ClearHooks()
```

There's also `c.Hooks().ClearPreRequest()` and `c.Hooks().ClearPostResponse()` if you only want to nuke one side.

## Example: log every URL, warn on errors

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "context"
    "fmt"

    http "github.com/sardanioss/http"
    "github.com/sardanioss/httpcloak/client"
)

func main() {
    c := client.NewClient("chrome-latest")
    defer c.Close()

    c.OnPreRequest(func(req *http.Request) error {
        fmt.Printf("[pre] %s %s\n", req.Method, req.URL)
        req.Header.Set("X-Request-ID", "abc-123")
        return nil
    })

    c.OnPostResponse(func(resp *client.Response) error {
        if resp.StatusCode >= 400 {
            fmt.Printf("[post] WARN %d %s\n", resp.StatusCode, resp.FinalURL)
        } else {
            fmt.Printf("[post] ok   %d %s\n", resp.StatusCode, resp.FinalURL)
        }
        return nil
    })

    resp, _ := c.Get(context.Background(), "https://httpbin.org/get", nil)
    resp.Close()

    resp, _ = c.Get(context.Background(), "https://httpbin.org/status/418", nil)
    resp.Close()
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

c = httpcloak.Client(preset="chrome-latest")

def on_pre(req):
    print(f"[pre] {req.method} {req.url}")
    req.headers["X-Request-ID"] = "abc-123"

def on_post(resp):
    tag = "WARN" if resp.status_code >= 400 else "ok  "
    print(f"[post] {tag} {resp.status_code} {resp.final_url}")

c.on_pre_request(on_pre)
c.on_post_response(on_post)

c.get("https://httpbin.org/get")
c.get("https://httpbin.org/status/418")
```

</TabItem>
<TabItem value="nodejs" label="Node.js">

```js
const { Client } = require("httpcloak");

const c = new Client({ preset: "chrome-latest" });

c.onPreRequest((req) => {
  console.log(`[pre] ${req.method} ${req.url}`);
  req.headers["X-Request-ID"] = "abc-123";
});

c.onPostResponse((resp) => {
  const tag = resp.statusCode >= 400 ? "WARN" : "ok  ";
  console.log(`[post] ${tag} ${resp.statusCode} ${resp.finalUrl}`);
});

await c.get("https://httpbin.org/get");
await c.get("https://httpbin.org/status/418");
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using HttpCloak;

using var c = new Client(preset: "chrome-latest");

c.OnPreRequest(req => {
    Console.WriteLine($"[pre] {req.Method} {req.Url}");
    req.Headers["X-Request-ID"] = "abc-123";
});

c.OnPostResponse(resp => {
    var tag = resp.StatusCode >= 400 ? "WARN" : "ok  ";
    Console.WriteLine($"[post] {tag} {resp.StatusCode} {resp.FinalUrl}");
});

await c.GetAsync("https://httpbin.org/get");
await c.GetAsync("https://httpbin.org/status/418");
```

</TabItem>
</Tabs>

What you'll see on stdout:

```text
[pre] GET https://httpbin.org/get
[post] ok   200 https://httpbin.org/get
[pre] GET https://httpbin.org/status/418
[post] WARN 418 https://httpbin.org/status/418
```

Two requests, four hook fires. The pre hook stamped both with `X-Request-ID: abc-123`, the post hook flagged the teapot.

:::warning
Hooks run on the request's hot path, synchronously, every single request. A hook that does network I/O or grabs a contended mutex tanks throughput. If your hook needs to hit a database or push to a queue, do it on a background goroutine / async task and return immediately. Heavy hooks turn a 50ms request into a 500ms one and you'll spend an afternoon wondering why.
:::

## Pulling a token out of a response

Quick pattern. Server sets `X-Auth-Token` on login. Stash it from a hook so the rest of your code can grab it without parsing every response by hand.

```go
var token string

c.OnPostResponse(func(resp *client.Response) error {
    if t := resp.GetHeader("X-Auth-Token"); t != "" {
        token = t
    }
    return nil
})
```

`GetHeader` is case-insensitive so you don't have to worry about whether the server sent `X-Auth-Token` or `x-auth-token`.

## Blocking a request at the gate

Return an error from PreRequest and the request never goes out. Handy for kill-switches or allowlists.

```go
allowed := map[string]bool{"api.example.com": true}

c.OnPreRequest(func(req *http.Request) error {
    if !allowed[req.URL.Host] {
        return fmt.Errorf("host %q not on allowlist", req.URL.Host)
    }
    return nil
})
```

The caller sees `pre-request hook failed: host "evil.example.com" not on allowlist` and zero bytes hit the wire.


---


<!-- source: docs/docs/bindings/index.md -->

# Bindings

Same lib, four languages. Go's the native one. The rest call into a cgo-built shared library, so you're getting the exact same wire behaviour everywhere.

## In this section

- [Go](./go): the native API, idiomatic Go
- [Python](./python): a `requests`-shaped wrapper over cgo
- [Node.js](./nodejs): koffi-backed, ESM and CJS both work
- [.NET](./dotnet): P/Invoke wrapper for .NET 8+


---


<!-- source: docs/docs/bindings/go.md -->

# Go

Go's the native API. Every other binding (Python, Node, .NET) calls into the cgo wrapper that wraps this exact code, so the Go surface is the most direct way in and usually the fastest. If your project's already in Go, just use this. No FFI hops, no JSON marshalling between two languages, no native binary to ship.

## Install

```bash
go get github.com/sardanioss/httpcloak
```

Module path is `github.com/sardanioss/httpcloak`. Public package name is `httpcloak`.

## Quick start

```go
package main

import (
	"context"
	"fmt"
	"time"

	"github.com/sardanioss/httpcloak"
)

func main() {
	s := httpcloak.NewSession("chrome-latest",
		httpcloak.WithSessionTimeout(20*time.Second),
	)
	defer s.Close()

	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
	defer cancel()

	resp, err := s.Get(ctx, "https://tls.peet.ws/api/all")
	if err != nil {
		panic(err)
	}
	defer resp.Close()

	body, _ := resp.Text()
	fmt.Println("status:", resp.StatusCode)
	fmt.Println("proto:", resp.Protocol)
	fmt.Println("len:", len(body))
}
```

Three things worth flagging:

- `NewSession` takes a preset name string and a variadic list of `SessionOption` values. Full preset catalog at [Presets](/fingerprinting/presets).
- `ctx context.Context` is always the first arg. Idiomatic Go, and you get cancellation and deadlines for free.
- `defer s.Close()` and `defer resp.Close()`. The session owns connections and a cookie jar. The response body is an `io.ReadCloser` you must drain or close.

## Two API levels

httpcloak ships two API levels. Most folks want the session level.

### `Session` (recommended)

Persistent. Holds cookies, TLS resumption tickets, ECH configs, the connection pool. Reach for this when you're hitting the same host more than once, when you care about cookies, or when you want browser-style refresh / warmup behaviour.

```go
s := httpcloak.NewSession("chrome-latest")
defer s.Close()
```

### `Client` (lower level)

Stateless wrapper for one-off requests. No cookie jar. Each `Do()` builds a fresh request through the same transport stack. Use this when you genuinely don't want state between requests.

```go
c := httpcloak.New("chrome-latest", httpcloak.WithTimeout(15*time.Second))
defer c.Close()

resp, err := c.Get(ctx, "https://example.com")
```

The two surfaces look similar on purpose, but the option types are different: `Option` for `Client`, `SessionOption` for `Session`. Don't mix them.

## Session methods

Full method list on `*httpcloak.Session`. Read top to bottom.

### Construction

```go
func NewSession(preset string, opts ...SessionOption) *Session
func LoadSession(path string) (*Session, error)
func UnmarshalSession(data []byte) (*Session, error)
```

`NewSession` is the normal entry point. `LoadSession` and `UnmarshalSession` rebuild a session from a file or JSON blob you saved earlier, see [Session save & restore](/connection-lifecycle/session-save-restore).

### Core request

```go
func (s *Session) Do(ctx context.Context, req *Request) (*Response, error)
func (s *Session) DoWithBody(ctx context.Context, req *Request, bodyReader io.Reader) (*Response, error)
func (s *Session) Get(ctx context.Context, url string) (*Response, error)
```

The Go session API is sparser than Python's or Node's, on purpose. `Get` is the only one-call shortcut. For `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`, build a `Request` struct and call `Do`:

```go
req := &httpcloak.Request{
	Method:  "POST",
	URL:     "https://httpbin.org/post",
	Headers: map[string][]string{"Content-Type": {"application/json"}},
	Body:    bytes.NewReader([]byte(`{"hello":"world"}`)),
}
resp, err := s.Do(ctx, req)
```

`DoWithBody` takes the body separately as an `io.Reader`. Reach for it when you're streaming an upload and don't want to buffer the body upfront.

### Streaming responses

```go
func (s *Session) DoStream(ctx context.Context, req *Request) (*StreamResponse, error)
func (s *Session) GetStream(ctx context.Context, url string) (*StreamResponse, error)
func (s *Session) GetStreamWithHeaders(ctx context.Context, url string, headers map[string][]string) (*StreamResponse, error)
```

`StreamResponse` exposes `Read(p []byte) (int, error)`, `ReadChunk(size int) ([]byte, error)`, `ReadAll() ([]byte, error)`, and `Close() error`. Use `DoStream` for downloads where buffering the whole body in memory is a bad idea: videos, big JSON dumps, archives.

Streaming won't auto-follow redirects. If you get a 3xx back, you handle it manually.

### Lifecycle

```go
func (s *Session) Close()
func (s *Session) Refresh()
func (s *Session) RefreshWithProtocol(protocol string) error
func (s *Session) Warmup(ctx context.Context, url string) error
func (s *Session) Fork(n int) []*Session
```

- `Close()` releases the connection pool and the cookie jar. Always defer it.
- `Refresh()` drops connections but keeps cookies and TLS tickets. Like a browser hitting F5.
- `RefreshWithProtocol("h1" | "h2" | "h3" | "auto")` does a refresh and switches the wire protocol for next requests. Handy for warming TLS on H3 then serving H2 with resumption.
- `Warmup(ctx, url)` does a real-browser-style page load: HTML first, then subresources with proper priorities, headers, and timing. Pop this before hitting an antibot endpoint.
- `Fork(n)` makes `n` child sessions that share cookies and TLS resumption with the parent but get their own connections. Same browser, multiple tabs.

### Persistence

```go
func (s *Session) Save(path string) error
func (s *Session) Marshal() ([]byte, error)
```

`Save` writes a JSON blob (cookies, TLS session tickets, ECH configs) to disk. `Marshal` returns the same blob as bytes if you'd rather stuff it into Redis or a database. Round-trip with `LoadSession` / `UnmarshalSession`.

### Cookie management

```go
func (s *Session) GetCookies() []CookieInfo
func (s *Session) GetCookiesDetailed() []CookieInfo
func (s *Session) SetCookie(cookie CookieInfo)
func (s *Session) DeleteCookie(name, domain string)
func (s *Session) ClearCookies()
```

`CookieInfo` is a type alias for `session.CookieState` and carries the full `name`, `value`, `domain`, `path`, `expires`, `maxAge`, `secure`, `httpOnly`, `sameSite` set.

### Proxy management

```go
func (s *Session) SetProxy(proxyURL string)
func (s *Session) SetTCPProxy(proxyURL string)
func (s *Session) SetUDPProxy(proxyURL string)
func (s *Session) GetProxy() string
func (s *Session) GetTCPProxy() string
func (s *Session) GetUDPProxy() string
```

`SetProxy("")` flips the session back to direct. The split TCP/UDP proxy methods exist for when you want H1/H2 over an HTTP proxy and H3 over MASQUE. See [Proxies overview](/proxies/overview).

### Header order

```go
func (s *Session) SetHeaderOrder(order []string)
func (s *Session) GetHeaderOrder() []string
```

Override the preset's header order. Pass lowercase names. Empty slice resets to the preset default.

### Other

```go
func (s *Session) SetSessionIdentifier(sessionId string)
```

Tags this session for distributed TLS cache key isolation when used behind a `LocalProxy`. Most users won't touch this.

## Client methods

`*httpcloak.Client` for one-off requests:

```go
func New(preset string, opts ...Option) *Client
func (c *Client) Do(ctx context.Context, req *Request) (*Response, error)
func (c *Client) Get(ctx context.Context, url string) (*Response, error)
func (c *Client) GetWithHeaders(ctx context.Context, url string, headers map[string][]string) (*Response, error)
func (c *Client) Post(ctx context.Context, url string, body io.Reader, contentType string) (*Response, error)
func (c *Client) PostJSON(ctx context.Context, url string, body []byte) (*Response, error)
func (c *Client) PostForm(ctx context.Context, url string, body []byte) (*Response, error)
func (c *Client) PostMultipart(ctx context.Context, url string, fields []MultipartField) (*Response, error)
func (c *Client) Close()
```

`Client` only takes `WithTimeout` and `WithProxy`. Need more knobs? Switch to `Session`.

## Request struct

```go
type Request struct {
	Method  string
	URL     string
	Headers map[string][]string // matches http.Header
	Body    io.Reader
	Timeout time.Duration
	TLSOnly *bool // per-request override
}
```

`Headers` is `map[string][]string` to match the stdlib `http.Header` shape and let you send the same header more than once. Lowercase the keys so they line up with the preset's order.

`TLSOnly` set to `&true` skips the preset's HTTP headers for this single request (TLS fingerprint still applies). `nil` means use the session's setting.

## Response struct

```go
type Response struct {
	StatusCode int
	Headers    map[string][]string
	Body       io.ReadCloser
	FinalURL   string
	Protocol   string             // "http/1.1", "h2", "h3"
	History    []*RedirectInfo
}
```

Methods:

```go
func (r *Response) Close() error
func (r *Response) Bytes() ([]byte, error)
func (r *Response) Text() (string, error)
func (r *Response) JSON(v interface{}) error
func (r *Response) GetHeader(key string) string
func (r *Response) GetHeaders(key string) []string
```

`Bytes`, `Text`, `JSON` cache the body after the first read. `GetHeader` / `GetHeaders` look up case-insensitively against the lowercase keys.

`History` is the list of intermediate redirects you went through. Each entry has `StatusCode`, `URL`, and `Headers`.

## Idiomatic patterns

### Always defer Close

```go
s := httpcloak.NewSession("chrome-latest")
defer s.Close()
// ...
resp, err := s.Get(ctx, url)
if err != nil { return err }
defer resp.Close()
```

The session owns network resources. The response body is an `io.ReadCloser` you have to close.

### Pass context

Always thread a `context.Context` through. That's how cancellation, deadlines, and request-scoped values move around in Go. httpcloak honours `ctx.Done()` everywhere: at dial, at TLS handshake, at body reads.

```go
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
resp, err := s.Get(ctx, url)
```

### Decode JSON straight into a struct

```go
var payload struct {
	UserAgent string `json:"user_agent"`
	IP        string `json:"ip"`
}
if err := resp.JSON(&payload); err != nil {
	return err
}
```

`Response.JSON` reads the body once, caches the bytes, then runs `encoding/json` on them.

### Errors

httpcloak returns plain `error` values. Use `errors.Is` against `context.DeadlineExceeded` or `context.Canceled` to tell timeout errors apart from anything else.

## Concurrency

The session's safe for concurrent use. It holds a `sync.RWMutex` around mutable state (cookies, header order, proxy switches), and the underlying transport pool handles concurrent dials.

In practice:

- One `*Session`, many goroutines making requests at once. Fine.
- One `*Session`, one goroutine calling `SetProxy()` while another calls `Get()`. Also fine, the lock orders them.
- Reading the same `Response.Body` from multiple goroutines at once. Don't. Each response is single-reader.

If you want true parallelism with shared cookie state, use `Fork(n)` to get sibling sessions. Each fork has its own connection pool but inherits the parent's cookies and TLS tickets. That's the closest you'll get to "browser tabs" behaviour.

## Custom fingerprints

```go
s := httpcloak.NewSession("chrome-latest",
	httpcloak.WithCustomFingerprint(httpcloak.CustomFingerprint{
		JA3:    "771,4865-4866-4867-...,0-23-65281-...,29-23-24,0",
		Akamai: "1:65536;2:0;4:6291456;6:262144|15663105|0|m,a,s,p",
	}),
)
```

Setting `JA3` automatically flips the session into TLS-only mode (HTTP headers from the preset get skipped). See [Custom JA3](/fingerprinting/custom-ja3) and [Akamai shorthand](/fingerprinting/akamai-shorthand).

## What about HTTP/3?

Same `Session.Get`, `Session.Do`, etc. The transport picks the protocol via Alt-Svc, ALPN, and a small race between H3 and H2 dials. Force a specific one with `WithForceHTTP1`, `WithForceHTTP2`, `WithForceHTTP3`. The `Response.Protocol` field tells you what actually went on the wire.

## See also

- [Options reference](/reference/options): every `SessionOption` flag with a one-line description.
- [Connection lifecycle](/connection-lifecycle): refresh, warmup, fork, save, load.
- [Cookies and state](/cookies-and-state): jar internals and per-request overrides.
- [Proxies](/proxies): HTTP, SOCKS5, MASQUE, source-IP binding.


---


<!-- source: docs/docs/bindings/python.md -->

# Python

The Python binding's a Pythonic wrapper around the cgo shared library. Same C ABI as the Node and .NET bindings underneath, but the surface looks like the `requests` lib: `Session`, `.get()`, `.post()`, `.json()`, kwargs everywhere, `with`-statements for cleanup.

If you've used `requests`, you'll be at home in five minutes.

## Install

```bash
pip install httpcloak
```

The wheel ships the prebuilt shared library for your platform. Linux x86_64 / arm64, macOS x86_64 / arm64, Windows x86_64 are all covered. Python 3.8 and up.

If pip's resolver picks the right wheel, you're done. If you're on something unusual you'll have to build from source, see the GitHub README for that.

## Quick start

```python
import httpcloak

with httpcloak.Session(preset="chrome-146") as s:
    r = s.get("https://tls.peet.ws/api/all")
    print(r.status_code)
    print(r.json()["user_agent"])
```

The `with` block makes sure the session closes cleanly even if you raise. Same vibe as a `requests.Session()`, just with the TLS fingerprint baked in.

## Module-level shortcuts

For one-off requests, there are top-level functions that mirror `requests`:

```python
import httpcloak

r = httpcloak.get("https://tls.peet.ws/api/all")
r = httpcloak.post("https://httpbin.org/post", json={"hello": "world"})
r = httpcloak.put(...)
r = httpcloak.delete(...)
r = httpcloak.patch(...)
r = httpcloak.head(...)
r = httpcloak.options(...)
r = httpcloak.request("GET", url)
```

These all share a hidden default `Session`. To configure that default (preset, headers, proxy, retry, etc.):

```python
httpcloak.configure(
    preset="chrome-146",
    headers={"Authorization": "Bearer xxx"},
    proxy="http://user:pass@proxy:8080",
    retry=3,
)
r = httpcloak.get("https://example.com")  # uses the configured defaults
```

For anything beyond a few requests, use an explicit `Session`. The default-session path's mostly there for porting `requests`-style scripts in a hurry.

## `Session`

The main class. Constructor signature (kwargs, all optional):

```python
httpcloak.Session(
    preset: str = "chrome-146",
    proxy: Optional[str] = None,
    tcp_proxy: Optional[str] = None,
    udp_proxy: Optional[str] = None,
    timeout: int = 30,
    http_version: str = "auto",       # "auto", "h1", "h2", "h3"
    verify: bool = True,
    allow_redirects: bool = True,
    max_redirects: int = 10,
    retry: int = 0,                    # 0 = retries off
    retry_on_status: Optional[List[int]] = None,
    retry_wait_min: int = 500,
    retry_wait_max: int = 10000,
    prefer_ipv4: bool = False,
    auth: Optional[Tuple[str, str]] = None,
    connect_to: Optional[Dict[str, str]] = None,
    ech_config_domain: Optional[str] = None,
    tls_only: bool = False,
    quic_idle_timeout: int = 0,
    local_address: Optional[str] = None,
    key_log_file: Optional[str] = None,
    enable_speculative_tls: bool = False,
    switch_protocol: Optional[str] = None,
    without_cookie_jar: bool = False,
    ja3: Optional[str] = None,
    akamai: Optional[str] = None,
    extra_fp: Optional[Dict[str, Any]] = None,
    tcp_ttl: Optional[int] = None,
    tcp_mss: Optional[int] = None,
    tcp_window_size: Optional[int] = None,
    tcp_window_scale: Optional[int] = None,
    tcp_df: Optional[bool] = None,
)
```

Full description for each kwarg: [Options reference](/reference/options).

`retry` defaults to `0`. The previous `3` default silently retried POST/PUT/PATCH on 5xx, which broke idempotency expectations. Set it explicitly to a positive integer if you want retries.

### Request methods

```python
session.get(url, params=None, headers=None, cookies=None, auth=None,
            timeout=None, stream=False, fetch_mode=None) -> Response
session.post(url, data=None, json=None, files=None, params=None,
             headers=None, cookies=None, auth=None, timeout=None,
             stream=False, fetch_mode=None) -> Response
session.put(url, data=None, json=None, ...) -> Response
session.patch(url, data=None, json=None, ...) -> Response
session.delete(url, ...) -> Response
session.head(url, ...) -> Response
session.options(url, ...) -> Response
session.request(method, url, data=None, json=None, ...) -> Response
```

Pass `stream=True` to get a `StreamResponse` instead. Pass `json={...}` and the body's JSON-encoded with `Content-Type: application/json` set. Pass `data={...}` for form encoding. Pass `files={...}` for multipart uploads.

### Streaming methods

```python
session.get_stream(url, ...) -> StreamResponse
session.post_stream(url, ...) -> StreamResponse
session.put_stream(url, ...) -> StreamResponse
session.patch_stream(url, ...) -> StreamResponse
session.delete_stream(url, ...) -> StreamResponse
session.request_stream(method, url, ...) -> StreamResponse
```

`StreamResponse` supports `iter_content(chunk_size=8192)`, `iter_lines()`, `content`, `text`, `json()`, and the `with`-block protocol. 1:1 match for `requests`'s streaming API.

```python
with session.get("https://example.com/big.zip", stream=True) as r:
    with open("big.zip", "wb") as f:
        for chunk in r.iter_content(chunk_size=64 * 1024):
            f.write(chunk)
```

### Fast methods

```python
session.get_fast(url, ...) -> FastResponse
session.post_fast(url, ...) -> FastResponse
session.request_fast(method, url, ...) -> FastResponse
session.put_fast(...) / delete_fast(...) / patch_fast(...) -> FastResponse
```

`FastResponse` skips a few allocations and exposes `.content` as a `memoryview` instead of `bytes`. Reach for it when you're pulling huge bodies and want zero-copy access. Read the docstring before relying on the buffer, it can be reused on later requests, so copy with `bytes(r.content)` if you need to hold onto it.

### Lifecycle

```python
session.close()
session.refresh(switch_protocol: Optional[str] = None)
session.warmup(url: str, timeout: Optional[int] = None)
session.fork(n: int = 1) -> List[Session]
```

`refresh()` mirrors a browser F5: keeps cookies and TLS tickets, drops connections. Pass `switch_protocol="h2"` to also flip the wire protocol. `warmup()` simulates a real page load. `fork(n)` returns `n` sibling sessions that share cookies and TLS state but get their own connection pools.

### Persistence

```python
session.save(path: str)
session.marshal() -> str
Session.load(path: str) -> Session
Session.unmarshal(data: str) -> Session
```

`save` writes a JSON file with cookies, TLS tickets, and ECH configs. `marshal` hands you the same blob as a string, perfect for stashing in Redis or a database. `Session.load` and `Session.unmarshal` are classmethods.

### Cookie management

```python
session.cookies                           # dict (deprecated flat shape)
session.get_cookies() -> Dict[str, str]   # deprecated
session.get_cookies_detailed() -> List[Cookie]
session.get_cookie(name) -> Optional[str]      # deprecated
session.get_cookie_detailed(name) -> Optional[Cookie]
session.set_cookie(name, value, domain="", path="/", secure=False,
                   http_only=False, same_site="", max_age=0, expires=None)
session.delete_cookie(name, domain="")
session.clear_cookies()
```

The `_detailed` variants return full `Cookie` objects with `domain`, `path`, `expires`, `max_age`, `secure`, `http_only`, `same_site`. The flat-dict variants will eventually return the detailed shape too, that's why they're tagged deprecated. Migrate when you can.

### Proxy management

```python
session.set_proxy(proxy_url: str)
session.set_tcp_proxy(proxy_url: str)
session.set_udp_proxy(proxy_url: str)
session.get_proxy() -> str
session.get_tcp_proxy() -> str
session.get_udp_proxy() -> str
```

Empty string flips back to direct.

### Header order

```python
session.set_header_order(order: List[str])  # lowercase names
session.get_header_order() -> List[str]
```

### Misc

```python
session.set_session_identifier(session_id: str)
session.headers              # dict for default headers, mutate freely
session.auth                 # tuple for default basic auth
```

## Pythonic conventions

- snake_case names everywhere. `get_cookies`, `set_proxy`, `clear_cookies`, never `getCookies`.
- Kwargs over positional once you're past `url`. `session.get("...", headers=..., timeout=...)` reads way better than positional params.
- Context managers. `with httpcloak.Session(...) as s:` and `with session.get(url, stream=True) as r:` both work.
- Exceptions. Errors raise `httpcloak.HTTPCloakError`. `r.raise_for_status()` raises on `>= 400`, same as `requests`.
- `r.json()` parses, `r.text` gives a `str`, `r.content` (and `r.body`) gives `bytes`.

## `Response`

```python
r.status_code: int
r.ok: bool                          # True if status_code < 400
r.reason: str                        # "OK", "Not Found", etc.
r.headers: Dict[str, str]
r.body: bytes
r.content: bytes                     # alias of body
r.text: str
r.encoding: Optional[str]
r.url: str                           # final URL after redirects
r.final_url: str                     # alias
r.protocol: str                      # "http/1.1", "h2", "h3"
r.elapsed: float                     # seconds
r.cookies: List[Cookie]
r.history: List[RedirectInfo]
r.json(**kwargs) -> Any
r.raise_for_status()
```

`raise_for_status()` raises `HTTPCloakError` on 4xx/5xx.

## Concurrency

The session's thread-safe for concurrent requests. The Go transport pool underneath handles parallel dials, and the Python wrapper holds the GIL only briefly when entering the C call.

For asyncio: there's no native async surface on the public API yet. The lib has an internal async callback manager, but most folks run httpcloak in a `concurrent.futures.ThreadPoolExecutor` or `asyncio.to_thread` and that performs fine, since the request is mostly waiting on cgo with the GIL released.

```python
import asyncio

async def fetch(s, url):
    return await asyncio.to_thread(s.get, url)

async def main():
    with httpcloak.Session(preset="chrome-146") as s:
        results = await asyncio.gather(
            fetch(s, "https://example.com"),
            fetch(s, "https://example.org"),
            fetch(s, "https://httpbin.org/get"),
        )
        for r in results:
            print(r.status_code)

asyncio.run(main())
```

## Custom fingerprints

Pass `ja3=` and / or `akamai=` to the `Session` constructor:

```python
with httpcloak.Session(
    preset="chrome-146",
    ja3="771,4865-4866-4867-49195-49199,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513-21,29-23-24,0",
    akamai="1:65536;2:0;4:6291456;6:262144|15663105|0|m,a,s,p",
) as s:
    r = s.get("https://tls.peet.ws/api/all")
```

Setting `ja3` flips the session into TLS-only mode automatically. See [Custom JA3](/fingerprinting/custom-ja3).

## Other building blocks

```python
httpcloak.LocalProxy(...)            # local HTTP proxy that fingerprints any client
httpcloak.PresetPool(path)           # rotate through a JSON-defined preset pool
httpcloak.SessionCacheBackend(...)   # plug a Redis-style backend for distributed TLS resumption
httpcloak.load_preset(path)          # register a JSON preset file
httpcloak.load_preset_from_json(...) # register a JSON preset string
httpcloak.unregister_preset(name)
httpcloak.describe_preset(name)
httpcloak.available_presets()
httpcloak.version()
httpcloak.set_ech_dns_servers([...])
httpcloak.get_ech_dns_servers()
```

`LocalProxy` runs an HTTP proxy server that applies the fingerprint to whatever HTTP client you point at it. `PresetPool` and the JSON loaders are covered in [JSON preset builder](/fingerprinting/json-preset-builder). `SessionCacheBackend` plugs into [Session save and restore](/connection-lifecycle/session-save-restore).

## See also

- [Options reference](/reference/options): every kwarg with one line each.
- [Cookies and state](/cookies-and-state).
- [Proxies](/proxies).


---


<!-- source: docs/docs/bindings/nodejs.md -->

# Node.js

The Node.js binding wraps the cgo shared library through [koffi](https://koffi.dev/), a fast FFI lib that doesn't need a node-gyp build step. Both ESM (`import`) and CommonJS (`require`) work. TypeScript types ship in the package, no separate `@types` install.

## Install

```bash
npm install httpcloak
```

The main package pulls in koffi and a per-platform native binary as an `optionalDependencies` entry. So a Linux x64 user transparently gets `@httpcloak/linux-x64`, a macOS arm64 user gets `@httpcloak/darwin-arm64`, and so on. If npm picks the wrong one (rare on weird platforms or in Docker buildx setups), force the right one:

```bash
npm install httpcloak @httpcloak/linux-x64
```

Supported platforms: `linux-x64`, `linux-arm64`, `darwin-x64`, `darwin-arm64`, `win32-x64`. Node 14+.

## Quick start

ESM:

```js

const s = new Session({ preset: "chrome-146" });
try {
  const r = await s.get("https://tls.peet.ws/api/all");
  console.log(r.statusCode, r.json().user_agent);
} finally {
  s.close();
}
```

CommonJS:

```js
const { Session } = require("httpcloak");

(async () => {
  const s = new Session({ preset: "chrome-146" });
  try {
    const r = await s.get("https://tls.peet.ws/api/all");
    console.log(r.statusCode);
  } finally {
    s.close();
  }
})();
```

There's no `using` declaration in standard JS yet, so `try / finally` is how you guarantee `close()`. If your TypeScript target is `ES2024+` you can do `using s = new Session(...)` once we ship `Symbol.asyncDispose` support.

## koffi vs napi

Worth flagging upfront: this binding's FFI-based, not a node-native module. Two practical knock-ons:

- **No prebuild compile step.** `npm install` just downloads JS plus the per-platform `.so` / `.dylib` / `.dll`. Faster install, no compiler dependency.
- **Different runtime constraints than typical native modules.** Worker threads can use the binding fine. Buffer ownership rules are spelled out per-method (FastResponse calls out which buffers are pool-managed in its docstring).

If you've worked with koffi before, none of this is news. If you haven't, just know that calling into the lib has a small (microseconds) FFI overhead and the binding handles type marshalling for you.

## `Session`

Constructor takes an options object:

```ts
new Session(options?: SessionOptions);
```

`SessionOptions` (all optional):

```ts
{
  preset?: string;             // "chrome-146" by default
  proxy?: string;
  tcpProxy?: string;
  udpProxy?: string;
  timeout?: number;            // seconds, default 30
  httpVersion?: string;        // "auto" | "h1" | "h2" | "h3"
  verify?: boolean;            // SSL verify, default true
  allowRedirects?: boolean;
  maxRedirects?: number;
  retry?: number;
  retryOnStatus?: number[];
  retryWaitMin?: number;       // ms
  retryWaitMax?: number;       // ms
  preferIpv4?: boolean;
  auth?: [string, string];
  connectTo?: Record<string, string>;
  echConfigDomain?: string;
  tlsOnly?: boolean;
  quicIdleTimeout?: number;    // seconds
  localAddress?: string;
  keyLogFile?: string;
  enableSpeculativeTls?: boolean;
  switchProtocol?: string;
  withoutCookieJar?: boolean;
  ja3?: string;
  akamai?: string;
  extraFp?: Record<string, any>;
}
```

Full per-flag description: [Options reference](/reference/options).

### Async request methods

All return `Promise<Response>`:

```ts
session.get(url, options?): Promise<Response>;
session.post(url, options?): Promise<Response>;
session.put(url, options?): Promise<Response>;
session.delete(url, options?): Promise<Response>;
session.patch(url, options?): Promise<Response>;
session.head(url, options?): Promise<Response>;
session.options(url, options?): Promise<Response>;
session.request(method, url, options?): Promise<Response>;
```

### Sync variants

```ts
session.getSync(url, options?): Response;
session.postSync(url, options?): Response;
session.requestSync(method, url, options?): Response;
```

These block the event loop. Don't use them inside an async server. They're here for scripts and CLIs where you genuinely don't have a loop to worry about.

### `RequestOptions`

```ts
{
  headers?: Record<string, string>;
  body?: string | Buffer | Record<string, any>;
  json?: Record<string, any>;       // serialized + Content-Type added
  data?: Record<string, any>;       // form-urlencoded
  files?: Record<string, Buffer | { filename, content, contentType? }>;
  params?: Record<string, string | number | boolean>;
  cookies?: Record<string, string>;
  auth?: [string, string];
  timeout?: number;                  // seconds
  fetchMode?: "cors" | "no-cors" | "navigate" | "websocket";
}
```

`fetchMode` overrides the auto-detected `Sec-Fetch-Mode` / `Sec-Fetch-Dest` / `Sec-Fetch-Site` triplet. Useful when the auto-sniff gets it wrong (POSTs to CORS endpoints without a JSON Accept header are the usual offender).

### Streaming

```ts
session.getStream(url, options?): StreamResponse;
session.postStream(url, options?): StreamResponse;
session.requestStream(method, url, options?): StreamResponse;
```

`StreamResponse` is async-iterable:

```js
const stream = session.getStream("https://example.com/big.zip");
const out = fs.createWriteStream("big.zip");
for await (const chunk of stream) {
  out.write(chunk);
}
stream.close();
```

It also exposes `readChunk(size)`, `readAll()`, and `iterate(chunkSize)` if you want explicit control.

### Fast path

```ts
session.getFast(url, options?): FastResponse;
session.postFast(url, options?): FastResponse;
session.requestFast(method, url, options?): FastResponse;
session.putFast(url, options?): FastResponse;
session.deleteFast(url, options?): FastResponse;
session.patchFast(url, options?): FastResponse;
```

`FastResponse` is sync-only and uses pool-managed buffers. Call `release()` when you're done so the buffer goes back. Don't hold the buffer across many requests without copying it first.

### Lifecycle

```ts
session.close(): void;
session.refresh(): void;
session.warmup(url, options?): void;
session.fork(n?: number): Session[];
```

`refresh` keeps cookies and TLS tickets, drops connections. `warmup` simulates a real page load. `fork` clones cookies and TLS state into N sibling sessions, each with its own connection pool.

### Persistence

```ts
session.save(path: string): void;
session.marshal(): string;
Session.load(path: string): Session;       // static
Session.unmarshal(data: string): Session;  // static
```

`marshal()` returns JSON you can stuff into a database. `load` and `unmarshal` rebuild the session.

### Cookies

```ts
session.cookies: Record<string, string>;        // deprecated flat shape
session.getCookies(): Record<string, string>;    // deprecated
session.getCookiesDetailed(): Cookie[];
session.getCookie(name): string | null;          // deprecated
session.getCookieDetailed(name): Cookie | null;
session.setCookie(name, value, options?): void;
session.deleteCookie(name, domain?): void;
session.clearCookies(): void;
```

The flat `Record<string, string>` shape will get replaced with `Cookie[]` in a future major. Use `getCookiesDetailed` / `getCookieDetailed` if you want the new shape today.

### Proxies

```ts
session.setProxy(url): void;
session.setTcpProxy(url): void;
session.setUdpProxy(url): void;
session.getProxy(): string;
session.getTcpProxy(): string;
session.getUdpProxy(): string;
session.proxy: string;     // also exposed as a getter/setter property
```

Empty string disables the proxy.

### Header order

```ts
session.setHeaderOrder(order: string[]): void;
session.getHeaderOrder(): string[];
```

Lowercase names. Empty array resets to preset default.

### Misc

```ts
session.headers: Record<string, string>;     // default headers, mutate freely
session.auth: [string, string] | null;       // default auth
session.setSessionIdentifier(sessionId: string): void;
```

## Conventions

- camelCase everywhere. `getCookies`, `setProxy`, `clearCookies`, never `get_cookies`.
- Promises by default. Sync siblings have a `Sync` suffix. Streams and the fast path are sync-only since they handle their own lifecycle.
- TypeScript types ship in the package. `import type { SessionOptions, Response } from "httpcloak"` works without `@types`.
- Errors throw `HTTPCloakError`. `r.raiseForStatus()` throws on `>= 400`.

## `Response`

```ts
{
  statusCode: number;
  headers: Record<string, string>;
  body: Buffer;
  content: Buffer;          // alias of body
  text: string;
  finalUrl: string;
  url: string;              // alias of finalUrl
  protocol: string;         // "http/1.1", "h2", "h3"
  elapsed: number;          // ms
  cookies: Cookie[];
  history: RedirectInfo[];
  ok: boolean;
  reason: string;
  encoding: string | null;
  json<T>(): T;
  raiseForStatus(): void;
}
```

## Concurrency

Fire many concurrent `session.get()` calls from the same `Session` and you're fine. The cgo transport handles parallel dials and the Node side uses koffi's thread-pool offload so the event loop stays responsive.

What that means:

- One session, many `await Promise.all([...])` calls. Fine.
- Worker threads each holding their own `Session`. Also fine.
- Sharing one `Session` across worker threads. Possible but you have to pass it via the koffi pointer dance. Most folks just create one per worker.

For browser-tab-style parallelism with shared cookies, use `session.fork(n)`.

## Custom fingerprints

```js
const s = new Session({
  preset: "chrome-146",
  ja3: "771,4865-4866-4867-49195-49199,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513-21,29-23-24,0",
  akamai: "1:65536;2:0;4:6291456;6:262144|15663105|0|m,a,s,p",
});
```

Setting `ja3` auto-enables TLS-only mode. See [Custom JA3](/fingerprinting/custom-ja3).

## Other exports

```ts
import {
  LocalProxy,
  PresetPool,
  SessionCacheBackend,
  HTTPCloakError,
  configureSessionCache,
  clearSessionCache,
} from "httpcloak";
```

`LocalProxy` runs an HTTP proxy server that applies the fingerprint to whatever HTTP client you point at it. Undici, fetch, curl, anything.

## See also

- [Options reference](/reference/options).
- [Cookies and state](/cookies-and-state).
- [Proxies](/proxies).


---


<!-- source: docs/docs/bindings/dotnet.md -->

# .NET

The .NET binding wraps the cgo shared library through P/Invoke. Same C ABI as the Node and Python bindings underneath, surface area styled like .NET: PascalCase, `Async` suffixes for `Task<T>` returns, `IDisposable` for resource cleanup, `using` declarations.

## Install

```bash
dotnet add package HttpCloak
```

The NuGet package ships native binaries for `linux-x64`, `linux-arm64`, `osx-x64`, `osx-arm64`, `win-x64` under the standard `runtimes/` layout. .NET picks the right one based on RID at build time, no extra configuration.

Target frameworks: `net6.0`, `net7.0`, `net8.0`, `net9.0`, `net10.0`. Use the latest LTS (`net8.0` at the time of writing) unless you've got a reason not to.

## Quick start

```csharp
using HttpCloak;

using var s = new Session(preset: "chrome-146");
var r = await s.GetAsync("https://tls.peet.ws/api/all");
Console.WriteLine($"Status: {r.StatusCode}");
Console.WriteLine($"Protocol: {r.Protocol}");
Console.WriteLine($"Body length: {r.Text.Length}");
```

The `using` declaration disposes the session when the enclosing scope ends. The session implements `IDisposable`, so always pair `new Session(...)` with `using`.

## `Session`

Constructor signature (named arguments are the way):

```csharp
public Session(
    string preset = "chrome-146",
    string? proxy = null,
    string? tcpProxy = null,
    string? udpProxy = null,
    int timeout = 30,
    string httpVersion = "auto",
    bool verify = true,
    bool allowRedirects = true,
    int maxRedirects = 10,
    int retry = 0,
    int[]? retryOnStatus = null,
    int retryWaitMin = 500,
    int retryWaitMax = 10000,
    bool preferIpv4 = false,
    (string Username, string Password)? auth = null,
    Dictionary<string, string>? connectTo = null,
    string? echConfigDomain = null,
    bool tlsOnly = false,
    int quicIdleTimeout = 0,
    string? localAddress = null,
    string? keyLogFile = null,
    bool enableSpeculativeTls = false,
    string? switchProtocol = null,
    bool withoutCookieJar = false,
    string? ja3 = null,
    string? akamai = null,
    Dictionary<string, object>? extraFp = null,
    int? tcpTtl = null,
    int? tcpMss = null,
    int? tcpWindowSize = null,
    int? tcpWindowScale = null,
    bool? tcpDf = null
)
```

Use named arguments at call sites. Positional gets messy fast with this many parameters.

Full description per option: [Options reference](/reference/options).

### Async request methods (recommended)

All return `Task<Response>` and accept `CancellationToken`:

```csharp
Task<Response> GetAsync(string url, ..., CancellationToken cancellationToken = default, ...);
Task<Response> PostAsync(string url, string? body = null, ...);
Task<Response> PostJsonAsync<T>(string url, T data, ...);
Task<Response> PostFormAsync(string url, Dictionary<string, string> formData, ...);
Task<Response> PutAsync(string url, string? body = null, ...);
Task<Response> PutJsonAsync<T>(string url, T data, ...);
Task<Response> PatchAsync(string url, string? body = null, ...);
Task<Response> PatchJsonAsync<T>(string url, T data, ...);
Task<Response> DeleteAsync(string url, ...);
Task<Response> HeadAsync(string url, ...);
Task<Response> OptionsAsync(string url, ...);
Task<Response> RequestAsync(string method, string url, string? body = null, ...);
```

Common kwargs across all of them: `headers`, `parameters`, `cookies`, `auth`, `timeout`, `cancellationToken`, `fetchMode`. The JSON variants serialize `data` to JSON and add `Content-Type: application/json`.

```csharp
var r = await s.PostJsonAsync("https://httpbin.org/post", new { hello = "world" });
```

### Sync variants

```csharp
Response Get(string url, ...);
Response Post(string url, string? body = null, ...);
Response PostJson<T>(string url, T data, ...);
Response PostForm(string url, Dictionary<string, string> formData, ...);
Response PostMultipart(string url, ...);
Response Put(string url, string? body = null, ...);
Response PutJson<T>(string url, T data, ...);
Response Patch(string url, string? body = null, ...);
Response PatchJson<T>(string url, T data, ...);
Response Delete(string url, ...);
Response Head(string url, ...);
Response Options(string url, ...);
Response Request(string method, string url, string? body = null, ...);
```

There are also overloads that take `byte[]` and `Stream` for the body:

```csharp
Response Post(string url, byte[] body, ...);
Response Post(string url, Stream bodyStream, ...);
// Same for Put / Patch
Response RequestBinary(string method, string url, byte[] body, ...);
Response RequestStream(string method, string url, Stream bodyStream, ...);
```

The `Stream` overloads are for streaming uploads when you don't want to materialise the body in memory. Common case: uploading a big file from disk.

### Streaming responses

```csharp
StreamResponse GetStream(string url, ...);
StreamResponse PostStream(string url, string? body = null, ...);
StreamResponse RequestStream(string method, string url, string? body = null, ...);
```

`StreamResponse` exposes a `Stream`-like API and `IDisposable`. Wrap it in a `using` block when you consume it.

### Fast path

```csharp
FastResponse GetFast(string url, ...);
FastResponse PostFast(string url, byte[]? body = null, ...);
FastResponse RequestFast(string method, string url, byte[]? body = null, ...);
FastResponse PutFast(string url, byte[]? body = null, ...);
FastResponse DeleteFast(string url, ...);
FastResponse PatchFast(string url, byte[]? body = null, ...);
```

`FastResponse` skips a few allocations and exposes `Body` as a `byte[]` from a pooled buffer. Dispose it (or call `Release()`) when you're done so the buffer returns to the pool.

### Lifecycle

```csharp
void Dispose();                            // also via using
void Refresh(string? switchProtocol = null);
void Warmup(string url, long timeoutMs = 0);
Session[] Fork(int n = 1);
```

`Refresh` keeps cookies and TLS tickets while dropping connections. `Warmup` does a real-browser-style page load. `Fork(n)` returns sibling sessions sharing cookies and TLS state.

### Persistence

```csharp
void Save(string path);
string Marshal();
static Session Load(string path);
static Session Unmarshal(string data);
```

`Marshal` returns a JSON string. Save it to Redis, a database, wherever, then `Unmarshal` to rebuild.

### Cookies

```csharp
List<Cookie> GetCookies();                       // deprecated flat shape
List<Cookie> GetCookiesDetailed();
Cookie? GetCookie(string name);                   // deprecated
Cookie? GetCookieDetailed(string name);
void SetCookie(string name, string value,
               string? domain = null, string? path = null,
               bool secure = false, bool httpOnly = false,
               string? sameSite = null,
               int maxAge = 0, DateTime? expires = null);
void DeleteCookie(string name, string domain = "");
void ClearCookies();
```

The deprecated variants currently return shape-compatible data. They'll switch to the detailed shape in a future major. Migrate to `*Detailed` when convenient.

### Proxy management

```csharp
void SetProxy(string? proxyUrl);
void SetTcpProxy(string? proxyUrl);
void SetUdpProxy(string? proxyUrl);
string GetProxy();
string GetTcpProxy();
string GetUdpProxy();

string Proxy { get; set; }   // also a property
```

Pass `null` or empty string to disable.

### Header order

```csharp
void SetHeaderOrder(string[]? order);   // null/empty resets to preset default
string[] GetHeaderOrder();
```

Lowercase names.

### Misc

```csharp
void SetSessionIdentifier(string? sessionId);
public (string Username, string Password)? Auth { get; set; }   // default for all requests
```

## `Response`

```csharp
public sealed class Response
{
    public int StatusCode { get; }
    public Dictionary<string, string> Headers { get; }
    public byte[] Body { get; }
    public string Text { get; }
    public string FinalUrl { get; }
    public string Url { get; }            // alias of FinalUrl
    public string Protocol { get; }       // "http/1.1", "h2", "h3"
    public double Elapsed { get; }        // ms
    public List<Cookie> Cookies { get; }
    public List<RedirectInfo> History { get; }
    public bool Ok { get; }               // true if StatusCode < 400
    public string Reason { get; }
    public string? Encoding { get; }

    public T Json<T>();
    public void RaiseForStatus();
}
```

`Json<T>()` parses the body using `System.Text.Json` with relaxed escaping. `RaiseForStatus()` throws `HttpCloakException` on `>= 400`.

## Conventions

- PascalCase everywhere. `GetCookies`, `SetProxy`, `ClearCookies`.
- `Async` suffix for `Task<T>` returns.
- `CancellationToken` parameter on all `*Async` methods. Use it.
- `IDisposable` on `Session`, `StreamResponse`, `FastResponse`, `LocalProxy`. Pair every `new` with `using`.
- Errors throw `HttpCloakException`.
- Nullable annotations are on. `string?` means it can be null, `string` means it can't.

## Concurrency

`Session` is safe for concurrent use. Multiple `Task`s can call request methods on the same session at once, the underlying transport handles parallel dials.

```csharp
using var s = new Session(preset: "chrome-146");
var tasks = urls.Select(u => s.GetAsync(u));
var responses = await Task.WhenAll(tasks);
```

For browser-tab-style parallelism with shared cookies, use `Fork(n)`. Each fork has its own connection pool but inherits cookies and TLS resumption tickets from the parent.

## Custom fingerprints

```csharp
using var s = new Session(
    preset: "chrome-146",
    ja3: "771,4865-4866-4867-49195-49199,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513-21,29-23-24,0",
    akamai: "1:65536;2:0;4:6291456;6:262144|15663105|0|m,a,s,p"
);
```

Setting `ja3` auto-enables TLS-only mode. See [Custom JA3](/fingerprinting/custom-ja3).

## Other types

```csharp
HttpCloak.LocalProxy
HttpCloak.PresetPool
HttpCloak.SessionCacheBackend
HttpCloak.HttpCloakException
HttpCloak.MultipartFile     // for PostMultipart
HttpCloak.Cookie
HttpCloak.RedirectInfo
HttpCloak.StreamResponse
HttpCloak.FastResponse
```

`LocalProxy` runs a local HTTP proxy server that applies the fingerprint to whatever HTTP client points at it. `PresetPool` and JSON loading are covered in [JSON preset builder](/fingerprinting/json-preset-builder). `SessionCacheBackend` plugs into [Session save and restore](/connection-lifecycle/session-save-restore).

## P/Invoke pitfalls

The native lib's a cgo shared library. A few things to keep in mind:

- The lib's loaded once per process. Loading it from multiple `AppDomain`s isn't supported.
- The lib calls back into managed code for the distributed session cache. Pin the delegates the way `SessionCacheBackend` already does, don't roll your own without reading that source.
- `Native.cs` exposes the raw P/Invoke surface but is internal. You should never need to touch it from app code, the `Session` / `LocalProxy` / `PresetPool` classes wrap everything.

## See also

- [Options reference](/reference/options).
- [Cookies and state](/cookies-and-state).
- [Proxies](/proxies).


---


<!-- source: docs/docs/reference/index.md -->

# Reference

Everything in one place. Every option, every preset, the JSON schema, and a top-down map of how the library hangs together.

## In this section

- [Options](./options): every WithX option in one place
- [Presets](./presets): every preset's JA3, JA4, akamai hash, default headers
- [JSON Preset Spec](./json-preset-spec): the canonical JSON schema for load_preset_from_json
- [Architecture](./architecture): high-level component map of the library


---


<!-- source: docs/docs/reference/options.md -->

# Options

Every option you can pass to `httpcloak.New(...)` and `httpcloak.NewSession(...)`, all in one place. Lookup-style. For the reasoning behind each one, follow the link to the topic page.

:::info
Flat reference. For why each option exists and when to reach for it, see the topic sections (Proxies, Fingerprinting, Sessions, etc.).
:::

Two surfaces:

- **`httpcloak.New(preset, ...Option)`** gives you a stateless `*Client`. Few options.
- **`httpcloak.NewSession(preset, ...SessionOption)`** gives you a stateful `*Session` (cookies, TLS resumption, header memory). All the juicy options live here.

New here? Start with `NewSession`. `New` is for one-shot scripts.

---

## Client options (`httpcloak.New`)

The stateless `Client`. Two options, by design.

| Signature | Default | What it does |
|---|---|---|
| `WithTimeout(d time.Duration) Option` | `30s` | Per-request timeout for `client.Do`, `Get`, `Post`, etc. Resets on every call. |
| `WithProxy(url string) Option` | `""` (no proxy) | Single-protocol proxy URL (`http://`, `https://`, `socks5://`). Applied to every request. For per-protocol split routing, use `NewSession` with the TCP/UDP proxy options. |

---

## Session options (`httpcloak.NewSession`)

The full surface, grouped by category. Every option constructor returns a `SessionOption`.

### Lifecycle and cookies

Session-level state: the cookie jar, header memory, what protocol you flip to after `Refresh()`.

| Signature | Default | What it does |
|---|---|---|
| `WithoutCookieJar() SessionOption` | jar enabled | Disables the internal cookie jar entirely. `Set-Cookie` is not stored, jar contents are not auto-injected as `Cookie:` headers. Caller-provided `Cookie` headers always pass through. Use when you have your own jar (database, shared cache). See [Disabling the cookie jar](/cookies-and-state/disabling-cookie-jar). |
| `WithSwitchProtocol(proto string) SessionOption` | `""` (no switch) | Protocol the session switches to on the next `Refresh()`. Valid values: `"h1"`, `"h2"`, `"h3"`. Useful for warming TLS on H3 then serving on H2 with resumption. |
| `WithKeyLogFile(path string) SessionOption` | `SSLKEYLOGFILE` env | Per-session override for the TLS key log path. Wireshark / Chrome use this to decrypt captured traffic. |

### Network, proxies, local binding

How connections get made: proxy routing, IP family preference, source IP.

| Signature | Default | What it does |
|---|---|---|
| `WithSessionProxy(url string) SessionOption` | `""` | Single proxy URL applied to all protocols (TCP and UDP). Schemes: `http://`, `https://`, `socks5://`. See [Proxies](../proxies). |
| `WithSessionTCPProxy(url string) SessionOption` | `""` | TCP-only proxy (HTTP/1.1, HTTP/2). Pair with `WithSessionUDPProxy` for split routing. |
| `WithSessionUDPProxy(url string) SessionOption` | `""` | UDP-only proxy (HTTP/3 via SOCKS5 or MASQUE). Pair with `WithSessionTCPProxy`. |
| `WithSessionPreferIPv4() SessionOption` | IPv4/IPv6 racing | Forces IPv4 dial. Use on networks where IPv6 is broken or slow. Disables Happy Eyeballs racing. |
| `WithLocalAddress(addr string) SessionOption` | OS-chosen | Binds outgoing connections to a specific local IP (v4 or v6). On Linux, freebind is auto-applied so any address from a routed prefix works without per-IP interface config. Useful for IPv6 rotation. |
| `WithLocalAddrIP(ip net.IP) SessionOption` | OS-chosen | Same as `WithLocalAddress` but takes a parsed `net.IP`. Nil is a no-op (so conditional builders don't clobber a previous value). |
| `WithConnectTo(requestHost, connectHost string) SessionOption` | no override | Domain fronting: requests to `requestHost` connect to `connectHost`. SNI and `Host:` keep `requestHost`. Can be called multiple times for multiple mappings. |
| `WithEnableSpeculativeTLS() SessionOption` | off | Sends CONNECT and TLS ClientHello together over a proxy, saving one round-trip (~25% speedup). Off by default because some HTTP proxies choke on it. Enable when you've validated the proxy supports it. |

### Protocol forcing

Lock or unlock specific HTTP versions.

| Signature | Default | What it does |
|---|---|---|
| `WithForceHTTP1() SessionOption` | auto | Forces HTTP/1.1. Implies `WithDisableHTTP3()`. |
| `WithForceHTTP2() SessionOption` | auto | Forces HTTP/2. Implies `WithDisableHTTP3()`. |
| `WithForceHTTP3() SessionOption` | auto | Forces HTTP/3 (QUIC). Fails on hosts that don't advertise H3. |
| `WithDisableHTTP3() SessionOption` | H3 enabled when preset supports it | Disables HTTP/3 racing while keeping H1/H2 negotiation. Use when QUIC is unreliable on the network or you bound to an address that can't UDP. |
| `WithTLSOnly() SessionOption` | off | Keeps the preset's TLS fingerprint but skips its default HTTP headers. You set every header per-request. Auto-enabled when `WithCustomFingerprint` provides a JA3. |

### TLS, ECH, certificate verification

| Signature | Default | What it does |
|---|---|---|
| `WithInsecureSkipVerify() SessionOption` | verify enabled | Skips TLS certificate verification. Test-only, never ship this enabled. |
| `WithDisableECH() SessionOption` | ECH attempted when DNS has it | Skips the ECH (Encrypted Client Hello) HTTPS RR lookup. Saves ~15-20ms on first connect at the cost of the privacy bump ECH gives you. |
| `WithECHFrom(domain string) SessionOption` | target domain | Pulls ECH config from a different domain's DNS than the request target. Common pattern for Cloudflare: `WithECHFrom("cloudflare-ech.com")` works for any CF-fronted host. |
| `WithSessionCache(backend, errCb) SessionOption` | in-memory | Plugs a distributed TLS session cache (e.g. Redis). `backend` implements `transport.SessionCacheBackend`; `errCb` is called when the backend fails. Lets multiple processes share TLS resumption tickets. |

### Fingerprint customization

| Signature | Default | What it does |
|---|---|---|
| `WithCustomFingerprint(fp CustomFingerprint) SessionOption` | preset's defaults | Override TLS (JA3) and HTTP/2 (Akamai) fingerprints. When `JA3` is set, `WithTLSOnly()` is auto-enabled. The struct fields: `JA3` (full string), `Akamai` (settings/window/priority/pseudo string), `SignatureAlgorithms`, `ALPN`, `CertCompression`, `PermuteExtensions`. See [Custom fingerprints](../fingerprinting/custom-ja3). |
| `WithTCPFingerprint(fp fingerprint.TCPFingerprint) SessionOption` | preset's defaults | Override TCP/IP fingerprint fields (TTL, MSS, window size, window scale, DF bit). Only non-zero fields apply; zero fields keep the preset value. |

### Timeouts and retries

| Signature | Default | What it does |
|---|---|---|
| `WithSessionTimeout(d time.Duration) SessionOption` | `30s` | Default per-request timeout. Each `Do` / `Get` can override via `req.Timeout`. |
| `WithQuicIdleTimeout(d time.Duration) SessionOption` | `30s` | QUIC idle timeout. Connections close after this much silence. Match Chrome's default unless you need long-lived H3 sessions across request gaps. |
| `WithRetry(count int) SessionOption` | retry off | Enables retry with default backoff. `count` is total retry attempts (not including the first try). |
| `WithoutRetry() SessionOption` | retry off | Explicitly disables retry. No-op if retry was never enabled. |
| `WithRetryConfig(count int, waitMin, waitMax time.Duration, retryOnStatus []int) SessionOption` | see source | Full retry config. `waitMin/waitMax` define exponential backoff bounds. `retryOnStatus` is the set of HTTP statuses that trigger a retry. |

### Redirects

| Signature | Default | What it does |
|---|---|---|
| `WithoutRedirects() SessionOption` | follow on | Don't follow redirects. The first 3xx response returns to caller. |
| `WithRedirects(follow bool, maxRedirects int) SessionOption` | follow=true, max=10 | Toggle follow + cap the chain. `maxRedirects=0` with `follow=true` falls back to the package default. |

### Custom fingerprint struct (`CustomFingerprint`)

The struct you hand to `WithCustomFingerprint`. Lives in the root package.

| Field | Type | Notes |
|---|---|---|
| `JA3` | `string` | Full JA3 string: `Version,Ciphers,Extensions,Curves,Formats`. Setting this implies TLS-only mode. |
| `Akamai` | `string` | Akamai HTTP/2 fingerprint: `SETTINGS\|WINDOW_UPDATE\|PRIORITY\|PSEUDO_ORDER`. Example: `1:65536;2:0;4:6291456;6:262144\|15663105\|0\|m,a,s,p`. |
| `SignatureAlgorithms` | `[]string` | Names like `"ecdsa_secp256r1_sha256"`, `"rsa_pss_rsae_sha256"`. Replaces the JA3 spec's default sig-algs. |
| `ALPN` | `[]string` | Default `["h2", "http/1.1"]`. Override to limit (e.g. H1-only). |
| `CertCompression` | `[]string` | One or more of `"brotli"`, `"zlib"`, `"zstd"`. |
| `PermuteExtensions` | `bool` | When true, the TLS extension order is permuted per handshake (Chrome 110+ behavior). |

---

## Per-request options

The `Request` struct carries per-call overrides. These don't go through `SessionOption`:

| Field | Type | What it does |
|---|---|---|
| `Method` | `string` | HTTP method. |
| `URL` | `string` | Absolute URL. |
| `Headers` | `map[string][]string` | Extra headers (multi-value, matches `http.Header`). Caller-provided `Cookie:` always passes through. |
| `Body` | `io.Reader` | Streaming body (no length needed for chunked). |
| `Timeout` | `time.Duration` | Per-request timeout override. |
| `TLSOnly` | `*bool` | Per-request override for `WithTLSOnly`. `nil` falls back to the session setting. Useful for `LocalProxy` where each request has its own TLS-only flag via `X-HTTPCloak-TlsOnly`. |

---

## Session methods (mutators after construction)

Not `SessionOption` constructors. These live on `*Session` and you call them after `NewSession` hands you one.

| Method | What it does |
|---|---|
| `SetProxy(url string)` | Replaces the unified proxy. Closes existing connections. Empty string switches to direct. |
| `SetTCPProxy(url string)` | Replaces only the TCP proxy. |
| `SetUDPProxy(url string)` | Replaces only the UDP proxy. |
| `GetProxy() string` | Current unified or TCP proxy URL. |
| `GetTCPProxy() string` | Current TCP proxy URL. |
| `GetUDPProxy() string` | Current UDP proxy URL. |
| `SetHeaderOrder(order []string)` | Override the preset's header order. Lowercase names. `nil` resets to preset default. |
| `GetHeaderOrder() []string` | Current header order, or preset default if no override. |
| `SetSessionIdentifier(id string)` | TLS-cache key namespace. Used when a session is registered with `LocalProxy` so distributed caches isolate per-session tickets. |
| `Warmup(ctx, url) error` | Simulates a real browser page load: fetches HTML + CSS/JS/image subresources with realistic headers, priorities, and timing. Warms TLS, cookies, ticket cache. |
| `Fork(n int) []*Session` | Create `n` child sessions sharing cookies and TLS cache but with independent connections. Mimics multiple browser tabs. |
| `Refresh()` | Close all connections, keep TLS cache and cookies. Switches protocol if `WithSwitchProtocol` was set. |
| `RefreshWithProtocol(proto string) error` | Same as `Refresh` but switches to the given protocol. The change persists for future `Refresh()` calls. Valid: `"h1"`, `"h2"`, `"h3"`, `"auto"`. |
| `Save(path string) error` | Persist cookies + TLS sessions to a file. |
| `Marshal() ([]byte, error)` | Persist cookies + TLS sessions to bytes. |
| `Close()` | Release everything. Always defer this. |

Cookie API:

| Method | What it does |
|---|---|
| `GetCookies() []CookieInfo` | All cookies with full metadata. |
| `GetCookiesDetailed() []CookieInfo` | Same shape (the bindings split this; in Go they're identical). |
| `SetCookie(c CookieInfo)` | Insert / replace a cookie with full metadata. |
| `DeleteCookie(name, domain string)` | Delete by name. Empty domain wipes from every domain. |
| `ClearCookies()` | Wipe the jar. |

Loaders. Package-level, not methods:

| Function | What it does |
|---|---|
| `LoadSession(path string) (*Session, error)` | Restore a session saved with `Save`. |
| `UnmarshalSession(data []byte) (*Session, error)` | Restore a session from bytes saved with `Marshal`. |
| `Presets() []string` | All registered preset names (built-ins + any custom registrations). |

---

## Top-level helpers

Not options. Just useful symbols in the root package.

| Symbol | What it does |
|---|---|
| `BuildMultipart(fields []MultipartField) ([]byte, string, error)` | Encode a multipart/form-data body. Returns body bytes + the `Content-Type` header value (with boundary). Handles both text fields (`Name`, `Value`) and file fields (`Name`, `Filename`, `Content`, `ContentType`). |
| `MultipartField` | Struct passed to `BuildMultipart`. Fields: `Name`, `Value`, `Filename`, `Content`, `ContentType`. |
| `Request`, `Response`, `RedirectInfo`, `StreamResponse` | Request/response shapes. |
| `Response.Bytes() / Text() / JSON(v)` | Read the body once, with caching. |
| `Response.GetHeader(key) / GetHeaders(key)` | Case-insensitive lookup (header keys are stored lowercase). |
| `StreamResponse.Read / ReadChunk / ReadAll / Close` | Streaming body reads. Streaming does **not** support redirects, use `Do` for redirect handling. |

---

## Defaults at a glance

| Setting | Default |
|---|---|
| Request timeout | `30s` |
| QUIC idle timeout | `30s` |
| Cookie jar | enabled |
| Redirect follow | on, max 10 |
| Retry | off |
| HTTP/3 | enabled when preset supports it |
| ECH lookup | on if the target's DNS publishes HTTPS RRs |
| Speculative TLS | off |
| TLS verify | on |
| Header order | preset default |
| Local IP bind | none (OS-chosen) |
| IPv4/IPv6 preference | racing (Happy Eyeballs) |

If a default isn't what you expected, file an issue with the preset name and a `tls.peet.ws/api/all` capture.


---


<!-- source: docs/docs/reference/presets.md -->

# Presets

Every fingerprint preset that ships with httpcloak. This is the lookup table when you need to know which preset gives you which JA3, JA4, Akamai H2 hash, and User-Agent.

Below comes from the registry in `fingerprint/presets.go`. The newer Chrome versions (147, 148) live in the embedded JSON registry at `fingerprint/embedded/*.json` and inherit from older presets via `based_on`.

:::tip
Want to see what a real browser sends right now? Hit [tls.peet.ws/api/all](https://tls.peet.ws/api/all). DevTools won't show you header order, so peet is your only source of truth there.
:::

---

## Aliases

The `-latest` aliases follow the newest version we track. Not separate fingerprints, just pointers.

| Alias | Resolves to |
|---|---|
| `chrome-latest` | `chrome-148` (auto-detects host OS) |
| `chrome-latest-windows` | `chrome-148-windows` |
| `chrome-latest-linux` | `chrome-148-linux` |
| `chrome-latest-macos` | `chrome-148-macos` |
| `chrome-latest-ios` | `chrome-148-ios` |
| `chrome-latest-android` | `chrome-148-android` |
| `firefox-latest` | `firefox-148` |
| `safari-latest` | `safari-18` |
| `safari-latest-ios` | `safari-18-ios` |
| `ios-chrome-latest` | `chrome-148-ios` (back-compat naming) |
| `ios-safari-latest` | `safari-18-ios` (back-compat naming) |
| `android-chrome-latest` | `chrome-148-android` (back-compat naming) |

`chrome-148` with no platform suffix sniffs the running OS and dispatches to `chrome-148-windows`, `chrome-148-macos`, or `chrome-148-linux`. Pick this if your binary should match the host OS. Pick the explicit suffix when you want, say, a Windows fingerprint from a Linux box. That's the common scraping case.

---

## Captured hashes (verified against tls.peet.ws)

Captured from the Linux build host on `2026-05-10` via `NewSession(preset).Get(ctx, "https://tls.peet.ws/api/all")`. The `protocol` column is what tls.peet observed (H2, because peet doesn't advertise H3).

| Preset | Protocol | JA3 hash | JA4 | Akamai HTTP/2 hash | PeetPrint |
|---|---|---|---|---|---|
| `chrome-latest` (resolves to `chrome-148-linux`) | h2 | `51c8a5ff78d815668581664c5789d09c` | `t13d1516h2_8daaf6152771_d8a2da3f94cd` | `52d84b11737d980aef856699f885ca86` | `1d4ffe9b0e34acac0bd883fa7f79d7b5` |
| `chrome-148-windows` | h2 | `f592f2dfba4cdfc1b18ed1f29df8c8b7` | `t13d1516h2_8daaf6152771_d8a2da3f94cd` | `52d84b11737d980aef856699f885ca86` | `1d4ffe9b0e34acac0bd883fa7f79d7b5` |
| `firefox-148` | h2 | `6f7889b9fb1a62a9577e685c1fcfa919` | `t13d1717h2_5b57614c22b0_3cbfd9057e0d` | `6ea73faa8fc5aac76bded7bd238f6433` | `89d89662b21018947a9a46658c4f5ede` |
| `safari-18` | h2 | `c8af4d593e65bd6ba927ef9a0bdef541` | `t13d2013h2_a09f3c656075_7f0f34a4126d` | `90d8353e47699c4c38ecd773e9b5a089` | `62b834de729e78a9f0ebd1dd099314a7` |
| `safari-18-ios` | h2 | `e7c59d91e34d9d83e510732edf732b83` | `t13d2013h2_a09f3c656075_7f0f34a4126d` | `90d8353e47699c4c38ecd773e9b5a089` | `62b834de729e78a9f0ebd1dd099314a7` |

Notes:

- `chrome-latest` and `chrome-148-windows` differ on `ja3_hash` because the cipher / extension order is platform-specific (Linux uses `HelloChrome_148_Linux`, Windows uses `HelloChrome_148_Windows`). JA4 collapses to the same value because JA4 is order-insensitive in the cipher / extension portions.
- `safari-18` and `safari-18-ios` share JA4 + Akamai because the H2 stack is identical. The JA3 differs because of platform-specific ClientHello extensions.

For other presets, capture them yourself the same way. Or read the JSON in `fingerprint/embedded/<name>.json` for the static parts (UA, sec-ch-ua, header order).

---

## Chrome desktop

The Chrome desktop family. Versions 143-146 are Go-defined in `fingerprint/presets.go`. Versions 147 and 148 ship as JSON in `fingerprint/embedded/`, inheriting from 146 / 147 with just the User-Agent and `sec-ch-ua` brand list bumped.

| Preset | UA | `sec-ch-ua` | Notes |
|---|---|---|---|
| `chrome-148-windows` | `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36` | `"Chromium";v="148", "Google Chrome";v="148", "Not/A)Brand";v="99"` | Inherits TLS from `chrome-147-windows`. |
| `chrome-148-linux` | `Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36` | `"Chromium";v="148", "Google Chrome";v="148", "Not/A)Brand";v="99"` | Inherits TLS from `chrome-147-linux`. |
| `chrome-148-macos` | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36` | `"Chromium";v="148", "Google Chrome";v="148", "Not/A)Brand";v="99"` | Inherits TLS from `chrome-147-macos`. |
| `chrome-147-windows` | `...Chrome/147.0.0.0 Safari/537.36` | `"Google Chrome";v="147", "Chromium";v="147", "Not.A/Brand";v="8"` | Inherits TLS from `chrome-146-windows`. |
| `chrome-147-linux` | `...Chrome/147.0.0.0 Safari/537.36` | `"Google Chrome";v="147", "Chromium";v="147", "Not.A/Brand";v="8"` | Inherits TLS from `chrome-146-linux`. |
| `chrome-147-macos` | `...Chrome/147.0.0.0 Safari/537.36` | `"Google Chrome";v="147", "Chromium";v="147", "Not.A/Brand";v="8"` | Inherits TLS from `chrome-146-macos`. |
| `chrome-146-windows` | `...Chrome/146.0.0.0 Safari/537.36` | `"Google Chrome";v="146", "Chromium";v="146", "Not.A/Brand";v="8"` | Native Go preset. ClientHello: `HelloChrome_146_Windows`. |
| `chrome-146-linux` | `...Chrome/146.0.0.0 Safari/537.36` | `"Google Chrome";v="146", "Chromium";v="146", "Not.A/Brand";v="8"` | Native Go preset. ClientHello: `HelloChrome_146_Linux`. |
| `chrome-146-macos` | `...Chrome/146.0.0.0 Safari/537.36` | `"Google Chrome";v="146", "Chromium";v="146", "Not.A/Brand";v="8"` | Native Go preset. ClientHello: `HelloChrome_146_macOS`. |
| `chrome-145-{windows,linux,macos}` | `...Chrome/145.0.0.0...` | matching brand list | Native Go preset, per-platform ClientHello. |
| `chrome-144-{windows,linux,macos}` | `...Chrome/144.0.0.0...` | matching brand list | Native Go preset, per-platform ClientHello. |
| `chrome-143-{windows,linux,macos}` | `...Chrome/143.0.0.0...` | matching brand list | Native Go preset, per-platform ClientHello. |
| `chrome-141` | `...Chrome/141.0.0.0...` | matching brand list | Auto-detects platform. |
| `chrome-133` | `...Chrome/133.0.0.0...` | matching brand list | Auto-detects platform. |

The unsuffixed `chrome-148` / `chrome-147` / `chrome-146` / `chrome-145` / `chrome-144` / `chrome-143` resolve to whichever platform-suffixed variant matches the host OS at runtime. For consistent results across machines, pick the suffix.

All Chrome desktop presets:

- Speak HTTP/3 via `tls.HelloChrome_<v>_QUIC` plus a PSK variant for resumption.
- Use the Chrome H2 config (`chromeH2Config`): pseudo-header order `m,a,s,p`, settings order from real Chrome captures, RFC 7540 priorities on `HEADERS`.
- Default Akamai: `1:65536;2:0;4:6291456;6:262144|15663105|0|m,a,s,p`.

---

## Chrome iOS

iOS Chrome is a WebKit wrapper, so its TLS fingerprint matches Safari iOS, not desktop Chrome. Apple's rule, not ours.

| Preset | UA | TLS | Notes |
|---|---|---|---|
| `chrome-148-ios` | `...CriOS/148.0.0.0 Mobile/15E148 Safari/604.1` | `HelloIOS_18` | Inherits from `chrome-146-ios`. |
| `chrome-147-ios` | `...CriOS/147.0.0.0 Mobile/15E148 Safari/604.1` | `HelloIOS_18` | Inherits from `chrome-146-ios`. |
| `chrome-146-ios` | `...CriOS/146.0.0.0 Mobile/15E148 Safari/604.1` | `HelloIOS_18` | Native Go preset. |
| `chrome-145-ios` | `...CriOS/145.0.0.0...` | `HelloIOS_18` | Native Go preset. |
| `chrome-144-ios` | `...CriOS/144.0.0.0...` | `HelloIOS_18` | Native Go preset. |
| `chrome-143-ios` | `...CriOS/143.0.0.0...` | `HelloIOS_18` | Native Go preset. |

All iOS Chrome presets:

- Use the iOS Safari H2 stack (`safariH2Config`): pseudo `m,s,p,a`, `NO_RFC7540_PRIORITIES=1`.
- Speak HTTP/3 via `HelloIOS_18_QUIC`.
- Default Akamai: `2:0;4:2097152;3:100;5:16384;9:1|10485760|0|m,s,p,a`.

---

## Chrome Android

Android Chrome ships its own native TLS stack. No WebKit lockdown like iOS.

| Preset | UA | TLS | Notes |
|---|---|---|---|
| `chrome-148-android` | `Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Mobile Safari/537.36` | `HelloChrome_<v>_Linux` | Inherits from `chrome-147-android`. |
| `chrome-147-android` | `...Chrome/147.0.0.0 Mobile Safari/537.36` | `HelloChrome_<v>_Linux` | Inherits from `chrome-146-android`. |
| `chrome-146-android` | `...Chrome/146.0.0.0 Mobile Safari/537.36` | `HelloChrome_146_Linux` | Native Go preset. |
| `chrome-145-android` | `...Chrome/145.0.0.0...` | `HelloChrome_145_Linux` | Native Go preset. |
| `chrome-144-android` | `...Chrome/144.0.0.0...` | `HelloChrome_144_Linux` | Native Go preset. |
| `chrome-143-android` | `...Chrome/143.0.0.0...` | `HelloChrome_143_Linux` | Native Go preset. |

`sec-ch-ua-mobile` becomes `?1` (vs `?0` on desktop). `sec-ch-ua-platform` is `"Android"`. Default Akamai matches Chrome desktop because the H2 stack is the same.

---

## Firefox

Firefox uses a totally different TLS extension order from Chrome. Compare the JA3s above and you'll see.

| Preset | UA | TLS | Notes |
|---|---|---|---|
| `firefox-148` | `Mozilla/5.0 (...; rv:148.0) Gecko/20100101 Firefox/148.0` | JA3 mode (no native uTLS Firefox 148) | H3 not supported (no Firefox QUIC fingerprint in uTLS). |
| `firefox-133` | `Mozilla/5.0 (...; rv:133.0) Gecko/20100101 Firefox/133.0` | uTLS `HelloFirefox_133` | H3 not supported. |

All Firefox presets:

- Use the Firefox H2 stack (`firefoxH2Config`): pseudo `m,p,a,s`, `ENABLE_PUSH=0`, custom HPACK ordering.
- Send `TE: trailers`. Chrome doesn't.
- Default Akamai for `firefox-148`: `1:65536;2:0;4:131072;5:16384|12517377|0|m,p,a,s`.
- Skip `sec-ch-ua` headers entirely. Firefox doesn't implement Client Hints.

---

## Safari (macOS)

| Preset | UA | TLS | Notes |
|---|---|---|---|
| `safari-18` | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Safari/605.1.15` | `HelloSafari_18` | H3 via `HelloIOS_18_QUIC` (Safari shares iOS QUIC). |

Safari macOS:

- Pseudo order `m,s,p,a`. Different from both Chrome and Firefox.
- `NO_RFC7540_PRIORITIES=1`. Safari opts out of stream priorities.
- No `sec-ch-ua`. Header order is shorter than Chrome's.
- Default Akamai: `2:0;4:2097152;3:100;5:16384;9:1|10485760|0|m,s,p,a`.

---

## Safari iOS

| Preset | UA | TLS | Notes |
|---|---|---|---|
| `safari-18-ios` | `Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1` | `HelloIOS_18` | H3 via `HelloIOS_18_QUIC`. |
| `safari-17-ios` | `...iPhone OS 17_0...Version/17.0 Mobile...` | `HelloIOS_17` | Older variant. |

iOS Safari shares the H2 fingerprint with macOS Safari but ships a slightly different TLS extension order. Visible in the JA3, identical in JA4.

---

## Per-preset details

For the static parts of any preset (UA, sec-ch-ua, header order, H2 settings), the source of truth is either the JSON in `fingerprint/embedded/` (v147+) or the Go function in `fingerprint/presets.go` (v146 and older).

To dump any preset as canonical JSON:

```go
import "github.com/sardanioss/httpcloak/fingerprint"

j, err := fingerprint.Describe("chrome-148-windows")
// j is the round-trip-stable JSON form
```

That same JSON loads back via `fingerprint.LoadPresetFromJSON` and `fingerprint.BuildPreset` unmodified. So this is also how you snapshot a preset to disk for diffing across versions.

---

## Picking a preset

Quick guide:

| Goal | Use |
|---|---|
| Just scrape something modern | `chrome-latest` |
| Looking like a Windows desktop user | `chrome-latest-windows` |
| Looking like a phone | `chrome-latest-android` or `safari-latest-ios` |
| Sites that allowlist Firefox quirks (HPACK, TE: trailers) | `firefox-latest` |
| Sites that block Chrome but pass Safari | `safari-latest` |
| Pinning to a specific version for reproducibility | `chrome-148-windows` (no `-latest`) |

For sites that fingerprint the TCP/IP stack (rare, but a few bot-management products do), pair the preset with `WithTCPFingerprint(...)` to spoof TTL / window size / MSS.

For everything else: start with `chrome-latest`, capture against `tls.peet.ws/api/all`, compare against a real Chrome on the same OS, file an issue if JA3 / Akamai / JA4 doesn't match.


---


<!-- source: docs/docs/reference/json-preset-spec.md -->

# JSON Preset Spec

The canonical JSON schema for presets. If you're building a preset programmatically, this is the contract.

Source of truth: `fingerprint/custom_preset.go` (`PresetSpec` and friends). The schema is round-trip stable. `fingerprint.Describe(name)` spits out JSON that `fingerprint.LoadPresetFromJSON` parses straight back into an identical preset.

:::note
JSON doesn't allow comments. The `// ...` annotations in the snippets below are docs only. Strip them before handing the JSON to the parser.
:::

---

## Top-level shape

```json
{
  "version": 1,
  "preset": { ... },
  "pool":   { ... }
}
```

| Field | Type | Required | Notes |
|---|---|---|---|
| `version` | int | yes | Schema version. Currently `1`. |
| `preset` | object | one of `preset` / `pool` | Single preset definition. |
| `pool` | object | one of `preset` / `pool` | A pool of presets for round-robin or random rotation. |

Exactly one of `preset` or `pool` has to be set.

### Pool shape

```json
{
  "version": 1,
  "pool": {
    "name": "my-rotation",
    "strategy": "random",       // or "round-robin"
    "presets": [
      { "name": "...", ... },
      { "name": "...", ... }
    ]
  }
}
```

---

## `preset` object

Every field a single preset can declare.

```json
{
  "name":     "my-chrome",          // required, unique
  "based_on": "chrome-148-windows", // optional, parent preset name
  "tls":      { ... },              // TLS fingerprint
  "http2":    { ... },              // HTTP/2 fingerprint
  "http3":    { ... },              // HTTP/3 + QUIC fingerprint
  "headers":  { ... },              // user-agent, header values, header order
  "tcp":      { ... },              // TCP/IP fingerprint
  "protocols":{ ... }               // protocol support flags
}
```

| Field | Type | Notes |
|---|---|---|
| `name` | string | The registry name. Used by `NewSession(name)`. |
| `based_on` | string | Parent preset. Inherits everything; this preset's fields overlay. Inheritance loops are detected at build time (looped chains return an error). |
| `tls` | object | See [TLS section](#tls-object). |
| `http2` | object | See [HTTP/2 section](#http2-object). |
| `http3` | object | See [HTTP/3 section](#http3-object). |
| `headers` | object | See [Headers section](#headers-object). |
| `tcp` | object | See [TCP section](#tcp-object). |
| `protocols` | object | See [Protocols section](#protocols-object). |

Omit a field and it inherits from `based_on`. If there's no parent, it stays at zero.

---

## `tls` object

```json
"tls": {
  "client_hello":      "chrome-148-windows",       // mutually exclusive with ja3
  "psk_client_hello":  "chrome-148-windows-psk",
  "quic_client_hello": "chrome-148-quic",
  "quic_psk_client_hello": "chrome-148-quic-psk",

  "ja3":        "771,4865-...,0-23-...,29-23-24,0",
  "ja3_extras": { ... },

  "signature_algorithms":            [1027, 2052, 1025],
  "delegated_credential_algorithms": [1027, 2052],
  "alpn":               ["h2", "http/1.1"],
  "cert_compression":   ["brotli", "zlib", "zstd"],
  "permute_extensions": true,
  "record_size_limit":  16385,
  "key_share_curves":   1
}
```

| Field | Type | Notes |
|---|---|---|
| `client_hello` | string | uTLS ClientHello ID name (e.g. `"chrome-146-windows"`). Mutually exclusive with `ja3`. |
| `psk_client_hello` | string | PSK variant for TLS session resumption. Requires `client_hello` (directly or via `based_on`). |
| `quic_client_hello` | string | QUIC-specific ClientHello. Cannot be used with `ja3`. |
| `quic_psk_client_hello` | string | QUIC PSK variant. |
| `ja3` | string | Full JA3: `Version,Ciphers,Extensions,Curves,Formats`. Setting this clears any inherited `client_hello`. |
| `ja3_extras` | object | JA3-mode extras: sig-algs, ALPN, cert compression, etc. Only valid when `ja3` is set. |
| `signature_algorithms` | uint16[] | Top-level shortcut. Only applies in JA3 mode. |
| `delegated_credential_algorithms` | uint16[] | Top-level shortcut. JA3 mode only. |
| `alpn` | string[] | ALPN protocol list. Default `["h2", "http/1.1"]`. JA3 mode only. |
| `cert_compression` | string[] | One or more of `"brotli"`, `"zlib"`, `"zstd"`. JA3 mode only. |
| `permute_extensions` | bool | When true, extension order shuffles per handshake (Chrome 110+ behaviour). |
| `record_size_limit` | uint16 | TLS extension 28 value. |
| `key_share_curves` | int | Number of curves to advertise key shares for. `1` for Chrome (X25519MLKEM768 only), `3` for Firefox. |

### `ja3_extras` shape

Same fields as the top-level shortcuts, just nested. Use this when you want the JA3 string and its extras kept together:

```json
"ja3_extras": {
  "signature_algorithms":            [1027, 2052, ...],
  "delegated_credential_algorithms": [1027, 2052, ...],
  "alpn":               ["h2", "http/1.1"],
  "cert_compression":   ["brotli"],
  "permute_extensions": true,
  "record_size_limit":  16385,
  "key_share_curves":   1
}
```

### TLS validation rules

The build step rejects these combos:

- `ja3` and `client_hello` set in the same spec.
- `ja3_extras` without `ja3`.
- Any of `psk_client_hello`, `quic_client_hello`, `quic_psk_client_hello` when there's no primary `client_hello` or `ja3` to anchor them.
- `quic_client_hello` / `quic_psk_client_hello` / `psk_client_hello` paired with `ja3` (JA3 doesn't control QUIC TLS, use `client_hello` mode for QUIC).
- TLS extension fields (`signature_algorithms`, `alpn`, `cert_compression`, `permute_extensions`, `record_size_limit`) when `client_hello` is set without `ja3` (those fields only apply to JA3).

---

## `http2` object

```json
"http2": {
  "akamai": "1:65536;2:0;4:6291456;6:262144|15663105|0|m,a,s,p",

  "header_table_size":        65536,
  "enable_push":              false,
  "max_concurrent_streams":   0,
  "initial_window_size":      6291456,
  "max_frame_size":           0,
  "max_header_list_size":     262144,
  "connection_window_update": 15663105,
  "stream_weight":            256,
  "stream_exclusive":         true,
  "no_rfc7540_priorities":    false,

  "settings":       [{"id": 1, "value": 65536}, ...],
  "settings_order": [1, 2, 4, 6],
  "pseudo_order":   ["m", "a", "s", "p"],

  "hpack_header_order":   ["sec-ch-ua", "user-agent", ...],
  "hpack_indexing_policy":"chrome",
  "hpack_never_index":    ["cookie", "authorization"],
  "stream_priority_mode": "chrome",
  "disable_cookie_split": false,

  "priority_table": {
    "document": { "urgency": 0, "incremental": false, "emit_header": true },
    "image":    { "urgency": 5, "incremental": true,  "emit_header": true }
  }
}
```

### Akamai shorthand

`akamai` is a one-line shorthand: `SETTINGS|WINDOW_UPDATE|PRIORITY|PSEUDO_ORDER`. The parser splits it and applies the four parts.

When both `akamai` and individual fields are set, here's the resolution order:

1. Apply individual fields (`header_table_size`, `enable_push`, etc.) for any slots the akamai shorthand does **not** touch.
2. Apply `akamai` authoritatively for the slots it explicitly names.
3. Apply `settings` (the structured `[{id, value}]` list) last. Overrides both.

So if your akamai is `1:65536` and you also set `header_table_size: 99999`, the akamai value wins for slot 1. Slots not in akamai (like `max_concurrent_streams`) take the individual value.

### Settings IDs

| ID | Setting |
|---|---|
| 1 | `HEADER_TABLE_SIZE` |
| 2 | `ENABLE_PUSH` |
| 3 | `MAX_CONCURRENT_STREAMS` |
| 4 | `INITIAL_WINDOW_SIZE` |
| 5 | `MAX_FRAME_SIZE` |
| 6 | `MAX_HEADER_LIST_SIZE` |
| 9 | `NO_RFC7540_PRIORITIES` |

### HPACK and priority

| Field | Type | Values |
|---|---|---|
| `hpack_indexing_policy` | string | `"chrome"`, `"never"`, `"always"`, `"default"` |
| `stream_priority_mode` | string | `"chrome"`, `"default"` |
| `disable_cookie_split` | bool | When true, the `Cookie:` header is sent as one line instead of split into multiple HPACK entries. |
| `hpack_never_index` | string[] | Lowercase header names that must be sent without HPACK indexing. |

### `priority_table`

Maps `sec-fetch-dest` values (`document`, `image`, `script`, `style`, `font`, etc.) to per-resource priority settings. When populated, the transport emits a per-request RFC 7540 stream weight (derived from `urgency`) and an RFC 9218 `priority:` header on every request, keyed off its `sec-fetch-dest`.

```json
"priority_table": {
  "document": { "urgency": 0, "incremental": false, "emit_header": true },
  "image":    { "urgency": 5, "incremental": true,  "emit_header": true },
  "style":    { "urgency": 1, "incremental": false, "emit_header": true }
}
```

| Field | Type | Notes |
|---|---|---|
| `urgency` | uint8 | 0 (highest) to 7 (lowest). Maps to RFC 9218. |
| `incremental` | bool | Whether the resource can be processed incrementally. |
| `emit_header` | bool | When true, the transport emits a `priority:` header on the request. |

Omit it and you get the preset's static `stream_weight` / `stream_exclusive` on every request. That's the legacy single-weight behaviour.

---

## `http3` object

```json
"http3": {
  "qpack_max_table_capacity": 65536,
  "qpack_blocked_streams":     100,
  "max_field_section_size":    65536,
  "enable_datagrams":          true,

  "quic_initial_packet_size":     1252,
  "quic_max_incoming_streams":    100,
  "quic_max_incoming_uni_streams":3,
  "quic_allow_0rtt":              true,
  "quic_chrome_style_initial":    true,
  "quic_disable_hello_scramble":  false,
  "quic_transport_param_order":   "chrome",   // or "random"
  "quic_connection_id_length":    8,
  "quic_max_datagram_frame_size": 65535,

  "max_response_header_bytes":    524288,
  "send_grease_frames":           true,

  "quic_initial_stream_receive_window":     2097152,
  "quic_initial_connection_receive_window": 16777216
}
```

| Field | Type | Notes |
|---|---|---|
| `qpack_max_table_capacity` | uint64 | QPACK encoder table cap advertised in `SETTINGS`. |
| `qpack_blocked_streams` | uint64 | Max QPACK-blocked streams. |
| `max_field_section_size` | uint64 | Max headers size. |
| `enable_datagrams` | bool | Whether to advertise H3 DATAGRAM support. |
| `quic_initial_packet_size` | uint16 | Initial packet size for QUIC handshake. Chrome uses 1252. |
| `quic_max_incoming_streams` | int64 | `initial_max_streams_bidi`. |
| `quic_max_incoming_uni_streams` | int64 | `initial_max_streams_uni`. |
| `quic_allow_0rtt` | bool | Enable 0-RTT data. |
| `quic_chrome_style_initial` | bool | Mimic Chrome's first-flight packet shape. |
| `quic_disable_hello_scramble` | bool | When true, don't permute extensions in QUIC ClientHello. |
| `quic_transport_param_order` | string | `"chrome"` or `"random"`. Chrome's order is fixed and identifying. |
| `quic_connection_id_length` | int | Length of source connection IDs. |
| `quic_max_datagram_frame_size` | uint64 | Max DATAGRAM frame size. |
| `max_response_header_bytes` | uint64 | Per-response header size cap. |
| `send_grease_frames` | bool | Send GREASE frames between real frames. |
| `quic_initial_stream_receive_window` | uint64 | `initial_max_stream_data_*`. iOS Safari uses 2 MiB; Chrome desktop uses different values. |
| `quic_initial_connection_receive_window` | uint64 | `initial_max_data`. iOS Safari uses 16 MiB. |

Omit a field (nil) and you get the quic-go default. The library only sets a slot if the spec asks for it.

---

## `headers` object

```json
"headers": {
  "user_agent": "Mozilla/5.0 ...",
  "values": {
    "accept-language": "en-US,en;q=0.9",
    "sec-ch-ua":       "..."
  },
  "order": [
    {"key": "sec-ch-ua",         "value": "..."},
    {"key": "user-agent",        "value": ""},
    {"key": "accept",            "value": "..."},
    {"key": "accept-encoding",   "value": "gzip, deflate, br, zstd"}
  ]
}
```

| Field | Type | Notes |
|---|---|---|
| `user_agent` | string | The `User-Agent` value. Set separately because the field is also referenced in `order` via `"key": "user-agent"`. |
| `values` | object (string→string) | Header values keyed by lowercase header name. Merged with the inherited `values` from `based_on`. |
| `order` | array of `{key, value}` | The exact header order on the wire. Lowercase keys. An empty `value` means "use the value from `values` or `user_agent`". |

Order matters. HTTP/2 / HTTP/3 implementations don't enforce header order on the receiving side, but bot detection products absolutely fingerprint it. Real Chrome and real Firefox sit miles apart on this.

---

## `tcp` object

```json
"tcp": {
  "platform":     "Windows",   // shorthand: "Windows", "macOS", "Linux"
  "ttl":          128,
  "mss":          1460,
  "window_size":  65535,
  "window_scale": 8,
  "df_bit":       true
}
```

`platform` is a shorthand that fills in the typical TTL / MSS / window combo for that OS. Individual fields override the platform default.

These only matter for the handful of bot-management products that fingerprint the TCP/IP stack. Most don't bother.

---

## `protocols` object

```json
"protocols": {
  "http3": true
}
```

| Field | Type | Notes |
|---|---|---|
| `http3` | bool | Whether the preset advertises HTTP/3 support. When false, the runtime won't try QUIC even if the host advertises it via Alt-Svc. |

---

## Round-trip guarantee

`Describe -> LoadPresetFromJSON -> BuildPreset -> Describe` produces byte-identical JSON. CI uses this to catch silent drift in the embedded presets.

```go
import "github.com/sardanioss/httpcloak/fingerprint"

orig, _ := fingerprint.Describe("chrome-148-windows")
pf, _ := fingerprint.LoadPresetFromJSON([]byte(orig))
rebuilt, _ := fingerprint.BuildPreset(pf.Preset)
fingerprint.Register(rebuilt.Name+"-rt", rebuilt)
again, _ := fingerprint.Describe(rebuilt.Name+"-rt")
// orig == again, modulo the renamed `name` field
```

The verified spot-check (chrome-148-windows, firefox-148, safari-18-ios) shows zero diff beyond the rename.

---

## Inheritance and validation

`based_on` resolves at build time. Loops get detected and reported as `based_on inheritance loop detected at "..."`. The chain ends at a built-in (whose `based_on` is empty).

When you call `BuildPreset(spec)`:

1. If `based_on` is set, the parent preset gets cloned (deep copy of headers, H2/H3 config, JA3 extras).
2. Each non-empty section in your spec overlays on top.
3. Validation runs: TLS rules, HPACK indexing policy values, stream priority mode values, QUIC transport param order values.
4. The built `*Preset` comes back. Register it with `fingerprint.Register(name, preset)` so `NewSession(name)` can find it.

A spec with no `name` is fine. `BuildPreset` returns a `*Preset` carrying whatever name `based_on` had, and you can rename before registering.

---

## Loading from disk

```go
pf, err := fingerprint.LoadPresetFromFile("/etc/httpcloak/presets/my-chrome.json")
preset, err := fingerprint.BuildPreset(pf.Preset)
fingerprint.Register("my-chrome", preset)

// Now NewSession("my-chrome") works.
```

For one-shot loading and registration:

```go
preset, err := fingerprint.LoadAndBuildPreset("/path/to/preset.json")
fingerprint.Register(preset.Name, preset)
```

---

## A complete minimal example

A real preset that just swaps the User-Agent on top of `chrome-148-windows`:

```json
{
  "version": 1,
  "preset": {
    "name": "chrome-148-windows-headless",
    "based_on": "chrome-148-windows",
    "headers": {
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/148.0.0.0 Safari/537.36"
    }
  }
}
```

Everything else (TLS, HTTP/2, header order, HTTP/3, TCP) inherits from `chrome-148-windows`. This is exactly the trick the embedded JSONs use to ship Chrome 147 and 148 without retyping 5000 lines per version.


---


<!-- source: docs/docs/reference/architecture.md -->

# Architecture

A top-down map of the library. Pull this up when you're trying to figure out which package owns a behaviour, or when you want to trace a request from `Session.Do` all the way down to a TLS ClientHello hitting the wire.

---

## The layering

```
                    +---------------------------------+
   user code  --->  |  httpcloak (root package)       |
                    |  - Client / Session             |
                    |  - WithX option constructors    |
                    |  - Multipart helpers            |
                    +-----------------+---------------+
                                      |
                                      v
                    +---------------------------------+
                    |  session/                       |
                    |  - cookie jar (own + sardanioss)|
                    |  - per-host transport routing   |
                    |  - Refresh / Fork / Warmup      |
                    |  - state save / load            |
                    +-----------------+---------------+
                                      |
              +-----------------------+-----------------------+
              |                       |                       |
              v                       v                       v
      +---------------+       +---------------+       +---------------+
      | HTTP1Transport|       | HTTP2Transport|       | HTTP3Transport|
      | (raw TCP+TLS) |       | (uTLS + h2cc) |       | (quic-go h3)  |
      +---------------+       +---------------+       +---------------+
              |                       |                       |
              v                       v                       v
      +---------------+       +---------------+       +---------------+
      | proxy (HTTP   |       | proxy (HTTP   |       | proxy (UDP    |
      | CONNECT,      |       | CONNECT,      |       | SOCKS5,       |
      | SOCKS5)       |       | SOCKS5)       |       | MASQUE)       |
      +---------------+       +---------------+       +---------------+
              \                       |                      /
               \                      v                     /
                \               +-----+-----+              /
                 +------------> |  network  | <-----------+
                                +-----------+

               +-------------------------------+
   built once, +  fingerprint registry         |
   shared:     |  - Go presets (presets.go)    |
               |  - JSON presets (embedded/)   |
               |  - JA3 / Akamai / TCP fp data |
               +---------------+---------------+
                               |
                               v
               +-------------------------------+
   shared:     |  dns/                         |
               |  - SNI resolution             |
               |  - HTTPS RR / ECH lookup      |
               +-------------------------------+
```

Three transports, one session layer, one fingerprint registry, one DNS layer. The session picks which transport handles a request based on what the host advertises (Alt-Svc for H3) and whatever you forced via options.

---

## Packages

### `httpcloak` (root)

The public Go API. `Client`, `Session`, all the `WithX` option constructors, multipart helpers. Deliberately thin. Everything interesting lives in subpackages. Most options just set fields on a `protocol.SessionConfig` that gets handed to `session.NewSession`.

Files: `httpcloak.go`, `local_proxy.go`.

### `session/`

Stateful session. Owns the cookie jar, the per-host transport map, and the lifecycle of `Refresh` / `Fork` / `Warmup` / state persistence.

The interesting bits:

- One transport per host, lazily created. First request to `example.com` builds the transport. Every request after reuses it.
- `Refresh()` closes connections but keeps the cookie jar and the TLS resumption ticket cache. Can switch protocols on the way.
- `Fork(n)` returns `n` child sessions sharing the cookie jar and TLS cache but with their own connections. Like opening multiple browser tabs.
- `Warmup(ctx, url)` simulates a real page load: fetches the HTML, parses it, then pulls CSS/JS/image subresources with realistic per-resource priorities and timing.

### `transport/`

The three transports plus the unifying `Transport` wrapper. One transport per protocol family.

- **`HTTP1Transport`**: raw TCP, TLS via uTLS, HTTP/1.1 framing through the `sardanioss/http` fork. Kicks in when a host doesn't speak H2 or H1's been forced.
- **`HTTP2Transport`**: uTLS for the ClientHello, then a custom `http2.ClientConn` from the `sardanioss/http` fork. That custom conn is what lets us send Chrome's exact `SETTINGS` order, `PRIORITY` frames, `WINDOW_UPDATE` value, and HPACK indexing policy.
- **`HTTP3Transport`**: `quic-go` from `sardanioss/quic-go` (with the `PRIORITY_UPDATE` fix and Chrome-style initial packet shaping) plus `http3.Transport`.

The other stuff this package owns:

- **Speculative TLS for proxy CONNECT**: sends the CONNECT request and the TLS ClientHello in one TCP write. Saves a round-trip. Off by default because some proxies choke on it. Toggle via `WithEnableSpeculativeTLS`.
- **Happy Eyeballs**: IPv4/IPv6 racing inside the H3 dial functions. First address that completes the QUIC handshake wins. The loser gets closed.
- **`raceH3H2`**: protocol racing. When a host advertises H3 via Alt-Svc and you haven't forced a protocol, an H3 dial and an H2 dial fire off in parallel. First successful handshake wins.
- **TLS session ticket cache**: in-memory by default, pluggable via `WithSessionCache(backend, errCb)` for distributed setups (Redis, etc.).
- **Connection pool**: per-transport with idle timeout. H3 idle is set via `WithQuicIdleTimeout`.

### `fingerprint/`

The preset registry and the data structures behind it.

- `presets.go`: Go-defined presets (Chrome 133-146, Firefox 133, Safari 18, iOS, Android variants). Each preset is a `func() *Preset`.
- `embedded/*.json`: JSON-defined presets (Chrome 147, 148 across every platform). Loaded at package init and registered alongside the Go presets.
- `custom_preset.go`: JSON parsing plus `BuildPreset`. Powers both the embedded JSONs and user-supplied presets through `LoadPresetFromFile` / `LoadPresetFromJSON`.
- `describe.go`: the inverse of `BuildPreset`. Spits canonical JSON from a `*Preset`. Round-trip stable.
- `client_hello_ids.go`: string-to-uTLS ClientHelloID resolution.
- `akamai.go`: Akamai H2 fingerprint string parser. The shorthand format `SETTINGS|WINDOW_UPDATE|PRIORITY|PSEUDO` is parsed here.
- `ja3.go`: JA3 string parser and TLS spec builder.
- `headers.go`: header order and value handling.
- `preset_pool.go`: round-robin or random rotation across multiple presets.
- `priority_table_test.go` (paired with the runtime piece in transport): RFC 9218 priority handling for `sec-fetch-dest` driven priorities.

### `proxy/`

Proxy implementations. Three protocols:

- **HTTP CONNECT**: for `http://` and `https://` proxy URLs. Used by H1 and H2.
- **SOCKS5**: for `socks5://` URLs. Used by H1, H2, and (if the proxy supports UDP-associate) H3.
- **MASQUE**: UDP-tunnelled-over-HTTP/3 proxying. Used for H3 through an HTTP-aware UDP proxy. Implements the CONNECT-UDP method.

Proxy chains work (proxy through a proxy). `WithSessionProxy` sets one URL for all protocols. `WithSessionTCPProxy` + `WithSessionUDPProxy` lets you split it (say, SOCKS5 for H1/H2, MASQUE for H3).

### `dns/`

DNS resolution layer.

- A/AAAA lookup with caching.
- HTTPS RR lookup for pulling ECH config. Used by `WithECHFrom` and the default ECH-when-available path.
- Per-resolver overrides (system, DoH, custom).

### `protocol/`

The IPC layer for the daemon binary (`httpcloak-daemon`). Languages other than Go (Python, Node.js, .NET) talk to the daemon over stdin/stdout JSON. Not relevant if you're using the Go API directly. But `protocol/types.go` defines `SessionConfig`, which is what the root package's `NewSession` builds internally.

### `client/`

A second, lower-level client surface that predates the unified root API. Most folks should stick with the root `httpcloak.Client` / `Session`. The `client/` package still ships its own `WithX` options for backwards compatibility (`client.WithPreset`, `client.WithECHConfig`, certificate pinning via `PinCertificate`).

### Other directories

- `bindings/`: language SDKs (Python, Node.js, .NET) that wrap the daemon or link against the C library.
- `pool/`: connection pooling primitives.
- `streaming/`: streaming-body request helpers.
- `extensions/`: uTLS extension shims.

---

## Forked dependencies

httpcloak rides on four forks. Each one patches upstream to expose fingerprint-relevant knobs.

| Fork | Upstream | What we changed |
|---|---|---|
| `sardanioss/http` | `golang.org/x/net/http2` | Custom `http2.ClientConn` that lets us control `SETTINGS` order, `WINDOW_UPDATE`, `PRIORITY` frames, HPACK indexing policy, pseudo-header order, cookie splitting. |
| `sardanioss/utls` | `refraction-networking/utls` | Additional ClientHello presets for newer Chrome / iOS / Safari versions, QUIC ClientHello variants, PSK variants, key share count control. |
| `sardanioss/quic-go` | `quic-go/quic-go` | Chrome-style initial packet shaping, transport parameter order control, `PRIORITY_UPDATE` frame fix, GREASE frame emission. |
| `sardanioss/net` | `golang.org/x/net` | Various small fixes for the `http2` interaction. |

These are pinned in `go.mod`. For local dev you can use `go.work` to point at a local checkout of the fork.

---

## Request flow

A normal `Session.Get(ctx, "https://example.com/")` walks this path:

1. **Cookie injection**: `session/` looks up cookies for the URL and tacks them on as a `Cookie:` header (unless `WithoutCookieJar` is set or the caller already passed their own).
2. **Header building**: preset's header order + values + your request-level overrides get merged into the final ordered list. `User-Agent`, `sec-ch-ua`, `accept-language`, etc. all come from the preset.
3. **Transport selection**: `session/` looks up the per-host transport. If none yet, it builds one based on whatever the host has advertised (H3 via Alt-Svc cache) or what you forced.
4. **Connect / dial**: the transport opens a connection if needed. For H1/H2: TCP, then TLS via uTLS with the preset's ClientHello. For H3: UDP, then QUIC handshake with the preset's QUIC ClientHello plus transport parameters.
   - Happy Eyeballs races IPv4 and IPv6.
   - Protocol racing fires H3 and H2 in parallel if the host advertises both.
   - Through a proxy: CONNECT / SOCKS5 / MASQUE first, then handshake.
5. **DNS / ECH**: handled by `dns/`. ECH HTTPS RR is fetched unless disabled.
6. **Wire send**: the transport writes request frames (HTTP/2 `HEADERS` + `DATA`, or HTTP/3 equivalent). Frame ordering, settings, priorities all come from the preset.
7. **Response**: read back, parsed, body delivered as `io.ReadCloser`.
8. **Cookie storage**: `Set-Cookie` headers from the response go into the jar (unless `WithoutCookieJar`).
9. **Redirect**: if the response is 3xx and follow is on, jump back to step 1 with the new URL.

---

## Threading and concurrency

- `Session` is goroutine-safe for concurrent requests. Internal state (cookie jar, transport map, TLS cache) is mutex-protected.
- `Fork(n)` returns sessions sharing the cookie jar mutex with the parent. Concurrent requests across forks contend on the jar but ride independent connections.
- Transport `Close()` paths are wrapped in `closeWithTimeout` because QUIC `Close` can hang forever on a half-closed UDP socket. One of the timeout patterns we keep a close eye on.
- Per-request context propagates down to the transport. Cancel the context, you cancel the in-flight read, handshake, or dial.

---

## Where to look when something's wrong

| Symptom | Look in |
|---|---|
| Wrong JA3 / cipher order | `fingerprint/presets.go` or `fingerprint/embedded/*.json` for the preset's TLS section. Cross-check uTLS ClientHello ID. |
| Wrong HTTP/2 SETTINGS / pseudo order | `fingerprint/presets.go` H2 settings + `chromeH2Config` / `firefoxH2Config` / `safariH2Config`. |
| Wrong header order | Preset's `HeaderOrder` field. Verify against `tls.peet.ws/api/all`. |
| H3 not used | Check the host's Alt-Svc, the preset's `SupportHTTP3`, and whether `WithDisableHTTP3` was called. |
| Proxy doesn't connect | `proxy/`. Check the proxy URL scheme matches what the proxy speaks. |
| Hangs on close | `transport/` close paths. Check the QUIC close timeout wrapping. |
| Timeout not respected | `session/` and `transport/`. Context propagation, deadline computation. |

For everything else, the source reads easier than this map. Start at `httpcloak.NewSession` and just follow the calls.


---


<!-- source: docs/docs/recipes/index.md -->

# Recipes

End-to-end patterns for the stuff people actually ship. Copy, tweak, run.

## In this section

- [Multi-Proxy Rotation With State](./multi-proxy-rotation-with-state): swap proxies without burning your TLS session
- [Build Custom Chrome From tls.peet.ws](./build-custom-chrome-from-tls-peet): grab a tls.peet capture, turn it into your own preset
- [Long-Running Scraper Patterns](./long-running-scraper-patterns): refresh, warmup, cookie strategies for scrapers that run for days
- [Debug With Wireshark](./debug-with-wireshark): keylog plus filter tricks for seeing exactly what the library puts on the wire


---


<!-- source: docs/docs/recipes/multi-proxy-rotation-with-state.md -->

# Multi-Proxy Rotation With State

Swap proxies without throwing away your TLS state. Same fingerprint across
rotations, no fresh handshake every time you change exits.

## Why session continuity matters

Most rotators nuke the whole client when they swap proxies. New client, new
TCP and TLS handshake, new session ticket, start over. Fine for soft targets.
Leaves a trail everywhere else.

Here's what dies between two "fresh" handshakes:

- **TLS extension order** drifts a bit because of GREASE rotation. Same
  preset, same browser version, but the bytes on the wire don't quite match.
- **Session tickets** are gone. Returning visitors look very different from
  first-time visitors. Looking like a first-time visitor 500 times in a row
  is a dead giveaway.
- **ECH state** resets. If the target uses ECH, you re-fetch the config from
  zero.
- **Cookie jar** resets unless you copy it over.
- **Per-connection tracking** like CF's `__cf_bm` cookie ages weirdly when
  you hop hosts.

Keep ONE session and just swap the proxy under it. Handshake state, tickets,
cookies, ECH, all sticks. Only the IP changes. Clean.

:::tip
Most residential proxy providers don't care about session continuity. But if
you're hitting Cloudflare or anything with session tracking layered on top,
this pattern keeps you from looking like a brand-new visitor every single
request.
:::

## The pattern

1. Spin up one `Session` with your preset (e.g. `chrome-latest`).
2. For each request:
   - Pick a proxy from your pool.
   - Call `session.SetTCPProxy(url)` (plus `SetUDPProxy` if you're on H3).
   - Send the request.
3. Optional: call `session.Refresh()` to drop live connections without
   killing tickets or cookies. Next request gets 0-RTT on the new proxy.

That's the whole thing. The session keeps every piece of state across
rotations.

## Full example: rotating through 3 proxies

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "context"
    "fmt"
    "time"

    "github.com/sardanioss/httpcloak"
)

// In production, load this from a file or your provider's API.
// We use placeholder URLs here so the example doesn't ship credentials.
var proxyPool = []string{
    "http://user1:pass1@proxy1.example.com:8080",
    "http://user2:pass2@proxy2.example.com:8080",
    "http://user3:pass3@proxy3.example.com:8080",
}

func main() {
    // ONE session for the whole run. Proxy is set per-request below.
    s := httpcloak.NewSession("chrome-latest",
        httpcloak.WithSessionTimeout(30*time.Second),
    )
    defer s.Close()

    targets := []string{
        "https://tls.peet.ws/api/all",
        "https://tls.peet.ws/api/all",
        "https://tls.peet.ws/api/all",
        "https://tls.peet.ws/api/all",
    }

    for i, url := range targets {
        // Round-robin pick. Swap for random / weighted / sticky-by-host
        // depending on what your target wants.
        proxy := proxyPool[i%len(proxyPool)]
        s.SetTCPProxy(proxy)

        ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
        resp, err := s.Get(ctx, url)
        cancel()
        if err != nil {
            fmt.Printf("[req %d] proxy=%s err=%v\n", i, proxy, err)
            continue
        }
        body, _ := resp.Text()
        resp.Close()
        fmt.Printf("[req %d] proxy=%s status=%d body_len=%d\n",
            i, proxy, resp.StatusCode, len(body))

        // Refresh between requests to drop the live connection.
        // Tickets and cookies survive, next request resumes 0-RTT
        // on whatever proxy is set at that point.
        s.Refresh()
    }
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

PROXY_POOL = [
    "http://user1:pass1@proxy1.example.com:8080",
    "http://user2:pass2@proxy2.example.com:8080",
    "http://user3:pass3@proxy3.example.com:8080",
]

with httpcloak.Session("chrome-latest", timeout=30) as s:
    for i in range(4):
        proxy = PROXY_POOL[i % len(PROXY_POOL)]
        s.set_tcp_proxy(proxy)

        try:
            r = s.get("https://tls.peet.ws/api/all")
            print(f"[req {i}] proxy={proxy} status={r.status_code}")
        except Exception as e:
            print(f"[req {i}] proxy={proxy} err={e}")

        s.refresh()
```

Full Python API lives at [/bindings/python](../bindings/python).

</TabItem>
</Tabs>

## What survives a rotation

After `SetTCPProxy(newProxy)` (with or without `Refresh()`):

| State | Survives? | Notes |
|-------|-----------|-------|
| TLS session tickets | Yes | 0-RTT on next handshake |
| Cookie jar | Yes | Same jar, same cookies |
| ECH config | Yes | No re-fetch needed |
| Header order, preset config | Yes | Session-level, not per-conn |
| HTTP/2 connection | No (after Refresh) | Drops cleanly, reopens on next req |
| HTTP/3 connection | No (after Refresh) | Same |
| TCP socket | No (after Refresh) | Reopens through new proxy |

The live socket is the only thing that dies, and that's the point. You want a
new TCP connection through the new proxy IP, with all the fingerprint and
cookie state riding along.

## Rotation strategies

### Round-robin (simplest)

```go
proxy := proxyPool[i%len(proxyPool)]
```

Cheap, predictable, works for most cases.

### Sticky-by-host

Hitting multiple hosts and want one proxy per host? Use a small map:

```go
hostProxy := map[string]string{}

for _, url := range urls {
    host := parseHost(url)
    if _, ok := hostProxy[host]; !ok {
        hostProxy[host] = pickFromPool()
    }
    s.SetTCPProxy(hostProxy[host])
    // ... send
}
```

Handy when servers correlate the IP a session started on with later requests.
Start a CF challenge on IP A, finish it on IP B, that's a red flag.

### Rotate-on-error

Stick with the same proxy until you get a 403 / 429 / connection error, then
move. Way cheaper than rotating every request, and you only burn proxies when
something actually breaks.

```go
err := doRequest(s)
if err != nil || isBadStatus(resp.StatusCode) {
    s.SetTCPProxy(nextProxy())
    s.Refresh()
}
```

## H3 / QUIC notes

Running HTTP/3 through a MASQUE proxy? Set the UDP proxy too:

```go
s.SetTCPProxy("http://user:pass@http-proxy:8080")
s.SetUDPProxy("masque://user:pass@masque-proxy:443")
```

Most providers only do TCP. If you set `SetTCPProxy` and leave `SetUDPProxy`
empty, H3 quietly falls back to direct UDP, which leaks your real IP. Either
wire both up or force H1/H2 with `WithForceHTTP2()`.

## Combining with Save / LoadSession

For runs that go for hours and need to survive a process restart:

```go
// Periodically:
s.Save("/var/lib/scraper/state.json")

// On startup:
s, _ := httpcloak.LoadSession("/var/lib/scraper/state.json")
s.SetTCPProxy(currentProxy)
```

Saves the cookie jar, ticket cache, ECH state. Reloads like you never
stopped. The full pattern lives in
[Long-Running Scraper Patterns](./long-running-scraper-patterns).

## Common mistakes

**Spinning up a new session per proxy.** Trashes tickets, cookies, the lot.
The whole point of this recipe is one session, many proxies.

**Forgetting Refresh().** Skip `Refresh()` between requests and the existing
TCP/TLS connection keeps chugging along through the OLD proxy, even after you
set a new one. `SetTCPProxy` only kicks in on the NEXT new connection. Want
the IP swap right now? Call `Refresh()`.

**Mixing UDP and TCP proxies.** H3 needs `SetUDPProxy`. H1/H2 needs
`SetTCPProxy`. Set only one and let protocol racing pick the other, and
you'll bypass the proxy without realising.

## Related

- [Refresh](../connection-lifecycle/refresh), what `Refresh()` actually does
- [Proxies overview](../proxies/overview), supported proxy types
- [SOCKS5](../proxies/socks5), SOCKS5 specifics
- [MASQUE](../proxies/masque), UDP / H3 proxying


---


<!-- source: docs/docs/recipes/build-custom-chrome-from-tls-peet.md -->

# Build Custom Chrome From tls.peet.ws

Grab a tls.peet.ws capture from a real Chrome session, turn it into your own
httpcloak preset. Ten minutes of work, and you're shipping a Chrome version
we don't bundle yet.

:::tip
This is the move when you need a Chrome major we haven't shipped. Don't wait
for a release. Capture, edit JSON, ship.
:::

## When to use this

Reach for this recipe when:

- A target site checks `User-Agent` against the major Chrome version, and
  the shipped `chrome-latest` is a major or two behind what they expect.
- You want to reproduce a specific user's setup (Linux Chrome 145, macOS
  Chrome 147, whatever).
- You're debugging a fingerprint mismatch and want to compare what Chrome
  actually sends versus what httpcloak puts on the wire.

Don't use this to impersonate a browser we haven't profiled at the TLS layer.
This recipe only handles header, User-Agent, and sec-ch-ua deltas. If a new
Chrome version added a TLS extension or reshuffled extension order, you need
a fresh utls profile, not JSON edits. See
[Custom JA3](../fingerprinting/custom-ja3) for that path.

## The flow

1. Open Chrome (the version you want to clone). Hit `https://tls.peet.ws/api/all`.
2. Save the response JSON.
3. Run `describe_preset("chrome-latest")` to dump the shipped preset to JSON.
4. Diff the two. Spot the deltas (UA string, sec-ch-ua brand list, sometimes
   accept-language).
5. Edit the preset JSON to match the capture.
6. Load it with `load_preset_from_json` under a fresh name.
7. Hit tls.peet again with the new preset. Verify JA4, peetprint, and akamai
   hash all match the original capture.

## Step 1: Capture from real Chrome

Open Chrome, navigate to `https://tls.peet.ws/api/all`, save the JSON.
On Linux you can do it from the command line if you have Chrome installed:

```bash
google-chrome --headless --dump-dom https://tls.peet.ws/api/all > capture.json
```

The fields we care about (full response is much bigger):

```json
{
  "http_version": "h2",
  "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36",
  "tls": {
    "ja3": "771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,51-11-43-23-18-0-27-65281-45-16-5-17613-10-35-65037-13,4588-29-23-24,0",
    "ja3_hash": "f33ef28649dda9a281b02e75670c8139",
    "ja4": "t13d1516h2_8daaf6152771_d8a2da3f94cd",
    "peetprint_hash": "1d4ffe9b0e34acac0bd883fa7f79d7b5"
  },
  "http2": {
    "akamai_fingerprint": "1:65536;2:0;4:6291456;6:262144|15663105|0|m,a,s,p",
    "akamai_fingerprint_hash": "52d84b11737d980aef856699f885ca86",
    "sent_frames": [
      {
        "frame_type": "HEADERS",
        "headers": [
          ":method: GET",
          ":authority: tls.peet.ws",
          ":scheme: https",
          ":path: /api/all",
          "sec-ch-ua: \"Chromium\";v=\"148\", \"Google Chrome\";v=\"148\", \"Not/A)Brand\";v=\"99\"",
          "sec-ch-ua-mobile: ?0",
          "sec-ch-ua-platform: \"Linux\"",
          "user-agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36",
          "accept: text/html,...",
          "..."
        ]
      }
    ]
  }
}
```

Two things we'll pull out:

1. `user_agent`, the exact Chrome version string. Note the major number and
   the platform.
2. `sec-ch-ua` header, the brand-version list. Rotates with Chrome majors,
   classic giveaway when it's stale.

:::tip
DevTools won't show you the actual header order Chrome ships. The
`sent_frames[].headers` block in `tls.peet.ws/api/all` is the ground truth
for what your target actually sees.
:::

## Step 2: Describe the shipped preset

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "fmt"
    "os"

    "github.com/sardanioss/httpcloak/fingerprint"
)

func main() {
    j, err := fingerprint.Describe("chrome-latest")
    if err != nil {
        fmt.Println(err); os.Exit(1)
    }
    os.WriteFile("chrome-latest.json", []byte(j), 0644)
    fmt.Printf("wrote %d bytes\n", len(j))
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

j = httpcloak.describe_preset("chrome-latest")
with open("chrome-latest.json", "w") as f:
    f.write(j)
print(f"wrote {len(j)} bytes")
```

</TabItem>
</Tabs>

Dumps the entire shipped preset, fully resolved. No inheritance, no defaults
to chase. You'll see something like:

```json
{
  "version": 1,
  "preset": {
    "name": "chrome-148-linux",
    "tls": {
      "client_hello": "chrome-146-linux",
      "psk_client_hello": "chrome-146-linux-psk",
      "quic_client_hello": "chrome-146-quic",
      "quic_psk_client_hello": "chrome-146-quic-psk"
    },
    "http2": {
      "header_table_size": 65536,
      "initial_window_size": 6291456,
      "max_header_list_size": 262144,
      "settings_order": [1, 2, 4, 6],
      "pseudo_order": [":method", ":authority", ":scheme", ":path"],
      "stream_priority_mode": "chrome",
      "priority_table": { "...": "..." }
    },
    "headers": {
      "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36",
      "values": {
        "sec-ch-ua": "\"Chromium\";v=\"148\", \"Google Chrome\";v=\"148\", \"Not/A)Brand\";v=\"99\"",
        "sec-ch-ua-mobile": "?0",
        "sec-ch-ua-platform": "\"Linux\"",
        "Accept-Language": "en-US,en;q=0.9"
      },
      "order": [
        {"key": "sec-ch-ua", "value": "..."},
        {"key": "sec-ch-ua-mobile", "value": "..."},
        {"key": "sec-ch-ua-platform", "value": "..."},
        {"key": "upgrade-insecure-requests", "value": "1"},
        {"key": "user-agent", "value": "..."},
        {"key": "accept", "value": "..."}
      ]
    }
  }
}
```

## Step 3: Diff the capture vs the preset

Three spots where things usually drift:

| Field | Where in capture | Where in preset |
|-------|------------------|-----------------|
| User-Agent | `user_agent` top-level | `headers.user_agent` |
| sec-ch-ua brand list | inside `sent_frames[].headers` | `headers.values."sec-ch-ua"` |
| sec-ch-ua-platform | same | `headers.values."sec-ch-ua-platform"` |

Less common but still worth checking:

- `accept-language`, defaults vary by Chrome locale.
- TLS extensions. If the capture lists an extension that's not in the JA3
  string of the shipped preset, JSON won't save you. That's a utls profile
  bump. See
  [What is TLS fingerprinting](../fingerprinting/what-is-tls-fingerprinting).

In our example both the capture and the shipped preset are Chrome 148 on
Linux, so the deltas are minimal. If your capture is Chrome 150 on macOS,
you'd update:

```json
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/150.0.0.0 Safari/537.36",

"headers": {
  "values": {
    "sec-ch-ua": "\"Chromium\";v=\"150\", \"Google Chrome\";v=\"150\", \"Not/A)Brand\";v=\"99\"",
    "sec-ch-ua-platform": "\"macOS\""
  }
}
```

## Step 4: Edit and rename

Always rename. `RegisterStrict` (used internally by the loader) refuses to
shadow a built-in name, so you literally can't overwrite `chrome-latest` by
accident.

```json
{
  "version": 1,
  "preset": {
    "name": "chrome-148-linux-mine",
    "...": "everything else, edited as needed"
  }
}
```

## Step 5: Load + register

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "fmt"
    "os"

    "github.com/sardanioss/httpcloak/fingerprint"
)

func main() {
    data, err := os.ReadFile("chrome-148-linux-mine.json")
    if err != nil { fmt.Println(err); os.Exit(1) }

    p, err := fingerprint.LoadAndBuildPresetFromJSON(data)
    if err != nil { fmt.Println("build:", err); os.Exit(1) }

    if err := fingerprint.RegisterStrict("chrome-148-linux-mine", p); err != nil {
        fmt.Println("register:", err); os.Exit(1)
    }
    fmt.Println("registered chrome-148-linux-mine")
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import httpcloak

with open("chrome-148-linux-mine.json") as f:
    name = httpcloak.load_preset_from_json(f.read())
print(f"registered {name}")
```

</TabItem>
</Tabs>

## Step 6: Verify the round-trip

This is the step that actually matters. Hit tls.peet again with your new
preset, check the hashes line up with the original capture.

```go
package main

import (
    "context"
    "encoding/json"
    "fmt"
    "os"
    "time"

    "github.com/sardanioss/httpcloak"
)

type peet struct {
    HTTPV string `json:"http_version"`
    UA    string `json:"user_agent"`
    TLS   struct {
        Ja4      string `json:"ja4"`
        PeetHash string `json:"peetprint_hash"`
    } `json:"tls"`
    HTTP2 struct {
        AkamaiHash string `json:"akamai_fingerprint_hash"`
    } `json:"http2"`
}

func capture(preset string) peet {
    s := httpcloak.NewSession(preset, httpcloak.WithSessionTimeout(30*time.Second))
    defer s.Close()
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()
    r, _ := s.Get(ctx, "https://tls.peet.ws/api/all")
    defer r.Close()
    b, _ := r.Bytes()
    var p peet
    json.Unmarshal(b, &p)
    return p
}

func main() {
    base := capture("chrome-latest")
    mine := capture("chrome-148-linux-mine")

    fmt.Printf("ja4   base=%s mine=%s match=%v\n", base.TLS.Ja4, mine.TLS.Ja4, base.TLS.Ja4 == mine.TLS.Ja4)
    fmt.Printf("peet  base=%s mine=%s match=%v\n", base.TLS.PeetHash, mine.TLS.PeetHash, base.TLS.PeetHash == mine.TLS.PeetHash)
    fmt.Printf("akama base=%s mine=%s match=%v\n", base.HTTP2.AkamaiHash, mine.HTTP2.AkamaiHash, base.HTTP2.AkamaiHash == mine.HTTP2.AkamaiHash)
    fmt.Printf("ua    base=%s\n        mine=%s\n", base.UA, mine.UA)

    if base.TLS.Ja4 != mine.TLS.Ja4 || base.TLS.PeetHash != mine.TLS.PeetHash || base.HTTP2.AkamaiHash != mine.HTTP2.AkamaiHash {
        os.Exit(1)
    }
    fmt.Println("PASS")
}
```

Run it end-to-end and you should see `PASS`. Actual output from running this
recipe against the live tls.peet endpoint:

```
ja4   base=t13d1516h2_8daaf6152771_d8a2da3f94cd mine=t13d1516h2_8daaf6152771_d8a2da3f94cd match=true
peet  base=1d4ffe9b0e34acac0bd883fa7f79d7b5 mine=1d4ffe9b0e34acac0bd883fa7f79d7b5 match=true
akama base=52d84b11737d980aef856699f885ca86 mine=52d84b11737d980aef856699f885ca86 match=true
PASS
```

## Why JA3 might differ

Comparing JA3 hashes between two captures with the same preset? They won't
match. JA3 bakes raw TLS extension IDs into the string, and Chrome rotates
GREASE values on every connection. JA3 is unstable by design.

JA4, peetprint, and akamai hashes are all GREASE-normalised. Those are the
right metrics for "did my preset round-trip correctly?" If JA4 and peetprint
match, you're good, even if JA3 changes on every request.

:::warning
Don't use JA3 hash matching as your CI pass criterion. It'll flake. Use JA4
instead.
:::

## What this recipe doesn't cover

- **TLS extension order changes**: Chrome 150 adds a new extension or
  reshuffles them? JSON edits won't help. utls needs a profile bump.
- **HTTP/2 frame ordering**: shipped presets cover all the common Chrome
  shapes. If you spot a frame shape the shipped preset doesn't have, open
  an issue.
- **HTTP/3**: same deal. The shipped `quic_client_hello` references cover
  QUIC handshake bytes. JSON only touches headers, not the QUIC layer.

For any of those, the path is updating utls plus sardanioss/net, not
authoring JSON.

## Related

- [JSON Preset Builder](../fingerprinting/json-preset-builder), full JSON
  schema reference
- [Presets](../fingerprinting/presets), what we ship
- [Custom JA3](../fingerprinting/custom-ja3), bypassing the preset system
- [Akamai Shorthand](../fingerprinting/akamai-shorthand), HTTP/2 fingerprint
  format


---


<!-- source: docs/docs/recipes/long-running-scraper-patterns.md -->

# Long-Running Scraper Patterns

Scrapers that run for days hit two ugly problems:

1. **Connections age out.** Servers and load balancers close idle keep-alive
   connections. Some kill them mid-use. Your nice TLS tickets and 0-RTT
   setup get tossed.
2. **Session fingerprints get tracked.** A scraper that never refreshes its
   TCP connection looks nothing like a real browser. Real browsers cycle
   connections constantly.

The fix is a handful of patterns: periodic `Refresh()`, `Warmup()` at
startup, careful cookie handling, Save/Load across process restarts.

## Pattern 1: Periodic Refresh

Real browsers don't sit on TCP connections for hours. Keepalives time out,
users open new tabs, life happens. Your scraper should mimic that.

`session.Refresh()` drops every live connection but keeps:

- TLS session tickets (next handshake is 0-RTT)
- Cookies
- ECH config
- Preset plus any custom fingerprint overrides

Next request opens a fresh TCP socket but resumes TLS instantly with the
same cookies. From the server's POV that's a returning visitor with a
slightly older session, which is exactly what real browsers look like.

:::warning
Don't refresh after every request. That kills the point of session
continuity. Slow cadence, minutes not seconds.
:::

A solid default is every 2-5 minutes:

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "context"
    "fmt"
    "time"

    "github.com/sardanioss/httpcloak"
)

func main() {
    s := httpcloak.NewSession("chrome-latest", httpcloak.WithSessionTimeout(30*time.Second))
    defer s.Close()

    // Refresh ticker. Reasonable cadence: 2-5 min.
    refreshEvery := 3 * time.Minute
    nextRefresh := time.Now().Add(refreshEvery)

    for i := 0; i < 1000; i++ {
        ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
        r, err := s.Get(ctx, "https://example.com/page")
        cancel()
        if err != nil {
            fmt.Println("err:", err)
            time.Sleep(5 * time.Second)
            continue
        }
        r.Close()

        if time.Now().After(nextRefresh) {
            s.Refresh()
            nextRefresh = time.Now().Add(refreshEvery)
            fmt.Println("refreshed")
        }
    }
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import time
import httpcloak

with httpcloak.Session("chrome-latest", timeout=30) as s:
    refresh_every = 180  # seconds
    next_refresh = time.time() + refresh_every

    for i in range(1000):
        try:
            r = s.get("https://example.com/page")
        except Exception as e:
            print("err:", e)
            time.sleep(5)
            continue

        if time.time() > next_refresh:
            s.refresh()
            next_refresh = time.time() + refresh_every
            print("refreshed")
```

</TabItem>
</Tabs>

How fast is too fast? If your scraper sends one request every 30 seconds,
refreshing every 30 seconds means a fresh TCP/TLS handshake on every single
request. Even with 0-RTT that's wasted RTT. Refresh during idle gaps, not in
front of every request.

## Pattern 2: Warmup at startup

`Warmup(ctx, url)` mimics a real browser page load. Fetches the page HTML,
parses it, then pulls the obvious subresources (CSS, JS, fonts) with
realistic headers, priorities, and timing.

Once warmup runs, the session has:

- TLS session tickets for the target's edge servers
- Cookies set by the page and its subresources (analytics, CDN cookies)
- Cache headers (ETag, Last-Modified) ready for follow-up requests

So your first "real" scrape request looks like the second navigation inside
an already-open tab, which is way less suspicious than a cold first hit.

```go
s := httpcloak.NewSession("chrome-latest")
defer s.Close()

ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
defer cancel()

// One-time warmup. Hit the home page or a typical entry page.
if err := s.Warmup(ctx, "https://example.com"); err != nil {
    log.Printf("warmup soft-fail: %v", err)
    // Don't bail, warmup is opportunistic. If it fails, scrape anyway.
}

// Now run your scrape loop. The session has CDN cookies, tickets,
// and cache state populated.
scrapeLoop(ctx, s)
```

Warmup is opportunistic. Home page fails or hits a challenge? Log it and
keep going. The scrape loop should handle that case on its own.

:::tip
Got a heavy login flow? Do an authenticated warmup once per process: log in,
navigate, save with `Save()`. Later runs just `LoadSession()` from disk and
start scraping right away, no re-login dance.
:::

## Pattern 3: Cookie strategy

By default, sessions ship with a cookie jar. One jar per session, shared
across every request that goes through it.

Three patterns, depending on what you're scraping:

### One session, one target

The default. Shared cookie jar, every request through the same session sees
the same cookies.

```go
s := httpcloak.NewSession("chrome-latest")
// Hit target.com 1000 times. All requests share the cookie jar.
```

### N sessions, N targets (jar isolation)

Hitting N different targets? You almost always want one session per target.
Cookies stay scoped, no leaks across hosts:

```go
sessions := map[string]*httpcloak.Session{
    "site-a.com": httpcloak.NewSession("chrome-latest"),
    "site-b.com": httpcloak.NewSession("chrome-latest"),
    "site-c.com": httpcloak.NewSession("chrome-latest"),
}
defer func() {
    for _, s := range sessions {
        s.Close()
    }
}()

// Route each request to the right session by host.
```

Bonus: each session warms up independently against its own target, and you
Save/Load each one separately.

### Manual cookie management

Got weird requirements? Sharing one cookie across multiple sessions, A/B
testing two cookie sets against the same site, that kind of thing. Use
`WithoutCookieJar()` and set the `Cookie` header yourself on every request:

```go
s := httpcloak.NewSession("chrome-latest", httpcloak.WithoutCookieJar())

req := &httpcloak.Request{
    Method: "GET",
    URL:    "https://example.com/page",
    Headers: map[string][]string{
        "Cookie": {"session=abc123; csrf=xyz"},
    },
}
resp, _ := s.Do(ctx, req)
```

You lose automatic cookie tracking. Set-Cookie response headers are now
your problem to parse. Most scrapers should NOT go this route.

## Pattern 4: Save / LoadSession across restarts

Scraper runs for hours and might crash or restart? Save state to disk
periodically. On startup, load it. Crashes survive without losing warmed-up
tickets, ECH config, or cookies.

```go
const stateFile = "/var/lib/scraper/state.json"

func main() {
    var s *httpcloak.Session

    // Try to load from disk. If it fails, start fresh.
    if loaded, err := httpcloak.LoadSession(stateFile); err == nil {
        s = loaded
        log.Println("loaded state from disk")
    } else {
        s = httpcloak.NewSession("chrome-latest")
        // Cold-start warmup.
        ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
        s.Warmup(ctx, "https://example.com")
        cancel()
    }
    defer s.Close()

    // Save every 5 minutes.
    saveTicker := time.NewTicker(5 * time.Minute)
    defer saveTicker.Stop()

    go func() {
        for range saveTicker.C {
            if err := s.Save(stateFile); err != nil {
                log.Printf("save: %v", err)
            }
        }
    }()

    // Save on shutdown.
    defer func() {
        if err := s.Save(stateFile); err != nil {
            log.Printf("save on shutdown: %v", err)
        }
    }()

    scrapeLoop(s)
}
```

Don't want a file? Use `Marshal()` / `UnmarshalSession()` to serialise to
bytes (e.g. stash it in Redis):

```go
data, _ := s.Marshal()
redisClient.Set(ctx, "scraper:state", data, 24*time.Hour)

// Later:
data, _ := redisClient.Get(ctx, "scraper:state").Bytes()
s, _ := httpcloak.UnmarshalSession(data)
```

## Putting it together

The full long-running pattern in pseudocode shape:

```go
func main() {
    s := loadOrCreate("state.json")
    defer s.Close()
    defer s.Save("state.json")

    refreshEvery := 3 * time.Minute
    saveEvery := 5 * time.Minute

    nextRefresh := time.Now().Add(refreshEvery)
    nextSave := time.Now().Add(saveEvery)

    for {
        url, ok := nextWorkItem()
        if !ok {
            break
        }

        ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
        resp, err := s.Get(ctx, url)
        cancel()

        if err != nil {
            handleError(err)
            continue
        }
        process(resp)
        resp.Close()

        if time.Now().After(nextRefresh) {
            s.Refresh()
            nextRefresh = time.Now().Add(refreshEvery)
        }
        if time.Now().After(nextSave) {
            s.Save("state.json")
            nextSave = time.Now().Add(saveEvery)
        }
    }
}

func loadOrCreate(path string) *httpcloak.Session {
    if s, err := httpcloak.LoadSession(path); err == nil {
        return s
    }
    s := httpcloak.NewSession("chrome-latest")
    ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
    defer cancel()
    s.Warmup(ctx, "https://example.com")
    return s
}
```

Tune cadences to your target. Faster scrapers want longer refresh intervals
(don't cycle TCP under sub-second request load). Slower scrapers running
once a minute can refresh every 5-10 minutes no problem.

## Things to NOT do

- **Don't refresh on every request.** You're tossing the connection benefit
  you just paid for.
- **Don't save state on every request.** Disk IO will dominate. Every few
  minutes is plenty.
- **Don't share one session across very different targets.** Cookies leak
  across hosts in the jar. One session per target is safer.
- **Don't forget `resp.Close()`.** Body leaks tie up connection resources,
  which makes Refresh way less effective.

## Forking sessions for parallel scrapes

Want N parallel workers all hitting the same target with the same warm
session state? Use `Fork(n)`:

```go
s := httpcloak.NewSession("chrome-latest")
s.Warmup(ctx, "https://example.com")

workers := s.Fork(8)
var wg sync.WaitGroup
for _, w := range workers {
    wg.Add(1)
    go func(w *httpcloak.Session) {
        defer wg.Done()
        defer w.Close()
        runWorkerLoop(w)
    }(w)
}
wg.Wait()
s.Close()
```

Each forked session shares the cookie jar and the TLS ticket cache (so all
8 workers get 0-RTT on the first request) but keeps its own connection
state. Basically 8 browser tabs sharing one profile.

## Related

- [Refresh](../connection-lifecycle/refresh), what `Refresh()` does
- [Warmup](../connection-lifecycle/warmup), full warmup mechanics
- [Session Save/Restore](../connection-lifecycle/session-save-restore), Save / Load API
- [Cookies and State](../cookies-and-state/), cookie jar internals


---


<!-- source: docs/docs/recipes/debug-with-wireshark.md -->

# Debug With Wireshark

When you really need to see what httpcloak puts on the wire, dump TLS keys
and decrypt in Wireshark. Lowest-level view you can get short of stepping
through the library with a debugger.

:::info
For fingerprinting issues, Wireshark plus keylog is the ground truth.
tls.peet.ws is handy but it's a server-side reconstruction, not the actual
wire bytes. They mostly agree. When they don't, Wireshark wins.
:::

## What you'll see

Once decrypted, you can read:

- The full TLS ClientHello with extension order, GREASE values, key shares,
  the works.
- Every HTTP/2 frame: SETTINGS, WINDOW_UPDATE, HEADERS, PRIORITY,
  PRIORITY_UPDATE.
- HPACK-decoded headers (Wireshark does the HPACK decode for you).
- Every QUIC frame for HTTP/3, including PRIORITY_UPDATE and STREAM frames.
- Server response framing, server settings, connection-level windowing.

For HTTP/2 fingerprint checks specifically: SETTINGS values, settings order,
the first PRIORITY frame on a request stream, header order in HEADERS
frames. All in plain bytes.

## Step 1: Dump TLS keys from your code

Use `WithKeyLogFile` to write the SSLKEYLOGFILE format Wireshark wants.

<Tabs groupId="lang">
<TabItem value="go" label="Go">

```go
package main

import (
    "context"
    "fmt"
    "os"
    "time"

    "github.com/sardanioss/httpcloak"
)

func main() {
    keyLogPath := "/tmp/sslkeys.log"
    // Make sure the file is fresh, old keys won't decrypt new traffic.
    os.Remove(keyLogPath)

    s := httpcloak.NewSession("chrome-latest",
        httpcloak.WithKeyLogFile(keyLogPath),
        httpcloak.WithSessionTimeout(30*time.Second),
    )
    defer s.Close()

    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    r, err := s.Get(ctx, "https://tls.peet.ws/api/all")
    if err != nil {
        fmt.Println("err:", err); os.Exit(1)
    }
    defer r.Close()
    fmt.Println("status:", r.StatusCode, "proto:", r.Protocol)
    fmt.Println("keys written to:", keyLogPath)
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import os
import httpcloak

keylog = "/tmp/sslkeys.log"
if os.path.exists(keylog):
    os.remove(keylog)

with httpcloak.Session("chrome-latest", key_log_file=keylog, timeout=30) as s:
    r = s.get("https://tls.peet.ws/api/all")
    print(f"status={r.status_code} proto={r.protocol}")
    print(f"keys written to {keylog}")
```

</TabItem>
</Tabs>

`WithKeyLogFile` overrides the global `SSLKEYLOGFILE` env var for this one
session. Want to set it once for every session in the process? Export the
env var before running:

```bash
export SSLKEYLOGFILE=/tmp/sslkeys.log
go run main.go
```

httpcloak picks it up at startup automatically.

## Step 2: Verify the keylog file

After your program runs, the file should look like this (one line per
secret, NSS keylog format):

```
CLIENT_HANDSHAKE_TRAFFIC_SECRET <client_random> <secret>
SERVER_HANDSHAKE_TRAFFIC_SECRET <client_random> <secret>
CLIENT_TRAFFIC_SECRET_0 <client_random> <secret>
SERVER_TRAFFIC_SECRET_0 <client_random> <secret>
```

Four lines per TLS 1.3 connection. Fewer than that and the connection
didn't complete. Zero lines and either the file path is wrong or the
session died before hitting the application data stage.

Quick sanity check:

```bash
$ wc -l /tmp/sslkeys.log
4 /tmp/sslkeys.log

$ awk '{print $1}' /tmp/sslkeys.log | sort -u
CLIENT_HANDSHAKE_TRAFFIC_SECRET
CLIENT_TRAFFIC_SECRET_0
SERVER_HANDSHAKE_TRAFFIC_SECRET
SERVER_TRAFFIC_SECRET_0
```

That's a healthy single-connection keylog.

For QUIC / HTTP/3, you'll see the same four labels plus maybe
`EARLY_TRAFFIC_SECRET` if 0-RTT fired. Recent Wireshark versions read QUIC
and TLS keys from the same file.

## Step 3: Capture traffic

Start Wireshark BEFORE you run your program. Otherwise you miss the
ClientHello and the rest of the trace is uselessly opaque.

Useful capture filters:

| Filter | What it captures |
|--------|------------------|
| `tcp port 443` | All HTTPS over TCP (H1, H2) |
| `udp port 443` | All QUIC (H3) |
| `tcp port 443 or udp port 443` | Both |
| `host tls.peet.ws` | Just traffic to a specific host |

For headless work, `tshark` is the CLI version:

```bash
sudo tshark -i any -f "tcp port 443 or udp port 443" -w /tmp/capture.pcapng
```

Run your Go / Python program while tshark captures, then Ctrl-C tshark.

## Step 4: Point Wireshark at the keylog

In Wireshark:

1. **Edit** → **Preferences** → **Protocols** → **TLS**.
2. **(Pre)-Master-Secret log filename** → `/tmp/sslkeys.log`.
3. OK.

Wireshark re-decodes the capture right there. Any TLS connection whose
`client_random` matches a line in the keylog gets fully decrypted.

QUIC needs zero extra setup. Same TLS keylog config covers it.

## Step 5: Useful display filters

After decryption, the filters worth knowing:

| Filter | Shows |
|--------|-------|
| `tls.handshake.type == 1` | Just ClientHello frames |
| `http2` | All HTTP/2 frames |
| `http2.type == 4` | HTTP/2 SETTINGS frames |
| `http2.type == 2` | HTTP/2 PRIORITY frames |
| `http2.type == 1` | HTTP/2 HEADERS frames |
| `http2.type == 12` | HTTP/2 PRIORITY_UPDATE (RFC 9218) |
| `quic` | All QUIC frames |
| `http3` | All HTTP/3 frames |
| `http3.frame_type == 0xf0700` | H3 PRIORITY_UPDATE |
| `tls.handshake.extension.type` | Group by extension type |

## Things to look for

### TLS ClientHello

Click the ClientHello, expand **Secure Sockets Layer** → **TLS** →
**Handshake** → **Extensions**. You should see:

- Extension order matching your preset's JA4 / peetprint.
- GREASE extension at position 0 (Chrome-style presets only).
- `key_share` carrying the same curves as your preset's `key_share_curves`
  list. Modern Chrome ships GREASE + X25519MLKEM768 + X25519.
- ALPN listing `h2` and `http/1.1` (or just `h3` for QUIC).

### HTTP/2 SETTINGS

Filter: `http2.type == 4`. The first SETTINGS frame from your client
should match your preset's settings:

- Setting 1 (HEADER_TABLE_SIZE): 65536 for Chrome.
- Setting 2 (ENABLE_PUSH): 0.
- Setting 4 (INITIAL_WINDOW_SIZE): 6291456 for Chrome.
- Setting 6 (MAX_HEADER_LIST_SIZE): 262144 for Chrome.

These should land in the order your preset's `settings_order` specifies.
Wireshark shows them sequentially, so order is visible right in the tree
view.

### HTTP/2 PRIORITY on first request stream

For RFC 7540 priorities (Chrome shape), the HEADERS frame on stream 1
carries a PRIORITY flag (`0x20`). Expand **HyperText Transfer Protocol 2**
→ **Stream** → **Header**. Look for:

- `Stream Dependency`: 0
- `Weight`: 256 (Chrome) or whatever your preset says
- `Exclusive Bit`: set

If `stream_priority_mode` is `chrome` and this priority isn't showing up on
the first request, something's busted.

### HTTP/3 PRIORITY_UPDATE

For HTTP/3, hunt for QUIC stream frames carrying H3 PRIORITY_UPDATE
(frame type 0xf0700). They should reference the actual request stream ID,
not stream 0. Older versions had a regression where the request stream
wasn't referenced correctly. Wireshark is the most direct way to confirm
your install actually behaves.

### HPACK / QPACK header order

Click the HEADERS / QPACK encoder stream. Wireshark decodes the headers
into a list. The order should match your preset's `hpack_header_order`
(H2) or QPACK ordering (H3). Pseudo-headers come first, specifically in
this order:

```
:method  :authority  :scheme  :path
```

That's the Chrome `pseudo_order`. Other shapes are visible too. Safari, for
instance, puts `:scheme` before `:authority`.

## tshark for CI

Want to assert these things in tests instead of eyeballing them:

```bash
# Extract just the SETTINGS frames as JSON
tshark -r capture.pcapng -Y "http2.type == 4" \
  -T fields -e http2.settings.identifier -e http2.settings.value

# Print all extension types in the first ClientHello
tshark -r capture.pcapng -Y "tls.handshake.type == 1" \
  -T fields -e tls.handshake.extension.type
```

Wire those into a test harness, capture a known-good run, compare extension
types and order on every CI run.

## Common gotchas

**Old keylog file.** Reusing a keylog from a previous run won't decrypt new
connections because the `client_random` is different. Always start with a
fresh file, or delete before each run.

**Capture started after the handshake.** Start tshark / Wireshark
mid-connection and you'll miss the ClientHello. The keys are still valid,
but Wireshark needs the handshake bytes to tie keys to the connection.

**HTTP/3 falling back to TCP.** If H3 dial fails and the library falls back
to H2, you'll see TCP instead of UDP. Not a bug, but worth knowing. Check
the `Protocol` field of your response: `h3` means UDP, `h2` means TCP.

**Network namespace mismatch.** Code running inside a container or netns
while tshark runs on the host? You won't see the traffic. Run tshark in the
same namespace.

## Related

- [Akamai Shorthand](../fingerprinting/akamai-shorthand), what the SETTINGS
  values mean
- [Per-resource Priority](../fingerprinting/per-resource-priority), what
  PRIORITY frames are for
- [What is TLS Fingerprinting](../fingerprinting/what-is-tls-fingerprinting)
 , the ClientHello you're inspecting


---


<!-- source: docs/docs/recipes/local-proxy-server.md -->

# Local Proxy Server

You've already got a Python scraper. Or a Node service. Or a .NET app some intern wrote three years ago and nobody wants to touch. Swapping the HTTP client out for a fingerprinted one isn't on the table. `LocalProxy` is the escape hatch: run httpcloak as a tiny HTTP proxy on `127.0.0.1`, point your existing client at it, and every request that goes through gets Chrome-grade TLS and H2 fingerprinting on the way out.

It's a drop-in. No SDK install in the target language, no code changes beyond a proxy URL in your client config. Anything that speaks "HTTP proxy" works: `requests`, `fetch`, `curl`, Undici, `HttpClient`, Playwright, your Bash one-liner from 2019.

## Quick start

Spin one up in Go and curl it:

```go
package main

import (
    "log"
    "github.com/sardanioss/httpcloak"
)

func main() {
    lp, err := httpcloak.StartLocalProxy(8080,
        httpcloak.WithProxyPreset("chrome-latest"),
    )
    if err != nil { log.Fatal(err) }
    defer lp.Stop()

    log.Printf("listening on :%d", lp.Port())
    select {} // block forever
}
```

Then, from anywhere on the box:

```bash
curl -x http://127.0.0.1:8080 https://tls.peet.ws/api/all
```

The response body holds the JA4, JA3, akamai hash, peetprint hash. They'll match real Chrome, not Go's default client. Job done.

:::tip
The proxy binds to `127.0.0.1` only, never `0.0.0.0`. That's deliberate. You don't want a fingerprinting proxy reachable from your LAN by accident. If you need it on a different host, run it inside that host or front it with something like `socat` or an SSH tunnel you actually trust.
:::

## Options

Pass these to `StartLocalProxy(port, opts...)`:

| Option | What it does |
| --- | --- |
| `WithProxyPreset(name)` | Pick the fingerprint preset (e.g. `chrome-latest`, `firefox-148`, `safari-tp`). Default is `chrome-146`. |
| `WithProxyTimeout(d)` | Per-request timeout. Default 30s. |
| `WithProxyMaxConnections(n)` | Hard cap on concurrent client connections. New ones get dropped above the cap. Default 1000. |
| `WithProxyUpstream(tcp, udp)` | Chain through an upstream proxy (SOCKS5 or HTTP). UDP arg is for H3 / QUIC. |
| `WithProxyTLSOnly()` | Apply TLS+H2 fingerprinting but don't rewrite HTTP headers. Use this when your client already sends authentic browser headers (Playwright, real browsers driven by CDP). |
| `WithProxySessionCache(backend, errCb)` | Plug in a distributed TLS session ticket cache so multiple proxy instances share resumption state. |

Pass `0` as the port to let the kernel pick one, then read it back with `lp.Port()`.

## Lifecycle

The returned `*LocalProxy` is the whole control surface:

| Method | Returns |
| --- | --- |
| `Stop() error` | Graceful shutdown. Closes the listener, waits up to 10s for in-flight requests, closes the underlying session and idle conns. Idempotent. |
| `Port() int` | The port the proxy actually bound to. Useful when you started with `0`. |
| `IsRunning() bool` | True between successful `StartLocalProxy` and `Stop`. |
| `Stats() map[string]interface{}` | Snapshot: `running`, `port`, `active_conns`, `total_requests`, `preset`, `max_connections`, `registered_sessions`. Cheap, no locks held during the call. |

Wire it into your shutdown handler, scrape `Stats()` into Prometheus, you're set.

## Session registry: one proxy, many fingerprints

Sometimes you want the same proxy port to serve different "users", each with their own cookies, IP, and TLS state. That's what the registry is for. You pre-build sessions, register them with an ID, and the client picks one per-request via the `X-HTTPCloak-Session` header.

```go
lp, _ := httpcloak.StartLocalProxy(8080, httpcloak.WithProxyPreset("chrome-latest"))
defer lp.Stop()

// One session per persona, each with its own proxy and cookie jar
alice := httpcloak.NewSession("chrome-latest",
    httpcloak.WithSessionTCPProxy("socks5://user1:pass@residential.example:1080"))
bob := httpcloak.NewSession("firefox-148",
    httpcloak.WithSessionTCPProxy("socks5://user2:pass@residential.example:1080"))

lp.RegisterSession("alice", alice)
lp.RegisterSession("bob", bob)
```

From the client side, just set the header:

```bash
curl -x http://127.0.0.1:8080 \
     -H "X-HTTPCloak-Session: alice" \
     https://example.com/profile
```

Registry methods:

| Method | What it does |
| --- | --- |
| `RegisterSession(id, *Session) error` | Adds a session under `id`. Errors if the ID already exists. Sets the session's identifier so distributed TLS caches stay isolated per persona. |
| `UnregisterSession(id) *Session` | Removes the session and returns it. Does NOT close it: that's your call, since you might reuse it. |
| `GetSession(id) *Session` | Direct lookup. Returns `nil` if missing. |
| `ListSessions() []string` | All registered IDs. Handy for `/health` endpoints. |

Unknown session IDs return a 400 from the proxy, so typos surface fast instead of silently falling back to the default session.

:::info
The registry is just a routing layer. The sessions you register are normal `*Session` values: same options, same cookie jar, same `Refresh()` semantics. You can swap their proxies on the fly with `SetTCPProxy`, and the next request through the registry picks up the change.
:::

## Hitting the proxy from any language

The whole point is that you don't need an httpcloak SDK in the calling language. Standard HTTP-proxy config does it.

<Tabs groupId="lang">
<TabItem value="python" label="Python">

```python
import requests

proxies = {
    "http":  "http://127.0.0.1:8080",
    "https": "http://127.0.0.1:8080",
}

# Per-request session pick
headers = {"X-HTTPCloak-Session": "alice"}

r = requests.get("https://tls.peet.ws/api/all", proxies=proxies, headers=headers)
print(r.json()["tls"]["ja4"])
```

</TabItem>
<TabItem value="node" label="Node.js">

```js

const dispatcher = new ProxyAgent("http://127.0.0.1:8080");

const r = await fetch("https://tls.peet.ws/api/all", {
  dispatcher,
  headers: { "X-HTTPCloak-Session": "alice" },
});

console.log((await r.json()).tls.ja4);
```

</TabItem>
<TabItem value="go" label="Go">

```go
proxyURL, _ := url.Parse("http://127.0.0.1:8080")
client := &http.Client{
    Transport: &http.Transport{Proxy: http.ProxyURL(proxyURL)},
}
req, _ := http.NewRequest("GET", "https://tls.peet.ws/api/all", nil)
req.Header.Set("X-HTTPCloak-Session", "alice")
resp, _ := client.Do(req)
```

</TabItem>
<TabItem value="dotnet" label=".NET">

```csharp
using System.Net;
using System.Net.Http;

var handler = new HttpClientHandler {
    Proxy = new WebProxy("http://127.0.0.1:8080"),
    UseProxy = true,
};
using var client = new HttpClient(handler);
client.DefaultRequestHeaders.Add("X-HTTPCloak-Session", "alice");

var r = await client.GetStringAsync("https://tls.peet.ws/api/all");
Console.WriteLine(r);
```

</TabItem>
<TabItem value="curl" label="curl">

```bash
curl -x http://127.0.0.1:8080 \
     -H "X-HTTPCloak-Session: alice" \
     https://tls.peet.ws/api/all
```

</TabItem>
</Tabs>

For HTTPS targets the proxy uses `Session.DoStream()` under the hood, so you get the full fingerprint stack: TLS, H2 SETTINGS, pseudo-header order, the works. For plain HTTP it just forwards fast since there's no TLS to fingerprint anyway.

## What's next

- [Multi-Proxy Rotation With State](./multi-proxy-rotation-with-state): rotate IPs under a single registered session without burning tickets.
- [Long-Running Scraper Patterns](./long-running-scraper-patterns): lifecycle and refresh strategies that play nicely with the registry.


---


<!-- source: docs/docs/changelog.md -->

# Changelog

The full release history lives in [`CHANGELOG.md`](https://github.com/sardanioss/httpcloak/blob/main/CHANGELOG.md) on GitHub. It is updated on every release and follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) plus [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

For a high-level catalog of features, see the [home page](/). For the full option surface, see [Reference / Options](./reference/options).


---