void

Void

Void is a NodeJS module that intelligently invalidates your CloudFront Cache. It respects the following 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.

Follow your hosting provider's instructions for setting environment variables in production:

• Heroku
• AWS Elastic Beanstalk

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!

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
• 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 of CloudFront distribution id in source control

To do

• More tests
• Surface granual Job properties in Void constructor for more flexibility
• Void event callbacks
• Document Job object