new: add inflightRequests() API (#181)

README.md

@@ -218,6 +218,7 @@ client.del('/foo/bar', function(err, req, res) {
 });
 ```
 
+
 ### StringClient
 
 `StringClient` is what `JsonClient` is built on, and provides a base
@@ -470,6 +471,26 @@ client.get(options, function(err, res, socket, head) {
 });
 ```
 
+### Common APIs
+
+The following methods are shared by all versions of the client:
+
+#### inflightRequests()
+
+Returns the number of inflight requests the client is currently handling. The
+request count is incremented as soon as a verb method is called, which means
+that an inflight request is defined as a request that is in any of the
+following states:
+
+* after the verb function is called but before any I/O
+* waiting on I/O (dns resolution, socket connection, server response, etc.)
+* request serialization (uploading of req bodies, etc.)
+* response marshalling/consumption
+
+The counter is decremented when the response's `end` event is emitted, or when
+the request's `error` event is emitted.
+
+
 ### Events
 
 The client emits the following events:

lib/HttpClient.js

@@ -119,6 +119,9 @@ function rawRequest(opts, cb) {
     // explicit.
     var cbCalled = false;
 
+    // increment the number of currently inflight requests
+    opts.client._incrementInflightRequests();
+
     /**
      * this function is called after the request lifecycle has been "completed"
      * and the after event is ready to be fired. this requires the consumer to
@@ -268,8 +271,8 @@ function rawRequest(opts, cb) {
             req.getMetrics = function getMetrics() {
                 return metrics;
             };
+            opts.client._decrementInflightRequests();
             opts.client.emit('metrics', metrics);
-
             emitAfter(req, res, err);
         });
 
@@ -310,6 +313,7 @@ function rawRequest(opts, cb) {
         log.trace({ err: realErr }, 'Request failed');
         clearTimeout(connectionTimer);
         clearTimeout(requestTimer);
+        opts.client._decrementInflightRequests();
 
         // the user provided callback is invoked as soon as a connection is
         // established. however, the request can be aborted or can fail after
@@ -512,6 +516,10 @@ function HttpClient(options) {
 
     var self = this;
 
+    // internal only properties
+    this._inflightRequests = 0;
+
+    // options properties
     this.agent = options.agent;
     this.appendPath = options.appendPath || false;
     this.ca = options.ca;
@@ -947,3 +955,44 @@ HttpClient.prototype._options = function (method, options) {
 
     return (opts);
 };
+
+
+/**
+ * return number of currently inflight requests
+ * @public
+ * @method inflightRequests
+ * @returns {Number}
+*/
+HttpClient.prototype.inflightRequests = function inflightRequests() {
+    var self = this;
+    return self._inflightRequests;
+};
+
+
+/**
+ * increment the number of currently inflight requests
+ * @private
+ * @method inflightRequests
+ * @returns {Number}
+*/
+HttpClient.prototype._incrementInflightRequests =
+function _incrementInflightRequests() {
+    var self = this;
+    self._inflightRequests++;
+};
+
+
+/**
+ * decrement the number of currently inflight requests. also make sure we never
+ * drop below 0, which would mean there's a bug in the way we're counting.
+ * @public
+ * @method inflightRequests
+ * @returns {Number}
+*/
+HttpClient.prototype._decrementInflightRequests =
+function _decrementInflightRequests() {
+    var self = this;
+    self._inflightRequests--;
+    assert.ok(self._inflightRequests >= 0,
+        'number of inflight requests cannot be < 0');
+};