Void
Void is a NodeJS module that intelligently invalidates your CloudFront cache. It respects the following CloudFront limitations:
- Hard limit of 1000 paths per invalidation
- Only 3 invalidations can run at the same time (and other processes may be creating them too)
- There is no callback for the native AWS SDK, so the API must be polled
Installation
$ npm install void
Void relies on the AWS-SDK, which requires that you set two environment variables:
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
You can export them in the shell for local testing or permanent use. You can also load them into your environment using a tool like supervisor or foreman to load an .env file.
Void requires a third environment variable that contains the CloudFront distribution id:
DISTRIBUTION_ID
WARNING: Do not place your AWS credentials or CloudFront Distribution ID in source control!
Follow your hosting provider's instructions for setting environment variables in production:
Usage
Require void at the top of your script.
var Void = require('void');
Call the constructor with the new
keyword.
var v = new Void();
Note: Use a capital "V" for the constructor and a single, lowercase "v" to avoid collision with the reserved word "void".
Arguments
- name: will default to a 5 character string for logging
- distribution: will default to
process.env.DISTRIBUTION_ID
- paths: Array of path strings to be cleared (this will default to
"/*"
and clear the entire distribution) - dirs: Array of directories to be scanned and added to
paths
- poison: Array of path strings to be removed from
paths
- maxPaths: Max number of paths per invalidation (defaults to 1000)
- maxJobs: Max number of simultaneous invalidations (defaults to 3)
Properties
- queue: Queue of invalidations
- cloudfront: The AWS-SDK object
Example
We can change the default maxPaths
method to see some complex behavior:
var v = new Void({
paths : [
'/index.html',
'/index2.html',
'/foo/bar.html',
'/foo2/bar2.html'
],
maxPaths : 1
});
This will result in the the following console output:
[Void:IWZ33] Created 4 item(s) in the queue
[Void:IWZ33][Job:H27NL] Invalidation "IVBLZ2PCXZL5Q" created. Checking in 10 minute(s)...
[Void:IWZ33][Job:JD9ZU] Invalidation "I35PDGSFYBCA1X" created. Checking in 10 minute(s)...
[Void:IWZ33][Job:H1C3R] Too many invalidations, retrying in 2 minute(s)
[Void:IWZ33][Job:H1C3R] Too many invalidations, retrying in 2 minute(s)
[Void:IWZ33][Job:H1C3R] Too many invalidations, retrying in 2 minute(s)
[Void:IWZ33][Job:H1C3R] Too many invalidations, retrying in 2 minute(s)
[Void:IWZ33][Job:H1C3R] Too many invalidations, retrying in 2 minute(s)
[Void:IWZ33][Job:H27NL] In progress, re-checking in 2 minute(s)...
[Void:IWZ33][Job:JD9ZU] In progress, re-checking in 2 minute(s)...
[Void:IWZ33][Job:H1C3R] Too many invalidations, retrying in 2 minute(s)
[Void:IWZ33][Job:H27NL] In progress, re-checking in 2 minute(s)...
[Void:IWZ33][Job:JD9ZU] In progress, re-checking in 2 minute(s)...
[Void:IWZ33][Job:H1C3R] Invalidation "I13B9HSQI6RO7J" created. Checking in 10 minute(s)...
[Void:IWZ33][Job:JD9ZU] Invalidation "I35PDGSFYBCA1X" completed!
[Void:IWZ33][Job:H27NL] Invalidation "IVBLZ2PCXZL5Q" completed!
[Void:IWZ33][Job:7BTD7] Invalidation "I3HRQCLJU7OSZ7" created. Checking in 10 minute(s)...
[Void:IWZ33][Job:H1C3R] Invalidation "I13B9HSQI6RO7J" completed!
[Void:IWZ33][Job:7BTD7] In progress, re-checking in 2 minute(s)...
[Void:IWZ33][Job:7BTD7] Invalidation "I3HRQCLJU7OSZ7" completed!
[Void:IWZ23] All jobs complete!
Tests
Install the global dependancies with sudo permissions.
$ sudo npm install -g mocha
$ sudo npm install -g should
Run mocha directly to see the test results.
$ cd void
$ mocha
WARNING: Tests will fail unless you have the AWS_ACCESS_KEY_ID
, AWS_SECRET_ACCESS_KEY
, and DISTRIBUTION_ID
variables configured in your environment!
Notes
- You may incur charges if you invalidate your CloudFront cache frequently. Please see their documentation and pricing.
- Again… do NOT put your AWS credentials or CloudFront distribution id in source control.
To do
- Istanbul
- More tests
- Surface granular
Job
properties inVoid
constructor for more flexibility Void
event callbacks- Document
Job
object