tiny-cdn v0.7.0

tiny-cdn

A tiny static files serving handler

About

This module has been developed on top of holdon utility.

While this script is the fastest on Internet of Things devices such Arduino Yun or Raspberry PI, it has also been tested on regular servers and it has demonstrated to be both reliable and on average 2X or more faster than common nodejs solutions.

How to install

npm install -g tiny-cdn

The Module API

Used as module, tiny-cdn exports a function with a public .create method which is simply an alternative way to invoke the module.

The function will return a function usable as serving middle-ware.

var
  tinyCDN = require('./tiny-cdn'),
  siteCDN = tinyCDN({ ..configuration object ..})
;
require('http')
  .createServer(function (request,  response) {
    if (/^\/(?:js|css|img|assets)/.test(request.url)) {
      siteCDN(request,  response);
    } else {
      // dynamic content generation in here
    }
  })
  .listen(8080, '0.0.0.0')
;

If the purpose of the machine is to serve static files only, this is also possible.

require('http')
  .createServer(require('./tiny-cdn').create({
    // the configuration object
  }))
  .listen(8080, '0.0.0.0');

The Configuration Object

tinyCDN({...}) function accepts a configuration object. Following a description of all accepted properties:

var tinyCDN = require('./tiny-cdn').create({


  // where are original files ?
  // this should be the root of client requests
  // as example, /js/main.js should be a file
  // originally saved in ./source/js/main.js
  // the folder does not have to be publicly reachable
  source: './source',


  // where should ETags and Compressed files be stored ?
  // this folder will be populated with respective etags
  // per each requested file and their gzip or deflate version
  dest: './dest',


  // optional, if specified will create
  // gzip and deflate version of every request
  // in case the requesting UA is compatible.
  //
  // If specified as string,
  // it can be one of these values:
  //    best     // best compression
  //    speed    // fastest compression
  //    default  // default compression
  //    no       // no compression ( kinda pointeless )
  //
  // If specified as number,
  // it could be an integer from 1 to 9
  // that will mirror the compression level
  // accordingly with current zlib API compression values
  compression: 'best',

  // optional, if specified will activate compression
  // and it will perform it only for the list of known extensions
  // such list can be passed as Array of extensions
  // with values like 'txt' or '.css'
  // by default, if compression is enabled,
  // the list of known files will be the following one
  compress: [
    'js', 'css', 'txt', 'html',
    'svg', 'md', 'htm', 'xml', 'json', 'yml'
  ],

  // optional, if specified will create
  // an etag related file per each request kind
  // (raw, gzip, deflate)
  // it can be any valid crypt hash
  // and by default it will be the sha256 one
  etag: 'sha256',


  // optional, if specified will limit
  // the amount of connection that cpould be piped
  // as streams when any file is served
  maxListeners: Infinity, // as deafault


  // optional, if specified will define
  // the masimum age any  ETag should last
  maxAge: 30672000, // as deafault


  // optional, if set every file will send
  // the Access-Control-Allow-Origin header
  // with the specified value
  accessControlAllowOrigin: '', // as deafault


  // if cluster is used and you'd like
  // to not use optimizations made for multiple workers
  // feel free to force this flag to true (false by default)
  ignoreCluster: false, // as deafault

  // optional, if specified will define
  // the Not Found content per each page
  // served accordingly with common readind standards
  404: {

    // either html or HTML, could be any HTML page
    html: 'Not Found',
    // or
    HTML: 'Not Found',

    // either json or JSON, could be any JSON
    json: '{"error":"Not found"}',
    // or
    JSON: '{"error":"Not found"}',

    // either txt or TXT, could be any TXT
    txt: 'Not Found',
    // or
    TXT: 'Not Found'
  },


  // optional, if specified will be invoked
  // every time an erro occurs.
  // by default tinyCDN will take care of everything
  onError: function (
    // the error that triggered this callback
    err,
    // the requested url that generated the error
    url,
    // the list of requestes waiting for a response.
    // do not use an error handler if you don't have
    // a good way to serve failures.
    // Use simply `onResponse` handler instead
    // to be notified, if that's what you are looking for
    held
  ) {
    // do your stuff here ...
  },


  // optional, if specified will be invoked
  // every time a request completes.
  // It will eventually provide the error object
  // and the url as second argument.
  // But there won't be anything to do once this triggers
  onResponse: function (
    // the error, if any, that happened while serving
    err,
    // the url that successfully, eventually, got delivered
    url
  ) {
    // do your stuff here ...
  }
});

The CLI API

If used directly as executable, tinyCDN is capable of creating an http or https server, pre-build a file and its compressed versions, or generate a configuration JSON/object content to read and test.

./tiny-cdn [run] [options]

Mandatory options

  -s | --source           the source folder with static content
  -d | --dest             the destination folder for ETags / gzip

Configuration options

  -c | --compression      use compression and optionally specify its level
                          best, speed, default, or an integer
  -cl | --compress-list   a comma separated list of extension to compress
  -e | --etag             use etag and optionally specify its algorithm
                          by default it's sha256
  -ma | --max-age         the cache max-age header in seconds (default: 30672000)
  -ml | --max-listeners   the maximum amount of listeners to use per each stream
                          by default there is no limit
  -ic | --ignore-cluster  if true (or empty) will never use master/cluster logic

SSL options

  -ssl-cert               will use the provided cert file to run HTTPS instead of HTTP
  -ssl-key                will use the provided key file to run HTTPS instead of HTTP

Network options

  -h | --host | -ip       if specified, will be used as server address
  -p | --port             if specified, will be used as port

Build file option
  -b | --build            if specified will pre build a file
                          creating in the destination folder
                          the gzip and deflate version of the file
                          plus the ETag per each version

run examples

This is the minimum requirement to run an http server:

tiny-cdn run

Above snippet will start tinyCDN static file serving in the current folder without creating etags or compressed files. Handy to quickly test some directory content statically.

Please note that point at a generic /folder/ will automatically check for an index.html file within that folder.

Reaching the default shown url will also look for an index.html file and will return a Not Found error if none is provided.

It is possible to specify both source and destination though:

tiny-cdn run -s=./source -d=./dest

To use compression and etags, we can add related flags too:

tiny-cdn run -s=./source -d=./dest -e -c

To use a specific version of the etag or compression

tiny-cdn run -s=./source -d=./dest -e=md5 -c=speed

To specify a different host or port

tiny-cdn run -s=./source -d=./dest -h=192.168.1.10 -p=4321 -e -c

build examples

The build flag will create only what will be served to every request accordingly with the configuration options.

For instannce, assuming we have source/js/main.js file in the source folder, the following command will do basically nothing:

tiny-cdn -s=./source -d=./dest -b=/js/main.js

because neither etag nor compression flag is required.

However, if we use the ETag flag:

tiny-cdn -s=./source -d=./dest -b=/js/main.js -e

the builder will create the file ./dest/js/main.js.raw.sha256 with its ETag content.

Using the compression flag will create both gzip and deflate version of the file.

tiny-cdn -s=./source -d=./dest -b=/js/main.js -c

Now we'll have also ./dest/js/main.js.raw.gzip and ./dest/js/main.js.raw.deflate files.

Putting everything together will have also ./dest/js/main.js.raw.gzip.sha256 and ./dest/js/main.js.raw.deflate.sha256 files generated.

tiny-cdn -s=./source -d=./dest -b=/js/main.js -c -e

Running tinyCDN through SSL

If the -ssl-cert=file.crt and the -ssl-key=file.key are provided, the CLI will create a https server instead. Please note that if you created the certificate using your local network IP address, you might need to specify it as -h=192.168.1.5 in order to have a link in console that will point to the authorized page.

Otherwise you can always write down manually that IP address when visiting the CDN.

If you have no idea how to create a certificate, feel free to read this "How To" page.

Following an example on how to run SSL and HTTPS server

./tiny-cdn run \
  -s=source/ \
  -ssl-key=~/.server/192.168.1.5.key \
  -ssl-cert=~/test/https/192.168.1.5.crt \
  -h=192.168.1.5

# will log
# [tinyCDN] running on https://192.168.1.5:7151/

configuration example

In case you'd like to automatically generate a configuration file for your CDN, or simply read how it looks like, skip run and build options and just execute the cli

tiny-cdn -s=./source -d=./dest -c -e

/* [tinyCDN] */{
  "source": "/home/yourname/cdn/source",
  "dest": "/home/yourname/cdn/dest",
  "compression": "best",
  "etag": "sha256"
}

It is helpful to also understand defaults and verify folders.

tinyCDN and cluster

The main reason tinyCDN is 2X faster is disk access which, even if executed in an asynchronous non-blocking way, is usually repeated per each request.

All common operations like file stats access, runtime etag or gzip compression, and even piping the output, are performed through a single-request model, which will serve every other connection that meanwhile asked for the same file.

This is a great model specially on Internet of Things devices, where every disk operation might have a huge cost, specially the writing one.

When the cluster module is in place, we can use every available core to serve our CDN.

This is great, and it works already out of the box with common solutions, however there could be cases where a single file that should be compressed at runtime, will be asked potentially from different workers.

What usually happens is that each worker will perform the same operation if the file wasn't there, unable to know another worker maybe is going to create such file.

Due to the nature of cluster and workers, the holdon module (as it is) cannot coordinate in a single core requests from every CPU, so here it comes the converger, which role is to be a cluster director.

The Converger Utility

This helper does basically one thing: it forces asynchronous methods to be execute only in Master, providing a regular JS looking interface that is transparent to human eyes.

var
  cluster = require('cluster'),
  fs = require('fs'),
  numCPUs = require('os').cpus().length,
  Converger = require('tiny-cdn').Converger,

  // it should be defined no matter if this is master or worker
  // it will perform in master anyway
  master = new Converger({
    readFile: function (path, onFileRead) {
      // just to be sure we are reading from master
      console.log('reading from ' +
        (cluster.isMaster ? 'Master' : 'Worker'));
      fs.readFile(path, function (err, file) {
        onFileRead(err, err || file.toString());
      });
    }
  })
;

// if we have one CPU there's no  point to fork this process
if (cluster.isMaster && 1 < numCPUs) {
  while (numCPUs--) cluster.fork();
} else {
  // but even with a single CPU we can use Converger as it is
  master.readFile(__filename, function (err, content) {
    // however, if we have multiple cores
    // we will receive data per each of them
    console.log(
      'Read file with length ' + content.length +
      (cluster.isMaster ? '' :
        (' [worker ' + cluster.worker.id + ']'))
    );
  });
}

If we run above example we'll see this kind of output:

reading from Master
reading from Master
reading from Master
reading from Master
Read file with length 1098 [worker 2]
Read file with length 1098 [worker 1]
Read file with length 1098 [worker 3]
Read file with length 1098 [worker 4]

Which means the Converger instance worked as expected, but we have 4 workers asking for the same file so that in order to satisfy all of them the system will access and read from scratch each time.

Adding holdon to this equation will result in less reading operations.

// ...

  // let's hold on readFile
  heldFile = cluster.isMaster ?
    // since we'd like to do this on master only ...
    require('holdon').create(['callback']) : null,

  // it should be defined no matter if this is master or worker
  // it will perform in master anyway
  master = new Converger({
    readFile: function (path, onFileRead) {
      // absolute path is a unique identifier
      if (heldFile.add(path, onFileRead)) {
        // only if added as new record
        console.log('reading from ' +
          (cluster.isMaster ? 'Master' : 'Worker'));
        fs.readFile(path, function (err, file) {
          // per each worker waiting for a result
          heldFile.remove(path).callback.forEach(
            function (callback) {
              // send already processed arguments
              callback.apply(null, this);
            },
            [err, err || file.toString()]
          );
        });
      }
    }
  })

// ...

Accordingly with your machine performance, your output should be now like the following one:

reading from Master
Read file with length 1603 [worker 1]
Read file with length 1603 [worker 2]
Read file with length 1603 [worker 3]
Read file with length 1603 [worker 4]

Where reading from Master could happen twice and the workers order could be completely different.

reading from Master
reading from Master
Read file with length 1603 [worker 2]
Read file with length 1603 [worker 3]
Read file with length 1603 [worker 1]
Read file with length 1603 [worker 4]

In latter case two workers asked in different reading time the same file ... which is OK, it means my machine was that fast (cache).

Converger Performance

While this might not look like a huge win on the reading path, this might actually save your Raspberry PI, as well as your server, for all cases when you need some runtime operation like compressing and storing a file or creating its etag.

Those kind of slow operation that specially on SD cards might take "forever".

The writing is indeed a wonderful fit for Converger which is, together with holdon module, capable of bringing in a very good performance compromise even for IoT projects.

However, the serialization channel can be very slow, and serving files entirely read on a single thread broadcasted per each worker becomes a bottleneck, rather than a feature.

Accordingly, beside little content read, how an ETag could be, or some little information, as a fs.Stats object could contain, are a good fit for Converger pattern but every other reading should be avoided.

The tinyCDN strategy when it comes to file serving is to pipe all requests at once when the read stream is ready, and the etag has been retrieved.

The compression, and the etag generation, is done only once, holding every request.

I also need to better benchmark the get stats path and see if it makes sense to pass through the channel, or if I could simply use the thread for every read-only opration.

License

Copyright (C) 2015 by Andrea Giammarchi - @WebReflection

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.