Fix misleading cacheByDefault documentation #4338
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| @@ -1103,7 +1103,7 @@ The `cache` interceptor implements client-side response caching as described in | |||
|
|
|||
| - `store` - The [`CacheStore`](/docs/docs/api/CacheStore.md) to store and retrieve responses from. Default is [`MemoryCacheStore`](/docs/docs/api/CacheStore.md#memorycachestore). | |||
| - `methods` - The [**safe** HTTP methods](https://www.rfc-editor.org/rfc/rfc9110#section-9.2.1) to cache the response of. | |||
| - `cacheByDefault` - The default expiration time to cache responses by if they don't have an explicit expiration. If this isn't present, responses without explicit expiration will not be cached. Default `undefined`. | |||
| - `cacheByDefault` - The default expiration time to cache responses by if they don't have an explicit expiration and cannot have an heuristic expiry computed. If this isn't present, responses neither with an explicit expiration nor heuristically cacheable will not be cached. Default `undefined`. | |||
There was a problem hiding this comment.
Any suggestion of a better wording is welcome. I do not find this easy to understand. But my attempts to make it more straightforward resulted in a lot more sentences, which ends up no better.
6 tasks
|
Actually I find it surprising to have heuristic caching enabled by default in a shared cache (shared in most case at least). I was not expecting to have heuristic caching at all in the cache interceptor. And I wonder if that is really a desirable default feature of it. Also see #4335. Correctly supporting heuristic caching while not disabling more desirable caching (in my opinion at least) like caching of responses with explicit caching directive (but non heuristically cacheable status) is a bit complicated. |
metcoder95
approved these changes
Jul 17, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This relates to...
The
cacheByDefaultstates:That is wrong. If the response has a
last-modifiedheader, an heuristic expiry will be used by current Undici code base instead ofcacheByDefault. If the response is heuristically cacheable, it will be cached even ifcacheByDefaultis undefined.See
https://github.com/nodejs/undici/blob/4608ef157cc75d5ce3d2802e6949cb865d73146c/lib/handler/cache-handler.js#L346C26-L358
https://github.com/nodejs/undici/blob/4608ef157cc75d5ce3d2802e6949cb865d73146c/lib/handler/cache-handler.js#L115C1-L125C6
Changes
cacheByDefaultabout heuristic caching.Features
N/A
Bug Fixes
Breaking Changes and Deprecations
N/A
Status