The Insanity of the Vary Header

In my first deep dive into a HTTP header on the user-agent header I said that I would try and produce a series of posts going under the covers on certain HTTP headers.  This post is about the Vary header.  The Vary header both wonderful and sad at the same time.  I’ll discuss how to make it work for you and where it fails miserably.

The Vary header is used for HTTP caching.  If you want the really gory details of HTTP caching, you can find them here in,  Caching is hard, draw me a picture.  The short and pertinent part of that story is, when you make an HTTP request, it is possible that the response will come from a cache, rather than being generated by the origin server.  For the cache to know whether it can satisfy a response it needs a cache key.

Anatomy of a cache key

Cache entries have a primary cache key and potentially a secondary cache key.  The primary cache key is made up of a HTTP method and a URL.  For the vast majority of cases the HTTP method is a GET.  So, for the purposes of our discussion about the vary header, we can assume that the primary cache key is the URL of the HTTP resource. 

Assuming a resource identifies itself as cacheable, or at least, does not explicitly prevent it, a cache that sits somewhere between the client and the origin server, could hold on to a copy of the representation returned from the origin server and store it for satisfying future requests to the same URL. 

But we have variants

The challenge that we have is other HTTP headers can be used to request variations of the representation.  If we were to send Accept-encoding: gzip in our request, we are telling the server that we can handle the response being compressed.  What should the cache do?  Should it ignore the request and pass it along to the server.  Should it return the uncompressed version?  For compressed content, it might not be a big deal because if the client can handle compressed responses, it can also handle uncompressed responses, so whatever happens the client will be happy.  But what should the cache do with a compressed response that comes back from the origin server? Should it update the representation stored in the cache  with the new compressed one?  That would be a problem for future request from clients that do not have the ability to decompress responses.

The example of Accept-Encoding has lots of possible solutions.  However, a header like Accept-Language is more challenging.  If one user asks for a French version of a resource and another asks for an English version of a resource, only one can be stored in the cache if we limit ourselves to just the primary cache key.

We have the same problem if we just use the Accept header to do transparent negotiation between media types.  If one user asks for application/calendar+json and another asks for application/calendar+xml then we can only cache one of these at once.

Vary to the rescue

So far we have mentioned three different HTTP headers that could cause different variations of the resource to be returned.  We can use the Vary header in a response from a server to indicate which HTTP headers were used to produce the variation.

When a HTTP cache goes to store the representation it needs to look at the Vary header and for each header listed, look at the request headers that generated the response.  The values of those request headers are used as the secondary cache key.  The cache then uses this secondary cache key to store multiple variants for the same primary cache key.

When trying to satisfy a request from those stored, the cache will use the headers named in the Vary header of the stored variant to generate a new secondary cache key from the request.  If the secondary cache key generated from the request, match that of the stored representation then the stored representation can be served to the client.

Bingo! We can now cache all kinds of variants of our resource and the cache will know which one to serve up based on what the request asks for.

Sounds like a great idea, but…

Consider this request

> GET /test HTTP/1.1
> Host: example.com
> Accept-Encoding: gzip,deflate
>
< HTTP/1.1 200 OK
< Vary: Accept-Encoding
< Content-Encoding: gzip
< Content-Type: application/json
< Content-Length: 230
< Cache-Control: max-age=10000000

followed by

> GET /test HTTP/1.1 
> Host: example.com 
> Accept-Encoding: gzip 
> 
< HTTP/1.1 200 OK 
< Vary: Accept-Encoding
< Content-Encoding: gzip 
< Content-Type: application/json 
< Content-Length: 230 
< Cache-Control: max-age=10000000 

The first request would generate a secondary cache key of “gzip,deflate” because the Vary header declared by the server says that the representation was affected by the value of the Accept-Encoding header. 

In the second request, the Accept-Encoding header is different, because this client does not support the “deflate” method of compression.  Even though the cache is holding onto a perfectly good copy of the representation that is gzip compressed and the second client can process gzipped representations, the second client will not get that stored response served because the Accept-Encoding header of the request does not match the value in the secondary cache key.

Translated into English, if you don’t ask for exactly the same thing, you won’t get the cached copy even if is what you want.

Wait, it gets worse

Time passes, representations are cached, the origin server code is updated to be multilingual, and now the vary header that is returned includes both Accept-Encoding and Accept-Language.

A client makes the following request,

> GET /test HTTP/1.1
> Host: example.com
> Accept-Encoding: gzip,deflate
> Accept-Language: fr
>
< HTTP/1.1 200 OK
< Vary: Accept-Encoding, Accept-Language
< Content-Encoding: gzip
< Content-Language: fr
< Content-Type: application/json
< Content-Length: 230
< Cache-Control: max-age=10000000

The cache stores the representation using a secondary cache key of “gzip,deflate:fr”.  The same client then makes exactly the same request. Can you see a problem?

If we assume that the representation we stored, back when the vary header only contained Accept-Encoding, is still fresh then we now have two stored representations that match.  This is because when we compare this new request with the old stored representation, the vary header of the old representation only tells us to look at the Accept-Encoding header.

The guidance provided by the HTTP Caching specification tells us that we  MUST use the most recent matching response to satisfy these ambiguous requests.   This isn’t really a major problem for developers writing clients and servers, but it’s a pain for people trying to write caches.  In fact, I haven’t found a private cache implementation that actually does this yet.

Its not as simple as I make it out to be

I glossed over a number of additional issues mentioned in the spec.  When the vary header contains an asterisk, no variants are allowed to match.  I’m still trying to figure out why you would want to store a variant that will never match a request.

Also, I talked about generating the secondary cache key from the values in the request header.  Technically, before creating the secondary cache key, those header values should be normalized.  Which is a fancy term for stripping unnecessary whitespace, removing differences of letter casing when a header value is deemed case insensitive and other more insane requirements like re-ordering field values where the order is not significant.  You can imagine doing a vary on an accept header that lists a bunch of different media types and having to parse them and sort them before being able to do a comparison!

If you think the specification is bad, you should see the implementations

I can’t speak for implementations on all platforms, but the support for the vary header on the Windows platform is less than ideal.  Eric Lawrence covers the details of Vary in IE in a blog post.  It would not surprise me in the slightest if other platforms are similarly limited in their support for Vary.

Is there a point to this post?

I believe there are three points to this post: 

• Vary is a widely used HTTP header, so ideally developers should understand how it is supposed to work.
• Lots of people are gung-ho on transparent content negotiation.  Without a good working vary implementation, caching is going to be difficult.  That’s not good for performance.
• I’d like to point to a proposed alternative that solves many of the problems of the vary header, the Key Response Http Header.  I’ll have to save discussion of this solution for a future post.

Image Credit: Key https://flic.kr/p/56DLot
Image Credit: Rescue https://flic.kr/p/9w9doc
Image Credit: Accident https://flic.kr/p/5XfRKk
Image Credit: Road https://flic.kr/p/8GokGE