Feature: add support for a read hook

README.md

@@ -191,7 +191,7 @@ Service-Client plugins provide the ability to hook into different spots of a req
 Plugins are registered with `ServiceClient.mergeConfig({plugins: []})` or `ServiceClient.use([])` and affect all Service-Client instances created thereafter.
 
 ### Overview
-A plugin exports a function which, when executed, returns an object containing a set of hook functions to be ran during a request's lifecycle. See all available hooks [below](#available-plugins).
+A plugin exports a function which, when executed, returns an object containing a set of hook functions to be run during a request's lifecycle. See all available hooks [below](#available-plugins).
 
 Example:
 ```js
@@ -322,7 +322,7 @@ async function plugin({client, context, plugins}) {
          * This hook is special. The only value that should be returned here is
          * a response object. This is helpful for authentication plugins that
          * want to retry a request if an invalid response was received. A request
-         * made within this hook could return it's response object here.
+         * made within this hook could return its response object here.
          *
          * There's a catch however. Since response objects from multiple hooks
          * cannot be merged, only the first response object will be taken. All
@@ -335,6 +335,24 @@ async function plugin({client, context, plugins}) {
 
         },
 
+        /**
+         * This hook is special. This hook behaves just like response but can be used to 
+         * validate data after being read. The only value that should be returned here is
+         * a response object. This is helpful for authentication plugins that
+         * want to retry a request if an invalid response was received. A request
+         * made within this hook could return its response object here.
+         *
+         * There's a catch however. Since response objects from multiple hooks
+         * cannot be merged, only the first response object will be taken. All
+         * other returned responses are discarded.
+         *
+         * @param {object} data - data provided to the hook on every request
+         * @param {object} data.response - the response received from Wreck after being read
+         */
+        async onPostRead(data) {
+
+        },
+
         /**
          * @param {object} data - data provided to the hook on every request
          * @param {Error} data.error - the error object resulting from timeouts, read errors, etc

lib/client.js

@@ -163,6 +163,11 @@ class ServiceClient {
         await hooks.error({ context, clientId, requestId, ts, servicename, operation, error })
       }
     }
+    if (hooks.onPostRead) {
+      reqHooks.onPostRead = async (id, response, ts = Date.now()) => {
+        return hooks.onPostRead({ context, clientId, requestId, ts, servicename, operation, response })
+      }
+    }
 
     const doRequest = async function () {
       if (self._circuitState.open) {

lib/hooks.js

@@ -124,6 +124,14 @@ async function init (options) {
 
         return response
       }
+
+      if (hookName === 'onPostRead') {
+        const response = results.find((result) => result)
+
+        debug('%s(): first result: %j', hookName, response)
+
+        return response
+      }
     }
   })
 

lib/http/request.js

@@ -135,6 +135,18 @@ const makeRequest = async function (method, path, options, hooks) {
 
     response.payload = await Read(response, options.readOptions)
 
+    if (hooks.onPostRead) {
+      response = await hooks.onPostRead(options.id, response) || response
+    }
+    // because of the retry, the code is not going to hit the read step
+    // which means that the payload will not be initialized. instead of
+    // hacking inside hooks to read there, keep the code together and do it
+    // here
+    // eslint-disable-next-line no-prototype-builtins
+    if (!response.hasOwnProperty('payload')) {
+      response.payload = await Read(response, options.readOptions)
+    }
+
     debug('makeRequest(): payload read')
     oncomplete()
     return response

test/unit/hooks/standalone.test.js

@@ -43,7 +43,8 @@ describe('Using ServiceClient in a standalone context', () => {
       response: suite.sandbox.spy(),
       error: suite.sandbox.spy(),
       stats: suite.sandbox.spy(),
-      end: suite.sandbox.spy()
+      end: suite.sandbox.spy(),
+      onPostRead: suite.sandbox.spy()
     }
     ServiceClient.use(() => {
       return spies
@@ -65,8 +66,9 @@ describe('Using ServiceClient in a standalone context', () => {
     Sinon.assert.notCalled(spies.error) // no error for this test
     Sinon.assert.calledOnce(spies.stats)
     Sinon.assert.calledOnce(spies.end)
+    Sinon.assert.calledOnce(spies.onPostRead)
 
-    Sinon.assert.callOrder(spies.request, spies.init, spies.socket, spies.response, spies.stats, spies.end)
+    Sinon.assert.callOrder(spies.request, spies.init, spies.socket, spies.response, spies.onPostRead, spies.stats, spies.end)
   })
 
   it('should call hooks (error thrown in plugin initialization)', async function () {

test/unit/http/request.test.js

@@ -213,6 +213,34 @@ describe('request', () => {
     assert.ok(response.payload, 'is body')
   })
 
+  it('should make a successful request with `read: true` - onPostRead', async function () {
+    const readStub = suite.sandbox.stub(Wreck, 'read')
+    readStub.onCall(0).returns(null)
+    readStub.onCall(1).returns({ message: 'success' })
+    const hooks = {
+      onPostRead: () => {
+        return { statusCode: 200 }
+      }
+    }
+    Nock('http://service.local:80')
+      .get('/graphql')
+      .reply(200, {
+        errors: [{
+          message:
+                  'Missing or invalid Bearer token in the Authorization header.',
+          extensions: {
+            code: 'FORBIDDEN'
+          }
+        }
+        ]
+      }
+      )
+
+    const response = await Request('GET', '/graphql', { baseUrl: 'http://service.local:80', read: true }, hooks)
+    assert.equal(response.statusCode, 200, 'is ok')
+    assert.ok(response.payload, 'is body')
+  })
+
   it('should make a successful request without `connectTimeout`', async function () {
     const response = await makeRequest({
       getDeferred: () => Request('GET', '/v1/test/stuff', { baseUrl: 'https://service.local:80', connectTimeout: 0 })