grout host header & dynamic routing doc

README.md

@@ -78,6 +78,8 @@
   - [Grout Authentication](#grout-authentication)
   - [Grout Paths](#grout-paths)
   - [Grout Wildcard Domains](#grout-wildcard-domains)
+  - ["Host" Header Based Wildcard Routing](#grout-wildcard-domain-routing-based-upon-host-header)
+  - ["Dynamic" Routing](#grout-client-plugin)
   - [Grout using Docker](#grout-using-docker)
   - [How Grout works](#how-grout-works)
   - [Self-hosted Grout](#self-hosted-grout)
@@ -1443,6 +1445,55 @@ grout https://localhost:8080 custom.example.com --wildcard
 2024-08-05 18:25:03,159 - setup - Grouting https://*.custom.domain.com
 ```
 
+## Grout Wildcard Domain Routing Based Upon "Host" Header
+
+  > Only available with `--wildcard`
+
+Along with the default route you can also provide additional routes which takes precendence when the host field matches.  Example:
+
+```console
+grout https://localhost:8080 custom.example.com \
+  --wildcard \
+  --tunnel-route-url stream.example.com=http://localhost:7001
+```
+
+You can provide multiple custom routes by repeating this flag.
+
+## Grout Client Plugin
+
+`GroutClientBasePlugin` allows you to dynamically route traffic to different upstreams.  Below is a simple implementation with some description about how to use it.
+
+```python
+class GroutClientPlugin(GroutClientBasePlugin):
+
+    def resolve_route(
+        self,
+        route: str,
+        request: HttpParser,
+        origin: HostPort,
+        server: HostPort,
+    ) -> Tuple[Optional[str], HttpParser]:
+        print(request, origin, server, '->', route)
+        print(request.header(b'host'), request.path)
+        #
+        # Here, we send traffic to localhost:7001 irrespective
+        # of the original "route" value provided to the grout
+        # client OR any custom host:upstream mapping provided
+        # through the --tunnel-route-url flags (when using
+        # --wildcard).
+        #
+        # Optionally, you can also strip path before
+        # sending traffic to upstrem, like:
+        # request.path = b"/"
+        #
+        # To drop the request, simply return None for route
+        # return None, request
+        #
+        return 'http://localhost:7001', request
+```
+
+See [grout_client.py](./proxy/plugin/grout_client.py) for more information.  To try this out, start by passing `--plugin proxy.plugin.grout_client.GroutClientPlugin` when starting the grout client.
+
 ## Grout using Docker
 
 ```console