Merge pull request #273 from matrix-org/paul/wrap-request

Make it easier for SDK users to wrap prevailing the 'request' function

lib/matrix.js

@@ -82,6 +82,27 @@ module.exports.request = function(r) {
     request = r;
 };
 
+/**
+ * Return the currently-set request function.
+ * @return {requestFunction} The current request function.
+ */
+module.exports.getRequest = function() {
+    return request;
+};
+
+/**
+ * Apply wrapping code around the request function. The wrapper function is
+ * installed as the new request handler, and when invoked it is passed the
+ * previous value, along with the options and callback arguments.
+ * @param {requestWrapperFunction} wrapper The wrapping function.
+ */
+module.exports.wrapRequest = function(wrapper) {
+    var origRequest = request;
+    request = function(options, callback) {
+        return wrapper(origRequest, options, callback);
+    };
+};
+
 /**
  * Construct a Matrix Client. Similar to {@link module:client~MatrixClient}
  * except that the 'request', 'store' and 'scheduler' dependencies are satisfied.
@@ -129,6 +150,16 @@ module.exports.createClient = function(opts) {
  * @param {requestCallback} callback The request callback.
  */
 
+/**
+ * A wrapper for the request function interface.
+ * @callback requestWrapperFunction
+ * @param {requestFunction} origRequest The underlying request function being
+ * wrapped
+ * @param {Object} opts The options for this HTTP request, given in the same
+ * form as {@link requestFunction}.
+ * @param {requestCallback} callback The request callback.
+ */
+
  /**
   * The request callback interface for performing HTTP requests. This matches the
   * API for the {@link https://github.com/request/request#requestoptions-callback|