# Terminus

Terminus is a package to adds graceful shutdown and Kubernetes readiness / liveliness checks for any HTTP applications. This tutorial will show you how to install and use Terminus with Ts.ED.

# Installation

Before using terminus, we need to install the terminus (opens new window) module.

npm install --save @godaddy/terminus @tsed/terminus

Then import @tsed/terminus and add the following configuration in your Server.ts:

# Options

terminus configuration options waiting the same option description in the official Terminus documentation here (opens new window). The following the options are managed by the @tsed/terminus package:

healthChecks
onSignal
onSendFailureDuringShutdown
onShutdown
beforeShutdown
onSigterm

export type TerminusSettings = Omit<
  TerminusOptions,
  "healthChecks" | "onSignal" | "onSendFailureDuringShutdown" | "onShutdown" | "beforeShutdown" | "onSigterm"
>;

1
2
3
4

# Usage

# Readiness / liveliness checks

To create a readiness / liveliness checks use the @Health decorator.

import {Health} from "@tsed/terminus";
import {Injectable, Inject} from "@tsed/di";

@Injectable()
class MongoCtrl {
  @Health("mongo")
  async check() {
    // Here check the mongo health
    return "ok";
  }
}

1
2
3
4
5
6
7
8
9
10
11

You can also create an HealthCheckError when an error appear during your check.

import {Health} from "@tsed/terminus";
import {Injectable, Inject} from "@tsed/di";
import {HealthCheckError} from "@godaddy/terminus";
import {REDIS_CONNECTION} from "./RedisConnection";

@Injectable()
class RedisClient {
  @Inject(REDIS_CONNECTION)
  protected redisConnection: REDIS_CONNECTION;

  @Health("redis")
  async check() {
    if (this.redisConnection.status === "ready") {
      return "ok";
    }

    // Here check the redis health
    throw new HealthCheckError("failed", {
      redis: this.redisConnection.status
    });
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Expected result when calling the "/health":

{
  "status": "ok",
  "info": [
    {
      "mongo": "ok"
    },
    {
      "redis": "ok"
    }
  ],
  "details": [
    {
      "mongo": "ok"
    },
    {
      "redis": "ok"
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# Graceful shutdown

@tsed/terminus package give some decorators to handle Terminus hooks. These hooks allow you to adds graceful shutdown. Here is the list of decorators:

$beforeShutdown: Use this hook if you deploy your application with Kubernetes (see more details here (opens new window)),
$onSignal: cleanup hook, returning a promise (used to be onSigterm),
$onShutdown: called right before exiting,
$onSendFailureDuringShutdown: called before sending each 503 during shutdowns.

Example:

import {Injectable} from "@tsed/di";

@Injectable()
class RedisCtrl {
  $beforeShutdown() {
    console.log("called before shutdown");
  }

  $onSignal() {
    console.log("called on signal");
  }

  $onShutdown() {
    console.log("called on shutdown");
  }

  $onSendFailureDuringShutdown() {
    console.log("on send failure during shutdown");
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# Author

# Maintainers

Become maintainer