Browse Source

Clarify the routing algorithm

Loïc Hoguin 5 years ago
parent
commit
78b23ddfa5
1 changed files with 20 additions and 3 deletions
  1. 20 3
      doc/src/guide/routing.asciidoc

+ 20 - 3
doc/src/guide/routing.asciidoc

@@ -6,9 +6,26 @@ Cowboy does nothing by default.
 To make Cowboy useful, you need to map URIs to Erlang modules that will
 To make Cowboy useful, you need to map URIs to Erlang modules that will
 handle the requests. This is called routing.
 handle the requests. This is called routing.
 
 
-When Cowboy receives a request, it tries to match the requested host and
-path to the configured routes. When there's a match, the route's
-associated handler is executed.
+Cowboy routes requests using the following algorithm:
+
+* If no configured host matches the request URI, a 400 response
+  is returned.
+
+* Otherwise, the first configured host that matches the request
+  URI will be used. Only the paths configured for this host will
+  be considered.
+
+* If none of the configured paths found in the previous step
+  match the request URI, a 404 response is returned.
+
+* Otherwise, the handler and its initial state are added to the
+  environment and the request continues to be processed.
+
+NOTE: It is possible to run into a situation where two hosts match a
+request URI, but only the paths on the second host match the
+request URI. In this case the expected result is a 404 response
+because the only paths used during routing are the paths from
+the first configured host that matches the request URI.
 
 
 Routes need to be compiled before they can be used by Cowboy.
 Routes need to be compiled before they can be used by Cowboy.
 The result of the compilation is the dispatch rules.
 The result of the compilation is the dispatch rules.