From 072a97a9118677ed4d90fa95a5b908b1095ba72f Mon Sep 17 00:00:00 2001
From: Jonathan Samines <jn.samines@gmail.com>
Date: Mon, 6 Aug 2018 21:03:39 -0600
Subject: [PATCH] [master] Add error code levee circuit open message. Update
 documentation of levee errors and their corresponding codes

---
 README.md       | 23 ++++++++++++-----------
 lib/breaker.js  |  9 ++++++++-
 test/breaker.js |  4 ++++
 3 files changed, 24 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 9dc80ce..3785e4f 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@ Levee
 
 A [circuit breaker](http://doc.akka.io/docs/akka/snapshot/common/circuitbreaker.html) implementation based heavily on
 ryanfitz's [node-circuitbreaker](https://github.com/ryanfitz/node-circuitbreaker). More information about the circuitbreaker
-pattern can be found in the [akka documentation](http://doc.akka.io/docs/akka/snapshot/common/circuitbreaker.html).
+pattern can be found in the [akka documentation](https://doc.akka.io/docs/akka/current/common/circuitbreaker.html).
 
 [![Build Status](https://travis-ci.org/krakenjs/levee.svg)](https://travis-ci.org/krakenjs/levee)
 
@@ -39,26 +39,26 @@ function fallback(url, callback) {
     callback(null, null, new Buffer('The requested website is not available. Please try again later.'));
 }
 
-circuit = Levee.createBreaker(service, options);
-circuit.fallback = Levee.createBreaker(fallback, options);
+breaker = Levee.createBreaker(service, options);
+breaker.fallback = Levee.createBreaker(fallback, options);
 
-circuit.on('timeout', function () {
+breaker.on('timeout', function () {
     console.log('Request timed out.');
 });
 
-circuit.on('failure', function (err) {
+breaker.on('failure', function (err) {
     console.log('Request failed.', err);
 });
 
-circuit.run('http://www.google.com', function (err, req, payload) {
+breaker.run('http://www.google.com', function (err, req, payload) {
     // If the service fails or timeouts occur 5 consecutive times,
     // the breaker opens, fast failing subsequent requests.
     console.log(err || payload);
 });
 
 var stats, fbStats;
-stats = Levee.createStats(circuit);
-fbStats = Levee.createStats(circuit.fallback);
+stats = Levee.createStats(breaker);
+fbStats = Levee.createStats(breaker.fallback);
 
 // Print stats every 5 seconds.
 setInterval(function () {
@@ -94,7 +94,7 @@ An alternative method for creating Breaker instances with the following argument
 ```javascript
 var Levee = require('levee');
 
-function doStuff(context, callback) {
+function fn(context, callback) {
     callback(null, 'ok');
 }
 
@@ -128,10 +128,10 @@ var breaker = Levee.createStats(breaker);
 
 #### Options
 ##### `timeout`
-the amount of time to allow an operation to run before terminating with an error.
+the amount of time to allow an operation to run before terminating with an error. In case the command execution exceeds the configured timeout, the run callback will be provided with an error with the `ETIMEDOUT` code.
 
 ##### `maxFailures`
-the number of failures allowed before the Breaker enters the `open` state.
+the number of failures allowed before the Breaker enters the `open` state. Once the breaker enters this state, the run callback will be provided with an error with the `EUNAVAILABLE` code.
 
 ##### `resetTimeout`
 the amount of time to wait before switch the Breaker from the `open` to `half_open` state to attempt recovery.
@@ -155,6 +155,7 @@ Executes the wrapped functionality within the circuit breaker functionality with
 
 - `context` - any context to be provided to the implementation.
 - `callback` - the callback to be fired upon completion with the signature `function (err, [param1, param2, ...])`
+  - `err` - any error ocurred during the command execution or a levee error caused either by timeout or an open circuit
 
 
 ## Stats
diff --git a/lib/breaker.js b/lib/breaker.js
index e2ec4f6..dbee6fc 100644
--- a/lib/breaker.js
+++ b/lib/breaker.js
@@ -71,7 +71,13 @@ Breaker.prototype._run = function _run(/*args...n, callback*/) {
 
     if (this.isOpen() || this._pendingClose) {
         this.emit('reject');
-        callback(new Error(this.settings.openErrMsg || 'Command not available.'));
+
+        var error = new Error(this.settings.openErrMsg || 'Command not available.');
+        error.name = 'commandUnavailable';
+        error.code = 'EUNAVAILABLE';
+
+        callback(error);
+
         return;
     }
 
@@ -92,6 +98,7 @@ Breaker.prototype._run = function _run(/*args...n, callback*/) {
         var error = new Error(self.settings.timeoutErrMsg || 'Command timeout.');
         error.name = 'commandTimeout';
         error.code = 'ETIMEDOUT';
+
         timer = undefined;
         self._pendingClose = false;
         self.emit('timeout');
diff --git a/test/breaker.js b/test/breaker.js
index 7a8c87d..48e2f91 100644
--- a/test/breaker.js
+++ b/test/breaker.js
@@ -120,6 +120,8 @@ test('failure', function (t) {
         breaker.run('not ok', function (err, data) {
             t.ok(err);
             t.equal(err.message, 'Command not available.');
+            t.equal(err.name, 'commandUnavailable');
+            t.equal(err.code, 'EUNAVAILABLE');
             t.notOk(data);
             t.ok(breaker.isOpen());
             t.end();
@@ -190,6 +192,8 @@ test('timeout', function (t) {
     breaker.run('ok', function (err, data) {
         t.ok(err);
         t.equal(err.message, 'Command timeout.');
+        t.equal(err.name, 'commandTimeout');
+        t.equal(err.code, 'ETIMEDOUT');
         t.notOk(data);
         t.ok(breaker.isOpen());
         t.end();