@usvc/boilerplate v0.3.5

@usvc/boilerplate

Quick, opinionated, Express-based boilerplate for microservices written in Node.

What's Included

• Metrics monitoring with Prometheus
• Contextual logging with Winston
• Logs centralisation with FluentD (td-agent)
• Distributed tracing with Zipkin
• Tracable request object with Zipkin
• Zipkin-instrumented Request object
• Bootstrapped HTTP server with Express
• Liveness and readiness health checks
• Cross Origin Resource Sharing (CORS) support
• Content Security Policy (CSP) support

TL;DR

• What's Included
• Usage
  • Basic Usage
  • Advanced Usage
• Examples
  • Proof-of-Concept
• Configuration
  • Configuring Boilerplate
  • Configuring Application
  • Configuring Logs Collator
  • Configuring Logger
  • Configuring Tracer
• Types
  • Health

Usage

Install this boilerplate with:

npm i @usvc/boilerplate;
# or via yarn
yarn add @usvc/boilerplate;

Basic Usage w/ No Configuration

import {Boilerplate} from '@usvc/boilerplate';

Boilerplate.init();

const {
  app, // bootstrapped Express application
  logger, // contextual logger
  request, // request object
} = Boilerplate;

const server = app.listen(3000);

server.on('listening', () => {
  logger.info('Server listening on http://localhost:3000');
});

Advanced Usage w/ Full Configurations

import {Boilerplate} from '@usvc/boilerplate';

Boilerplate.init({
  appAccessLoggingBypassUrls: [],
  appCookieSessionName: 'usvcbp',
  appCorsWhitelist: [],
  appCspChildSrc: ['"self"'],
  appCspConnectSrc: ['"self"'],
  appCspDefaultSrc: ['"self"'],
  appCspFontSrc: ['"self"'],
  appCspFrameSrc: ['"self"'],
  appCspImgSrc: ['"self"'],
  appCspMediaSrc: ['"self"'],
  appCspObjectSrc: ['"none"'],
  appCspReportUri: '/csp-report',
  appCspScriptSrc: ['"self"'],
  appCspStyleSrc: ['"self"'],
  appEnableCors: true,
  appEnableCsp: true,
  appJsonBodyContentType: '*/json',
  appJsonBodySizeLimit: '2mb',
  appLivenessCheckEndpoint: '/healthz',
  appLivenessChecks: {},
  appMetricsEndpoint: '/metrics',
  appReadinessCheckEndpoint: '/readyz',
  appReadinessChecks: {},
  appUrlEncodedBodyContentType: '*/x-www-form-urlencoded',
  appUrlEncodedBodySizeLimit: '2mb',
  logger: 'winston',
  logsCollator: 'fluentd',
  fluentdHost: 'localhost',
  fluentdPort: '24224',
  requester: 'request',
  serviceId: 'usvcbp',
  tracer: 'zipkin',
  winstonFormats: [],
  winstonLevel: 'silly',
  winstonTransports: [],
  zipkinHeaders: {},
  zipkinHost: 'localhost',
  zipkinPort: '9411',
  zipkinSampleFrequency: 1.0,
  zipkinScheme: 'http',
});

Examples

Proof-of-Concept

Requires docker and docker-compose to be available on your machine

Clone this repository, install dependencies and run:

npm run eg:poc;

To shut it down, run:

npm run eg:poc:down;

Configuration

The boilerplate is initialized through the .init() function. It accepts configuration options from both the environment as well as parameters. Note that environment configuration will always take precendence over parameter configuration, this is so that parameterised code can be written for development, but can also be modified for a production environment via environment.

Configuring Boilerplate

Configuring Application

Configuring Logs Collator

Configuring Logger

Configuring Tracer

Types

Type: Health

interface Health {
  data?: object;
  message?: string;
  status: boolean;
}

Development Lifecycle

TODO

License

This package is licensed under the MIT license. See the LICENSE file for details.

Cheers