README
¶
Purgery is a lightweight cache invalidation service intended to be ran alongside Varnish.
The problem
Some popular open source caching proxies don't offer official tools to issue cache purges across multiple instances.
If you run caches in multiple regions, you'll need something like this to ensure you aren't serving stale content to users.
Requirements
Purgery requires a Redis (version 6.2+) instance to distribute requests. Redis streams ensure that purge fails can be reliably delivered, and replayed from a checkpoint after outages.
Deployment
Purgery may be run as its own service, but you should ensure that it runs one instance per caching proxy instance, ideally in the same deployment region.
The following environment variables must be set in production:
REDIS_URL: Your Redis connection string (i.e:redis:///localhost:6379/0)VARNISH_ADDR: The Varnish server address this instance should target
Purgery only supports Varnish, and only versions that accept BAN verb requests over HTTP.
We provide a Varnish image with:
- Default configuration supporting BAN requests over HTTP
- An option to run Purgery in the same container alongside Varnish
Issuing cache invalidation requests
Cache invalidation is achieved by a single XADD command sent to the Redis purgery:purge key. See purge.sh.
XADD takes two arguments:
MINID: Timestamp in the past at which previous entries should be truncated. This is used as a simple mechanism to keep the stream from filling up indefinitely.url: Full URL to be purged. For now, the default Varnish configuration only supports purging entire domains. The path is ignored.
Deploying in Fly.io
Optionally, you can set PROXY_APP_NAME when deploying on Fly.io to automatically set VARNISH_ADDR to the instance of that Fly app in the same region as Purgery.
A sample Fly.io setup is coming soon.
Development
An example stack can be run with docker-compose up, and purges may be performed using the purge.sh script.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
cache
Package cache implements integrations with Redis.
|
Package cache implements integrations with Redis. |
|
common
Package common implements functionality consumed by other packages.
|
Package common implements functionality consumed by other packages. |
|
env
Package env implements environment-related functionality.
|
Package env implements environment-related functionality. |
|
log
Package log implements logging functionality.
|
Package log implements logging functionality. |
|
rest
Package rest implements the embedded REST server.
|
Package rest implements the embedded REST server. |
|
rest/internal/render
Package render implements rendering helpers.
|
Package render implements rendering helpers. |
|
safe
Package safe implements secure functionality.
|
Package safe implements secure functionality. |
|
pkg
|
|
|
client
Package client implements a purgery client.
|
Package client implements a purgery client. |