RFC 5861

RFC 5861: HTTP Cache-Control Extensions for Stale Content ✨

• Author: Mark Nottingham, Yahoo! Inc. 🎀
• Category: Informational, as an Independent Submission 📚
• Date: May 2010 🗓️
• ISSN: 2070-1721
• Obsoletes / Updates: The header doesn't list any RFCs that this one obsoletes or updates 🙈

---

Abstract

okay bestie, this doc defines two independent HTTP Cache-Control extensions that let you control when caches are allowed to serve stale responses 🦋 ngl that's a whole vibe

Status of This Memo

this is not an Internet Standards Track spec, it's published just for info 📖 it's a contribution to the RFC Series, independent of any other RFC stream. The RFC Editor chose to publish it at their discretion and makes no statement about its value for implementation or deployment. Docs the RFC Editor approves aren't a candidate for any level of Internet Standard (see Section 2 of RFC 5741) 💅

for the current status, errata, and how to send feedback, check http://www.rfc-editor.org/info/rfc5861 🌸

Copyright Notice

Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved. 🔒

this doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as in effect on the publication date. Please read those carefully, bestie, because they spell out your rights and restrictions for this doc 🫶

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . 2
   2.  Notational Conventions  . . . . . . . . . . . . . . . . . . . . 2
   3.  The stale-while-revalidate Cache-Control Extension  . . . . . . 2
     3.1.  Example . . . . . . . . . . . . . . . . . . . . . . . . . . 3
   4.  The stale-if-error Cache-Control Extension  . . . . . . . . . . 3
     4.1.  Example . . . . . . . . . . . . . . . . . . . . . . . . . . 4
   5.  Security Considerations . . . . . . . . . . . . . . . . . . . . 5
   6.  Normative References  . . . . . . . . . . . . . . . . . . . . . 5
   Appendix A.  Acknowledgements . . . . . . . . . . . . . . . . . . . 6

1. Introduction ✨

okay so HTTP [RFC2616] says caches should "respond to a request with the most up-to-date response held... that is appropriate to the request," but it also allows a stale response to be returned "in carefully considered circumstances." 🧚 This doc adds two independent Cache-Control extensions that give you that control: stale-if-error and stale-while-revalidate 💜

stale-if-error lets a cache hand back a stale response when an error shows up (think a 500 Internal Server Error, a network segment going down, or a DNS failure) instead of passing along a "hard" error. Main character energy for availability 👑

stale-while-revalidate lets a cache instantly return a stale response while it revalidates in the background. That hides latency (both in the network and on the server) from clients, which is so iconic 🦋

2. Notational Conventions 💅

the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119] 📝

this spec uses the augmented Backus-Naur Form of RFC 2616 [RFC2616], and it includes the delta-seconds rule from that spec 🎀

3. The stale-while-revalidate Cache-Control Extension 🦋

when this shows up in an HTTP response, it tells caches they MAY serve that response after it goes stale, for up to the number of seconds given 🌈

stale-while-revalidate = "stale-while-revalidate" "=" delta-seconds

if a cached response gets served stale because of this extension, the cache SHOULD try to revalidate it while still serving stale responses (that means without blocking) 🔥

note that "stale" means the response will have a non-zero Age header and a warning header, as per HTTP's requirements 🙈

if delta-seconds passes without the cached entity getting revalidated, it SHOULD NOT keep being served stale, absent other information 💀

3.1. Example 🍓

a response containing:

Cache-Control: max-age=600, stale-while-revalidate=30

is fresh for 600 seconds, and it may keep being served stale for up to 30 more seconds while an async validation is attempted. If validation is inconclusive, or if no traffic triggers it, the stale-while-revalidate function stops working after 30 seconds, and the cached response is "truly" stale (so the next request blocks and gets handled normally) 😭

servers will usually want the combo of max-age and stale-while-revalidate to be the longest total potential freshness lifetime they can tolerate. For example, with both set to 600, the server must be able to tolerate the response being served from cache for up to 20 minutes ⭐

async validation only happens if a request comes in after the response has gone stale but before the stale-while-revalidate window closes. So the size of that window and how likely a request is during it decide how likely it is that every request gets served without delay. If the window is too small, or traffic is too sparse, some requests will fall outside it and block until the server validates the cached response 🫠

4. The stale-if-error Cache-Control Extension 🌸

the stale-if-error Cache-Control extension says that when an error is encountered, a cached stale response MAY be used to satisfy the request, regardless of other freshness info 💖

stale-if-error = "stale-if-error" "=" delta-seconds

when it's used as a request Cache-Control extension, its scope is the request it appears in. When it's used as a response Cache-Control extension, its scope is any request that applies to the cached response it's in 🧚

its value is the upper limit to staleness. When the cached response is more stale than that amount, the cached response SHOULD NOT be used to satisfy the request, absent other information ⚠️

in this context, an error is any situation that would result in a 500, 502, 503, or 504 HTTP response status code being returned 🚨

note that this directive does not affect freshness. Stale cached responses that do get used SHOULD still be visibly stale when sent (so, a non-zero Age header and a warning header, as per HTTP's requirements) 👀

4.1. Example 🎀

a response containing:

HTTP/1.1 200 OK
Cache-Control: max-age=600, stale-if-error=1200
Content-Type: text/plain

success

is fresh for 600 seconds, and it may be used if an error is hit after it goes stale for another 1200 seconds 🌈

so if the cache tries to validate 900 seconds later and gets:

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain

failure

the successful response can be returned instead:

HTTP/1.1 200 OK
Cache-Control: max-age=600, stale-if-error=1200
Age: 900
Content-Type: text/plain

success

once the age is greater than 1800 seconds (aka it's been stale for 1200 seconds), the cache must write the error message through 🥲

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain

failure

5. Security Considerations 🔐

the stale-while-revalidate extension gives origin servers a way to dictate that stale content should be served from caches under certain circumstances, with the expectation that the cached response will be revalidated in the background. It's suggested that this validation be predicated upon an incoming request, to avoid the possibility of an amplification attack (as can be seen in some other pre-fetching and automatic refresh mechanisms). Cache implementers should keep this in mind when deciding the circumstances under which they'll generate a request that isn't directly initiated by a user or client. ⚠️💀 this is serious bestie, no cap

the stale-if-error extension gives origin servers and clients a way to dictate that stale content should be served from caches under certain circumstances. It doesn't pose any additional security considerations beyond those of RFC 2616, which also allows stale content to be served 🫶

6. Normative References 📚

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119, March 1997.

[RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
           Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
           Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.

Appendix A. Acknowledgements 💜

thanks to Ben Drees, John Nienart, Henrik Nordstrom, Evan Torrie, and Chris Westin for their suggestions. The author takes all responsibility for errors and omissions 🙏

Author's Address 🌸

Mark Nottingham Yahoo! Inc.

EMail: mnot@yahoo-inc.com URI: http://www.mnot.net/