# 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
1

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

        Last Updated: 2/5/2023, 1:16:22 PM

        Other topics