From ed83aec75be817967cdac2663907d060fdc6adc3 Mon Sep 17 00:00:00 2001 From: Kornel Date: Sun, 1 Mar 2020 23:51:47 +0000 Subject: [PATCH] Explain trust server date --- README.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 2d37b3a..685aa55 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Can I cache this? [![Build Status](https://travis-ci.org/kornelski/http-cache-semantics.svg?branch=master)](https://travis-ci.org/kornelski/http-cache-semantics) -`CachePolicy` tells when responses can be reused from a cache, taking into account [HTTP RFC 7234](http://httpwg.org/specs/rfc7234.html) rules for user agents and shared caches. +`CachePolicy` tells when responses can be reused from a cache, taking into account [HTTP RFC 7234](http://httpwg.org/specs/rfc7234.html) rules for user agents and shared caches. It also implements [RFC 5861](https://tools.ietf.org/html/rfc5861), implementing `stale-if-error` and `stale-while-revalidate`. It's aware of many tricky details such as the `Vary` header, proxy revalidation, and authenticated responses. @@ -67,7 +67,6 @@ const options = { cacheHeuristic: 0.1, immutableMinTimeToLive: 24 * 3600 * 1000, // 24h ignoreCargoCult: false, - trustServerDate: true, }; ``` @@ -79,8 +78,6 @@ If `options.shared` is `true` (default), then the response is evaluated from a p If `options.ignoreCargoCult` is true, common anti-cache directives will be completely ignored if the non-standard `pre-check` and `post-check` directives are present. These two useless directives are most commonly found in bad StackOverflow answers and PHP's "session limiter" defaults. -If `options.trustServerDate` is false, then server's `Date` header won't be used as the base for `max-age`. This is against the RFC, but it's useful if you want to cache responses with very short `max-age`, but your local clock is not exactly in sync with the server's. - ### `storable()` Returns `true` if the response can be stored in a cache. If it's `false` then you MUST NOT store either the request or the response. @@ -189,8 +186,18 @@ if (!oldPolicy.satisfiesWithoutRevalidation(newRequest)) { - Requests for stale data. - Filtering of hop-by-hop headers. - Basic revalidation request +- `stale-if-error` ## Unimplemented -- Merging of range requests, If-Range (but correctly supports them as non-cacheable) +- Merging of range requests, `If-Range` (but correctly supports them as non-cacheable) - Revalidation of multiple representations + +### Trusting server `Date` + +Per the RFC, the cache should take into account the time between server-supplied `Date` and the time it received the response. The RFC-mandated behavior creates two problems: + + * Servers with incorrectly set timezone may add several hours to cache age (or more, if the clock is completely wrong). + * Even reasonably correct clocks may be off by a couple of seconds, breaking `max-age=1` trick (which is useful for reverse proxies on high-traffic servers). + +Previous versions of this library had an option to ignore the server date if it was "too inaccurate". To support the `max-age=1` trick the library also has to ignore dates that pretty accurate. There's no point of having an option to trust dates that are only a bit inaccurate, so this library won't trust any server dates. `max-age` will be interpreted from the time the response has been received, not from when it has been sent. This will affect only [RFC 1149 networks](https://tools.ietf.org/html/rfc1149).