Future proof interceptor argument signatures

The third argument to the request/response callbacks for an interceptor
was previously a reference to the current client. Now it's a hash, which
in turn contains the client. The raw client arguments are also available
on that hash.

As other properties are injected into the interceptor callbacks, they will
be added to this hash instead rather than using positional arguments.

README.md

@@ -231,6 +231,7 @@ Change Log
 .next
 - JSON HAL mime serializer for application/hal+json
 - CSRF protection interceptor
+- the third argument to the interceptor request/response callbacks is not an object instead of the client, the client is a property on that object
 - HATEOAS interceptor defaults to indexing relationships directly on the host entity instead of the '_links' child object.  A child object may still be configured.
 - HATEOAS interceptor returns same promise on multiple relationship property accesses
 - support bower 0.10+, older versions of bower will no longer work

docs/interceptors.md

@@ -942,19 +942,19 @@ noopInterceptor = interceptor({
         // do studd with the config
         return config;
     },
-    request: function (request, config) {
+    request: function (request, config, meta) {
         // do stuff with the request
         return request;
     },
-    response: function (response, config, client) {
+    response: function (response, config, meta) {
         // do stuff with the response
         return response;
     },
-    success: function (response, config, client) {
+    success: function (response, config, meta) {
         // do stuff with the response
         return response;
     },
-    error: function (response, config, client) {
+    error: function (response, config, meta) {
         // do stuff with the response
         return response;
     }
@@ -973,17 +973,19 @@ delayRequestInterceptor = interceptor({
 });
 ```
 
+The `meta` argument contains additional information about the context of the request. It contains the `client`, which can be used to make subsequent requests, and the raw `arguments` provided to the client.
+
 For interceptors that need to track state between request and response handlers, the context of each handler is shared and unique to each invocation.
 
 ```javascript
 interceptor = require('rest/interceptor');
 counter = 0;
 countLoggingInterceptor = interceptor({
-    request: function (request, config) {
+    request: function (request) {
         this.count = counter++;
         return request;
     },
-    response: function (response, config, client) {
+    response: function (response) {
         console.log('invocation count: ', this.count);
         return response;
     }

interceptor.js

@@ -40,11 +40,11 @@
 			return config;
 		}
 
-		function defaultRequestHandler(request /*, config */) {
+		function defaultRequestHandler(request /*, config, meta */) {
 			return request;
 		}
 
-		function defaultResponseHandler(response /*, config, client */) {
+		function defaultResponseHandler(response /*, config, meta */) {
 			return response;
 		}
 
@@ -111,11 +111,13 @@
 				config = initHandler(beget(config));
 
 				client = function (request) {
-					var context = {};
+					var context, meta;
+					context = {};
+					meta = { 'arguments': Array.prototype.slice.call(arguments), client: client };
 					request = typeof request === 'string' ? { path: request } : request || {};
 					request.originator = request.originator || client;
 					return when(
-						requestHandler.call(context, request, config),
+						requestHandler.call(context, request, config, meta),
 						function (request) {
 							var response, abort, next;
 							next = target;
@@ -131,10 +133,10 @@
 								return when(
 									next(request),
 									function (response) {
-										return successResponseHandler.call(context, response, config, client);
+										return successResponseHandler.call(context, response, config, meta);
 									},
 									function (response) {
-										return errorResponseHandler.call(context, response, config, client);
+										return errorResponseHandler.call(context, response, config, meta);
 									}
 								);
 							});

interceptor/hateoas.js

@@ -59,10 +59,10 @@
 				config.target = config.target || '';
 				return config;
 			},
-			response: function (response, config, hateoas) {
+			response: function (response, config, meta) {
 				var client;
 
-				client = config.client || (response.request && response.request.originator) || hateoas;
+				client = config.client || (response.request && response.request.originator) || meta.client;
 
 				function apply(target, links) {
 					links.forEach(function (link) {

interceptor/retry.js

@@ -36,7 +36,7 @@
 				config.max = config.max || Infinity;
 				return config;
 			},
-			error: function (response, config, client) {
+			error: function (response, config, meta) {
 				var request;
 
 				request = response.request;
@@ -48,7 +48,7 @@
 						return when.reject({ request: request, error: 'precanceled' });
 					}
 					request.retry = Math.min(request.retry * config.multiplier, config.max);
-					return client(request);
+					return meta.client(request);
 				});
 			}
 		});

test/interceptor-test.js

@@ -406,17 +406,42 @@
 					})
 				);
 			},
-			'should have access to the client in the response handlers for subsequent requests': function () {
+			'should have access to the client for subsequent requests': function () {
 				var theInterceptor, client;
 				theInterceptor = interceptor({
-					response: function (response, config, client) {
-						response.client = client;
+					request: function (request, config, meta) {
+						request.client = meta.client;
+						return request;
+					},
+					response: function (response, config, meta) {
+						response.client = meta.client;
 						return response;
 					}
 				});
 				client = theInterceptor(defaultClient);
 				return client().then(function (response) {
 					assert.same(client, response.client);
+					assert.same(client, response.request.client);
+					assert.same('default', response.id);
+				}).otherwise(fail);
+			},
+			'should have access to the invocation args': function () {
+				var theInterceptor, client;
+				theInterceptor = interceptor({
+					request: function (request, config, meta) {
+						request['arguments'] = meta['arguments'];
+						return request;
+					},
+					response: function (response, config, meta) {
+						response['arguments'] = meta['arguments'];
+						return response;
+					}
+				});
+				client = theInterceptor(defaultClient);
+				return client('foo', 'bar').then(function (response) {
+					assert.same('foo', response['arguments'][0]);
+					assert.same('bar', response['arguments'][1]);
+					assert.same(response['arguments'], response.request['arguments']);
 					assert.same('default', response.id);
 				}).otherwise(fail);
 			},