]>

Prahran Australia mnot@mnot.net https://www.mnot.net/

Internet-Draft 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 Status information for this document may be found at . information can be found at . Source for this draft and an issue tracker can be found at .

Introduction 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. This document standardises an HTTP-based API for HTTP cache invalidation. describes an HTTP resource that accepts requests to invalidate stored responses, using a format described in . specifies a format that describes the capabilities and configuration of a cache's invalidation API, so that tools used by the origin server can easily consume it.

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 when, and only when, they appear in all capitals, as shown here.

HTTP Cache Invalidation Resources An HTTP Cache Invalidation Resource (hereafter, 'invalidation resource') is an HTTP resource () 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 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 , 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 :

• 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 ). 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 are not required to be implemented; for example, some event selector types might not be supported, or the "purge" member might not be 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.

HTTP Cache Invalidation Event Format The HTTP Cache Invalidation Event Format (hereafter, 'event format') is a JSON-based 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
• "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: 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.

When a cache indicates support for purge (see ) and purge is true, 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.

Selector Types This document defines the following cache invalidation selector types:

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 or an 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 .
2. Syntax-based normalization is applied to both the selector and stored response URI, per .
3. Scheme-based normalization is applied to both the selector and stored response URI, per .

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"
• "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)

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 or an 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 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"
• "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)

Origin Selectors The "origin" selector type selects all stored responses associated with a URI origin (). When the invalidation event type is "origin", the content of each selector string MUST be a normalized (using the process defined in ) 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"

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 ) URI prefix with port always present, and without a trailing "/". See 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 . For example:

Gateway Description Format To alloworigin servers and tools that they use to be easily configured, this document defines a Gateway Description Format that describes the configuration of an HTTP gateway (commonly, a "reverse proxy" or content delivery network). It is intended to be generated by gateways and made available out-of-band to origin servers using them. The format is based upon JSON . The root object can contain members with the following names and values:

• "generated": a string containing the date that the description was generated, in the IMF-fixdate format described in
• "description": a string containing a human-readable description of the gateway
• "invalidation": an invalidation description object (see below)
• "api-authentication": an API authentication description object (see below)
• "targeted-cc": an array of strings indicating the targeted cache-control header field(s) supported by the gateway, in order of precedence (i.e., first entry overrides later entries)
• "vendor": an object containing arbitrary, vendor-specific extensions

Invalidation description objects can contain the following members and values:

• "uri": a string conveying the URI of the Invalidation Resource ()
• "selectors": an array of strings indicating the selectors () that the Invalidation Resource supports
• "purge": a boolean indicating whether the Invalidation Resource supports the "purge" member in requests (see )
• "p95-latency": an integer indicating the number of milliseconds that 95% of invalidation requests should be fully applied to the scope indicated by the description.

API authentication objects can contain the following members and values:

• "bearer": a string containing a token to be used to authenticate to the API(s) described in the document, using Bearer HTTP authentication as described in

Unrecognised members of all of these objects MUST be ignored. New members may be introduced to them by updating this specification. For example:

IANA Considerations

Media Types TBD

Cache Invalidation Selector Types TBD

Security Considerations TBD

Normative References The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document defines HTTP caches and the associated header fields that control cache behavior or indicate cacheable response messages. This document obsoletes RFC 7234. This specification describes how to use bearer tokens in HTTP requests to access OAuth 2.0 protected resources. Any party in possession of a bearer token (a "bearer") can use it to get access to the associated resources (without demonstrating possession of a cryptographic key). To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport. [STANDARDS-TRACK] This specification defines a convention for HTTP response header fields that allow cache directives to be targeted at specific caches or classes of caches. It also defines one such header field, the CDN-Cache-Control response header field, which is targeted at content delivery network (CDN) caches. JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] This document defines a new protocol element, the Internationalized Resource Identifier (IRI), as a complement of the Uniform Resource Identifier (URI). An IRI is a sequence of characters from the Universal Character Set (Unicode/ISO 10646). A mapping from IRIs to URIs is defined, which means that IRIs can be used instead of URIs, where appropriate, to identify resources. The approach of defining a new protocol element was chosen instead of extending or changing the definition of URIs. This was done in order to allow a clear distinction and to avoid incompatibilities with existing software. Guidelines are provided for the use and deployment of IRIs in various protocols, formats, and software components that currently deal with URIs. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.

Acknowledgements Thanks to Stephen Ludin for his review and suggestions.