From 0426ab7d0cf959fd3ee4de4f808ffd55f3bf63ee Mon Sep 17 00:00:00 2001
From: Abhinav Singh <mailsforabhinav@gmail.com>
Date: Sun, 13 Oct 2024 20:45:56 +0530
Subject: [PATCH 1/3] `grout` host header & dynamic routing doc

---
 README.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/README.md b/README.md
index fe7b45c8be..9072fb3186 100644
--- a/README.md
+++ b/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

From a185d8fca39b49d02e7b0007b09a4adfc76574c4 Mon Sep 17 00:00:00 2001
From: Abhinav Singh <mailsforabhinav@gmail.com>
Date: Sun, 13 Oct 2024 20:47:42 +0530
Subject: [PATCH 2/3] spell fix

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 9072fb3186..082f41fe2a 100644
--- a/README.md
+++ b/README.md
@@ -1449,7 +1449,7 @@ grout https://localhost:8080 custom.example.com --wildcard
 
   > Only available with `--wildcard`
 
-Along with the default route you can also provide additional routes which takes precendence when the host field matches.  Example:
+Along with the default route you can also provide additional routes which takes precedence when the host field matches.  Example:
 
 ```console
 grout https://localhost:8080 custom.example.com \

From 407d113321bf97940b8f8ecaedce65e2ee3d6c02 Mon Sep 17 00:00:00 2001
From: Abhinav Singh <mailsforabhinav@gmail.com>
Date: Sun, 13 Oct 2024 20:57:54 +0530
Subject: [PATCH 3/3] Link to repo

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 082f41fe2a..c8897bd9d6 100644
--- a/README.md
+++ b/README.md
@@ -1492,7 +1492,7 @@ class GroutClientPlugin(GroutClientBasePlugin):
         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.
+See [grout_client.py](https://github.com/abhinavsingh/proxy.py/blob/develop/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