README.md

composite-service

Compose multiple services into one

In essence, composite-service is a Node.js library to use in a script that composes multiple services into one "composite service", by managing a child process for each composed service.

A composite service script is useful for packaging an application of multiple services or process types (e.g. a frontend web app & a backend web api) within a single Docker image, for simplified delivery and deployment. That is, if you have multiple services that make up your overall application, you do not need to deploy them to your hosting individually (multiplying cost & weakening manageability), nor do you need to use more advanced/complex tools like Kubernetes to manage your deployments; You can just bundle the services together with a composite service script.

Features

• Configuration lives in a script, not .json or .yaml file & therefore supports startup tasks and dynamic configurations
• Includes TypeScript types, meaning autocompletion & code intelligence in your IDE even if you're writing JavaScript
• Configurable Crash Handling with smart default
• Graceful Startup, to ensure a service is only started after the services it depends on are ready
• Options for Shutting Down
• Supports executing Node.js CLI programs by name
• Companion composite-service-http-gateway package

Table of Contents

• Install
• Basic Usage
• Crash Handling
  • Default Behavior
  • Configuring Behavior
• Graceful Startup
• Shutting Down

Install

npm install composite-service

Basic Usage

Create a Node.js script that calls the exported startCompositeService function with a CompositeServiceConfig object. That object includes a services property, which is a collection of ServiceConfig objects keyed by service ID.

The complete documentation for these config object interfaces is in the source code ( CompositeServiceConfig.ts & ServiceConfig.ts ) and should be accessible with code intelligence in most IDEs. Please use this as your main reference when using composite-service.

The most basic properties of ServiceConfig are:

• cwd Current working directory of the service. Defaults to '.'.
• command Command used to run the service. Required.
• env Environment variables to pass to the service. Defaults to process.env.

Example

const { startCompositeService } = require('composite-service')

const { PORT, DATABASE_URL } = process.env

startCompositeService({
  services: {
    worker: {
      cwd: `${__dirname}/worker`,
      command: 'node main.js',
      env: { DATABASE_URL },
    },
    web: {
      cwd: `${__dirname}/web`,
      command: ['node', 'server.js'],
      env: { PORT, DATABASE_URL },
    },
  },
})

The above script will:

1. Start the described services (worker & web) with their respective configuration
2. Print interleaved stdout & stderr of each service, each line prepended with the service ID
3. Restart services after they crash
4. Shut down services and exit when it is itself told to shut down

Crash Handling

A "crash" is considered to be when a service exits unexpectedly (i.e. without being told to do so).

Default behavior

The default behavior for handling crashes is to restart the service if it already achieved "ready" status. If the service crashes before becoming "ready" (i.e. during startup), the composite service itself will bail out and crash (shut down & exit). This saves us from burning system resources (continuously crashing & restarting) when a service is completely broken.

To benefit from this behavior, ServiceConfig.ready must be defined. Otherwise, the service is considered ready as soon as the process is spawned, and therefore the service will always be restarted after a crash, even if it happened during startup.

Example

These changes to the initial example will prevent either service from spinning and burning resources when unable to start up:

const { startCompositeService } = require('composite-service')

const { PORT, DATABASE_URL } = process.env

startCompositeService({
  services: {
    worker: {
      cwd: `${__dirname}/worker`,
      command: 'node main.js',
      env: { DATABASE_URL },
+     // ready once a certain line appears in the console output
+     ready: ctx => ctx.onceOutputLine(line => line === 'Started worker'),
    },
    web: {
      cwd: `${__dirname}/web`,
      command: ['node', 'server.js'],
      env: { PORT, DATABASE_URL },
+     // ready once port is accepting connections
+     ready: ctx => ctx.onceTcpPortUsed(PORT),
    },
  },
})

Configuring behavior

Crash handling behavior can be configured with ServiceConfig.onCrash. This is a function executed each time the service crashes, to determine whether to restart the service or to crash the composite service, and possibly perform arbitrary tasks such as sending an email or calling a web hook. It receives an OnCrashContext object with some contextual information.

The default crash handling behavior (described in the section above) is implemented as the default value for onCrash. You may want to include this logic in your own custom onCrash functions:

ctx => {
  if (!ctx.isServiceReady) throw new Error('Crashed before becoming ready')
}

Example

const { startCompositeService } = require('composite-service')

startCompositeService({
  services: { ... },
  // Override configuration defaults for all services
  serviceDefaults: {
    onCrash: async ctx => {
      // Crash composite process if service crashed before becoming ready
      if (!ctx.isServiceReady) throw new Error('Crashed before becoming ready')
      // Try sending an alert via email (but don't wait for it or require it to succeed)
      email('me@mydomain.com', `Service ${ctx.serviceId} crashed`, ctx.crash.logTail.join('\n'))
        .catch(console.error)
      // Do "something async" before restarting the service
      await doSomethingAsync()
    },
    // Set max length of `ctx.crash.logTail` used above (default is 0)
    logTailLength: 5,
  },
})

Graceful Startup

If we have a service that depends on another service or services, and don't want it to be started until the other "dependency" service or services are "ready", we can use dependencies and ready ServiceConfig properties. A service will not be started until all its dependencies are ready according to their respective ready config.

Example

The following script will start web only after api is accepting connections. This prevents web from appearing ready to handle requests before it's actually ready, and allows it to safely make calls to api during startup.

const { startCompositeService } = require('composite-service')

const webPort = process.env.PORT || 3000
const apiPort = process.env.API_PORT || 8000

startCompositeService({
  services: {
    web: {
      dependencies: ['api'],
      command: 'node web/server.js',
      env: { PORT: webPort, API_ENDPOINT: `http://localhost:${apiPort}` },
      ready: ctx => ctx.onceTcpPortUsed(webPort),
    },
    api: {
      command: 'node api/server.js',
      env: { PORT: apiPort },
      ready: ctx => ctx.onceTcpPortUsed(apiPort),
    },
  },
})

Shutting Down

The composite service will shut down when it encounters a fatal error (error spawning process, or error from ready or onCrash config functions) or when it receives a signal to shut down (ctrl+c, SIGINT, or SIGTERM).

The default procedure for shutting down is to immediately signal all composed services to shut down, and wait for them to exit before exiting itself. Where supported (i.e. on non-Windows systems), a SIGINT signal is issued first, and if the process does not exit within a period of time (ServiceConfig.forceKillTimeout), a SIGKILL signal is issued to forcibly kill the process. On Windows, where such signal types don't exist, a single signal is issued, which forcibly kills the process.

Some optional behaviors can be enabled. See gracefulShutdown & windowsCtrlCShutdown properties in CompositeServiceConfig.

Hint: If a composed service needs to do any cleanup before exiting, you should enable windowsCtrlCShutdown to allow for that when on Windows. This option however comes with some caveats. See windowsCtrlCShutdown in CompositeServiceConfig.