@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 hapi and catalyst-server npm i @vrbo/catalyst-server hapi into an empty node project
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 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

At its core, catalyst-server loads a manifest.json to initial and start 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:

Basic 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"
            }
        }
    }
}

For the configuration you can access the values in the server/app section from inside your code from the the server.app.config object. So the code to retrieve the example values look 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 comes with the following short-stop resolvers:

• 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

Steerage also 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", 
                        "development": false,
                        "$default": true 
                    }
                },
                "restful": true
            }
        }
    }
}

Here you can see the $filter and $default fields. These fields allow for filtering 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. You could also determine whether plugin should be registered at all. See the code below for an example based on this manifest.json file.

// 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.

Advanced

Here are some examples of the short-stop resolvers available that makes 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 an example.

Further Reading

• License
• Code of conduct
• Contributing
• Changelog

Changelog

1.0.0 - 2019-04-19

Initial release