Skip to content

edj-boston/void

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

99 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Void npm Build Status Coverage Status Dependency Status devDependency Status

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".

Options

name description default
accessKeyId The AWS Access Key ID process.env.AWS_ACCESS_KEY_ID
secretAccessKey The AWS secret access key process.env.AWS_SECRET_ACCESS_KEY
name Random name for logging, can be overridden Math.random().toString(36).substr(2, 5).toUpperCase()
distribution AWS distribution id process.env.DISTRIBUTION_ID
paths Array of paths to be cleared [ '/*' ]
dirs Array of local directories to be scanned and added to paths []
poison Array of paths to be removed from paths []
maxPaths Max number of paths per invalidation 2
maxJobs Max number of simultaneous Job objects 3
logger An optional log function console.log
cloudfront A credentialed AWS-SDK object new AWS.CloudFront()
createInterval Minutes to wait before retrying to create an invalidation 2
createTimeout Minutes to wait after 'running' status to quit trying to create an invalidation 30
checkDelay Minutes to wait before the first status check 10
checkInterval Minutes to wait between the 2nd and Nth status checks 2
checkTimeout Minutes to wait after the invalidation is created to quit and stop checking for progress 20
callback Function to call when completed null

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!

Development

Clone the repo, cd to your local copy, install deps, and run gulp:

$ cd void
$ npm install
$ gulp

Gulp will watch the lib and test directories, run tests, and display coverage data.

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

  1. You may incur charges if you invalidate your CloudFront cache frequently. Please see their documentation and pricing.
  2. Again… do NOT put your AWS credentials or CloudFront distribution id in source control.

To do

  1. Void event callbacks
  2. Document Job object

About

Easily invalidate your CloudFront Cache in NodeJS.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published