Skip to content

Latest commit

 

History

History
186 lines (136 loc) · 7.65 KB

README.md

File metadata and controls

186 lines (136 loc) · 7.65 KB
Raw

Rapptor

Test Status Lint Status NPM

Rapptor is a server framework that vastly simplifies use of hapi servers by leveraging easy-to-read YAML config files instead of Javascript. If you use the hapi library, the Rapptor framework is a must-have!

Features

  • Configure and manage server plugins with YAML
  • Automatically load and configure server routes from the routes directory
  • Automatically load and configure server methods from the methods directory
  • Configure logging from YAML
  • Configure server health monitoring and alerts
  • Track server metrics using Prometheus metrics.

Installation

npm install rapptor

or

yarn add rapptor

Usage:

Add the following to your package.json:

{
  "scripts": {
    "start": "rapptor"
  }
}

Then run: npm start to launch the server!

Directory Layout

The following is an example of the directory layout for a rapptor project:

/conf
│   ├── default.yaml/
│   ├── default-envs.yaml/
│   ├── dev.yaml/
/methods
│   ├── foo_method.js/
│   ├── auth_methods
│       ├── login.js/
│       ├── logout.js/
/plugins
│   ├── my_security_plugin.js/
/routes
├── api
│   ├── foo_route.js/
│   ├── bat/
│       ├── bif_route.js/
├── login.js
├── logout.js
/node_modules
│   ...
package.json

Configuration files are in /conf, routes are defined in the /routes directory, server methods are defined in /methods and server plugins are defined either in /plugins or installed automatically by npm in node_modules.

Configuring

All server configuration takes place in YAML files located in the /conf directory. At minimum you should have a conf/default.yaml file but you can have as many configuration files in /conf as you want.

File names beginning with _default-.yaml form will always be loaded in the order they appear in the directory. Files lacking the default- prefix will only be loaded if they match ENV.NODE_ENV. So you can have a dev.yaml that only loads when NODE_ENV is dev and a production.yaml that only loads when NODE_ENV is production.

Inside your configuration files you can access environment variables and create/access more complex variables inside YAML in a flexible manner with the double-bracket notation like this:

github:
  token: '{{ENV.GITHUB_TOKEN}}'
  endpoint: '{{ENV.GITHUB_REPO}}'
githubToken: '{{github.token}}'

This could cause problems if you forgot to define the correct environment variables in your shell, so for safety it is best to use the built-in env handlers like so:

aString: '{{getEnv("EXAMPLE_ENV_VARIABLE", "the backup value!")}}'
aBoolean: '{{truthyEnv("IS_TRUTHY")}}'

since this will set aValue to the string "the backup value!" if you didn't define EXAMPLE_ENV_VARIABLE and will coerce aBoolean to be either 'true' or 'false' depending on whether ENV.IS_TRUTHY was defined and is 'truthy'. For example if IS_TRUTHY is the literal string 'false' or the numeric -1 then it will be a boolean 'false' value.

More information on configuration file format is available at hapi-confi.

Adding a plugin

Plugins can be added and configured by listing them in a plugins: section like so:

plugins:
  my_security_plugin:
    authRoute: '/auth'
    keys:
      serverKey: '{{ENV.SERVER_API_KEY"}}'
      adminKey: '1234abc'

This will cause hapi to look for "my_security_plugin" in the plugins directory and then in node_modules for a plugin named my_security_plugin. Once found it will be registered with your hapi server along with any of the underlying options. Note that plugins: could appear in any of your conf files, so you can have a default-plugins.yaml file just for listing your plugins, or have different plugins in a production.yaml file that will only load when you set NODE_ENV to production.

By default rapptor includes the following core plugins:

Adding a route

Create a file: routes/someroute.js and add the following:

exports.homepage = {
  path: '/',
  method: 'GET'
  handler(req, h) {
    return 'homepage!';
  }
}

Now if you launch rapptor and go to http://localhost:8080/ you should see homepage!.

For more information on configuring route loading see hapi-route-loader.

Adding a method

Add a file: methods/foo.js and then add the following:

module.exports = {
  method() {
    //some stuff
    this.log(['tag1', 'tag2'], "Hello World!");
  }
}

This will cause hapi to register foo() as a server method, so server.methods.foo() will be available in your code. Server methods will be bound to the server, so this.log is equivalent to server.log.

For more information on method loading in rapptor see hapi-method-loader.

Additional Features

Logging

Rapptor also includes facilities for logging in various formats and output media via the hapi-logr plugin. By default hapi-logr prints to console but can be configured to log to just about any output such as a Slack channel or text messages via SNS. For more information see the documentation at hapi-logr.

Healthcheck

Rapptor includes a built-in secure healthcheck plugin, which will register an endpoint at /health that is protected by ENV.HEALTH_TOKEN. Calling /health?token={HEALTH_TOKEN} will return basic metrics like server uptime, CPU level and current memory usage. This route can be polled at regular intervals from a remote script to ensure that your server is alive and available.

Metrics

Rapptor also includes metrics reporting via Prometheus. If ENV.ENABLE_PROM is set to true then the [hapi-prom]((https://github.com/firstandthird/hapi-prom) server plugin will automatically begin collecting default metrics using the prom-client package. These metrics are available at the /metrics route on your hapi server, for more info on how to configure hapi-prom see [hapi-prom]((https://github.com/firstandthird/hapi-prom).

A First + Third Project