BITBEAT WEB MODULE

Introduction

This is the official web module for bitbeat using fastify as web server.
This package will export you a web server, a web server config and basic default actions.
To use it follow the documentation of bitbeat at the homepage.

Default modules

The following modules are always enabled:

• fastify-cors
• fastify-helmet
• fastify-sensible

Optionally these modules can be enabled or disabled:

• fastify-rate-limiter (enabled in production by default)
• underPressure (enabled in production by default)
• middie (enabled in default)

Configure

The default WebConfig looks like this:

export default class WebServerConfig extends Configuration {
    constructor() {
        super();
    }

    default: WebConfigProperties = {
        options: {
            disableRequestLogging: true,
        },
        host: '0.0.0.0',
        port: 8080,
        pathForActions: 'api',
        useVersioning: true,
        useHeaderVersioning: false,
        enableMiddlewares: true,
    };

    production: WebConfigProperties = {
        fastifyRateLimit: {
            max: 100,
        },
        underPressure: {
            maxEventLoopDelay: 1000,
            maxHeapUsedBytes: 100000000,
            maxRssBytes: 100000000,
        },
    };
}

You can edit those properties by either extending the WebConfig class in your project's config folder as own class or edit it in the boot.js.

Example 1:

-- config
 |-- myOwnConfig.ts

import { WebConfig } from '@bitbeat/web';
import { merge } from 'lodash';

export default class MyOwnConfig extends WebConfig {
    constructor() {
        super();
    }

    default = {}; // this will overwrite the default props

    /* or you can do something non-destructive like this
    default = merge(default, {
        port: 3000,
    });
    */
}

Example 2:

This example happens in the boot.js:

import { registerBulk } from '@bitbeat/core';
import { WebConfig, WebServer } from '@bitbeat/web';

export default async () => {
    const webConfig = new WebConfig();
    webConfig.default.port = 3000;
    await registerBulk(new Set([webConfig, WebServer]));
};

Add actions

To add your own web action to the web server, just extend the WebAction-class in the actions folder and the web server will automatically load them. Examples can be found in the default web actions. Example:

-- actions
 |-- test.ts

import { WebAction } from '@bitbeat/web';

export default class Test extends WebAction {
    // no name means the action will be named 'Test', based on the class name
    constructor() {
        super();
    }

    async run() {}
}

Versioning

The versioning is sematic versioning like the default versioning. You can either set the server to accept the action version via url /api/v1.0.0/xx or via header Headers: Accept-Version: '1.x' if enabled (see config) and via url /api/xx. See fastify-routes for more details about the usage. The default version is always 1.0.0.

Naming

The name will be automatically generated by the name of the class, if no name set (same for default actions). Means export default class Test extends WebAction will have the name 'Test' and will be available via /api/v1.0.0/Test or via the header version.

Methods

To make the action available only for some type of rest requests use this.methods. By default GET and POST is enabled.

Content type

Here you can configure the type, the response should answer with. Make sure the content is always matching the content type.

Strict mode

You have the option to enable strict mode for the output and the accept type.

Accept type

If you enable this, the server will reject the request if the response type is not equal the accept type.

Output

If you enable output, the server will strip any params which are not defined in the output schema.

Custom integrations

To add your own custom logic to the existing server use one of the following methods:

• preRegister
• postRegister
• postRouteRegister
• postServerStart
• postServerStop

These are a sets of functions, which will run one by one and support async. There is always the "current" WebServer-runtime and WebConfig provided in those functions.