Skip to content

Add Cache-Control section and clarify caching directives #2092

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

Open
Artemiz0307 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add Cache-Control section and clarify caching directives #2092

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
28 changes: 28 additions & 0 deletions cheatsheets/HTTP_Headers_Cheat_Sheet.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,8 @@ Set the Content-Type header correctly throughout the site.

The `Referrer-Policy` HTTP header controls how much referrer information (sent via the Referer header) should be included with requests.



Copy link
Copy Markdown
Contributor

@maheshkukreja maheshkukreja Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Small nit: looks like a couple of extra blank lines got added here. Was this intended?

#### Recommendation

Referrer policy has been supported by browsers since 2014. Today, the default behavior in modern browsers is to no longer send all referrer information (origin, path, and query string) to the same site but to only send the origin to other sites. However, since not all users may be using the latest browsers we suggest forcing this behavior by sending this header on all responses.
Expand All @@ -62,6 +64,32 @@ Referrer policy has been supported by browsers since 2014. Today, the default be

- *NOTE:* For more information on configuring this header please see [Mozilla Referrer-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy).

### Cache-Control

The `Cache-Control` HTTP header defines how responses are cached by browsers and intermediate systems such as proxies.

Improper caching of sensitive content can lead to security issues such as data leakage or unauthorized access, especially when shared caches are involved.

Common directives include:

- `no-store`: Prevents the response from being stored in any cache. This is the safest option for sensitive data such as authentication responses or personal information.

- `no-cache`: Allows the response to be stored, but requires the cache to revalidate with the server before using it. This ensures that stale data is not served.

- `private`: Allows caching only in the user’s browser, but prevents storage in shared caches such as proxies.
Copy link
Copy Markdown
Contributor

@maheshkukreja maheshkukreja Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it make sense to add must-revalidate to the list as well? It's commonly paired with no-cache and private in practice, and without it some caches may serve stale responses after disconnecting from the origin. Something like: "must-revalidate: Once a cached response becomes stale, it must not be used without successful revalidation with the origin server."


Copy link
Copy Markdown
Contributor

@maheshkukreja maheshkukreja Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

RFC 9111 section 3.5 has specific rules about how shared caches must handle responses to requests containing an Authorization header. Since this section covers the private directive and shared caches, would it be helpful to add a note like: "Responses to requests with an Authorization header are not stored by shared caches unless explicitly allowed via public, must-revalidate, or s-maxage"? It's a common gotcha that catches people off guard

It is important not to confuse `no-cache` with `no-store`. While `no-cache` still allows storage under certain conditions, `no-store` completely disables caching.

#### Recommendation

For sensitive or user-specific content, use:

> `Cache-Control: no-store`

For content that can be cached per user but not shared:

> `Cache-Control: private`

### Content-Type

The `Content-Type` representation header is used to indicate the original media type of the resource (before any content encoding is applied for sending). If not set correctly, the resource (e.g. an image) may be interpreted as HTML, making XSS vulnerabilities possible.
Expand Down
Loading