Feature/re route specific handlers (#269)

* #264 added handlers to config

* #264 added global handlers object and defaut param for method, not sure this is correct api for users yet

* #264 Can now add all sorts of delegating handlers in all sorts of ways

* +semver: breaking #264

docs/features/delegatinghandlers.rst

@@ -1,26 +1,16 @@
 Delegating Handers
 ==================
 
-Ocelot allows the user to add delegating handlers to the HttpClient transport. This feature was requested `GitHub #208 <https://github.com/TomPallister/Ocelot/issues/208>`_ and I decided that it was going to be useful in various ways.
+Ocelot allows the user to add delegating handlers to the HttpClient transport. This feature was requested `GitHub #208 <https://github.com/TomPallister/Ocelot/issues/208>`_ 
+and I decided that it was going to be useful in various ways. Since then we extended it in `GitHub #208 <https://github.com/TomPallister/Ocelot/issues/264>`_.
 
 Usage
 ^^^^^
 
-In order to add delegating handlers to the HttpClient transport you need to do the following.
+In order to add delegating handlers to the HttpClient transport you need to do two main things.
 
-This will register the Handlers as singletons. Because Ocelot caches the HttpClient for the downstream services to avoid
-socket exhaustion (well known http client issue) you can only register singleton handlers.
-
-.. code-block:: csharp
-
-    services.AddOcelot()
-            .AddDelegatingHandler<FakeHandler>()
-            .AddDelegatingHandler<FakeHandlerTwo>()
-
-You can have as many DelegatingHandlers as you want and they are run in a first in first out order. If you are using Ocelot's QoS functionality then that will always be run after your last delegating handler. If you are also registering handlers in DI these will be
-run first.
-
-In order to create a class that can be used a delegating handler it must look as follows
+First in order to create a class that can be used a delegating handler it must look as follows. We are going to register these handlers in the 
+asp.net core container so you can inject any other services you have registered into the constructor of your handler.
 
 .. code-block:: csharp
 
@@ -33,4 +23,57 @@ In order to create a class that can be used a delegating handler it must look as
         }
     }
 
-Hopefully other people will find this feature useful!
+Next you must add the handlers to Ocelot's container either as singleton like follows..
+
+.. code-block:: csharp
+
+    services.AddOcelot()
+            .AddSingletonDelegatingHandler<FakeHandler>()
+            .AddSingletonDelegatingHandler<FakeHandlerTwo>()
+
+Or transient as below...
+
+.. code-block:: csharp
+
+    services.AddOcelot()
+            .AddTransientDelegatingHandler<FakeHandler>()
+            .AddTransientDelegatingHandler<FakeHandlerTwo>()
+
+Both of these Add methods have a default parameter called global which is set to false. If it is false then the intent of 
+the DelegatingHandler is to be applied to specific ReRoutes via configuration.json (more on that later). If it is set to true
+then it becomes a global handler and will be applied to all ReRoutes.
+
+e.g.
+
+.. code-block:: csharp
+
+    services.AddOcelot()
+            .AddSingletonDelegatingHandler<FakeHandler>(true)
+
+Or transient as below...
+
+.. code-block:: csharp
+
+    services.AddOcelot()
+            .AddTransientDelegatingHandler<FakeHandler>(true)
+
+Finally if you want ReRoute specific DelegatingHandlers or to order your specific and / or global (more on this later) DelegatingHandlers
+then you must add the following json to the specific ReRoute in configuration.json. The names in the array must match the class names of your
+DelegatingHandlers for Ocelot to match them together.
+
+.. code-block:: json
+
+    "DelegatingHandlers": [
+        "FakeHandlerTwo",
+        "FakeHandler"
+    ]
+
+You can have as many DelegatingHandlers as you want and they are run in the following order:
+
+1. Any globals that are left in the order they were added to services and are not in the DelegatingHandlers array from configuration.json.
+2. Any non global DelegatingHandlers plus any globals that were in the DelegatingHandlers array from configuration.json ordered as they are in the DelegatingHandlers array.
+3. Tracing DelegatingHandler if enabled (see tracing docs).
+4. QoS DelegatingHandler if enabled (see QoS docs).
+5. The HttpClient sends the HttpRequestMessage.
+
+Hopefully other people will find this feature useful!