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: