crashbytes-resilience 1.0.0__tar.gz

crashbytes_resilience-1.0.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @CrashBytes

crashbytes_resilience-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check src/ tests/
+      - run: mypy --strict src/
+      - run: pytest --cov=crashbytes_resilience --cov-branch --cov-fail-under=90

crashbytes_resilience-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

crashbytes_resilience-1.0.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.pyo
+dist/
+build/
+*.egg-info/
+.coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+

crashbytes_resilience-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CrashBytes
+
+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.

crashbytes_resilience-1.0.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: crashbytes-resilience
+Version: 1.0.0
+Summary: Unified resilience patterns — retry, circuit breaker, rate limiter, timeout, bulkhead, fallback.
+Project-URL: Homepage, https://github.com/CrashBytes/crashbytes-resilience
+Project-URL: Repository, https://github.com/CrashBytes/crashbytes-resilience
+Project-URL: Issues, https://github.com/CrashBytes/crashbytes-resilience/issues
+Author-email: CrashBytes <crashbytes@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bulkhead,circuit-breaker,rate-limiter,resilience,retry,timeout
+Classifier: Development Status :: 5 - Production/Stable
+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: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# crashbytes-resilience
+
+Unified resilience patterns for Python — retry, circuit breaker, rate limiter, timeout, bulkhead, fallback. Zero dependencies. Sync + async. Thread-safe.
+
+## Install
+
+```bash
+pip install crashbytes-resilience
+```
+
+## Usage
+
+```python
+from crashbytes_resilience import retry, circuit_breaker, timeout, fallback, pipeline
+
+@retry(max_attempts=3, delay=0.5, backoff=2.0)
+def fetch_data():
+    ...
+
+@circuit_breaker(failure_threshold=5, recovery_timeout=30)
+def call_service():
+    ...
+
+@timeout(5.0)
+async def slow_operation():
+    ...
+
+@fallback(lambda: {"cached": True})
+def get_config():
+    ...
+
+# Compose patterns
+@pipeline(retry(max_attempts=3, delay=0.1), timeout(5.0), fallback(lambda: None))
+def resilient_call():
+    ...
+```
+
+## Patterns
+
+| Decorator | Description |
+|-----------|-------------|
+| `@retry()` | Retry with exponential backoff |
+| `@circuit_breaker()` | Stop calling failing services |
+| `@rate_limiter()` | Token-bucket rate limiting |
+| `@timeout()` | Time-limit operations |
+| `@bulkhead()` | Limit concurrent executions |
+| `@fallback()` | Provide fallback on failure |
+| `@pipeline()` | Compose multiple patterns |
+
+All patterns work with both sync and async functions.
+
+## License
+
+MIT

crashbytes_resilience-1.0.0/README.md

@@ -0,0 +1,54 @@
+# crashbytes-resilience
+
+Unified resilience patterns for Python — retry, circuit breaker, rate limiter, timeout, bulkhead, fallback. Zero dependencies. Sync + async. Thread-safe.
+
+## Install
+
+```bash
+pip install crashbytes-resilience
+```
+
+## Usage
+
+```python
+from crashbytes_resilience import retry, circuit_breaker, timeout, fallback, pipeline
+
+@retry(max_attempts=3, delay=0.5, backoff=2.0)
+def fetch_data():
+    ...
+
+@circuit_breaker(failure_threshold=5, recovery_timeout=30)
+def call_service():
+    ...
+
+@timeout(5.0)
+async def slow_operation():
+    ...
+
+@fallback(lambda: {"cached": True})
+def get_config():
+    ...
+
+# Compose patterns
+@pipeline(retry(max_attempts=3, delay=0.1), timeout(5.0), fallback(lambda: None))
+def resilient_call():
+    ...
+```
+
+## Patterns
+
+| Decorator | Description |
+|-----------|-------------|
+| `@retry()` | Retry with exponential backoff |
+| `@circuit_breaker()` | Stop calling failing services |
+| `@rate_limiter()` | Token-bucket rate limiting |
+| `@timeout()` | Time-limit operations |
+| `@bulkhead()` | Limit concurrent executions |
+| `@fallback()` | Provide fallback on failure |
+| `@pipeline()` | Compose multiple patterns |
+
+All patterns work with both sync and async functions.
+
+## License
+
+MIT

crashbytes_resilience-1.0.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "crashbytes-resilience"
+version = "1.0.0"
+description = "Unified resilience patterns — retry, circuit breaker, rate limiter, timeout, bulkhead, fallback."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "CrashBytes", email = "crashbytes@users.noreply.github.com" }]
+keywords = ["resilience", "retry", "circuit-breaker", "rate-limiter", "timeout", "bulkhead"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-cov", "pytest-asyncio", "mypy", "ruff"]
+
+[project.urls]
+Homepage = "https://github.com/CrashBytes/crashbytes-resilience"
+Repository = "https://github.com/CrashBytes/crashbytes-resilience"
+Issues = "https://github.com/CrashBytes/crashbytes-resilience/issues"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "SIM", "TCH"]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.coverage.run]
+branch = true
+source = ["crashbytes_resilience"]
+
+[tool.coverage.report]
+fail_under = 90

crashbytes_resilience-1.0.0/src/crashbytes_resilience/__init__.py

@@ -0,0 +1,35 @@
+"""crashbytes-resilience — Unified resilience patterns for Python."""
+
+from crashbytes_resilience._core import (
+    BulkheadFullError,
+    CircuitBreaker,
+    CircuitOpenError,
+    RateLimiter,
+    ResilienceError,
+    RetriesExhaustedError,
+    TimeoutExceededError,
+    bulkhead,
+    circuit_breaker,
+    fallback,
+    pipeline,
+    rate_limiter,
+    retry,
+    timeout,
+)
+
+__all__ = [
+    "BulkheadFullError",
+    "CircuitBreaker",
+    "CircuitOpenError",
+    "RateLimiter",
+    "ResilienceError",
+    "RetriesExhaustedError",
+    "TimeoutExceededError",
+    "bulkhead",
+    "circuit_breaker",
+    "fallback",
+    "pipeline",
+    "rate_limiter",
+    "retry",
+    "timeout",
+]

crashbytes_resilience-1.0.0/src/crashbytes_resilience/_core.py

@@ -0,0 +1,381 @@
+"""Unified resilience patterns for Python."""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import inspect
+import threading
+import time
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+# ── Exceptions ──────────────────────────────────────────────────────
+
+
+class ResilienceError(Exception):
+    """Base for all resilience errors."""
+
+
+class CircuitOpenError(ResilienceError):
+    """Raised when the circuit breaker is open."""
+
+
+class BulkheadFullError(ResilienceError):
+    """Raised when the bulkhead is at capacity."""
+
+
+class TimeoutExceededError(ResilienceError):
+    """Raised when an operation exceeds its timeout."""
+
+
+class RetriesExhaustedError(ResilienceError):
+    """Raised when all retry attempts fail."""
+
+    def __init__(self, last_exception: Exception) -> None:
+        self.last_exception = last_exception
+        super().__init__(f"All retries exhausted. Last error: {last_exception}")
+
+
+# ── Retry ───────────────────────────────────────────────────────────
+
+
+def retry(
+    max_attempts: int = 3,
+    delay: float = 0.1,
+    backoff: float = 2.0,
+    exceptions: tuple[type[Exception], ...] = (Exception,),
+) -> Any:
+    """Decorator: retry on failure with exponential backoff.
+
+    Works with both sync and async functions.
+    """
+
+    def decorator(fn: Any) -> Any:
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                current_delay = delay
+                last_exc: Exception | None = None
+                for attempt in range(max_attempts):
+                    try:
+                        return await fn(*args, **kwargs)
+                    except exceptions as exc:
+                        last_exc = exc
+                        if attempt < max_attempts - 1:
+                            await asyncio.sleep(current_delay)
+                            current_delay *= backoff
+                assert last_exc is not None
+                raise RetriesExhaustedError(last_exc)
+
+            return async_wrapper
+
+        @functools.wraps(fn)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            current_delay = delay
+            last_exc: Exception | None = None
+            for attempt in range(max_attempts):
+                try:
+                    return fn(*args, **kwargs)
+                except exceptions as exc:
+                    last_exc = exc
+                    if attempt < max_attempts - 1:
+                        time.sleep(current_delay)
+                        current_delay *= backoff
+            assert last_exc is not None
+            raise RetriesExhaustedError(last_exc)
+
+        return sync_wrapper
+
+    return decorator
+
+
+# ── Circuit Breaker ─────────────────────────────────────────────────
+
+
+class CircuitBreaker:
+    """Thread-safe circuit breaker.
+
+    States: CLOSED -> OPEN -> HALF_OPEN -> CLOSED (or back to OPEN).
+    """
+
+    CLOSED = "closed"
+    OPEN = "open"
+    HALF_OPEN = "half_open"
+
+    def __init__(
+        self,
+        failure_threshold: int = 5,
+        recovery_timeout: float = 30.0,
+        exceptions: tuple[type[Exception], ...] = (Exception,),
+    ) -> None:
+        self._failure_threshold = failure_threshold
+        self._recovery_timeout = recovery_timeout
+        self._exceptions = exceptions
+        self._state = self.CLOSED
+        self._failure_count = 0
+        self._last_failure_time = 0.0
+        self._lock = threading.Lock()
+
+    @property
+    def state(self) -> str:
+        with self._lock:
+            if (
+                self._state == self.OPEN
+                and time.monotonic() - self._last_failure_time >= self._recovery_timeout
+            ):
+                self._state = self.HALF_OPEN
+            return self._state
+
+    def _record_success(self) -> None:
+        with self._lock:
+            self._failure_count = 0
+            self._state = self.CLOSED
+
+    def _record_failure(self) -> None:
+        with self._lock:
+            self._failure_count += 1
+            self._last_failure_time = time.monotonic()
+            if self._failure_count >= self._failure_threshold:
+                self._state = self.OPEN
+
+    def __call__(self, fn: Any) -> Any:
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                if self.state == self.OPEN:
+                    raise CircuitOpenError("Circuit breaker is open")
+                try:
+                    result = await fn(*args, **kwargs)
+                except self._exceptions:
+                    self._record_failure()
+                    raise
+                self._record_success()
+                return result
+
+            return async_wrapper
+
+        @functools.wraps(fn)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            if self.state == self.OPEN:
+                raise CircuitOpenError("Circuit breaker is open")
+            try:
+                result = fn(*args, **kwargs)
+            except self._exceptions:
+                self._record_failure()
+                raise
+            self._record_success()
+            return result
+
+        return sync_wrapper
+
+
+def circuit_breaker(
+    failure_threshold: int = 5,
+    recovery_timeout: float = 30.0,
+    exceptions: tuple[type[Exception], ...] = (Exception,),
+) -> CircuitBreaker:
+    """Create a circuit breaker decorator."""
+    return CircuitBreaker(failure_threshold, recovery_timeout, exceptions)
+
+
+# ── Rate Limiter ────────────────────────────────────────────────────
+
+
+class RateLimiter:
+    """Thread-safe token-bucket rate limiter."""
+
+    def __init__(self, max_calls: int, period: float = 1.0) -> None:
+        self._max_calls = max_calls
+        self._period = period
+        self._tokens = float(max_calls)
+        self._last_refill = time.monotonic()
+        self._lock = threading.Lock()
+
+    def _refill(self) -> None:
+        now = time.monotonic()
+        elapsed = now - self._last_refill
+        refill = self._tokens + elapsed * self._max_calls / self._period
+        self._tokens = min(self._max_calls, refill)
+        self._last_refill = now
+
+    def acquire(self) -> bool:
+        """Try to acquire a token. Returns True if allowed."""
+        with self._lock:
+            self._refill()
+            if self._tokens >= 1.0:
+                self._tokens -= 1.0
+                return True
+            return False
+
+    def __call__(self, fn: Any) -> Any:
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                if not self.acquire():
+                    raise ResilienceError("Rate limit exceeded")
+                return await fn(*args, **kwargs)
+
+            return async_wrapper
+
+        @functools.wraps(fn)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            if not self.acquire():
+                raise ResilienceError("Rate limit exceeded")
+            return fn(*args, **kwargs)
+
+        return sync_wrapper
+
+
+def rate_limiter(max_calls: int, period: float = 1.0) -> RateLimiter:
+    """Create a rate limiter decorator."""
+    return RateLimiter(max_calls, period)
+
+
+# ── Timeout ─────────────────────────────────────────────────────────
+
+
+def timeout(seconds: float) -> Any:
+    """Decorator: raise TimeoutError_ if the function exceeds *seconds*.
+
+    For async functions, uses asyncio.wait_for.
+    For sync functions, uses threading.
+    """
+
+    def decorator(fn: Any) -> Any:
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                try:
+                    return await asyncio.wait_for(fn(*args, **kwargs), timeout=seconds)
+                except asyncio.TimeoutError:
+                    raise TimeoutExceededError(f"Operation timed out after {seconds}s") from None
+
+            return async_wrapper
+
+        @functools.wraps(fn)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            result_container: list[Any] = []
+            exc_container: list[Exception] = []
+
+            def target() -> None:
+                try:
+                    result_container.append(fn(*args, **kwargs))
+                except Exception as e:
+                    exc_container.append(e)
+
+            thread = threading.Thread(target=target)
+            thread.start()
+            thread.join(timeout=seconds)
+            if thread.is_alive():
+                raise TimeoutExceededError(f"Operation timed out after {seconds}s")
+            if exc_container:
+                raise exc_container[0]
+            return result_container[0]
+
+        return sync_wrapper
+
+    return decorator
+
+
+# ── Bulkhead ────────────────────────────────────────────────────────
+
+
+def bulkhead(max_concurrent: int) -> Any:
+    """Decorator: limit concurrent executions.
+
+    Uses threading.Semaphore for sync, asyncio.Semaphore for async.
+    """
+    sync_sem = threading.Semaphore(max_concurrent)
+    async_sem: asyncio.Semaphore | None = None
+
+    def decorator(fn: Any) -> Any:
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                nonlocal async_sem
+                if async_sem is None:
+                    async_sem = asyncio.Semaphore(max_concurrent)
+                acquired = async_sem._value > 0  # noqa: SLF001
+                if not acquired:
+                    raise BulkheadFullError(
+                        f"Bulkhead full (max {max_concurrent} concurrent)"
+                    )
+                async with async_sem:
+                    return await fn(*args, **kwargs)
+
+            return async_wrapper
+
+        @functools.wraps(fn)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            acquired = sync_sem.acquire(blocking=False)
+            if not acquired:
+                raise BulkheadFullError(
+                    f"Bulkhead full (max {max_concurrent} concurrent)"
+                )
+            try:
+                return fn(*args, **kwargs)
+            finally:
+                sync_sem.release()
+
+        return sync_wrapper
+
+    return decorator
+
+
+# ── Fallback ────────────────────────────────────────────────────────
+
+
+def fallback(fallback_fn: Any) -> Any:
+    """Decorator: call *fallback_fn* if the wrapped function raises."""
+
+    def decorator(fn: Any) -> Any:
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                try:
+                    return await fn(*args, **kwargs)
+                except Exception:
+                    if inspect.iscoroutinefunction(fallback_fn):
+                        return await fallback_fn(*args, **kwargs)
+                    return fallback_fn(*args, **kwargs)
+
+            return async_wrapper
+
+        @functools.wraps(fn)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return fn(*args, **kwargs)
+            except Exception:
+                return fallback_fn(*args, **kwargs)
+
+        return sync_wrapper
+
+    return decorator
+
+
+# ── Pipeline ────────────────────────────────────────────────────────
+
+
+def pipeline(*decorators: Any) -> Any:
+    """Compose multiple resilience decorators into a single decorator.
+
+    Applied inside-out: ``pipeline(retry(), circuit_breaker())`` means
+    the circuit breaker wraps the retry which wraps the function.
+    """
+
+    def decorator(fn: Any) -> Any:
+        result = fn
+        for dec in decorators:
+            result = dec(result)
+        return result
+
+    return decorator

crashbytes_resilience-1.0.0/tests/test_resilience.py

@@ -0,0 +1,390 @@
+"""Tests for crashbytes-resilience."""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import threading
+import time
+from typing import Any
+
+import pytest
+
+from crashbytes_resilience import (
+    BulkheadFullError,
+    CircuitBreaker,
+    CircuitOpenError,
+    RateLimiter,
+    ResilienceError,
+    RetriesExhaustedError,
+    TimeoutExceededError,
+    bulkhead,
+    circuit_breaker,
+    fallback,
+    pipeline,
+    rate_limiter,
+    retry,
+    timeout,
+)
+
+# ── Retry ───────────────────────────────────────────────────────────
+
+
+class TestRetry:
+    def test_succeeds_first_try(self) -> None:
+        @retry(max_attempts=3, delay=0)
+        def succeed() -> str:
+            return "ok"
+
+        assert succeed() == "ok"
+
+    def test_retries_then_succeeds(self) -> None:
+        call_count = 0
+
+        @retry(max_attempts=3, delay=0)
+        def flaky() -> str:
+            nonlocal call_count
+            call_count += 1
+            if call_count < 3:
+                raise ValueError("fail")
+            return "ok"
+
+        assert flaky() == "ok"
+        assert call_count == 3
+
+    def test_exhausted(self) -> None:
+        @retry(max_attempts=2, delay=0)
+        def always_fail() -> None:
+            raise ValueError("nope")
+
+        with pytest.raises(RetriesExhaustedError, match="nope"):
+            always_fail()
+
+    def test_specific_exceptions(self) -> None:
+        @retry(max_attempts=3, delay=0, exceptions=(ValueError,))
+        def raise_type() -> None:
+            raise TypeError("wrong")
+
+        with pytest.raises(TypeError):
+            raise_type()
+
+    def test_backoff_delay(self) -> None:
+        times: list[float] = []
+
+        @retry(max_attempts=3, delay=0.05, backoff=2.0)
+        def track_time() -> None:
+            times.append(time.monotonic())
+            raise ValueError("fail")
+
+        with pytest.raises(RetriesExhaustedError):
+            track_time()
+
+        assert len(times) == 3
+        # First delay ~0.05s, second ~0.1s
+        assert times[1] - times[0] >= 0.04
+        assert times[2] - times[1] >= 0.08
+
+
+class TestRetryAsync:
+    async def test_async_retry(self) -> None:
+        call_count = 0
+
+        @retry(max_attempts=3, delay=0)
+        async def flaky() -> str:
+            nonlocal call_count
+            call_count += 1
+            if call_count < 2:
+                raise ValueError("fail")
+            return "ok"
+
+        result = await flaky()
+        assert result == "ok"
+        assert call_count == 2
+
+    async def test_async_exhausted(self) -> None:
+        @retry(max_attempts=2, delay=0)
+        async def always_fail() -> None:
+            raise ValueError("nope")
+
+        with pytest.raises(RetriesExhaustedError):
+            await always_fail()
+
+
+# ── Circuit Breaker ─────────────────────────────────────────────────
+
+
+class TestCircuitBreaker:
+    def test_closes_on_success(self) -> None:
+        cb = circuit_breaker(failure_threshold=3)
+
+        @cb
+        def success() -> str:
+            return "ok"
+
+        assert success() == "ok"
+        assert cb.state == CircuitBreaker.CLOSED
+
+    def test_opens_after_threshold(self) -> None:
+        cb = circuit_breaker(failure_threshold=2, recovery_timeout=10)
+
+        @cb
+        def fail() -> None:
+            raise ValueError("fail")
+
+        for _ in range(2):
+            with pytest.raises(ValueError):
+                fail()
+
+        assert cb.state == CircuitBreaker.OPEN
+
+        with pytest.raises(CircuitOpenError):
+            fail()
+
+    def test_half_open_recovery(self) -> None:
+        cb = circuit_breaker(failure_threshold=1, recovery_timeout=0.05)
+
+        call_count = 0
+
+        @cb
+        def flaky() -> str:
+            nonlocal call_count
+            call_count += 1
+            if call_count == 1:
+                raise ValueError("fail")
+            return "ok"
+
+        with pytest.raises(ValueError):
+            flaky()
+
+        assert cb.state == CircuitBreaker.OPEN
+        time.sleep(0.06)
+        assert cb.state == CircuitBreaker.HALF_OPEN
+
+        assert flaky() == "ok"
+        assert cb.state == CircuitBreaker.CLOSED
+
+    async def test_async_circuit_breaker(self) -> None:
+        cb = circuit_breaker(failure_threshold=1)
+
+        @cb
+        async def fail() -> None:
+            raise ValueError("fail")
+
+        with pytest.raises(ValueError):
+            await fail()
+
+        with pytest.raises(CircuitOpenError):
+            await fail()
+
+
+# ── Rate Limiter ────────────────────────────────────────────────────
+
+
+class TestRateLimiter:
+    def test_allows_within_limit(self) -> None:
+        rl = rate_limiter(max_calls=5, period=1.0)
+
+        @rl
+        def call() -> str:
+            return "ok"
+
+        for _ in range(5):
+            assert call() == "ok"
+
+    def test_blocks_over_limit(self) -> None:
+        rl = rate_limiter(max_calls=2, period=10.0)
+
+        @rl
+        def call() -> str:
+            return "ok"
+
+        call()
+        call()
+        with pytest.raises(ResilienceError, match="Rate limit"):
+            call()
+
+    def test_acquire_method(self) -> None:
+        rl = RateLimiter(max_calls=1, period=10.0)
+        assert rl.acquire() is True
+        assert rl.acquire() is False
+
+    async def test_async_rate_limiter(self) -> None:
+        rl = rate_limiter(max_calls=1, period=10.0)
+
+        @rl
+        async def call() -> str:
+            return "ok"
+
+        assert await call() == "ok"
+        with pytest.raises(ResilienceError):
+            await call()
+
+
+# ── Timeout ─────────────────────────────────────────────────────────
+
+
+class TestTimeout:
+    def test_within_timeout(self) -> None:
+        @timeout(1.0)
+        def fast() -> str:
+            return "ok"
+
+        assert fast() == "ok"
+
+    def test_exceeds_timeout(self) -> None:
+        @timeout(0.05)
+        def slow() -> str:
+            time.sleep(1.0)
+            return "ok"
+
+        with pytest.raises(TimeoutExceededError):
+            slow()
+
+    def test_propagates_exception(self) -> None:
+        @timeout(1.0)
+        def fail() -> None:
+            raise ValueError("inner")
+
+        with pytest.raises(ValueError, match="inner"):
+            fail()
+
+    async def test_async_timeout(self) -> None:
+        @timeout(1.0)
+        async def fast() -> str:
+            return "ok"
+
+        assert await fast() == "ok"
+
+    async def test_async_exceeds_timeout(self) -> None:
+        @timeout(0.05)
+        async def slow() -> str:
+            await asyncio.sleep(1.0)
+            return "ok"
+
+        with pytest.raises(TimeoutExceededError):
+            await slow()
+
+
+# ── Bulkhead ────────────────────────────────────────────────────────
+
+
+class TestBulkhead:
+    def test_allows_within_limit(self) -> None:
+        @bulkhead(max_concurrent=2)
+        def call() -> str:
+            return "ok"
+
+        assert call() == "ok"
+
+    def test_blocks_over_limit(self) -> None:
+        barrier = threading.Barrier(2)
+
+        @bulkhead(max_concurrent=1)
+        def call() -> str:
+            barrier.wait(timeout=1)
+            return "ok"
+
+        errors: list[Exception] = []
+        results: list[str] = []
+
+        def run() -> None:
+            try:
+                results.append(call())
+            except BulkheadFullError as e:
+                errors.append(e)
+
+        t1 = threading.Thread(target=run)
+        t2 = threading.Thread(target=run)
+        t1.start()
+        time.sleep(0.02)  # Let t1 acquire the semaphore
+        t2.start()
+        t1.join(timeout=2)
+        t2.join(timeout=2)
+
+        assert len(errors) == 1
+
+    async def test_async_bulkhead(self) -> None:
+        @bulkhead(max_concurrent=2)
+        async def call() -> str:
+            return "ok"
+
+        assert await call() == "ok"
+
+
+# ── Fallback ────────────────────────────────────────────────────────
+
+
+class TestFallback:
+    def test_no_fallback_on_success(self) -> None:
+        @fallback(lambda: "fallback")
+        def call() -> str:
+            return "ok"
+
+        assert call() == "ok"
+
+    def test_fallback_on_failure(self) -> None:
+        @fallback(lambda: "fallback")
+        def call() -> str:
+            raise ValueError("fail")
+
+        assert call() == "fallback"
+
+    async def test_async_fallback(self) -> None:
+        @fallback(lambda: "fallback")
+        async def call() -> str:
+            raise ValueError("fail")
+
+        assert await call() == "fallback"
+
+    async def test_async_fallback_fn(self) -> None:
+        async def fb() -> str:
+            return "async fallback"
+
+        @fallback(fb)
+        async def call() -> str:
+            raise ValueError("fail")
+
+        assert await call() == "async fallback"
+
+
+# ── Pipeline ────────────────────────────────────────────────────────
+
+
+class TestPipeline:
+    def test_compose_retry_and_fallback(self) -> None:
+        call_count = 0
+
+        @pipeline(retry(max_attempts=2, delay=0), fallback(lambda: "fallback"))
+        def call() -> str:
+            nonlocal call_count
+            call_count += 1
+            raise ValueError("fail")
+
+        result = call()
+        assert result == "fallback"
+        assert call_count == 2
+
+    def test_compose_order(self) -> None:
+        order: list[str] = []
+
+        def deco_a(fn: Any) -> Any:
+            @functools.wraps(fn)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                order.append("a")
+                return fn(*args, **kwargs)
+            return wrapper
+
+        def deco_b(fn: Any) -> Any:
+            @functools.wraps(fn)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                order.append("b")
+                return fn(*args, **kwargs)
+            return wrapper
+
+        @pipeline(deco_a, deco_b)
+        def call() -> str:
+            return "ok"
+
+        call()
+        # deco_b wraps deco_a wraps fn → b runs first, then a
+        assert order == ["b", "a"]