resilient-httpx 0.1.0__tar.gz

resilient_httpx-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.json
+htmlcov/

resilient_httpx-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 galthran-wq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

resilient_httpx-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: resilient-httpx
+Version: 0.1.0
+Summary: Async HTTP client with retry, backoff, and proxy rotation
+Project-URL: Homepage, https://github.com/galthran-wq/resilient-httpx
+Project-URL: Repository, https://github.com/galthran-wq/resilient-httpx
+Project-URL: Issues, https://github.com/galthran-wq/resilient-httpx/issues
+Author: galthran-wq
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: structlog>=25.0.0
+Requires-Dist: tenacity>=9.1.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: respx; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# resilient-httpx
+
+![python](https://img.shields.io/badge/python-3.10%2B-blue)
+![coverage](https://img.shields.io/badge/coverage-99%25-brightgreen)
+
+Async HTTP client with retry, backoff, and proxy rotation. Built on top of `httpx`, `tenacity`, and `structlog`.
+
+## Installation
+
+```bash
+pip install git+https://github.com/galthran-wq/resilient-httpx.git
+```
+
+## Usage
+
+### Basic (no proxies)
+
+```python
+from resilient_httpx import ProxyHttpClient, RetryPolicy
+
+async with ProxyHttpClient(retry=RetryPolicy(max_attempts=5), timeout=15.0) as client:
+    response = await client.get("https://api.example.com/data")
+```
+
+### With proxy rotation
+
+```python
+from resilient_httpx import ProxyHttpClient, RetryPolicy
+
+client = ProxyHttpClient(
+    proxies=[
+        "http://proxy1:8080",
+        "http://user:pass@proxy2:8080",
+        "socks5://proxy3:1080",
+    ],
+    proxy_strategy="round-robin",  # or "random"
+    retry=RetryPolicy(max_attempts=5, backoff="exponential"),
+    timeout=15.0,
+    blacklist_threshold=3,
+    blacklist_ttl=300.0,
+)
+
+async with client:
+    response = await client.get("https://api.example.com/data")
+    data = response.json()
+```
+
+### Custom retry policy
+
+```python
+import httpx
+from resilient_httpx import RetryPolicy
+
+policy = RetryPolicy(
+    max_attempts=5,
+    backoff="exponential",       # "exponential" | "fixed" | "random_jitter"
+    min_wait=1.0,
+    max_wait=30.0,
+    retry_on=[429, 500, 502, 503, 504],
+    retry_on_exception=[httpx.TimeoutException, httpx.ConnectError],
+)
+```
+
+### Error handling
+
+```python
+from resilient_httpx import ProxyHttpClient, AllProxiesExhausted, MaxRetriesExceeded
+
+async with ProxyHttpClient(proxies=proxy_list) as client:
+    try:
+        response = await client.get("https://api.example.com/data")
+    except AllProxiesExhausted:
+        ...  # all proxies blacklisted
+    except MaxRetriesExceeded as exc:
+        ...  # retries exhausted, exc.__cause__ has the last error
+```
+
+## Configuration Reference
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `proxies` | `list[str] \| None` | `None` | Proxy URLs |
+| `proxy_strategy` | `str` | `"round-robin"` | `"round-robin"` or `"random"` |
+| `retry` | `RetryPolicy` | `RetryPolicy()` | Retry configuration |
+| `timeout` | `float` | `30.0` | Request timeout in seconds |
+| `headers` | `dict[str, str] \| None` | `None` | Default headers |
+| `blacklist_threshold` | `int` | `3` | Consecutive failures before blacklisting |
+| `blacklist_ttl` | `float` | `300.0` | Blacklist duration in seconds |
+| `fallback_to_direct` | `bool` | `False` | Request without proxy when all are blacklisted |
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Run with coverage:
+
+```bash
+pytest --cov=resilient_httpx --cov-report=term-missing
+```

resilient_httpx-0.1.0/README.md

@@ -0,0 +1,104 @@
+# resilient-httpx
+
+![python](https://img.shields.io/badge/python-3.10%2B-blue)
+![coverage](https://img.shields.io/badge/coverage-99%25-brightgreen)
+
+Async HTTP client with retry, backoff, and proxy rotation. Built on top of `httpx`, `tenacity`, and `structlog`.
+
+## Installation
+
+```bash
+pip install git+https://github.com/galthran-wq/resilient-httpx.git
+```
+
+## Usage
+
+### Basic (no proxies)
+
+```python
+from resilient_httpx import ProxyHttpClient, RetryPolicy
+
+async with ProxyHttpClient(retry=RetryPolicy(max_attempts=5), timeout=15.0) as client:
+    response = await client.get("https://api.example.com/data")
+```
+
+### With proxy rotation
+
+```python
+from resilient_httpx import ProxyHttpClient, RetryPolicy
+
+client = ProxyHttpClient(
+    proxies=[
+        "http://proxy1:8080",
+        "http://user:pass@proxy2:8080",
+        "socks5://proxy3:1080",
+    ],
+    proxy_strategy="round-robin",  # or "random"
+    retry=RetryPolicy(max_attempts=5, backoff="exponential"),
+    timeout=15.0,
+    blacklist_threshold=3,
+    blacklist_ttl=300.0,
+)
+
+async with client:
+    response = await client.get("https://api.example.com/data")
+    data = response.json()
+```
+
+### Custom retry policy
+
+```python
+import httpx
+from resilient_httpx import RetryPolicy
+
+policy = RetryPolicy(
+    max_attempts=5,
+    backoff="exponential",       # "exponential" | "fixed" | "random_jitter"
+    min_wait=1.0,
+    max_wait=30.0,
+    retry_on=[429, 500, 502, 503, 504],
+    retry_on_exception=[httpx.TimeoutException, httpx.ConnectError],
+)
+```
+
+### Error handling
+
+```python
+from resilient_httpx import ProxyHttpClient, AllProxiesExhausted, MaxRetriesExceeded
+
+async with ProxyHttpClient(proxies=proxy_list) as client:
+    try:
+        response = await client.get("https://api.example.com/data")
+    except AllProxiesExhausted:
+        ...  # all proxies blacklisted
+    except MaxRetriesExceeded as exc:
+        ...  # retries exhausted, exc.__cause__ has the last error
+```
+
+## Configuration Reference
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `proxies` | `list[str] \| None` | `None` | Proxy URLs |
+| `proxy_strategy` | `str` | `"round-robin"` | `"round-robin"` or `"random"` |
+| `retry` | `RetryPolicy` | `RetryPolicy()` | Retry configuration |
+| `timeout` | `float` | `30.0` | Request timeout in seconds |
+| `headers` | `dict[str, str] \| None` | `None` | Default headers |
+| `blacklist_threshold` | `int` | `3` | Consecutive failures before blacklisting |
+| `blacklist_ttl` | `float` | `300.0` | Blacklist duration in seconds |
+| `fallback_to_direct` | `bool` | `False` | Request without proxy when all are blacklisted |
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Run with coverage:
+
+```bash
+pytest --cov=resilient_httpx --cov-report=term-missing
+```

resilient_httpx-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "resilient-httpx"
+version = "0.1.0"
+description = "Async HTTP client with retry, backoff, and proxy rotation"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "galthran-wq" },
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = [
+    "httpx>=0.28.0",
+    "tenacity>=9.1.0",
+    "structlog>=25.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/galthran-wq/resilient-httpx"
+Repository = "https://github.com/galthran-wq/resilient-httpx"
+Issues = "https://github.com/galthran-wq/resilient-httpx/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-asyncio",
+    "pytest-cov",
+    "respx",
+    "ruff",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/resilient_httpx"]

resilient_httpx-0.1.0/src/resilient_httpx/__init__.py

@@ -0,0 +1,12 @@
+from resilient_httpx.client import ProxyHttpClient
+from resilient_httpx.exceptions import AllProxiesExhausted, MaxRetriesExceeded
+from resilient_httpx.retry import RetryPolicy
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ProxyHttpClient",
+    "RetryPolicy",
+    "AllProxiesExhausted",
+    "MaxRetriesExceeded",
+]

resilient_httpx-0.1.0/src/resilient_httpx/client.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+import httpx
+import structlog
+from tenacity import RetryError
+
+from resilient_httpx.exceptions import AllProxiesExhausted, MaxRetriesExceeded
+from resilient_httpx.pool import ProxyPool
+from resilient_httpx.retry import RetryPolicy
+
+_ALL = "_all"
+_DEFAULT = "_default"
+
+
+class _RetriableStatusError(Exception):
+    def __init__(self, response: httpx.Response) -> None:
+        self.response = response
+        super().__init__(f"HTTP {response.status_code}")
+
+
+class ProxyHttpClient:
+    def __init__(
+        self,
+        proxies: list[str] | dict[str, list[str]] | None = None,
+        proxy_strategy: str = "round-robin",
+        retry: RetryPolicy | None = None,
+        timeout: float = 30.0,
+        headers: dict[str, str] | None = None,
+        blacklist_threshold: int = 3,
+        blacklist_ttl: float = 300.0,
+        fallback_to_direct: bool = False,
+        default_pool: str | None = None,
+    ) -> None:
+        self._strategy = proxy_strategy
+        self._blacklist_threshold = blacklist_threshold
+        self._blacklist_ttl = blacklist_ttl
+        self._pools: dict[str, ProxyPool] = {}
+        self._default_pool_name: str | None = None
+
+        if default_pool is not None and not isinstance(proxies, dict):
+            raise ValueError("default_pool requires proxies to be a dict")
+
+        if isinstance(proxies, list):
+            self._pools[_DEFAULT] = self._make_pool(proxies)
+            self._default_pool_name = _DEFAULT
+        elif isinstance(proxies, dict):
+            reserved = {_ALL, _DEFAULT}
+            overlap = reserved.intersection(proxies)
+            if overlap:
+                raise ValueError(f"Reserved pool name(s): {sorted(overlap)!r}")
+            for name, proxy_list in proxies.items():
+                self._pools[name] = self._make_pool(proxy_list)
+            if default_pool is not None:
+                if default_pool not in self._pools:
+                    raise ValueError(f"Unknown default pool: {default_pool!r}")
+                self._default_pool_name = default_pool
+            else:
+                self._build_combined_pool()
+
+        self._retry = retry or RetryPolicy()
+        self._timeout = timeout
+        self._headers = headers or {}
+        self._fallback = fallback_to_direct
+        self._clients: dict[str | None, httpx.AsyncClient] = {}
+        self._log = structlog.get_logger()
+
+    def _make_pool(
+        self,
+        proxies: list[str],
+        state: dict[str, object] | None = None,
+    ) -> ProxyPool:
+        return ProxyPool(
+            proxies=proxies,
+            strategy=self._strategy,
+            blacklist_threshold=self._blacklist_threshold,
+            blacklist_ttl=self._blacklist_ttl,
+            state=state,
+        )
+
+    def _build_combined_pool(self) -> None:
+        all_proxies = []
+        state = {}
+        for name, pool in self._pools.items():
+            if name != _ALL:
+                for proxy in pool._proxies:
+                    all_proxies.append(proxy)
+                    if proxy not in state:
+                        state[proxy] = pool._state[proxy]
+        if all_proxies:
+            self._pools[_ALL] = self._make_pool(all_proxies, state=state)
+            self._default_pool_name = _ALL
+
+    def add_pool(self, name: str, proxies: list[str]) -> None:
+        if name in (_ALL, _DEFAULT):
+            raise ValueError(f"Reserved pool name: {name!r}")
+        self._pools[name] = self._make_pool(proxies)
+        if self._default_pool_name == _ALL or self._default_pool_name is None:
+            self._build_combined_pool()
+
+    def _resolve_pool(self, pool: str | None) -> ProxyPool | None:
+        if pool is not None:
+            if pool not in self._pools:
+                raise ValueError(f"Unknown pool: {pool!r}")
+            return self._pools[pool]
+        if self._default_pool_name is not None:
+            return self._pools[self._default_pool_name]
+        return None
+
+    def _get_client(self, proxy: str | None) -> httpx.AsyncClient:
+        if proxy not in self._clients:
+            self._clients[proxy] = httpx.AsyncClient(
+                proxy=proxy,
+                timeout=self._timeout,
+                headers=self._headers,
+            )
+        return self._clients[proxy]
+
+    async def _request(
+        self, method: str, url: str, *, pool: str | None = None, **kwargs,
+    ) -> httpx.Response:
+        active_pool = self._resolve_pool(pool)
+        retrying = self._retry.build_retrying(
+            extra_exceptions=[_RetriableStatusError],
+        )
+
+        try:
+            async for attempt in retrying:
+                with attempt:
+                    proxy = None
+                    if active_pool:
+                        proxy = await active_pool.get_proxy()
+                        if proxy is None:
+                            if self._fallback:
+                                self._log.warning(
+                                    "all_proxies_blacklisted",
+                                    fallback="direct",
+                                )
+                            else:
+                                raise AllProxiesExhausted()
+
+                    self._log.debug(
+                        "request_attempt",
+                        method=method,
+                        url=url,
+                        proxy=proxy,
+                        attempt=attempt.retry_state.attempt_number,
+                    )
+
+                    client = self._get_client(proxy)
+                    try:
+                        response = await client.request(method, url, **kwargs)
+                    except tuple(self._retry.retry_on_exception):
+                        if active_pool and proxy:
+                            blacklisted = await active_pool.report_failure(proxy)
+                            if blacklisted:
+                                self._log.warning(
+                                    "proxy_blacklisted", proxy=proxy
+                                )
+                        raise
+
+                    if response.status_code in self._retry.retry_on:
+                        if active_pool and proxy:
+                            blacklisted = await active_pool.report_failure(proxy)
+                            if blacklisted:
+                                self._log.warning(
+                                    "proxy_blacklisted", proxy=proxy
+                                )
+                        raise _RetriableStatusError(response)
+
+                    if active_pool and proxy:
+                        await active_pool.report_success(proxy)
+                    return response
+        except AllProxiesExhausted:
+            self._log.error("all_proxies_exhausted")
+            raise
+        except RetryError as exc:
+            last = exc.last_attempt.exception()
+            self._log.error("max_retries_exceeded", last_error=str(last))
+            raise MaxRetriesExceeded(str(last)) from last
+
+    async def get(self, url: str, *, pool: str | None = None, **kwargs) -> httpx.Response:
+        return await self._request("GET", url, pool=pool, **kwargs)
+
+    async def post(self, url: str, *, pool: str | None = None, **kwargs) -> httpx.Response:
+        return await self._request("POST", url, pool=pool, **kwargs)
+
+    async def put(self, url: str, *, pool: str | None = None, **kwargs) -> httpx.Response:
+        return await self._request("PUT", url, pool=pool, **kwargs)
+
+    async def patch(self, url: str, *, pool: str | None = None, **kwargs) -> httpx.Response:
+        return await self._request("PATCH", url, pool=pool, **kwargs)
+
+    async def delete(self, url: str, *, pool: str | None = None, **kwargs) -> httpx.Response:
+        return await self._request("DELETE", url, pool=pool, **kwargs)
+
+    async def aclose(self) -> None:
+        for client in self._clients.values():
+            await client.aclose()
+        self._clients.clear()
+
+    async def __aenter__(self) -> ProxyHttpClient:
+        return self
+
+    async def __aexit__(self, *args) -> None:
+        await self.aclose()

resilient_httpx-0.1.0/src/resilient_httpx/exceptions.py

@@ -0,0 +1,6 @@
+class AllProxiesExhausted(Exception):
+    pass
+
+
+class MaxRetriesExceeded(Exception):
+    pass

resilient_httpx-0.1.0/src/resilient_httpx/pool.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from dataclasses import dataclass
+
+
+@dataclass
+class _ProxyState:
+    fail_count: int = 0
+    blacklisted_until: float | None = None
+
+
+class ProxyPool:
+    def __init__(
+        self,
+        proxies: list[str],
+        strategy: str = "round-robin",
+        blacklist_threshold: int = 3,
+        blacklist_ttl: float = 300.0,
+        state: dict[str, _ProxyState] | None = None,
+    ) -> None:
+        self._proxies = list(proxies)
+        self._strategy = strategy
+        self._threshold = blacklist_threshold
+        self._ttl = blacklist_ttl
+        existing_state = state or {}
+        self._state = {p: existing_state.get(p, _ProxyState()) for p in self._proxies}
+        self._index = 0
+        self._lock = asyncio.Lock()
+
+    def _is_available(self, proxy: str) -> bool:
+        state = self._state[proxy]
+        if state.blacklisted_until is None:
+            return True
+        if time.monotonic() >= state.blacklisted_until:
+            state.blacklisted_until = None
+            state.fail_count = self._threshold - 1
+            return True
+        return False
+
+    async def get_proxy(self) -> str | None:
+        async with self._lock:
+            available = [p for p in self._proxies if self._is_available(p)]
+            if not available:
+                return None
+
+            if self._strategy == "random":
+                return random.choice(available)
+
+            while True:
+                proxy = self._proxies[self._index % len(self._proxies)]
+                self._index += 1
+                if proxy in available:
+                    return proxy
+
+    async def report_failure(self, proxy: str) -> bool:
+        async with self._lock:
+            state = self._state[proxy]
+            state.fail_count += 1
+            if state.fail_count >= self._threshold:
+                state.blacklisted_until = time.monotonic() + self._ttl
+                return True
+            return False
+
+    async def report_success(self, proxy: str) -> None:
+        async with self._lock:
+            state = self._state[proxy]
+            state.fail_count = 0
+            state.blacklisted_until = None

resilient_httpx-0.1.0/src/resilient_httpx/retry.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import httpx
+from tenacity import (
+    AsyncRetrying,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+    wait_fixed,
+    wait_random,
+)
+
+
+def _default_retry_on_exception() -> list[type[Exception]]:
+    return [httpx.TimeoutException, httpx.ConnectError]
+
+
+@dataclass
+class RetryPolicy:
+    max_attempts: int = 3
+    backoff: str = "exponential"
+    min_wait: float = 1.0
+    max_wait: float = 30.0
+    retry_on: list[int] = field(
+        default_factory=lambda: [429, 500, 502, 503, 504],
+    )
+    retry_on_exception: list[type[Exception]] = field(
+        default_factory=_default_retry_on_exception,
+    )
+
+    def build_retrying(
+        self,
+        extra_exceptions: list[type[Exception]] | None = None,
+    ) -> AsyncRetrying:
+        if self.backoff == "fixed":
+            wait = wait_fixed(self.min_wait)
+        elif self.backoff == "random_jitter":
+            wait = wait_random(min=self.min_wait, max=self.max_wait)
+        else:
+            wait = wait_exponential(min=self.min_wait, max=self.max_wait)
+
+        exceptions = list(self.retry_on_exception)
+        if extra_exceptions:
+            exceptions.extend(extra_exceptions)
+
+        return AsyncRetrying(
+            stop=stop_after_attempt(self.max_attempts),
+            wait=wait,
+            retry=retry_if_exception_type(tuple(exceptions)),
+        )

resilient_httpx-0.1.0/tests/conftest.py

@@ -0,0 +1,10 @@
+import pytest
+
+
+@pytest.fixture
+def proxy_list():
+    return [
+        "http://proxy1:8080",
+        "http://proxy2:8080",
+        "http://proxy3:8080",
+    ]

resilient_httpx-0.1.0/tests/test_client.py

@@ -0,0 +1,154 @@
+from contextlib import contextmanager
+from unittest.mock import AsyncMock, patch
+
+import httpx
+import pytest
+
+from resilient_httpx import (
+    AllProxiesExhausted,
+    MaxRetriesExceeded,
+    ProxyHttpClient,
+    RetryPolicy,
+)
+
+URL = "https://api.example.com/data"
+NO_WAIT = RetryPolicy(min_wait=0, max_wait=0)
+
+
+def _response(status: int = 200, text: str = "ok") -> httpx.Response:
+    return httpx.Response(status, text=text, request=httpx.Request("GET", URL))
+
+
+@contextmanager
+def mock_httpx(side_effect):
+    mock = AsyncMock(side_effect=side_effect)
+    with (
+        patch.object(httpx.AsyncClient, "request", mock),
+        patch.object(httpx.AsyncClient, "aclose", new_callable=AsyncMock),
+    ):
+        yield mock
+
+
+async def test_successful_request_no_proxies():
+    with mock_httpx([_response(200)]) as mock:
+        async with ProxyHttpClient(retry=NO_WAIT) as client:
+            resp = await client.get(URL)
+    assert resp.status_code == 200
+    assert mock.call_count == 1
+
+
+async def test_successful_request_with_proxies(proxy_list):
+    with mock_httpx([_response(200)]):
+        async with ProxyHttpClient(proxies=proxy_list, retry=NO_WAIT) as client:
+            resp = await client.get(URL)
+    assert resp.status_code == 200
+
+
+async def test_retry_on_502():
+    with mock_httpx([_response(502), _response(200)]) as mock:
+        async with ProxyHttpClient(retry=NO_WAIT) as client:
+            resp = await client.get(URL)
+    assert resp.status_code == 200
+    assert mock.call_count == 2
+
+
+async def test_retry_on_429():
+    with mock_httpx([_response(429), _response(429), _response(200)]) as mock:
+        policy = RetryPolicy(max_attempts=5, min_wait=0, max_wait=0)
+        async with ProxyHttpClient(retry=policy) as client:
+            resp = await client.get(URL)
+    assert resp.status_code == 200
+    assert mock.call_count == 3
+
+
+async def test_retry_on_network_exception():
+    side_effect = [httpx.ConnectError("connection refused"), _response(200)]
+    with mock_httpx(side_effect) as mock:
+        async with ProxyHttpClient(retry=NO_WAIT) as client:
+            resp = await client.get(URL)
+    assert resp.status_code == 200
+    assert mock.call_count == 2
+
+
+async def test_max_retries_exceeded():
+    with mock_httpx([_response(502)] * 3):
+        async with ProxyHttpClient(retry=NO_WAIT) as client:
+            with pytest.raises(MaxRetriesExceeded):
+                await client.get(URL)
+
+
+async def test_max_retries_exceeded_has_cause():
+    with mock_httpx([httpx.ConnectError("fail")] * 3):
+        async with ProxyHttpClient(retry=NO_WAIT) as client:
+            with pytest.raises(MaxRetriesExceeded) as exc_info:
+                await client.get(URL)
+    assert isinstance(exc_info.value.__cause__, httpx.ConnectError)
+
+
+async def test_all_proxies_exhausted(proxy_list):
+    responses = [_response(502)] * 4
+    with mock_httpx(responses):
+        policy = RetryPolicy(max_attempts=5, min_wait=0, max_wait=0)
+        async with ProxyHttpClient(
+            proxies=proxy_list,
+            retry=policy,
+            blacklist_threshold=1,
+        ) as client:
+            with pytest.raises(AllProxiesExhausted):
+                await client.get(URL)
+
+
+async def test_all_proxies_exhausted_fallback(proxy_list):
+    responses = [_response(502)] * 3 + [_response(200)]
+    with mock_httpx(responses) as mock:
+        policy = RetryPolicy(max_attempts=5, min_wait=0, max_wait=0)
+        async with ProxyHttpClient(
+            proxies=proxy_list,
+            retry=policy,
+            blacklist_threshold=1,
+            fallback_to_direct=True,
+        ) as client:
+            resp = await client.get(URL)
+    assert resp.status_code == 200
+    assert mock.call_count == 4
+
+
+async def test_proxy_rotation_on_failure(proxy_list):
+    captured_proxies = []
+    original_get_client = ProxyHttpClient._get_client
+
+    def spy_get_client(self, proxy):
+        captured_proxies.append(proxy)
+        return original_get_client(self, proxy)
+
+    with mock_httpx([_response(502), _response(502), _response(200)]):
+        with patch.object(ProxyHttpClient, "_get_client", spy_get_client):
+            async with ProxyHttpClient(proxies=proxy_list, retry=NO_WAIT) as client:
+                await client.get(URL)
+    assert len(captured_proxies) == 3
+    assert captured_proxies[0] != captured_proxies[1]
+
+
+async def test_context_manager_closes_clients():
+    with mock_httpx([_response(200)]):
+        client = ProxyHttpClient(retry=NO_WAIT)
+        async with client:
+            await client.get(URL)
+        assert client._clients == {}
+
+
+async def test_http_methods():
+    for method in ["get", "post", "put", "patch", "delete"]:
+        with mock_httpx([_response(200)]) as mock:
+            async with ProxyHttpClient(retry=NO_WAIT) as client:
+                resp = await getattr(client, method)(URL)
+        assert resp.status_code == 200
+        assert mock.call_args[0][0] == method.upper()
+
+
+async def test_no_retry_on_non_retriable_status():
+    with mock_httpx([_response(400)]) as mock:
+        async with ProxyHttpClient(retry=NO_WAIT) as client:
+            resp = await client.get(URL)
+    assert resp.status_code == 400
+    assert mock.call_count == 1

resilient_httpx-0.1.0/tests/test_named_pools.py

@@ -0,0 +1,119 @@
+from unittest.mock import AsyncMock, patch
+
+import httpx
+import pytest
+
+from resilient_httpx import ProxyHttpClient, RetryPolicy
+
+from .test_client import URL, NO_WAIT, _response, mock_httpx
+
+EXTERNAL = ["http://external1:8080", "http://external2:8080"]
+INTERNAL = ["http://internal1:8080", "http://internal2:8080"]
+
+
+async def test_named_pools_per_request():
+    captured_proxies = []
+    original_get_client = ProxyHttpClient._get_client
+
+    def spy_get_client(self, proxy):
+        captured_proxies.append(proxy)
+        return original_get_client(self, proxy)
+
+    with mock_httpx([_response(200)] * 2):
+        with patch.object(ProxyHttpClient, "_get_client", spy_get_client):
+            async with ProxyHttpClient(
+                proxies={"external": EXTERNAL, "internal": INTERNAL},
+                retry=NO_WAIT,
+            ) as client:
+                await client.get(URL, pool="external")
+                await client.get(URL, pool="internal")
+    assert captured_proxies[0] in EXTERNAL
+    assert captured_proxies[1] in INTERNAL
+
+
+async def test_named_pools_default_combined():
+    captured_proxies = []
+    original_get_client = ProxyHttpClient._get_client
+
+    def spy_get_client(self, proxy):
+        captured_proxies.append(proxy)
+        return original_get_client(self, proxy)
+
+    with mock_httpx([_response(200)] * 4):
+        with patch.object(ProxyHttpClient, "_get_client", spy_get_client):
+            async with ProxyHttpClient(
+                proxies={"external": EXTERNAL, "internal": INTERNAL},
+                retry=NO_WAIT,
+            ) as client:
+                for _ in range(4):
+                    await client.get(URL)
+    assert set(captured_proxies) == set(EXTERNAL + INTERNAL)
+
+
+async def test_named_pools_explicit_default():
+    captured_proxies = []
+    original_get_client = ProxyHttpClient._get_client
+
+    def spy_get_client(self, proxy):
+        captured_proxies.append(proxy)
+        return original_get_client(self, proxy)
+
+    with mock_httpx([_response(200)] * 2):
+        with patch.object(ProxyHttpClient, "_get_client", spy_get_client):
+            async with ProxyHttpClient(
+                proxies={"external": EXTERNAL, "internal": INTERNAL},
+                default_pool="internal",
+                retry=NO_WAIT,
+            ) as client:
+                await client.get(URL)
+                await client.get(URL)
+    assert all(p in INTERNAL for p in captured_proxies)
+
+
+async def test_add_pool():
+    extra = ["http://extra1:8080"]
+    captured_proxies = []
+    original_get_client = ProxyHttpClient._get_client
+
+    def spy_get_client(self, proxy):
+        captured_proxies.append(proxy)
+        return original_get_client(self, proxy)
+
+    with mock_httpx([_response(200)]):
+        with patch.object(ProxyHttpClient, "_get_client", spy_get_client):
+            async with ProxyHttpClient(
+                proxies={"external": EXTERNAL},
+                retry=NO_WAIT,
+            ) as client:
+                client.add_pool("extra", extra)
+                await client.get(URL, pool="extra")
+    assert captured_proxies[0] in extra
+
+
+async def test_add_pool_updates_combined_default():
+    extra = ["http://extra1:8080"]
+    client = ProxyHttpClient(
+        proxies={"external": EXTERNAL},
+        retry=NO_WAIT,
+    )
+    client.add_pool("extra", extra)
+    combined = client._pools["_all"]
+    assert "http://extra1:8080" in combined._proxies
+    assert all(p in combined._proxies for p in EXTERNAL)
+
+
+async def test_unknown_pool_raises():
+    async with ProxyHttpClient(
+        proxies={"external": EXTERNAL},
+        retry=NO_WAIT,
+    ) as client:
+        with pytest.raises(ValueError, match="Unknown pool"):
+            await client.get(URL, pool="nonexistent")
+
+
+async def test_unknown_default_pool_raises():
+    with pytest.raises(ValueError, match="Unknown default pool"):
+        ProxyHttpClient(
+            proxies={"external": EXTERNAL},
+            default_pool="nonexistent",
+        )

resilient_httpx-0.1.0/tests/test_pool.py

@@ -0,0 +1,95 @@
+import asyncio
+
+import pytest
+
+from resilient_httpx.pool import ProxyPool
+
+
+@pytest.fixture
+def pool(proxy_list):
+    return ProxyPool(proxies=proxy_list, blacklist_threshold=3, blacklist_ttl=10.0)
+
+
+async def test_round_robin_order(pool, proxy_list):
+    results = [await pool.get_proxy() for _ in range(6)]
+    assert results == proxy_list * 2
+
+
+async def test_random_strategy(proxy_list):
+    pool = ProxyPool(proxies=proxy_list, strategy="random")
+    result = await pool.get_proxy()
+    assert result in proxy_list
+
+
+async def test_blacklist_after_threshold(pool):
+    for _ in range(3):
+        await pool.report_failure("http://proxy1:8080")
+    result = await pool.get_proxy()
+    assert result == "http://proxy2:8080"
+
+
+async def test_report_failure_returns_blacklisted_flag(pool):
+    assert await pool.report_failure("http://proxy1:8080") is False
+    assert await pool.report_failure("http://proxy1:8080") is False
+    assert await pool.report_failure("http://proxy1:8080") is True
+
+
+async def test_all_blacklisted_returns_none(pool):
+    for proxy in ["http://proxy1:8080", "http://proxy2:8080", "http://proxy3:8080"]:
+        for _ in range(3):
+            await pool.report_failure(proxy)
+    assert await pool.get_proxy() is None
+
+
+async def test_ttl_recovery(proxy_list):
+    pool = ProxyPool(
+        proxies=proxy_list, blacklist_threshold=2, blacklist_ttl=0.1,
+    )
+    for _ in range(2):
+        await pool.report_failure("http://proxy1:8080")
+
+    assert await pool.get_proxy() == "http://proxy2:8080"
+
+    await _sleep(0.15)
+
+    results = [await pool.get_proxy() for _ in range(3)]
+    assert "http://proxy1:8080" in results
+
+
+async def test_lowered_priority_after_recovery(proxy_list):
+    pool = ProxyPool(
+        proxies=proxy_list, blacklist_threshold=3, blacklist_ttl=0.1,
+    )
+    for _ in range(3):
+        await pool.report_failure("http://proxy1:8080")
+
+    await _sleep(0.15)
+
+    await pool.get_proxy()
+    state = pool._state["http://proxy1:8080"]
+    assert state.fail_count == 2
+
+
+async def test_report_success_resets(pool):
+    await pool.report_failure("http://proxy1:8080")
+    await pool.report_failure("http://proxy1:8080")
+    await pool.report_success("http://proxy1:8080")
+    state = pool._state["http://proxy1:8080"]
+    assert state.fail_count == 0
+    assert state.blacklisted_until is None
+
+
+async def test_round_robin_skips_blacklisted(pool):
+    for _ in range(3):
+        await pool.report_failure("http://proxy2:8080")
+    results = [await pool.get_proxy() for _ in range(4)]
+    assert results == [
+        "http://proxy1:8080",
+        "http://proxy3:8080",
+        "http://proxy1:8080",
+        "http://proxy3:8080",
+    ]
+
+
+async def _sleep(seconds: float) -> None:
+    await asyncio.sleep(seconds)

resilient_httpx-0.1.0/tests/test_retry.py

@@ -0,0 +1,46 @@
+import httpx
+from tenacity import wait_exponential, wait_fixed, wait_random
+
+from resilient_httpx.retry import RetryPolicy
+
+
+def test_defaults():
+    policy = RetryPolicy()
+    assert policy.max_attempts == 3
+    assert policy.backoff == "exponential"
+    assert policy.min_wait == 1.0
+    assert policy.max_wait == 30.0
+    assert policy.retry_on == [429, 500, 502, 503, 504]
+    assert httpx.TimeoutException in policy.retry_on_exception
+    assert httpx.ConnectError in policy.retry_on_exception
+
+
+def test_build_retrying_exponential():
+    retrying = RetryPolicy(backoff="exponential", min_wait=2.0, max_wait=60.0).build_retrying()
+    assert isinstance(retrying.wait, wait_exponential)
+
+
+def test_build_retrying_fixed():
+    retrying = RetryPolicy(backoff="fixed", min_wait=5.0).build_retrying()
+    assert isinstance(retrying.wait, wait_fixed)
+
+
+def test_build_retrying_random_jitter():
+    retrying = RetryPolicy(backoff="random_jitter").build_retrying()
+    assert isinstance(retrying.wait, wait_random)
+
+
+def test_build_retrying_stop_after_attempts():
+    retrying = RetryPolicy(max_attempts=7).build_retrying()
+    assert retrying.stop.max_attempt_number == 7
+
+
+def test_build_retrying_extra_exceptions():
+    class CustomError(Exception):
+        pass
+
+    retrying = RetryPolicy().build_retrying(extra_exceptions=[CustomError])
+    retry_check = retrying.retry
+    assert hasattr(retry_check, "exception_types")
+    assert CustomError in retry_check.exception_types
+    assert httpx.TimeoutException in retry_check.exception_types