@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 one or more manifest.json files. The userConfigPath accepts a string that is a path to a single manifest.json file, or an array of path strings to support merging multiple manifest files. Duplicate keys in configuration files will be overwritten upon merging. If an array is passed, values of the config file that is the last index of userConfigPath takes precedence when merging, otherwise values from the single config file passed to userConfigPath takes precedence. 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');

// Init a new Catalyst server, and pass the path to your manifest file to the userConfigPath option to compose your app plugins
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();

// Alternatively, pass an array of paths to compose your app plugins from separate manifest files.
const server = await Catalyst.init({
    userConfigPath: [
        path.resolve(__dirname, 'manifest.json'),
        path.resolve(__dirname, '/external/manifest.json')
    ]
});

manifest.json

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

Catalyst.init() Options

• userConfigPath - Path to the json configuration file (see examples).
• onConfig - Hook for modifying config prior to creating list of plugins to register (can be async). (config) => {return config;}
• defaults - default pre-resolved configuration values. Can be an object or a path to a json file.
• overrides - optional override pre-resolved configuration values. Can be an object or a path to a json file.
• baseDir - Alternative location to base shortstop relative paths from.
• environment - Additional criteria for confidence property resolution and defaults to { env: process.env }.
• shortstopHandlers - Object for additional shortstop handlers.
• enableShutdownListeners - Flag indicator for enabling or disabling execution of shutdown listeners, default 'true'

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": {
            "plugin": "require:@hapi/inert"
        },
        "vision": {
            "plugin": "require:@hapi/vision",
            "options": {
                "engines": {
                    "html": "require:handlebars"
                },
                "path": "path:./templates"
            }
        }
    },
    // Hapi routes
    "routes": [
        {
            "method": "GET",
            "path": "/my-file.txt",
            "handler": {
                "file": "path:./my-file.txt"
            }
        }
    ]
}

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": {
            "plugin": "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.

    "plugin": "require:@hapi/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

5.5.2 (2023-02-15)

Bug Fixes

• Altering the order of semantic release config file to have it correct (#77) (1342685)