Created Proxying (markdown)

Proxying.md

@@ -0,0 +1,39 @@
+# Proxying
+
+WireMock.NET has the ability to selectively proxy requests through to other hosts. This supports a proxy/intercept setup where requests are by default proxied to another (possibly real, live) service, but where specific stubs are configured these are returned in place of the remote service’s response. Responses that the live service can’t be forced to generate on demand can thus be injected for testing.
+
+## Proxy stub mappings
+
+Proxy responses are defined in exactly the same manner as stubs, meaning that the same request matching criteria can be used.
+
+The following code will proxy all GET requests made to http://<host>:<port>/other/service/.* to http://otherservice.com/approot, e.g. when running WireMock.NET locally a request to http://localhost:9000/other/service/doc/123 would be forwarded to http://otherservice.com/approot/other/service/doc/123.
+
+stubFor(get(urlMatching("/other/service/.*"))
+        .willReturn(aResponse().proxiedFrom("http://otherhost.com/approot")));
+
+The JSON equivalent would be:
+
+{
+    "request": {
+        "method": "GET",
+        "urlPattern": "/other/service/.*"
+    },
+    "response": {
+        "proxyBaseUrl" : "http://otherhost.com/approot"
+    }
+}
+
+Proxy/intercept
+
+The proxy/intercept pattern described above is achieved by adding a low priority proxy mapping with a broad URL match and any number of higher priority stub mappings e.g.
+
+// Low priority catch-all proxies to otherhost.com by default
+stubFor(get(urlMatching(".*")).atPriority(10)
+        .willReturn(aResponse().proxiedFrom("http://otherhost.com")));
+
+
+// High priority stub will send a Service Unavailable response
+// if the specified URL is requested
+stubFor(get(urlEqualTo("/api/override/123")).atPriority(1)
+        .willReturn(aResponse().withStatus(503)));            
+