ah-tdp-js-connector-plugin

#ah-tdp-js-connector-plugin

##Version Master: v0.1.2

##Semver This project aims to maintain the semver version numbering scheme.

##Changelog See the changelog file

##Overview An actionhero plugin provides an actionhero(/primus) javascript client instance with local caching (using localStorage) of action responses.

This plugin is a simplified/contextualised adaptation of RFC2616. The adaptations are intended to be pertinent to websockets and javascript:

• Hyphen-separated names are converted to camel-case e.g. "no-cache" becomes "noCache"
• The (frankly ugly and unwieldy) format of the Cache-Control HTTP header is split into an object: cacheControl:{maxAge:, noCache:...}
• Accordingly with the above adaptation of the Cache-Control header into object-form, parameters are rationalised into simpler to manage formats, mainly integers and booleans

##Request/response format As shown above, the Cache-Control header structure is ported into a more javascript-friendly object (default values shown):

// Requests
cacheControl:
{
    noCache:false // Boolean. Should a response be served from cache (if possible)
}

// Responses
cacheControl:
{
    // All server/connection types ("web", "websockets" and "TCP")
    maxAge:60, // Integer. Number of seconds for which the cached response will be valid
    noCache:false, // Boolean. Should the response be cached?

    // "Web" connections only (see below - "Real" HTTP headers)
    private:false, // Boolean. If true, the "private" (rather than "public") cacheability status will be set in the HTTP response header
    mustRevalidate:false // Boolean. If true, "must-revalidate" will be included in the HTTP response header
}

Note that the remaining RFC2616 elements are not implemented (yet).

##Features ###Actionhero client Uses the standard actionhero client library to establish a connection to the remote (server-side) actionhero instance.

###Server-side configuration An initiailiser pulls relevant/appropriate elements of the configuration file and presents them via a public, static JSON file

###Caching of action responses Response caching is configurable (server-side) via several methods which are evaluated in the following order:

1. The values of connection.cacheControl parameters. These are likely to be set by either pre/post processors or actions
2. The values of actionTemplate.cacheControl parameters. These are set directly in the action meta data (in the same way that inputs etc. are set in the actions file)
3. The values of the matching entry in the server-side config file for this plugin (in cacheControlMap)
4. The default values, set in the server-side config file for this plugin (in cacheControlDefaults)

Default values will be used for any parameters which are not set by 1-3 in the above list.

###"Real" HTTP headers If the server/connection type is "web" (i.e. not "TCP", "websocket" or a custom server) and createRealHTTPHeaders is true in the config file, this plugin will create a Cache-Control HTTP response header (overwriting any existing header if overwriteExistingHTTPCacheControlHeader is true). This is intended to level the playing field for non-websocket connections.

##Requirements Requirements are few:

• actionhero
• TDPBrowserCache / tdp-browser-cache - a simple javascript (client-side) caching library with a localstorage backend (which falls back to JSON storage if localStorage is not supported)

###Production requirements

###Development/test requirements

##Installation

npm install ah-tdp-js-connector-plugin

##Usage

##Configuration

##Credits

• /public/js/3rd-party/md5.js is an MD5 library written/ported by Sebastian Tschan and is available at JavaScript-MD5 on Github. It's released under an MIT license.

##To do/roadmap

• Support vary HTTP header and websockets equivalent
• IS THIS WORTH IT? THE FILE WOULD STILL NEED TO BE SERVED FROM AH BECAUSE OF BEING GENERATED...UNLESS WE COPY IT TO A WEB SERVER Include server connection config into front end JS and create generic script a la demo js
  • DONE generate file
• DONE Minify all JS
• Complete functionality
  • DONE action map for config via regex/glob
  • get server-side config into front end - needs XHR of some sort (or a probably iffy solution of e.g. creating a js file instead and setting a var to it).
  • DONE consider adding the rest of the RFC7234 params
  • Enable a mode which is the reverse of current - set JSON/websocket cacheControl headers based on HTTP headers
• Consider some sort of reverse setup - i.e. existing HTTP headers get ported into JS
• DONE Add logging (AH)
• Finish docs
• Create tests
• Add pkg json deps for testing etc.
• github/travis etc.
• Blog post on setting headers in AH

##Tests Tests currently run in a raw mode (simply running scripts which use process.exit() and the relevant exit code) and are run via Travis CI.

##License ah-tdp-js-connector-plugin 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.