From 48a2b11006e685897d5641be21b4a4d009cd7d25 Mon Sep 17 00:00:00 2001 From: agustin18 Date: Sat, 21 Nov 2026 04:33:32 -0300 Subject: [PATCH 01/22] docs(inmemory): distinguish published 0.5.0 from merged read-only 0.6 candidate --- site_docs/guides/inmemory.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/site_docs/guides/inmemory.md b/site_docs/guides/inmemory.md index c2767f19..445afaf8 100644 --- a/site_docs/guides/inmemory.md +++ b/site_docs/guides/inmemory.md @@ -30,7 +30,28 @@ The namespace is scoped under your configured prefix, not a command to clear eve !!! warning "Unbounded dictionary" Published 0.5.0 has **no `max_entries` constructor argument**. Expired entries are removed lazily, which means a stream of never-revisited unique keys can grow memory. For high-cardinality traffic, use Redis and configure capacity appropriately. -[Issue #54](https://github.com/agustin18/fastapi-cache/issues/54) is the separately reviewed proposal for an opt-in capacity limit. Do not pass `max_entries` to your published 0.5.0 application until a newer release explicitly ships it. +[PR #85](https://github.com/agustin18/fastapi-cache/pull/85) is **merged into `stable` but not published**. The following capacity API is **not supported by 0.5.0**. + +## Next-release source: bounded InMemory (not yet published) + +!!! warning "Source-only example, NOT for fastapi-cache-stable==0.5.0" + No 0.6.0 wheel, sdist or tag has been published. Use this example only when independently evaluating a reviewed source checkout or candidate; normal users must stay with the published 0.5.0 snippet above. + +```python +from fastapi_cache import FastAPICache +from fastapi_cache.backends.inmemory import InMemoryBackend + +backend = InMemoryBackend(max_entries=1_000) +FastAPICache.init(backend, prefix="my-app") +``` + +- `max_entries` accepts only a **positive integer** (excluding `bool`) or `None` for historical unbounded mode; invalid capacities raise `ValueError`. +- The limit is **fixed at construction**. `backend.max_entries` is read-only; assigning to it raises `AttributeError`. Dynamic resizing is unsupported. +- At capacity, insertion reclaims **one expired entry first** when possible; otherwise it evicts the least-recently-used entry. Successful reads, including `get_with_ttl`, and writes refresh recency. There is no background sweeper. +- The limit counts **entries in one instance and worker**, not payload bytes, all worker processes or total memory usage. A single entry can be large. +- Ordinary bounded writes use an indexed expiry heap. Explicit namespace clearing may scan all local entries under the async lock; thread/cross-event-loop sharing is not guaranteed. + +For shared multiworker caching, use [Redis](redis.md) with appropriate server-side memory policies. The entry limit is not a privacy, rate-limiting or tenant-isolation guarantee. See [#92 release acceptance](https://github.com/agustin18/fastapi-cache/issues/92). ## Privacy From d80f7519523181a2d9ad074f17b14420e105a98c Mon Sep 17 00:00:00 2001 From: agustin18 Date: Sat, 21 Nov 2026 04:33:42 -0300 Subject: [PATCH 02/22] docs(api): document unreleased immutable max_entries contract separately from 0.5.0 --- site_docs/reference/api.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/site_docs/reference/api.md b/site_docs/reference/api.md index af624fec..8c900bac 100644 --- a/site_docs/reference/api.md +++ b/site_docs/reference/api.md @@ -49,7 +49,7 @@ HTTP `Vary` alone does not partition the library's internal cache. The decorator FastAPICache.init(InMemoryBackend(), prefix="demo") ``` - Per-instance, process-local, **unbounded in published 0.5.0**. The proposed `max_entries` argument in [#54](https://github.com/agustin18/fastapi-cache/issues/54) is **not released**. + Per-instance, process-local, **unbounded in published 0.5.0**. [PR #85](https://github.com/agustin18/fastapi-cache/pull/85) merged a capacity argument into **unreleased `stable` source**, not into the 0.5.0 package. === "Redis standalone" @@ -63,6 +63,21 @@ HTTP `Vary` alone does not partition the library's internal cache. The decorator Close your client in lifespan teardown. Redis Cluster namespace-wide `clear()` is unsupported. +## Next-release source API (not published) + +!!! warning "0.5.0 does not accept this argument" + The following constructor is implemented in `stable` after [PR #85](https://github.com/agustin18/fastapi-cache/pull/85), but is **not part of a published 0.6.0 distribution**. Keep existing `fastapi-cache-stable==0.5.0` installs on their documented unbounded constructor. + +```python +InMemoryBackend(*, max_entries: Optional[int] = None) +``` + +- A **positive integer** caps entry **count per backend instance**. `None` preserves the original unbounded mode; `bool`, zero, negative and non-integer inputs raise `ValueError`. +- `max_entries` is a **read-only property** after construction. Assignments raise `AttributeError`, and dynamic resizing is not supported. +- When full, new keys reclaim one expired entry if available, else evict the least-recently-used entry. The expiry heap does not start a background task. +- This is **not** a byte-memory cap or an aggregate multiworker limit. Explicit namespace clear can still scan the entire local store under the async lock. +- For a source-only example and release requirements see the [InMemory guide](../guides/inmemory.md) and [0.6.0 checklist](https://github.com/agustin18/fastapi-cache/issues/92). + ## Coders - `JsonCoder` is the default and decodes cached JSON into ordinary Python values. From ab8bdb8f63ce3481b20e1a723b31fea01d433647 Mon Sep 17 00:00:00 2001 From: agustin18 Date: Sat, 21 Nov 2026 04:33:50 -0300 Subject: [PATCH 03/22] docs(0.6): keep published feature and merged-source status distinct --- site_docs/reference/features.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site_docs/reference/features.md b/site_docs/reference/features.md index e06b018c..f5ace79d 100644 --- a/site_docs/reference/features.md +++ b/site_docs/reference/features.md @@ -15,7 +15,7 @@ This page describes features in the **published 0.5.0 wheel and sdist**. PRs and | Authorization/Cookie bypass | :material-check-circle: Shipped | Default behavior, not generic custom-auth detection | | `vary_headers` | :material-check-circle: Shipped | Explicit public header variations, no tenant autodetection | | Typed JSON restoration | :material-check-circle: Opt-in | `TypedJsonCoder`, Pydantic v2 profiles | -| InMemory capacity / LRU | :material-clock-outline: In review | [#54](https://github.com/agustin18/fastapi-cache/issues/54), **not in 0.5.0** | +| InMemory capacity / LRU | :material-clock-outline: Merged source, unreleased | [PR #85](https://github.com/agustin18/fastapi-cache/pull/85): immutable per-instance entry-count limit in `stable`, **not in published 0.5.0** | | Cache event callbacks | :material-clock-outline: Proposed | [#50](https://github.com/agustin18/fastapi-cache/issues/50) | | Argument exclusion | :material-clock-outline: Proposed | [#49](https://github.com/agustin18/fastapi-cache/issues/49), privacy design required | | Single-flight / distributed locking | :material-flask-outline: Research | Cancellation, lease and stampede design needed | From f7c2eec23905bb17b4e3e7e3a95d3bf621a3a549 Mon Sep 17 00:00:00 2001 From: agustin18 Date: Sat, 21 Nov 2026 04:33:52 -0300 Subject: [PATCH 04/22] docs(0.6): keep published feature and merged-source status distinct --- site_docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site_docs/index.md b/site_docs/index.md index b2cf6f9e..819b16d5 100644 --- a/site_docs/index.md +++ b/site_docs/index.md @@ -66,7 +66,7 @@ The package name is **`fastapi-cache-stable`**; imports remain **`fastapi_cache` | Included in published 0.5.0 | Future / not shipped | |---|---| -| Default-key-compatible GET/JSON caching | Optional bounded InMemory (#54) | +| Default-key-compatible GET/JSON caching | Bounded InMemory [merged in unreleased source (#85)](https://github.com/agustin18/fastapi-cache/pull/85), **not in 0.5.0** | | Standalone Redis and process-local InMemory | Typed cache lifecycle events (#50) | | Safe default Authorization/Cookie bypass | Arbitrary hidden tenant/context autodetection (#53 residual) | | Opt-in `vary_headers`, ETag and HTTP 304 | Single-flight and tag-based invalidation | From b3f2702200a25e6a131cf53decbf878840319c67 Mon Sep 17 00:00:00 2001 From: agustin18 Date: Sat, 21 Nov 2026 04:33:54 -0300 Subject: [PATCH 05/22] docs(0.6): keep published feature and merged-source status distinct --- site_docs/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site_docs/getting-started.md b/site_docs/getting-started.md index 170537a3..58eefddd 100644 --- a/site_docs/getting-started.md +++ b/site_docs/getting-started.md @@ -84,7 +84,7 @@ The first response has `X-FastAPI-Cache: MISS`; the second identical request wit | Several workers / processes | [RedisBackend](guides/redis.md) | | DynamoDB or Memcached | Experimental: read [compatibility](reference/compatibility.md) first | -The 0.5.0 InMemory backend has **no entry-count limit**. A future, opt-in bounded mode is being reviewed under [#54](https://github.com/agustin18/fastapi-cache/issues/54). +Published 0.5.0 InMemory has **no entry-count limit**. [#85](https://github.com/agustin18/fastapi-cache/pull/85) merged an opt-in fixed-at-construction cap into **unreleased `stable`**. See the [version-separated guide](guides/inmemory.md), but **do not pass `max_entries` with the 0.5.0 install command above**. ## 5. Before production From fdc9810843a6188bf3b302543f41f8b188a04079 Mon Sep 17 00:00:00 2001 From: agustin18 Date: Sat, 21 Nov 2026 04:34:02 -0300 Subject: [PATCH 06/22] docs(0.6): reconcile staging, privacy, backend choice and release provenance --- site_docs/backends.md | 1 + 1 file changed, 1 insertion(+) diff --git a/site_docs/backends.md b/site_docs/backends.md index a7a15eae..35de9563 100644 --- a/site_docs/backends.md +++ b/site_docs/backends.md @@ -9,6 +9,7 @@ Pick based on where your FastAPI workers run. The backend affects operational be | Persistent across worker restart? | No | Redis configuration-dependent | | Production multiworker use | No shared cache | Recommended path | | Published 0.5.0 capacity bound | No | Configure Redis eviction separately | +| Unreleased `stable` source | Optional per-instance fixed `max_entries` from [#85](https://github.com/agustin18/fastapi-cache/pull/85) | Redis memory policies remain separate | | Cache expiry | TTL / optional no-expiry | Redis TTL | | Scoped namespace clearing | Yes | Yes for supported standalone mode | | Recommended for | Dev, tests, single worker | Servers with multiple workers | From 2c25312facee30e088eff1f6bef11aa1cab21939 Mon Sep 17 00:00:00 2001 From: agustin18 Date: Sat, 21 Nov 2026 04:34:05 -0300 Subject: [PATCH 07/22] docs(0.6): reconcile staging, privacy, backend choice and release provenance --- site_docs/reference/alternatives.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site_docs/reference/alternatives.md b/site_docs/reference/alternatives.md index ae500cd3..fee4f412 100644 --- a/site_docs/reference/alternatives.md +++ b/site_docs/reference/alternatives.md @@ -31,7 +31,7 @@ Choosing a library is a question of **migration cost, HTTP semantics, operationa --- - [#54](https://github.com/agustin18/fastapi-cache/issues/54) is reviewing an opt-in, entry-count-limited LRU/TTL backend, with actual full-capacity 10k/100k workload benchmarks. **Not shipped in 0.5.0.** + [PR #85](https://github.com/agustin18/fastapi-cache/pull/85) merged the opt-in entry-count-limited LRU/TTL backend and read-only capacity, with full-capacity 10k/100k CI benchmarks. It is **implemented in unreleased `stable` but not shipped in 0.5.0**. - :material-chart-timeline-variant: **Optional diagnostics** From dbaa17c4f908c578e30dc4ca8c0cc59f458e5879 Mon Sep 17 00:00:00 2001 From: agustin18 Date: Sat, 21 Nov 2026 04:34:07 -0300 Subject: [PATCH 08/22] docs(0.6): reconcile staging, privacy, backend choice and release provenance --- site_docs/guides/privacy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site_docs/guides/privacy.md b/site_docs/guides/privacy.md index df94f702..10508801 100644 --- a/site_docs/guides/privacy.md +++ b/site_docs/guides/privacy.md @@ -48,7 +48,7 @@ async def greeting(): ## Protect against cardinality attacks -A client can send many distinct values and multiply entries. Validate and canonicalize externally supplied values, enforce limits and request rate controls, keep TTLs bounded and use backend capacity controls. The future [bounded InMemory proposal](https://github.com/agustin18/fastapi-cache/issues/54) is not in 0.5.0. +A client can send many distinct values and multiply entries. Validate and canonicalize externally supplied values, enforce limits and request rate controls, keep TTLs bounded and use backend capacity controls. The [bounded InMemory implementation](https://github.com/agustin18/fastapi-cache/pull/85) is merged in **unreleased `stable`** but **not in published 0.5.0**. Its entry-count limit does not replace header normalization, identity-aware cache keys, authorization checks or rate limiting. For private/tenant-sensitive caching, prefer an application-reviewed custom key builder incorporating **validated identity, permissions and all response dimensions**, or bypass caching. From d0285221a4d1a7e410bff6c6a943b50330765858 Mon Sep 17 00:00:00 2001 From: agustin18 Date: Sat, 21 Nov 2026 04:34:10 -0300 Subject: [PATCH 09/22] docs(0.6): reconcile staging, privacy, backend choice and release provenance --- site_docs/reference/releases.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site_docs/reference/releases.md b/site_docs/reference/releases.md index 9c9e3fba..c44c97a6 100644 --- a/site_docs/reference/releases.md +++ b/site_docs/reference/releases.md @@ -1,6 +1,6 @@ # Published releases and evidence -Release tags are immutable reference points. The repository's `stable` branch may contain later documentation or unreleased work. +Release tags are immutable reference points. The repository's `stable` branch may contain later documentation or unreleased work. [#85](https://github.com/agustin18/fastapi-cache/pull/85) merged bounded InMemory into source only; **it is not part of any published 0.5.0 artifact**. See [#92](https://github.com/agustin18/fastapi-cache/issues/92) for 0.6.0 release gates. | Release | Status | Highlights | |---|---|---| From 3090002a23cd3ff87d90532f677fc50b457f4516 Mon Sep 17 00:00:00 2001 From: agustin18 Date: Sat, 21 Nov 2026 04:34:18 -0300 Subject: [PATCH 10/22] docs(roadmap): reflect merged #85, optional #50 deferral and release boundary --- site_docs/roadmap.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/site_docs/roadmap.md b/site_docs/roadmap.md index c52f1993..1b6d3f93 100644 --- a/site_docs/roadmap.md +++ b/site_docs/roadmap.md @@ -1,14 +1,14 @@ # Roadmap: what is next? -**0.5.0 is published.** Proposed 0.6.0 features remain unshipped until separately reviewed and released. This page is an approachable overview, not a release authorization. +**0.5.0 is published.** [#85](https://github.com/agustin18/fastapi-cache/pull/85) is merged in `stable`, but its new API remains **unshipped** until a separately reviewed 0.6.0 artifact exists. This is a roadmap, not release authorization. ## Priorities for 0.6.0 | Priority | Issue | What users gain | Boundary | |---|---|---|---| | P0 when reproducible | [#53 — hidden identity/tenant inputs](https://github.com/agustin18/fastapi-cache/issues/53) | Correct private-response behavior | No promise of generic autodetection | -| P1 / active PR | [#54 — bounded InMemory](https://github.com/agustin18/fastapi-cache/issues/54) | Optional LRU capacity for a single process | No memory-byte or multiworker guarantee | -| P1 / proposed | [#50 — typed events](https://github.com/agustin18/fastapi-cache/issues/50) | Observe HIT/MISS/BYPASS/error safely | Opt-in; no mandatory telemetry | +| P1 / code merged, release pending | [#54 — bounded InMemory](https://github.com/agustin18/fastapi-cache/issues/54) | Optional read-only per-instance `max_entries` with LRU/TTL | **Not in 0.5.0**; no byte or multiworker cap | +| P2 / defer by default | [#50 — typed events](https://github.com/agustin18/fastapi-cache/issues/50) | Optional HIT/MISS/BYPASS/error events | **Not implemented/published**; defer to 0.7.0 unless independently audited before freeze | | Research | Single-flight | Avoid duplicated same-key computations | Needs cancellation/race tests | | Design first | [#49 — parameter exclusion](https://github.com/agustin18/fastapi-cache/issues/49) | Stable keys for irrelevant dependencies | No implicit removal of user/tenant/locale | | Maintenance | [#45 DynamoDB](https://github.com/agustin18/fastapi-cache/issues/45), [#55 FIPS](https://github.com/agustin18/fastapi-cache/issues/55) | Real defect fixes | Isolated from new minor features | From 38c12e0fa3d9519b1ef9806ce463202352f5be32 Mon Sep 17 00:00:00 2001 From: agustin18 Date: Sat, 21 Nov 2026 04:34:26 -0300 Subject: [PATCH 11/22] docs(0.6): distinguish merged source from published quickstart contract --- docs/QUICKSTART.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index 2a61ac78..81955f93 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -92,9 +92,11 @@ authentication or role state safe. See [the privacy guide](../site_docs/guides/privacy.md) and [#53](https://github.com/agustin18/fastapi-cache/issues/53). -Published 0.5.0 InMemory is **unbounded per process**. The separate -[#54 proposal](https://github.com/agustin18/fastapi-cache/issues/54) -adds optional capacity only in a future release if reviewed and shipped. +Published 0.5.0 InMemory is **unbounded per process**. +[PR #85](https://github.com/agustin18/fastapi-cache/pull/85) merged an +optional, fixed-at-construction `max_entries` cap into **unreleased +`stable` source**. It is **not available with the 0.5.0 install pin above**. +Read the [version-separated InMemory guide](../site_docs/guides/inmemory.md). ## Privacy and migration rules From 4d58e8fa9b864c953110ad7d6ae794cd67a456f2 Mon Sep 17 00:00:00 2001 From: agustin18 Date: Sat, 21 Nov 2026 04:34:28 -0300 Subject: [PATCH 12/22] docs(0.6): distinguish merged source from published quickstart contract --- docs/DOCS_SITE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/DOCS_SITE.md b/docs/DOCS_SITE.md index 801037b7..b5495594 100644 --- a/docs/DOCS_SITE.md +++ b/docs/DOCS_SITE.md @@ -29,7 +29,7 @@ Historical releases already remain navigable at [docs/releases](releases/README. ## Authoring contract -- Primary guides describe published behavior. Features from unmerged PRs must be visibly labeled proposed. +- Primary guides describe **published** behavior. Features merged into `stable` but absent from the latest PyPI artifact must be labeled **merged source, not released**, with a distinct next-release section. Features in unmerged PRs stay proposed. - Show the distribution name fastapi-cache-stable, the import fastapi_cache and Python legacy/security support boundaries accurately. - Migration walkthroughs cover uninstalling fastapi-cache2, application lockfiles, tenant safety, targeted namespace cleanup and bounded rollback. - Snippets declare dependencies and are runnable on the named Python/server profiles. From 0d05f32afd2c742b5ccd39de5e98a36d07854e49 Mon Sep 17 00:00:00 2001 From: agustin18 Date: Sat, 21 Nov 2026 04:34:39 -0300 Subject: [PATCH 13/22] docs(readme): report #85 merged but not on PyPI; document immutable opt-in capacity --- README.md | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index c2bd1c6a..737aef43 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ See [compatibility & risk matrix](https://github.com/agustin18/fastapi-cache/blo **Try it:** [one-command before/after migration demo](examples/migration/README.md) (two isolated published environments, no Redis or credentials). -**Published:** [fastapi-cache-stable 0.5.0](https://pypi.org/project/fastapi-cache-stable/0.5.0/). The new searchable site is in [site_docs/](site_docs/index.md) and has a **CI build preview**; it is not claimed to be hosted publicly until a separate deployment is approved. +**Published:** [fastapi-cache-stable 0.5.0](https://pypi.org/project/fastapi-cache-stable/0.5.0/). **Merged source, not yet released:** [#85](https://github.com/agustin18/fastapi-cache/pull/85) adds an opt-in bounded InMemory backend in `stable` for a proposed 0.6.0; it is **not** available with the 0.5.0 install pin. The searchable site is in [site_docs/](site_docs/index.md) with CI preview; it is not confirmed publicly hosted. ## Introduction @@ -550,9 +550,10 @@ all instances/workers and persistent Redis caches. The bypass is not retroactive ### InMemoryBackend -The `InMemoryBackend` stores cache data in memory and only deletes when an -expired key is accessed. This means that if you don't access a function after -data has been cached, the data will not be removed automatically. +**Published 0.5.0** `InMemoryBackend` stores cache data in an +**unbounded** dictionary and removes expired entries lazily when accessed. +Never-revisited keys may accumulate. Do not pass `max_entries` to the +published 0.5.0 distribution. `expire=None` means no expiration. Each backend instance owns its store and lock, so a new instance does not see entries from another instance. Do not share one instance across event @@ -562,6 +563,19 @@ cross-process sharing. `expire=0` keeps the legacy fallback to the global `expir `get_with_ttl` returns `-1` for no-expiration entries; the decorator omits `max-age` for those entries and for `expire=None`. +**Implemented in `stable` for the next release (not in published 0.5.0):** +[PR #85](https://github.com/agustin18/fastapi-cache/pull/85) adds +`InMemoryBackend(max_entries=1_000)`. This positive-integer, opt-in cap +counts **entries per backend instance**, not bytes, processes or all workers; +`None` preserves the unbounded default. `max_entries` is a **read-only +property**, fixed at construction: assignments afterward raise +`AttributeError`. When full, bounded mode evicts the LRU item, reclaiming +an expired item first when available; no background sweeper is started. +Explicit namespace clearing still scans local entries under the async lock. +The next-release API is not an installed feature until a separately reviewed +version ships. See [InMemory version guide](site_docs/guides/inmemory.md) +and [release acceptance #92](https://github.com/agustin18/fastapi-cache/issues/92). + ### RedisBackend When using the Redis backend, please make sure you pass in a redis client that does [_not_ decode responses][redis-decode] (`decode_responses` **must** be `False`, which is the default). Cached data is stored as `bytes` (binary), decoding these in the Redis client would break caching. From e86b2d15fcf1c8d5cf2735eef7fba462bb1ccd1a Mon Sep 17 00:00:00 2001 From: agustin18 Date: Sat, 21 Nov 2026 04:34:50 -0300 Subject: [PATCH 14/22] docs(roadmap): record merged #85 and narrow 0.6.0 acceptance plan --- ROADMAP.md | 58 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 34 insertions(+), 24 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index 4b39ecf9..9eb834ef 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -26,16 +26,22 @@ cache keys and safe default HTTP/private-response behavior. The active [0.6.0 tracker #86](https://github.com/agustin18/fastapi-cache/issues/86) supersedes the **completed** [0.5.0 train #70](https://github.com/agustin18/fastapi-cache/issues/70). -The proposed first feature PR is [#85](https://github.com/agustin18/fastapi-cache/pull/85) -for opt-in bounded InMemory (#54). It is **unmerged** and not available -in the immutable published 0.5.0 wheel. A separate documentation PR -updates the [five-minute quickstart](docs/QUICKSTART.md) and adds -a [navigable site](site_docs/index.md) with CI preview; public hosting -and true versioned deployment remain independent approvals. - -0.6.0 should stay focused on optional bounded InMemory and privacy-safe -observability (#50). Single-flight is **research**, and argument filtering -(#49) requires a separate safety contract before any implementation. +[PR #85](https://github.com/agustin18/fastapi-cache/pull/85) +for opt-in bounded InMemory (#54) **merged into `stable`** at commit +`190d105915972d436ddbf4ad152ad654a4db392a`. Its positive integer +`max_entries` cap is **read-only after construction**, counts entries +per instance (not bytes), and retains the default unbounded behavior. +**Not available in the immutable published 0.5.0 wheel.** +The [quickstart](docs/QUICKSTART.md) and +[navigable site source](site_docs/index.md) describe the published release +separately. Pages activation and versioned historical hosting still need +explicit approval and URL verification. + +0.6.0 should focus on the merged opt-in bounded InMemory feature, +release validation and the remaining #53 privacy/security disposition. +**Defer #50 observability to 0.7.0 by default** unless fully implemented, +audited and explicitly accepted before freeze. Single-flight is +**research**, and #49 argument filtering requires a separate safety contract. Proven #53 privacy defects outrank the feature roadmap. Never inherit 0.5.0's release-specific security acceptance for a different SHA. @@ -46,20 +52,23 @@ Proven #53 privacy defects outrank the feature roadmap. Never inherit **first coordinated public promotion**, not the first PyPI release; published 0.5.0 stays the baseline until a separate reviewed 0.6.0. - [#48](https://github.com/agustin18/fastapi-cache/issues/48): - navigable Zensical docs sources shipped in #87. A separate manual-only - GitHub Pages workflow, tested preview, API reference and comparison guide - are proposed; publication and live URL verification require approval. + navigable Zensical docs shipped in #87 and manual-only GitHub Pages + workflow, API reference and comparison guide merged in #89. Public + activation, stable-only environment restriction and live URL verification + require separate approval. - [Alternatives guide](site_docs/reference/alternatives.md): compare FastAPI-CacheX, Cashews, aiocache and Redis SDK by application fit, not unsupported performance multipliers. **No universal feature parity goal** for 0.6.0. - [Public API guide](site_docs/reference/api.md): - distinguish *published 0.5.0* from opt-in capabilities proposed in #54. -- **Feature freeze:** #54 only after clean base, heap fuzz, full-capacity - 10k/100k LRU/expired-reclaim benchmarks and signed exact-head CI; - #50 only if scoped, opt-in, data-minimizing, and reviewed without delaying - release. #53 residual stays a security review gate; #49, tags, - stampede/locks and other expansions remain separate design/research. + distinguish *published 0.5.0* from merged-but-unreleased + `max_entries` in the next-release source. +- **Feature freeze:** #54/#85 passed independent counteraudit and exact-head + CI before merge; **final 0.6.0 artifacts require new security and + migration evidence**. #50 is deferred to 0.7.0 unless separately approved. + #53 residual remains a security risk-disposition gate; #91 requires two + independent consumers; #92 tracks final candidate checks and manual + release approval. #49, tags and single-flight remain future research. ## Version strategy @@ -67,10 +76,11 @@ Proven #53 privacy defects outrank the feature roadmap. Never inherit `>=3.8,<3.14` metadata and documented Redis client ranges; security maintenance is best-effort on server-side CPython 3.11–3.13. - **0.4.x:** previous published patch line, retained for migration. -- **Future version (separate opt-in features):** argument filtering, - bounded InMemory and privacy-safe cache events are optional. - If they change the public API, prefer a separately reviewed new - minor release (e.g. `0.6.0`) instead of reopening 0.5.0. +- **0.6.0 candidate:** bounded InMemory is merged in source only, not + in the published 0.5.0 distribution. Argument filtering (#49) and + privacy-safe event callbacks (#50) remain separate possible future work. + A new minor release needs a reviewed wheel/sdist, not a retroactive + rewrite of 0.5.0. Keep distributed locking, tag invalidation and app-scoped configurations in research until their concurrency and privacy contracts are tested. - **1.0.0:** not automatically scheduled; current @@ -194,7 +204,7 @@ matrix. None of them reopens the published 0.5.0 signoff. | **P1 — correctness** | [#45](https://github.com/agustin18/fastapi-cache/issues/45) DynamoDB expired-value and client-lifecycle correctness | Experimental backend; needs a real-service reproduction | | **P1 — portability** | [#55](https://github.com/agustin18/fastapi-cache/issues/55) FIPS/restricted-MD5 key compatibility | Preserve legacy digests on non-FIPS profiles | | **P2 — API** | [#49](https://github.com/agustin18/fastapi-cache/issues/49) deterministic argument filtering | Must never silently drop identity or response-defining inputs | -| **P2 — capacity** | [#54](https://github.com/agustin18/fastapi-cache/issues/54) bounded InMemory eviction | Default behavior and compatibility must remain unchanged | +| **Source merged, release pending** | [#54 / #85](https://github.com/agustin18/fastapi-cache/pull/85) bounded InMemory | Read-only cap, default unchanged; **not** in 0.5.0 | | **P2 — observability** | [#50](https://github.com/agustin18/fastapi-cache/issues/50) typed HIT/MISS/BYPASS/STORE/ERROR events | Opt-in, privacy-safe and no mandatory telemetry dependency | | **P3 — compatibility** | [#51](https://github.com/agustin18/fastapi-cache/issues/51) Python 3.14 qualification | Only after a full functional/security matrix passes | | **P3 — documentation** | [#48](https://github.com/agustin18/fastapi-cache/issues/48) versioned documentation site | A separately hosted site is optional; migration guides remain authoritative here | From 5ea4a2d06e4059e8b6f8821cf99ecceae0014c56 Mon Sep 17 00:00:00 2001 From: agustin18 Date: Sat, 21 Nov 2026 04:34:57 -0300 Subject: [PATCH 15/22] docs(compat): separate published InMemory contract from #85 source API --- COMPATIBILITY.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md index 4d2b3be0..c1ac33e8 100644 --- a/COMPATIBILITY.md +++ b/COMPATIBILITY.md @@ -275,6 +275,32 @@ Status definitions: | DynamoDB | Experimental; Python >=3.10 only for target `0.5.0` | `dynamodb` extra requires aiobotocore and aiohttp >=3.14.4; the extra omits those dependencies on Python 3.8/3.9. Unit tests use a fake client; `clear` raises `NotImplementedError`; no real-service integration | | Import `fastapi_cache` | Verified | Covered by compatibility tests | +### Bounded InMemory in unreleased `stable` (not a 0.5.0 guarantee) + +The **published 0.5.0 matrix above remains unchanged**: its InMemory +backend is unbounded. [PR #85](https://github.com/agustin18/fastapi-cache/pull/85) +merged the planned next-release constructor +`InMemoryBackend(max_entries: Optional[int] = None)` into `stable`. +**No 0.6.0 distribution has been published.** + +- `None` retains unbounded legacy behavior. A positive integer caps + **entry count per instance**, not payload bytes or total cache capacity + across processes. `bool`, zero, negative and non-integer values fail + construction validation. +- `max_entries` is a **read-only** property fixed at initialization. + Assignments raise `AttributeError`; dynamic resizing is unsupported. +- At capacity, a new key reclaims one expired key first if available, + otherwise the least-recently-used entry. The indexed TTL heap avoids + a full scan on normal writes. Explicit namespace clearing still scans + stored keys while holding the instance async lock; for N stored entries + and k matches the bound is O(N + k log N). +- There is no background sweeper, bytes-based cap or thread/cross-event-loop + sharing guarantee. Existing cache privacy/tenant boundaries remain + application responsibilities, and the feature cannot be installed with + `fastapi-cache-stable==0.5.0`. +- Verified source and CI checks for #85 do **not** replace the final + package-specific checks in [#92](https://github.com/agustin18/fastapi-cache/issues/92). + > Verified Redis integration covers Redis 7 with redis-py 4.6.0. Other > versions are not verified by that job alone. From f740d8309d470657b08a388739f6f9fdf8fdd13e Mon Sep 17 00:00:00 2001 From: agustin18 Date: Sat, 21 Nov 2026 04:35:08 -0300 Subject: [PATCH 16/22] test(docs): enforce published 0.5.0 vs merged 0.6.0 candidate boundary --- tests/test_060_docs_version_boundary.py | 45 +++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 tests/test_060_docs_version_boundary.py diff --git a/tests/test_060_docs_version_boundary.py b/tests/test_060_docs_version_boundary.py new file mode 100644 index 00000000..7b97df85 --- /dev/null +++ b/tests/test_060_docs_version_boundary.py @@ -0,0 +1,45 @@ +"""Prevent source-only #85 API from being marketed as published 0.5.0.""" + +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] + + +def _read(path: str) -> str: + return (ROOT / path).read_text(encoding="utf-8") + + +def test_published_050_inmemory_remains_documented_as_unbounded() -> None: + guide = _read("site_docs/guides/inmemory.md") + api = _read("site_docs/reference/api.md") + quickstart = _read("docs/QUICKSTART.md") + assert "Published 0.5.0 has **no `max_entries` constructor argument**" in guide + assert "unbounded in published 0.5.0" in api + assert "Published 0.5.0 InMemory is **unbounded per process**" in quickstart + + +def test_merged_source_api_is_labelled_unreleased() -> None: + guide = _read("site_docs/guides/inmemory.md") + api = _read("site_docs/reference/api.md") + matrix = _read("site_docs/reference/features.md") + releases = _read("site_docs/reference/releases.md") + assert "InMemoryBackend(max_entries=1_000)" in guide + assert "read-only" in guide + assert "AttributeError" in guide + assert "not supported by 0.5.0" in guide + assert "max_entries: Optional[int]" in api + assert "not part of a published 0.6.0 distribution" in api + assert "Merged source, unreleased" in matrix + assert "not in published 0.5.0" in matrix + assert "not part of any published 0.5.0 artifact" in releases + + +def test_readme_and_roadmap_do_not_claim_060_was_published() -> None: + readme = _read("README.md") + roadmap = _read("ROADMAP.md") + assert "not available with the 0.5.0 install pin" in readme + assert "read-only" in readme + assert "AttributeError" in readme + assert "not in published 0.5.0" in roadmap.lower() + assert "#50" in roadmap and "0.7.0" in roadmap + assert "190d105915972d436ddbf4ad152ad654a4db392a" in roadmap From f455667dbe8f2cdfd45765086d6ff0d7400ae79f Mon Sep 17 00:00:00 2001 From: agustin18 Date: Sat, 21 Nov 2026 04:35:10 -0300 Subject: [PATCH 17/22] test(docs): enforce published 0.5.0 vs merged 0.6.0 candidate boundary --- changelog.d/92.doc.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/92.doc.md diff --git a/changelog.d/92.doc.md b/changelog.d/92.doc.md new file mode 100644 index 00000000..969805b6 --- /dev/null +++ b/changelog.d/92.doc.md @@ -0,0 +1 @@ +Update documentation after #85: describe the unreleased, opt-in, read-only entry-count InMemory limit separately from the published unbounded 0.5.0 API, with source-vs-artifact assertions and refreshed roadmap/release gates. From c5e3e6efa9e787e622a475b4634ed72f46d676f1 Mon Sep 17 00:00:00 2001 From: agustin18 Date: Sat, 21 Nov 2026 04:35:17 -0300 Subject: [PATCH 18/22] test(docs): match exact published-wheel warning in roadmap --- tests/test_060_docs_version_boundary.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test_060_docs_version_boundary.py b/tests/test_060_docs_version_boundary.py index 7b97df85..e6a981ad 100644 --- a/tests/test_060_docs_version_boundary.py +++ b/tests/test_060_docs_version_boundary.py @@ -40,6 +40,6 @@ def test_readme_and_roadmap_do_not_claim_060_was_published() -> None: assert "not available with the 0.5.0 install pin" in readme assert "read-only" in readme assert "AttributeError" in readme - assert "not in published 0.5.0" in roadmap.lower() + assert "not available in the immutable published 0.5.0 wheel" in roadmap.lower() assert "#50" in roadmap and "0.7.0" in roadmap assert "190d105915972d436ddbf4ad152ad654a4db392a" in roadmap From 7c4b8a8541d53acc0e19d77421740af8b802da16 Mon Sep 17 00:00:00 2001 From: agustin18 Date: Sat, 21 Nov 2026 04:36:15 -0300 Subject: [PATCH 19/22] fix(docs): satisfy Ruff assertion style and exact release wording --- tests/test_060_docs_version_boundary.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tests/test_060_docs_version_boundary.py b/tests/test_060_docs_version_boundary.py index e6a981ad..cbfe25ac 100644 --- a/tests/test_060_docs_version_boundary.py +++ b/tests/test_060_docs_version_boundary.py @@ -41,5 +41,6 @@ def test_readme_and_roadmap_do_not_claim_060_was_published() -> None: assert "read-only" in readme assert "AttributeError" in readme assert "not available in the immutable published 0.5.0 wheel" in roadmap.lower() - assert "#50" in roadmap and "0.7.0" in roadmap + assert "#50" in roadmap + assert "0.7.0" in roadmap assert "190d105915972d436ddbf4ad152ad654a4db392a" in roadmap From 0832013acaf152412c67422759b9b8a7b5220e93 Mon Sep 17 00:00:00 2001 From: agustin18 Date: Sat, 21 Nov 2026 04:36:17 -0300 Subject: [PATCH 20/22] fix(docs): satisfy Ruff assertion style and exact release wording --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 737aef43..69e9c87c 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ See [compatibility & risk matrix](https://github.com/agustin18/fastapi-cache/blo **Try it:** [one-command before/after migration demo](examples/migration/README.md) (two isolated published environments, no Redis or credentials). -**Published:** [fastapi-cache-stable 0.5.0](https://pypi.org/project/fastapi-cache-stable/0.5.0/). **Merged source, not yet released:** [#85](https://github.com/agustin18/fastapi-cache/pull/85) adds an opt-in bounded InMemory backend in `stable` for a proposed 0.6.0; it is **not** available with the 0.5.0 install pin. The searchable site is in [site_docs/](site_docs/index.md) with CI preview; it is not confirmed publicly hosted. +**Published:** [fastapi-cache-stable 0.5.0](https://pypi.org/project/fastapi-cache-stable/0.5.0/). **Merged source, not yet released:** [#85](https://github.com/agustin18/fastapi-cache/pull/85) adds an opt-in bounded InMemory backend in `stable` for a proposed 0.6.0; it is **not available with the 0.5.0 install pin**. The searchable site is in [site_docs/](site_docs/index.md) with CI preview; it is not confirmed publicly hosted. ## Introduction From 4199852aff859e166163bcab92ec9bcf996a9467 Mon Sep 17 00:00:00 2001 From: agustin18 Date: Sat, 21 Nov 2026 04:37:30 -0300 Subject: [PATCH 21/22] docs(features): retain published-0.5.0 wording required by site validation --- site_docs/reference/features.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site_docs/reference/features.md b/site_docs/reference/features.md index f5ace79d..c07d911f 100644 --- a/site_docs/reference/features.md +++ b/site_docs/reference/features.md @@ -15,7 +15,7 @@ This page describes features in the **published 0.5.0 wheel and sdist**. PRs and | Authorization/Cookie bypass | :material-check-circle: Shipped | Default behavior, not generic custom-auth detection | | `vary_headers` | :material-check-circle: Shipped | Explicit public header variations, no tenant autodetection | | Typed JSON restoration | :material-check-circle: Opt-in | `TypedJsonCoder`, Pydantic v2 profiles | -| InMemory capacity / LRU | :material-clock-outline: Merged source, unreleased | [PR #85](https://github.com/agustin18/fastapi-cache/pull/85): immutable per-instance entry-count limit in `stable`, **not in published 0.5.0** | +| InMemory capacity / LRU | :material-clock-outline: Merged source, unreleased | [PR #85](https://github.com/agustin18/fastapi-cache/pull/85): immutable per-instance entry-count limit in `stable`, **not in 0.5.0** (published wheel/sdist) | | Cache event callbacks | :material-clock-outline: Proposed | [#50](https://github.com/agustin18/fastapi-cache/issues/50) | | Argument exclusion | :material-clock-outline: Proposed | [#49](https://github.com/agustin18/fastapi-cache/issues/49), privacy design required | | Single-flight / distributed locking | :material-flask-outline: Research | Cancellation, lease and stampede design needed | From 1aa2b2151eb09f93bae8c7f7b79083e7bc201e64 Mon Sep 17 00:00:00 2001 From: agustin18 Date: Sat, 21 Nov 2026 04:37:32 -0300 Subject: [PATCH 22/22] docs(features): retain published-0.5.0 wording required by site validation --- tests/test_060_docs_version_boundary.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test_060_docs_version_boundary.py b/tests/test_060_docs_version_boundary.py index cbfe25ac..c68d9a2f 100644 --- a/tests/test_060_docs_version_boundary.py +++ b/tests/test_060_docs_version_boundary.py @@ -30,7 +30,7 @@ def test_merged_source_api_is_labelled_unreleased() -> None: assert "max_entries: Optional[int]" in api assert "not part of a published 0.6.0 distribution" in api assert "Merged source, unreleased" in matrix - assert "not in published 0.5.0" in matrix + assert "not in 0.5.0" in matrix assert "not part of any published 0.5.0 artifact" in releases