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. diff --git a/README.md b/README.md index c2bd1c6a..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/). 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. 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 | 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. 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. 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 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 | 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 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 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. 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 | 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** 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. diff --git a/site_docs/reference/features.md b/site_docs/reference/features.md index e06b018c..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: 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 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 | 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 | |---|---|---| 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 | diff --git a/tests/test_060_docs_version_boundary.py b/tests/test_060_docs_version_boundary.py new file mode 100644 index 00000000..c68d9a2f --- /dev/null +++ b/tests/test_060_docs_version_boundary.py @@ -0,0 +1,46 @@ +"""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 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 available in the immutable published 0.5.0 wheel" in roadmap.lower() + assert "#50" in roadmap + assert "0.7.0" in roadmap + assert "190d105915972d436ddbf4ad152ad654a4db392a" in roadmap