Skip to content

Latest commit

 

History

History
99 lines (82 loc) · 4.52 KB

README.md

File metadata and controls

99 lines (82 loc) · 4.52 KB
Raw

patova

A limitd plug-in for hapi.js

Install

npm i -S patova

Registering the plug-in (Hapi >= 17)

The following code snippet shows how to register the plug-in in your server:

const Hapi = require('hapi');
const patova = require('patova');

const server = new Hapi.Server({ port: 9999 });

await server.register({
  plugin: patova,
  options: {
    event: 'onPostAuth',
    type: 'users',
    limitd: limitdClient,
    extractKey: (request) => request.auth.credentials
  },
});

Options (Hapi >= 17)

The object has the following schema (validated here using Joi):

Required

  • event: String - The name of the extension point in the request lifecycle when the bucket check must be performed. Options are "onRequest", "onPreAuth", "onPostAuth","onPreHandler" (anything before the request).
  • type: String|async (request, flowControl) => () - Either the bucket type as a string or a function. If you use a function, it will be called for every request, this could be a async function. It's possible to decide skip the check, for this return flowControl.continue;
  • limitd: an instance of limitd client
  • extractKey: (request, flowControl) => () - A function that receives the request and the object flowControl.
    • request: Request - The hapi.js request object.
    • flowControl - This object contains a property continue to let the plugin know that you want to skip the check. Same situation to what happen in key.

Optional

  • onError: (error, h) => () - A function that takes the error that occurred when trying to get a token from the bucket and the reply interface.
    • error: Error - The error that occurred.
    • h: ResponseToolkit - The hapi.js response toolkit.

    If an error occurs and no function is provided, the request lifecycle continues normally as if there was no token bucket restriction. This is a useful default behavior in case the limitd server goes down.

Registering the plug-in (Hapi <= 16)

The following code snippet shows how to register the plug-in in your server:

const Hapi = require('hapi');
const patova = require('patova');

const server = new Hapi.Server();
server.connection({ /* options */ });

server.register({
  register: patova,
  options: {
    event: 'onPostAuth',
    type: 'users',
    limitd: limitdClient,
    extractKey: function(request, reply, done){
      var key = request.auth.credentials.userId;
      done(null, key);
    }
  },
}, err => {
  //
});

Options (Hapi <= 16)

The object has the following schema (validated here using Joi):

Required

  • event: String - The name of the extension point in the request lifecycle when the bucket check must be performed. Options are "onRequest", "onPreAuth", "onPostAuth","onPreHandler" (anything before the request).
  • type: String|(request, callback) => () - Either the bucket type as a string or a function. If you use a function, it will be called for every request, this function must invoke the callback function when it is finished.
  • limitd: an instance of limitd client
  • extractKey: (request, reply, done) => () - A function that receives the request and a callback done.
    • request: Request - The hapi.js request object.
    • reply: Reply - The hapi.js reply interface. Useful if you want to skip the check.
    • done: (err: Error, key: String) - A function that takes an error as the first parameter and the bucket key as the second parameter.

Optional

  • onError: (error, reply) => () - A function that takes the error that occurred when trying to get a token from the bucket and the reply interface.
    • error: Error - The error that occurred.
    • reply: Reply - The hapi.js reply interface.

    If an error occurs and no function is provided, the request lifecycle continues normally as if there was no token bucket restriction. This is a useful default behavior in case the limitd server goes down.

Contributing

Feel free to open issues with questions/bugs/features. PRs are also welcome.

Supported versions

Hapi Version Patova Version
Hapi <= 16 v2.2.x
Hapi >= 17 v3.0.x

License

MIT