score.varnish

A module for defining caching durations for your routes as well as sending cache invalidation requests to a running Varnish server. The Varnish server must be configured to be able to interpret the commands sent by this module correctly.

Quickstart

You will first need to configure your varnish servers in your score configuration file:

[score.init]
modules =
    score.varnish

[varnish]
servers = 127.0.0.1:80

You can now configure caching for your score.http routes:

from score.varnish import cache

@cache('5m')
@route('home', '/')
def home(ctx):
    return 'Hello World'

If you also configure your Varnish server to be able to accept HTTP requests with the custom HTTP verb PURGE, you can use this module to send such cache invalidation requests. You can find a short introduction to cache invalidation in Varnish in the varnish documentation:

# remove dead parrot
score.varnish.purge(path='^/parrot$')

Configuration

score.varnish.init(confdict)[source]

Initializes this module according to our module initialization guidelines with the following configuration keys:

servers []
A list of Varnish hosts interpreted via score.init.parse_host_port().
timeout 5s
The timeout for sending requests to a Varnish host passed to
header.domain X-Purge-Domain
The header used for communicating the domain to purge.
header.path X-Purge-Path
The header used for communicating the URL path to purge.
header.type X-Purge-Type
The header that controls the purge type.

Details

PURGE Headers

We have already mentioned, that the HTTP request will supply the custom verb PURGE. The following is the list of default headers sent with the request to control the operation:

X-Purge-Domain
A regular expression for desired domains. It is meant to purge something like .*\.montypython.com which would affect montypython.com as well as www.montypython.com and all other subdomains.
X-Purge-Path
A regular expression describing the paths to purge. The expression ^/python$ for example should solely purge one path.
X-Purge-Type
This header controls the type of the purge to perform, if your server supports more than one.

Command-Line Interface

Upon installation, this module registers a score.cli command that can be used to invalidate all your Varnish hosts at once:

$ score varnish purge --domain .*montypython.com
  --domain python.org --hard --timeout 3s ^/parrot ^/pythonland
HOSTS: localhost:6081
DOMAINS: .*montypython.com
         python.org
PATHS: ^/parrot
       ^/pythonland
Purge hard? [y/N]: yes
Purged hard: localhost:6081 python.org ^/parrot
Purged hard: localhost:6081 .*montypython.com ^/pythonland
Purged hard: localhost:6081 python.org ^/pythonland
Purged hard: localhost:6081 .*montypython.com ^/parrot

$ score varnish purge --host localhost:6081 ^/pythons
HOSTS: localhost:6081
DOMAINS: .*
PATHS: ^/pythons
Purge soft? [y/N]: y
Purged soft: localhost:6081 .* ^/pythons

$ score varnish purge
HOSTS: localhost:6081
DOMAINS: .*
PATHS: .*
Purge soft? [y/N]: yes
Purged soft: localhost:6081 .* .*

If you want to bypass the confirmation dialog, just append the yes option:

$ score varnish purge --yes
Purged soft: localhost:6081 .* .*

API

score.varnish.init(confdict)[source]

Initializes this module according to our module initialization guidelines with the following configuration keys:

servers []
A list of Varnish hosts interpreted via score.init.parse_host_port().
timeout 5s
The timeout for sending requests to a Varnish host passed to
header.domain X-Purge-Domain
The header used for communicating the domain to purge.
header.path X-Purge-Path
The header used for communicating the URL path to purge.
header.type X-Purge-Type
The header that controls the purge type.
class score.varnish.ConfiguredVarnishModule(servers, timeout, header_mapping)[source]

This module’s configuration object.

purge(*, domains=[], domain=None, paths=[], path=None, type=None, raise_on_error=True)[source]

Sends multiple purge requests to all configured Varnish servers with given keyword arguments for domains and paths. Each domain and path will result in a separate request to every configured Varnish host. All requests are sent asynchronously.

The keyword argument type sends the type of purge request to perform.

This method raises a PurgeError containing a list of PurgeError causes if one of the requests fails for any reason.

You can pass a domain and/or a path, …

# ...
varnish_conf.purge(domain='montypython.com', path='^/parrot$')

… lists of domains and/or paths …

varnish_conf.purge(domains=['montypython.com', 'python.org'],
                   paths=['^/parrot$', '^/asteroids', '.*game$'])

… or nothing at all (purging everything):

varnish_conf.purge()

Note that domains and domain are mutually exclusive (as are paths and path).

varnish_conf.purge(domain='python.org',
                   paths=['^/parrot$', '.*game$'],
                   type='hard')

or none of them, which ist the most unspecific solution and will purge all servers and all paths on each Varnish host. Use with caution.

varnish_conf.purge()
score.varnish.cache(duration)

Adds caching to a route by adding the Cache-Control header s-maxage to the response. The header is only added to responses of GET requests. The duration may be anything acceptable by score.init.parse_time_interval().

See Section 14.9.3 of RFC 2616 for the documentation of the s-maxage value.

class score.varnish.PurgeError(msg, causes=None)[source]

Thrown if a purge request failed.