nodejs-server-maintenance

Express.js middleware to control server maintenance mode

Installation

yarn add nodejs-server-maintenance

or

npm install nodejs-server-maintenance

Usage

Using default options

const maintenance = require('nodejs-server-maintenance');

maintenance(app);

Initializing maintenance mode to true

const maintenance = require('nodejs-server-maintenance');

maintenance(app, true);

Using customized configuration

const maintenance = require('nodejs-server-maintenance');

// these are the default values

const options = {
    mode: false,
    accessKey: "pw1234", // optional
    endpoint: '/maintenance',
    filePath: null,
    useApi: false,
    statusCode: 503,
    message: 'Error 503: Server is temporarily unavailable, please try again lager.', // 503 is taken from statusCode
    blockMethods: ['GET']
}

maintenance(app, options);

Setting a customized access middleware

If you want to handle the access to the endpoint by yourself, you can add a function. It allows you to hide the endpoint API and control the response.

const maintenance = require('nodejs-server-maintenance');

// options

const middleware = (req, res, next) => {
	try {
		// you can verify the token if you use jwt or have other conditions
		const  token  =  req.headers.authorization.split("  ")[1];
		if (token  ===  "token1234") return  next();
		throw  new  Error();
	} catch (error) {
		res.sendStatus(404);	
	}
};

maintenance(app, options, middleware);

Setting maintenance mode on

POST request to http://yourserver/[endpoint]?access_key=[accessKey]

You can also customize the parameters sending a JSON with the fields below you want to change without changing your code (until the app restarts)

{
    filePath: '...',
    useApi: false,
    statusCode: 503,
    message: '...',
    blockMethods: ['GET']
}

Setting maintenance mode off

DELETE request to http://yourserver/[endpoint]?access_key=[accessKey]

In order to reset the customized parameters above, send the following JSON or restart the server

{
    reset: true
}

Getting maintenance status

GET request to http://yourserver/[endpoint]/status

Response:

{
    success: true,
    mode: true/false
}

Notes

• accessKey is optional but is recommended to use
• The maintenance should be defined before your app routes and after your body parser
• The priority of the variables is
  1. useApi - if true the server will send a JSON
  2. filePath - if filePath is provided, the server will send that file
  3. message - if above are false or null, the message will be sent by default

Variables

Name | Type | Description ------------ | ------------- | ------------- mode | Boolean | Sets maintenance mode on/off accessKey | String | Allows access only using the access key endpoint | String | The URL endpoint of the API requests filePath | String | The path to the file to send (the default value is null) message | String | A default message to display useApi | Boolean | If true, the server will send JSON { statusCode, message } statusCode | Number | Response status code blockMethods | Array (strings) | Blocks the request methods during the maintenance