Nondeterministic Postrequisite Metaprotocol

    void

    1.0.2 • Public • Published

    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

    Install

    npm i void

    Homepage

    voidjs.com

    DownloadsWeekly Downloads

    24

    Version

    1.0.2

    License

    MIT

    Last publish

    Collaborators

    • edjboston