Varnish Broadcaster

Examples

This section will highlight some of the simple use cases where the broadcaster can be used. While it was meant as a generic http distributor, its main purpose resides around the invalidation of cached content.

Varnish provides three mechanisms which enable caching invalidation: purging, banning and xkey. Note that the broadcaster is agnostic of any of the chosen invalidation methods, therefore your VCL will need to be aware of your invalidation intentions.

Here you will find a brief user guide which addresses both purging and banning.

Invalidation examples

Purge /something/to/purge in all the nodes defined in the [default] group:
$ curl -is http://localhost:8088/something/to/purge -H "X-Broadcast-Group: default"  -X PURGE
Ban /foo in all the nodes defined in the [prod] group:
$ curl -is http://localhost:8088/foo -H "X-Broadcast-Group: prod"  -X BAN
Purge everything across all your nodes:
$ curl -is http://localhost:8088/ -X PURGE
Purge everything across all your caches over https:
$ curl -is https://localhost:8443/ -X PURGE --cacert server.crt
Purge by xkey:

Xkey is an advanced method of purging, where objects in the cache are tagged with keys that can then be referenced in invalidation requests. More about Xkey here.

$ curl -is http://localhost:8088/foo -H "xkey-purge: a1b2c3d4f5g6"

Response samples

Output sample in synchronous mode:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 11 Dec 2017 12:34:33 GMT
Content-Length: 101

{
  "done": true,
  "method": "PURGE",
  "uri": "/foo/bar",
  "ts": 1512995646,
  "rate": 25,
  "nodes": {
    "Cache1": 503,
    "Cache2": 500,
    "Cache3": 503,
    "Cache4": 200
  }
}

Output sample in async mode:

HTTP/1.1 202 Accepted
X-Job-Id: 570204483
Date: Mon, 11 Dec 2017 12:20:59 GMT
Content-Length: 0
Content-Type: text/plain; charset=utf-8

When in async mode, the broadcaster returns imediatelly to the client with the status code of 202 and a X-Job-Id header. Use the value of this header in the /api/status endpoint to check whether the invalidation request has finished.

Status check.

The broadcaster exposes one /api/status endpoint which allows checking whether a specific invalidation request is done or not. The endpoint is available under the broadcaster’s management port.

Examples:

  • Check current running configuration:
$ curl http://localhost:8089/api/configuration
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Job-Id
Content-Type: application/json
Date: Wed, 12 Dec 2017 09:40:59 GMT
Content-Length: 313

{
    "Local": [
        {
            "address": "https://localhost:7081",
            "name": "beta"
        },
        {
            "address": "https://localhost:4443",
            "name": "charlie"
        },
        {
            "address": "https://localhost:6081",
            "name": "alpha"
        }
    ],
    "Remote": [
        {
            "address": "https://burlan.eu",
            "name": "second"
        },
        {
            "address": "https://apienginedemo.varnish-software.com",
            "name": "third"
        }
    ],
	"async": false
}
  • Check the status of all invalidation requests:
$ curl  http://localhost:8089/api/status
HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 11 Dec 2017 12:42:29 GMT
Content-Length: 574

{
  "510158363": {
    "done": true,
    "method": "PURGE",
    "uri": "/foo/bar",
    "ts": 1512995673,
    "rate": 25,
    "nodes": {
      "Cache1": 503,
      "Cache2": 500,
      "Cache3": 503,
      "Cache4": 200
    }
  },
  "752412541": {
    "done": true,
    "method": "BAN",
    "uri": "/foo/bar",
    "ts": 1512995630,
    "rate": 25,
    "nodes": {
      "Cache1": 503,
      "Cache2": 500,
      "Cache3": 503,
      "Cache4": 200
    }
  },
  "2377945909": {
    "done": true,
    "method": "PURGE",
    "uri": "/foo/bar",    
    "ts": 1512995637,
    "rate": 25,
    "nodes": {
      "Cache1": 503,
      "Cache2": 500,
      "Cache3": 503,
      "Cache4": 200
    }
  }
}
  • Broadcast a small payload:

In the below example, we’ll broadcast a small json payload against the /new/content endpoint on all configured nodes.

$  curl -is http://localhost:8088/new/content -d '{"foo":"bar"}' -H "Content-Type: application/json"
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Job-Id
Content-Type: application/json
Date: Mon, 26 Nov 2018 09:47:29 GMT
Content-Length: 357

{
	"method": "POST",
	"uri": "/new/content",
	"ts": 1543225649,
	"nodes": {
		"cache1": 503,
		"cache2": 500,
		"cache3": 500
	},
	"rate": 0,
	"done": true,
	"err":""
}
  • Check the status of a specific invalidation request which has finished:
$ curl -is http://localhost:8089/api/status?id=2377945909
HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 11 Dec 2017 12:42:43 GMT
Content-Length: 101

{
    "done": true,
    "ts": 1512995637,
    "method": "PURGE",
    "uri": "/foo/bar",    
    "rate": 25,
    "nodes": {
      "Cache1": 503,
      "Cache2": 500,
      "Cache3": 503,
      "Cache4": 200
    }
}
  • Check the status of a specific invalidation request which is still working:
$ curl -is http://localhost:8089/api/status?id=752412541
HTTP/1.1 202 Accepted
X-Job-Id: 570204483
Date: Mon, 11 Dec 2017 12:20:59 GMT
Content-Length: 0
Content-Type: text/plain; charset=utf-8

The status information for any invalidation request has the following structure:

Name About
method The HTTP method used for broadcasting.
uri The URI to be broadcasted against the configured nodes.
done Boolean telling whether the job batch has finished.
ts Unix timestamp which tells the time when a specific invalidation request has been sent onto the working channel.
rate Percentage which represents the quota of succesfull broadcasts. A broadcast is considered to have succeeded if its returned status code is 200.
nodes Dictionary representation of the nodes which have been broadcasted against along with their returned status codes.
err If present, this tag will contain errors occured at broadcast time.