Stop Cascading Failures: Implementing the Circuit Breaker Pattern in Node.js

Question

In modern web development, our systems rarely run in isolation. Your Node.js server likely connects to external APIs, databases, authentication providers, and third-party payment gateways. But what happens when one of those external systems slows down or crashes entirely? If your system continues to blindly send traffic to a broken dependency, you risk crashing your own backend. This is where The Circuit Breaker Pattern comes into play.

What is the Circuit Breaker Pattern?

The Circuit Breaker pattern is an architectural safety mechanism that monitors outbound requests to external dependencies and halts execution when failure rates cross a certain threshold. Instead of allowing your application to repeatedly attempt an operation that is almost guaranteed to fail, the circuit breaker trips. It quickly returns an error or a fallback response, saving system resources and preventing minor, isolated downtime from turning into a massive, system-wide outage.

A Relatable Real-Life Analogy

Imagine you are trying to call a local pizza shop to place an order, but their phone line is completely down due to a storm. If you sit there redialing their number every ten seconds, you are wasting your own time, draining your phone's battery, and growing increasingly frustrated.

A circuit breaker is like having a smart digital assistant. The first few times you try to call, the assistant lets the call go through. But after three failed attempts, the assistant intercepts your future attempts. Instead of dialing, it instantly tells you, "The shop is unreachable right now. I am not going to let you waste your time calling them. Let's try again in ten minutes, or order from another place instead." It protects your time and energy from being wasted on a guaranteed failure.

Why It Matters Daily in the Tech Industry

In a production environment, when an external API becomes sluggish or goes offline, incoming HTTP requests to your Express server will start to pile up. Each waiting request holds onto a system thread, a database connection, and a chunk of memory. Within seconds, your server runs out of available resources and crashes.

Engineers use circuit breakers to prevent these cascading failures. By failing fast, the circuit breaker immediately releases resources back to the server. Your application can then degrade gracefully—perhaps by serving cached data or displaying a polite "service temporarily offline" message—ensuring that the rest of your application remains fast and responsive for your users.

Code Example: Simulating a Circuit Breaker in Node.js

Here is a simple, plain Node.js implementation of a circuit breaker class protecting a route in an Express application:

const express = require('express');
const app = express();

class CircuitBreaker {
  constructor(requestFunction, failureThreshold = 3, cooldownPeriod = 10000) {
    this.requestFunction = requestFunction;
    this.failureThreshold = failureThreshold;
    this.cooldownPeriod = cooldownPeriod;
    this.state = 'CLOSED'; // States: CLOSED, OPEN, HALF-OPEN
    this.failureCount = 0;
    this.nextAttemptTime = Date.now();
  }

  async execute(...args) {
    if (this.state === 'OPEN') {
      if (Date.now() > this.nextAttemptTime) {
        this.state = 'HALF-OPEN';
        console.log('[Circuit Breaker] Transitioning to HALF-OPEN. Testing service...');
      } else {
        throw new Error('Circuit is OPEN. External service temporarily offline.');
      }
    }

    try {
      const result = await this.requestFunction(...args);
      this.reset();
      return result;
    } catch (error) {
      this.handleFailure();
      throw error;
    }
  }

  reset() {
    this.state = 'CLOSED';
    this.failureCount = 0;
    console.log('[Circuit Breaker] Success! Circuit reset to CLOSED.');
  }

  handleFailure() {
    this.failureCount++;
    console.warn(`[Circuit Breaker] Failure recorded. Count: ${this.failureCount}`);
    if (this.failureCount >= this.failureThreshold) {
      this.state = 'OPEN';
      this.nextAttemptTime = Date.now() + this.cooldownPeriod;
      console.error(`[Circuit Breaker] Threshold reached! Circuit is now OPEN for ${this.cooldownPeriod}ms.`);
    }
  }
}

// A mock external API function that always fails
const unstableExternalAPI = async () => {
  throw new Error('API Timeout');
};

const breaker = new CircuitBreaker(unstableExternalAPI);

app.get('/external-data', async (req, res) => {
  try {
    const data = await breaker.execute();
    res.json({ success: true, data });
  } catch (error) {
    res.status(503).json({
      success: false,
      message: error.message,
      fallbackData: { items: ['Cached Item 1', 'Cached Item 2'] } // Graceful fallback
    });
  }
});

app.listen(3000, () => console.log('Server running on port 3000'));

Key Takeaway

Designing resilient distributed systems means accepting that third-party dependencies will inevitably fail. Instead of hoping for 100% uptime from external APIs, developers must use the Circuit Breaker pattern to isolate those inevitable failures, shield their own resources, and keep their core application functional.

---

Originally published on my blog. You can read the alternative breakdown here.