fastapi-cache-stable 0.3.0a0__tar.gz → 0.3.0a2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. fastapi_cache_stable-0.3.0a2/CHANGELOG.md +151 -0
  2. fastapi_cache_stable-0.3.0a2/COMPATIBILITY.md +284 -0
  3. fastapi_cache_stable-0.3.0a2/FORK_ORIGIN.md +12 -0
  4. fastapi_cache_stable-0.3.0a2/MIGRATION.md +408 -0
  5. fastapi_cache_stable-0.3.0a2/PKG-INFO +428 -0
  6. fastapi_cache_stable-0.3.0a2/README.md +385 -0
  7. fastapi_cache_stable-0.3.0a2/SECURITY.md +15 -0
  8. fastapi_cache_stable-0.3.0a2/SUPPORT.md +27 -0
  9. {fastapi_cache_stable-0.3.0a0 → fastapi_cache_stable-0.3.0a2}/fastapi_cache/__init__.py +18 -3
  10. {fastapi_cache_stable-0.3.0a0 → fastapi_cache_stable-0.3.0a2}/fastapi_cache/backends/inmemory.py +27 -15
  11. fastapi_cache_stable-0.3.0a2/fastapi_cache/backends/redis.py +80 -0
  12. fastapi_cache_stable-0.3.0a2/fastapi_cache/coder.py +208 -0
  13. fastapi_cache_stable-0.3.0a2/fastapi_cache/decorator.py +396 -0
  14. {fastapi_cache_stable-0.3.0a0 → fastapi_cache_stable-0.3.0a2}/pyproject.toml +32 -8
  15. fastapi_cache_stable-0.3.0a0/PKG-INFO +0 -281
  16. fastapi_cache_stable-0.3.0a0/README.md +0 -238
  17. fastapi_cache_stable-0.3.0a0/fastapi_cache/backends/redis.py +0 -30
  18. fastapi_cache_stable-0.3.0a0/fastapi_cache/coder.py +0 -129
  19. fastapi_cache_stable-0.3.0a0/fastapi_cache/decorator.py +0 -231
  20. {fastapi_cache_stable-0.3.0a0 → fastapi_cache_stable-0.3.0a2}/LICENSE +0 -0
  21. {fastapi_cache_stable-0.3.0a0 → fastapi_cache_stable-0.3.0a2}/NOTICE +0 -0
  22. {fastapi_cache_stable-0.3.0a0 → fastapi_cache_stable-0.3.0a2}/fastapi_cache/backends/__init__.py +0 -0
  23. {fastapi_cache_stable-0.3.0a0 → fastapi_cache_stable-0.3.0a2}/fastapi_cache/backends/dynamodb.py +0 -0
  24. {fastapi_cache_stable-0.3.0a0 → fastapi_cache_stable-0.3.0a2}/fastapi_cache/backends/memcached.py +0 -0
  25. {fastapi_cache_stable-0.3.0a0 → fastapi_cache_stable-0.3.0a2}/fastapi_cache/key_builder.py +0 -0
  26. {fastapi_cache_stable-0.3.0a0 → fastapi_cache_stable-0.3.0a2}/fastapi_cache/py.typed +0 -0
  27. {fastapi_cache_stable-0.3.0a0 → fastapi_cache_stable-0.3.0a2}/fastapi_cache/types.py +0 -0
@@ -0,0 +1,151 @@
1
+ # ChangeLog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
+
7
+ This project uses [*towncrier*](https://towncrier.readthedocs.io/) and the changes for the upcoming release can be found in <https://github.com/agustin18/fastapi-cache/tree/stable/changelog.d/>.
8
+
9
+ <!-- towncrier release notes start -->
10
+
11
+ ## [0.3.0a2](https://github.com/agustin18/fastapi-cache/tree/v0.3.0a2) - 2026-11-14
12
+
13
+ ### Bugfixes
14
+
15
+ - Bypass the cache for requests with a non-empty `Authorization` or `Cookie` header by
16
+ default. Add `cache_authenticated=True` to opt in with an identity-aware `key_builder`;
17
+ opting in with the default key builder raises `ValueError` for authenticated requests.
18
+ Backend error logs now report only the endpoint, namespace, and exception type; they no
19
+ longer include the cache key, exception message, or traceback.
20
+ Clear or rotate the cache namespace when upgrading from versions that cached authenticated
21
+ responses. [#12](https://github.com/agustin18/fastapi-cache/issues/12)
22
+ - InMemory backend: `expire=None` now means no expiration instead of immediate expiry, and each
23
+ backend instance has its own store and lock. Existing process-local entries are not shared
24
+ between instances; use a shared backend for cross-process caching. [#13](https://github.com/agustin18/fastapi-cache/issues/13)
25
+ - Emit `Cache-Control: max-age` only when the effective expiry is valid and non-negative.
26
+ `expire=None` and no-expiration InMemory hits no longer produce `max-age=None` or
27
+ `max-age=-1`; `ETag` and the cache-status header are still emitted. `expire=0` keeps the
28
+ legacy fallback to the global `expire` value. [#14](https://github.com/agustin18/fastapi-cache/issues/14)
29
+ - Use a stable SHA-256 digest for the ETag and emit it as a quoted weak validator
30
+ (`W/"<digest>"`). `If-None-Match` now uses weak comparison, supports comma-separated lists
31
+ and `*`, and is evaluated on both cache hits and misses, including after
32
+ `Cache-Control: no-cache`. Malformed entity-tags are ignored. The ETag value changes once
33
+ when upgrading; clients revalidate and receive the new value. [#15](https://github.com/agustin18/fastapi-cache/issues/15)
34
+ - Namespace the internal `_spec_type` marker as `__fastapi_cache_spec_type__` so user payloads
35
+ with `_spec_type` are preserved. `JsonCoder` now caches only simple `JSONResponse` objects
36
+ (status `200`, `application/json`, no custom headers, no background task) and bypasses other
37
+ non-JSON responses (`StreamingResponse`, `FileResponse`, `RedirectResponse`, plain `Response`,
38
+ templates). Responses with `Set-Cookie`, `Cache-Control: no-store`/`private`, or a background
39
+ task are never cached, regardless of the coder. The injected `response` object is also
40
+ checked before a cache read and before writing; cookies, `Cache-Control: no-store`/`private`,
41
+ background tasks, non-`200` statuses, and custom headers bypass the cache. `PickleCoder` caches serializable response
42
+ objects it can reproduce faithfully and bypasses streaming, file, and template responses. Old
43
+ cache entries written with `_spec_type` are treated as user data; flush the namespace if you
44
+ cache `datetime`/`date`/`Decimal` values. [#16](https://github.com/agustin18/fastapi-cache/issues/16)
45
+
46
+ ### Improved Documentation
47
+
48
+ - Document the published `0.3.0a1` release and pin the alpha install commands. [#11](https://github.com/agustin18/fastapi-cache/issues/11)
49
+ - Document the `0.3.0a2` release status, pin the alpha install commands, and record the tested
50
+ Redis/redis-py compatibility. The auth/privacy, InMemory, `Cache-Control`, ETag,
51
+ `_spec_type`, and response-bypass fixes are now available in `0.3.0a2`. [#17](https://github.com/agustin18/fastapi-cache/issues/17)
52
+
53
+ ## [0.3.0a1](https://github.com/agustin18/fastapi-cache/tree/v0.3.0a1) - 2026-11-14
54
+
55
+ ### Bugfixes
56
+
57
+ - Avoid caching explicitly returned `Response` objects with status codes >= 400. Adapted from upstream PR #575 by RitiGrover. [#2](https://github.com/agustin18/fastapi-cache/issues/2)
58
+ - Add opt-in `TypedJsonCoder` for Pydantic v2 typed restoration. `JsonCoder` keeps the legacy decoded behavior; Pydantic v1 and unsupported annotations fall back; validation errors propagate. Adapted from upstream PR #576 by bezff. [#4](https://github.com/agustin18/fastapi-cache/issues/4)
59
+ - Fix `clear(key=...)` so it deletes only the requested key, and require the `:` boundary for
60
+ namespace clears in InMemory and Redis. Redis standalone now uses `SCAN`/`UNLINK`; Redis
61
+ Cluster namespace clearing raises `NotImplementedError`. Memcached/DynamoDB clear remains
62
+ unsupported. [#7](https://github.com/agustin18/fastapi-cache/issues/7)
63
+
64
+ ### Improved Documentation
65
+
66
+ - Document and verify the legacy compatibility matrix: Python 3.8/3.9, FastAPI 0.111.1, and
67
+ Pydantic 1.10.27/2.8.2. Add a legacy CI job and a Python 3.8 wheel smoke test. No runtime
68
+ behavior changes. [#5](https://github.com/agustin18/fastapi-cache/issues/5)
69
+
70
+ ### Misc
71
+
72
+ - Bump the transitive `certifi` dev/test dependency from 2024.7.4 to 2026.10.23. [#6](https://github.com/agustin18/fastapi-cache/issues/6)
73
+ - Add a manual TestPyPI publishing workflow with a separate `testpypi` environment and Trusted Publisher. It never runs on `release: published`. [#8](https://github.com/agustin18/fastapi-cache/issues/8)
74
+ - Make PyPI publishing manual-only by removing the `release: published` trigger. [#9](https://github.com/agustin18/fastapi-cache/issues/9)
75
+
76
+ ## 0.3.0a0
77
+
78
+ - Community-maintained stable fork of fastapi-cache2, based on v0.2.2.
79
+ - Distribution renamed to `fastapi-cache-stable`; the `fastapi_cache` import and public API are unchanged.
80
+ - Declare `jinja2` as a direct dependency; the `starlette.templating` import in `coder.py` requires it.
81
+ - This is an alpha to reserve the PyPI distribution name. The 0.3.0 release will include the P0 correctness fixes and compatibility tests.
82
+
83
+ ## 0.2
84
+
85
+ ### 0.2.1
86
+ - Fix picklecoder
87
+ - Fix connection failure transparency and add logging
88
+ - Add Cache-Control and ETag on first response
89
+ - Support Async RedisCluster client from redis-py
90
+
91
+ ### 0.2.0
92
+
93
+ - Make `request` and `response` optional.
94
+ - Add typing info to the `cache` decorator.
95
+ - Support cache jinja2 template response.
96
+ - Support cache `JSONResponse`
97
+ - Add `py.typed` file and type hints
98
+ - Add TestCase
99
+ - Fix cache decorate sync function
100
+ - Transparently handle backend connection failures.
101
+
102
+ ## 0.1
103
+
104
+ ### 0.1.10
105
+
106
+ - Add `Cache-Control:no-cache` support.
107
+
108
+ ### 0.1.9
109
+
110
+ - Replace `aioredis` with `redis-py`.
111
+
112
+ ### 0.1.8
113
+
114
+ - Support `dynamodb` backend.
115
+
116
+ ### 0.1.7
117
+
118
+ - Fix default json coder for datetime.
119
+ - Add `enable` param to `init`.
120
+
121
+ ### 0.1.6
122
+
123
+ - Fix redis cache.
124
+ - Encode key builder.
125
+
126
+ ### 0.1.5
127
+
128
+ - Fix setting expire for redis (#24)
129
+ - Update expire key
130
+
131
+ ### 0.1.4
132
+
133
+ - Fix default expire for memcached. (#13)
134
+ - Update default key builder. (#12)
135
+
136
+ ### 0.1.3
137
+
138
+ - Fix cache key builder.
139
+
140
+ ### 0.1.2
141
+
142
+ - Add default config when init.
143
+ - Update JsonEncoder.
144
+
145
+ ### 0.1.1
146
+
147
+ - Add in-memory support.
148
+
149
+ ### 0.1.0
150
+
151
+ - First version release.
@@ -0,0 +1,284 @@
1
+ # Compatibility contract
2
+
3
+ `fastapi-cache-stable` is an independent, community-maintained fork of
4
+ [`fastapi-cache2`](https://pypi.org/project/fastapi-cache2/). This document defines what
5
+ "drop-in" means for this project and what we promise to keep stable.
6
+
7
+ ## What "drop-in" means
8
+
9
+ - The distribution is `fastapi-cache-stable`, but the Python import remains `fastapi_cache`.
10
+ - The public names below keep their import paths and call signatures.
11
+ - The normal success path for a GET endpoint keeps the same observable behavior: cache
12
+ miss calls the endpoint, cache hit returns the cached value, and the cache status header
13
+ reports `MISS`/`HIT`.
14
+ - Existing `@cache(...)` and `FastAPICache.init(...)` calls keep working without code changes.
15
+ - Authenticated requests bypass the cache by default. This is an intentional privacy behavior
16
+ change; authenticated endpoints must opt in with `cache_authenticated=True` and an
17
+ identity-aware `key_builder` to keep caching.
18
+ - `InMemoryBackend` instances are isolated: each owns its store and lock. `expire=None` means
19
+ no expiration. InMemory remains process-local; use a shared backend for cross-process
20
+ caching.
21
+ - Existing custom backends, coders and key builders that implement the documented protocols
22
+ keep working.
23
+ - Migration from `fastapi-cache2` does not require application code changes for valid legacy
24
+ use cases.
25
+ - Pydantic v2 users can opt into `TypedJsonCoder` for typed restoration; the default
26
+ `JsonCoder` keeps the legacy decoded behavior. Pydantic v1 and unsupported annotations
27
+ keep the legacy behavior.
28
+ - Python 3.8/3.9 legacy compatibility is validated in CI with FastAPI 0.111.1 and
29
+ Pydantic 1.10.27/2.8.2; it is migration compatibility, not a new-production recommendation.
30
+
31
+ ## Public surface
32
+
33
+ ```python
34
+ from fastapi_cache import (
35
+ Backend,
36
+ Coder,
37
+ FastAPICache,
38
+ JsonCoder,
39
+ KeyBuilder,
40
+ TypedJsonCoder,
41
+ default_key_builder,
42
+ )
43
+ from fastapi_cache.decorator import cache
44
+ from fastapi_cache.backends.inmemory import InMemoryBackend
45
+ from fastapi_cache.backends.redis import RedisBackend
46
+ from fastapi_cache.backends.memcached import MemcachedBackend
47
+ from fastapi_cache.backends.dynamodb import DynamoBackend
48
+ ```
49
+
50
+ ### `FastAPICache`
51
+
52
+ ```python
53
+ FastAPICache.init(
54
+ backend,
55
+ prefix="",
56
+ expire=None,
57
+ coder=JsonCoder,
58
+ key_builder=default_key_builder,
59
+ cache_status_header="X-FastAPI-Cache",
60
+ enable=True,
61
+ cache_authenticated=False,
62
+ )
63
+ FastAPICache.clear(namespace=None, key=None)
64
+ FastAPICache.reset()
65
+ FastAPICache.get_backend()
66
+ FastAPICache.get_prefix()
67
+ FastAPICache.get_expire()
68
+ FastAPICache.get_coder()
69
+ FastAPICache.get_key_builder()
70
+ FastAPICache.get_cache_status_header()
71
+ FastAPICache.get_enable()
72
+ FastAPICache.get_cache_authenticated()
73
+ ```
74
+
75
+ ### `@cache(...)`
76
+
77
+ ```python
78
+ cache(
79
+ expire=None,
80
+ coder=None,
81
+ key_builder=None,
82
+ namespace="",
83
+ injected_dependency_namespace="__fastapi_cache",
84
+ cache_authenticated=None,
85
+ )
86
+ ```
87
+
88
+ ### `Backend` protocol
89
+
90
+ ```python
91
+ async def get_with_ttl(key: str) -> tuple[int, bytes | None]
92
+ async def get(key: str) -> bytes | None
93
+ async def set(key: str, value: bytes, expire: int | None = None) -> None
94
+ async def clear(namespace: str | None = None, key: str | None = None) -> int
95
+ ```
96
+
97
+ ### `KeyBuilder` protocol
98
+
99
+ ```python
100
+ def __call__(
101
+ function,
102
+ namespace: str = "",
103
+ *,
104
+ request=None,
105
+ response=None,
106
+ args: tuple,
107
+ kwargs: dict,
108
+ ) -> str | Awaitable[str]
109
+ ```
110
+
111
+ ### `Coder` protocol
112
+
113
+ ```python
114
+ classmethod can_encode(value) -> bool
115
+ classmethod encode(value) -> bytes
116
+ classmethod decode(value: bytes) -> Any
117
+ classmethod decode_as_type(value: bytes, *, type_) -> Any
118
+ ```
119
+
120
+ ## Support levels
121
+
122
+ - **Migration compatibility:** tested legacy combinations are kept so existing applications can
123
+ move to this fork without code changes. This is not a recommendation for new production
124
+ deployments.
125
+ - **Security-supported environment:** current Python, FastAPI and Pydantic releases that still
126
+ receive upstream security fixes. This project does not backport security fixes for
127
+ end-of-life upstreams.
128
+
129
+ Python 3.8, 3.9 and 3.10 are end-of-life, and Pydantic v1 is end-of-life with 1.10.27 as its
130
+ final release. They remain in the migration matrix for compatibility, not as supported
131
+ security targets.
132
+
133
+ ## Supported matrix for `0.3.x`
134
+
135
+ > The `0.3.0` line keeps `python = "^3.8"` for legacy migration. Python 3.8/3.9/3.10 and
136
+ > Pydantic v1 are end-of-life upstream; they are tested for migration, not recommended for
137
+ > new production deployments. The minimum supported Python will be revisited only after the
138
+ > compatibility matrix and an explicit floor decision.
139
+
140
+ Status definitions:
141
+
142
+ - **Verified**: tested in CI with identified versions.
143
+ - **Targeted for 0.3.0**: intended behavior, not yet guaranteed.
144
+ - **Experimental**: interface available, coverage insufficient.
145
+ - **Unsupported**: outside the compatibility contract.
146
+
147
+ | Component | Status | Notes |
148
+ |---|---|---|
149
+ | Python 3.10–3.13 | Verified | CI matrix runs the suite; Python 3.10 is EOL and kept for migration |
150
+ | Python 3.8/3.9 | Verified for migration | Legacy CI job with FastAPI 0.111.1 and Pydantic 1.10.27/2.8.2; EOL, not recommended for new production |
151
+ | Python 3.14 | Targeted | Evaluated after the first stable release |
152
+ | FastAPI | Verified with 0.111.1 and current 0.x | Older 0.100.x validation is a beta gate; no upper pin yet (`fastapi = "*"`) |
153
+ | Pydantic 2.x | Verified | Typed restoration is opt-in via `TypedJsonCoder`; default `JsonCoder` keeps legacy behavior |
154
+ | Pydantic v1 | Verified for migration | Tested with 1.10.27; EOL, no new security fixes; typed restoration is not applied |
155
+ | `Response`/`JSONResponse` annotations | Legacy decoded behavior | No Pydantic schema generation; cache hits keep working |
156
+ | Redis standalone | Verified for clear semantics | Redis 7 service in CI with redis-py 4.6.0; key-only clear and namespace boundary tested. redis-py 5/6 are not supported by the current `^4.2.0rc1` constraint and are untested |
157
+ | Redis Cluster | Unsupported for namespace clear | Key-only clear is supported; namespace clear raises `NotImplementedError`; no complete namespace clearing |
158
+ | InMemory | Verified for basic operations, clear semantics, `expire=None` and instance isolation | Unit tests; each instance owns its store and lock; no size cap yet |
159
+ | Memcached | Experimental | No full `clear`/TTL parity; `clear` raises `NotImplementedError` |
160
+ | DynamoDB | Experimental | `clear` raises `NotImplementedError`; the client cleanup issue remains open and is targeted for a future fix |
161
+ | Import `fastapi_cache` | Verified | Covered by compatibility tests |
162
+
163
+ > Redis results in `0.3.0a2` cover Redis 7 with redis-py 4.6.0. Other client or server
164
+ > versions are not verified; do not infer support from the Redis 7 job alone.
165
+
166
+ ### `0.3.0a1` status
167
+
168
+ Implemented: error responses, opt-in `TypedJsonCoder`, `clear()` key/namespace semantics,
169
+ Redis Cluster namespace `NotImplementedError`, and the legacy compatibility matrix.
170
+
171
+ ### `0.3.0a2` status
172
+
173
+ Implemented in `0.3.0a2`: authenticated requests bypass the
174
+ cache by default; opt-in with `cache_authenticated=True` and an identity-aware `key_builder`.
175
+ Opting in with the default key builder raises `ValueError` for authenticated requests.
176
+ `InMemoryBackend` instances are isolated, and `expire=None` means no expiration. The
177
+ decorator emits `Cache-Control: max-age` only for valid, non-negative expiry values; it
178
+ omits `max-age` for `expire=None` and no-expiration hits. `expire=0` keeps the legacy
179
+ fallback to the global `expire` value. ETags are quoted weak validators derived from a
180
+ stable SHA-256 digest; `If-None-Match` uses weak comparison, supports lists and `*`, is
181
+ evaluated on hits and misses, and ignores malformed entity-tags. `_spec_type` user payloads
182
+ are preserved via a namespaced internal marker. `JsonCoder` caches only simple `200`
183
+ `application/json` `JSONResponse` objects; other responses are bypassed unless the coder's
184
+ `can_encode` supports them. Responses with `Set-Cookie`, `Cache-Control: no-store/private`,
185
+ or a background task are never cached. The injected `response` object is checked before a
186
+ cache read and before a write; those directives, a non-`200` status, or any header other than
187
+ the automatic `content-length` bypass the cache for dict/list returns.
188
+
189
+ Targeted for later pre-releases: explicit re-`init()` and the Redis client/server matrix.
190
+
191
+ ### Clear semantics
192
+
193
+ - `clear(key=...)` deletes exactly that key. Pass the full key as stored by the backend.
194
+ - `clear(namespace=...)` requires the `:` namespace boundary and includes nested namespaces.
195
+ - `clear()` clears the configured prefix; with an empty prefix it is a no-op.
196
+ - If both `namespace` and `key` are provided, `namespace` wins.
197
+ - Namespace clear is best-effort, not atomic. Keys added during a Redis `SCAN` may survive.
198
+ - Redis standalone uses `SCAN` + `UNLINK`; Redis Cluster namespace clear raises
199
+ `NotImplementedError`; use key-only clear or flush the database out of band.
200
+ - Memcached and DynamoDB do not implement `clear`.
201
+ - `clear()` is an administrative invalidation operation. Do not accept arbitrary keys or
202
+ namespaces from untrusted users.
203
+
204
+ ## Intentional behavior changes
205
+
206
+ These are bug fixes targeted for `0.3.0`. The error-response, typed-decode and
207
+ clear-semantics fixes are implemented in `0.3.0a1`; the auth/privacy, InMemory,
208
+ `Cache-Control`, ETag, `_spec_type` and response-caching fixes are implemented in `0.3.0a2`;
209
+ the second-`init` row is targeted for later pre-releases. Each one is documented in [`MIGRATION.md`](MIGRATION.md) and covered by a
210
+ regression test when implemented.
211
+
212
+ | Version | Change | Why | Status |
213
+ |---|---|---|---|
214
+ | 0.3.0 | Error `Response` objects (status >= 400) are not cached | A cached 404 could be returned as 200 | Implemented in `0.3.0a1` |
215
+ | 0.3.0 | Opt-in `TypedJsonCoder` decodes cached JSON into the annotated return type on Pydantic v2 | Default `JsonCoder` and Pydantic v1 keep the legacy decoded behavior; `TypedJsonCoder` propagates validation errors | Implemented in `0.3.0a1` |
216
+ | 0.3.0 | Authenticated requests bypass the cache by default | Prevent cross-user response reuse | Implemented in `0.3.0a2` |
217
+ | 0.3.0 | ETag is stable across processes and correctly quoted | `hash()` is randomized per process and the old header was invalid | Implemented in `0.3.0a2` |
218
+ | 0.3.0 | `clear(key=...)` deletes only that key | It used to delete the whole prefix namespace | Implemented in `0.3.0a1` |
219
+ | 0.3.0 | `clear("app:user")` does not delete `app:users` | Namespace matching requires the `:` boundary | Implemented in `0.3.0a1` |
220
+ | 0.3.0 | Redis Cluster namespace clear raises `NotImplementedError` | Partial/unsafe clearing was not reliable | Implemented in `0.3.0a1` |
221
+ | 0.3.0 | `expire=None` means no expiration in `InMemoryBackend` | It used to expire almost immediately | Implemented in `0.3.0a2` |
222
+ | 0.3.0 | `InMemoryBackend` instances do not share state | The class-level store leaked entries between instances | Implemented in `0.3.0a2` |
223
+ | 0.3.0 | `Cache-Control` never emits `max-age=None` or `max-age=-1` | Invalid headers | Implemented in `0.3.0a2` |
224
+ | 0.3.0 | User payloads with a `_spec_type` key are not interpreted as internal metadata | The marker collided with user data | Implemented in `0.3.0a2` |
225
+ | 0.3.0 | Only simple `JSONResponse` objects are cached by `JsonCoder`; other responses bypass | Status/headers/body were lost or corrupted | Implemented in `0.3.0a2` |
226
+ | 0.3.0 | Responses with `Set-Cookie`, `Cache-Control: no-store/private`, or a background task are never cached | Cookies and private data could be replayed to other clients | Implemented in `0.3.0a2` |
227
+ | 0.3.0 | Injected `response` metadata is checked before cache reads and writes | Dict/list responses could cache cookies, private data, custom statuses, or custom headers | Implemented in `0.3.0a2` |
228
+ | 0.3.0 | A second `FastAPICache.init(...)` is not a silent no-op | Configuration was impossible to change | Targeted |
229
+
230
+ ## Cache data compatibility
231
+
232
+ - **ETag:** the value changes once. The new value is a stable SHA-256 digest; clients may
233
+ revalidate after upgrading.
234
+ - **Key format:** if a release changes the default key format, old entries become
235
+ unreachable. Flush the cache namespace after upgrading.
236
+ - **Error responses:** old cached error entries may remain until their TTL expires. Flush
237
+ the cache namespace if you were affected.
238
+ - **Authenticated responses:** entries written by versions that cached authenticated requests
239
+ under the default key may remain. Clear or rotate the cache namespace before deploying the
240
+ bypass, including all instances/workers and persistent Redis caches. The bypass is not
241
+ retroactive.
242
+ - **InMemory:** data is process-local and is lost on restart. Instances no longer share a
243
+ store; a new backend after `FastAPICache.reset()` starts empty. No data-format migration.
244
+ - **Pydantic/dataclass values:** old entries encoded as plain JSON still decode; the
245
+ annotated type is restored on read. No flush required for this fix alone.
246
+ - **`_spec_type`:** the internal marker changed to `__fastapi_cache_spec_type__`. Old entries
247
+ written with `_spec_type` are treated as user data; flush the namespace if you cache
248
+ `datetime`/`date`/`Decimal` values.
249
+
250
+ ## How compatibility is tested
251
+
252
+ - API signature tests for the public names above.
253
+ - Characterization tests for the normal GET success path.
254
+ - Auth/privacy tests for default bypass, opt-in isolation, backend non-access, and legacy
255
+ cache-entry invalidation.
256
+ - InMemory tests for `expire=None`, instance isolation, clear isolation, and decorator
257
+ default-expire behavior.
258
+ - Regression tests for every behavior change.
259
+ - CI tests Python 3.10–3.13 with resolver-selected FastAPI and Pydantic versions.
260
+ - A `legacy-compat` job tests Python 3.8/3.9 with FastAPI 0.111.1 and Pydantic 1.10.27/2.8.2,
261
+ plus Python 3.10/3.11 with Pydantic 1.10.27.
262
+ - A `legacy-smoke` job builds the wheel and installs it on Python 3.8 with Pydantic 1.10.27.
263
+ - Wheel and sdist smoke tests in a clean virtual environment.
264
+ - Redis 7 integration tests run in CI; Memcached and DynamoDB backend integration tests are
265
+ planned.
266
+ - Migration tests that install the package and run a small app.
267
+
268
+ ## If we break something
269
+
270
+ We treat a compatibility break as a bug:
271
+
272
+ 1. Open an issue (when issues are enabled) or a private security advisory for a
273
+ vulnerability.
274
+ 2. Document the break and the rollback path in `MIGRATION.md`.
275
+ 3. Publish a patch release with a regression test.
276
+ 4. If the break is unavoidable, announce it before the release and provide a migration path.
277
+
278
+ ## Not covered by this contract
279
+
280
+ - Private APIs of FastAPI, Starlette or Pydantic.
281
+ - Behavior of optional backends marked experimental.
282
+ - Undocumented attributes such as `FastAPICache._backend` or `_enable`.
283
+ - Exact cache key strings, ETag values, header ordering or log messages.
284
+ - Performance characteristics.
@@ -0,0 +1,12 @@
1
+ # Fork origin
2
+
3
+ This project is a community-maintained fork of fastapi-cache (PyPI: `fastapi-cache2`),
4
+ originally by long2ice and contributors:
5
+
6
+ https://github.com/long2ice/fastapi-cache
7
+
8
+ - Baseline: `v0.2.2` (2024-07-24).
9
+ - License: Apache-2.0 (see `LICENSE`).
10
+ - This fork is not affiliated with or endorsed by the original author.
11
+ - The `fastapi_cache` import and public API are preserved for drop-in compatibility.
12
+ - Changes are documented in `CHANGELOG.md`.