foghttp 0.3.7__tar.gz → 0.3.8__tar.gz

{foghttp-0.3.7 → foghttp-0.3.8}/Cargo.lock

@@ -92,6 +92,12 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "fastrand"
+version = "2.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
+
 [[package]]
 name = "find-msvc-tools"
 version = "0.1.9"
@@ -110,12 +116,14 @@ dependencies = [
 
 [[package]]
 name = "foghttp"
-version = "0.3.7"
+version = "0.3.8"
 dependencies = [
  "brotli",
  "bytes",
+ "fastrand",
  "flate2",
  "http-body-util",
+ "httpdate",
  "hyper",
  "hyper-rustls",
  "hyper-util",
@@ -224,6 +232,12 @@ version = "1.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
 
+[[package]]
+name = "httpdate"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
+
 [[package]]
 name = "hyper"
 version = "1.10.1"

{foghttp-0.3.7 → foghttp-0.3.8}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "foghttp"
-version = "0.3.7"
+version = "0.3.8"
 description = "Observable Rust-powered HTTP client for Python services."
 edition = "2021"
 homepage = "https://github.com/AmberFog/foghttp"
@@ -20,8 +20,10 @@ extension-module = ["pyo3/extension-module"]
 [dependencies]
 brotli = "8.0.4"
 bytes = "1.12.0"
+fastrand = "2.3.0"
 flate2 = "1.1.9"
 http-body-util = "0.1.3"
+httpdate = "1.0.3"
 url = "2.5.8"
 
 [dependencies.hyper]

{foghttp-0.3.7 → foghttp-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: foghttp
-Version: 0.3.7
+Version: 0.3.8
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: AsyncIO
 Classifier: License :: OSI Approved :: MIT License
@@ -74,6 +74,8 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
 - typed telemetry event hooks with redacted request/response lifecycle events
 - versioned telemetry snapshots that separate alert-oriented stats from
   diagnostic dump APIs
+- opt-in Rust-owned retries with replayability gates and immutable attempt
+  traces, plus opt-in per-hop and post-DNS SSRF destination controls
 - opt-in async lifecycle debug snapshots for staging and tests
 - lazy process-wide shared Tokio runtime by default, opt-in dedicated runtime
   tuning, and fail-closed client ownership across `fork()`
@@ -170,6 +172,10 @@ async with foghttp.AsyncClient() as client:
   response body, and request completion lifecycle
 - opt-in typed transport policy hooks for lightweight request admission and
   response-head checks without default-path Python callbacks
+- opt-in Rust-owned retry policy for selected statuses and pre-header network
+  failures, with safe methods, replayable bodies, and immutable attempt traces
+- opt-in Rust-owned SSRF destination policy with per-hop allowlists,
+  post-resolution IP checks, and DNS rebinding mitigation
 - versioned telemetry snapshot metadata for `stats()`, `dump_transport_state()`,
   and `dump_pool_diagnostics()`
 - opt-in async lifecycle debug mode for active request snapshots, strict leak
@@ -189,6 +195,8 @@ async with foghttp.AsyncClient() as client:
 - [Timeout model](https://github.com/AmberFog/foghttp/blob/main/docs/timeouts.md)
 - [Upload typing contracts](https://github.com/AmberFog/foghttp/blob/main/docs/upload-types.md)
 - [Transport policy hooks](https://github.com/AmberFog/foghttp/blob/main/docs/policy-hooks.md)
+- [Retry policy](https://github.com/AmberFog/foghttp/blob/main/docs/retries.md)
+- [SSRF protection](https://github.com/AmberFog/foghttp/blob/main/docs/ssrf.md)
 - [Telemetry contract](https://github.com/AmberFog/foghttp/blob/main/docs/telemetry.md)
 - [Response streaming](https://github.com/AmberFog/foghttp/blob/main/docs/streaming.md)
 - [Proxy and trust_env](https://github.com/AmberFog/foghttp/blob/main/docs/proxies.md)
@@ -207,7 +215,8 @@ available as bytes/text/line context-managed APIs. Streaming `content=` uploads
 and multipart `files=` uploads are available with explicit replayability and
 cleanup rules. HTTP proxy routing and HTTPS proxy `CONNECT` tunnelling are
 available through `proxy=` and `trust_env=True` when the proxy endpoint itself
-uses `http://`.
+uses `http://`. Proxy-routed requests fail closed when `SSRFPolicy` is enabled
+because the client cannot prove which target address a remote proxy resolves.
 Cookies, auth helpers, HTTP/2, automatic `Accept-Encoding` negotiation,
 streaming decompression, and per-request connect timeout reconfiguration are
 planned for later versions. Physical connection caps currently apply to the

{foghttp-0.3.7 → foghttp-0.3.8}/README.md

@@ -31,6 +31,8 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
 - typed telemetry event hooks with redacted request/response lifecycle events
 - versioned telemetry snapshots that separate alert-oriented stats from
   diagnostic dump APIs
+- opt-in Rust-owned retries with replayability gates and immutable attempt
+  traces, plus opt-in per-hop and post-DNS SSRF destination controls
 - opt-in async lifecycle debug snapshots for staging and tests
 - lazy process-wide shared Tokio runtime by default, opt-in dedicated runtime
   tuning, and fail-closed client ownership across `fork()`
@@ -127,6 +129,10 @@ async with foghttp.AsyncClient() as client:
   response body, and request completion lifecycle
 - opt-in typed transport policy hooks for lightweight request admission and
   response-head checks without default-path Python callbacks
+- opt-in Rust-owned retry policy for selected statuses and pre-header network
+  failures, with safe methods, replayable bodies, and immutable attempt traces
+- opt-in Rust-owned SSRF destination policy with per-hop allowlists,
+  post-resolution IP checks, and DNS rebinding mitigation
 - versioned telemetry snapshot metadata for `stats()`, `dump_transport_state()`,
   and `dump_pool_diagnostics()`
 - opt-in async lifecycle debug mode for active request snapshots, strict leak
@@ -146,6 +152,8 @@ async with foghttp.AsyncClient() as client:
 - [Timeout model](https://github.com/AmberFog/foghttp/blob/main/docs/timeouts.md)
 - [Upload typing contracts](https://github.com/AmberFog/foghttp/blob/main/docs/upload-types.md)
 - [Transport policy hooks](https://github.com/AmberFog/foghttp/blob/main/docs/policy-hooks.md)
+- [Retry policy](https://github.com/AmberFog/foghttp/blob/main/docs/retries.md)
+- [SSRF protection](https://github.com/AmberFog/foghttp/blob/main/docs/ssrf.md)
 - [Telemetry contract](https://github.com/AmberFog/foghttp/blob/main/docs/telemetry.md)
 - [Response streaming](https://github.com/AmberFog/foghttp/blob/main/docs/streaming.md)
 - [Proxy and trust_env](https://github.com/AmberFog/foghttp/blob/main/docs/proxies.md)
@@ -164,7 +172,8 @@ available as bytes/text/line context-managed APIs. Streaming `content=` uploads
 and multipart `files=` uploads are available with explicit replayability and
 cleanup rules. HTTP proxy routing and HTTPS proxy `CONNECT` tunnelling are
 available through `proxy=` and `trust_env=True` when the proxy endpoint itself
-uses `http://`.
+uses `http://`. Proxy-routed requests fail closed when `SSRFPolicy` is enabled
+because the client cannot prove which target address a remote proxy resolves.
 Cookies, auth helpers, HTTP/2, automatic `Accept-Encoding` negotiation,
 streaming decompression, and per-request connect timeout reconfiguration are
 planned for later versions. Physical connection caps currently apply to the

{foghttp-0.3.7 → foghttp-0.3.8}/docs/index.md

@@ -4,7 +4,7 @@ layout: "home"
 hero:
   name: "FogHTTP"
   text: "Rust-powered HTTP client for Python"
-  tagline: "Buffered JSON and form requests, streaming and multipart uploads, sync and async response streaming, transparent response decoding, base URL clients, default headers and params, sync and async APIs, redirects, custom CA certificates, cancellation, and observable request limits with pool diagnostics."
+  tagline: "Buffered JSON and form requests, streaming and multipart uploads, sync and async response streaming, transparent response decoding, base URL clients, default headers and params, opt-in safe retries and SSRF destination controls, redirects, custom CA certificates, cancellation, and observable request limits with pool diagnostics."
 
 features:
   - title: "Rust transport"
@@ -62,6 +62,10 @@ FogHTTP is designed around a few engineering priorities:
   events
 - opt-in typed transport policy hooks for lightweight request admission and
   response-head checks, with Rust-owned redirect safety
+- opt-in Rust-owned retry policy with safe-method defaults, replayability
+  gating, bounded backoff, typed decisions, and immutable attempt traces
+- opt-in Rust-owned SSRF destination policy with per-hop allowlists,
+  post-resolution IP checks, and DNS rebinding mitigation
 - versioned telemetry snapshots that separate alert-oriented stats from
   diagnostic dump APIs
 - opt-in async lifecycle debug snapshots for tests, staging, and incident
@@ -79,6 +83,8 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
 - [Timeout model](./timeouts.md)
 - [Upload typing contracts](./upload-types.md)
 - [Transport policy hooks](./policy-hooks.md)
+- [Retry policy](./retries.md)
+- [SSRF protection](./ssrf.md)
 - [Telemetry contract](./telemetry.md)
 - [Response streaming](./streaming.md)
 - [TLS trust](./tls.md)
@@ -98,6 +104,9 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
 - cancellable buffered async requests
 - bounded sync and async response streaming
 - prepared requests that can be inspected before sending
+- opt-in safe retries with request-scoped attempt diagnostics
+- direct service clients that need an opt-in SSRF guard for partially trusted
+  destination URLs
 - simple benchmarks against other buffered HTTP clients
 
 ## Key Features
@@ -136,6 +145,10 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
   response body, and request completion lifecycle
 - opt-in typed transport policy hooks with immutable request/response views and
   no default-path Python callback
+- opt-in retry policy for selected statuses and pre-header network failures,
+  with safe methods, replayable bodies, and immutable attempt traces
+- opt-in SSRF destination policy that validates initial and redirected targets,
+  then pins each connection attempt to its checked DNS result
 - versioned telemetry snapshot metadata for `stats()`, `dump_transport_state()`,
   and `dump_pool_diagnostics()`
 - opt-in async lifecycle debug mode for active request snapshots and strict

{foghttp-0.3.7 → foghttp-0.3.8}/docs/limitations.md

@@ -55,6 +55,12 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
   response body, and request completion lifecycle
 - opt-in synchronous transport policy hooks with immutable request/response
   snapshots and Rust-owned redirect safety
+- opt-in retry policy for selected statuses and pre-header network failures,
+  gated by method safety and request-body replayability, with immutable
+  request-scoped attempt traces on responses and terminal `FogHTTPError`
+- opt-in SSRF destination policy with scheme/origin/domain allowlists,
+  per-redirect checks, post-resolution address validation, and typed redacted
+  `SSRFError` reasons
 - opt-in async lifecycle debug snapshots for active async request handles,
   pending transport pressure, strict test checks, and unclosed-client context
 - default per-response and aggregate buffered response memory limits
@@ -99,6 +105,8 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
 | socket lifecycle telemetry granularity | `TransportStats` and `dump_transport_state()["origins"]` expose opened, open-failed, closed, reused, aborted, idle-timeout eviction, active, and idle tracked connection counters for the current HTTP/1 path; dedicated failed-reuse and close-reason taxonomy are not exposed yet because current connector hooks do not provide a stable reason signal |
 | telemetry hook granularity | `TelemetryConfig` currently dispatches Python-level request/response lifecycle events; lower-level Rust pool acquire and connection lifecycle event delivery is planned before Prometheus/OpenTelemetry exporters |
 | transport policy hook execution | `TransportPolicyHooks` callbacks are synchronous, inline, non-reentrant, and may run on Rust transport worker threads; `after_response_body` observes only redirect bodies consumed internally, not the final response body returned to the caller |
+| retry scope | Retry is client-level and opt-in. It covers configured response statuses and pre-header `NetworkError` only; response-body errors, FogHTTP timeouts, local upload-provider failures, auth refresh, hedging, and circuit breaking are not retried. |
+| SSRF protection scope | `SSRFPolicy` is client-level and opt-in. It validates initial and redirected destinations plus every resolved address, but it is not a replacement for network egress policy. Proxy routes fail closed because a remote proxy can resolve the target independently. |
 | diagnostic snapshot transactionality | `stats()`, `dump_transport_state()`, and `dump_pool_diagnostics()` include `schema_version` and a monotonic `snapshot_sequence`, but the `dump_*` APIs remain diagnostic snapshots rather than lock-protected SLA transactions; use `stats()` for alert-oriented low-cardinality metrics |
 
 ## Practical Guidance
@@ -116,6 +124,8 @@ Use FogHTTP today when:
 - async request cancellation and sync/async stream cleanup behavior are useful
 - global/per-origin request-slot backpressure and opt-in global/per-host
   physical connection caps are enough for your resource control needs
+- you accept partially trusted destination URLs and can use direct connections
+  with an explicit client-level `SSRFPolicy`
 - you can reuse clients instead of creating many short-lived transport and pool
   instances once requests start flowing
 
@@ -123,6 +133,8 @@ Wait before using FogHTTP when:
 
 - you need transparent streaming decompression
 - you need SOCKS, PAC, WPAD, or platform proxy discovery
+- you require proxy routing and application-layer SSRF protection on the same
+  client; enforce destination policy at the proxy or network egress boundary
 - you rely on cookies across requests
 - you need per-request connect timeout reconfiguration
 - you need automatic compression negotiation instead of manual
@@ -132,12 +144,15 @@ Wait before using FogHTTP when:
 
 ## Error Surface
 
-Network and protocol failures map to `RequestError`. Pool acquire timeout and
+Pre-header transport failures map to `NetworkError`, a `RequestError` subtype;
+local request-provider and other request failures remain `RequestError`. Pool acquire timeout and
 queue-full conditions map to `PoolTimeout`. Response body progress timeout maps
 to `ReadTimeout` for buffered responses and streamed body chunks. Buffered and
 streamed request body write progress timeout maps to `WriteTimeout`. The broader
 buffered transport deadline maps to the base `TimeoutError` with phase-aware
 diagnostics; for streaming responses it covers acquire, redirects, and response
-headers before the stream is returned. Dedicated connect timeout exception mapping is
-reserved for later timeout work. See
+headers before the stream is returned. An enabled SSRF policy raises
+`SSRFError` with a stable `SSRFViolationReason` before a blocked destination is
+sent. Dedicated connect timeout exception mapping is reserved for later timeout
+work. See
 [Timeout model](./timeouts.md) for the current behavior.

{foghttp-0.3.7 → foghttp-0.3.8}/docs/policy-hooks.md

@@ -47,13 +47,14 @@ or replace transport state.
 
 | Hook | Ordering and scope |
 |---|---|
-| `before_send` | Runs for the initial request and every redirect hop after Rust has selected and validated the transport route, but before request-slot acquire. |
-| `on_response_headers` | Runs for every response after Rust has classified any redirect action and before FogHTTP consumes or returns the response body. |
+| `before_send` | Runs for the initial request, every retry attempt, and every redirect hop after Rust has selected and validated the transport route, but before request-slot acquire. |
+| `on_response_headers` | Runs for every response attempt after Rust has classified any redirect action and before FogHTTP consumes or returns the response body. |
 | `after_response_body` | Runs only for redirect response bodies consumed internally by FogHTTP. Rust first validates the redirect limit, replayability, scheme downgrade, header policy, and proxy boundary; the hook runs before the already validated mutation is applied. It does not run for the final body returned to the caller. |
 
-There is deliberately no error, timeout, or cancellation hook. Those stages
-remain unavailable until FogHTTP has a Rust-owned failure taxonomy and a real
-retry-policy consumer.
+There is deliberately no public error, timeout, cancellation, or retry-decision
+hook. The built-in retry policy uses a Rust-owned pre-header network-error
+classification and exposes decisions through typed telemetry instead of
+calling Python policy code from failure paths.
 
 ## Snapshot Contract
 

{foghttp-0.3.7 → foghttp-0.3.8}/docs/proxies.md

@@ -7,8 +7,9 @@ For `https://` targets, FogHTTP opens a `CONNECT` tunnel to the proxy and then
 performs the TLS handshake against the **target** host over that tunnel, so the
 certificate is validated for the target origin, not the proxy. If the tunnel
 cannot be established — proxy authentication failure, a non-2xx `CONNECT`
-status, or the proxy closing the tunnel early — FogHTTP raises `RequestError`
-instead of silently falling back to a direct connection.
+status, or the proxy closing the tunnel early — FogHTTP raises `NetworkError`
+(a `RequestError` subtype) instead of silently falling back to a direct
+connection.
 
 ## Explicit Proxy
 
@@ -61,7 +62,7 @@ Host: api.internal:443
 TLS is validated against the **target** host using the same `TLSConfig` rules as
 a direct connection; the proxy never terminates TLS and cannot impersonate the
 target. A failed tunnel (`CONNECT` non-2xx, proxy auth failure, or early close)
-maps to a stable `RequestError`, releases the request slot, and does not return
+maps to a stable `NetworkError`, releases the request slot, and does not return
 a poisoned connection to the pool. The tunnelled request itself is sent in
 origin-form, exactly like a direct HTTPS request.
 
@@ -193,10 +194,18 @@ FogHTTP intentionally does not expose a `verify=False` compatibility mode and
 does not honor environment variables that disable certificate verification.
 Use explicit `TLSConfig` for custom CA bundles and custom-only trust.
 
+## SSRF Policy Compatibility
+
+Requests that select a proxy route fail closed when `SSRFPolicy` is enabled.
+Forward and `CONNECT` proxies can resolve the target hostname remotely, so the
+client cannot guarantee that its locally checked DNS result is the address
+used by the proxy. See [SSRF protection](./ssrf.md) for the trust boundary and
+recommended network-layer controls.
+
 ## Not Implemented Yet
 
 - SOCKS5/SOCKS5h
 - TLS-to-proxy endpoints (`https://proxy.example:443`)
 - PAC/WPAD or platform/browser proxy discovery
 - per-route proxy policies
-- proxy retry policy
+- proxy failover, rotation, or per-route policy

{foghttp-0.3.7 → foghttp-0.3.8}/docs/pyo3-boundary.md

@@ -73,9 +73,11 @@ seam does not mutate response status, headers, or body content.
 Policy diagnostics may include a normalized origin, but must not include URL
 userinfo, path, query parameters, or fragments.
 
-Error and timeout policy stages are intentionally absent until the retry work
-defines a Rust-owned failure taxonomy. Core policy code must not accept or
-return `PyErr` merely to reserve a future hook.
+The built-in retry stage owns a narrow Rust failure taxonomy: eligible network
+failures occur before response headers and exclude timeout, connection-acquire,
+and user request-body provider errors. Retry decisions remain typed core values;
+core policy code does not accept or return `PyErr`. The PyO3 adapter maps final
+errors and carries structured retry decisions to optional Python telemetry.
 
 The PyO3 bridge lives outside `src/core/policy/`. It invokes only callbacks
 resolved when `RawClient` is created, rejects non-`None` callback returns, and

{foghttp-0.3.7 → foghttp-0.3.8}/docs/request-builder.md

@@ -64,9 +64,10 @@ sniff the body or invent a media type. `Accept-Query` response headers are
 available through the normal case-insensitive `response.headers` interface;
 FogHTTP does not yet parse that Structured Field value.
 
-RFC 10008 classifies QUERY as safe and idempotent. FogHTTP records the method
-name in request metadata and telemetry, but does not currently provide an
-automatic retry policy or an HTTP cache. RFC 10008 permits QUERY responses to
+RFC 10008 classifies QUERY as safe and idempotent. FogHTTP therefore includes
+it in the default method set of the opt-in [retry policy](./retries.md), but a
+body-bearing QUERY is eligible only when its provider is replayable. FogHTTP
+does not currently provide an HTTP cache. RFC 10008 permits QUERY responses to
 be cached, but a QUERY cache key must incorporate the request content and
 related metadata, including `Content-Type`; a URL-only GET-style cache key is
 not valid for QUERY.

foghttp-0.3.8/docs/retries.md

@@ -0,0 +1,224 @@
+# Retry Policy
+
+FogHTTP provides an opt-in, client-level retry policy for transient response
+statuses and network failures before response headers arrive. The default
+client does not enable this policy.
+
+```python
+import foghttp
+
+
+retry = foghttp.RetryPolicy(
+    retries=2,
+    backoff=0.1,
+    jitter=0.1,
+)
+
+with foghttp.Client(retry=retry) as client:
+    response = client.get("https://api.example.com/items")
+```
+
+`retries` is the number of additional sends allowed by retry decisions across
+one logical request. With no redirects, a policy with `retries=2` can therefore
+make at most three attempts; redirect hops are bounded separately by
+`max_redirects`. The same policy contract is available on `Client` and
+`AsyncClient`, including buffered and streaming response entry points. For a
+streaming response, retries finish before the response object is exposed;
+failures while the caller consumes the returned response body are not retried.
+
+## Defaults
+
+`RetryPolicy()` uses these defaults:
+
+| Option | Default | Meaning |
+|---|---:|---|
+| `retries` | `2` | Additional attempts after the initial send. |
+| `backoff` | `0.1` | Base exponential delay in seconds. |
+| `jitter` | `0.1` | Maximum random delay added to each backoff, in seconds. |
+| `retry_on.statuses` | `429`, `502`, `503`, `504` | Response statuses eligible for retry. |
+| `retry_on.exceptions` | `NetworkError` | Pre-header transport failure eligible for retry. |
+| `methods` | `GET`, `HEAD`, `OPTIONS`, `QUERY`, `TRACE` | Methods eligible for automatic retry. |
+
+The delay before retry number `n`, starting at zero, is
+`backoff * 2**n + uniform(0, jitter)`. A valid `Retry-After` delta or HTTP date
+on a retryable response is honored as a minimum delay. Backoff and response
+draining remain inside the request's shared `Timeouts.total` budget, including
+any redirect hops in the same logical request. Malformed `Retry-After` values
+are ignored, and accepted server delays are capped by the same duration ceiling
+as local numeric options.
+
+`RetryConditions` makes triggers explicit:
+
+```python
+conditions = foghttp.RetryConditions(
+    statuses=(429, 503),
+    exceptions=(foghttp.NetworkError,),
+)
+
+retry = foghttp.RetryPolicy(
+    retries=3,
+    backoff=0.2,
+    jitter=0.05,
+    retry_on=conditions,
+)
+```
+
+Use an empty tuple to disable a trigger category. The current exception
+contract supports `NetworkError` only; local upload-provider failures and
+FogHTTP timeout exceptions are not classified as retryable network failures.
+Response-body failures after headers are also not retried.
+
+## Method And Body Safety
+
+`POST` is deliberately absent from the default method set. This prevents an
+automatic retry from duplicating a side effect. Applications can explicitly
+replace `methods`, but they then own the endpoint's idempotency guarantee:
+
+```python
+retry = foghttp.RetryPolicy(methods=("GET", "PUT", "POST"))
+```
+
+Method eligibility is necessary but not sufficient. A non-empty request body
+must also be replayable:
+
+| Body source | Replayable |
+|---|---|
+| `bytes`, `str`, `json=`, encoded `data=` | Yes |
+| bytes-like multipart parts | Yes |
+| zero-argument stream or multipart factory | Yes, if it returns equivalent fresh content |
+| direct iterator, async iterator, or file-like `content=` | No |
+| direct file or stream multipart part | No |
+
+RFC 10008 classifies `QUERY` as safe and idempotent, so it is enabled by
+default. A body-bearing QUERY is still retried only when its provider is
+replayable. If a matching response or network failure occurs with a
+non-replayable body, FogHTTP returns the response or raises the original error
+without a second send and records `block_non_replayable` with reason
+`non_replayable_body`.
+
+There is no public `body_replayable=True` escape hatch. Use a zero-argument
+factory when a stream can be recreated safely for every attempt.
+
+## Ordering And Resources
+
+Retry runs inside the Rust transport policy pipeline. Redirect classification
+has priority for a response that is both a redirect and listed in retry
+statuses. Each new retry attempt reruns route selection and lightweight
+`before_send`/`on_response_headers` policy hooks.
+
+Before retrying a status response, FogHTTP drains its body under the configured
+read and total deadlines. A clean keep-alive connection can then return to the
+pool. A connection that fails before headers is not reused. The request slot is
+released before backoff, so sleeping retries do not occupy active transport
+capacity. Cancelling an async request cancels its pending backoff and releases
+the logical request lifecycle.
+
+## Observability
+
+A request made by a client with `RetryPolicy` exposes one immutable,
+request-scoped `RetryTrace` when transport execution returns a buffered or
+streaming response, or raises a terminal `FogHTTPError`. Responses provide it
+as `response.retry_trace`; terminal `FogHTTPError` instances provide the same
+property. Errors raised before native transport execution are outside this
+contract. A client without a retry policy returns `None`, so the default path
+does not collect attempt history or allocate terminal trace values.
+
+```python
+try:
+    response = client.get("https://api.example.com/items")
+except foghttp.FogHTTPError as error:
+    trace = error.retry_trace
+else:
+    trace = response.retry_trace
+
+if trace is not None:
+    for attempt in trace.attempts:
+        print(attempt.attempt, attempt.decision, attempt.reason)
+```
+
+`RetryTrace` contains:
+
+| Field | Meaning |
+|---|---|
+| `attempts` | Ordered immutable tuple, bounded to at most `retries + 1` entries. |
+| `outcome` | `response` when the transport returned a response object, or `error` when it raised. |
+| `status_code` | Final response status, otherwise `None`. |
+| `error_type` | Diagnostic name of the final public exception class, otherwise `None`. |
+| `elapsed` | Total logical-request time in seconds through the returned response or error. |
+
+Each `RetryAttempt` represents one retry-policy execution cycle inside the
+native transport, not one socket send or server-observed request. Redirect hops
+remain within the same retry attempt and rerun route selection, the
+`before_send` hook and request-slot/connection acquisition. An attempt can
+therefore end with a policy or acquire error before a connection sends any
+request bytes.
+
+An attempt contains the 1-based `attempt`, normalized `method`, credential-free
+`origin`, zero-based `redirect_hop`, optional `status_code` and `error_type`,
+typed `decision` and `reason`, selected `backoff` in seconds, optional cumulative
+`decision_elapsed` seconds when the retry decision was committed by the
+transport, and cumulative `completed_elapsed` seconds when that execution
+attempt ended. All elapsed values are measured from the start of the logical
+request, not from the start of an individual attempt. A buffered attempt can
+contain both a status and a later body-read error. The final retry execution
+attempt is always present. Its `decision` and `reason` are `None` when that
+attempt did not trigger retry policy; a terminal method stop, replayability
+block or exhaustion retains its typed decision and reason.
+
+`error_type` follows the corresponding public exception class name and is a
+diagnostic field rather than a separate error-category enum. When class-name
+comparison is needed, prefer `foghttp.NetworkError.__name__` over a repeated
+string literal. `backoff` is the delay selected by policy, not a measurement of
+time actually slept; a timeout or cancellation can end the wait early.
+
+A logical request can fail after its latest transport attempt has completed.
+For example, a total timeout during retry backoff is reported by
+`RetryTrace.error_type` and `RetryTrace.elapsed`; it does not overwrite the
+completed status or network result of the preceding attempt.
+
+`RetryTraceOutcome.RESPONSE` means that request execution produced a response;
+it does not classify an HTTP status as successful. For streaming responses the
+trace is complete when response headers are exposed, because body-consumption
+failures are outside the retry scope and do not mutate the immutable trace.
+`HTTPStatusError` preserves the trace of its response.
+
+FogHTTP preserves the original terminal request error if CPython cannot
+allocate or attach the native trace handoff object. That exceptional attachment
+failure is reported through `sys.unraisablehook`; the error then has no trace
+rather than being replaced by an observability error.
+
+Trace values never include a request path, query, headers, body, credentials or
+userinfo. They retain only the normalized origin and typed operational fields,
+so their default representation is safe for diagnostics.
+
+When telemetry is enabled and the native request returns or raises, each retry
+decision emits a typed `TelemetryEventType.RETRY_DECISION` event with:
+
+- `retry_attempt`, starting at `1` for the failed initial attempt;
+- `status_code` or `error_type`;
+- `retry_decision`: `retry`, `stop`, or `block_non_replayable`;
+- `retry_reason`: `status`, `network_error`, `method_not_allowed`,
+  `non_replayable_body`, or `retries_exhausted`;
+- `retry_backoff_ns` and `elapsed_ns`;
+- normalized method and origin, without request path, query, headers, or body.
+
+The public trace and telemetry events are derived from the same native attempt
+records; terminal attempts without a retry decision do not emit a
+`retry_decision` event. The final `request_finished` event still reports the
+logical request outcome. Native records are delivered when the transport
+returns or raises, not as live callbacks during backoff.
+`RetryAttempt.decision` and `RetryAttempt.reason` intentionally reuse
+`TelemetryRetryDecision` and `TelemetryRetryReason` as the shared public retry
+vocabulary; telemetry is a projection of the same decision records rather than
+a separate enum contract.
+For a `retry_decision` event, `elapsed_ns` is derived from
+`RetryAttempt.decision_elapsed`, and `status_code`/`error_type` describe the
+trigger seen when that decision was committed. A later buffered-body error can
+therefore appear on the state-oriented `RetryAttempt` without rewriting the
+earlier decision event.
+
+Cancelling an async caller can abort the native task before a response or
+exception is returned. `asyncio.CancelledError` therefore does not manufacture
+a partial `retry_trace`, and buffered retry decisions, including the decision
+that selected a cancelled backoff, are not emitted to the Python sink. There is
+no global retry-trace history.