TDPAHDynamicPrePostProcessorLoader

Overview

TDPAHDynamicPrePostProcessorLoader is a dynamic pre/post processor loader for the actionHero API framework which allows usage of dynamic pre and post processor scripts i.e. action/version-specific pre/post processors. This module uses an ACL-like configuration method, allowing pre/post processor scripts to concentrate on their function rather than how/where they are applied and encourages modularisation of pre/post processors by freeing their scripted content from ties to action/version checking.

Version

Master: 2.0.2-beta use with caution!

Design goals

There are a few simple design goals on this project:

• To free processor module code from ties to evaluating which actions/versions to run under (thus making processor modules simpler, easier to maintain and more reusable)
• To do as much of the computationally expensive work as possible in the initialisation phase
• To create as little computational per-request overhead as possible
• To make configuration of matching up processors to run versus actions/versions simple and easy to read

Operating system support

Operating system support should not be a major issue for this module though I always mention in my projects for transparency that I do not design or test for correct function on non-*nix-like OS's (e.g. Windows). If you want to test/develop and submit pull requests for Windows support then I will certainly consider them but likely only if they have minimal to no impact on performance and reliability for *nix-like OSs. The reason for this is simply that I personally don't consider Windows to be a serious server operating system and thus a good direction in which to spend my time and i'm not trying to offend anyone. I realise that others may completely differ in opinion and you're always welcome (obviously) to fork the repo and create your own version with Windows support. If my time were unlimited then I would likely spend some time on Windows support but sadly it's not.

Dependencies

TDPAHDynamicPrePostProcessorLoader itself has few dependencies and although it is a module, it is designed only for use with actionHero. Dependencies are (NPM modules):

• path (core nodejs module) - filesystem paths
• util (core nodejs module) - utilities
• glob - file globber
• semver - semantic version numbering functions

Your pre/post processors may of course require further dependencies, these should be handled in the usual way (using npm install <MODULE-NAME> from the actionHero base directory and using var ModuleName=require(<MODULE-NAME>);) in your processor script).

Issues/problems

Please log any issues/problems in Github issues for this project.

Installation

Installation is simple, mainly via NPM:

1. Ensure you have installed actionHero and run the generate command as per the actionHero getting started guide
2. From your actionHero base directory (which contains e.g. the actionHero package.json and routes.js files) and install the NPM module: npm install tdp-ah-dynamic-pre-post-processor-loader
3. Run the tdp-ah-dynamic-pre-post-processor-loader installer script ./node_modules/tdp-ah-dynamic-pre-post-processor-loader/bin/install - this copies the initialiser to the actionHero "initializers" directory and creates pre/post processor container directories which contain some starter/example processors (which you can delete if you don't need them).

If you have issues with step 3, please ensure the user your are running the installer script with has necessary permissions on the directories - ideally you'd run it with the user who owns the actionHero base directory and files.

Usage/configuration

Once you have installed the NPM module and run the installer (step 3 above), you're good to go, so you can edit the config file which ends up in <actionHero root>/config/TDPAHDynamicPrePostProcessorLoader/TDPAHDynamicPrePostProcessorLoaderConfig.js. There are comments in the config file but the key part to edit are the actionProcessors which are defined in config.actionProcessors (a javascript object), format is:

config.actionProcessors=
{
    defaultParamAndResponseFilters:
    {
        actions:["*"], 
        preProcessors:["filterNonAsciiCharsInParams","forceLowerCaseParams"],  
        postProcessors:["filterNonAsciiCharsInResponses","forceLowerCaseResponses"]
    },
    navigationAndPageContent:
    {
        actions:["navigation","pageContent:>=1.0"],
        preProcessors:["forceUpperCaseParams"],
        postProcessors:["escapeResponses"]
    }
}

You'll notice that for action names, you can use the * wildcard parameter.

First dimension element names (in the example above, defaultParamAndResponseFilters and navigationAndPageContent) can be anything you like e.g. a useful reference or can be an integer in which case, it will determine the order of application of rules Details of parameters:

actions: array of colon-separated parameters as follows: 
    String <actionName>:[semantic version comparator <actionVersions>]
    
preProcessors: An array of processor module names (i.e. from exports.<MODULENAME>=function ... in your pre/post processor modules) which must be available via the paths defined in config.pathsToProcessorModules. NOTE: It doesn't matter what you name your closure

postProcessors: An array of processor module names (i.e. from exports.<MODULENAME>=function ... in your pre/post processor modules) which must be available via the paths defined in config.pathsToProcessorModules. 

NOTE: It doesn't matter what you name your closure If a processor returns false, processing of the action will cease and no output will be sent!

During initialisation, TDPAHDynamicPrePostProcessorLoader will scan through all the loaded actionHero actions and will determine which of your defined/configured pre and post processors should be run for each based on their action.name and action.version.

Processors are applied for each request/response from top (first) to bottom (last).

If any processor modules which are defined in your config cannot be located during initialisation and config.errorIf.processorFunctionDoesNotExist is true, an error will be thrown.

Writing pre/post processors for use with TDPAHDynamicPrePostProcessorLoader

Creating pre/post processors for use with TDPAHDynamicPrePostProcessorLoader is a little different to creating native actionHero pre/post processors. They must be a standard NodeJS module which contains a single function (using exports) and are still passed the same objects (along with the api object which is often needed if e.g. you want to acess objects/functions you have loaded onto the api object) but they do not need to call next(), instead they should return true unless a hard error occurs, in which case they should return false. An example of each is:

Pre-processor:

exports.examplePreProcessor=function examplePreProcessorFunction(api, connection, actionTemplate, callback)
{	
    // async (probably) function goes here...
    // ...it needs to return callback(err) where err is true for an error or false for OK/no error
};

Post-processor:

exports.examplePostProcessor=function examplePostProcessorFunction(api, connection, actionTemplate, callback)
{	
    // async (probably) function goes here...
    // ...it needs to return callback(err) where err is true for an error or false for OK/no error
};

Processor file paths/locations

Processor files must be located in a path defined in config.pathsToProcessorModules. This object has an element for preProcessors and one for postProcessors, these elements are both arrays so you can have multiple file paths/locations for each and the paths are glob'd so you can use the * wildcard.

The default file path/location for processors are <actionHero root>/preProcessors/*.js and <actionHero root>/postProcessors/*.js though you can override or add to these if you wish.

Bundled pre/post processors

There are a number of pre/post processors bundled, currently:

Bundled pre processors

• A
• B
• C

Bundled post processors

• A
• B
• C

Change history overview

• v2.0.0 - Changed pre/post processors to use a callback (and thus be async-friendly) and changed the function runner to be fully asynchronous, also improved the bundled files
• v1.0.0 - Added api as first parameter to the pre/post processor functions
• v.0.1.x - initial version

To do

• Log remaining issues and the below in github issues
• Create some example pre/post processors and add to this repo
• Ensure we clean up as much as possible after initialisation
• Check what happens for actions with no defined action.version
• Ensure that relevant errors are thrown in the right places (and not in the wrong places) and that we drop out of the processor chains when appropriate (cancelling the action request/response on serious errors if configured that way)
• Possibly create a pre/post processor generator
• Test NPM module installation
• Create some meaningful tests
• Integrate with travis
• Optimise code

License

TDPAHDynamicPrePostProcessorLoader is issued under a Creative Commons attribution share-alike license. This means you can share and adapt the code provided you attribute the original author(s) and you share your resulting source code. If, for some specific reason you need to use this library under a different license then please contact me and i'll see what I can do - though I should mention that I am committed to all my code being open-source so closed licenses will almost certainly not be possible.