express-maintenance-mode

Express middleware that allows you to put the server(s) in maintenance mode

Table of Contents

• Motivation
• How it works
• Install
• Usage
  • Redis example
• API
• Contributors
• License

Motivation

I developed this module because I needed an easy way to transfer all servers behind the load balancer to maintenance mode with one API request. That is why I made methods for getting and setting external maintenance status. In my production environment, I use these techniques to keep the service status in sync with Redis. This way, all servers in the load balancing group are aware of the status update within a minute.

How it works

Module provides simple api to control maintenance state. Access to all middlewares below can be controlled by maintenance middleware

Install

npm:

npm install express-maintenance-mode

yarn:

yarn add express-maintenance-mode

Usage

import { ExpressMaintenanceMode } from 'express-maintenance-mode';

const maintenance = new ExpressMaintenanceMode<MaintenanceResponseBody>({
  maintenancePath: '/maintenance', // Path to control maintenance state
  apiBasePath: '/api', // Base path of your API
  accessKey: 'changeme', // Access key for maintenance endpoint. Works without authorization if not provided
  getExternalMaintenanceState: () => {
    // Optional
    // Your method to get external state
  },
  setExternalMaintenanceState: () => {
    // Optional
    // Your method to set external state
  },
  localMaintenanceStateTTL: 6000 // Lifetime of local maintenance state, until it be synced with external state
  maintenanceResponseOptions: { // Optional
    statusCode: 302, // Default to 503
    body: fs.readdirSync('path/to/maintenance/index.html').toString()
  }
});

// Optional
interface MaintenanceResponseBody {
  message: string;
}

// App example

app.use(bodyParser.json());
app.use(maintenance.middleware)
// ...
app.use(yourGreatAPIRouter)

Redis example

import {MaintenanceState} from './index';

const getExternalMaintenanceState = async (): Promise<MaintenanceState<MaintenanceResponseBody>> => {
  return yourRedisDAO.get<MaintenanceState<MaintenanceResponseBody>>('maintenance');
}
  
const setExternalState = async (maintenanceState: MaintenanceState<MaintenanceResponseBody>) => {
  yourRedicDAO.save('maintenance', maintenanceState);
}

API

To control maintenance status three methods available:

GET - to get maintenance status POST - to set server in maintenance mode DELETE - to set server in regular mode

Using POST method you can set response status code and body

Request body:

{
  "statusCode": 503,
  "body": {
    "message": "Server in maintenance mode"
  }
}

Contributors

Name
George Lykuanov

License

Apache-2.0 © George Lykuanov