Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
efad0cf
docs(site): polished 0.5.0 discovery, installation and migration land…
agustin18 Nov 21, 2026
a268453
docs(site): polished 0.5.0 discovery, installation and migration land…
agustin18 Nov 21, 2026
1aac4ad
docs(site): polished 0.5.0 discovery, installation and migration land…
agustin18 Nov 21, 2026
2102e91
docs(site): polished 0.5.0 discovery, installation and migration land…
agustin18 Nov 21, 2026
12e894f
docs(site): polished 0.5.0 discovery, installation and migration land…
agustin18 Nov 21, 2026
861bb95
docs(site): backend choice, Redis, InMemory, privacy and troubleshoot…
agustin18 Nov 21, 2026
84f25c1
docs(site): backend choice, Redis, InMemory, privacy and troubleshoot…
agustin18 Nov 21, 2026
97e848a
docs(site): backend choice, Redis, InMemory, privacy and troubleshoot…
agustin18 Nov 21, 2026
6479574
docs(site): backend choice, Redis, InMemory, privacy and troubleshoot…
agustin18 Nov 21, 2026
91ac284
docs(site): backend choice, Redis, InMemory, privacy and troubleshoot…
agustin18 Nov 21, 2026
bfc6c79
docs(site): published capability matrix, support, release evidence an…
agustin18 Nov 21, 2026
183e48c
docs(site): published capability matrix, support, release evidence an…
agustin18 Nov 21, 2026
04c636e
docs(site): published capability matrix, support, release evidence an…
agustin18 Nov 21, 2026
2cd6ed1
docs(site): published capability matrix, support, release evidence an…
agustin18 Nov 21, 2026
a208c91
docs(site): render Markdown code blocks and inline code without escap…
agustin18 Nov 21, 2026
a23a4ef
docs(site): render Markdown code blocks and inline code without escap…
agustin18 Nov 21, 2026
94e004e
docs(site): render Markdown code blocks and inline code without escap…
agustin18 Nov 21, 2026
c7b6eb1
docs(site): add reproducible Zensical build with read-only PR preview…
agustin18 Nov 21, 2026
121ca75
docs(site): add reproducible Zensical build with read-only PR preview…
agustin18 Nov 21, 2026
8c2329a
docs(site): add reproducible Zensical build with read-only PR preview…
agustin18 Nov 21, 2026
42861d2
docs(quickstart): use published 0.5.0 and distinguish shipped Vary fr…
agustin18 Nov 21, 2026
627fca9
docs(discoverability): clarify start-vs-migrate and separate 0.6.0 tr…
agustin18 Nov 21, 2026
1b24edc
docs(discoverability): clarify start-vs-migrate and separate 0.6.0 tr…
agustin18 Nov 21, 2026
0857e5f
test(docs): validate every built HTML link and fragment offline (#48)
agustin18 Nov 21, 2026
e6de3ff
test(docs): validate every built HTML link and fragment offline (#48)
agustin18 Nov 21, 2026
b85e1ad
ci(docs): fail closed on broken links across all generated site pages…
agustin18 Nov 21, 2026
f3fb579
fix(docs): annotate link parser collections for strict mypy gate (#48)
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
78 changes: 78 additions & 0 deletions .github/workflows/docs-site.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
name: Documentation site

on:
pull_request:
branches: [stable]
paths:
- "site_docs/**"
- "mkdocs.yml"
- ".github/workflows/docs-site.yml"
- "docs/QUICKSTART.md"
- "docs/DOCS_SITE.md"
- "README.md"
- "ROADMAP.md"
push:
branches: [stable]
paths:
- "site_docs/**"
- "mkdocs.yml"
- ".github/workflows/docs-site.yml"
- "docs/QUICKSTART.md"
- "docs/DOCS_SITE.md"
- "README.md"
- "ROADMAP.md"
workflow_dispatch:

permissions:
contents: read

jobs:
site:
name: Build, verify and preview documentation
runs-on: ubuntu-24.04
timeout-minutes: 15
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
with:
python-version: "3.12"
- name: Install pinned docs tooling (not a runtime dependency)
run: |
python -m pip install --upgrade pip
python -m pip install "zensical==0.1.3"
- name: Build static site
run: zensical build
- name: Check real pages and published-version promises
run: |
python - <<'PY'
from pathlib import Path
pages = {
"home": Path("site/index.html"),
"start": Path("site/getting-started/index.html"),
"migration": Path("site/migration/index.html"),
"features": Path("site/reference/features/index.html"),
"privacy": Path("site/guides/privacy/index.html"),
}
for name, page in pages.items():
if not page.is_file():
raise AssertionError((name, page))
data = page.read_text(encoding="utf-8")
assert "<html" in data and "0.5.0" in data, (name, page)
homepage = pages["home"].read_text(encoding="utf-8")
assert "Start from scratch" in homepage
assert "Migrate from fastapi-cache2" in homepage
assert "not in 0.5.0" in pages["features"].read_text(encoding="utf-8")
quickstart = Path("docs/QUICKSTART.md").read_text()
assert "fastapi-cache-stable==0.5.0" in quickstart
assert "fastapi-cache-stable==0.4.1" not in quickstart
PY
- name: Validate every built HTML link, target file and page fragment
run: python scripts/check_docs_links.py --site-dir site
- name: Upload preview without publishing a website
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
with:
name: documentation-site-preview
path: site/
if-no-files-found: warn
retention-days: 14
14 changes: 14 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,20 @@ See [compatibility & risk matrix](https://github.com/agustin18/fastapi-cache/blo
[security policy](https://github.com/agustin18/fastapi-cache/blob/stable/SECURITY.md) and
[legacy vulnerability explanation](https://github.com/agustin18/fastapi-cache/blob/stable/audit/security/LEGACY_SUPPORT_AND_RISKS.md).


## Choose your path

| I'm… | Start here | What you'll learn |
|---|---|---|
| **Starting from zero** | [Install in 5 minutes](docs/QUICKSTART.md) · [Visual guide source](site_docs/getting-started.md) | Pinned package, InMemory, first HIT/MISS, Redis |
| **Already on fastapi-cache2** | [Migration walkthrough](site_docs/migration.md) · [Full migration contract](MIGRATION.md) | Remove the old distribution, validate privacy, migrate namespaces, rollback |
| **Comparing features/backends** | [Feature matrix](site_docs/reference/features.md) · [Backend choice](site_docs/backends.md) | What's actually in 0.5.0 and what remains proposed |
| **Checking security** | [Tenant and request safety](site_docs/guides/privacy.md) · [Security policy](SECURITY.md) | Default auth bypass, custom headers, cache-key isolation |
| **Looking ahead** | [Next release plan](site_docs/roadmap.md) · [#86 tracker](https://github.com/agustin18/fastapi-cache/issues/86) | 0.6.0 candidates, not publication promises |

**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.


## Introduction

`fastapi-cache` is a tool to cache FastAPI endpoint and function results, with
Expand Down
19 changes: 19 additions & 0 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,25 @@ The primary product advantage remains conservative migration from
`fastapi-cache2==0.2.2`, preserved `fastapi_cache` imports, predictable
cache keys and safe default HTTP/private-response behavior.


## 0.6.0 — planning, not a release commitment

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.
Proven #53 privacy defects outrank the feature roadmap. Never inherit
0.5.0's release-specific security acceptance for a different SHA.


## Version strategy

- **0.5.x:** current published line. Keep the published Python
Expand Down
1 change: 1 addition & 0 deletions changelog.d/48.doc.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Create a searchable, responsive docs site with separate beginner installation and safe fastapi-cache2 migration, explicit 0.5.0 security/capability boundaries, release evidence, and read-only CI previews. Update the published 0.5.0 quickstart and separate the completed 0.5.0 release from 0.6.0 planning.
39 changes: 39 additions & 0 deletions docs/DOCS_SITE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Documentation site development

The authoritative published package remains **fastapi-cache-stable 0.5.0**. The sources in site_docs/ are a searchable companion to MIGRATION.md, SECURITY.md, COMPATIBILITY.md, SUPPORT.md and the release archive.

## Preview locally

Use a separate docs virtual environment on Python 3.11+:

~~~console
python -m venv .venv-docs
. .venv-docs/bin/activate
python -m pip install "zensical==0.1.3"
zensical serve
~~~

Open http://127.0.0.1:8000/. Build the static pages:

~~~console
zensical build
~~~

The generated site/ directory is not committed. The documentation tool is **not a runtime dependency** of the library.

## PR previews

The read-only Documentation site GitHub Actions workflow builds the site and uploads static output as a short-lived artifact. It does not publish GitHub Pages, mutate PyPI or create a deployment. A public website and true multi-version hosting require separate maintainer approval.

Historical releases already remain navigable at [docs/releases](releases/README.md); source on stable is not immutable documentation for older wheels.

## Authoring contract

- Primary guides describe published behavior. Features from unmerged PRs must be visibly labeled 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.
- Mobile navigation, readable color schemes, accessible links/contrast and reduced-motion preferences are design requirements.
- Compare release dates/hashes against [RELEASE_STATUS_0.5.0.md](releases/RELEASE_STATUS_0.5.0.md), not source version on stable.

The site uses [Zensical](https://zensical.org/) for search, responsive navigation and a modern theme.
31 changes: 24 additions & 7 deletions docs/QUICKSTART.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Quickstart — fastapi-cache-stable 0.4.1
# Quickstart — fastapi-cache-stable 0.5.0

Five-minute example of response caching with
[`fastapi-cache-stable`](https://pypi.org/project/fastapi-cache-stable/0.4.1/).
[`fastapi-cache-stable`](https://pypi.org/project/fastapi-cache-stable/0.5.0/).
The Python import remains `fastapi_cache`.

## Install
Expand All @@ -12,7 +12,7 @@ environment. Create a clean virtual environment:
```sh
python -m venv .venv
. .venv/bin/activate
python -m pip install "fastapi-cache-stable==0.4.1" "uvicorn"
python -m pip install "fastapi-cache-stable==0.5.0" "uvicorn"
python -m pip check
```

Expand Down Expand Up @@ -63,23 +63,39 @@ next identical request within the TTL should show `HIT`.
The decorator order matters: `@app.get` is **above** `@cache`.

**InMemory is per Python process**, not shared between workers; it
has no size cap in 0.4.x. Use Redis standalone when workers must
has no size cap in 0.5.0. Use Redis standalone when workers must
share cached values.

## Redis standalone

First install the tested Redis client line:

```sh
python -m pip install "fastapi-cache-stable[redis]==0.4.1"
python -m pip install "fastapi-cache-stable[redis]==0.5.0"
```

Use [the complete Redis lifespan example](../README.md#quick-start)
and a **test Redis instance**. The 0.4.x compatibility matrix covers
and a **test Redis instance**. The 0.5.0 compatibility matrix covers
Python-conditional redis-py 4.6–8.1 clients and Redis servers 6.2/7.0/7.4/8.0;
see [COMPATIBILITY.md](../COMPATIBILITY.md) and the
[Redis research evidence](../audit/redis/REDIS_CLIENT_MATRIX_RESEARCH.md).

## Header variations in 0.5.0

Public responses that vary on a known header can opt in with
`@cache(expire=60, vary_headers=("Accept-Language",))`. Declare
**every** representation-defining dimension and validate untrusted
header values to avoid cache flooding. An HTTP `Vary` header by
itself does not partition the library's internal store. The feature
is not automatic tenant isolation, and it does not make hidden
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.

## Privacy and migration rules

- Authenticated `Authorization` or `Cookie` requests **bypass** the
Expand All @@ -92,7 +108,7 @@ see [COMPATIBILITY.md](../COMPATIBILITY.md) and the
`Vary`, locale, tenant or custom-auth headers. Use a suitable
custom key builder, or bypass caching until variation is proven safe.
See [the header/Vary investigation](https://github.com/agustin18/fastapi-cache/issues/53).
**0.3.1 and 0.4.1** bypass cache reads and writes when an endpoint
**0.3.1, 0.4.1 and 0.5.0** bypass cache reads and writes when an endpoint
explicitly declares `Request` and uses the default builder; endpoints
with a custom, identity-aware key builder still cache. This does not make
hidden middleware/context variables safe for routes that do not declare
Expand All @@ -110,6 +126,7 @@ see [COMPATIBILITY.md](../COMPATIBILITY.md) and the

## Continue

- [New searchable documentation source](../site_docs/index.md) (web publishing is separate)
- [Migration and rollback](../MIGRATION.md)
- [Precise compatibility matrix](../COMPATIBILITY.md)
- [Security limitations](../SECURITY.md)
Expand Down
80 changes: 80 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
site_name: fastapi-cache-stable
site_description: Drop-in FastAPI response caching with safe migration from fastapi-cache2.
repo_url: https://github.com/agustin18/fastapi-cache
repo_name: agustin18/fastapi-cache
edit_uri: edit/stable/site_docs/
docs_dir: site_docs
site_dir: site
use_directory_urls: true

nav:
- Overview: index.md
- Get started:
- Install from scratch: getting-started.md
- Migrate from fastapi-cache2: migration.md
- Choose a backend: backends.md
- Guides:
- Redis standalone: guides/redis.md
- InMemory: guides/inmemory.md
- Privacy and tenant safety: guides/privacy.md
- Troubleshooting: guides/troubleshooting.md
- Reference:
- Capabilities: reference/features.md
- Compatibility: reference/compatibility.md
- Version history: reference/releases.md
- Roadmap: roadmap.md

theme:
name: material
variant: modern
language: en
font: false
icon:
logo: material/database-check-outline
repo: fontawesome/brands/github
features:
- navigation.tabs
- navigation.sections
- navigation.top
- navigation.tracking
- content.code.copy
- content.tabs.link
- search.suggest
- search.highlight
palette:
- media: "(prefers-color-scheme: light)"
scheme: default
primary: blue
accent: teal
toggle:
icon: material/brightness-7
name: Switch to dark mode
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: blue
accent: teal
toggle:
icon: material/brightness-4
name: Switch to light mode

plugins:
- search

markdown_extensions:
- admonition
- attr_list
- md_in_html
- pymdownx.details
- pymdownx.superfences
- pymdownx.tabbed:
alternate_style: true
- toc:
permalink: true

extra_css:
- assets/stylesheets/extra.css
extra:
social:
- icon: fontawesome/brands/github
link: https://github.com/agustin18/fastapi-cache
copyright: Apache-2.0 · Community-maintained, independent from upstream.
Loading
Loading