doc: router: options

- Add failOnDuplicateRoutes
- fix #3741

Author: jknack

docs/asciidoc/handlers/access-log.adoc

@@ -56,5 +56,5 @@ Extra request or response headers can be appended at the end using the available
 [TIP]
 ====
 If you run behind a reverse proxy that has been configured to send the X-Forwarded-* header,
-please consider to use <<router-options-trust-proxy, trust proxy>> option.
+please consider to use <<router-options-routing, trust proxy>> option.
 ====

docs/asciidoc/handlers/ssl.adoc

@@ -38,7 +38,7 @@ import io.jooby.handler.SSHandler
 <1> Install SSLHandler
 
 The SSL Handler recreates the HTTPs URL version using the `Host` header, if you are behind a proxy
-you will need to use the `X-Forwarded-Host` header. To do that set the <<router-options-trust-proxy, trust proxy>> option.
+you will need to use the `X-Forwarded-Host` header. To do that set the <<router-options-routing, trust proxy>> option.
 
 Optionally, you can specify the host to use:
 
@@ -79,5 +79,5 @@ For more information about SSL, please check the <<server-https-support, configu
 [TIP]
 ====
 If you run behind a reverse proxy that has been configured to send the X-Forwarded-* header,
-please consider adding the <<router-options-trust-proxy, trust proxy>> to your pipeline.
+please consider adding the <<router-options-routing, trust proxy>> to your pipeline.
 ====

docs/asciidoc/router-options.adoc

@@ -0,0 +1,81 @@
+==== Routing
+
+The javadoc:Router[setRouterOptions, io.jooby.RouterOptions] control routing options.
+
+.Usage
+[source, java, role = "primary"]
+----
+import io.jooby.Jooby;
+...
+{
+  
+  setRouterOptions(new RouterOptions()
+        .setIgnoreCase(true)
+        .setFailOnDuplicateRoutes(true)
+        .setIgnoreTrailingSlash(true)
+        .setNormalizeSlash(true)
+        .setResetHeadersOnError(false)
+        .setTrustProxy(true)
+  );
+}
+----
+
+.Kotlin
+[source, kotlin, role = "secondary"]
+----
+import io.jooby.Jooby
+...
+{
+  routerOptions = RouterOptions().apply {
+    ignoreCase = true
+    ignoreTrailingSlash = true
+    failOnDuplicateRoutes = true
+    normalizeSlash = true
+    resetHeadersOnError = false
+    trustProxy = true
+  }
+}
+----
+
+[cols="1,1,1,1"]
+|===
+| Option | Value | Default Value| Description
+
+|ignoreCase
+|boolean
+|false
+|Indicates whenever routing algorithm does case-sensitive matching on an incoming request path.
+
+|ignoreTrailingSlash
+|boolean
+|false
+|Indicates whenever a trailing slash is ignored on an incoming request path.
+
+|failOnDuplicateRoutes
+|boolean
+|false
+|Indicates whenever a trailing slash is ignored on an incoming request path.
+
+|normalizeSlash
+|boolean
+|false
+|Normalize an incoming request path by removing multiple slash sequences.
+
+|resetHeadersOnError
+|boolean
+|true
+|Indicates whenever response headers are clear/reset in case of exception.
+
+|trustProxy
+|boolean
+|false
+|When true handles X-Forwarded-* headers by updating the values on the current context to match what was sent in the header(s).
+
+|===
+
+[IMPORTANT]
+====
+trustProxy: This should only be installed behind a reverse proxy that has been configured to send the
+`X-Forwarded-*` header, otherwise a remote user can spoof their address by sending a header with
+bogus values.
+====

docs/asciidoc/router-trust-proxy.adoc

@@ -1414,6 +1414,6 @@ might not work as you expected. It is recommend to use just the `logback.xml` or
 
 === Options
 
-include::router-hidden-method.adoc[]
+include::router-options.adoc[]
 
-include::router-trust-proxy.adoc[]
+include::router-hidden-method.adoc[]