Mrhorse

MrHorse

Manage your hapi routes with modular policies.

Lead Maintainer: Mark Bradshaw, contributors

What is it?

Wouldn't it be nice to easily configure your routes for authentication by adding an isLoggedIn tag? Or before replying to a request checking to see if userHasAccessToWidget? Maybe you'd like to do some a/b testing, and want to change some requests to a different handler with splitAB. Or you'd like to add some special analytics tracking to some of your api requests, after your controller has already responded, with trackThisAtAWS. You create the policies and MrHorse applies them as directed, when directed.

MrHorse allows you to do all of these and more in a way that centralizes repeated code, and very visibly demonstrates what routes are doing. You don't have to guess any more whether a route is performing an action.

It looks like this:

server.route({
    method: 'GET',
    path: '/loggedin',
    handler: async function() {},
    options: {
        plugins: {
            policies: ['isLoggedIn', 'addTracking', 'logThis']
        }
    }
});

server.route({
    method: 'GET',
    path: '/admin',
    handler: async function() {},
    options: {
        plugins: {
            policies: [
                ['isLoggedIn', 'isAnAdmin'], // Do these two in parallel
                'onlyInUS' // Then do this last
            ]
        }
    }
});

Why use this?

Often your route handlers end up doing a lot of repeated work to collect data, check for user rights, tack on special data, and otherwise prepare to do the work of replying to a request. It'd be very nice to put the code that keeps getting repeated in a single location, and just apply it to routes declaratively. Often you end up repeating the same small bit of code across a lot of handlers to check for rights, or generate some tracking code, update a cookie, etc. It's hard to see where these actions are happening across your site, code gets repeated, and updating that code to correct a bug can be tricky.

MrHorse let's you take those repeated bits of code and centralize them into "policies", which are just single purpose javascript functions with the signature async function(request, h). Policies are a good fit whenever you find yourself repeating code in your handlers. Policies can be used for authentication, authorization, reply modification and shaping, logging, or just about anything else you can imagine. Policies can be applied at any point in the Hapi request life cycle, before authentication, before the request is processed, or even after a response has been created. Once you've created a policy, you just apply it to whatever routes need it and let MrHorse take care of the rest.

Using policies you can easily mix and match your business logic into your routes in a declarative manner. This makes it much easier to see what is being done on each route, and allows you to centralize your authentication, authorization, or logging in one place to DRY out your code. If a policy decides that there's a problem with the current request it can immediately reply back with a 403 forbidden error, or the error of your choice. You always have the option of doing a custom reply as well, and MrHorse will see that and step out of the way.

Why use MrHorse instead of Hapi route prerequisites

Hapi provides a somewhat similar mechanism for doing things before a route handler is executed, called route prerequisites. MrHorse seems to be overlapping this functionality, so why not just use prerequisites?

1. MrHorse puts more focus on whether to continue on to the next policy, allowing you to more easily short circuit a request and skip other policies or the route handler. This makes authentication and authorization tasks more straightforward. Since you can stop processing with any policy, it allows you to fail quickly and early, and avoid later processing.
2. MrHorse gives you the option of running policies at any point in the Hapi request life cycle, including after a request handler has run. This allows you to easily modify responses, add additional data, or do logging tasks and still run your normal handler. With prerequisites, you can take over a response, but your route handler won't get run. It gives you no ability to do additional processing post handler.
3. MrHorse helps you to keep your policy type code in a central location, and loads it up for you. Prerequisites don't provide any help with this.
4. MrHorse can allow policies to run at even more places in the Hapi request life cycle than just right before the handler. This is a flexibility that prerequisites probably will never have.

Examples

Look in the example folder to see MrHorse in action. node example/index.js.

Install

To install mrhorse:

npm install mrhorse --save

Requires Node >= 14, following the baseline requirements of hapi v21.

Updating

From 2.x

Version 3.x contains breaking changes from 2.x. In particular, the Node callback model has been abandoned in favor of async / await. This is a change in the entire Hapi ecosystem, so we are following their decision. This also means that you must be running at least Node 8.

The following functions are now async and do not accept a callback parameter any longer:

• server.plugins.mrhorse.loadPolicies

• Policies are now defined as async functions. If the function does not throw, it will be considered successful (and should return h.continue). In other words, policy definition should change from:

function myPolicy(request, reply, next) {
  if (isAdmin(request) === true ) {
    return next(null, true);
  }

  return next(Boom.forbidden('Sorry')); // failure
}

to:

async function myPolicy(request, h) {
  if (isAdmin(request) === true) {
    return h.continue; // success
  }

  throw Boom.forbidden('Sorry'); // failure
}

Setup

Mrhorse looks for policy files in a directory you create. I recommend calling the directory policies, but you can choose any name you want. You can have this directory sit anywhere in your Hapi project structure. If you are using plugins for different site functionality, each plugin can have its own, separate policies directory.

Once you have created your policies directory you must tell MrHorse where it is. You do this in two ways. You can either pass the directory location in to the mrhorse plugin when you register it, like this:

await server.register({
    plugin: require('mrhorse'),
    options: {
        policyDirectory: `${__dirname}/policies`
    }
});

Or you can provide a directory location using the loadPolicies function, like this:

server.plugins.mrhorse.loadPolicies(server, {
        policyDirectory: `${__dirname}/policies`
    });

Both strategies are fine, and can be complementary. If your Hapi project uses plugins to separate up functionality it is perfectly acceptable for each plugin to have its own policies folder. Just use the loadPolicies function in each plugin. See the example folder for additional detail.

You can use MrHorse in as many places as you want. It's ok to have multiple policies folders in different locations, and tell MrHorse to look in each one. The only requirement is that each policy file name must be globally unique, since policies can be used on any route in any location.

Normally MrHorse would throw an error when it encounters a duplicate policy, and that's to keep you from accidentally duplicating a policy name, but there are situations that might make sense to ignore the duplicates. For instance, you might be using a development tool like wallaby that will reload your server as you change code, and inadvertently cause MrHorse to reinitialize. This would cause the process to throw an error and likely abort the server. In that case you can add ignoreDuplicates: true to your MrHorse options and duplicate policies will be silently ignored.

By default policies are applied at the onPreHandler event in the Hapi request life cycle if no other event is specified in the policy. Each policy can control which event to apply at. You can also change the default event to whatever you want. You would do this by passing in defaultApplyPoint in the options object when registering the plugin, like this:

await server.register({
        plugin: require('mrhorse'),
        options: {
            policyDirectory: `${__dirname}/policies`
            defaultApplyPoint: 'onPreHandler' /* optional.  Defaults to onPreHandler */,
        }
    });

Policies

Now create a policy file inside the policies folder. This is just a simple javascript file that exports one async javascript function. The name of the file should be the name you want to use for your policy. MrHorse uses the file name, not the function name, to identify the policy so make sure you name the file appropriately. If this policy file is named isAdmin.js, then the policy would be identified as isAdmin.

const isAdmin = async function(request, h) {
   const role = _do_something_to_check_user_role(request);
   if (role && role === 'admin') {
       return h.continue; // All is well with this