actionhero

remove SIGKILL from startCluster ans Start (single server)

• these signals do not work with node >= v0.9

Routes

• routes remain optional
• actions defiend in params directly action=theAction or hitting the named URL for an action /api/theAction will always override RESTful routing
• you can mix explicitly defined params with route-defined params. If there is an overlap, the route-defined params win
  • IE: /api/user/123?userId=456 => connection.userId = 123
  • this is a change from previous versions
• routes defined with the "all" method will be duplicated to "get", "put", "post", and "delete"
• use ":variable" to defined "variable"
• undefined ":variable" will match
  • IE: "/api/user/" WILL match "/api/user/:userId"
• routes are matched as defined here top-down
• you can optionally define a regex match along with your route variable
  • IE: { path:"/game/:id(^[a-z]{0,10}$)", action: "gamehandler" }
  • be sure to double-escape when needed: { path: "/login/:userID(^\d{3}$)", action: "login" }

General

• tasks will now log thier params when starting
• tasks will now log thier duration when complete

Bugs

• re-enabled the welcome message in websocket clients, and used this as the connection trigger rather than a timer
• added a welcome event websocket clients

Windows

Using the unstable readline module, catching of sigint on windows can be achieved. This allows for a graceful shutdown.

Action PreProcessor

You can overwrite the stub method api.actionProcessor.prototype.preProcessAction which will be called before every action. You can use this to do things like authentication before allowing a connection into an action. The arguments to preProcessAction are:
function(api, connection, actionTemplate, callback).

actionTemplate is the literal action definition, so you can inspect actionTemplate.name, actionTemplate.description, etc. You can feel free to add additional parameters to your action definitions like actionTemplate.secure which you can inspect in the preProcessAction method.

The goal of preProcessAction is to return either true or false to the callback, where true will move on to the action proper, and false will render the connection types default return to the client. It would be best to set connection.error if you are returning false to preProcessAction's callback so the client has an idea of why they were denied.

It is best to define preProcessAction in an initializer.

Server

All of the server types (web, webSocket, socket) are now extended from a prototypical genericServer class. This should make it easer to make your own servers going forward

Chat

• web clients (http) can no longer use chat. They can only send messages to chat rooms via a method you design. A web-only 'chat' method is provided as an example

Bugs

• websocket clients will now reconnect properly when the connection to the server has been lost

General

• When using actionHero generateTask, you no longer are required to pass description (name will be used if you don't)
• When using actionHero generateAction, you no longer are required to pass description (name will be used if you don't)
• If you don't to use actionHero's default id genrator, you can set api.configData.general.id. Be careful to make this unique for all of your servers!

Modular & Prototypical Servers

• This release adds generic & prototypical servers
  • It is now easy & possible to write your own servers for actionHero.
  • we have moved all existing servers (web, websocket, socket) to this new achetecture
  • connections specivic verbs (ie: setParam, roomView) have been homogonized and shared
  • all "sever-specific" logic moved only into servers; no more if type == 'web' shenanigans
  • significang config.js chnges. Please see the example for updates
  • many responses and params have been homogenized
    • remoteIP
    • "data" returned from verbs
  • preparing to seperate into seperate NPM packages
• the file-sending middleware is renamed to 'staticFile'
  • much simpler API, appropriate for more server types
  • uniforn response api which uses file handlers / pipe
• server types renamed to "web", "socket", "websocket" for claricy
• serer types can have options about chatting and such
• the param "file" replaces "fileName" when attempting to directly access the content of files
• a new generator, generateServer, exists to help you make servers

web server

• header control in the web server has been moved to connection.rawConnection.responseHeaders from connection.responseHeaders
• http code control in the web server has been moved to connection.rawConnection.responseHttpCode from connection.responseHttpCode

socket server

• when setting params with JSON for a socket connection, those JSON params will now 'stick' with the connection going forward

websocket server

• we will now use a client-generated UUID as the communication channel rather than faye's clientId. This is more secure, and will be checked for uniqueness on the server.

other

• config.js drastically simplified (no more commonWeb, servers block, etc)
• winston logger object will now be passed into loger config methods
• speed improvments and tests added for the stats module (thanks @jacobbubu)
• wiki updates to refelect the above
• static site updates to reflect the above

bugs

• utils.hashMerge will no loner mangle arrays
• initilizers will now load custom code over base code, allowing ovverwrites

bugs

• remove explicit path to optimist in binary. This should solve package conflicts
• remove windows like breaks from generators

Version 6.1.0

API Versions

ActionHero can now support multiple versions of the same action. This will allow you to support actions/routes of the same name with upgraded functionality.

• actions now have the action.version attribute
  • If actions don't have action.version, they will be defaulted to version 1.
• a new reserverd param, apiVersion has been introduced. This is used to directly specify the version of an action a client may request
• if a client doesn't specify an apiVersion, they will be directed to the higest numerical version
• you can optionally create routes to handle your API versioning:

exports.routes = {
  all: [
    // creates routes like `/api/myAction/1/` and `/api/myAction/2/`
    // will also default `/api/myAction` to the latest version
    { path: "/myAction/:apiVersion", action: "myAction" },

    // creates routes like `/api/1/myAction/` and `/api/2/myAction/`
    // will also default `/api/myAction` to the latest version
    { path: "/:apiVersion/myAction", action: "myAction" },
  ]
};

middleware
This replaces api.actionProcessor.prototype.preProcessAction

actionHero provides hooks for you to execute custom code both before and after the excecution of all actions. You do this by adding to the api.actions.preProcessors and api.actions.postProcessors array. Functions you add here will be excecuted in order on the connection.

This is a great place to write atutentication logic or custom loggers.

preProcessors, like actions themselves, return the connection and a toProcess flag. Setting toProcess to false will block the excecution of an action. You can operate on connection.response and connection.error, just like within an action to create messages to the client.

preProcessors are provided with connection, actionTemplate, and next. They are expected to return (connection, toProcess)
postProcessors are provided with connection, actionTemplate, and next. They are expected to return (connection)

bugs

• fix a bug when reloading a task in development mode

actionHero run

This version introduces the ability to run actionHero's methods from the command line. This is similar to Ruby's rake command. the new actionHero run command has the api object in scope.

For example,

• we can set a cache object: actionHero run --method="api.cache.save" --args=test,123
• then read it back: actionHero run --method="api.cache.load" --args=test

> ./node_modules/.bin/actionHero run --method="api.cache.save" --args=test,123
info: actionHero >> run
info: project_root >> /Users/evantahler/PROJECTS/actionHero/
info: actionHero_root >> /Users/evantahler/PROJECTS/actionHero/
{ '0': null, '1': true }

> ./node_modules/.bin/actionHero run --method="api.cache.load" --args=test
info: actionHero >> run
info: project_root >> /Users/evantahler/PROJECTS/actionHero/
info: actionHero_root >> /Users/evantahler/PROJECTS/actionHero/
{ '0': null,
  '1': '123',
  '2': null,
  '3': 1373154368728,
  '4': 1373154385785 }

The response of the run command will be an ordered list of all the arguments passed to the callback (if it has one), or the function's return value (if the method is synchronous).

For safety, you can not run arbitrary code from actionHero run, so you will need to define first define the method you wish to call in an initializer, and append it to the api object

Run actionHero help for more information.

This version also formally separates actionHero.start into actionHero.initialize (loads your initializers) and actionHero.start (runs the _start methods and starts the various servers). Don't worry, you can still call actionHero.start without actionHero.initialize (it will run initialize for you).