feat: add errorFilter option to bypass incrementing failure stats

Refs: #262

index.js

@@ -51,6 +51,12 @@ const defaults = {
  * can open. This is similar to `options.allowWarmUp` in that no matter how many
  * failures there are, if the number of requests within the statistical window
  * does not exceed this threshold, the circuit will remain closed. Default: 0
+ * @param options.errorFilter {Function} an optional function that will be
+ * called when the circuit's function fails (returns a rejected Promise). If
+ * this function returns truthy, the circuit's failure statistics will not be
+ * incremented. This is useful, for example, when you don't want HTTP 404 to
+ * trip the circuit, but still want to handle it as a failure case.
+
  * @return a {@link CircuitBreaker} instance
  */
 function circuitBreaker (action, options) {

lib/circuit.js

@@ -72,6 +72,11 @@ Please use options.errorThresholdPercentage`;
  * can open. This is similar to `options.allowWarmUp` in that no matter how many
  * failures there are, if the number of requests within the statistical window
  * does not exceed this threshold, the circuit will remain closed. Default: 0
+ * @param options.errorFilter {Function} an optional function that will be
+ * called when the circuit's function fails (returns a rejected Promise). If
+ * this function returns truthy, the circuit's failure statistics will not be
+ * incremented. This is useful, for example, when you don't want HTTP 404 to
+ * trip the circuit, but still want to handle it as a failure case.
  */
 class CircuitBreaker extends EventEmitter {
   constructor (action, options) {
@@ -82,6 +87,7 @@ class CircuitBreaker extends EventEmitter {
     this.options.rollingPercentilesEnabled =
       options.rollingPercentilesEnabled !== false;
     this.options.capacity = Number.isInteger(options.capacity) ? options.capacity : Number.MAX_SAFE_INTEGER;
+    this.options.errorFilter = options.errorFilter || (_ => false);
 
     this.semaphore = new Semaphore(this.options.capacity);
 
@@ -541,6 +547,8 @@ function fallback (circuit, err, args) {
 }
 
 function fail (circuit, err, args, latency) {
+  if (circuit.options.errorFilter(err)) return;
+
   /**
    * Emitted when the circuit breaker action fails
    * @event CircuitBreaker#failure

test/error-filter-test.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const test = require('tape');
+const opossum = require('../');
+
+function mightFail (errorCode) {
+  const err = new Error('Something went wrong');
+  err.statusCode = errorCode;
+  return Promise.reject(err);
+}
+
+const options = {
+  errorThresholdPercentage: 1,
+  resetTimeout: 10000,
+  // if this function returns true, the error statistics
+  // should not be incremented
+  errorFilter: err => err.statusCode < 500
+};
+
+test('Bypasses failure stats if errorFilter returns true', t => {
+  t.plan(3);
+
+  const breaker = opossum(mightFail, options);
+  breaker.fire(400)
+    .then(t.fail)
+    .catch(err => {
+      t.equal(err.statusCode, 400);
+      t.equal(breaker.stats.failures, 0);
+      t.ok(breaker.closed);
+      t.end();
+    });
+});
+
+test('Increments failure stats if errorFilter returns false', t => {
+  t.plan(3);
+
+  const breaker = opossum(mightFail, options);
+  breaker.fire(500)
+    .then(t.fail)
+    .catch(err => {
+      t.equal(err.statusCode, 500);
+      t.equal(breaker.stats.failures, 1);
+      t.ok(breaker.open);
+      t.end();
+    });
+});
+
+test('Increments failure stats if no filter is provided', t => {
+  t.plan(3);
+  const breaker = opossum(mightFail, { errorThresholdPercentage: 1 });
+  breaker.fire(500)
+    .then(t.fail)
+    .catch(err => {
+      t.equal(err.statusCode, 500);
+      console.log(breaker.stats);
+      t.equal(breaker.stats.failures, 1);
+      t.ok(breaker.open);
+      t.end();
+    });
+});