foghttp 0.3.6__tar.gz → 0.3.7__tar.gz

{foghttp-0.3.6 → foghttp-0.3.7}/.flake8

@@ -29,10 +29,11 @@ exclude =
 per-file-ignores =
     # FogHTTP uses public __init__.py modules as explicit import/__all__ API vitrines.
     **/__init__.py: WPS412
-    # Public/API orchestration modules naturally collect more dependencies and ergonomic kwargs.
-    foghttp/__init__.py: WPS201, WPS412
+    # Root package is an explicit API vitrine; import count follows the stable public surface.
+    foghttp/__init__.py: WPS201, WPS203, WPS412
+    # Public client orchestration modules naturally collect ergonomic kwargs.
     foghttp/client.py: WPS201, WPS211, WPS214, WPS501
-    foghttp/async_client.py: WPS201, WPS211, WPS214
+    foghttp/async_client.py: WPS201, WPS203, WPS211, WPS214
     # ClientCore maps Rust snapshots to TypedDict literal keys and owns the unclosed-client warning.
     foghttp/_client/core.py: WPS201, WPS211, WPS214, WPS226, WPS603
     # Public domain objects intentionally expose mapping/response/url-style APIs.

{foghttp-0.3.6 → foghttp-0.3.7}/.github/workflows/ci.yml

@@ -152,8 +152,8 @@ jobs:
           enable-cache: true
           cache-dependency-glob: uv.lock
 
-      - name: Install editable package
-        run: uv run --extra dev --with "maturin>=1.7,<2" maturin develop --locked
+      - name: Build extension in place
+        run: uv run --extra dev --with "maturin>=1.7,<2" maturin develop --locked --skip-install
 
       - name: Run tests
         if: matrix.python-version != '3.14'

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

@@ -110,7 +110,7 @@ dependencies = [
 
 [[package]]
 name = "foghttp"
-version = "0.3.6"
+version = "0.3.7"
 dependencies = [
  "brotli",
  "bytes",

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

@@ -1,6 +1,6 @@
 [package]
 name = "foghttp"
-version = "0.3.6"
+version = "0.3.7"
 description = "Observable Rust-powered HTTP client for Python services."
 edition = "2021"
 homepage = "https://github.com/AmberFog/foghttp"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: foghttp
-Version: 0.3.6
+Version: 0.3.7
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: AsyncIO
 Classifier: License :: OSI Approved :: MIT License
@@ -92,9 +92,9 @@ Runtime requirements:
 - `orjson>=3.11,<4`
 
 Published CPython wheels use the stable `cp311-abi3` ABI: each supported
-OS/architecture pair has one wheel for Python 3.11 and newer. The release
-pipeline currently installs and exercises those wheels on GIL-enabled CPython
-3.11 through 3.14. See [Packaging and Python compatibility](https://github.com/AmberFog/foghttp/blob/main/docs/packaging.md)
+OS/architecture pair has one wheel for the currently validated GIL-enabled
+CPython 3.11 through 3.14 range. Newer Python versions are not part of the
+compatibility claim until they pass the same release checks. See [Packaging and Python compatibility](https://github.com/AmberFog/foghttp/blob/main/docs/packaging.md)
 for the complete wheel matrix and validation policy.
 
 ## Quick Start
@@ -149,12 +149,14 @@ async with foghttp.AsyncClient() as client:
 - sync and async bytes/text/line response streaming with explicit
   context-managed lifecycle
 - prepared `Request` objects with `build_request()` and `send()`
+- immutable request `extensions` for policy/application metadata outside the HTTP message
 - case-insensitive `Headers` with repeated values
 - safe policy for transport-managed request headers
 - redacted repr/error surfaces for sensitive headers, URL credentials,
   token-like URL params, and buffered body bytes
 - normalized `URL` model with origin comparison and relative joins
-- GET/HEAD/POST/QUERY redirects with final URL, history, and conservative replay policy
+- GET/HEAD/POST/QUERY redirects with final URL, history, typed same-origin and
+  cross-origin header policy, and no cross-origin body replay
 - HTTP proxy routing and HTTPS proxy `CONNECT` tunnelling through explicit
   `proxy=` or `trust_env=True` when the proxy endpoint uses `http://`
 - HTTPS with default WebPKI roots, explicit custom CA certificates, and
@@ -166,6 +168,8 @@ async with foghttp.AsyncClient() as client:
   acquire pressure and idle lifecycle diagnostics
 - opt-in typed telemetry event hooks for request, redirect, response headers,
   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
 - 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
@@ -184,6 +188,7 @@ async with foghttp.AsyncClient() as client:
 - [Packaging and Python compatibility](https://github.com/AmberFog/foghttp/blob/main/docs/packaging.md)
 - [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)
 - [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)
@@ -217,7 +222,7 @@ path. Disabling TLS verification is intentionally not supported.
 Development requires a Rust toolchain with `cargo` available in `PATH`.
 
 ```bash
-uv run --extra dev --with "maturin>=1.7,<2" maturin develop
+uv run --extra dev --with "maturin>=1.7,<2" maturin develop --locked --skip-install
 uv run --extra dev coverage run -m pytest
 uv run --extra dev coverage report -m
 uv run --extra dev pre-commit run --all-files --show-diff-on-failure

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

@@ -49,9 +49,9 @@ Runtime requirements:
 - `orjson>=3.11,<4`
 
 Published CPython wheels use the stable `cp311-abi3` ABI: each supported
-OS/architecture pair has one wheel for Python 3.11 and newer. The release
-pipeline currently installs and exercises those wheels on GIL-enabled CPython
-3.11 through 3.14. See [Packaging and Python compatibility](https://github.com/AmberFog/foghttp/blob/main/docs/packaging.md)
+OS/architecture pair has one wheel for the currently validated GIL-enabled
+CPython 3.11 through 3.14 range. Newer Python versions are not part of the
+compatibility claim until they pass the same release checks. See [Packaging and Python compatibility](https://github.com/AmberFog/foghttp/blob/main/docs/packaging.md)
 for the complete wheel matrix and validation policy.
 
 ## Quick Start
@@ -106,12 +106,14 @@ async with foghttp.AsyncClient() as client:
 - sync and async bytes/text/line response streaming with explicit
   context-managed lifecycle
 - prepared `Request` objects with `build_request()` and `send()`
+- immutable request `extensions` for policy/application metadata outside the HTTP message
 - case-insensitive `Headers` with repeated values
 - safe policy for transport-managed request headers
 - redacted repr/error surfaces for sensitive headers, URL credentials,
   token-like URL params, and buffered body bytes
 - normalized `URL` model with origin comparison and relative joins
-- GET/HEAD/POST/QUERY redirects with final URL, history, and conservative replay policy
+- GET/HEAD/POST/QUERY redirects with final URL, history, typed same-origin and
+  cross-origin header policy, and no cross-origin body replay
 - HTTP proxy routing and HTTPS proxy `CONNECT` tunnelling through explicit
   `proxy=` or `trust_env=True` when the proxy endpoint uses `http://`
 - HTTPS with default WebPKI roots, explicit custom CA certificates, and
@@ -123,6 +125,8 @@ async with foghttp.AsyncClient() as client:
   acquire pressure and idle lifecycle diagnostics
 - opt-in typed telemetry event hooks for request, redirect, response headers,
   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
 - 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
@@ -141,6 +145,7 @@ async with foghttp.AsyncClient() as client:
 - [Packaging and Python compatibility](https://github.com/AmberFog/foghttp/blob/main/docs/packaging.md)
 - [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)
 - [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)
@@ -174,7 +179,7 @@ path. Disabling TLS verification is intentionally not supported.
 Development requires a Rust toolchain with `cargo` available in `PATH`.
 
 ```bash
-uv run --extra dev --with "maturin>=1.7,<2" maturin develop
+uv run --extra dev --with "maturin>=1.7,<2" maturin develop --locked --skip-install
 uv run --extra dev coverage run -m pytest
 uv run --extra dev coverage report -m
 uv run --extra dev pre-commit run --all-files --show-diff-on-failure

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

@@ -60,6 +60,8 @@ FogHTTP is designed around a few engineering priorities:
   pressure, idle lifecycle snapshots, and stuck request diagnostics
 - opt-in typed telemetry event hooks with redacted request/response lifecycle
   events
+- opt-in typed transport policy hooks for lightweight request admission and
+  response-head checks, with Rust-owned redirect safety
 - versioned telemetry snapshots that separate alert-oriented stats from
   diagnostic dump APIs
 - opt-in async lifecycle debug snapshots for tests, staging, and incident
@@ -76,6 +78,7 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
 - [Packaging and Python compatibility](./packaging.md)
 - [Timeout model](./timeouts.md)
 - [Upload typing contracts](./upload-types.md)
+- [Transport policy hooks](./policy-hooks.md)
 - [Telemetry contract](./telemetry.md)
 - [Response streaming](./streaming.md)
 - [TLS trust](./tls.md)
@@ -110,6 +113,7 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
 - sync and async bytes/text/line response streaming with context-managed cleanup
 - response status flags for success, redirects, and client/server errors
 - prepared `Request` objects with `build_request()` and `send()`
+- immutable request `extensions` for policy/application metadata outside the HTTP message
 - public upload typing contracts for streaming request bodies and multipart
   `files=` providers
 - case-insensitive `Headers` with repeated value support
@@ -117,7 +121,8 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
 - redacted repr/error surfaces for sensitive headers, URL credentials,
   token-like URL params, and buffered body bytes
 - normalized `URL` model with origin comparison and relative joins
-- GET/HEAD/POST/QUERY redirects with final URL, history, and conservative replay policy
+- GET/HEAD/POST/QUERY redirects with final URL, history, typed same-origin and
+  cross-origin header policy, and no cross-origin body replay
 - HTTPS with default WebPKI roots, explicit custom CA certificates, and
   custom-only CA trust
 - documented lazy transport creation, graceful sync close, async request
@@ -129,6 +134,8 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
   acquire and idle lifecycle telemetry
 - opt-in typed telemetry event hooks for request, redirect, response headers,
   response body, and request completion lifecycle
+- opt-in typed transport policy hooks with immutable request/response views and
+  no default-path Python callback
 - 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.6 → foghttp-0.3.7}/docs/limitations.md

@@ -34,6 +34,7 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
   `response.raise_for_status()`
 - lightweight `response.request`
 - prepared `Request` objects with `build_request()` and `send()`
+- immutable request `extensions` propagated to policy hooks and `response.request`
 - case-insensitive `Headers` with repeated values
 - response header bytes exposed as Latin-1 strings, including obs-text values
 - normalized `URL` with origin comparison and relative joins
@@ -52,6 +53,8 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
   connection-acquire pressure and idle lifecycle diagnostics
 - opt-in typed telemetry event hooks for request, redirect, response headers,
   response body, and request completion lifecycle
+- opt-in synchronous transport policy hooks with immutable request/response
+  snapshots and Rust-owned redirect safety
 - 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
@@ -95,6 +98,7 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
 | separate read/write timeout semantics | `Timeouts.read` is implemented as a buffered and streamed response body progress timeout; `Timeouts.write` is implemented for buffered request body write progress and streaming upload chunk/write progress |
 | 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 |
 | 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

{foghttp-0.3.6 → foghttp-0.3.7}/docs/packaging.md

@@ -2,9 +2,11 @@
 
 FogHTTP ships a Rust extension built with PyO3. Published CPython wheels target
 the stable `cp311-abi3` ABI, matching the package minimum of Python 3.11. One
-wheel per supported operating-system and architecture pair can therefore be
-installed by GIL-enabled CPython 3.11 and newer instead of building a separate
-wheel for every CPython minor version.
+wheel per supported operating-system and architecture pair covers the
+currently validated GIL-enabled CPython 3.11-3.14 range instead of requiring a
+separate wheel for every supported CPython minor version. The ABI may remain
+compatible with newer Python versions, but FogHTTP does not claim that support
+until the full suite and exact wheel pass the release validation matrix.
 
 ## Release Matrix
 

foghttp-0.3.7/docs/policy-hooks.md

@@ -0,0 +1,109 @@
+# Transport Policy Hooks
+
+FogHTTP exposes a small opt-in Python edge around its Rust-owned transport
+policy stages. It is intended for trusted, lightweight request admission and
+response-head policy checks. It is not a middleware framework and does not
+expose the internal transport adapter.
+
+The default is `policy_hooks=None`. In that mode the Rust bridge does not
+resolve callback or view objects, allocate hook snapshots, call Python, or
+build a runtime list of policies. Built-in proxy and redirect policies remain
+statically dispatched in Rust.
+
+## Configuration
+
+Hooks are configured per client and have the same contract for `Client` and
+`AsyncClient`, including buffered and streaming requests:
+
+```python
+import foghttp
+
+
+def allow_service_origins(request: foghttp.TransportPolicyRequest) -> None:
+    if foghttp.URL(request.url).origin != "https://api.example.com":
+        raise PermissionError("transport target is outside the service boundary")
+
+
+def reject_server_errors(response: foghttp.TransportPolicyResponse) -> None:
+    if response.status_code >= 500:
+        raise RuntimeError("upstream response rejected by transport policy")
+
+
+hooks = foghttp.TransportPolicyHooks(
+    before_send=allow_service_origins,
+    on_response_headers=reject_server_errors,
+)
+
+with foghttp.Client(policy_hooks=hooks) as client:
+    response = client.get("https://api.example.com/resource")
+```
+
+All callbacks are synchronous and must return `None`. Raising an exception
+rejects the current request and preserves that exception for the caller.
+Returning any other value raises `TypeError`; hook return values cannot mutate
+or replace transport state.
+
+## Stage Order
+
+| 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. |
+| `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.
+
+## Snapshot Contract
+
+`TransportPolicyRequest` is an immutable snapshot with:
+
+- normalized uppercase `method`;
+- full normalized `url`;
+- `body` as `"empty"`, `"replayable"`, or `"non_replayable"`;
+- zero-based `redirect_hop`;
+- immutable request-scoped `extensions` supplied by the caller.
+
+`TransportPolicyResponse` contains the request snapshot, `status_code`, and an
+immutable tuple of response header pairs. Repeated values for the same header
+retain their order.
+
+The full URL and header values are available because trusted policy code may
+need them to make a decision. They can contain credentials or tokens and are
+not telemetry-safe data. Their `repr()` surfaces redact URL secrets and omit
+header values plus extension keys and values, but hook code must still avoid
+logging the raw attributes. Extensions are metadata only and are never
+serialized into HTTP headers, the URL, or the request body. Use
+[`TelemetryConfig`](./telemetry.md) when the goal is observability through
+redacted events rather than request admission.
+
+Snapshots contain no socket, permit, response body, cancellation handle, pool,
+or runtime reference. Their transport fields are copies: replacing those fields
+through Python escape hatches cannot alter the request or bypass Rust redirect
+and replayability checks. The extensions mapping is immutable, but its values
+are the caller-owned shallow references described in the request builder
+contract.
+
+## Execution And Lifecycle
+
+Hooks run inline with transport policy evaluation. They may execute on FogHTTP
+transport worker threads and may be invoked concurrently by concurrent
+requests. A hook must therefore be fast, thread-safe, and independent of an
+asyncio event loop, thread-local state, or `contextvars` propagation.
+Extension values are shared shallow references, so hooks must treat them as
+read-only and safe for concurrent observation.
+
+Do not perform blocking I/O, call back into FogHTTP, or re-enter the same client
+from a hook. Hook execution advances the wall clock used by later total-time
+checks, but a running Python callback is not preempted or independently bounded
+by FogHTTP timeouts. Callback failure unwinds through the normal request path
+so permits, response bodies, connections, upload providers, and request metrics
+retain their existing owners and cleanup behavior.
+
+## Stability Boundary
+
+`TransportPolicyHooks` and its immutable views are the deliberate public
+surface. `src/core/policy/`, PyO3 bridge classes, raw clients, connector types,
+and internal transport adapter Protocols remain implementation details and are
+not extension points.

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

@@ -44,6 +44,46 @@ buffered requests:
 - If a Rust stream state lock owns an active Python future handle, the lock must
   be released before scheduling cancellation or completion on the Python loop.
 
+## Internal Request/Response Policy Seam
+
+`src/core/policy/` is an internal, unstable seam for built-in transport
+policies. It is not a public middleware API. The optional
+`TransportPolicyHooks` bridge observes typed copies at selected stage edges;
+it does not expose the core pipeline or transport adapter. The default request
+path performs no Python callback, dynamic dispatch, policy-list allocation, or
+hook-snapshot construction.
+
+Policy stages run in this order:
+
+1. Before send, the pipeline selects the direct or proxy transport for the
+   normalized request URL.
+2. After response headers, it may produce an opaque pending redirect decision.
+3. After the redirect response body has been consumed, it validates the
+   redirect limit, request-body replayability, and environment-derived proxy
+   boundary before returning a typed request mutation.
+4. `RequestState` applies the mutation before the next send. The policy layer
+   never owns sockets, permits, response bodies, or Python objects.
+
+The current mutation surface can replace the method and URL, remove request
+headers, and either preserve or drop the request body. A non-replayable body is
+never resent. Environment-derived proxy decisions are not reused across
+origins and therefore fail closed until per-hop environment resolution exists.
+Responses are observed through immutable status and header views; the current
+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 PyO3 bridge lives outside `src/core/policy/`. It invokes only callbacks
+resolved when `RawClient` is created, rejects non-`None` callback returns, and
+passes immutable Python snapshots without transport resources. Built-in
+validation runs before a Python hook can veto a redirect mutation. See
+[Transport policy hooks](./policy-hooks.md) for the public execution and
+threading contract.
+
 ## Review Checklist
 
 For PRs touching PyO3, runtime, cancellation, close/aclose, streaming, or

{foghttp-0.3.6 → foghttp-0.3.7}/docs/quickstart.md

@@ -5,7 +5,7 @@
 Development requires a Rust toolchain with `cargo` available in `PATH`.
 
 ```bash
-uv run --extra dev --with "maturin>=1.7,<2" maturin develop
+uv run --extra dev --with "maturin>=1.7,<2" maturin develop --locked --skip-install
 ```
 
 Runtime requirements:
@@ -713,6 +713,28 @@ monotonic `snapshot_sequence` within one Rust transport lifetime. Use
 `TransportStats` for dashboards and alert-oriented metrics; see
 [Telemetry contract](./telemetry.md) for the current guarantees.
 
+For trusted lightweight admission checks, configure synchronous transport
+policy hooks. The hook receives the full normalized target, may reject by
+raising, and cannot mutate transport state:
+
+```python
+def require_https(request: foghttp.TransportPolicyRequest) -> None:
+    if foghttp.URL(request.url).scheme != "https":
+        raise PermissionError("HTTPS is required")
+
+
+hooks = foghttp.TransportPolicyHooks(before_send=require_https)
+
+with foghttp.Client(policy_hooks=hooks) as client:
+    response = client.get("https://httpbin.org/get")
+```
+
+Hooks run inline and can execute on transport worker threads, so they must be
+fast, synchronous, thread-safe, and non-reentrant. Their snapshots are not
+telemetry-safe: full URLs and response header values may contain secrets. See
+[Transport policy hooks](./policy-hooks.md) for stage ordering, redirect-body
+scope, error propagation, and lifecycle constraints.
+
 For opt-in event hooks, pass a typed telemetry config. Hooks receive redacted
 `TelemetryEvent` objects and are intended for logging/tracing bridges, not for
 mutating requests or responses. Hooks run inline, so keep sinks fast and

{foghttp-0.3.6 → foghttp-0.3.7}/docs/redirects.md

@@ -129,41 +129,37 @@ query at a different origin.
 ## Security Policy
 
 FogHTTP applies a conservative redirect security policy on every redirect hop.
-
-For same-origin redirects, request headers are preserved unless the redirect
-changes the request method and drops the body.
-
-For cross-origin redirects, FogHTTP strips sensitive headers before sending the
-next request:
-
-- `Authorization`
-- `Proxy-Authorization`
-- `Cookie`
-- `Origin`
-- `Referer`
-
-This is intentionally strict. It prevents credentials, manually supplied
-cookies, origin metadata, and referrer metadata from being forwarded to a
-different origin by a redirect response. `Host` is transport-managed and cannot
-be set manually through the safe API.
-
-When a redirect rewrites `POST` or `QUERY` to `GET`, FogHTTP drops the request
-body and strips body-specific headers:
-
-- `Content-Encoding`
-- `Content-Length`
-- `Content-Type`
-- `Transfer-Encoding`
-
-`Content-Length` and `Transfer-Encoding` are transport-managed and cannot be set
-manually through the safe API.
-
-For same-origin method-preserving POST and QUERY redirects, FogHTTP resends a
-replayable body. For cross-origin method-preserving POST and QUERY redirects,
-FogHTTP preserves the method but drops the body and body-specific headers
-before the next request. This prevents JSON payloads, tokens, form data, and
-other request bodies from being forwarded to a different origin by a redirect
-response.
+The policy runs after the target URL and body action have been resolved and
+before the next request is sent.
+
+| Header category | Fields | Redirect behavior |
+|---|---|---|
+| Transport routing, framing, proxy, and connection | `Host`, `Content-Length`, `Transfer-Encoding`, `Connection`, `Keep-Alive`, `Proxy-Authorization`, `Proxy-Connection`, `TE`, `Trailer`, `Upgrade`, plus fields named by `Connection` | Always removed from the previous request. The transport derives fresh routing and framing fields for the new URL and body and applies proxy credentials for the selected route. |
+| Conditional validators | `If-Match`, `If-None-Match`, `If-Modified-Since`, `If-Unmodified-Since`, `If-Range` | Always removed because the validator describes the previous target resource. |
+| Origin-scoped credentials and metadata | `Authorization`, `Cookie`, `Origin`, `Referer` | Preserved for same-origin redirects and removed for cross-origin redirects. |
+| Content metadata | Every `Content-*` field, including `Content-Type`, `Content-Encoding`, `Content-Language`, `Content-Location`, `Content-Range`, `Content-Disposition`, and `Content-Digest`; also legacy `Digest`, current `Repr-Digest`, and `Last-Modified` | Preserved only while the request body is preserved. Removed when a method rewrite or cross-origin policy drops the body. |
+| Other caller headers | For example, `Accept` and application-specific fields | Preserved. |
+
+Same-origin means that the scheme, normalized host, and effective port all
+match. A change to any of those components is cross-origin.
+
+The safe API already rejects manual transport-managed fields. Rebuilding them
+inside the Rust redirect policy also protects the lower-level boundary and
+prevents stale authority, framing, proxy credentials, or connection state from
+crossing a hop.
+
+The conditional and content rules follow the redirect guidance in
+[RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html). FogHTTP recognizes both
+the obsolete `Digest` field and its current
+[RFC 9530](https://www.rfc-editor.org/rfc/rfc9530.html) replacements.
+
+For same-origin method-preserving redirects, FogHTTP resends a replayable body.
+For cross-origin method-preserving redirects, FogHTTP preserves the method but
+drops any body and its content metadata before the next request. This rule also
+protects bodies supplied through the generic `request()` API for methods whose
+convenience helpers do not accept body arguments. It prevents JSON payloads,
+tokens, form data, and other request bodies from being forwarded to a different
+origin by a redirect response.
 
 FogHTTP also blocks `https -> http` redirects. Scheme downgrade redirects are
 too easy to misuse once credentials, cookies, body replay, or future auth helpers
@@ -174,6 +170,12 @@ Direct streaming bodies use the explicit non-replayable path and are not resent
 automatically. Factory-backed streams are replayable because each attempt gets
 a fresh provider.
 
+Automatic redirects cannot infer whether an arbitrary application header such
+as `X-API-Key` contains an origin-scoped secret. Keep automatic redirects
+disabled and follow the response explicitly when custom credentials require a
+different forwarding policy. This is also the explicit escape hatch for callers
+that need behavior looser than the built-in matrix.
+
 ## Proxy Policy
 
 Redirects interact with proxy routing because a redirect target can change the
@@ -196,7 +198,8 @@ recomputation is planned separately.
 ## Redirect Limit
 
 `max_redirects` defaults to `20`. If the limit is exceeded, FogHTTP raises
-`RequestError`.
+`RequestError`. The diagnostic identifies the normalized origin but omits URL
+userinfo, path, query parameters, and fragments.
 
 ```python
 with foghttp.Client(follow_redirects=True, max_redirects=5) as client:

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

@@ -18,6 +18,7 @@ the current FogHTTP API. The same flow is available as a runnable example in
 | `params` | Supported | Accepts mappings, repeated pairs, and raw query strings. Existing URL query is preserved. |
 | client default `params` | Supported | Passed as `Client(params=...)` or `AsyncClient(params=...)`. Appended after URL query and before per-request params. |
 | `headers` | Supported | Accepts mappings, pairs, and `foghttp.Headers`. Lookups are case-insensitive and repeated values are preserved. |
+| `extensions` | Supported | Immutable request-scoped metadata for policy and application coordination. It is never serialized into the HTTP message. |
 | client default `headers` | Supported | Passed as `Client(headers=...)` or `AsyncClient(headers=...)`. Per-request headers override defaults case-insensitively. |
 | `json` | Supported | Encoded with `orjson`. Adds `content-type: application/json` unless explicitly set. |
 | `content` | Supported | Accepts buffered `bytes` or `str`, binary file-like objects, sync bytes-like iterables, zero-arg byte-stream factories, and async bytes-like iterables/factories on `AsyncClient`. Strings are encoded as UTF-8. No semantic content type is added. |
@@ -88,6 +89,54 @@ Per-request headers override client defaults case-insensitively. Repeated
 headers from defaults are preserved when the request does not override that
 header name.
 
+## Request Extensions
+
+Use `extensions=` for request-scoped application metadata that policy hooks,
+auth, retry, proxy, or tracing integrations may need without placing service
+state in HTTP headers. The name is deliberately `extensions`, not `context`:
+the value belongs to a prepared request and does not imply `contextvars`, event
+loop, or task-context propagation.
+
+```python
+import foghttp
+from foghttp.methods import GET
+
+
+with foghttp.Client() as client:
+    request = client.build_request(
+        GET,
+        "https://api.example.com/resource",
+        extensions={"example.request_id": "request-42"},
+    )
+    response = client.send(request)
+    assert response.request.extensions["example.request_id"] == "request-42"
+```
+
+`Request`, `build_request()`, `request()`, `stream()`, and every method shortcut
+accept `extensions=`. FogHTTP makes a shallow immutable copy represented by
+`RequestExtensions`; later changes to the source mapping do not change the
+prepared request. Values remain caller-owned references, so keep them small and
+treat mutable values as immutable while a request, response, or hook may retain
+them. Do not attach open files, sockets, clients, tasks, or other lifecycle-owned
+resources.
+
+Keys must be non-empty strings. Libraries should use a package or reverse-domain
+namespace rather than generic names. The case-insensitive `foghttp.*` namespace
+is reserved for present and future internal timeout, trace, proxy, retry, and
+other policy decisions; callers cannot set it. Reserved internal state is not a
+public configuration API.
+
+Extensions are available as `request.extensions`, on
+`TransportPolicyRequest.extensions`, and on `response.request.extensions`,
+including redirect history. They are not copied into the URL, headers, or body.
+Their keys and values are omitted from request, response, and policy snapshot
+`repr()` output, but application code must still avoid logging the raw mapping
+when it contains sensitive metadata.
+
+When `extensions` is omitted, requests share one empty immutable snapshot and
+the native boundary receives `None`; no per-request metadata mapping or Python
+policy callback is introduced.
+
 ## Sync Example
 
 ```python

{foghttp-0.3.6 → foghttp-0.3.7}/foghttp/__init__.py

@@ -24,6 +24,7 @@ __all__ = (
     "ReadTimeout",
     "Request",
     "RequestError",
+    "RequestExtensions",
     "RequestInfo",
     "Response",
     "ResponseBodyBudgetExceededError",
@@ -43,6 +44,10 @@ __all__ = (
     "TimeoutError",
     "TimeoutPhase",
     "Timeouts",
+    "TransportPolicyBodyState",
+    "TransportPolicyHooks",
+    "TransportPolicyRequest",
+    "TransportPolicyResponse",
     "TransportState",
     "TransportStats",
     "UnclosedClientError",
@@ -81,8 +86,15 @@ from .lifecycle_debug import (
     AsyncLifecycleDebugSnapshot,
 )
 from .limits import Limits
+from .policy import (
+    TransportPolicyBodyState,
+    TransportPolicyHooks,
+    TransportPolicyRequest,
+    TransportPolicyResponse,
+)
 from .pool_diagnostics import OriginPoolDiagnostics, PoolBlockingReason, PoolDiagnostics
 from .request import Request
+from .request_extensions import RequestExtensions
 from .request_info import RequestInfo
 from .response import Response
 from .stream_response import AsyncStreamResponse, StreamResponse