Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
48a2b11
docs(inmemory): distinguish published 0.5.0 from merged read-only 0.6…
agustin18 Nov 21, 2026
d80f751
docs(api): document unreleased immutable max_entries contract separat…
agustin18 Nov 21, 2026
ab8bdb8
docs(0.6): keep published feature and merged-source status distinct
agustin18 Nov 21, 2026
f7c2eec
docs(0.6): keep published feature and merged-source status distinct
agustin18 Nov 21, 2026
b3f2702
docs(0.6): keep published feature and merged-source status distinct
agustin18 Nov 21, 2026
fdc9810
docs(0.6): reconcile staging, privacy, backend choice and release pro…
agustin18 Nov 21, 2026
2c25312
docs(0.6): reconcile staging, privacy, backend choice and release pro…
agustin18 Nov 21, 2026
dbaa17c
docs(0.6): reconcile staging, privacy, backend choice and release pro…
agustin18 Nov 21, 2026
d028522
docs(0.6): reconcile staging, privacy, backend choice and release pro…
agustin18 Nov 21, 2026
3090002
docs(roadmap): reflect merged #85, optional #50 deferral and release …
agustin18 Nov 21, 2026
38c12e0
docs(0.6): distinguish merged source from published quickstart contract
agustin18 Nov 21, 2026
4d58e8f
docs(0.6): distinguish merged source from published quickstart contract
agustin18 Nov 21, 2026
0d05f32
docs(readme): report #85 merged but not on PyPI; document immutable o…
agustin18 Nov 21, 2026
e86b2d1
docs(roadmap): record merged #85 and narrow 0.6.0 acceptance plan
agustin18 Nov 21, 2026
5ea4a2d
docs(compat): separate published InMemory contract from #85 source API
agustin18 Nov 21, 2026
f740d83
test(docs): enforce published 0.5.0 vs merged 0.6.0 candidate boundary
agustin18 Nov 21, 2026
f455667
test(docs): enforce published 0.5.0 vs merged 0.6.0 candidate boundary
agustin18 Nov 21, 2026
c5e3e6e
test(docs): match exact published-wheel warning in roadmap
agustin18 Nov 21, 2026
7c4b8a8
fix(docs): satisfy Ruff assertion style and exact release wording
agustin18 Nov 21, 2026
0832013
fix(docs): satisfy Ruff assertion style and exact release wording
agustin18 Nov 21, 2026
4199852
docs(features): retain published-0.5.0 wording required by site valid…
agustin18 Nov 21, 2026
1aa2b21
docs(features): retain published-0.5.0 wording required by site valid…
agustin18 Nov 21, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions COMPATIBILITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
22 changes: 18 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand Down
58 changes: 34 additions & 24 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -46,31 +52,35 @@ 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

- **0.5.x:** current published line. Keep the published Python
`>=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
Expand Down Expand Up @@ -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 |
Expand Down
1 change: 1 addition & 0 deletions changelog.d/92.doc.md
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 1 addition & 1 deletion docs/DOCS_SITE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
8 changes: 5 additions & 3 deletions docs/QUICKSTART.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
1 change: 1 addition & 0 deletions site_docs/backends.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
2 changes: 1 addition & 1 deletion site_docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
23 changes: 22 additions & 1 deletion site_docs/guides/inmemory.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion site_docs/guides/privacy.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion site_docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
2 changes: 1 addition & 1 deletion site_docs/reference/alternatives.md
Original file line number Diff line number Diff line change
Expand Up @@ -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**

Expand Down
Loading
Loading