Skip to main content
Redhat Developers  Logo
  • Products

    Featured

    • Red Hat Enterprise Linux
      Red Hat Enterprise Linux Icon
    • Red Hat OpenShift AI
      Red Hat OpenShift AI
    • Red Hat Enterprise Linux AI
      Linux icon inside of a brain
    • Image mode for Red Hat Enterprise Linux
      RHEL image mode
    • Red Hat OpenShift
      Openshift icon
    • Red Hat Ansible Automation Platform
      Ansible icon
    • Red Hat Developer Hub
      Developer Hub
    • View All Red Hat Products
    • Linux

      • Red Hat Enterprise Linux
      • Image mode for Red Hat Enterprise Linux
      • Red Hat Universal Base Images (UBI)
    • Java runtimes & frameworks

      • JBoss Enterprise Application Platform
      • Red Hat build of OpenJDK
    • Kubernetes

      • Red Hat OpenShift
      • Microsoft Azure Red Hat OpenShift
      • Red Hat OpenShift Virtualization
      • Red Hat OpenShift Lightspeed
    • Integration & App Connectivity

      • Red Hat Build of Apache Camel
      • Red Hat Service Interconnect
      • Red Hat Connectivity Link
    • AI/ML

      • Red Hat OpenShift AI
      • Red Hat Enterprise Linux AI
    • Automation

      • Red Hat Ansible Automation Platform
      • Red Hat Ansible Lightspeed
    • Developer tools

      • Red Hat Trusted Software Supply Chain
      • Podman Desktop
      • Red Hat OpenShift Dev Spaces
    • Developer Sandbox

      Developer Sandbox
      Try Red Hat products and technologies without setup or configuration fees for 30 days with this shared Openshift and Kubernetes cluster.
    • Try at no cost
  • Technologies

    Featured

    • AI/ML
      AI/ML Icon
    • Linux
      Linux Icon
    • Kubernetes
      Cloud icon
    • Automation
      Automation Icon showing arrows moving in a circle around a gear
    • View All Technologies
    • Programming Languages & Frameworks

      • Java
      • Python
      • JavaScript
    • System Design & Architecture

      • Red Hat architecture and design patterns
      • Microservices
      • Event-Driven Architecture
      • Databases
    • Developer Productivity

      • Developer productivity
      • Developer Tools
      • GitOps
    • Secure Development & Architectures

      • Security
      • Secure coding
    • Platform Engineering

      • DevOps
      • DevSecOps
      • Ansible automation for applications and services
    • Automated Data Processing

      • AI/ML
      • Data Science
      • Apache Kafka on Kubernetes
      • View All Technologies
    • Start exploring in the Developer Sandbox for free

      sandbox graphic
      Try Red Hat's products and technologies without setup or configuration.
    • Try at no cost
  • Learn

    Featured

    • Kubernetes & Cloud Native
      Openshift icon
    • Linux
      Rhel icon
    • Automation
      Ansible cloud icon
    • Java
      Java icon
    • AI/ML
      AI/ML Icon
    • View All Learning Resources

    E-Books

    • GitOps Cookbook
    • Podman in Action
    • Kubernetes Operators
    • The Path to GitOps
    • View All E-books

    Cheat Sheets

    • Linux Commands
    • Bash Commands
    • Git
    • systemd Commands
    • View All Cheat Sheets

    Documentation

    • API Catalog
    • Product Documentation
    • Legacy Documentation
    • Red Hat Learning

      Learning image
      Boost your technical skills to expert-level with the help of interactive lessons offered by various Red Hat Learning programs.
    • Explore Red Hat Learning
  • Developer Sandbox

    Developer Sandbox

    • Access Red Hat’s products and technologies without setup or configuration, and start developing quicker than ever before with our new, no-cost sandbox environments.
    • Explore Developer Sandbox

    Featured Developer Sandbox activities

    • Get started with your Developer Sandbox
    • OpenShift virtualization and application modernization using the Developer Sandbox
    • Explore all Developer Sandbox activities

    Ready to start developing apps?

    • Try at no cost
  • Blog
  • Events
  • Videos

Fail fast with Opossum circuit breaker in Node.js

April 15, 2021
Lucas Holmquist
Related topics:
KubernetesMicroservicesNode.js
Related products:
Red Hat build of Node.js

Share:

    The microservices pattern is pretty standard for today's software architecture. Microservices let you break up your application into small chunks and avoid having one giant monolith. The only problem is that if one of these services fails, it could have a cascading effect on your whole architecture.

    Luckily, there is another pattern that can help with this issue: The circuit breaker pattern.

    This article explains what a circuit breaker is and how to use the pattern in your Node.js applications. We'll use Opossum, a Node.js implementation of the circuit breaker pattern.

    What is a circuit breaker?

    Before we dive into an example, let's quickly define a circuit breaker and how to use the pattern in your code.

    You might already be familiar with circuit breakers if you’ve tried to run too many household appliances at once. The lights go out due to an overwhelming influx of electricity. To restore power, you need to go down to the basement, find the electrical box, search for the breaker that “tripped,” and reset it. Circuit breakers protect your residence by shutting down during an electrical surge.

    The circuit breaker pattern works similarly when dealing with microservices that communicate over a network. Its purpose is to reduce the impact of a service that is running too slowly or that can’t be reached due to a network failure. The circuit breaker monitors for such failures. Once failures reach a particular threshold, the circuit “trips,” and any call made after that either returns an error or adopts a fallback response. Then, after a set time has passed, the circuit breaker makes test calls to the affected services. If the calls are successful, the circuit closes, and traffic starts flowing again.

    Circuit breakers are especially important when multiple services depend on each other. If one service fails, it could take down the whole architecture. Remember the first Death Star explosion in the Star Wars movie series? A good circuit breaker might have avoided that.

    What is Opossum?

    Opossum is a circuit breaker for Node.js. When things start to fail, opossum plays dead and fails fast. If you want to, you can provide a fallback function to be executed when in the failure state.

    Opossum has been a community project since late 2016, and it now has more than 70,000 downloads per week. It is supported by the Nodeshift community. Recently, Red Hat has released a fully supported version of Opossum that is distributed through Red Hat’s customer registry as @redhat/opossum. Opossum will always be a community project, but if you would like to know that the version you are using has Red Hat's support, then the @redhat/opossum version might be for you. You can learn more about Red Hat's Node.js offerings here.

    The following sections show how to add this module to an application and how to use it to protect your microservices.

    Adding Red Hat Opossum to your application

    Adding the @redhat/opossum module to your application is just like adding any other Node.js module, with one small change. Because you will download this module from the Red Hat customer registry, you need to tell npm to download any modules with the @redhat namespace from the Red Hat registry while continuing to download all other modules from the upstream NPM registry.

    To start, add a .npmrc file in your application's root directory. The file should look something like this:

    @redhat:registry=https://npm.registry.redhat.com
    registry=https://registry.npmjs.org
    

    With this file in place, you can run the following command successfully:

    $ npm install @redhat/opossum
    

    To require the module in your application, insert the same kind of statement you would for every other Node.js module:

    const CircuitBreaker = require(‘@redhat/opossum’)
    

    Now, let's take a look at an example.

    Example: Opossum circuit breaker for Node.js

    For this example, we are going to use the Nodeshift Circuit Breaker Starter Application.

    Note: This example works the same way on both the community and Red Hat versions of Opossum.

    The example consists of two simple Node.js microservices, so let's look at them both.

    The greeting service

    The greeting-service is the application's entry point. A simple web page makes a call to the greeting REST endpoint. This endpoint then makes a call, wrapped in a circuit breaker, to the second service. The web page also has a button to let you toggle the name service (which I will introduce shortly) on or off to simulate a network failure.

    Here's the code responsible for the greeting service:

    ...
    // We require Opossum
    const Opossum = require('@redhat/opossum');
    …
    
    // Set some circuit breaker options
    const circuitOptions = {
      timeout: 3000, // If name service takes longer than .3 seconds, trigger a failure
      errorThresholdPercentage: 50, // When 50% of requests fail, trip the circuit
      resetTimeout: 10000 // After 10 seconds, try again.
    };
    …
    
    // Use a circuit breaker for the name service and define fallback function
    const circuit = new Opossum(nameService, circuitOptions);
    circuit.fallback(_ => 'Fallback');
    
    …
    
    // Greeting API
    app.get('/api/greeting', (request, response) => {
     // Using the Circuits 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);
    });
    

    Next, we pass the nameService function as the first argument to the circuit breaker. It looks something like the following, which is a standard call to another endpoint using axios:

    'use strict';
    const axios = require('axios');
    
    module.exports = endpoint => {
      return new Promise((resolve, reject) => {
        axios.get(endpoint)
          .then(response => {
            if (response.status !== 200) {
              return reject(new Error(`Expected status code 200, instead got ${response.status}`));
            }
    
            resolve(response.data);
          })
          .catch(reject);
      });
    };
    

    The name service

    The other microservice, name-service, is a REST endpoint that sends back a response based on the on or off toggle I mentioned before.

    Starting the application is straightforward. From the repository's root directory, run the ./start-localhost.sh file to bring up the two Node.js processes. The script will also attempt to open a web browser to the location of the running application.

    Pressing the invoke button on the web page contacts the first endpoint. The endpoint sends back a response saying whether it could contact the second service or had to use the fallback. You can click the toggle button to simulate a network failure.

    Conclusion

    This article has shown how a circuit breaker helps to reduce unexpected failures in microservices. You can use the @redhat/opossum module to add this pattern to your Node.js applications. To find out more about this new supported offering, check out the article Opossum: Fully supported circuit breaker module for Red Hat build of Node.js on the Red Hat Customer Portal.

    See these resources to learn more about the topics discussed in this article:

    • For more more about circuit breaking, see Microservice Architecture's introduction to the circuit breaker pattern.
    • Also see Martin Fowler's very good article about the circuit breaker pattern.
    • See the Opossum API documentation for more about what you can do with @redhat/opossum.
    • Visit the Node.js landing page to find out what else Red Hat is doing with Node.js.
    Last updated: February 11, 2024

    Recent Posts

    • How to use RHEL 10 as a WSL Podman machine

    • MINC: Fast, local Kubernetes with Podman Desktop & MicroShift

    • How to stay informed with Red Hat status notifications

    • Getting started with RHEL on WSL

    • llm-d: Kubernetes-native distributed inferencing

    Red Hat Developers logo LinkedIn YouTube Twitter Facebook

    Products

    • Red Hat Enterprise Linux
    • Red Hat OpenShift
    • Red Hat Ansible Automation Platform

    Build

    • Developer Sandbox
    • Developer Tools
    • Interactive Tutorials
    • API Catalog

    Quicklinks

    • Learning Resources
    • E-books
    • Cheat Sheets
    • Blog
    • Events
    • Newsletter

    Communicate

    • About us
    • Contact sales
    • Find a partner
    • Report a website issue
    • Site Status Dashboard
    • Report a security problem

    RED HAT DEVELOPER

    Build here. Go anywhere.

    We serve the builders. The problem solvers who create careers with code.

    Join us if you’re a developer, software engineer, web designer, front-end designer, UX designer, computer scientist, architect, tester, product manager, project manager or team lead.

    Sign me up

    Red Hat legal and privacy links

    • About Red Hat
    • Jobs
    • Events
    • Locations
    • Contact Red Hat
    • Red Hat Blog
    • Inclusion at Red Hat
    • Cool Stuff Store
    • Red Hat Summit

    Red Hat legal and privacy links

    • Privacy statement
    • Terms of use
    • All policies and guidelines
    • Digital accessibility

    Report a website issue