foghttp 0.3.4__tar.gz → 0.3.5__tar.gz

{foghttp-0.3.4 → foghttp-0.3.5}/.github/workflows/ci.yml

@@ -94,7 +94,7 @@ jobs:
         run: uv run --extra dev --with "maturin>=1.7,<2" maturin develop
 
       - name: Run tests with coverage
-        run: uv run --extra dev coverage run -m pytest
+        run: uv run --extra dev coverage run -m pytest -vv
 
       - name: Report coverage
         run: uv run --extra dev coverage report -m

{foghttp-0.3.4 → foghttp-0.3.5}/.pre-commit-config.yaml

@@ -28,7 +28,7 @@ repos:
       - id: add-trailing-comma
 
   - repo: https://github.com/crate-ci/typos
-    rev: v1.46.1
+    rev: v1.47.2
     hooks:
       - id: typos
 
@@ -38,12 +38,12 @@ repos:
       - id: detect-secrets
 
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.11.14
+    rev: 0.11.25
     hooks:
       - id: uv-lock
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.12
+    rev: v0.15.20
     hooks:
       - id: ruff-format
       - id: ruff-check
@@ -66,4 +66,4 @@ repos:
           - orjson>=3.11,<4
           - typing-extensions>=4.3.0,<5
         args: [--config-file=pyproject.toml, --install-types, --non-interactive]
-        files: ^foghttp/.*\.pyi?$
+        files: ^(foghttp|tests/types)/.*\.pyi?$

{foghttp-0.3.4 → foghttp-0.3.5}/Cargo.lock

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

{foghttp-0.3.4 → foghttp-0.3.5}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "foghttp"
-version = "0.3.4"
+version = "0.3.5"
 edition = "2021"
 license = "MIT"
 readme = "README.md"

{foghttp-0.3.4 → foghttp-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: foghttp
-Version: 0.3.4
+Version: 0.3.5
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: AsyncIO
 Classifier: License :: OSI Approved :: MIT License
@@ -15,6 +15,7 @@ Requires-Dist: mypy>=2.1,<3 ; extra == 'dev'
 Requires-Dist: pre-commit>=4,<5 ; extra == 'dev'
 Requires-Dist: pytest>=8 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'
+Requires-Dist: pytest-timeout>=2,<3 ; extra == 'dev'
 Requires-Dist: ruff>=0.15,<0.16 ; extra == 'dev'
 Requires-Dist: trustme>=1.2 ; extra == 'dev'
 Provides-Extra: dev
@@ -69,8 +70,8 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
   diagnostic dump APIs
 - opt-in async lifecycle debug snapshots for staging and tests
 - advanced per-client Tokio runtime worker tuning
-- focused buffered HTTP surface for JSON and form APIs, internal services,
-  workers, and benchmarks
+- focused HTTP surface for JSON, form, streaming upload, and multipart API
+  workloads in internal services, workers, and benchmarks
 
 ## Install
 
@@ -124,8 +125,11 @@ async with foghttp.AsyncClient() as client:
 - `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE`
 - `base_url` for reusable API clients and relative request paths
 - default client headers and query params for reusable API clients
-- query params with repeated keys, JSON, form-urlencoded data, and buffered
-  bytes/text bodies
+- query params with repeated keys, JSON, form-urlencoded data, buffered
+  bytes/text bodies, binary file-like request bodies, and streaming
+  bytes-like upload providers
+- multipart `files=` uploads with bytes-like parts, binary file-like objects,
+  direct byte streams, and replayable byte-stream factories
 - buffered `Response` with status flags, charset-aware `text`, `json()`,
   `raise_for_status()`, and request metadata
 - transparent `gzip`, `deflate`, and `br` decoding for buffered responses
@@ -164,6 +168,7 @@ async with foghttp.AsyncClient() as client:
 - [Request builder compatibility](https://github.com/AmberFog/foghttp/blob/main/docs/request-builder.md)
 - [Client lifecycle](https://github.com/AmberFog/foghttp/blob/main/docs/lifecycle.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)
 - [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)
@@ -177,18 +182,19 @@ async with foghttp.AsyncClient() as client:
 ## Current Limitations
 
 FogHTTP is currently focused on controlled HTTP workloads. Buffered responses
-are the broadest supported path; sync and async response streaming are available
-as bytes/text/line context-managed APIs. HTTP proxy routing and HTTPS proxy
-`CONNECT` tunnelling are available through `proxy=` and `trust_env=True` when
-the proxy endpoint itself uses `http://`.
-Streaming uploads, cookies, auth helpers, multipart uploads,
-HTTP/2, automatic `Accept-Encoding` negotiation, streaming decompression,
-strict connection-level pool limits,
-per-request connect timeout reconfiguration, and request-body write timeout
-semantics are planned for later versions. Response body read timeout is
-available for buffered and streaming response bodies. Socket lifecycle telemetry
-is available for the current HTTP/1 path. Disabling TLS verification is
-intentionally not supported.
+are the broadest supported response path; sync and async response streaming are
+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://`.
+Cookies, auth helpers, HTTP/2, automatic `Accept-Encoding` negotiation,
+streaming decompression, strict connection-level pool limits, and per-request
+connect timeout reconfiguration are planned for later versions.
+Response body read timeout is available for buffered and streaming response
+bodies; request body write timeout is available for buffered and streaming
+request bodies. Socket lifecycle telemetry is available for the current HTTP/1
+path. Disabling TLS verification is intentionally not supported.
 
 ## Development
 

{foghttp-0.3.4 → foghttp-0.3.5}/README.md

@@ -33,8 +33,8 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
   diagnostic dump APIs
 - opt-in async lifecycle debug snapshots for staging and tests
 - advanced per-client Tokio runtime worker tuning
-- focused buffered HTTP surface for JSON and form APIs, internal services,
-  workers, and benchmarks
+- focused HTTP surface for JSON, form, streaming upload, and multipart API
+  workloads in internal services, workers, and benchmarks
 
 ## Install
 
@@ -88,8 +88,11 @@ async with foghttp.AsyncClient() as client:
 - `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE`
 - `base_url` for reusable API clients and relative request paths
 - default client headers and query params for reusable API clients
-- query params with repeated keys, JSON, form-urlencoded data, and buffered
-  bytes/text bodies
+- query params with repeated keys, JSON, form-urlencoded data, buffered
+  bytes/text bodies, binary file-like request bodies, and streaming
+  bytes-like upload providers
+- multipart `files=` uploads with bytes-like parts, binary file-like objects,
+  direct byte streams, and replayable byte-stream factories
 - buffered `Response` with status flags, charset-aware `text`, `json()`,
   `raise_for_status()`, and request metadata
 - transparent `gzip`, `deflate`, and `br` decoding for buffered responses
@@ -128,6 +131,7 @@ async with foghttp.AsyncClient() as client:
 - [Request builder compatibility](https://github.com/AmberFog/foghttp/blob/main/docs/request-builder.md)
 - [Client lifecycle](https://github.com/AmberFog/foghttp/blob/main/docs/lifecycle.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)
 - [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)
@@ -141,18 +145,19 @@ async with foghttp.AsyncClient() as client:
 ## Current Limitations
 
 FogHTTP is currently focused on controlled HTTP workloads. Buffered responses
-are the broadest supported path; sync and async response streaming are available
-as bytes/text/line context-managed APIs. HTTP proxy routing and HTTPS proxy
-`CONNECT` tunnelling are available through `proxy=` and `trust_env=True` when
-the proxy endpoint itself uses `http://`.
-Streaming uploads, cookies, auth helpers, multipart uploads,
-HTTP/2, automatic `Accept-Encoding` negotiation, streaming decompression,
-strict connection-level pool limits,
-per-request connect timeout reconfiguration, and request-body write timeout
-semantics are planned for later versions. Response body read timeout is
-available for buffered and streaming response bodies. Socket lifecycle telemetry
-is available for the current HTTP/1 path. Disabling TLS verification is
-intentionally not supported.
+are the broadest supported response path; sync and async response streaming are
+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://`.
+Cookies, auth helpers, HTTP/2, automatic `Accept-Encoding` negotiation,
+streaming decompression, strict connection-level pool limits, and per-request
+connect timeout reconfiguration are planned for later versions.
+Response body read timeout is available for buffered and streaming response
+bodies; request body write timeout is available for buffered and streaming
+request bodies. Socket lifecycle telemetry is available for the current HTTP/1
+path. Disabling TLS verification is intentionally not supported.
 
 ## Development
 

foghttp-0.3.5/docs/benchmarks.md

@@ -0,0 +1,206 @@
+# Benchmarks
+
+Benchmark harness and full benchmark reports live in a separate repository:
+[github.com/AmberFog/FogHttpBenchmark](https://github.com/AmberFog/FogHttpBenchmark).
+
+This page is a benchmark status snapshot, not a marketing scoreboard. Invalid
+rows, compatibility gaps, resource-limit errors, and weak spots stay visible
+because they are the inputs we use to improve FogHTTP.
+
+Last updated: `2026-06-08`.
+
+## Methodology
+
+- Server: local asyncio HTTP/1.1 loopback server, plus local HTTPS/proxy
+  fixtures for the proxy suite.
+- Python: `3.14.0` on the primary benchmark host.
+- Shuffle seed: `20260507`.
+- Higher `ok/s`, `ops/s`, `req/s`, successful `streams/s`, `MiB/s`, or
+  `lines/s` is better.
+- Lower `p95 ms`, `p99 ms`, threads, fds, and error counts are better.
+- Throughput and latency comparisons are only meaningful for rows with `0`
+  measured errors and `0` warmup errors.
+- Resource/backpressure suites intentionally trigger `PoolTimeout`,
+  `ResponseBodyTooLargeError`, and `ResponseBodyBudgetExceededError`; those are
+  expected resource-control outcomes, not benchmark harness failures.
+- Reports with `needs-rerun` or `invalid` validity are diagnostic evidence. They
+  must not be used as strong performance baselines until the reason is
+  classified or rerun.
+
+## Benchmark Hosts
+
+Primary benchmark data source for this page:
+
+- Result directories:
+  `results/full-current-deps-foghttp-0.3.4-20260607-121844`,
+  `results/full-branch-opt-pipeline-20260607-230009`, and
+  `results/proxy-connect-0.3.4-isolated-full-20260607-213445`.
+- Platform: `macOS-26.5.1-arm64-arm-64bit-Mach-O`.
+- Python: `3.14.0`.
+- Server: local asyncio HTTP/1.1 loopback server; proxy suite additionally uses
+  local HTTPS origin and local HTTP proxy fixtures.
+- Package versions: FogHTTP `0.3.4`, aiohttp `3.14.0`, httpx `0.28.1`,
+  httpxyz `0.31.2`, zapros `0.13.0`.
+
+Secondary diagnostic host:
+
+- Result directory: `results/dvorkin-opt_pipeline-20260607-230859`.
+- Platform: `macOS-15.7.7-x86_64-i386-64bit-Mach-O`.
+- Python: `3.13.7`.
+- Package versions match the primary host for the clients listed above.
+
+Absolute throughput, latency, memory, thread, and fd values are compared only
+within the same host/result lineage. The secondary host is used as a relative
+sanity check: it can confirm whether broad client ranking patterns repeat, but
+it is not mixed into release delta charts or absolute performance conclusions.
+
+## Current Source Snapshots
+
+| Role | Result directory | Status | Use |
+| --- | --- | --- | --- |
+| Latest release comparison | `results/full-current-deps-foghttp-0.3.4-20260607-121844` | legacy report, before the new validity gate metadata | Release-to-release signal versus `0.3.2`; useful, but dependency and harness changes mean attribution is not perfect. |
+| Primary branch evidence | `results/full-branch-opt-pipeline-20260607-230009` | mixed: valid/warning/needs-rerun by suite | Primary host execution evidence for the current benchmark harness. FogHTTP rows are clean in the local problematic suites, but some all-client reports need policy/rerun work before becoming strong baselines. |
+| Secondary host diagnostic run | `results/dvorkin-opt_pipeline-20260607-230859` | diagnostic; some suites `needs-rerun` | Relative cross-host sanity check only. External-only failures are not treated as FogHTTP runtime regressions until targeted reruns classify them. |
+| Valid proxy/CONNECT baseline | `results/proxy-connect-0.3.4-isolated-full-20260607-213445` | valid | Strong functional proxy/CONNECT baseline: `126` aggregate rows, `378` runs, `21` isolated child processes, `0` measured/warmup errors. |
+
+## Release-Level Read
+
+FogHTTP `0.3.4` does not show a broad functional regression in the local release
+baseline: normal request, client, compression, one-upstream, request-builder,
+and response-streaming FogHTTP rows have no unexpected errors. The clear
+engineering picture is performance drift in a few areas, not broken runtime
+semantics.
+
+| Suite | FogHTTP primary delta vs `0.3.2` | p95 delta vs `0.3.2` | Competitive result | Current judgement |
+| --- | ---: | ---: | --- | --- |
+| `requests` | `-2.8%` | `+4.3%` | wins `64/72` | Mild aggregate drift, but the primary branch run shows recovery; keep as watch suite. |
+| `requests-delay-pool` | `-1.6%` | `+1.5%` | wins `11/16` | Mostly stable under delayed/constrained request workloads. |
+| `client-creation` | `-14.4%` | `+24.3%` | wins `3/12` | Main confirmed regression candidate; short-lived client lifecycle got more expensive. |
+| `compressed-response` | `-7.7%` | `+9.1%` | wins `34/36` | Still strong and error-free for FogHTTP, but buffered decompression throughput drift needs validation. |
+| `one-upstream` | `-6.9%` | `+9.4%` | wins `48/48` | Still one of the strongest FogHTTP paths, but local drift needs a controlled rerun. |
+| `request-builder` | `-1.9%` | `+4.7%` | wins `20/20` | Stable overall; prepared send path should be watched. |
+| `response-streaming` | `-1.2%` | `+2.5%` | wins `37/60` | Competitive position improved, but async early-close remains a focused weak spot. |
+
+```mermaid
+xychart-beta
+    title "FogHTTP 0.3.4 primary delta vs 0.3.2"
+    x-axis [requests, delay_pool, client_creation, compressed, one_upstream, builder, streaming]
+    y-axis "primary delta %" -20 --> 5
+    bar [-2.8, -1.6, -14.4, -7.7, -6.9, -1.9, -1.2]
+```
+
+```mermaid
+xychart-beta
+    title "FogHTTP success-only wins by suite"
+    x-axis [requests, delay_pool, client_creation, compressed, one_upstream, builder, streaming]
+    y-axis "win %" 0 --> 100
+    bar [89, 69, 25, 94, 100, 100, 62]
+```
+
+## Primary Branch Evidence
+
+The primary host branch run,
+`results/full-branch-opt-pipeline-20260607-230009`, completed all local suites
+with `0` failed isolated child processes. That is good execution evidence for
+the harness and for FogHTTP's basic runtime stability.
+
+It is not yet a strong comparison baseline:
+
+- `compressed-response` is `needs-rerun` because `aiohttp` and `zapros` fail
+  `multi-gzip-deflate-64k`; FogHTTP rows have `0` measured and warmup errors.
+- `requests` is `needs-rerun` because competitor/case rows fail, including
+  `zapros` redirects and `aiohttp` pool-contention rows; FogHTTP rows have `0`
+  measured and warmup errors.
+- `response-streaming` is `needs-rerun` because `aiohttp` rejects
+  `long-line-1m`; FogHTTP rows have `0` measured and warmup errors.
+- `client-creation` and `one-upstream` are `warning`, mostly from high
+  variation rows.
+- `request-builder`, `resource-backpressure`, and `proxy-connect` are valid.
+
+This means the primary branch run is healthy enough to guide investigation, but the
+benchmark project still needs expected-compatibility policy and baseline-split
+work before these all-client reports should drive hard regression gates.
+
+## Secondary Host Evidence
+
+The external `dvorkin` run is a relative sanity check. It is not used for
+absolute performance numbers on this page. It shows two important diagnostic
+signals:
+
+- External `one-upstream` is `needs-rerun` from FogHTTP `direct-get`
+  `RequestError` rows, including a high-error row around `99.97%`. The same
+  failure does not reproduce in the local loopback run, so this is an
+  external-host reproducibility problem until targeted reruns prove otherwise.
+- External `proxy-connect` is `needs-rerun` from `httpx` HTTPS/proxy failures.
+  FogHTTP proxy rows are clean in that run, so this is not evidence of a
+  FogHTTP proxy regression.
+
+The correct next step is targeted external reruns and error-family preservation
+in aggregate reports, not optimization work based on the invalid secondary-host
+summary.
+
+## Proxy And CONNECT
+
+The valid isolated proxy baseline,
+`results/proxy-connect-0.3.4-isolated-full-20260607-213445`, is the most
+important new `0.3.4` validation signal:
+
+- `126` aggregate rows and `378` measured runs.
+- `21` isolated child processes.
+- `0` measured errors and `0` warmup errors.
+- Coverage includes direct HTTP, explicit HTTP proxy, `trust_env` HTTP proxy,
+  direct HTTPS, explicit HTTPS CONNECT, `trust_env` HTTPS CONNECT, and cold
+  CONNECT setup.
+
+Median successful request throughput by client in the local proxy suite:
+
+| Client | Median `req/s` across proxy suite rows |
+| --- | ---: |
+| FogHTTP | `4471.7` |
+| httpxyz | `1578.5` |
+| httpx | `1209.6` |
+
+This is not only a speed result. The more important release signal is that the
+new proxy/CONNECT paths are functionally stable under isolated all-client
+execution. The known limitation remains that separate proxy-endpoint telemetry
+is not exposed yet; current connection and pool diagnostics are target-origin
+keyed.
+
+## Strong Areas
+
+- Buffered local request workloads remain competitive, especially sync request
+  paths and high-concurrency rows.
+- Client defaults and one-upstream ergonomics remain cheap: the release baseline
+  wins `48/48` one-upstream groups.
+- Request building is still a strength: the release baseline wins `20/20`
+  groups.
+- Buffered gzip/deflate/br decompression is functionally strong and keeps
+  stacked-encoding compatibility where some competitors fail.
+- Proxy and HTTPS CONNECT are now covered by a valid isolated suite with clean
+  FogHTTP rows.
+- Resource/backpressure behavior is explicit: bounded response-body and pool
+  pressure errors are expected outcomes and are visible in the reports.
+
+## Weak Spots And Follow-Ups
+
+| Area | Signal | What to do next |
+| --- | --- | --- |
+| Client lifecycle | `client-creation` release baseline shows `-14.4%` primary delta and `+24.3%` p95 delta vs `0.3.2`. | Validate under the current validity-gated harness, then profile client/runtime setup and close paths. |
+| Buffered/API throughput | `compressed-response` and `one-upstream` remain strong competitively but show release-level drift. | Rerun with controlled dependencies and split strong baseline rows from compatibility rows. |
+| Streaming early close | Overall streaming improved, but async `first-chunk-close-1m` regressed in the release comparison. | Investigate early close/abort cleanup path separately from full-consume streaming. |
+| External reproducibility | External `one-upstream` FogHTTP `direct-get` errors do not reproduce locally. | Add targeted external rerun workflow before calling this a FogHTTP runtime issue. |
+| Benchmark reporting | Some aggregate reports lose enough error-family detail to classify expected competitor failures cleanly. | Preserve aggregate error metadata, then add expected-compatibility policy and regression gates. |
+
+## Current Engineering Conclusion
+
+FogHTTP `0.3.4` added the adoption-critical proxy and HTTPS CONNECT surface, and
+that path is now covered by a valid isolated benchmark. The core
+request/streaming/resource behavior remains functionally clean in local FogHTTP
+rows.
+
+The honest caveat is performance validation. The project should not optimize
+against invalid all-client summaries or external-host anomalies. The benchmark
+work should first harden validity metadata, expected compatibility policy,
+strong-baseline splitting, and targeted external reruns. After that, the real
+runtime optimization targets are client lifecycle cost, buffered/API drift, and
+streaming early-close overhead.

{foghttp-0.3.4 → foghttp-0.3.5}/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, 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, sync and async APIs, redirects, custom CA certificates, cancellation, and observable request limits with pool diagnostics."
 
 features:
   - title: "Rust transport"
@@ -14,14 +14,14 @@ features:
     details: "Use Client in scripts and workers, or AsyncClient for high-concurrency asyncio workloads."
 
   - title: "Focused MVP"
-    details: "FogHTTP is intentionally small today: buffered responses with gzip/deflate/br decoding, sync and async bytes/text/line streaming, JSON, form-urlencoded data, base URL clients, default headers and params, redirects, prepared requests, async cancellation, global and per-origin request limits, and request metadata."
+    details: "FogHTTP is intentionally small today: buffered responses with gzip/deflate/br decoding, sync and async bytes/text/line streaming, JSON, form-urlencoded data, streaming and multipart uploads, base URL clients, default headers and params, redirects, prepared requests, async cancellation, global and per-origin request limits, and request metadata."
 ---
 
 # FogHTTP Documentation
 
 FogHTTP is currently an MVP. It is already useful for controlled HTTP workloads
-that use buffered request/response bodies, JSON and form APIs, explicit client
-lifecycle, and predictable redirect behavior.
+that use buffered request/response bodies, JSON and form APIs, streaming or
+multipart uploads, explicit client lifecycle, and predictable redirect behavior.
 
 ## Positioning
 
@@ -71,6 +71,7 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
 - [Request builder compatibility](./request-builder.md)
 - [Client lifecycle](./lifecycle.md)
 - [Timeout model](./timeouts.md)
+- [Upload typing contracts](./upload-types.md)
 - [Telemetry contract](./telemetry.md)
 - [Response streaming](./streaming.md)
 - [TLS trust](./tls.md)
@@ -98,12 +99,15 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
 - `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE`
 - `base_url` for reusable API clients and relative request paths
 - default client headers and query params for reusable API clients
-- query params with repeated keys, JSON, form-urlencoded data, and buffered
-  bytes/text bodies
+- query params with repeated keys, JSON, form-urlencoded data, buffered
+  bytes/text bodies, file-like bodies, streaming bytes-like iterables, and
+  multipart `files=` uploads
 - transparent `gzip`, `deflate`, and `br` decoding for buffered responses
 - 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()`
+- public upload typing contracts for streaming request bodies and multipart
+  `files=` providers
 - case-insensitive `Headers` with repeated value support
 - safe policy for transport-managed request headers
 - redacted repr/error surfaces for sensitive headers, URL credentials,
@@ -132,9 +136,9 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
 
 ## Not Yet
 
-FogHTTP does not yet implement streaming uploads, cookies, multipart uploads,
-HTTP/2, automatic `Accept-Encoding` negotiation, streaming decompression, or
-advanced authentication helpers. `trust_env` supports HTTP proxy routing, HTTPS
+FogHTTP does not yet implement cookies, HTTP/2, automatic `Accept-Encoding`
+negotiation, streaming decompression, or advanced authentication helpers.
+`trust_env` supports HTTP proxy routing, HTTPS
 `CONNECT` tunnelling through `http://` proxy endpoints, and `SSL_CERT_FILE`.
 Disabling TLS verification is intentionally not supported. See
 [Limitations](./limitations.md) for details.

{foghttp-0.3.4 → foghttp-0.3.5}/docs/lifecycle.md

@@ -420,9 +420,10 @@ if diagnostics["pending_requests"]:
 
 ## Current Boundaries
 
-The lifecycle contract currently applies to buffered requests/responses and
-sync/async streamed response bodies. Streaming uploads, cookies, proxies, and
-advanced auth helpers are planned later and may extend the lifecycle model.
+The lifecycle contract currently applies to buffered requests/responses,
+sync/async streamed response bodies, and streaming request bodies passed through
+`content=`. Cookies and advanced auth helpers are planned later and may extend
+the lifecycle model.
 
 FogHTTP exposes socket lifecycle telemetry for the current HTTP/1 path, but
 resource limits still describe request backpressure rather than strict raw TCP

{foghttp-0.3.4 → foghttp-0.3.5}/docs/limitations.md

@@ -22,7 +22,10 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
 - query parameters from mappings, repeated pairs, and raw query strings
 - JSON bodies through `json=`
 - form-urlencoded bodies through mapping or repeated-pair `data=`
-- raw bytes/text bodies through `content=`
+- multipart file uploads through `files=`, optionally combined with mapping or
+  repeated-pair `data=` form fields
+- raw bytes/text, binary file-like, sync bytes-like iterable, and async bytes-like iterable
+  bodies through `content=`
 - buffered responses
 - transparent `gzip`, `deflate`, and `br` decoding for buffered responses
 - sync response streaming through `Client.stream()`
@@ -53,8 +56,8 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
 - explicit `close()`/`aclose()` lifecycle for Rust runtime and pool resources;
   sync `close()` waits for in-flight sync requests, while async `aclose()`
   cancels in-flight async requests; see [Client lifecycle](./lifecycle.md)
-- documented current timeout model for client-level `connect`, per-request
-  `pool`/`read`/`total`, and reserved `write`; see
+- documented current timeout model for client-level `connect` and per-request
+  `pool`/`read`/`write`/`total`; see
   [Timeout model](./timeouts.md)
 - advanced `runtime_workers` tuning for the per-client Tokio runtime
 - reusable HTTP method constants through `foghttp.methods`
@@ -65,9 +68,11 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
 | Feature | Current behavior |
 |---|---|
 | Streaming response decompression | Not available; buffered responses support transparent decoding |
-| Streaming uploads | Not available; request bodies are buffered |
-| Multipart uploads | Not available |
-| `files=` | Reserved in the body matrix; not available yet |
+| Multipart uploads | Available through `files=` for bytes-like parts, binary file-like objects, direct byte streams, and byte-stream factories |
+| `files=` | Available; can be combined with mapping or repeated-pair `data=` form fields, but not with raw `data=`, `content=`, or `json=` |
+| Multipart header values | Field names, filenames, and part content types are currently limited to printable ASCII; non-ASCII filenames need a later compatibility design |
+| Streaming uploads | Available through `content=` for binary file-like objects, sync bytes-like iterables, zero-arg byte-stream factories, and async bytes-like iterables/factories on `AsyncClient`; direct stream/file bodies are non-replayable for method-preserving redirects, while factories can replay by returning a fresh stream |
+| Upload typing contracts | Public provider/factory and multipart aliases are available for streaming `content=` and multipart `files=` APIs |
 | Cookie jar | `cookies=True` is rejected |
 | Plain HTTP proxy routing | Available for `http://` targets through explicit `proxy=` or `trust_env=True` environment config |
 | HTTPS proxy `CONNECT` | Available for `https://` targets through explicit `proxy=` or `trust_env=True` when the proxy endpoint itself uses `http://`; TLS is validated against the target host |
@@ -79,10 +84,10 @@ try to keep public interfaces stable and avoid unnecessary breaking changes.
 | HTTP/2 | Not available |
 | automatic `Accept-Encoding` negotiation | Not implemented; send `Accept-Encoding` manually when you want compressed responses |
 | transport-managed request headers | Safe API rejects manual `Host`, `Content-Length`, `Transfer-Encoding`, `TE`, `Trailer`, `Connection`, `Upgrade`, `Keep-Alive`, `Proxy-Connection`, and `Proxy-Authorization` |
-| request body source conflicts | Only one body source can be passed today: `json=`, `data=`, or `content=` |
+| request body source conflicts | Use one body source among `json=`, `data=`, `content=`, and `files=`; `files=` can include form fields from mapping or repeated-pair `data=` |
 | true active connection-level limits | `max_active_requests_per_origin` limits buffered request slots; socket lifecycle telemetry is observable, but FogHTTP does not yet expose separate physical connection limits |
 | per-request connect timeout changes | `Timeouts.connect` configures the Rust connector from client-level settings when transport state is created; per-request `timeout.connect` does not reconfigure the connector |
-| separate read/write timeout semantics | `Timeouts.read` is implemented as a buffered and streamed response body progress timeout; `Timeouts.write` is reserved for later streaming upload/body work |
+| 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, active, and idle tracked connection counters for the current HTTP/1 path; these are connector/lifecycle diagnostics, not a stable public view into Hyper's private pool internals |
 | 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 |
 | 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 |
@@ -95,7 +100,8 @@ Use FogHTTP today when:
 - responses are small enough to buffer in memory or can be consumed through the
   bytes/text/line streaming API; line streaming has a bounded per-line buffer by
   default
-- requests are JSON-heavy or use small form-urlencoded bodies
+- requests are JSON-heavy, use small form-urlencoded bodies, multipart file
+  uploads, or explicit streaming upload bodies
 - redirects are simple and do not require cookie jar or auth helper integration
 - sync and async clients with explicit lifecycle are enough
 - async request cancellation and sync/async stream cleanup behavior are useful
@@ -107,12 +113,9 @@ Use FogHTTP today when:
 Wait before using FogHTTP when:
 
 - you need transparent streaming decompression
-- you upload large files
 - you need SOCKS, PAC, WPAD, or platform proxy discovery
 - you rely on cookies across requests
-- you need multipart form-data or large uploads
-- you need per-request connect timeout reconfiguration or request-body write
-  timeout semantics
+- you need per-request connect timeout reconfiguration
 - you need automatic compression negotiation instead of manual
   `Accept-Encoding`
 - you need strict active per-host connection limits
@@ -122,9 +125,10 @@ Wait before using FogHTTP when:
 
 Network and protocol failures map to `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. The broader
+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 it covers acquire, redirects, and response headers
-before the stream is returned. Dedicated connect/write timeout exception
-mappings are reserved for later timeout work. See
+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
 [Timeout model](./timeouts.md) for the current behavior.

{foghttp-0.3.4 → foghttp-0.3.5}/docs/quickstart.md

@@ -364,7 +364,8 @@ body content and does not add `content-type` automatically.
 
 ## Raw Content
 
-Use `content=` for already encoded bytes or text.
+Use `content=` for already encoded bytes, text, binary file-like objects, or
+bytes-like iterables.
 
 ::: code-group
 
@@ -396,15 +397,25 @@ FogHTTP currently accepts one body source per request:
 |---|---|
 | `json=` | Encodes with `orjson` and adds `content-type: application/json` when no explicit content type is set |
 | `data=` | Encodes mappings and repeated pairs as `application/x-www-form-urlencoded`; raw `bytes` and `str` are sent as buffered body content |
-| `content=` | Accepts buffered `bytes` or `str`; strings are encoded as UTF-8 and no semantic content type is added |
-| `files=` | Reserved for future multipart uploads |
+| `content=` | 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 and no semantic content type is added |
+| `files=` | Builds multipart uploads from bytes-like parts, binary file-like objects, byte streams, or byte-stream factories; can be combined with mapping or repeated-pair `data=` form fields |
 
-Passing more than one body source raises `ValueError`. `Content-Length` and
+Passing incompatible body sources raises `ValueError`; `files=` may be combined
+with form-field `data=` mappings or repeated pairs. `Content-Length` and
 `Transfer-Encoding` are transport-managed framing headers and are not accepted
 in request headers; the Rust transport owns them. Buffered `json=`, `data=`,
-and `content=` bodies are replayable for the current redirect policy. Iterator,
-async iterator, and streaming request bodies are not accepted yet and will need
-an explicit non-replayable body contract later.
+byte/string `content=`, and bytes-like multipart file parts are replayable for
+the current redirect policy. File-like and direct streaming `content=` or
+`files=` bodies are non-replayable, so method-preserving redirects fail closed
+instead of replaying a consumed provider. Factory-backed streaming bodies are
+replayable because the factory returns a fresh stream per send attempt. Public
+provider and multipart type aliases are documented in
+[Upload typing contracts](./upload-types.md).
+
+`get()` and `head()` are bodyless convenience helpers. Use `post()`, `put()`,
+`patch()`, `delete()`, `request()`, or `stream()` for body parameters. If you
+intentionally need a non-standard GET or HEAD body, use the explicit
+`request("GET", ..., content=...)` / `request("HEAD", ..., content=...)` form.
 
 ## Buffered Response Decoding
 
@@ -686,8 +697,8 @@ with foghttp.Client(telemetry=foghttp.TelemetryConfig(sink=Sink())) as client:
 ```
 
 `Timeouts.connect` is client-level connector configuration. Per-request
-`timeout=` currently affects `pool`, `read`, and `total`, not `connect` or
-`write`. See [Timeout model](./timeouts.md) for the detailed current contract
+`timeout=` currently affects `pool`, `read`, `write`, and `total`, not
+`connect`. See [Timeout model](./timeouts.md) for the detailed current contract
 and limitations.
 
 ## Runtime Workers