Caching for Too Long

Throughout this book, I’ve always kept the best interests of the website owner, developer, and sysadmin in mind. The reality is that the site, API, and application are primarily services that the end user consumes. In the end, it’s all about the end user.

• Why do we want to make the site fast? For the user!

• Why do we want to keep the site available? For the user!

• Why do we cache? So that the user has a good experience!

Caching data for too long would mess with the integrity of the data, giving the user a bad experience when up-to-date output is important. This is especially the case for news websites.

We already talked about the use of Cache-control and Expires headers. It’s important to estimate the right time-to-live and set the right values for these headers. The more accurate the time-to-live, the better the balance.

Unfortunately, in many cases the data will be out-of-date even before the object expires. Setting it to a lower value could jeopardize the health and responsiveness of your backend. Talk about being stuck between a rock and a hard place!

Worry not—Varnish has your back! Varnish offers various mechanisms to evict objects from the cache based on certain criteria. By accessing these eviction mechanisms from your code, you can actively invalidate objects, even if they haven’t expired. That way your breaking news will be correctly displayed on the front page of your website, even if the object still has two hours to live according to the time-to-live.

The Varnish documentation has a page dedicated to cache invalidation. Have a look if you’re interested.

Purging

Purging is the easiest way to invalidate the cache. In the following example, you can see that in VCL you can perform a return (purge) from within the vcl_recv subroutine. This will explicitly evict the object from cache. The object will be identified by the criteria set in vcl_hash, so by default that is the hostname and the URL. Memory is freed up immediately and cache variations are also evicted.

acl purge {
    "localhost";
    "192.168.55.0"/24;
}

sub vcl_recv {
    # allow PURGE from localhost and 192.168.55...

    if (req.method == "PURGE") {
        if (!client.ip ~ purge) {
            return(synth(403,"Not allowed."));
        }
        return (purge);
    }
}

There’s a bit more housekeeping involved when you want to do it right: the preceding example protects you from unauthorized invalidations by enforcing an ACL. Only purges from localhost or from the 192.168.55.0/24 subnet are allowed.

And then there’s the PURGE request method that is checked. By requesting the resource with PURGE instead of GET, you’re basically telling Varnish that this HTTP request is not a regular data retrieval request, but a purging request.

You can implement a purge call anywhere in your code and you’ll typically use an HTTP client that is supported by your programming language or framework. In many cases, that client will be cURL-based. Here’s a purging example using the cURL binary:

curl -XPURGE http://example.com/some/page

This example uses the -X parameter in cURL to set the request method. As expected, we’re setting it to PURGE and setting the URL to http://example.com/some/page. That’s the resource we’re removing from cache.

Banning

Purging is easy: it uses the object’s hash, it evicts just that one object, and it can be executed with a simple return(purge).

But when you have a large number of purges to perform or you’re not exactly sure which resources are stale, exact URL invalidations might feel restrictive to you. A pattern-based invalidation mechanism would solve that problem, and banning does just that.

Banning should not be an unknown concept to you; in “Ban”, we talked about the ban function that executes these bans.

Basically, bans use a regular expression match to mark objects that should be removed from cache. These marked objects are put on the so-called ban list. Banning does not remove items from cache immediately and hence does not free up any memory directly.

Bans are checked when an object is hit and executed accordingly based on the ban list. There’s also a so-called ban lurker background thread that checks for bans that match against any variable of the obj object.

Here’s a basic BAN example. It does exactly the same thing as the PURGE example, but adds URL pattern-matching capabilities:

acl ban {
    "localhost";
    "192.168.55.0"/24;
}

sub vcl_recv {
    if (req.method == "BAN") {
        if (!client.ip ~ ban) {
            return(synth(403, "Not allowed."));
        }
        ban("req.http.host == " + req.http.host +
            " && req.url ~ " + req.url);
        return(synth(200, "Ban added"));
    }
}

acl ban {
    "localhost";
    "192.168.55.0"/24;
}

sub vcl_backend_response {
  set beresp.http.x-host = bereq.http.host;
  set beresp.http.x-url = bereq.url;
}

sub vcl_deliver {
  unset resp.http.x-host;
  unset resp.http.x-url;
}

sub vcl_recv {
    if (req.method == "BAN") {
        if (!client.ip ~ ban) {
            return(synth(403, "Not allowed."));
        }
        ban("obj.http.x-host == " + req.http.host +
            " && obj.http.x-url ~ " + req.url);
        return(synth(200, "Ban added"));
    }
}

acl ban {
    "localhost";
    "192.168.55.0"/24;
}

sub vcl_backend_response {
  set beresp.http.x-host = bereq.http.host;
  set beresp.http.x-url = bereq.url;
}

sub vcl_deliver {
  unset resp.http.x-host;
  unset resp.http.x-url;
}

sub vcl_recv {
    if (req.method == "BAN") {
        if (!client.ip ~ ban) {
            return(synth(403, "Not allowed."));
        }
        if(req.http.x-ban-regex) {
            ban("obj.http.x-host == " + req.http.host + "
            && obj.http.x-url ~ " + req.http.x-ban-regex);
        } else {
            ban("obj.http.x-host == " + req.http.host + "
            && obj.http.x-url == " + req.url);
        }
        return(synth(200, "Ban added"));
    }
}

curl -XBAN http://example.com/ -H"x-ban-regex: ^/product/[0-9]+/details"

curl -XBAN http://example.com/product/121/details

varnishadm ban.list

Present bans:
0xb75096d0 1318329475.377475    10      obj.http.x-host == example.com
&& obj.http.x-url ~ ^/product/[0-9]+/details
0xb7509610 1318329470.785875    20C     obj.http.x-host == example.com
&& obj.http.x-url ~ ^/category

Banning from the Command Line

The previous two sections approached the execution of cache invalidation from an HTTP perspective, meaning that your regular requests and your purge/ban requests all pass through the same channel. I mentioned the upside: it’s very easy to code in VCL and just as easy to implement in your backend.

There are also some downsides:

• You have to write additional VCL code, which adds complexity.

• There is no uniform way of implementing banning and purging in Varnish; your application will depend on the invalidation implementation in VCL.

• Although the ACLs provide a level of security, there is no isolation from a networking perspective.

Luckily, Varnish offers an admin console that allows you to issue ban statements. This can be done locally or remotely through the varnishadm program. In “CLI address binding”, I mentioned how you can configure your Varnish to accept remote connections on the admin interface.

varnishadm is just a client that connects to the Varnish CLI socket. You can also make a TCP connection to this socket and issue ban commands directly from within your code. Have a look at the documentation page on the Varnish Command Line Interface to learn more about the commands, remote connections, and the authentication protocol.

Here’s an example of our product detail invalidation, but this time using the CLI:

varnishadm> ban obj.http.x-host == example.com && obj.http.x-url ~^/product/