@vrbo/catalyst-server

@vrbo/catalyst-server

• Introduction
• Usage
• Configuration and Composition
  • Basic
  • Environment Aware
  • Advanced
• Further Reading

Introduction

Catalyst-server is a configuration and composition management tool for Hapi.js applications. It allows for composition and configuration that is environment aware and extensible for a web application. This is managed from a single manifest.json file. The server also will include sensible defaults and implementations (like hapi-pino for logging and crumb for CSRF).

Usage

1. Install catalyst-server and hapi into an empty node project with npm i @vrbo/catalyst-server @hapi/hapi
2. Create an index.js file for starting your server (example below).
3. Create a manifest.json for composition and configuration (example below).
4. Start your app node index.js

index.js

const Catalyst = require('@vrbo/catalyst-server');
const Path = require('path');

async function start(options = {}) {
    const server = await Catalyst.init({
        ...options,
        userConfigPath: Path.resolve(__dirname, 'manifest.json')
    });

    await server.start();

    server.log(['info'], `server running: ${server.info.uri}`);

    return server;
}

start();

manifest.json

{
     // server configuration and application context variables.
    "server": {
        "app": {
        }
    },
    // Hapi plugins
    "register": {
    }
}

Configuration and Composition

Catalyst-server uses @vrbo/steerage to configure and compose your application. It is environment aware and has some configuration protocols to resolve paths, read environment variables, import other JSON files, and more.

Basic example

At its core, catalyst-server loads a manifest.json file to initialize and start up a Hapi.js server. This file has a section for application configuration and composition via registering plugins.

Below is a basic example of a manifest.json file:

manifest.json

{
     // server configuration and application context variables.
    "server": {
        "app": {
            "urlPrefix": "temp/",
            "siteTitle": "temp site"
        }
    },
    // Hapi plugins
    "register": {
        "Inert": {
            "register": "require:inert"
        },
        "Vision": {
            "register": "require:vision",
            "options": {
                "engines": {
                    "html": "require:handlebars"
                },
                "path": "path:./templates"
            }
        }
    }
}

You can access all the configuration values in your code from the server.app.config object. So the code to retrieve the example values looks like this:

const urlPrefix = server.app.config.get('urlPrefix');
const siteTitle = server.app.config.get('siteTitle');

The register block registers the plugins referenced. In this example, it is using shortstop to resolve node modules using require:[module] and resolve paths using path:[file_path].

Catalyst-server ships with the following shortstop resolvers by default:

• file - read a file.
• path - resolve a path.
• base64 - resolve a base64 string.
• env - access an environment variable.
• require - require a javascript or json file.
• exec - execute a function in a file.
• glob - match files using the patterns shell uses.
• import - imports another JSON file, supports comments.
• eval - safely execute a string as javascript code.

Environment Aware

@vrbo/steerage uses confidence to give you the ability to build environmentally aware servers. See the example manifest.json file below.

Environment based manifest.json

{
     // server configuration and application context variables.
    "server": {
        "app": {
            "urlPrefix": {
                "$filter": "env.NODE_ENV",
                "production":"/application",
                "$default":"/temp"
            }
        }
    },
    // Hapi plugins
    "register": {
        "crumb": {
            "register": "require:crumb",
            "options": {
                "cookieOptions": {
                    "isSecure": {
                        "$filter": "env.NODE_ENV",
                        "production": true,
                        "$default": false
                    }
                },
                "restful": true
            }
        }
    }
}

In this example, the $filter and $default fields allow for filtering based on a resolver like env.NODE_ENV.

The $filter field evaluates the environment variable NODE_ENV. Then, it will look to the following fields for a match in the keys for that value. Otherwise, the $default value is used. So the configuration values and options for plugins will change based on the environment variable NODE_ENV.

This is what the above manifest configuration will return in code for different environments:

// ENVIRONMENT VARIABLE NODE_ENV='development'
const urlPrefix = server.app.config.get('urlPrefix');
// returns '/temp'
// crumb will NOT use secure cookies.

// ENVIRONMENT VARIABLE NODE_ENV='production'
const urlPrefix = server.app.config.get('urlPrefix');
// returns '/application'
// crumb WILL use secure cookies.

Using a filter, you can easily enable/disable a plugin for a given environment. See the code below for an example, where we disable hapi-pino in development mode, and enable it in all other environments:

{
    "register": {
        "hapi-pino": {
            "enabled": {
                "$filter": "env.NODE_ENV",
                "production": true,
                "$default": false
            }
        }
    }
}

Advanced

Here are some examples of the shortstop resolvers which make handling complex configuration and composition rather straight forward.

file: Reading a file into a value.

    "key": "file:./pgp_pub.key"

• loads the file pgp_pub.key and will set the value key to the contents of that file.

path: Resolve a path.

    "path": "path:./templates"

• will resolve the path of ./templates and will set the value path to the fully resolved path.

base64: Resolve a base64 string.

    "bytes": "base64:SGVsbG8="

• will decode the base64 string SGVsbG8= and will set the bytes value to a buffer from the base64 string.

env: Access an environment variable.

    "dbHost": "env:PG_HOST"

• will evaluate the environment variable PG_HOST and will set the dbHost value to the environment variable value.

require: Require a javascript or json file.

    "register": "require:inert"

• will load the node module inert and will set the register to what that module exports. This works for js files in you application.

exec: Execute a function in a file.

    "status": "exec:./callStatus#get"

• will load the file callStatus.js and will run the exported function get and whatever value is return will be set for the status value.

glob: Match files using the patterns shell uses.

    "files": "glob:./assets/**/*.js"

• will use glob to evaluate ./assets/**/*.js and sets the value of files to an array of files that match the glob string.

import: Imports another JSON file, supports comments.

    "data": "import:./data/salt.json"

• will load a json file ./data/salt.json, evaluate it (ignoring comments) and set data to that value.

eval: Safely execute a string as javascript code.

    "start": "eval:new Date().toISOString()"

• will use vm to evaluate the string and set the start to the current date time as an ISO string.

    {
        "server": {
            "app":{
                "first": "abc",
                "second": "xyz",
                "child": {
                    "value":"eval:${server.app.first}_${server.app.second}"
                }
            }
        }
    }

• eval can also be used to reference other values in the manifest. In the above example the child/value in server/app will be set to 'abc_xyz'.

Example Code

See the examples folder for example code.

Further Reading

• License
• Code of conduct
• Contributing
• Changelog

Changelog

2.1.0 - 2020-01-09

Changed

• Use @vrbo namespaced versions of steerage and determination
• Updated determination to v3
• Updated standard, sinon, and nyc dev deps