fix(proxy) describe actual router rule order (#1473)

Fix proxy router rule evaluation order documentation for newer versions. The router has evaluated regex path rules before prefix path rules for some time, and documentation has always stated the reverse. This applies to older versions also, but has not been updated there for the sake of time. Add some additional example information for route shadowing. Correct broken anchor link. Made some minor phrasing changes.
Kong · Aug 29, 2019 · 9a54147 · 9a54147
1 parent 6057569
commit 9a54147
Show file tree

Hide file tree

Showing 4 changed files with 64 additions and 36 deletions.
diff --git a/app/1.2.x/proxy.md b/app/1.2.x/proxy.md
@@ -447,40 +447,47 @@ in the path (the root `/` character).
 As previously mentioned, Kong evaluates prefix paths by length: the longest
 prefix paths are evaluated first. However, Kong will evaluate regex paths based
 on the `regex_priority` attribute of Routes from highest priority to lowest.
-This means that considering the following Routes:
+Regex paths are furthermore evaluated before prefix paths.
+
+Consider the following Routes:
 
 ```json
 [
   {
-    "paths": ["/status/d+"],
+    "paths": ["/status/\d+"],
     "regex_priority": 0
   },
   {
-    "paths": ["/version/d+/status/d+"],
+    "paths": ["/version/\d+/status/\d+"],
     "regex_priority": 6
   },
   {
-    "paths": ["/version"]
+    "paths": ["/version"],
   },
   {
-    "paths": ["/version/any/"]
+    "paths": ["/version/any/"],
   }
 ]
 ```
 
 In this scenario, Kong will evaluate incoming requests against the following
 defined URIs, in this order:
 
-1. `/version/any/`
-2. `/version`
-3. `/version/\d+/status/\d+`
-4. `/status/\d+`
+1. `/version/\d+/status/\d+`
+2. `/status/\d+`
+3. `/version/any/`
+4. `/version`
 
-Prefix paths are always evaluated before regex paths.
+Take care to avoid writing regex rules that are overly broad and may consume
+traffic intended for a prefix rule. Adding a rule with the path `/version/.*` to
+the ruleset above would likely consume some traffic intended for the `/version`
+prefix path. If you see unexpected behavior, sending `X-Kong-Debug: 1` in your
+request headers will indicate the matched Route ID in the response headers for
+troubleshooting purposes.
 
 As usual, a request must still match a Route's `hosts` and `methods` properties
-as well, and Kong will traverse your Routes until it finds one that matches
-the most rules (see [Routing priorities][proxy-routing-priorities]).
+as well, and Kong will traverse your Routes until it finds one that [matches
+the most rules](#matching-priorities).
 
 [Back to TOC](#table-of-contents)
 

diff --git a/app/1.3.x/proxy.md b/app/1.3.x/proxy.md
@@ -532,7 +532,9 @@ in the path (the root `/` character).
 As previously mentioned, Kong evaluates prefix paths by length: the longest
 prefix paths are evaluated first. However, Kong will evaluate regex paths based
 on the `regex_priority` attribute of Routes from highest priority to lowest.
-This means that considering the following Routes:
+Regex paths are furthermore evaluated before prefix paths.
+
+Consider the following Routes:
 
 ```json
 [
@@ -556,16 +558,21 @@ This means that considering the following Routes:
 In this scenario, Kong will evaluate incoming requests against the following
 defined URIs, in this order:
 
-1. `/version/any/`
-2. `/version`
-3. `/version/\d+/status/\d+`
-4. `/status/\d+`
+1. `/version/\d+/status/\d+`
+2. `/status/\d+`
+3. `/version/any/`
+4. `/version`
 
-Prefix paths are always evaluated before regex paths.
+Take care to avoid writing regex rules that are overly broad and may consume
+traffic intended for a prefix rule. Adding a rule with the path `/version/.*` to
+the ruleset above would likely consume some traffic intended for the `/version`
+prefix path. If you see unexpected behavior, sending `X-Kong-Debug: 1` in your
+request headers will indicate the matched Route ID in the response headers for
+troubleshooting purposes.
 
 As usual, a request must still match a Route's `hosts` and `methods` properties
-as well, and Kong will traverse your Routes until it finds one that matches
-the most rules (see [Matching priorities][matching-priorities]).
+as well, and Kong will traverse your Routes until it finds one that [matches
+the most rules](#matching-priorities).
 
 [Back to TOC](#table-of-contents)
 

diff --git a/app/enterprise/0.35-x/proxy.md b/app/enterprise/0.35-x/proxy.md
@@ -445,7 +445,9 @@ in the path (the root `/` character).
 As previously mentioned, Kong evaluates prefix paths by length: the longest
 prefix paths are evaluated first. However, Kong will evaluate regex paths based
 on the `regex_priority` attribute of Routes from highest priority to lowest.
-This means that considering the following Routes:
+Regex paths are furthermore evaluated before prefix paths.
+
+Consider the following Routes:
 
 ```json
 [
@@ -469,16 +471,21 @@ This means that considering the following Routes:
 In this scenario, Kong will evaluate incoming requests against the following
 defined URIs, in this order:
 
-1. `/version/any/`
-2. `/version`
-3. `/version/\d+/status/\d+`
-4. `/status/\d+`
+1. `/version/\d+/status/\d+`
+2. `/status/\d+`
+3. `/version/any/`
+4. `/version`
 
-Prefix paths are always evaluated before regex paths.
+Take care to avoid writing regex rules that are overly broad and may consume
+traffic intended for a prefix rule. Adding a rule with the path `/version/.*` to
+the ruleset above would likely consume some traffic intended for the `/version`
+prefix path. If you see unexpected behavior, sending `X-Kong-Debug: 1` in your
+request headers will indicate the matched Route ID in the response headers for
+troubleshooting purposes.
 
 As usual, a request must still match a Route's `hosts` and `methods` properties
-as well, and Kong will traverse your Routes until it finds one that matches
-the most rules (see [Routing priorities][proxy-routing-priorities]).
+as well, and Kong will traverse your Routes until it finds one that [matches
+the most rules](#matching-priorities).
 
 [Back to TOC](#table-of-contents)
 

diff --git a/app/enterprise/0.36-x/proxy.md b/app/enterprise/0.36-x/proxy.md
@@ -445,7 +445,9 @@ in the path (the root `/` character).
 As previously mentioned, Kong evaluates prefix paths by length: the longest
 prefix paths are evaluated first. However, Kong will evaluate regex paths based
 on the `regex_priority` attribute of Routes from highest priority to lowest.
-This means that considering the following Routes:
+Regex paths are furthermore evaluated before prefix paths.
+
+Consider the following Routes:
 
 ```json
 [
@@ -469,16 +471,21 @@ This means that considering the following Routes:
 In this scenario, Kong will evaluate incoming requests against the following
 defined URIs, in this order:
 
-1. `/version/any/`
-2. `/version`
-3. `/version/\d+/status/\d+`
-4. `/status/\d+`
+1. `/version/\d+/status/\d+`
+2. `/status/\d+`
+3. `/version/any/`
+4. `/version`
 
-Prefix paths are always evaluated before regex paths.
+Take care to avoid writing regex rules that are overly broad and may consume
+traffic intended for a prefix rule. Adding a rule with the path `/version/.*` to
+the ruleset above would likely consume some traffic intended for the `/version`
+prefix path. If you see unexpected behavior, sending `X-Kong-Debug: 1` in your
+request headers will indicate the matched Route ID in the response headers for
+troubleshooting purposes.
 
 As usual, a request must still match a Route's `hosts` and `methods` properties
-as well, and Kong will traverse your Routes until it finds one that matches
-the most rules (see [Routing priorities][proxy-routing-priorities]).
+as well, and Kong will traverse your Routes until it finds one that [matches
+the most rules](#matching-priorities).
 
 [Back to TOC](#table-of-contents)