Understanding the States of OmniRoute's Circuit Breaker: CLOSED, OPEN, HALF-OPEN, and DEGRADED

OmniRoute’s circuit breaker implements four distinct states—CLOSED, DEGRADED, OPEN, and HALF_OPEN—to govern request flow and protect upstream providers from cascading failures.

The OmniRoute repository provides a resilient request routing layer that leverages the circuit breaker pattern to prevent cascade failures across AI providers. Understanding the states of OmniRoute's circuit breaker is essential for configuring robust error handling and maintaining high availability in production environments. The implementation defines these lifecycle states in src/shared/utils/circuitBreaker.ts, with transition logic controlled by configurable failure thresholds and timeout parameters.

The Four OmniRoute Circuit Breaker States

CLOSED (Normal Operation)

In the CLOSED state, the circuit breaker permits all requests to flow to the provider. This is the default starting state and indicates healthy upstream service. According to the source code in src/shared/utils/circuitBreaker.ts, the breaker returns to CLOSED after successful probe requests or when failure counts decay below the degradation threshold.

DEGRADED (Warning Threshold)

The DEGRADED state acts as an early warning system. When the failure count exceeds the degradationThreshold (approximately 60% of the failureThreshold) but remains below the full failure limit, the system logs warnings while still allowing requests. This intermediate state prepares the system for a potential transition to OPEN without immediately blocking traffic.

OPEN (Short-Circuit)

When failures reach the configured failureThreshold, the breaker transitions to OPEN, immediately rejecting new requests with a CircuitBreakerOpenError. This short-circuit behavior prevents overwhelming struggling providers and allows them time to recover. The transition logic is implemented between lines 68-73 of the core utility file.

HALF_OPEN (Recovery Probe)

After the resetTimeout expires while in OPEN state, the breaker enters HALF_OPEN and allows a limited number of probe requests (controlled by halfOpenRequests) to test provider health. Successful probes return the breaker to CLOSED; failures escalate the back-off period and return it to OPEN.

State Transition Logic and Thresholds

The state machine governs transitions through configurable thresholds defined in the circuit breaker configuration:

• degradationThreshold: Approximately 60% of the failure threshold, triggering the DEGRADED state before full tripping
• failureThreshold: The absolute count of failures required to trip the breaker to OPEN
• resetTimeout: The cooldown period (in milliseconds) before transitioning from OPEN to HALF_OPEN
• halfOpenRequests: The number of allowed probe requests during the HALF_OPEN state to verify recovery

Implementing Circuit Breakers in OmniRoute

To utilize the circuit breaker pattern in your OmniRoute implementation, import the utilities from the shared module:

import { getCircuitBreaker, STATE } from '@/shared/utils/circuitBreaker';

// Create a breaker for the "openai" provider
const openAiBreaker = getCircuitBreaker('openai', {
  failureThreshold: 5,          // Trip to OPEN after 5 failures
  resetTimeout: 30_000,         // 30-second back-off before HALF_OPEN
  halfOpenRequests: 1,          // Allow one probe request
});

// Inspect current state
if (openAiBreaker.getStatus().state === STATE.CLOSED) {
  console.log('Provider is healthy – proceed with requests');
}

// Wrap a request with the breaker
try {
  const result = await openAiBreaker.execute(() => fetchOpenAiChat(payload));
  console.log('Chat response:', result);
} catch (err) {
  // CircuitBreakerOpenError is thrown when the breaker is OPEN or HALF_OPEN and no probes remain
  console.warn('Request blocked by circuit breaker:', err);
}

For administrative control, you can force a reset:

openAiBreaker.reset();   // Forces state back to CLOSED and clears counters

Monitoring Circuit Breaker Health

OmniRoute exposes breaker status for observability through the registry:

import { getAllCircuitBreakerStatuses } from '@/shared/utils/circuitBreaker';

console.table(getAllCircuitBreakerStatuses());

This function returns the current state of all registered breakers, enabling real-time monitoring of provider health across the system. The implementation also tracks specialized breakers, such as those defined in open-sse/services/tokenRefresh/circuitBreaker.ts, which follow the identical four-state model for authentication flows.

Summary

• OmniRoute implements four circuit breaker states: CLOSED, DEGRADED, OPEN, and HALF_OPEN to manage provider health
• The DEGRADED state provides early warning at ~60% of the failure threshold before full tripping
• OPEN state rejects requests immediately via CircuitBreakerOpenError to prevent cascade failures
• HALF_OPEN allows configurable probe requests to test recovery before returning to CLOSED
• State machine logic resides in src/shared/utils/circuitBreaker.ts with transitions controlled by failureThreshold, resetTimeout, and halfOpenRequests

Frequently Asked Questions

What triggers the transition from CLOSED to OPEN in OmniRoute's circuit breaker?

The transition occurs when the failure count reaches the configured failureThreshold or when an immediate-open condition is met for critical failure kinds. The system passes through the intermediate DEGRADED state when failures exceed the degradation threshold (approximately 60% of the failure limit) before reaching the full OPEN state.

How does the HALF_OPEN state determine whether to close or reopen the circuit?

While in HALF_OPEN, the breaker allows a limited number of requests defined by halfOpenRequests. If these probe requests succeed, the breaker transitions to CLOSED. If they fail, the breaker returns to OPEN with an escalated back-off timeout to prevent premature retry attempts.

Can I manually override the circuit breaker state in OmniRoute?

Yes. The circuitBreaker.ts implementation provides a reset() method that forces the breaker back to the CLOSED state and clears all internal failure counters. This is useful for administrative recovery actions or maintenance windows.

What is the difference between DEGRADED and OPEN states?

The DEGRADED state acts as a pre-alarm zone where requests still pass through but the system logs warnings when failure counts exceed the degradation threshold (~60% of the failure limit). The OPEN state represents a full short-circuit where new requests are immediately rejected to protect the upstream provider.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}