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.
[default]
group:$ curl -is http://localhost:8088/something/to/purge -H "X-Broadcast-Group: default" -X PURGE
[prod]
group:$ curl -is http://localhost:8088/foo -H "X-Broadcast-Group: prod" -X BAN
$ curl -is http://localhost:8088/ -X PURGE
$ curl -is https://localhost:8443/ -X PURGE --cacert server.crt
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"
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.
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.
$ 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
}
$ 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
}
}
}
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":""
}
$ 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
}
}
$ 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. |