Promise Circuit Breaker

Class: CircuitBreaker

CircuitBreaker

new CircuitBreaker(fn, fnThis, options)

Create a new circuit breaker wrapping function fn. If the function
is a method of an object, pass the object as the fnThis parameter.

You can configure it's behaviour with the options parameter, or through
various setters:

Parameters:
Name Type Argument Description
fn function

The function to be executed
fnThis object <optional>

If provided, call fn with fnThis as this argument
options object <optional>

Options. All times are in milliseconds.

Properties
Name Type Description
Promise function

Promise library (default: require('bluebird') / you can use the navite Promise constructor)
name string

Name for this instance (default: 'CircuitBreaker')
isErrorHandler function

Function to get error from callback
concurrency integer

Set a limit for concurrent calls (default: 0 - unlimited)
timeout integer

Timeout limit for callback to be called (default: 3000)
resetTime integer

When circuit is tripped, time to wait before a test call is allowed (default: 1000)
volumeThreshold integer

Minimum number of calls in health window before circuit is checked
for health. Circuit remains closed until then (default: 10)
intervalSize integer

Frequency with which the 'interval' event is emitted for reporting (default: 1000)
windowSize integer

Time size of each individual rolling window (default: 1000)
windowCount integer

Number of windows in health window (default: 10)
errorThreshold float

Error level between 0 and 1 at which the circuit is tripped (default: 0.05)
errorNamesThresholds object

Custom error levels for particular named errors (default: {})
emitIntervalEvent boolean

Enable/disable emitting the 'interval' event for reporting (default: true)
emitCallbackEvent boolean

Enable/disable emitting the 'callback' event (default: false)
Source:
Fires:
Example
var cb = new CircuitBreaker(fn)
         .setTimeout(1000)
         .setErrorThreshold(0.5);

Members

<static, readonly> STATE :string

State enum

Type:
  • string
Properties:
Name Type Default Description
OPEN string open

No calls are allowed
CLOSED string closed

Calls are allowed
HALF_OPEN string half-open

One call is allowed to test health
Source:

Promise :module

Bluebird Promise module

Type:
  • module
Source:

Methods

exec() → {external:Promise}

Main entry point. Call the protected function and return a promise.

Source:
Returns:
Type
external:Promise

getActiveCount() → {integer}

Get the amount of current active requests. That is,
calls which have started but have not timedout nor called-back.

Source:
Returns:
Type
integer

getCurrentCounts() → {object}

Get the current circuit breaker health rolling counts

Source:
Returns:
Type
object

getCurrentInterval() → {object}

Get the current reporting interval.

Source:
Returns:
Type
object

getCurrentInteval() → {object}

Deprecated:
  • Yes
Source:
Returns:
Type
object

getErrorPercentage() → {float}

Get current error percentage.

Source:
Returns:
Type
float

getName() → {string}

Get this instance's name

Source:
Returns:
Type
string

getQueuedCount() → {integer}

Get the amount of requests in queue when concurrency is enabled.

Source:
Returns:
Type
integer

getState() → {string}

Get current circuit's state.

Source:
Returns:
Type
string

setConcurrency(num) → {CircuitBreaker}

Set the concurrency level. Set to 0 to disable (default behaviour).

Requests will be queded if more than this number are currently active.

Parameters:
Name Type Description
num integer

The maximum number of requests allowed to be active.
Source:
Returns:
Type
CircuitBreaker

setEmitCallbackEvent(bool) → {CircuitBreaker}

Enables/disables emitting the 'callback' event for reporting.

Parameters:
Name Type Description
bool boolean
Source:
Returns:
Type
CircuitBreaker

setEmitIntervalEvent(bool) → {CircuitBreaker}

Enables/disables emitting the 'interval' event for reporting.

Parameters:
Name Type Description
bool boolean
Source:
Returns:
Type
CircuitBreaker

setErrorNameThreshold(name, level)

Set the error threshold for a particular error type.
The error type is obtained from the name property of the error.

Parameters:
Name Type Description
name string

Error name
level float

Float from 0 to 1
Source:

setErrorThreshold(level) → {CircuitBreaker}

Set the error threshold which tirggers circuit.
Set to 0 open circuit on first error.

Parameters:
Name Type Description
level float

Float from 0 to 1
Source:
Returns:
Type
CircuitBreaker

setIntervalSize(ms)

Set the reporting interval size.

Parameters:
Name Type Description
ms integer

The frequency with which the 'interval' event is emitted.
Source:

setIsErrorHandler(cb) → {CircuitBreaker}

Set a custom function to check if the callback was called with an error or not.

Parameters:
Name Type Description
cb function

A function which will be called with the callback arguments.
Source:
Returns:
Type
CircuitBreaker
Example
var cb = new RequestCircuitBreaker();
cb.setIsErrorHandler(function(error, response, body) {
    if (error) return error;
    if (response.statusCode == 503) {
        var unavailableError = new Error();
        unavailableError.name = "ServiceUnavailableError";
        return unavailableError;
    }
    return null;
});

setResetTime(ms) → {CircuitBreaker}

Set the sleep period until a test request is allowed to be made.
The circuit will remain open during this period of time.

Parameters:
Name Type Description
ms integer
Source:
Returns:
Type
CircuitBreaker

setTimeout(ms) → {CircuitBreaker}

Set the timeout in milliseconds. Set to 0 to disable.

Parameters:
Name Type Description
ms integer
Source:
Returns:
Type
CircuitBreaker

setVolumeThreshold(count) → {CircuitBreaker}

Set the minimum amount of calls to start checking for circuit health.
Circuit will always be closed until it reaches this threshold.
Set to 0 to instantly start checking for circuit health.

Parameters:
Name Type Description
count integer

Minimum amount of calls to start checking circuit health.
Source:
Returns:
Type
CircuitBreaker

setWindowCount(count) → {CircuitBreaker}

Set the total amount of windows to keep in the rolling counts.

Parameters:
Name Type Description
count integer
Source:
Returns:
Type
CircuitBreaker

setWindowSize(ms) → {CircuitBreaker}

Set the size in milliseconds of each individual window used in the rolling counts.

Parameters:
Name Type Description
ms integer
Source:
Returns:
Type
CircuitBreaker

startEvents()

Start events. Events starts automatically upon the first request.
This forces start emitting events before any request is made.

Source:

stopEvents()

Stop events. Clears the pending timeouts.

Source:

Events

callback

Callback event. Emitted on calls which do not timeout.

Type:
  • object
Properties:
Name Type Description
args array

Array or arguments in exec() call
start integer

Timestamp of the start of the call
end integer

Timestamp of the end of the call
result array

Array of arguments with which callback was called
Source:

interval

Interval event

Type:
  • object
Properties:
Name Type Description
start integer

Timestamp of start of the interval
end integer

Timestamp of the end of the interval
state string

Circuit's current state
active integer

Calls currently running
queued integer

Calls currently queued
total integer

Total calls
success integer

Total success calls
totalErrors integer

Total failed calls
errors object

Error counts by type

Properties
Name Type Description
TimeoutError integer

Total calls which timedout - if any
OpenCircuitError integer

Total calls which were rejected (short-circuit) - if any
times array

Times of successful calls in milliseconds
Source: