@zrpaplicacoes/maintenance_mode

Express.js middleware for switching to maintenance mode.

Usage no npm install needed!

<script type="module">
  import zrpaplicacoesMaintenanceMode from 'https://cdn.skypack.dev/@zrpaplicacoes/maintenance_mode';
</script>

README

Maintenance Mode

Express.js middleware for switching the API to maintenance mode.

Description

Support modes of work:

  • configuration-based (based on environment variables)
  • hot-switch mode (no redeployment, based on HTTP POST/DELETE)

In configuration-based mode, you should provide the mode signaling the application on maintenance mode and restart the application:

var options = {
  mode: true
};
maintenance(app, options);

Endpoint (HOT-SWITCH)

Hot-switch is could more convenient since doesn't require re-start. And could be controlled by HTTP:

# Maintenance Mode ON
HTTP POST https://api/maintenance/on

# Maintenance Mode OFF
HTTP POST https://api/maintenance/off

# Maintenance Mode OFF
HTTP DELETE https://api/maintenance

# Maintenance Mode Status (public)
HTTP GET https://api/maintenance/status

The access key is send in Request Headers with maintenance-private-key

Example:

curl --location --request POST 'https://api/maintenance/on' \
--header 'maintenance-private-key: ABC123'

curl --location --request DELETE 'https://api/maintenance' \
--header 'maintenance-private-key: ABC123'

curl --location --request GET 'https://api/maintenance/status'

Status Response

{
    "mode": false,
    "retryAfter": "30",
    "current": true
}

Usage

Install maintenance_mode from npm,

$ npm install @zrpaplicacoes/maintenance_mode

Update your application,

const app = express();
const maintenance = require('@zrpaplicacoes/maintenance_mode');
const options = {};

app.use(maintenance(app, options));

app.get('/', function (req, res) {
    console.log(req.url);
    res.send(200);
});

Specifying the initial mode,

// starts the app in maintenance mode
const options = { mode: true };

Specifying the adapter Redis (Memory is default),

// starts with another adapter, 
const RedisAdapter = require('@zrpaplicacoes/maintenance_mode/lib/RedisAdapter');
const options = {
  adapter: new RedisAdapter({
    prefix: 'anything_',
    url: 'redis://127.0.0.1:6379/0',
  }),
};

Options

Instead of initial you can customize maintenance_mode with options object,

const options = {
    mode: false,
    endpoint: false,
    url: '/maintenance',
    accessKey: 'CHANGE_ME',
    status: 503,
    message: 'sorry, we are on maintenance',
    checkpoint: '/status',
    retryAfter: 30,
    adapter: new <MemoryAdapter|RedisAdapter>()
};

maintenance(app, options);

Attributes

Option Type Default Value Description
mode Boolean false Initial maintenance mode on deploy/redeployment
endpoint Boolean false Active Endpoint to Hot-Switch
url String '/maintenance' Endpoint to responde if endpoint is actived
accessKey String 'CHANGE_ME' Access key for switch maintenance mode (depend endpoint is actived)
status Integer 503 HTTP Status Code
message String 'sorry, we are on maintenance' Message Human-like
checkpoint String /status Endpoint to check if maintenance mode is off
retryAfter Integer 30 Waiting time to next request in seconds
adapter Adapter 30 Waiting time to next request in seconds

Adapters

prefix allow separate maintenance_mode to module, environment, ecc.

MemoryAdapter

new MemoryAdapter({
  prefix: ''
});

RedisAdapter

new RedisAdapter({
  prefix: '',
  url: 'redis://redis:6379/0'
});

Licence (MIT)