Added docs for request filtering

docs-v2/_docs/extending-wiremock.md

@@ -384,3 +384,73 @@ new WireMockServer(wireMockConfig()
 If you would like to collect the traffic 
 and for example add it to your acceptance test's output, 
 you can use the ```CollectingNetworkTrafficListener```.
+
+
+## Intercepting and modifying requests
+
+Requests to both stubs and the admin API can be intercepted and either modified or halted with an immediate response.
+This supports a number of use cases including: authentication, URL rewriting and request header injection.
+
+To intercept stub requests, create a class that extends `StubRequestFilter`. For instance, to perform simple authentication:
+
+```java
+public class SimpleAuthRequestFilter extends StubRequestFilter {
+
+    @Override
+    public RequestFilterAction filter(Request request) {
+        if (request.header("Authorization").firstValue().equals("Basic abc123")) {
+            return RequestFilterAction.continueWith(request);
+        }
+
+        return RequestFilterAction.stopWith(ResponseDefinition.notAuthorised());
+    }
+
+    @Override
+    public String getName() {
+        return "simple-auth";
+    }
+}
+```
+
+Then add it as an extension as usual e.g.
+
+```java
+new WireMockRule(wireMockConfig().extensions(new SimpleAuthRequestFilter()));
+```
+
+
+To intercept admin API follow the same process, but extend `AdminRequestFilter`.
+
+### Modifying the request during interception
+
+To modify the HTTP request, the simplest approach is to wrap the original request with a `RequestWrapper` then continue e.g.
+
+```java
+public static class UrlAndHeadersModifyingFilter extends StubRequestFilter {
+
+    @Override
+    public RequestFilterAction filter(Request request) {
+        Request wrappedRequest = RequestWrapper.create()
+                .transformAbsoluteUrl(url -> url + "?extraQueryParam=123")
+                .addHeader("X-Custom-Header", "headerval")
+                .wrap(request);
+
+        return RequestFilterAction.continueWith(wrappedRequest);
+    }
+
+    @Override
+    public String getName() {
+        return "url-and-header-modifier";
+    }
+}
+```
+
+`RequestWrapper` is a builder pattern and allows any number of changes to the request. It supports the following changes:
+
+* Transformation of the URL. `transformAbsoluteUrl` takes a `FieldTransformer` as a parameter (or equivalent lambda) which maps
+from the old to the new URL. Note that the URL passed in is absolute, and the returned URL must also be.
+* Addition, removal and transformation (via `FieldTransformer`) of headers.
+* Addition, removal and transformation of cookies.
+* Changing the HTTP method.
+* Transformation of the request body.
+* Transformation of body parts (if a multipart encoded request).

src/test/java/ignored/Examples.java

@@ -21,8 +21,14 @@
 import com.github.tomakehurst.wiremock.common.Json;
 import com.github.tomakehurst.wiremock.core.WireMockConfiguration;
 import com.github.tomakehurst.wiremock.extension.Parameters;
+import com.github.tomakehurst.wiremock.extension.requestfilter.FieldTransformer;
+import com.github.tomakehurst.wiremock.extension.requestfilter.RequestFilterAction;
+import com.github.tomakehurst.wiremock.extension.requestfilter.RequestWrapper;
+import com.github.tomakehurst.wiremock.extension.requestfilter.StubRequestFilter;
 import com.github.tomakehurst.wiremock.http.Fault;
 import com.github.tomakehurst.wiremock.http.Request;
+import com.github.tomakehurst.wiremock.http.ResponseDefinition;
+import com.github.tomakehurst.wiremock.junit.WireMockRule;
 import com.github.tomakehurst.wiremock.matching.MatchResult;
 import com.github.tomakehurst.wiremock.matching.RequestMatcherExtension;
 import com.github.tomakehurst.wiremock.stubbing.ServeEvent;
@@ -37,6 +43,7 @@
 import java.util.UUID;
 
 import static com.github.tomakehurst.wiremock.client.WireMock.*;
+import static com.github.tomakehurst.wiremock.core.WireMockConfiguration.wireMockConfig;
 import static com.github.tomakehurst.wiremock.stubbing.Scenario.STARTED;
 import static java.util.Collections.singletonList;
 import static org.hamcrest.Matchers.containsString;
@@ -539,4 +546,44 @@ public void customAndStandardMatcherJson() {
                 .willReturn(ok())
                 .build()));
     }
+
+    public static class SimpleAuthRequestFilter extends StubRequestFilter {
+
+        @Override
+        public RequestFilterAction filter(Request request) {
+            if (request.header("Authorization").firstValue().equals("Basic abc123")) {
+                return RequestFilterAction.continueWith(request);
+            }
+
+            return RequestFilterAction.stopWith(ResponseDefinition.notAuthorised());
+        }
+
+        @Override
+        public String getName() {
+            return "simple-auth";
+        }
+    }
+
+    public static class UrlAndHeadersModifyingFilter extends StubRequestFilter {
+
+        @Override
+        public RequestFilterAction filter(Request request) {
+            Request wrappedRequest = RequestWrapper.create()
+                    .transformAbsoluteUrl(new FieldTransformer<String>() {
+                        @Override
+                        public String transform(String url) {
+                            return url + "extraparam=123";
+                        }
+                    })
+                    .addHeader("X-Custom-Header", "headerval")
+                    .wrap(request);
+
+            return RequestFilterAction.continueWith(wrappedRequest);
+        }
+
+        @Override
+        public String getName() {
+            return "url-and-header-modifier";
+        }
+    }
 }