resilience-kit 0.1.0rc1__tar.gz

resilience_kit-0.1.0rc1/.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+pip-wheel-metadata/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Tooling caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.tox/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.hypothesis/
+
+# uv / poetry
+.uv/
+poetry.lock
+
+# IDE / editor
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Local secrets
+.env
+.env.*
+!.env.example
+
+# Build artefacts
+*.log
+
+# Local Claude Code rules — project-private
+CLAUDE.md
+.claude/
+
+# Personal blog drafts — never committed; live local only
+docs/blog/

resilience_kit-0.1.0rc1/CHANGELOG.md

@@ -0,0 +1,101 @@
+# Changelog
+
+All notable changes to `resilience-kit` are documented here. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0rc1] - 2026-06-10
+
+First public release candidate. Cut to PyPI as a packaging smoke-test before the M7 boilerplate migration. Pre-release per [PEP 440](https://peps.python.org/pep-0440/) — `pip` will not install it without an explicit version pin or `--pre`. The 0.1.0 final ships at M8b after both boilerplates depend on the kit.
+
+### Added
+
+- Top-level re-exports of `http_status_for` and `HTTP_STATUS_MAP` (the LLD §11 exception↔HTTP mapping). Adapters and callers no longer need to reach into `resilience_kit.exceptions` for the locked-contract status table.
+
+<!-- m5-placeholder: feat/m5-fastapi-adapter replaces this line -->
+- M5: FastAPI adapter (`resilience_kit.adapters.fastapi`).
+  - `resilience_lifespan(inner=None)` — factory returning a FastAPI lifespan that starts `recovery.monitor` on enter and drains the audit dispatcher + stops the monitor on exit. Composes with an optional inner lifespan.
+  - `install_health_routes(app)` — mounts `GET /healthz` (always 200) and `GET /readyz` (reads `health_snapshot`, propagates 200 / 503). Excluded from the OpenAPI schema.
+  - `install_exception_handlers(app)` — maps every `ResilienceKitError` to the LLD §11 envelope via `exceptions.http_status_for`; `RateLimitError` gets a dedicated handler so the 429 response carries `Retry-After` + `X-RateLimit-*` headers without an extra branch.
+  - `install_middleware_stack(app, **opts)` — mounts the kit's six ASGI middleware in the LLD §11 outer→inner order. `SelectiveCorsMiddleware` is only added when both `cors_allow_origins` and `cors_path_prefixes` are passed so apps that handle CORS upstream are never double-wrapped.
+  - `rate_limit(scope, rate, *, attr_from_request=None)` — FastAPI dependency factory backed by `throttle.provider.get_throttle`. Parses the rate spec once at build time; raises `RateLimitError` on deny.
+  - `request_id_dep()` — returns the active `request_id` ContextVar.
+  - `EncryptedString` — SQLAlchemy 2.x `TypeDecorator[str]` over `FernetCipher`; `cache_ok = True`. None passes through.
+  - `[fastapi]` extra now pulls `sqlalchemy>=2.0` and `httpx>=0.27,<0.29` so a single `pip install resilience-kit[fastapi]` wires the whole adapter.
+  - `tests/integration/fastapi_app/` — minimal example + e2e suite against `testcontainers[postgresql]`. Asserts the M5 exit gate: health routes serve 200, 3rd `/limited` returns 429 with `Retry-After`, `EncryptedString` round-trips (Fernet token on disk, plaintext through the ORM), `AsyncAPIClient` reaches a fake upstream via injected transport.
+  - ADR 0010 (FastAPI adapter shape).
+<!-- m6-placeholder: feat/m6-django-adapter replaces this line -->
+- M6: Django adapter (`resilience_kit.adapters.django`).
+  - `ResilienceConfig` AppConfig — reads `settings.RESILIENCE['services']`, registers each per-service override, and spawns a daemon thread that owns a private asyncio loop driving `recovery.monitor` for the worker lifetime. atexit hook drains the audit dispatcher + stops the monitor on graceful exit. Idempotent across Django's autoreloader.
+  - Six middleware classes mirroring the kit's ASGI stack — `RequestIdMiddleware`, `BodyLimitMiddleware`, `SecurityHeadersMiddleware`, `SelectiveCorsMiddleware`, `RateLimitHeadersMiddleware`, `ExceptionLoggingMiddleware`. Both `sync_capable` + `async_capable`; the last two implement `process_exception` so view-raised kit errors are caught regardless of WSGI / ASGI mode.
+  - Five DRF throttle classes — `IPThrottle`, `UserTierThrottle`, `EndpointThrottle`, `BurstThrottle`, `AuthThrottle`. Subclass `BaseThrottle`, derive scope-specific keys via `throttle.scopes.build_key`, delegate to `throttle.provider.get_throttle()`. Rates resolve from `RESILIENCE_THROTTLE_RATES` (Django setting), with per-scope defaults. Deny raises `RateLimitError` so the response carries the LLD §11 envelope + the canonical `X-RateLimit-*` headers rather than DRF's `Throttled` shape.
+  - `handle(exc, context)` DRF exception handler — install via `REST_FRAMEWORK['EXCEPTION_HANDLER']`. Maps every `ResilienceKitError` through `exceptions.http_status_for`; non-kit exceptions fall through to DRF's default handler.
+  - `EncryptedCharField` — Django model field mirroring the FastAPI adapter's `EncryptedString`. `get_prep_value` + `from_db_value` over `FernetCipher`. Default `max_length=512`. `None` passes through.
+  - Management commands — `resilience_status` (with `--json`) prints overall + per-backend + per-service breaker state; `resilience_reset <service|--all>` force-closes breakers.
+  - `tests/integration/django_app/` — minimal Django + DRF project + e2e suite against `testcontainers postgres:16`. Asserts the M6 exit gate: middleware echoes X-Request-Id + X-Content-Type-Options; IPThrottle('2/min') denies the 3rd request with the LLD §11 envelope + Retry-After + X-RateLimit-Limit=2; EncryptedCharField round-trips (Fernet token on disk, plaintext through the ORM); management commands run.
+  - `[dependency-groups] test-integration` gains `pytest-django` + `psycopg[binary]`.
+  - `docs/sync-vs-async.md` + ADR 0011 (Django sync/async bridge).
+
+- M4: Audit + middleware + metrics + entry-point wiring.
+  - `resilience_kit.dispatch.fire_and_forget` — shared bounded queue + background worker + graceful drain. Drop-newest (default) / drop-oldest overflow with `dispatch.dropped` metric. Worker spawned in `contextvars.copy_context()` to isolate per-request pins.
+  - `resilience_kit.health.health_snapshot()` — `/readyz` aggregator that walks `recovery.registered_backends()`, runs `health_check()` in parallel with per-probe timeout, and reduces to `ok` / `degraded_but_serving` / `degraded` with the matching Kubernetes-style HTTP status.
+  - `resilience_kit.metrics.get_metrics()` — settings-driven sink factory. Builtins `noop` and `stdlib_logging` published as entry points; unknown sink names log a warning and fall back to no-op so observability misconfiguration cannot crash the kit.
+  - `resilience_kit.audit` — full subsystem: `AuditEvent` (LLD §7 shape), `AuditBackend` protocol, `NoopAuditBackend` + `StdlibLoggingAuditBackend` builtins, `PostgresAuditBackend` (asyncpg + batched executemany; extra `[audit-postgres]`). `Sanitizer` protocol + `DefaultRedactor` deep-walking dicts/lists. `FireAndForgetDispatcher` (LLD §7: bounded queue + batched flush + backend retry x3 + stdlib_logging fallback) and `InlineDispatcher` (tests). `@log_inbound` / `@log_outbound` decorators capturing timing, outcome, error class+code, and ContextVar request_id / correlation_id; optional `payload_factory` extracts the audit payload from call args.
+  - `resilience_kit.middleware` — framework-agnostic ASGI middleware: `RequestIdMiddleware` (seeds + echoes request_id / correlation_id), `BodyLimitMiddleware` (413 on oversize Content-Length or streamed body), `SecurityHeadersMiddleware` (conservative default header set + overrides/extras), `SelectiveCorsMiddleware` (CORS only on configured path prefixes), `RateLimitHeadersMiddleware` (catches `RateLimitError` → canonical 429 + `X-RateLimit-*`), `ExceptionLoggingMiddleware` (maps every kit exception onto its locked LLD §11 HTTP status + `{error_code,message,details}` envelope; non-kit raises become a generic 500 with no stack leakage).
+  - `resilience_kit.tasks` — in-process fire-and-forget task queue on top of `dispatch.fire_and_forget`. `register(name)` decorator + `submit(name, *args, **kwargs)` API; missing handler raises at submit time, handler failures are logged + metered via `tasks.failed` without breaking the worker.
+  - `AsyncAPIClient` now routes its default `on_outbound` audit through `audit.get_dispatcher()` — caller-supplied callbacks still win.
+  - Entry-point discovery: every kit-shipped builtin is also published under the kit's groups (`resilience_kit.{cache,breaker,throttle,audit,metrics}_*`) so the provider chain has one shape end-to-end. `tests/fixtures/fake_third_party/` proves the chain via `tests/contract/test_provider_chain.py` (installs the fixture with `uv pip install -e`, asserts `_providers.resolve_provider` finds it).
+  - `tests/integration/test_audit_postgres.py` — testcontainers Postgres + `@log_outbound` lands a sanitized row in `resilience_kit_audit`. `tests/integration/test_readyz_degraded.py` — paused redis container → `health_snapshot()` reports non-OK.
+  - Top-level re-exports: `log_inbound`, `log_outbound`, `AuditEvent`, `health_snapshot`, `HealthAggregate`, `HealthStatus`.
+  - `testing.reset_all_singletons` now clears the audit dispatcher, tasks queue, and tasks-handler registry so pytest-asyncio per-test loops don't bind queues to closed loops.
+  - ADRs: 0005 (fire-and-forget audit), 0009 (entry-point precedence chain).
+
+- M3: HTTP client + SSRF + crypto.
+  - `resilience_kit.ssrf` — `resolve_and_validate(url, strict=)`, `assert_public_url`, `assert_allowed_url`. Rejects non-http(s), private / loopback / link-local / multicast / reserved / unspecified addresses; allow-list supports exact host and `.suffix` matching.
+  - `resilience_kit.http_client` — `AsyncAPIClient(service)` composes `resolve_and_validate → assert_allowed_url → pinned(host→ips) → @resilient(service) → httpx.AsyncClient.request → map_httpx_errors → on_outbound audit hook` (LLD §5). Verb shortcuts (`get` / `post` / `put` / `patch` / `delete`). Sync mirror `request_sync` drives a private event loop only when no loop is running; raises `RuntimeError` from inside a running loop.
+  - `PinnedHTTPTransport` — `httpx.AsyncHTTPTransport` subclass that reads `pinned_dns` ContextVar and rewrites the request URL host to the pinned IP, preserving `Host` header + TLS SNI for cert verification.
+  - `pinned(host_to_ips)` context manager — token-restoring ContextVar set/reset; isolates DNS pins per asyncio task (LLD §9).
+  - Auth helpers — `BearerAuth`, `BasicAuth`, `HMACAuth` (HMAC-SHA256 over `METHOD\nPATH\nTS\nBODY`, with optional `X-Signature-Key-Id`).
+  - `pinned_httpx_client(**kwargs)` and `pinned_requests_session()` factories — extras-gated; raise `MissingExtraError` at import / first call when the optional dep is missing.
+  - `resilience_kit.crypto.FernetCipher.encrypt/decrypt` — SHA-256-of-secret key derivation, `lru_cache(maxsize=1)` instance. `settings.crypto.environment="prod"` refuses to start without `field_encryption_key`; `"dev"` / `"test"` fall back to an insecure-on-purpose constant with a one-time warning. Wrong key / corrupted token raises `DecryptionError`.
+  - `CryptoSettings.environment: Literal["prod","dev","test"]` field on `ResilienceSettings`.
+  - Exit-gate tests: TOCTOU DNS-rebinding under `tests/integration/test_dns_rebinding.py`; Fernet round-trip + prod-without-key refusal under `tests/unit/crypto/test_fernet.py`.
+  - Contract suite additions for SSRF allow-list shapes and httpx error mapping.
+  - `resilience_kit.__init__` re-exports `AsyncAPIClient`, `pinned`, `FernetCipher` via lazy `__getattr__` so `import resilience_kit` does not require the `[http]` / `[crypto]` extras.
+  - `.importlinter` extended with the L3 modules; `testing.reset_all_singletons` now clears the Fernet cache.
+  - ADRs: 0007 (DNS pin via ContextVar), 0008 (Fernet env-guard).
+
+- M2: Redis / Valkey + pybreaker backends.
+  - Shared provider-resolution chain (`resilience_kit._providers.resolve_provider`) implementing LLD §3: explicit → importable string → entry point → builtin → `UnknownBackendError` with the list of options.
+  - `PyBreakerAsyncBreaker` — async wrapper over the synchronous `pybreaker` library using `CircuitBreaker.calling()` so the contextmanager protocol lets the breaker observe both sync and async upstreams.
+  - `RedisAsyncBreaker` — Redis/Valkey-backed breaker with an atomic Lua state machine (CLOSED ↔ OPEN ↔ HALF_OPEN in one EVALSHA). Fail-open delegation to `InMemoryAsyncBreaker` on any Redis error, self-registers with the recovery monitor, `NoScriptError` triggers script reload.
+  - `RedisAsyncThrottle` — sliding-window Lua + in-call recovery probe (30 s gate so quiet workers don't keep PINGing). Fail-open to memory throttle.
+  - `RedisAsyncCache` — plain Redis ops, fail-open for everything except `incr` (which raises rather than diverge on the authoritative counter).
+  - `RecoveryMonitor` singleton — settings-driven probe interval (default 10 s production, tunable to 0.2 s in tests), warm hooks fire after any backend recovers, graceful start/stop from adapters.
+  - `MissingExtraError` raised at module-import time for every backend gated behind a pip extra. The error message carries the exact `pip install` hint.
+  - `auto` backend picker — chooses `redis` when `RESILIENCE_REDIS_URL` is set + the extra is importable, else `memory`.
+  - Contract suite parametrized over `memory + pybreaker + redis` with testcontainers-backed Redis. Backend-N/A combinations (e.g. FakeClock + Redis TTL) skip cleanly.
+  - Integration test proving the ROADMAP M2 exit gate: paused container → fail-open → unpause → recovery in < 5 s.
+
+### Fixed
+
+- `reset_settings_cache` now restores the default `EnvSettingsSource` so tests that swap in a `FixedSource` don't leak it into following tests.
+
+- M1: core primitives, in-memory only.
+  - Public decorators: `@retry`, `@retry_on_failure(name)`, `@circuit_breaker(name)`, `@resilient(name)` — sync + async, breaker-outer / retry-inner composition.
+  - Per-service `ResilienceRegistry` with defaults overlay and cached breaker instances.
+  - Exception hierarchy with stable `error_code` and structured `details`: `TransientError`, `ExternalTimeoutError`, `ExternalServiceError`, `ServiceUnavailableError`, `RepositoryError`, `DecryptionError`, `MissingExtraError`, `UnknownBackendError`, `ValidationError`, `RateLimitError` (with `response_headers()`).
+  - `ResilienceSettings` (pydantic v2) loaded from env via `RESILIENCE_*`, plus pluggable `SettingsSource` indirection.
+  - `request_id` / `correlation_id` ContextVars (LLD §9).
+  - Protocols: `AsyncBreaker`, `AsyncThrottle`, `AsyncCache`, `MetricsSink`, `Clock`, `SettingsSource` (LLD §2, locked at v0.1).
+  - In-memory backends for breaker (state machine with fake-clock support), throttle (sliding-window deque), cache (TTL + lazy eviction, atomic `incr`).
+  - Throttle scope keys: `IP`, `ENDPOINT`, `USER_TIER`, `GLOBAL`, `BURST`, `AUTH`; `Rate.parse("60/min")` parser.
+  - `MetricsSink` protocol with `NoopMetricsSink` (default) and `StdlibLoggingMetricsSink`.
+  - Decorrelated-jitter, exponential, and constant backoff strategies; jitter selectable via settings.
+  - Testing helpers: `FakeClock`, `FakeAuditSink`, `reset_all_singletons`.
+  - Contract test suite parametrized over backends — currently `memory` only; M2 wires `redis` and `pybreaker`.
+  - Activated full layered-architecture contract in `.importlinter`.
+- M0: repo scaffold — `pyproject.toml` with extras matrix, source layout with `py.typed`, ruff + mypy + import-linter + pydocstyle + darglint configs, pre-commit, GitHub Actions CI (lint / types / imports / tests on Python 3.11–3.13), CodeQL workflow, PR template, CODEOWNERS, dependabot, issue templates, smoke test.
+
+[Unreleased]: https://github.com/prajwalmahajan101/resilience-kit/compare/v0.1.0rc1...HEAD
+[0.1.0rc1]: https://github.com/prajwalmahajan101/resilience-kit/releases/tag/v0.1.0rc1

resilience_kit-0.1.0rc1/LICENSE

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

resilience_kit-0.1.0rc1/PKG-INFO

@@ -0,0 +1,429 @@
+Metadata-Version: 2.4
+Name: resilience-kit
+Version: 0.1.0rc1
+Summary: Framework-agnostic Python resilience + core-infrastructure kernel — retries, circuit breakers, throttles, cache, SSRF guard, DNS-pinned HTTP client, audit decorators, field crypto. Pluggable backends. Adapters for Django + FastAPI.
+Project-URL: Homepage, https://github.com/prajwalmahajan101/resilience-kit
+Project-URL: Documentation, https://github.com/prajwalmahajan101/resilience-kit/tree/main/docs
+Project-URL: Repository, https://github.com/prajwalmahajan101/resilience-kit
+Project-URL: Issues, https://github.com/prajwalmahajan101/resilience-kit/issues
+Project-URL: Changelog, https://github.com/prajwalmahajan101/resilience-kit/blob/main/CHANGELOG.md
+Author: Prajwal Mahajan
+License: MIT License
+        
+        Copyright (c) 2026 Prajwal Mahajan
+        
+        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.
+License-File: LICENSE
+Keywords: circuit-breaker,django,fastapi,rate-limit,resilience,retry,ssrf,throttle
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pybreaker>=1.2
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: pydantic>=2.6
+Provides-Extra: all
+Requires-Dist: asyncpg>=0.29; extra == 'all'
+Requires-Dist: cryptography>=42.0; extra == 'all'
+Requires-Dist: django<7,>=4.2; extra == 'all'
+Requires-Dist: djangorestframework>=3.14; extra == 'all'
+Requires-Dist: fastapi>=0.110; extra == 'all'
+Requires-Dist: httpx<0.29,>=0.27; extra == 'all'
+Requires-Dist: redis>=5.0; extra == 'all'
+Requires-Dist: requests>=2.31; extra == 'all'
+Requires-Dist: sqlalchemy>=2.0; extra == 'all'
+Requires-Dist: starlette>=0.36; extra == 'all'
+Provides-Extra: audit-postgres
+Requires-Dist: asyncpg>=0.29; extra == 'audit-postgres'
+Provides-Extra: crypto
+Requires-Dist: cryptography>=42.0; extra == 'crypto'
+Provides-Extra: django
+Requires-Dist: django<7,>=4.2; extra == 'django'
+Requires-Dist: djangorestframework>=3.14; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == 'fastapi'
+Requires-Dist: httpx<0.29,>=0.27; extra == 'fastapi'
+Requires-Dist: sqlalchemy>=2.0; extra == 'fastapi'
+Requires-Dist: starlette>=0.36; extra == 'fastapi'
+Provides-Extra: http
+Requires-Dist: httpx<0.29,>=0.27; extra == 'http'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Provides-Extra: requests
+Requires-Dist: requests>=2.31; extra == 'requests'
+Description-Content-Type: text/markdown
+
+# resilience-kit
+
+> Framework-agnostic Python resilience + core-infrastructure kernel.
+> Retries, circuit breakers, throttles, cache, SSRF guard, DNS-pinned HTTP client, audit decorators, field crypto — one package, pluggable backends, two thin adapters for Django and FastAPI.
+
+[![PyPI](https://img.shields.io/pypi/v/resilience-kit.svg)](https://pypi.org/project/resilience-kit/)
+[![Python](https://img.shields.io/pypi/pyversions/resilience-kit.svg)](https://pypi.org/project/resilience-kit/)
+[![CI](https://github.com/prajwalmahajan101/resilience-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/prajwalmahajan101/resilience-kit/actions)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+> **Status:** v0.1 — pre-release. **M0–M3 merged** (scaffold · in-memory primitives · Redis/pybreaker backends · HTTP client + SSRF + crypto); latest dev checkpoint is [`milestone/m3`](https://github.com/prajwalmahajan101/resilience-kit/tree/milestone/m3). M4–M8 outstanding; no PyPI release yet — the first installable version will be `v0.1.0` (see [Tagging convention](./docs/ROADMAP.md#tagging-convention)). Design is locked across four docs:
+>
+> | Doc | What it answers |
+> |---|---|
+> | [PRD.md](./docs/PRD.md) | What's in/out of scope, why, who it's for |
+> | [ROADMAP.md](./docs/ROADMAP.md) | Feature-level breakdown per milestone (M0–M8) with exit gates |
+> | [LLD.md](./docs/LLD.md) | Protocols, sequence diagrams, concurrency model, settings schema |
+> | [DIRECTORY-TREE.md](./docs/DIRECTORY-TREE.md) | Every file with arrival milestone and required extra |
+>
+> APIs marked *locked* in PRD §5.4 and LLD §2 will not break before 1.0.
+
+---
+
+## Why
+
+`django_boilerplate` and `fastapi_boilerplate` were shipping the **same** resilience kernel against two web frameworks — retry, circuit breaker, Valkey-backed throttles, SSRF guard, DNS-pinned HTTP client, Fernet field crypto, `@log_inbound` / `@log_outbound` audit decorators — and it had already drifted. This package extracts the kernel **once**, makes every backend swappable, and ships thin adapters for both frameworks.
+
+You probably want this if you've ever:
+
+- Copy-pasted `retry` / `circuit_breaker` decorators between two services.
+- Hand-rolled SSRF protection and then wondered if it survives DNS rebinding (it usually doesn't).
+- Wrapped `redis-py` in a degrades-to-memory shim for the third time.
+- Reached for `tenacity` and `pybreaker` and a custom Lua script and a sanitizer and a `ContextVar` request-id — all to add resilience to one outbound HTTP call.
+
+---
+
+## Install
+
+```bash
+pip install resilience-kit                        # core: pure-python, no I/O deps
+pip install "resilience-kit[fastapi,redis,http]"  # FastAPI app on Valkey
+pip install "resilience-kit[django,redis,http]"   # Django app on Valkey
+pip install "resilience-kit[all]"                 # everything
+```
+
+### Available extras
+
+| Extra | Enables |
+|---|---|
+| *(none)* | retry, in-memory breaker/throttle/cache, ssrf guard, audit decorators (noop sink), middleware factories, metrics shim, tasks queue, testing helpers |
+| `[redis]` | Valkey / Redis backends for breaker, throttle, cache |
+| `[pybreaker]` | `pybreaker` backend for the circuit breaker |
+| `[http]` | DNS-pinned `AsyncAPIClient` (httpx) |
+| `[requests]` | `pinned_requests_session()` |
+| `[crypto]` | `FernetCipher` for field-level encryption |
+| `[audit-postgres]` | Postgres audit-log backend |
+| `[django]` | Django + DRF adapter |
+| `[fastapi]` | FastAPI + Starlette adapter |
+| `[all]` | everything above |
+| `[dev]` | tooling: testcontainers, pytest-asyncio, mypy, ruff |
+
+Importing a backend whose extra isn't installed raises `MissingExtraError("install resilience-kit[redis]")` at import time — no confusing `ModuleNotFoundError` deep in a stack trace.
+
+---
+
+## Quickstart — the one decorator you'll use the most
+
+```python
+from resilience_kit import resilient
+
+@resilient("partner_api")          # circuit breaker (outer) + retry (inner)
+async def get_balance(account_id: str) -> Decimal:
+    response = await http_client.get(f"/accounts/{account_id}/balance")
+    return Decimal(response.json()["balance"])
+```
+
+That's it. Defaults from settings: 3 retries with exponential backoff + jitter, breaker opens after 5 failures, half-opens after 30s. Per-service overrides:
+
+```python
+from resilience_kit import registry
+
+registry.register_service("partner_api", {
+    "retry":           {"max_attempts": 5, "wait_min": 2, "wait_max": 30},
+    "circuit_breaker": {"fail_max": 3,     "reset_timeout": 60},
+})
+```
+
+---
+
+## FastAPI
+
+```python
+from fastapi import FastAPI, Depends
+from resilience_kit.adapters.fastapi import lifespan, rate_limit, exception_handlers
+
+app = FastAPI(lifespan=lifespan)
+exception_handlers.install(app)
+
+@app.get("/accounts/{id}", dependencies=[Depends(rate_limit("ip", "60/min"))])
+async def read_account(id: str):
+    ...
+```
+
+- `lifespan` starts the recovery monitor and mounts `/readyz`.
+- `rate_limit(scope, rate)` is a FastAPI dependency over the kit's throttle.
+- `exception_handlers.install(app)` maps kit exceptions (`ServiceUnavailableError`, `RateLimitError`, …) to JSON responses.
+
+## Django
+
+```python
+# settings.py
+INSTALLED_APPS = [..., "resilience_kit.adapters.django"]
+
+MIDDLEWARE = [
+    "resilience_kit.adapters.django.middleware.RequestIdMiddleware",
+    "resilience_kit.adapters.django.middleware.RateLimitHeadersMiddleware",
+    ...
+]
+
+REST_FRAMEWORK = {
+    "DEFAULT_THROTTLE_CLASSES": [
+        "resilience_kit.adapters.django.drf_throttles.IPThrottle",
+        "resilience_kit.adapters.django.drf_throttles.UserTierThrottle",
+    ],
+    "EXCEPTION_HANDLER": "resilience_kit.adapters.django.exception_handler.handle",
+}
+
+RESILIENCE = {
+    "BACKEND": "redis",
+    "REDIS_URL": env("REDIS_URL"),
+    "CRYPTO": {"FIELD_ENCRYPTION_KEY": env("FIELD_ENCRYPTION_KEY")},
+}
+```
+
+`./manage.py resilience_status` shows per-service breaker state. `./manage.py resilience_reset partner_api` force-closes one.
+
+---
+
+## What's in the box
+
+### Resilience primitives
+
+| Primitive | Sync | Async | Backends |
+|---|---|---|---|
+| `@retry(...)` / `@retry_on_failure(name)` | ✅ | ✅ | n/a (pure logic) |
+| `@circuit_breaker(name)` | ✅ | ✅ | `memory` (default), `pybreaker`, `redis` (atomic Lua) |
+| `@resilient(name)` — breaker ∘ retry | ✅ | ✅ | — |
+| Throttle — `rate_limit(scope, rate)` | ✅ | ✅ | `memory`, `redis` (global Lua) |
+| Cache — `get_cache(alias)` | ✅ | ✅ | `memory` (TTL), `redis` |
+| Recovery monitor — auto re-probe degraded backends | — | ✅ | — |
+
+Scopes: `ip` · `endpoint` · `user_tier` · `global` · `burst` · `auth`. Rate syntax: `"60/min"`, `"10/sec"`, `"1000/hour"`.
+
+### Security
+
+```python
+from resilience_kit.http_client import AsyncAPIClient
+from resilience_kit.crypto import FernetCipher
+
+async with AsyncAPIClient(service="partner_api") as client:
+    # SSRF guard + DNS pin + outbound allow-list + breaker + retry + audit — all composed.
+    data = await client.get("https://partner.example.com/v1/users/42")
+
+token = FernetCipher.encrypt("very secret")
+plaintext = FernetCipher.decrypt(token)
+```
+
+The DNS pin closes the classic validate→connect TOCTOU: the URL is validated *and* the resolved IPs are pinned into the same task-local `ContextVar` that the custom httpx resolver returns at dispatch time. A malicious zone that returns a public IP at validation and a private IP at request time gets blocked.
+
+### Audit — `@log_inbound` / `@log_outbound`
+
+```python
+from resilience_kit.audit import log_outbound
+
+@log_outbound(service="partner_api", redact=["card_number", "cvv"])
+async def charge(card_number: str, cvv: str, amount: Decimal):
+    ...
+```
+
+Pluggable sink: stdlib logging (default), Postgres (`[audit-postgres]`), Django ORM (via the Django adapter), or your own — see *Pluggability* below.
+
+### Framework-agnostic middleware factories
+
+`request_id`, `body_limit`, `security_headers`, `selective_cors`, `rate_limit_headers`, `exception_logging` — exposed as ASGI/WSGI factories. The Django and FastAPI adapters wrap them; you can also mount them directly in any Starlette / WSGI app.
+
+---
+
+## Pluggability
+
+Every swappable subsystem is a `typing.Protocol` plus a provider that resolves implementations from (in order):
+
+1. An explicit callable / instance you pass in.
+2. A `RESILIENCE_<SUBSYSTEM>_BACKEND="myapp.module:MyBackend"` settings string.
+3. An entry point named in your `pyproject.toml`.
+4. A builtin (`memory`, `redis`, …).
+
+Swappable subsystems at v0.1: **cache backend · circuit-breaker backend · throttle backend · audit sink · audit sanitizer · metrics sink · settings source · clock · audit dispatcher**.
+
+### Shipping your own backend
+
+```toml
+# in your own package's pyproject.toml
+[project.entry-points."resilience_kit.cache_backends"]
+memcached = "rk_memcached:MemcachedCache"
+```
+
+```python
+# rk_memcached.py
+from resilience_kit.cache.base import AsyncCache
+
+class MemcachedCache(AsyncCache):
+    async def get(self, key): ...
+    async def set(self, key, value, ttl=None): ...
+    async def incr(self, key, amount=1): ...
+    async def delete(self, key): ...
+    async def health_check(self): ...
+```
+
+```bash
+pip install rk-memcached
+export RESILIENCE_CACHE_BACKEND=memcached
+```
+
+No fork. No monkey-patching. Same `@resilient` decorator everywhere.
+
+---
+
+## Configuration
+
+Single `ResilienceSettings` model (pydantic v2). Resolved through `get_settings()` indirection so callers never import a global. Loaded from env with the `RESILIENCE_` prefix, or from `settings.RESILIENCE` in Django.
+
+| Key | Default | Notes |
+|---|---|---|
+| `backend` | `auto` | `auto` / `redis` / `memory` / `pybreaker` |
+| `redis_url` | `None` | when set, `[redis]` backends become available |
+| `defaults.retry.max_attempts` | `3` | |
+| `defaults.retry.wait_min` / `wait_max` | `1` / `10` | seconds |
+| `defaults.circuit_breaker.fail_max` | `5` | |
+| `defaults.circuit_breaker.reset_timeout` | `30` | seconds |
+| `defaults.circuit_breaker.success_threshold` | `2` | half-open → closed |
+| `defaults.throttle.auth_rate` | `5/min` | applied to `/auth/*` |
+| `ssrf.block_private_ips` | `True` | |
+| `ssrf.outbound_allowlist` | `["*"]` | exact host or `.suffix` |
+| `crypto.field_encryption_key` | `None` | required outside dev/test |
+| `audit.sink` | stdlib logging | importable string, callable, or entry-point name |
+| `audit.redact_fields` | `["password", "token", "secret", "authorization"]` | |
+
+Full pydantic schema in [LLD.md §10](./docs/LLD.md). Settings keys are loaded with the `RESILIENCE_` prefix and `__` nested delimiter (e.g. `RESILIENCE_DEFAULTS__RETRY__MAX_ATTEMPTS=5`).
+
+---
+
+## Exceptions you might catch
+
+```python
+from resilience_kit.exceptions import (
+    TransientError,           # retryable, transport-layer
+    ExternalTimeoutError,     # subtype of TransientError
+    ExternalServiceError,     # upstream returned non-success
+    ServiceUnavailableError,  # breaker is OPEN — adapter maps to 503
+    RateLimitError,           # throttle tripped — adapter maps to 429
+    DecryptionError,          # FernetCipher failed (key rotation?)
+    ValidationError,          # SSRF guard / config-time validation
+)
+```
+
+The Django and FastAPI adapters map these to the right HTTP responses out of the box.
+
+---
+
+## Testing your code that uses the kit
+
+```python
+from resilience_kit.testing import reset_all_singletons, FakeClock, FakeAuditSink
+
+@pytest.fixture(autouse=True)
+async def _reset():
+    await reset_all_singletons()
+```
+
+Integration tests against real backends use `testcontainers-redis`:
+
+```python
+@pytest.mark.integration
+async def test_throttle_under_load(redis_url):
+    settings.RESILIENCE_REDIS_URL = redis_url
+    # ... hammer the throttle, assert exact counts.
+```
+
+---
+
+## Compatibility
+
+- **Python**: 3.11, 3.12, 3.13
+- **Django**: 4.2 LTS, 5.x
+- **FastAPI**: 0.110+ (Starlette 0.36+)
+- **httpx**: `>=0.27, <0.29`
+- **Redis / Valkey**: Redis 7+, Valkey 8+ (verified in CI against both Docker images)
+
+---
+
+## Roadmap
+
+**v0.1** — everything in this README, both adapters, both boilerplates migrated to depend on it. Nine milestones:
+
+| | Milestone | Status |
+|---|---|---|
+| M0 | Repo scaffold | ⬜ pending |
+| M1 | Core primitives, in-memory only | ⬜ pending |
+| M2 | Redis/Valkey + pybreaker backends | ⬜ pending |
+| M3 | HTTP client + SSRF + crypto | ⬜ pending |
+| M4 | Audit + middleware + metrics + entry-point wiring | ⬜ pending |
+| M5 | FastAPI adapter | ⬜ pending |
+| M6 | Django adapter | ⬜ pending |
+| M7 | Boilerplate migrations | ⬜ pending |
+| M8 | v0.1.0 PyPI release | ⬜ pending |
+
+**v0.2+** — Flask adapter · Celery adapter · Litestar adapter · `resilience_kit doctor` CLI · Sphinx site.
+
+Per-milestone feature list and exit gates: [ROADMAP.md](./docs/ROADMAP.md). Final file tree with arrival milestones per file: [DIRECTORY-TREE.md](./docs/DIRECTORY-TREE.md).
+
+---
+
+## Contributing
+
+This is a portfolio project — issues and PRs welcome but I'm the only maintainer. The contract test suite under `tests/contract/` is the source of truth: any new backend must pass it, parametrized in. See [LLD.md §12](./docs/LLD.md) for the test strategy and [DIRECTORY-TREE.md](./docs/DIRECTORY-TREE.md) for where new code lands.
+
+```bash
+uv sync --all-extras --dev
+uv run pytest tests/contract -q              # contract suite, all backends
+uv run pytest tests/integration -q           # adapter + testcontainers
+uv run ruff check . && uv run ruff format --check .
+uv run mypy --strict src
+```
+
+---
+
+## License
+
+MIT. See [LICENSE](./LICENSE).
+
+---
+
+## Related
+
+- [`prajwalmahajan101/fastapi_boilerplate`](https://github.com/prajwalmahajan101/fastapi_boilerplate) — async FastAPI starter, will depend on this kit from its next release.
+- [`prajwalmahajan101/django_boilerplate`](https://github.com/prajwalmahajan101/django_boilerplate) — Django 6 + DRF starter, ditto.
+- Blog: *Circuit-breaker placement is different in async than sync — here's why.* (forthcoming on Hashnode)