Internet DRAFT - draft-nottingham-http-invalidation
draft-nottingham-http-invalidation
Network Working Group M. Nottingham
Internet-Draft 21 August 2023
Intended status: Standards Track
Expires: 22 February 2024
An HTTP Cache Invalidation API
draft-nottingham-http-invalidation-01
Abstract
This document specifies an HTTP-based API that gateway caches (such
as those in reverse proxies and content delivery networks) can expose
to allow origin servers to their invalidate stored responses.
About This Document
This note is to be removed before publishing as an RFC.
Status information for this document may be found at
https://datatracker.ietf.org/doc/draft-nottingham-http-invalidation/.
information can be found at https://mnot.github.io/I-D/.
Source for this draft and an issue tracker can be found at
https://github.com/mnot/I-D/labels/http-invalidation.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 22 February 2024.
Copyright Notice
Copyright (c) 2023 IETF Trust and the persons identified as the
document authors. All rights reserved.
Nottingham Expires 22 February 2024 [Page 1]
Internet-Draft An HTTP Cache Invalidation API August 2023
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3
2. HTTP Cache Invalidation Resources . . . . . . . . . . . . . . 3
3. HTTP Cache Invalidation Event Format . . . . . . . . . . . . 4
3.1. Selector Types . . . . . . . . . . . . . . . . . . . . . 5
3.1.1. URI Selectors . . . . . . . . . . . . . . . . . . . . 5
3.1.2. URI Prefix Selectors . . . . . . . . . . . . . . . . 6
3.1.3. Origin Selectors . . . . . . . . . . . . . . . . . . 7
3.1.4. Group Selectors . . . . . . . . . . . . . . . . . . . 7
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
4.1. Media Types . . . . . . . . . . . . . . . . . . . . . . . 8
4.2. Cache Invalidation Selector Types . . . . . . . . . . . . 8
5. Security Considerations . . . . . . . . . . . . . . . . . . . 8
6. Normative References . . . . . . . . . . . . . . . . . . . . 8
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9
1. Introduction
Section 4.4 of [HTTP-CACHING] defines invalidation as the side effect
of a state-changing request on one or more stored responses in an
HTTP cache.
In practice, it has become common for caches to allow invalidation to
be triggered through other mechanisms -- often, using a dedicated
HTTP API. This is especially useful for caches that have a
relationship with the origin server and wish to offer them finer-
grained control, as is the case for reverse proxies and content
delivery networks.
While many such APIs already exist, they are proprietary. That makes
it difficult for the origin server or its delegates (for example,
content management systems) to take advantage of those facilities,
because each integration needs to created and maintained, hindering
interoperability.
Nottingham Expires 22 February 2024 [Page 2]
Internet-Draft An HTTP Cache Invalidation API August 2023
This document standardises an HTTP-based API for HTTP cache
invalidation. Section 2 describes an HTTP resource that accepts
requests to invalidate stored responses, using a format described in
Section 3.
1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
2. HTTP Cache Invalidation Resources
An HTTP Cache Invalidation Resource (hereafter, 'invalidation
resource') is an HTTP resource (Section 3.1 of [HTTP]) that has the
behaviours described in this section.
Invalidation resources SHOULD require requests to include some form
of authentication. The specific mechanism is out of scope for this
document, but note that [DESCRIPTION] describes a way to specify a
mechanism and credentials in the description format.
When an invalidation resource receives a POST request whose content
is in the format described in Section 3, its expected behaviour will
be to process the request and invalidate the responses it indicates
that are stored in the cache(s) associated with it.
As described in Section 4.4 of [HTTP-CACHING]:
invalidate means that the cache will either remove all stored
responses whose target URI matches the given URI or mark them as
"invalid" and in need of a mandatory validation before they can be
sent in response to a subsequent request.
This includes all responses for the URI, including those who have
cache keys that include information derived from the Vary response
field (see Section 4.1 of [HTTP-CACHING]).
The authenticated user MUST be authorized to perform each
invalidation. Unauthorized invalidations MUST be ignored; future
extensions might allow description of which invalidations succeeded
or failed.
Furthermore, some features in the event format described in Section 3
are not required to be implemented; for example, some event selector
types might not be supported, or the "purge" member might not be
Nottingham Expires 22 February 2024 [Page 3]
Internet-Draft An HTTP Cache Invalidation API August 2023
supported. An invalidation resource that receives a request using an
unsupported feature SHOULD respond with a 501 (Not Implemented)
status code.
TODO: specify a problem details object for these errors
If the cache is able to invalidate the indicated stored responses in
a reasonable amount of time (for example, 30 seconds), the
invalidation resource SHOULD respond with a 200 (OK) status code only
once all of those responses have been invalidated.
Otherwise (i.e., the cache cannot invalidate within a reasonable
amount of time, or cannot estimate how long invalidation will take),
it SHOULD immediately respond with a 202 (Accepted) status code.
This specification does not define a format for successful responses
from invalidation resources; implementations MAY send responses with
empty content. Future extensions might allow description of the
results of invalidation.
3. HTTP Cache Invalidation Event Format
The HTTP Cache Invalidation Event Format (hereafter, 'event format')
is a JSON-based [JSON] format that conveys a list of selectors that
are used to identify the stored responses in a cache, along with
additional instructions about the nature of invalidation being
requested.
Its content is an object with the following two required members:
* "type": a case-sensitive string indicating the selector type for
the invalidation event; see Section 3.1
* "selectors": an array of strings, each being a selector of the
indicated type.
For example, this document contains an event using the "URI" selector
type, and invalidates two URIs:
{
"type": "uri",
"selectors": [
"https://example.com/foo/bar",
"https://example.com/foo/bar/baz"
]
}
Nottingham Expires 22 February 2024 [Page 4]
Internet-Draft An HTTP Cache Invalidation API August 2023
Additionally, this document defines one optional member of the top-
level object:
* "purge": a boolean that when true indicates that the selected
stored responses should be removed from cache, rather than just
marked as invalid.
Support for purge is OPTIONAL. When a cache supports for purge, the
cache MUST remove the relevant response(s) from volatile and non-
volatile storage as promptly as possible, and if the cache indicates
success with a 200 (OK) status code, MUST do so before returning the
response.
Unrecognised members of the top-level object MUST be ignored, to
allow future updates of this specification to add new features.
3.1. Selector Types
This document defines the following cache invalidation selector
types:
3.1.1. URI Selectors
The "uri" selector type selects one or more stored responses by their
URI. When the invalidation event type is "uri", the content each
selector string MUST be either a URI [URI] or an IRI [IRI].
When a selector value is compared to a stored response URI to
determine whether it selects that response, the following process is
used:
1. If the selector value is a IRI, it is converted to a URI, per
Section 3.2 of [IRI].
2. Syntax-based normalization is applied to both the selector and
stored response URI, per Section 6.2.2 of [URI].
3. Scheme-based normalization is applied to both the selector and
stored response URI, per Section 6.2.3 of [URI].
For example, "https://www.example.com/foo/bar" selects stored
responses with the following URIs:
* "https://www.example.com/foo/bar"
* "HTTPS://www.example.com:443/foo/bar"
* "https://www.example.com/fo%6f/bar"
Nottingham Expires 22 February 2024 [Page 5]
Internet-Draft An HTTP Cache Invalidation API August 2023
* "https://www.example.com/fo%6F/bar"
* "https://www.example.com/../foo/bar"
* "https://www.example.com:/foo/bar"
... but does not select stored responses with the following URIs:
* "https://www.example.com/FOO/bar" (different path)
* "https://www.example.com/foo/bar/baz" (different path)
* "https://www.example.com/foo/barbaz" (different path)
* "https://www.example.com/foo/bar/" (different path)
* "http://www.example.com/foo/bar" (different scheme)
* "https://example.com/foo/bar" (different authority)
* "https://www.example.com/foo/bar?baz" (different query)
* "https://www.example.com/foo/bar?" (different query)
* "https://www.example.com:8080/foo/bar" (different authority)
3.1.2. URI Prefix Selectors
The "uri-prefix" selector type selects one or more stored responses
by their URI prefix. When the invalidation event type is "uri-
prefix", the content each selector string MUST be either a URI [URI]
or an IRI [IRI].
When a selector value is compared to a stored response URI to
determine whether it selects that response, the same normalization
process described in Section 3.1.1 is used. However, the selector
value is considered to be a prefix to match. Additionally, each
segment of the selector value's path must have a matching segment in
the stored response URI.
For example, "https://www.example.com/foo/bar" would select all of
the following URIs:
* "https://www.example.com/foo/bar"
* "https://www.example.com/foo/bar/"
* "https://www.example.com/foo/bar/baz"
Nottingham Expires 22 February 2024 [Page 6]
Internet-Draft An HTTP Cache Invalidation API August 2023
* "https://www.example.com/foo/bar/baz/bat"
* "https://www.example.com/foo/bar?"
* "https://www.example.com/foo/bar?baz"
... but does not match stored responses with the following URIs:
* "https://www.example.com/foo/barbaz" (last segment does not match)
ww.example.com/foo/BAR/baz" (second segment does not match)
3.1.3. Origin Selectors
The "origin" selector type selects all stored responses associated
with a URI origin (Section 4.3.1 of [HTTP]). When the invalidation
event type is "origin", the content of each selector string MUST be a
normalized (using the process defined in Section 3.1.1) URI prefix,
without a trailing "/". If the port is not present, it is assumed to
be the default port for the scheme.
For example, all of these are origin selectors:
* "https://www.example.com:443"
* "http://example.com"
* "https://example.net:8080"
3.1.4. Group Selectors
The "group" selector type selects all stored responses associated
with a group on a specified origin. When the invalidation event type
is "group", the content of each selector string MUST be a normalized
(using the process defined in Section 3.1.1) URI prefix with port
always present, and without a trailing "/". See Section 3.1.3 for
examples.
Additionally, when the invalidation event type is "group", the
document's root object MUST contain an additional member, "groups",
whose value is an array of strings that correspond to the group(s)
being invalidated, per [GROUPS].
For example:
Nottingham Expires 22 February 2024 [Page 7]
Internet-Draft An HTTP Cache Invalidation API August 2023
{
"type": "group",
"selectors": [
"https://example.com:443",
"https://www.example.com:443"
],
"groups": [
"scripts"
]
}
4. IANA Considerations
4.1. Media Types
_TBD_
4.2. Cache Invalidation Selector Types
_TBD_
5. Security Considerations
_TBD_
6. Normative References
[DESCRIPTION]
"*** BROKEN REFERENCE ***".
[GROUPS] Nottingham, M., "HTTP Cache Groups", Work in Progress,
Internet-Draft, draft-nottingham-http-cache-groups-00, 24
June 2023, <https://datatracker.ietf.org/doc/html/draft-
nottingham-http-cache-groups-00>.
[HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", STD 97, RFC 9110,
DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/rfc/rfc9110>.
[HTTP-CACHING]
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Caching", STD 98, RFC 9111,
DOI 10.17487/RFC9111, June 2022,
<https://www.rfc-editor.org/rfc/rfc9111>.
Nottingham Expires 22 February 2024 [Page 8]
Internet-Draft An HTTP Cache Invalidation API August 2023
[IRI] Duerst, M. and M. Suignard, "Internationalized Resource
Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987,
January 2005, <https://www.rfc-editor.org/rfc/rfc3987>.
[JSON] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/rfc/rfc8259>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.
[URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/rfc/rfc3986>.
Appendix A. Acknowledgements
Thanks to Stephen Ludin for his review and suggestions.
Author's Address
Mark Nottingham
Prahran
Australia
Email: mnot@mnot.net
URI: https://www.mnot.net/
Nottingham Expires 22 February 2024 [Page 9]
