syntagma-versions

Syntagma/Matias Liwski forked original project to extend functionality. If manufacturer accept our new features, we will merge projects. For now, is a separate npm module because we need it for our own products.

Next, original documentation of manufacturer:

Versions is a simple but powerful node.js module that allows you to create a flexible static server or content delivery network. Serving static assets is a pain in Node, it's not something it focuses on and everybody advises you to setup a static server using NGINX or implement a cache proxying using Varnish or Squid. The biggest advantage that these servers have is that they support sendfile for sending static assets and is generally agreed upon that this is "The Best" method for sending static data. But Node doesn't have this advantage, it's removed from the core "due to reasons" and the only way to get decent file serving performance is to do aggressive caching of the assets in memory to reduce I/O operations as well as optimize for cache hits inside the browser or using conditional requests. And that is the goal of this project, cache all the things!

Build status

Please note that the build status only displays the status of the GitHub master branch. New stable versions are only released once the master passes all tests.

Features

Versions comes with tons of features to make it easier for you to set up a simple static server. We try to support as many features as a normal paid CDN would provide for you.

Origin Pull

In addition to serving files from disk you can also configure versions to pull static content from an origin server. This way you don't have to upload you static assets to a separate server in order to get them cached.

Set caching headers for files

In order to reduce the amount of HTTP requests that a browser would do for your files, versions automatically sets the appropriate caching headers. This way you assets will be served from the browser cache instead of the server.

Advanced gzipping

Gzip is enabled on every compatible file format, even if the origin server doesn't support gzip. In addition to that, we have disabled gzip for IE 5 and IE6 without service pack 2 as it is known to improperly cache it. We also have detection for obfuscated gzip headers as researched by the Yahoo performance team.

REST API for managing your server

You can communicate with the server using a REST API. You can inspect items from the cache, see what keys are cached or flush the server. The possibilities are endless.

Metrics

Everybody loves stats, that's why we are gathering metrics about the requests and the state of the server. These metrics can be accessed through the REST API.

Client API

Versions comes with a dedicated client that can communicate with it's REST API's or through Pub/Sub.

Synchronisation

Synchronises configuration and versions number between different connected consumers to ensure that they are all hitting the same cached version.

Love

It's crafted and engineered with love, what else do you need?

Installation

Installation is done through the node package manager (npm)

npm install versions --save

The --save tells npm to automatically add this file to the dependencies object of your package.json file.

API references

The API references are generated from the source's JSDoc comments:

• Server API reference
• Client API reference

Configuration

The server can be configured in 2 different ways or a hybrid of both. It has a dedicated configuration file called versions.json that lives in the root of your application folder (the application folder is the folder that contains your node_modules folder). But you can also configure the module through a chainable API. And the last would be a hybrid of those. Using a configuration file and using the API to override some of the configuration values.

<pre>versions.set('auth', 'Sup3rSecr3tP4z5w0rdy0');</pre>

<pre>versions.set('blacklisted extensions', ['.conf', '.log', '.gz']);</pre>

<pre>versions.set('cors', '*.example.com');</pre>

<pre>versions.set('directory', './public');</pre>

<pre>versions.set('force extensions', false);</pre>

<pre>versions.set('expire internal cache', '2 days');</pre>

<pre>versions.set('max age', '1 year')</pre>

<pre>versions.set('port', '8080');</pre>

<pre>versions.set('origin servers', { url: "http://example.com", name: "foo" });</pre>

<pre>versions.set('version', '0.0.0');</pre>

<pre>versions.set('aliases', 'http://example.org');</pre>

<pre>versions.set('log level', 'debug');</pre>

<pre>versions.set('plugins', [{ name: 'logger', config: 'short' }, 'logger']);</pre>

<pre>versions.set('sync', true);</pre>

<ul>
  <li>
    <strong>host</strong>
    The host name of your redis server.
  </li>
  <li>
    <strong>port</strong>
    The port number of your redis server.
  </li>
  <li>
    <strong>auth</strong>
    Optional auth/password to access your redis server.
  <li>
    <strong>namespace</strong>
    The key that should be used to store the configuration and be used as the
    channel name for the pub/sub channel. Defaults to <code>versions</code>
  </li>
</ul>

versions.json

When you require the versions module it will try to find a versions.json (or versions.js with a module.exports pattern) file in your root folder and use this as default configuration.

{
  "auth": "my-secret-auth-key",
  "blacklisted extensions": [".foo", ".conf"],
  "cors": "*",
  "directory": "./public",
  "expire internal cache": "1 hour",
  "max age": "30 days",
  "origin servers": [
    { "url": "https://www.nodejitsu.com", "id": "home" },
    { "url": "https://webops.nodejitsu.com", "id": "webops" }
  ],
  "port": 8080,
  "plugins": [
    "logger",
    "custom-nodejs-module",
    { 
      "name": "custom-nodejs-module",
      "config": {
        "custom": "configuration options that will be feed in to the middleware"
      }
    }
  ]
}

Configuration API

In addition to reading your versions.json file for the configuration it is also possible to set the configuration using dedicated API methods or the versions#set method. The versions#set method expects 2 arguments, the first argument is the name of the configuration key that you want to update and the second value is the actual value:

var versions = require('versions');

versions.set('auth', 'superSec3rtp4ssw0rd')

The API is also chainable, so you can do as many versions#set calls if needed. Versions also provides you with some API sugar to make configuring a bit more human readable:

versions.path('/public').expire('10 hours').set('sync', true);

The following API methods map directly to configuration (see versions.json configuration above for detailed information about what each configuration key triggers):

API | Configuration key ----------|------------------ path | directory lifetime | max age expire | expire internal cache

Server example

'use strict';

// require versions, if you have `versions.json` in the same folder as your
// `package.json` it will load that as default configuration for you
var versions = require('versions');

// If you don't have a versions.json or want to override some values:
versions.set('log level', 'debug')
        .set('auth', 'helloW0nderW0man');

// Or use some of the nicer API sugar
versions.path('./public').lifetime('30 days').expire('10 hours');

// After you have configured everything that you want just start listening on
// the server.
versions.listen(8080);

But it can be much shorter if you don't have to overide any configuration from your versions.json file:

require('versions').listen();

Rest API

GET /flush

Completely removes the internal cache. This does not flush cache-headers for the HTTP requests.

Returns:

{
  flush: 'OK'
}

GET /expire?key=

Removes the matched item(s) from the internal cache. It uses the value of ?key=key to find and match it against request URLS in the cache.

Returns:

{
  expire: 'OK',
  expired: 1
}

GET /inspect?key=

Finds the item in the cache and displays some information about it, like the total size of gzip, content-length etc.

Returns:

{
  key: 'name of the key',
  data: {
    'Content-Length': 0,
    'Content-Length Gzip': 0,
    'Content-Type': 'text/html',
    'Last-Modified': 'Sun, 31 Mar 2013 13:37:33 GMT'
  }
}

Or when a given key is not found:

{ inspect: 'Failed to find the requested key file in cache' }

GET /keys

Lists all items that are currently in the cache.

Returns:

{
  keys: [
    "versions:0.1.14#/css/jitsu.min.css",
    "#/id:home/img/sprite.png",
    "versions:0.1.14#/js/jitsu.min.js",
    "#/id:home/img/nodepm.png",
    "versions:0.1.14#/js/cortex.min.js",
    "#/id:home/img/trusted.png",
    "#/id:home/img/cloud.png",
    "#/id:home/webfonts/ss-standard.woff",
    "#/id:home/webfonts/ss-social-regular.woff",
    "#/id:home/webfonts/ss-social-circle.woff",
    "#/id:home/img/spinner.gif"
  ]
}

GET /version

Get the current version of internal cache.

Returns:

{ versions: '0.0.0' }

POST/PUT /version

Update the server to a new version number, if Redis sync is also the changes will also be synced with other instances.

Returns:

{ versions: '0.0.0' }

Or when no body is send:

{ error: 'Invalid body' }

GET /allowed-versions

Get the versioning allowed versions.

Returns:

{ 'allowed versions': ['0.0.1','0.2.0'] }

POST /version

Override server allowed versions with the allowed versions sent and the current version, if Redis sync is also the changes will also be synced with other instances.

Body:

{ 'allowed versions': ['0.0.1','0.2.0'] }

Returns:

{ 'allowed versions': ['0.0.1','0.2.0','0.0.0'] }

Or when no body is send:

{ error: 'Invalid body' }

PUT /version

Add sent allowed versions to the current allowed versions, if Redis sync is also the changes will also be synced with other instances.

Body:

{ 'allowed versions': ['1.0.1','3.2.1'] }

Returns:

{ 'allowed versions': ['0.0.1','0.2.0','0.0.0','1.0.1','3.2.1'] }

Or when no body is send:

{ error: 'Invalid body' }

DELETE /version (Content-type:text/plain)

Delete every allowed version except for current version, if Redis sync is also the changes will also be synced with other instances.

Returns:

{ 'allowed versions': ['0.0.0'] }

GET /metrics

Returns a bunch of metrics.

License

MIT