Skip to content

docs: show what each Cache-Control directive actually does #145

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
allen0099 merged 1 commit into from
Sep 25, 2026
Merged

docs: show what each Cache-Control directive actually does #145

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
6 changes: 6 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,12 @@ Note that 0.3.3 was never released; 0.3.4 follows 0.3.2.

### Fixed

- The Cache-Control table in the HTTP caching guide no longer marks
header-only directives as simply "supported". It now shows, for each
directive, how to set it, whether it is sent, and what it does to the
server-side cache. A new section documents that the request's own
`Cache-Control` is ignored by design.

- Docstrings and guides that disagreed with the code are corrected. Most
visible:
- `SessionConfig.sliding_threshold` now describes renewal once less than
Expand Down
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@

[English](https://github.com/allen0099/FastAPI-CacheX/blob/master/README.md) | [繁體中文](https://github.com/allen0099/FastAPI-CacheX/blob/master/docs/README.zh-TW.md)

A high-performance caching extension for FastAPI, providing comprehensive HTTP caching support and optional session management.
A high-performance caching extension for FastAPI: a server-side response cache with `Cache-Control` and `ETag` support, application-level caching, and optional session management.

**Documentation:** <https://fastapi-cachex.readthedocs.io/en/latest/> — guides and the full API reference.

Expand Down
49 changes: 32 additions & 17 deletions docs/HTTP_CACHING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,25 +38,40 @@ when it is missing. If no backend has been configured, `@cache` falls back to a

## Cache-Control directives

| Directive | Supported | Description |
|--------------------------|--------------------|---------------------------------------------------------------------------------------------------------|
| `max-age` | :white_check_mark: | Specifies the maximum amount of time a resource is considered fresh. |
| `s-maxage` | :x: | Specifies the maximum amount of time a resource is considered fresh for shared caches. |
| `no-cache` | :white_check_mark: | Forces caches to submit the request to the origin server for validation before releasing a cached copy. |
| `no-store` | :white_check_mark: | Instructs caches not to store any part of the request or response. |
| `no-transform` | :x: | Instructs caches not to transform the response content. |
| `must-revalidate` | :white_check_mark: | Forces caches to revalidate the response with the origin server after it becomes stale. |
| `proxy-revalidate` | :x: | Similar to `must-revalidate`, but only for shared caches. |
| `must-understand` | :x: | Indicates that the recipient must understand the directive or treat it as an error. |
| `private` | :white_check_mark: | Indicates that the response is intended for a single user and should not be stored by shared caches. |
| `public` | :white_check_mark: | Indicates that the response may be cached by any cache, even if it is normally non-cacheable. |
| `immutable` | :white_check_mark: | Indicates that the response body will not change over time, allowing for longer caching. |
| `stale-while-revalidate` | :white_check_mark: | Indicates that a cache can serve a stale response while it revalidates the response in the background. |
| `stale-if-error` | :white_check_mark: | Indicates that a cache can serve a stale response if the origin server is unavailable. |

How each decorator argument turns into the header is described in
`@cache` plays two roles. It writes a `Cache-Control` header for browsers and
intermediaries (CDNs, reverse proxies), and it keeps its own server-side cache in
the backend. Most directives only affect the first: they are written into the
header, and the server-side cache behaves the same with or without them.

| Directive | Set with | Sent in header | Effect on the server-side cache |
|--------------------------|------------------------------------------|--------------------|----------------------------------------------------------------------------------------------------------------|
| `max-age` | `ttl=N` | :white_check_mark: | The stored response is served for `N` seconds without running the handler (`ttl=0` or unset: never served directly). |
| `no-cache` | `no_cache=True` | :white_check_mark: | The handler runs on every request; the response is still stored, and a matching `If-None-Match` gets a 304. |
| `no-store` | `no_store=True` | :white_check_mark: | Nothing is read or stored, and no ETag is set. |
| `private` | `private=True` | :white_check_mark: | The backend is bypassed; the handler runs on every request, and ETag revalidation still works. |
| `public` | `public=True` | :white_check_mark: | None (header only). |
| `immutable` | `immutable=True` | :white_check_mark: | None (header only). |
| `must-revalidate` | `must_revalidate=True` | :white_check_mark: | None (header only). |
| `stale-while-revalidate` | `stale="revalidate", stale_ttl=N` | :white_check_mark: | None (header only): the server-side cache never serves stale content. |
| `stale-if-error` | `stale="error", stale_ttl=N` | :white_check_mark: | None (header only): a failing handler is not answered from the cache. |
| `s-maxage` | — | :x: | — |
| `proxy-revalidate` | — | :x: | — |
| `no-transform` | — | :x: | — |
| `must-understand` | — | :x: | — |

`no_cache=True` and `no_store=True` replace the rest of the header: with
`no_cache` only `no-cache` (and `must-revalidate`, when set) is sent, and with
`no_store` only `no-store`. How the other arguments combine is described in
[Cache flow](CACHE_FLOW.md#2-cache-control-directives).

### The request's `Cache-Control` is ignored

A client's own `Cache-Control` request header (`no-cache`, `max-age=0`, as sent
by a browser's hard reload, and so on) does not change what `@cache` does. This
is deliberate: if a request header could bypass the cache, any client could
send every request straight to your handler. Conditional requests are honoured:
a matching `If-None-Match` gets a 304.

## Cache hit behavior

When a cached entry is valid (within TTL):
Expand Down
38 changes: 21 additions & 17 deletions docs/README.zh-TW.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@

[English](https://github.com/allen0099/FastAPI-CacheX/blob/master/README.md) | [繁體中文](README.zh-TW.md)

FastAPI-CacheX 是一個為 FastAPI 框架設計的高效能快取擴充套件，提供完整的 HTTP 快取功能支援和可選的 Session 管理。
FastAPI-CacheX 是一個為 FastAPI 框架設計的高效能快取擴充套件，提供伺服器端回應快取（支援 `Cache-Control` 與 `ETag`）、應用層快取和可選的 Session 管理。

## 功能特點

Expand All @@ -27,7 +27,7 @@ FastAPI-CacheX 是一個為 FastAPI 框架設計的高效能快取擴充套件
- Redis
- Memcached
- 記憶體內快取
- 完整實現 Cache-Control 指令
- 可在回應中設定常用的 Cache-Control 指令（詳見下表）
- 簡單易用的 `@cache` 裝飾器

### Session 管理（可選擴充套件）
Expand All @@ -43,21 +43,25 @@ FastAPI-CacheX 是一個為 FastAPI 框架設計的高效能快取擴充套件

### Cache-Control 指令

| 指令 | 支援狀態 | 說明 |
|--------------------------|--------------------|---------------------------------|
| `max-age` | :white_check_mark: | 指定資源被認為是新鮮的最長時間。 |
| `s-maxage` | :x: | 在共享快取中資源被認為是新鮮的最長時間。 |
| `no-cache` | :white_check_mark: | 強制快取在釋放快取副本前向原始伺服器驗證請求。 |
| `no-store` | :white_check_mark: | 指示快取不儲存請求或回應的任何部分。 |
| `no-transform` | :x: | 指示快取不要轉換回應內容。 |
| `must-revalidate` | :white_check_mark: | 強制快取在資源過期後向原始伺服器重新驗證。 |
| `proxy-revalidate` | :x: | 類似 `must-revalidate`，但僅適用於共享快取。 |
| `must-understand` | :x: | 表示接收者必須理解該指令，否則應視為錯誤。 |
| `private` | :white_check_mark: | 表示回應僅供單一使用者使用，不應被共享快取儲存。 |
| `public` | :white_check_mark: | 表示回應可被任何快取儲存，即使通常是無法快取的。 |
| `immutable` | :white_check_mark: | 表示回應內容不會隨時間改變，允許更長時間的快取。 |
| `stale-while-revalidate` | :white_check_mark: | 表示快取可以在背景重新驗證時提供過期的回應。 |
| `stale-if-error` | :white_check_mark: | 表示當原始伺服器無法訪問時，快取可以提供過期的回應。 |
`@cache` 有兩個角色：替瀏覽器與中間層（CDN、反向代理）寫出 `Cache-Control` 標頭，以及在後端維護自己的伺服器端快取。大部分指令只影響前者：它們會寫進標頭，但伺服器端快取的行為不會因此改變。

| 指令 | 設定方式 | 寫入標頭 | 對伺服器端快取的影響 |
|--------------------------|-------------------------------------|--------------------|-------------------------------------------------------------|
| `max-age` | `ttl=N` | :white_check_mark: | `N` 秒內直接回傳已儲存的回應，不執行 handler（`ttl=0` 或未設定：不直接回傳）。 |
| `no-cache` | `no_cache=True` | :white_check_mark: | 每次都執行 handler；回應仍會儲存，`If-None-Match` 相符時回 304。 |
| `no-store` | `no_store=True` | :white_check_mark: | 不讀取也不儲存，也不設定 ETag。 |
| `private` | `private=True` | :white_check_mark: | 完全不經過後端；每次都執行 handler，ETag 重新驗證仍有效。 |
| `public` | `public=True` | :white_check_mark: | 無（僅寫入標頭）。 |
| `immutable` | `immutable=True` | :white_check_mark: | 無（僅寫入標頭）。 |
| `must-revalidate` | `must_revalidate=True` | :white_check_mark: | 無（僅寫入標頭）。 |
| `stale-while-revalidate` | `stale="revalidate", stale_ttl=N` | :white_check_mark: | 無（僅寫入標頭）：伺服器端快取不會回傳過期內容。 |
| `stale-if-error` | `stale="error", stale_ttl=N` | :white_check_mark: | 無（僅寫入標頭）：handler 失敗時不會改用快取回應。 |
| `s-maxage` | — | :x: | — |
| `proxy-revalidate` | — | :x: | — |
| `no-transform` | — | :x: | — |
| `must-understand` | — | :x: | — |

請求端的 `Cache-Control`（例如瀏覽器強制重新整理時送出的 `no-cache`、`max-age=0`）不會改變 `@cache` 的行為。這是刻意的設計：若請求標頭能繞過快取，任何用戶端都能讓每個請求直接打到 handler。條件式請求仍會處理：`If-None-Match` 相符時回 304。

## 安裝指南

Expand Down
Loading