Table of Contents
- ETags and Caching
- Optimistic Concurrency Control
- Weak ETag Headers
- Strong ETag headers (Enterprise Only)
Cloudflare supports both weak and strong ETag headers. Weak ETags can be used across all plan levels, and are supported by default. Strong ETags are for Enterprise customers only, require a Page Rule to activate, and will automatically deactivate Rocket Loader, Minification, Email Obfuscation, and Railgun. ETag headers can be used to identify versions of resources for caching, or optimistic concurrency control.
ETags and Caching
ETag headers can be used to identify a cached resource so that the server knows whether to send a newer version of the resource that is not already stored. The ETag field contains an arbitrary string value usually based on a hash of the content, though the actual value itself doesn't matter. The browser will store these ETags, and on subsequent requests it will send along an If-None-Match header with each of the ETag values the browser has encountered for that resource. If any of the ETag values in the header match the current version on the origin server, the server will send back a 304 Not-Modified HTTP response to indicate that the cached version is still valid. Otherwise, the server will send back the requested resource along with the new ETag value.
For example, suppose there is a ETag header set on the server side with the following value:
Then, the browser sends a GET request with an If-None-Match header holding these values:
GET /example.html HTTP/1.1 If-None-Match "asdf" , "qwerty"
In this case, the browser has already cached the latest version of the resource stored on the server indicated by the "qwerty" ETag value. The origin will then send back the 304 Not-Modified HTTP response, and the resource will revalidate in the cache.
Optimistic Concurrency Control
ETag headers can also be used to implement Optimistic Concurrency Control (OCC). This solves an issue where multiple requests attempt to update the same version of a resource at different times.
For example, suppose two people attempt to update a file. They grab the file at the same time, but one finishes before the other. Without some form of concurrency control, the latest update would overwrite any changes the first update had made without notifying the users that these earlier changes are now lost.
ETags can be used to prevent this using an If-Match header. In the above example, both users attempt to modify a version of the file that sends this header:
The first user to update will send a PUT request to modify the file, which contains an If-Match header with the same value:
PUT /example HTTP/1.1 If-Match: "zxcv"
Since the headers match here, the server will allow the update and return a "200 OK" response. The server will then generate a new ETag value to confirm that the resource has been modified:
Now when the other user attempts to update the file, they will send the previous ETag value in the If-Match header:
PUT /example HTTP/1.1 If-Match: "zxcv"
Since the ETag values do not match here, the server will not allow the update and will return a "412 Precondition Failed" response, notifying the user that the file has changed since it was last requested.
Simplified, the workflow would look like this:
What Are Weak ETag Headers?
Weak ETag headers indicate only the the two resources are semantically equivalent - ie. that they are basically the same and are practically interchangeable, though not necessarily byte-for-byte. They are indicated by a 'W/' before the value. For example:
Weak ETag headers are fully supported on Cloudflare by default, and are available for all plan levels.
Email Obfuscation and automatic https rewrites will need to be disabled, otherwise the ETag headers will be removed from the response. Email Obfuscation modifies the code significantly enough it cannot be considered semantically equivalent.
Note that if a resource is cacheable, and there is a cache miss, Cloudflare will not send ETag headers to the origin. This is because Cloudflare needs the full response body to fill the cache.
What Are Strong ETag Headers?
Strong ETag headers promise that the resource in the cache and the resource on the server are byte-for-byte identical, and as such can be used to cache partial responses to complete on later requests. Because of this, strong ETag headers cannot be used with any of our features that transform the response - Rocket Loader, Minification, Email Obfuscation, and Railgun will be automatically disabled when strong ETag headers are active. Cloudflare will also use the same HTTP Content-Encoding in the connection between Cloudflare and the origin as is used between the client and Cloudflare, so that the strong ETag won't be weakened.
Currently strong ETag headers are only supported for Cloudflare Enterprise customers, and need to be manually activated on URLs using a Page Rule. If a Page Rule is not set, then any strong ETag headers will be converted into weak ETag headers.
Using an ETag without quotes (
Etag: blah for example) causes the gzip module to remove a strong ETag instead of weakening it. Use quotes (
) for the strong ETag to weaken into
There is one very specific exception here. Cloudflare will allow Strong ETags for resources without the Page Rule set if and only if:
- The content has already been gzipped at the origin server
- The origin sent out the gzipped content with a strong ETag header, AND
- All of Cloudflare's performance features and apps are disabled
If all of these conditions are met, then the Strong ETag headers will be allowed since Cloudflare has not modified the content.