Ensure callback called for late errors

Add a flag when the execution loop is stopped.
Force a callback on error if the flag is set.
Update documentation to clarify behaviour of retry plugin.
Fixes #456

Author: ricellis

CHANGES.md

@@ -1,4 +1,6 @@
 # UNRELEASED
+- [FIXED] Hang caused by plugins (i.e. retry plugin) preventing callback execution
+  by attempting to retry on errors received after starting to return the response body.
 - [DEPRECATED] This library is now deprecated and will be EOL on Dec 31 2021.
 
 # 4.4.0 (2021-06-18)

README.md

@@ -511,7 +511,10 @@ var cloudant = Cloudant({ url: myurl, maxAttempt: 5, plugins: [ { iamauth: { iam
     - `retryErrors`
 
       Automatically retry a request on error (e.g. connection reset errors)
-      _(default: true)_.
+      _(default: true)_. Note that this will only retry errors encountered
+      _before_ the library starts to read response body data. After that point
+      any errors (e.g. socket timeout reading from the server) will be returned
+      to the caller (via callback or emitted `error` depending on the usage). 
 
     - `retryInitialDelayMsecs`
 

lib/clientutils.js

@@ -120,6 +120,7 @@ var processState = function(r, callback) {
   }
 
   // [5] => Return response to awaiting client.
+  r.state.final = true; // flags that we are terminating the loop
   setImmediate(callback, new Error('No retry requested')); // no retry
 };
 
@@ -157,7 +158,7 @@ var wrapCallback = function(r, done) {
       if (error) {
         runHooks('onError', r, error, function() {
           processState(r, function(stop) {
-            if (stop && !stop.skipClientCallback) {
+            if ((stop && !stop.skipClientCallback) || r.state.final) {
               r.clientCallback(error, response, body);
             }
             done(stop);