httpx-hedged 0.2.0__tar.gz

httpx_hedged-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.13"]
+      fail-fast: false
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      # If you have a requirements.txt file, uv installs it directly into an ephemeral environment
+      - name: Run Ruff Linter
+        run: uv run --with ruff ruff check .
+
+      - name: Run Ruff Formatter Check
+        run: uv run --with ruff ruff format --check .
+
+      - name: Run Tests with Pytest
+        run: uv run --with pytest pytest

httpx_hedged-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*' # Triggers on semantic version tags like v1.0.0, v0.2.1-beta, etc.
+
+jobs:
+  build-and-publish:
+    name: Build package and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    # Required environment permissions for PyPI Trusted Publishing OIDC
+    permissions:
+      id-token: write  # MANDATORY: Enables GitHub to request the OIDC token
+      contents: read   # Required to checkout code
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install "3.13"
+
+      - name: Build Source and Wheel Distributions
+        run: uv build
+
+      - name: Publish Package to PyPI
+        run: uv publish

httpx_hedged-0.2.0/.gitignore

@@ -0,0 +1,210 @@
+# Reference clone, not part of this project
+/hedge-python/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

httpx_hedged-0.2.0/.python-version

@@ -0,0 +1 @@
+3.13

httpx_hedged-0.2.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Brendan Fahy
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

httpx_hedged-0.2.0/PKG-INFO

@@ -0,0 +1,300 @@
+Metadata-Version: 2.4
+Name: httpx-hedged
+Version: 0.2.0
+Summary: Adaptive, per-endpoint request hedging transport for httpx. Learns latency percentiles per endpoint with DDSketch, caps hedge rate with a token bucket, and stops hedging under a host/endpoint circuit breaker.
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.27.0
+Description-Content-Type: text/markdown
+
+# httpx-hedged
+
+An [httpx](https://www.python-httpx.org/) transport that adds
+adaptive, per-endpoint request hedging: fire a backup request when the
+primary is running slow, take whichever finishes first, cancel the
+loser. Based on Google's [The Tail at
+Scale](https://research.google/pubs/pub40801/) and modeled heavily on
+[hedge-python](https://github.com/sunhailin-Leo/hedge-python).
+
+## Quick start
+
+```python
+import asyncio
+import httpx
+from httpx_hedged import HedgedTransport
+
+async def main():
+    transport = HedgedTransport()
+    async with httpx.AsyncClient(transport=transport) as client:
+        response = await client.get("https://api.example.com/data")
+        print(response.json())
+
+asyncio.run(main())
+```
+
+With no configuration, `HedgedTransport` learns a p90 latency estimate per
+host (via a [DDSketch](https://arxiv.org/abs/2004.08604) quantile sketch)
+and fires a hedge request whenever the primary exceeds it. 
+
+## Why per-endpoint?
+
+A single host can host wildly different endpoints. Learning one latency
+distribution per *host* -- rather than per endpoint -- means a handful of
+calls to a slow endpoint skew the hedge trigger for a fast one sharing the
+same host:
+
+```
+GET /api/v1/fast-lookup   median 10ms,  high RPS
+GET /api/v1/bulk-export   median 900ms, low RPS
+```
+
+`HedgedTransport` lets you register per-endpoint config up front. Each
+registered endpoint gets its own latency sketch, rate estimate, and hedge
+budget -- all still funneled through a **single inner transport and
+connection pool**, unlike using `httpx` `mounts={}`, which would mean one
+connection pool per pattern:
+
+```python
+from httpx_hedged import EndpointConfig, HedgedTransport
+
+transport = HedgedTransport()
+transport.register("GET", "/api/v1/fast-lookup", EndpointConfig(percentile=0.90))
+transport.register("GET", "/api/v1/bulk-export", EndpointConfig(percentile=0.90))
+```
+
+Requests that don't match a registered pattern fall back to a default
+config, tracked per host (the same behavior as hedging with no registered
+endpoints at all).
+
+Route patterns may contain `{name}` placeholders or a bare `*` for a single
+path segment, e.g. `/api/v1/users/{id}`. Patterns are matched in
+registration order -- register more specific patterns first.
+
+## Hardcoded vs. adaptive delay
+
+Most endpoints should hedge adaptively, against their own learned
+percentile:
+
+```python
+transport.register("GET", "/api/v1/search", EndpointConfig(percentile=0.95))
+```
+
+For an endpoint where you already know the right delay -- or want
+deterministic behavior without a warmup period -- hardcode it instead:
+
+```python
+transport.register("GET", "/api/v1/health", EndpointConfig(hedge_delay=0.05))
+```
+
+A hardcoded endpoint still records latency into its sketch for
+observability; it just isn't consulted for the hedge-delay decision.
+
+## Explicit endpoint override
+
+Auto-matching not precise enough for a particular call site (or you'd
+rather not register a pattern)? Tag the request directly -- this bypasses
+pattern matching entirely:
+
+```python
+await client.get(
+    "https://api.example.com/some/path",
+    extensions={"hedge_endpoint": "pinned-name"},
+)
+```
+
+The name must already be registered (`register(..., name="pinned-name")`);
+an unknown name raises `UnknownHedgeEndpointError` rather than silently
+falling back, so typos fail loudly.
+
+## Configuration
+
+### `HedgeConfig` (transport-wide default)
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `percentile` | `float` | `0.90` | Sketch quantile used as the hedge trigger |
+| `budget_percent` | `float` | `10.0` | Max hedge rate as percent of total traffic |
+| `estimated_rps` | `float \| None` | `None` | Pin the expected requests/sec, or leave `None` to auto-estimate from observed traffic |
+| `rps_window_duration` | `float` | `10.0` | Rolling window (seconds) for RPS auto-estimation |
+| `min_delay` | `float` | `0.001` | Floor on the hedge delay in seconds |
+| `warmup_requests` | `int` | `20` | Requests using a fixed delay before the sketch is trusted |
+| `warmup_delay` | `float` | `0.01` | Fixed hedge delay during warmup, in seconds |
+| `window_duration` | `float` | `30.0` | Latency sketch rotation interval in seconds |
+| `circuit_breaker` | `CircuitBreakerConfig` | see below | Health circuit-breaker configuration |
+
+### `EndpointConfig` (per-registered-endpoint override)
+
+Every field mirrors `HedgeConfig` and defaults to `None`, meaning "inherit
+the transport default." One extra field:
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `hedge_delay` | `float \| None` | `None` | Hardcode the hedge delay for this endpoint, skipping the sketch for the decision |
+
+### `CircuitBreakerConfig`
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `error_rate_threshold` | `float` | `0.5` | Failure fraction that trips the breaker open |
+| `min_samples` | `int` | `20` | Minimum samples in-window before the breaker can trip |
+| `window_duration` | `float` | `30.0` | Rolling window (seconds) for the error-rate estimate |
+| `cooldown` | `float` | `30.0` | Seconds the breaker stays open before a half-open trial |
+| `half_open_max_trial` | `int` | `5` | Trial requests allowed through while half-open |
+| `treat_5xx_as_failure` | `bool` | `True` | Whether an HTTP 5xx response counts as a failure |
+
+All three config classes validate their fields at construction time (e.g.
+`percentile` must be strictly between 0 and 1, delays and windows must be
+non-negative/positive) and raise `ValueError` immediately on a bad value,
+rather than silently misbehaving later.
+
+## How it works
+
+### Race and cancel
+
+```
+              ┌─ primary  ─────────── ✓ (fast) ──→ return
+request ──────┤
+              └─ hedge fires after estimated delay ─── ✗ (cancelled)
+```
+
+Only idempotent methods (`GET`, `HEAD`, `OPTIONS`) are ever hedged, to avoid
+duplicating side effects. A request with a body is also never hedged, even
+if the method is idempotent -- the primary and hedge send the same
+`httpx.Request` object, and a body backed by a one-shot stream can't be
+safely read twice.
+
+### DDSketch quantile estimator
+
+Each tracked key (an endpoint, or the per-host fallback) gets its own
+sliding-window DDSketch pair that rotates every `window_duration` seconds.
+DDSketch gives relative-error quantile guarantees regardless of the
+underlying latency distribution's shape.
+
+### Token bucket budget
+
+Hedges are rate-limited by a token bucket refilling at
+`estimated_rps * budget_percent / 100` tokens/second, per key. During a
+genuine outage the bucket drains and hedging stops automatically,
+preventing the load-doubling spiral that would deepen the incident. By
+default the RPS feeding this calculation is estimated automatically from
+observed traffic per key, rather than requiring a manual guess per
+endpoint.
+
+## Circuit breaker
+
+A closed / open / half-open circuit breaker tracks request success/failure
+at **two independent tiers**: one breaker per host, one breaker per
+endpoint key. Either tripping open suppresses hedging for its scope -- a
+host-level trip disables hedging for every endpoint on that host, while an
+endpoint-level trip disables hedging only for that one endpoint.
+
+Crucially, the breaker **only ever suppresses the hedge request**. The
+primary request is always sent, and its result or exception is always
+returned to the caller normally -- this is not a request-blocking circuit
+breaker, so hedging can't pile extra load onto a backend that's already
+struggling.
+
+```
+CLOSED ──(error rate ≥ threshold, samples ≥ min_samples)──▶ OPEN
+OPEN ──(cooldown elapsed)──▶ HALF_OPEN
+HALF_OPEN ──(trial requests mostly succeed)──▶ CLOSED
+HALF_OPEN ──(trial requests mostly fail)────▶ OPEN
+```
+
+Note: health is recorded from the *winning* task's outcome only -- a
+cancelled loser's real outcome is unknowable, and losers are cancelled
+deliberately (not doing so would defeat the point of reducing load on a
+struggling backend).
+
+## Observability
+
+### Polling stats and health snapshots
+
+```python
+transport = HedgedTransport()
+
+# ... after running some traffic ...
+for key, snap in transport.stats.all_snapshots().items():
+    print(key, snap)
+
+print(transport.stats.global_snapshot())
+print(transport.health.host_state("api.example.com"))
+```
+
+`StatsSnapshot` reports `total_requests`, `hedged_requests`, `hedge_wins`,
+`primary_wins`, `budget_exhausted`, `warmup_requests`, `circuit_blocked`,
+and `errors` per key, plus a global aggregate.
+
+### Push-based hooks: metrics and alerting
+
+Polling snapshots works for dashboards, but alerting on a circuit-breaker
+trip and emitting a metric on every hedge fire are both things you want to
+happen *at the moment they occur*, not on the next poll. `HedgedTransport`
+takes two optional callbacks for exactly this:
+
+```python
+import logging
+
+import httpx
+from httpx_hedged import EndpointConfig, HedgeConfig, HedgedTransport
+
+logger = logging.getLogger("myapp.hedging")
+
+
+def emit_hedge_fired_metric(key: str) -> None:
+    statsd_client.incr("http.hedge.fired", tags=[f"endpoint:{key}"])
+
+
+def alert_on_circuit_open(scope: str, key: str) -> None:
+    # scope is "host" or "endpoint"; key is the host name or endpoint key
+    # that tripped. Fires exactly once per OPEN transition.
+    logger.error(
+        "hedging circuit breaker OPEN: %s=%s is unhealthy, hedging suspended", scope, key
+    )
+
+
+transport = HedgedTransport(
+    default_config=HedgeConfig(),
+    on_hedge_fired=emit_hedge_fired_metric,
+    on_circuit_open=alert_on_circuit_open,
+)
+
+transport.register("GET", "/api/v1/fast-lookup", EndpointConfig(percentile=0.90))
+transport.register("GET", "/api/v1/bulk-export", EndpointConfig(percentile=0.90))
+
+async with httpx.AsyncClient(transport=transport) as client:
+    ...
+```
+
+`on_hedge_fired` is called with the key each time a hedge request is
+actually launched -- after the idempotency, circuit-breaker, and budget
+gates have all passed, so it only fires for hedges that were genuinely
+sent. `on_circuit_open` is called once per OPEN transition (not on every
+suppressed hedge while it stays open), so it's safe to wire straight into
+an alerting/paging pipeline without flooding it.
+
+Both callbacks run synchronously on the request path, so keep them fast
+(increment a counter, log a line) -- don't do network I/O in them directly.
+
+## Relationship to hedge-python
+
+This library is modeled heavily on
+[hedge-python](https://github.com/sunhailin-Leo/hedge-python), which
+pioneered the DDSketch-based adaptive-hedging approach this project
+borrows. hedge-python keys its sketch per host, which works well for a
+single-endpoint-per-host use case; this project exists to add per-endpoint
+tracking on top of the same core idea, plus a health circuit breaker,
+for services that expose many differently-shaped endpoints on one host. See
+the filed [upstream issue](https://github.com/sunhailin-Leo/hedge-python/issues/2)
+for the motivating scenario.
+
+## References
+
+- [The Tail at Scale](https://research.google/pubs/pub40801/) -- Google's paper on tail latency
+- [DDSketch: A fast and fully-mergeable quantile sketch with relative-error guarantees](https://arxiv.org/abs/2004.08604) -- Masson et al., VLDB 2019
+- [hedge-python](https://github.com/sunhailin-Leo/hedge-python) -- the project this one is modeled after
+- [httpx documentation](https://www.python-httpx.org/)
+
+## License
+
+BSD 3-Clause License. See [LICENSE](LICENSE) file for details.