actionhero / actionhero

Actionhero is a realtime multi-transport nodejs API Server with integrated cluster capabilities and delayed tasks

Actionhero

The reusable, scalable, and quick node.js API server for stateless and stateful applications

---

NPM | Web Site | Latest Docs | GitHub | Slack | Twitter

Who is the Actionhero?

Actionhero is a multi-transport API Server with integrated cluster capabilities and delayed tasks. The goal of actionhero is to create an easy-to-use toolkit for making reusable & scalable APIs for HTTP, WebSockets, and more. Clients connected to an actionhero server can consume the api, consume static content, and communicate with each other. Actionhero is cluster-ready, with built in support for background tasks, 0-downtime deploys, and more. Actionhero provides a simple Async/Await API for managing every type of connection and background task.

Currently actionhero supports the following out of the box...

• Web Clients: HTTP, HTTPS
• Web Socket Clients: HTTP, HTTPS

... and you can also make your own servers and transports.

Quick Start

# Generate a new Project
npx actionhero generate
npm install
npm run build
npm run dev # <-- I automatically notice changes and restart, as well as compiling .ts files

# Use the actionhero CLI
(npx) actionhero generate action --name my_action
(npx) actionhero generate task --name my_task --queue default --frequency 0

# Test
npm test

# To deploy your app
npm run build
npm run start

Your new project will come with example actions, tests, and more.

Or deploy a free API server now:

Learn More 📚

• Getting Started @ www.actionherojs.com
  • Actionhero's website can be found @ https://github.com/actionhero/www.actionherojs.com/. If you want to contribute to this site, visit the related project
  • ---> Start with the Tutorials <---
• Read the typedoc documentation @ docs.actionherojs.com
  • Starting with Actionhero version 18, the documentation for each version is included in this repository (and the NPM package) in the /docs folder. The current version of this documentation is also automatically deployed to https://docs.actionherojs.com.
• Find community-based resources
• Interact with the Community & View the Release History
• Server Client

In-depth Tutorials 🎓

Core Components

• Actions
• Tasks
• Middleware
• Initializers
• CLI Commands
• Configuration
• Cluster
• Chat & Realtime Communication
• File Server
• Logging
• Plugins
• Servers
• Localization & Translation

Server Types

• Web Server & Routes
• WebSocket Server

Testing, Deployment, and Operations

• Running Actionhero
• Development Mode & REPL
• Testing & SpecHelper
• Production Notes
• Upgrade Path

Sample Projects

• Simple
• Elaborate (React, Next.JS, Bootstrap, Sequelize)
• Client Use: React
• Client Use: React Native

Who?

• Many folks have helped to make Actionhero a reality.
• If you want to contribute to actionhero, contribute to the conversation on github and join us on slack

Contributing

• Contributing to Actionhero is easy! You can learn more about contributing to Actionhero here
• By engaging the with Actionhero community or contributing to this or related projects, you agree to our Code of Conduct

License

Apache 2.0

Dedication

Technology is a powerful force in our society. Data, software, and communication can be used for bad: to entrench unfair power structures, to undermine human rights, and to protect vested interests. But they can also be used for good: to make underrepresented people’s voices heard, to create opportunities for everyone, and to avert disasters. This project is dedicated to everyone working toward the good.

Inspired by Martin Kleppmann

actionhero's Issues

generators for actions

Make web chat methods opt in

They create a lot of overhead.

prevent server falling over on error

Would be nice to have an option to prevent the server falling over on error, eg log the error and continue with the next request like every other webserver does hehe :)

Not sure how you can implement that other than wrapping try/catch around action handler. dunno..

async processing and next()

quick question, not bug/feature related :)

I have a chain of redis statements in one of my actions. Is it ok to call next(connection,true) before those have completed. I presume they will of course continue to process even after next() has been called eh?

Many thanks~

TiM

The list of peers should be cleared periodically

Peers that haven't been seen in a while should be removed, and any tasks in queues they own should be emptied

Write an article about why actionHero is not like Rails

It will help clarify things

npm start should work when actionHero is installed globally

actionHero start is ok, but not npm start

Generators for initializers

And project init should make the folder

generators for tasks

Symlinks do not work in /public

linked files do not work (osx) but folders are OK

web-socket connections cannot use actions/say/etc if the server has been restarted

Data Encryption in ActionHero

To be more secure, I would like to add data encryption to ActionHero. I did try to encrypt data before send out, and decrypt after receive. everything works find, but I wonder if you could provide/add this encryption in alternative way, or can give some idea on "What is the best way to add encryption to ActionHero?"

file server should have a better log (like nginx)

log should show path, ip, etc and response code (200, 404, etc)

Make this more awesome

Make the actionHero API more awesome!

Should actionHero cache the content of flat files in /public?

This will probably make serving these files faster, but seems like an expensive use of RAM.
Thoughts?

Connections should be kept in a global pool with a defined transport rather than each type of transport holding connections of its own type

api.connections = [] rather than api.socketServer.connections && api.webSockets.connection

Upgrade to the Mocha test framework

"apiVersion" mispelled

In the json returned by an action call, the property "apiVersion" is mispelled. This error is also in the config.json file, renaming it "apiVersion" (instead of "apiVerson", missing "i") in this file makes the property to disappear in the action result's json.

update website with new start commands

cleanup global localization and path localization in binaries

it's a mess!

events should be emitted when people enter and leave a room (like say)

routes should be reloaded in development mode

PHP cUrl cannot call actionHero

This code above, does return nothing.

But when I pasted this same url on browser, it works ok, it does return
http://{someip}:8080/api/actionsView

could anyone help me, I want to call actionHero from PHP.
Thank you.

actionHero should conform to 'strict' mode

Beef up the cluster example to be production-ready

Handle UNIX signals [[ http://stackoverflow.com/questions/8933982/how-to-gracefully-restart-a-nodejs-server ]] to act more like ruby unicorn [[ http://unicorn.bogomips.org/SIGNALS.html ]] .

• 0 down time (rolling restart of workers)
• worker management
• worker logging

how to integrate a new Action with a 3rd party API call

hello,

thank you for such a well engineered api framework !

I am trying to create an Action destinated to call nexmo sms gateway API.

i am stuck with a TypeError: undefined is not a function.

i have created an initializer "initSms" and an Action "actionsSms".

1. The initializer

exports.initSms = function(api, next){

api.sms = {};
nexmo = {};
s = {};

api.sms.sendai = function(api, connection, next){

nexmo = require('../node_modules/nexmo-api/lib/nexmo.js').Nexmo,
key   = 'kkk',
secret  = 'sss';

s = new nexmo(key, secret);

s.send(connection.params.from, connection.params.to, connection.params.text, function(err, success){
  connection.success = success.id;
  next(err, success);
});

}

next();
}

2. extract oF the actionsSms.js [ action.run ] is

action.run = function(api, connection, next){

connection.response.sms = [];

api.sms.sendai(connection.params.from, connection.params.to, connection.params.text, function(err, success) {
        if (success) {

    connection.response.sms.push({
                result: success.id });

            console.log('nexmo api msgid: ' + success.id);
        }
        if (err) {
            console.log(err);
        }   
});


    connection.response.sms.push({

        from: connection.params.from,
        to: connection.params.to,
        text: connection.params.text,

    });


next(connection, true);

};

2012-11-24T16:05:58+00:00 app[web.1]: 2012-11-24 16:05:58 | ! params: {"from":"5548xxxxxxxx","to":"5548yyyyyyyy","text":"hello","action":"actionsSms","limit":100,"offset":0}
2012-11-24T16:05:58+00:00 app[web.1]: 2012-11-24 16:05:58 | ! room: "defaultRoom"
2012-11-24T16:05:58+00:00 app[web.1]: 2012-11-24 16:05:58 | ! type: "web"
2012-11-24T16:05:58+00:00 app[web.1]: 2012-11-24 16:05:58 | ! connection details:
2012-11-24T16:05:58+00:00 app[web.1]: 2012-11-24 16:05:58 | ! action: "actionsSms"
2012-11-24T16:05:58+00:00 app[web.1]: 2012-11-24 16:05:58 | ! uncaught error from action: actionsSms
2012-11-24T16:05:58+00:00 app[web.1]: 2012-11-24 16:05:58 | ! TypeError: undefined is not a function
2012-11-24T16:05:58+00:00 app[web.1]: 2012-11-24 16:05:58 | ! at Object.exports.initSms.api.sms.sendai (/app/initializers/initSms.js:16:9)
2012-11-24T16:05:58+00:00 app[web.1]: 2012-11-24 16:05:58 | ! at Object.action.run (/app/actions/actionsSms.js:34:10)
2012-11-24T16:05:58+00:00 app[web.1]: 2012-11-24 16:05:58 | ! at Domain.run (domain.js:141:23)
2012-11-24T16:05:58+00:00 app[web.1]: 2012-11-24 16:05:58 | ! at api.processAction.process.nextTick.api.actions.(anonymous function).run.connection.respondingTo (/app/node_modules/actionHero/initializers/initActions.js:129:40)
2012-11-24T16:05:58+00:00 app[web.1]: 2012-11-24 16:05:58 | ! at Domain.bind.b (domain.js:201:18)
2012-11-24T16:05:58+00:00 app[web.1]: 2012-11-24 16:05:58 | *
2012-11-24T16:05:58+00:00 app[web.1]: 2012-11-24 16:05:58 | ! at process.startup.processNextTick.process._tickCallback (node.js:244:9)

better http verb support for API documentation

yo, the action metaData is pretty limited. It's a bit hard to suggest api first when you cannot specify for each type of http verb the required/optional arguments.

For example..

action.name = "account";
action.description = "Get Account Information";
action.inputs = {
"required" : [],
"optional" : ['email','password','authkey']
};

In this example action

GET - email/pass or authkey
POST - authkey
PUT - authkey
DEL - authkey

Only GET requires email/pass. And actually I can't specify "authkey" as a required param because you can optionally use email/password for GET request. Admittedly this case is pretty rare.

Two issues really

• Lack of support for Verbs
• Lack of support for OR sets of params (not critical but would be super nice!)

See http://swagger.wordnik.com/ for an example.

Haven't looked at code but suspect its only a couple of lines of code that are checking the request params against the action.inputs. Should be pretty easy to extend and keep the existing format as the default eh

http(s) clients should be able to chat like everyone else

messages to clients should be saved ephemerally and available for retrieval.

config.js should be reloaded in development mode

responding to env variables

environment (dev/test/prod/etc)

• for config files
• for development mode

Provide null connection to api.chatRoom.socketRoomBroadcast(...)

https://github.com/evantahler/actionHero/wiki/Chat states that:

If you want your API to send messages to all connected clients, you can provide a null connection,
and api.configData.general.serverName will appear as the sender.

Unfortunately I can't seem to get that to work, given that the context I am calling this function is within a task. If I pass a { room: 'defaultRoom'} object as the connection param it complains about a missing id property.

Traceback:

2012-10-15 22:43:50 | Scanning for jobs...
2012-10-15 22:43:50 | ! uncaught error from task: jobProcessor
2012-10-15 22:43:50 | ! TypeError: Cannot read property 'room' of null
2012-10-15 22:43:50 | !     at Object.api.chatRoom.socketRoomBroadcast (/Users/jamie/dev/scratchpad/metropolis-ah/node_modules/actionHero/initializers/initChatRooms.js:20:22)
2012-10-15 22:43:50 | !     at Object.task.run (/Users/jamie/dev/scratchpad/metropolis-ah/tasks/jobProcessor.js:30:22)
2012-10-15 22:43:50 | !     at api.tasks.run (/Users/jamie/dev/scratchpad/metropolis-ah/node_modules/actionHero/initializers/initTasks.js:197:31)
2012-10-15 22:43:50 | !     at Domain.bind.b (domain.js:201:18)
2012-10-15 22:43:50 | !     at Domain.run (domain.js:141:23)
2012-10-15 22:43:50 | !     at Object.api.tasks.run (/Users/jamie/dev/scratchpad/metropolis-ah/node_modules/actionHero/initializers/initTasks.js:196:15)
2012-10-15 22:43:50 | !     at api.tasks.process (/Users/jamie/dev/scratchpad/metropolis-ah/node_modules/actionHero/initializers/initTasks.js:215:15)
2012-10-15 22:43:50 | !     at /Users/jamie/dev/scratchpad/metropolis-ah/node_modules/actionHero/initializers/initTasks.js:161:9
2012-10-15 22:43:50 | !     at try_callback (/Users/jamie/dev/scratchpad/metropolis-ah/node_modules/actionHero/node_modules/redis/index.js:520:9)
2012-10-15 22:43:50 | !     at RedisClient.return_reply (/Users/jamie/dev/scratchpad/metropolis-ah/node_modules/actionHero/node_modules/redis/index.js:590:13)
2012-10-15 22:43:50 | *
2012-10-15 22:43:50 | [timer 0] task failed to run: {"taskName":"jobProcessor","runAtTime":1350366230550,"params":null}

Folder depth for actions and tasks

I should be able to organize in sub folders

url params

Here's another one,

would be nice to utilize url segments within actions eg

/myAction/123

/myAction/:id

Rather than /myAction/?id=123

Which doesn't look very RESTy

TiM

combine existing stand-alone generations to one actionHero binary

This way, the module can be installed globally and run with a better syntax:

1. npm install actionHero -g
2. actionHero generate {app_name}
3. etc

(be sure to update the wiki, readme, and website)

We should be able to deprecate and modify versions of actions within the API

development mode?

Hi there,

Is there a way I can have my "actions" reload on each request? At present I have to stop/start the server which is not nice for testing.

Thnx,

PS Love the framework, very awesome..

TiM

refactor actionsView/self-documentation into a known format

Perhaps Swagger?
https://github.com/wordnik/swagger-core/wiki/API-Declaration

Session data helper based on connection.id

Will need expiry

Investigate buffered logging and non-blocking logging

each actionHero should be allowed to have more than one task worker

• how to resolve deadlocks when reading task queue? (or duplicate reads?)

api doc viewer

Hi there, any plans for an api browser?

See http://swagger.wordnik.com/ for a good example.

Cheers, TiM

Tests for websockets

I should be able to define more than one action in an action file

This way, I can reuse functions and what-not more easily

socket.io vs WebSocket.IO

https://github.com/LearnBoost/socket.io
https://github.com/LearnBoost/websocket.io

Seems websocket.io is a newer version of socket.io

Using above we could then use

https://github.com/nicokaiser/wamp.io

Which provides wamp (see http://wamp.ws/) subprotocol to websockets which would probably be a better solution than the 'chatroom' based message sharing you have baked in.

Honestly it's your framework but for broad appeal you should probably ditch the chatroom stuff or make it optional from websockets (which has no concept of a room but does have channels)

I love the concept of simply adding new (server) initializers to add functionality onto the server, I have yet to fully appreciate or even start to leverage that (at some point I need a socket that talks in binary to an android client) but would be nice to have these extras exist as optionals.

Cheers,

TiM

run periodic task

Not clear how to run a task periodically. I have set task.frequency = 5000 and would have expected it to be running every five seconds once server has started up. nope..

Tried adding

api.tasks.enqueue(api, taskName, runAtTime, params).

to app.js initialization but does nothing.

I simply want to run a task continuously, not on an action..

Cheers, TiM

web sockets example

There are a few errors in the web socket example

I think you meant:

var action = function(action,params) {
   if (params == null) { params = {}; }
   params['action'] = action;
   socket.emit("action", params);
}

etc.

installing

install failed

[email protected] install C:\Program Files\nodejs\node_modules\actionHero
./scripts/install

'.' is not recognized as an internal or external command,
operable program or batch file.
npm ERR! [email protected] install: ./scripts/install
npm ERR! cmd "/c" "./scripts/install" failed with 1
npm ERR!
npm ERR! Failed at the [email protected] install script.
npm ERR! This is most likely a problem with the actionHero package,
npm ERR! not with npm itself.
npm ERR! Tell the author that this fails on your system:
npm ERR! ./scripts/install
npm ERR! You can get their info via:
npm ERR! npm owner ls actionHero
npm ERR! There is likely additional logging output above.

npm ERR! System Windows_NT 6.1.7601
npm ERR! command "C:\Program Files\nodejs\node.exe" "C:\Program Files\nodejs\node_modules\npm\bin\npm-cli.js" "install" "
actionHero"
npm ERR! cwd C:\Program Files\nodejs\actionHero
npm ERR! node -v v0.8.14
npm ERR! npm -v 1.1.65
npm ERR! code ELIFECYCLE
npm ERR!
npm ERR! Additional logging details can be found in:
npm ERR! C:\Program Files\nodejs\actionHero\npm-debug.log
npm ERR! not ok code 0

C:\Program Files\nodejs\actionHero>

LOG FILE OUTPUT
2719 verbose true,C:\Program Files\nodejs\node_modules,C:\Program Files\nodejs\node_modules unbuild [email protected]
2720 info postuninstall [email protected]
2721 error [email protected] install: ./scripts/install
2721 error cmd "/c" "./scripts/install" failed with 1
2722 error Failed at the [email protected] install script.
2722 error This is most likely a problem with the actionHero package,
2722 error not with npm itself.
2722 error Tell the author that this fails on your system:
2722 error ./scripts/install
2722 error You can get their info via:
2722 error npm owner ls actionHero
2722 error There is likely additional logging output above.
2723 error System Windows_NT 6.1.7601
2724 error command "C:\Program Files\nodejs\node.exe" "C:\Program Files\nodejs\node_modules\npm\bin\npm-cli.js" "install"
"actionHero"
2725 error cwd C:\Program Files\nodejs\actionHero
2726 error node -v v0.8.14
2727 error npm -v 1.1.65
2728 error code ELIFECYCLE
2729 verbose exit [ 1, true ]

better tests for running jobs within cluster

multiple independent instances

I have several instances (alpha,beta,staging) running on single server. I have configured params.configChanges as per cluster example to have them running on seperate ports and hence a seperate ID for the instance.

I need them to work independently and not as nodes in a cluster that are sharing tasks, etc. What would I need to change to make this work?

Cheers,

TiM

passing params (not sticky) to actions from socket connection

I would have expected like this

myAction { key : value}

but nope, seems only "paramAdd " works which is fine for setting common keys for all actions apparently??