The circuit breaker add-on helps to reduce the impact of failures on service architectures, where services asynchronously invoke other services.

A failure can occur in either of the following situations:

In these situations, other services might exhaust critical resources by attempting to contact a service that is too slow or unable to respond. These other services can then become unusable, which causes a cascading failure that affects the entire microservice architecture. By using the circuit breaker add-on in your Node.js application code, you can make your applications more fault tolerant and resilient.

The circuit breaker pattern is designed to handle failures in service architectures and to prevent cascading failures across multiple systems. A circuit breaker can act as a proxy for a client function that is sending requests to a remote service endpoint that might fail. You can wrap any requests sent to the remote service endpoint in a circuit breaker object. The circuit breaker then calls the remote service and monitors its status. If the number of failures reaches a specified percentage threshold, the circuit breaker is triggered. The circuit breaker then ensures that any further requests to the remote service are automatically blocked with an error message or fallback response for a specified time period.

Based on the circuit breaker design pattern, the circuit breaker has one of the following states at any specific time:

This example application consists of two microservices:

greeting-service imports the circuit breaker add-on. greeting-service protects calls to the remote name-service by wrapping these calls in a circuit breaker object.

greeting-service exposes the following endpoints:

The following code example shows how to develop greeting-service:

'use strict';
const path = require('path');
const http = require('http');
const express = require('express');
const bodyParser = require('body-parser');

// Import the circuit breaker add-on
const Opossum = require('@redhat/opossum');

const probe = require('kube-probe');
const nameService = require('./lib/name-service-client');

const app = express();
const server = http.createServer(app);

// Add basic health check endpoints
probe(app);

const nameServiceHost = process.env.NAME_SERVICE_HOST || 'http://nodejs-circuit-breaker-redhat-name:8080';

// Set some circuit breaker options
const circuitOptions = {
  timeout: 3000, // If name service takes longer than 0.3 seconds,
                 // trigger a failure
  errorThresholdPercentage: 50, // When 50% of requests fail,
                                // trip the circuit
  resetTimeout: 10000 // After 10 seconds, try again.
};

// Create a new circuit breaker instance and pass the remote nameService
// as its first parameter
const circuit = new Opossum(nameService, circuitOptions);

// Create the app with an initial websocket endpoint
require('./lib/web-socket')(server, circuit);

// Serve index.html from the file system
app.use(express.static(path.join(__dirname, 'public')));
// Expose the license.html at http[s]://[host]:[port]/licences/licenses.html
app.use('/licenses', express.static(path.join(__dirname, 'licenses')));

// Send and receive json
app.use(bodyParser.json());

// Greeting API
app.get('/api/greeting', (request, response) => {
  // Use the circuit breaker’s fire method to execute the call
  // to the name service
  circuit.fire(`${nameServiceHost}/api/name`).then(name => {
    response.send({ content: `Hello, ${name}`, time: new Date() });
  }).catch(console.error);
});

// Circuit breaker state API
app.get('/api/cb-state', (request, response) => {
  response.send({ state: circuit.opened ? 'open' : 'closed' });
});

app.get('/api/name-service-host', (request, response) => {
  response.send({ host: nameServiceHost });
});

module.exports = server;

name-service exposes the following endpoints:

The following code example shows how to develop name-service:

'use strict';

const path = require('path');
const http = require('http');
const express = require('express');
const bodyParser = require('body-parser');
const cors = require('cors');
const probe = require('kube-probe');

const app = express();
const server = http.createServer(app);

// Adds basic health-check endpoints
probe(app);

let isOn = true;
const { update, sendMessage } = require('./lib/web-socket')(server, _ => isOn);

// Send and receive json
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended: false }));

// CORS support
app.use(cors());

// Name service API
app.get('/api/name', (request, response) => {
  if (isOn) {
    response.send('World!');
  } else {
    response.status(500).send('Name service down');
  }
  sendMessage(`${new Date()} ${isOn ? 'OK' : 'FAIL'}`);
});

// Current state of service
app.put('/api/state', (request, response) => {
  isOn = request.body.state === 'ok';
  response.send({ state: isOn });
  update();
});

app.get('/api/info',
  (request, response) => response.send({ state: isOn ? 'ok' : 'fail' }));

// Expose the license.html at http[s]://[host]:[port]/licenses/licenses.html
app.use('/licenses', express.static(path.join(__dirname, 'licenses')));

module.exports = server;

You can use the fallback method of the circuit breaker object to add your defined fallback function to the circuit breaker. If the call to the remote service fails after the circuit breaker fire method is executed, the fallback function is then called automatically.

For more information about the fallback method and other member types that you can use with the circuit breaker add-on, see the Circuit Breaker Add-on 5.0.0 API Documentation.

This example is based on the greeting-service that sends calls to the remote name-service that might fail. This example shows how to define a fallback function that prints the following message to the web console: This is the fallback function.

...

// Import the circuit breaker add-on
const Opossum = require('@redhat/opossum');

...

// Create a new circuit breaker instance and pass the
// remote nameService as its first parameter
const circuit = new Opossum(nameService, circuitOptions);

// Define a fallback function that will be called when
// the remote nameService fails
function fallback(result) {
    console.log('This is the fallback function', result);
}

// Use the circuit breaker's fallback method to add the
// fallback function to the circuit breaker instance
circuit.fallback(fallback);

...

// Greeting API
app.get('/api/greeting', (request, response) => {
  // Use the circuit breaker’s fire method to execute the call
  // to the name service
  circuit.fire(`${nameServiceHost}/api/name`).then(name => {
    response.send({ content: `Hello, ${name}`, time: new Date() });
  }).catch(console.error);
});

...

The circuit breaker add-on emits the following types of events:

This example shows how to listen for different types of events that the circuit breaker emits. In this example, a fetch function is used to request a microservice URL. Depending on the event type, the relevant message is printed to the web console.

...

// Import the circuit breaker add-on
const Opossum = require('@redhat/opossum');

...

// Create a new circuit breaker instance and pass the
// protected function call as its first parameter
const circuit = new Opossum(() => $.get(route), circuitOptions);

...

// Listen for success events emitted when the
// circuit breaker action completes successfully
circuit.on('success',
  (result) => {
    console.log(`SUCCESS: ${JSON.stringify(result)}`);
  }

// Listen for timeout events emitted when the timeout
// period for the circuit breaker action expires
circuit.on('timeout',
  (result) => {
    console.log(`TIMEOUT: ${url} is taking too long to respond.`);
  }

// Listen for reject events emitted when the
// circuit breaker has an open or half-open state
circuit.on('reject',
  (result) => {
    console.log(`REJECTED: The breaker for ${url} is open. Failing fast.`);
  }

// Listen for open events emitted when the
// circuit breaker moves to an open state
circuit.on('open',
  (result) => {
    console.log(`OPEN: The breaker for ${url} just opened.`);
  }

// Listen for halfOpen events emitted when the
// circuit breaker moves to a half-open state
circuit.on('halfOpen',
  (result) => {
    console.log(`HALF_OPEN: The breaker for ${url} is half open.`);
  }

// Listen for close events emitted when the
// circuit breaker moves to a closed state
circuit.on('close',
  (result) => {
    console.log(`CLOSE: The breaker for ${url} has closed. Service OK.`);
  }

// Listen for fallback events emitted when
// a fallback function is executed
circuit.on('fallback',
  (result) => {
    console.log(`FALLBACK: ${JSON.stringify(data)}`);
  }