Add regex rules for proxy and rewrite middleware (#180)

Author: lammel

website/content/middleware/proxy.md

@@ -9,7 +9,7 @@ description = "Reverse proxy middleware for Echo"
 Proxy provides an HTTP/WebSocket reverse proxy middleware. It forwards a request
 to upstream server using a configured load balancing technique.
 
-_Usage_
+### Usage
 
 ```go
 url1, err := url.Parse("http://localhost:8081")
@@ -32,34 +32,70 @@ e.Use(middleware.Proxy(middleware.NewRoundRobinBalancer([]*middleware.ProxyTarge
 
 ## Custom Configuration
 
-_Usage_
+### Usage
 
 ```go
 e := echo.New()
 e.Use(middleware.ProxyWithConfig(middleware.ProxyConfig{}))
 ```
 
-## Configuration
+### Configuration
 
 ```go
 // ProxyConfig defines the config for Proxy middleware.
-ProxyConfig struct {
-  // Skipper defines a function to skip middleware.
-  Skipper Skipper
-
-  // Balancer defines a load balancing technique.
-  // Required.
-  // Possible values:
-  // - RandomBalancer
-  // - RoundRobinBalancer
-  Balancer ProxyBalancer
-}
+  ProxyConfig struct {
+    // Skipper defines a function to skip middleware.
+    Skipper Skipper
+
+    // Balancer defines a load balancing technique.
+    // Required.
+    Balancer ProxyBalancer
+
+    // Rewrite defines URL path rewrite rules. The values captured in asterisk can be
+    // retrieved by index e.g. $1, $2 and so on.
+    Rewrite map[string]string
+
+    // RegexRewrite defines rewrite rules using regexp.Rexexp with captures
+    // Every capture group in the values can be retrieved by index e.g. $1, $2 and so on.
+    RegexRewrite map[*regexp.Regexp]string
+
+    // Context key to store selected ProxyTarget into context.
+    // Optional. Default value "target".
+    ContextKey string
+
+    // To customize the transport to remote.
+    // Examples: If custom TLS certificates are required.
+    Transport http.RoundTripper
+
+    // ModifyResponse defines function to modify response from ProxyTarget.
+    ModifyResponse func(*http.Response) error
 ```
 
-_Default Configuration_
+Default Configuration:
 
-| Name    | Value          |
-| ------- | -------------- |
-| Skipper | DefaultSkipper |
+| Name       | Value          |
+| ---------- | -------------- |
+| Skipper    | DefaultSkipper |
+| ContextKey | `target`       |
+
+### Regex-based Rules
+
+For advanced rewriting of proxy requests rules may also be defined using
+regular expression. Normal capture groups can be defined using `()` and referenced by index (`$1`, `$2`, ...) for the rewritten path.
+
+`RegexRules` and normal `Rules` can be combined.
+
+```go
+  e.Use(ProxyWithConfig(ProxyConfig{
+    Balancer: rrb,
+    Rewrite: map[string]string{
+      "^/v1/*":     "/v2/$1",
+    },
+    RegexRewrite: map[*regexp.Regexp]string{
+      regexp.MustCompile("^/foo/([0-9].*)"):  "/num/$1",
+      regexp.MustCompile("^/bar/(.+?)/(.*)"): "/baz/$2/$1",
+    },
+  }))
+```
 
 ## [Example](/cookbook/reverse-proxy)

website/content/middleware/rewrite.md

@@ -6,9 +6,9 @@ description = "Rewrite middleware for Echo"
   parent = "middleware"
 +++
 
-Rewrite middleware rewrites the URL path based on provided rules. It can be helpful for backward compatibility or just creating cleaner and more descriptive links.
+Rewrite middleware allows to rewrite an URL path based on provided rules. It can be helpful for backward compatibility or just creating cleaner and more descriptive links.
 
-*Usage*
+### Usage
 
 ```go
 e.Pre(middleware.Rewrite(map[string]string{
@@ -20,33 +20,59 @@ e.Pre(middleware.Rewrite(map[string]string{
 ```
 
 The values captured in asterisk can be retrieved by index e.g. $1, $2 and so on.
+Each asterisk will be non-greedy (translated to a capture group `(.*?)`) and if using
+multiple asterisk a trailing `*` will match the "rest" of the path.
+
+> Rewrite middleware should be registered via `Echo#Pre()` to get triggered before the router.
 
 ## Custom Configuration
 
-*Usage*
+### Usage
 
 ```go
 e := echo.New()
 e.Pre(middleware.RewriteWithConfig(middleware.RewriteConfig{}))
 ```
 
-## Configuration
+### Configuration
 
 ```go
 // RewriteConfig defines the config for Rewrite middleware.
-RewriteConfig struct {
-  // Skipper defines a function to skip middleware.
-  Skipper Skipper
+  RewriteConfig struct {
+    // Skipper defines a function to skip middleware.
+    Skipper Skipper
+
+    // Rules defines the URL path rewrite rules. The values captured in asterisk can be
+    // retrieved by index e.g. $1, $2 and so on.
+    Rules map[string]string `yaml:"rules"`
 
-  // Rules defines the URL path rewrite rules.
-  Rules map[string]string `yaml:"rules"`
-}
+    // RegexRules defines the URL path rewrite rules using regexp.Rexexp with captures
+    // Every capture group in the values can be retrieved by index e.g. $1, $2 and so on.
+    RegexRules map[*regexp.Regexp]string
+  }
 ```
 
-*Default Configuration*
+Default Configuration:
 
-Name | Value
----- | -----
-Skipper | DefaultSkipper
+| Name    | Value          |
+| ------- | -------------- |
+| Skipper | DefaultSkipper |
 
-> Rewrite middleware should be registered via `Echo#Pre()` to get triggered before the router.
+### Regex-based Rules
+
+For advanced rewriting of paths rules may also be defined using regular expression.
+Normal capture groups can be defined using `()` and referenced by index (`$1`, `$2`, ...) for the rewritten path.
+
+`RegexRules` and normal `Rules` can be combined.
+
+```go
+  e.Pre(RewriteWithConfig(RewriteConfig{
+    Rewrite: map[string]string{
+      "^/v1/*": "/v2/$1",
+    },
+    RegexRewrite: map[*regexp.Regexp]string{
+      regexp.MustCompile("^/foo/([0-9].*)"):  "/num/$1",
+      regexp.MustCompile("^/bar/(.+?)/(.*)"): "/baz/$2/$1",
+    },
+  }))
+```