From 78b23ddfa555136ddf9cd81396e5375845de219c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 20 May 2020 10:53:52 +0200 Subject: Clarify the routing algorithm --- doc/src/guide/routing.asciidoc | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/doc/src/guide/routing.asciidoc b/doc/src/guide/routing.asciidoc index 9e2ef25..37d3e5a 100644 --- a/doc/src/guide/routing.asciidoc +++ b/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 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. The result of the compilation is the dispatch rules. -- cgit v1.2.3