summaryrefslogtreecommitdiffstats
path: root/docs/en/cowboy/2.0/guide/routing/index.html
diff options
context:
space:
mode:
Diffstat (limited to 'docs/en/cowboy/2.0/guide/routing/index.html')
-rw-r--r--docs/en/cowboy/2.0/guide/routing/index.html515
1 files changed, 259 insertions, 256 deletions
diff --git a/docs/en/cowboy/2.0/guide/routing/index.html b/docs/en/cowboy/2.0/guide/routing/index.html
index f67532cd..24f5ca46 100644
--- a/docs/en/cowboy/2.0/guide/routing/index.html
+++ b/docs/en/cowboy/2.0/guide/routing/index.html
@@ -7,7 +7,7 @@
<meta name="description" content="">
<meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara">
- <meta name="generator" content="Hugo 0.17" />
+ <meta name="generator" content="Hugo 0.26" />
<title>Nine Nines: Routing</title>
@@ -67,267 +67,270 @@
<h1 class="lined-header"><span>Routing</span></h1>
-<div class="paragraph"><p>Cowboy does nothing by default.</p></div>
-<div class="paragraph"><p>To make Cowboy useful, you need to map URIs to Erlang modules that will
-handle the requests. This is called routing.</p></div>
-<div class="paragraph"><p>When Cowboy receives a request, it tries to match the requested host and
-path to the configured routes. When there&#8217;s a match, the route&#8217;s
-associated handler is executed.</p></div>
-<div class="paragraph"><p>Routes need to be compiled before they can be used by Cowboy.
-The result of the compilation is the dispatch rules.</p></div>
-<div class="sect1">
-<h2 id="_syntax">Syntax</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The general structure for the routes is defined as follow.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Routes</span> <span style="color: #990000">=</span> [<span style="color: #009900">Host1</span>, <span style="color: #009900">Host2</span>, <span style="color: #990000">...</span> <span style="color: #009900">HostN</span>]<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Each host contains matching rules for the host along with optional
-constraints, and a list of routes for the path component.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Host1</span> <span style="color: #990000">=</span> {<span style="color: #009900">HostMatch</span>, <span style="color: #009900">PathsList</span>}<span style="color: #990000">.</span>
-<span style="color: #009900">Host2</span> <span style="color: #990000">=</span> {<span style="color: #009900">HostMatch</span>, <span style="color: #009900">Constraints</span>, <span style="color: #009900">PathsList</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The list of routes for the path component is defined similar to the
-list of hosts.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">PathsList</span> <span style="color: #990000">=</span> [<span style="color: #009900">Path1</span>, <span style="color: #009900">Path2</span>, <span style="color: #990000">...</span> <span style="color: #009900">PathN</span>]<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Finally, each path contains matching rules for the path along with
-optional constraints, and gives us the handler module to be used
-along with its initial state.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Path1</span> <span style="color: #990000">=</span> {<span style="color: #009900">PathMatch</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">InitialState</span>}<span style="color: #990000">.</span>
-<span style="color: #009900">Path2</span> <span style="color: #990000">=</span> {<span style="color: #009900">PathMatch</span>, <span style="color: #009900">Constraints</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">InitialState</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Continue reading to learn more about the match syntax and the optional
-constraints.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_match_syntax">Match syntax</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The match syntax is used to associate host names and paths with their
-respective handlers.</p></div>
-<div class="paragraph"><p>The match syntax is the same for host and path with a few subtleties.
-Indeed, the segments separator is different, and the host is matched
-starting from the last segment going to the first. All examples will
-feature both host and path match rules and explain the differences
-when encountered.</p></div>
-<div class="paragraph"><p>Excluding special values that we will explain at the end of this section,
-the simplest match value is a host or a path. It can be given as either
-a <code>string()</code> or a <code>binary()</code>.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">PathMatch1</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/"</span><span style="color: #990000">.</span>
-<span style="color: #009900">PathMatch2</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/path/to/resource"</span><span style="color: #990000">.</span>
-
-<span style="color: #009900">HostMatch1</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"cowboy.example.org"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>As you can see, all paths defined this way must start with a slash
-character. Note that these two paths are identical as far as routing
-is concerned.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">PathMatch2</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/path/to/resource"</span><span style="color: #990000">.</span>
-<span style="color: #009900">PathMatch3</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/path/to/resource/"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Hosts with and without a trailing dot are equivalent for routing.
-Similarly, hosts with and without a leading dot are also equivalent.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">HostMatch1</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"cowboy.example.org"</span><span style="color: #990000">.</span>
-<span style="color: #009900">HostMatch2</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"cowboy.example.org."</span><span style="color: #990000">.</span>
-<span style="color: #009900">HostMatch3</span> <span style="color: #990000">=</span> <span style="color: #FF0000">".cowboy.example.org"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>It is possible to extract segments of the host and path and to store
-the values in the <code>Req</code> object for later use. We call these kind of
-values bindings.</p></div>
-<div class="paragraph"><p>The syntax for bindings is very simple. A segment that begins with
-the <code>:</code> character means that what follows until the end of the segment
-is the name of the binding in which the segment value will be stored.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/:name/prices"</span><span style="color: #990000">.</span>
-<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">":subdomain.example.org"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>If these two end up matching when routing, you will end up with two
-bindings defined, <code>subdomain</code> and <code>name</code>, each containing the
-segment value where they were defined. For example, the URL
-<code>http://test.example.org/hats/wild_cowboy_legendary/prices</code> will
-result in having the value <code>test</code> bound to the name <code>subdomain</code>
-and the value <code>wild_cowboy_legendary</code> bound to the name <code>name</code>.
-They can later be retrieved using <code>cowboy_req:binding/{2,3}</code>. The
-binding name must be given as an atom.</p></div>
-<div class="paragraph"><p>There is a special binding name you can use to mimic the underscore
-variable in Erlang. Any match against the <code>_</code> binding will succeed
-but the data will be discarded. This is especially useful for
-matching against many domain names in one go.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"ninenines.:_"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Similarly, it is possible to have optional segments. Anything
-between brackets is optional.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/[page/:number]"</span><span style="color: #990000">.</span>
-<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"[www.]ninenines.eu"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can also have imbricated optional segments.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/[page/[:number]]"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can retrieve the rest of the host or path using <code>[...]</code>.
-In the case of hosts it will match anything before, in the case
-of paths anything after the previously matched segments. It is
-a special case of optional segments, in that it can have
-zero, one or many segments. You can then find the segments using
-<code>cowboy_req:host_info/1</code> and <code>cowboy_req:path_info/1</code> respectively.
-They will be represented as a list of segments.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/[...]"</span><span style="color: #990000">.</span>
-<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"[...]ninenines.eu"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>If a binding appears twice in the routing rules, then the match
-will succeed only if they share the same value. This copies the
-Erlang pattern matching behavior.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/:name/:name"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>This is also true when an optional segment is present. In this
-case the two values must be identical only if the segment is
-available.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/:name/[:name]"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>If a binding is defined in both the host and path, then they must
-also share the same value.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/:user/[...]"</span><span style="color: #990000">.</span>
-<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">":user.github.com"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Finally, there are two special match values that can be used. The
-first is the atom <code>'_'</code> which will match any host or path.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF6600">'_'</span><span style="color: #990000">.</span>
-<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF6600">'_'</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The second is the special host match <code>"*"</code> which will match the
-wildcard path, generally used alongside the <code>OPTIONS</code> method.</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"*"</span><span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_constraints">Constraints</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>After the matching has completed, the resulting bindings can be tested
-against a set of constraints. Constraints are only tested when the
-binding is defined. They run in the order you defined them. The match
-will succeed only if they all succeed. If the match fails, then Cowboy
-tries the next route in the list.</p></div>
-<div class="paragraph"><p>The format used for constraints is the same as match functions in
-<code>cowboy_req</code>: they are provided as a list of fields which may have
-one or more constraints. While the router accepts the same format,
-it will skip fields with no constraints and will also ignore default
-values, if any.</p></div>
-<div class="paragraph"><p>Read more about <a href="../constraints">constraints</a>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_compilation">Compilation</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The routes must be compiled before Cowboy can use them. The compilation
-step normalizes the routes to simplify the code and speed up the
-execution, but the routes are still looked up one by one in the end.
-Faster compilation strategies could be to compile the routes directly
-to Erlang code, but would require heavier dependencies.</p></div>
-<div class="paragraph"><p>To compile routes, just call the appropriate function:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([
- <span style="font-style: italic"><span style="color: #9A1900">%% {HostMatch, list({PathMatch, Handler, InitialState})}</span></span>
- {<span style="color: #FF6600">'_'</span>, [{<span style="color: #FF6600">'_'</span>, <span style="color: #FF6600">my_handler</span>, #{}}]}
-]),
-<span style="font-style: italic"><span style="color: #9A1900">%% Name, NbAcceptors, TransOpts, ProtoOpts</span></span>
-<span style="font-weight: bold"><span style="color: #000000">cowboy:start_clear</span></span>(<span style="color: #FF6600">my_http_listener</span>,
- [{<span style="color: #FF6600">port</span>, <span style="color: #993399">8080</span>}],
- #{<span style="color: #0000FF">env</span> <span style="color: #990000">=&gt;</span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=&gt;</span> <span style="color: #009900">Dispatch</span>}}
-)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_live_update">Live update</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can use the <code>cowboy:set_env/3</code> function for updating the dispatch
-list used by routing. This will apply to all new connections accepted
-by the listener:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>(<span style="color: #009900">Routes</span>),
-<span style="font-weight: bold"><span style="color: #000000">cowboy:set_env</span></span>(<span style="color: #FF6600">my_http_listener</span>, <span style="color: #FF6600">dispatch</span>, <span style="color: #009900">Dispatch</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Note that you need to compile the routes again before updating.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Cowboy does nothing by default.</p></div>
+<div class="paragraph"><p>To make Cowboy useful, you need to map URIs to Erlang modules that will
+handle the requests. This is called routing.</p></div>
+<div class="paragraph"><p>When Cowboy receives a request, it tries to match the requested host and
+path to the configured routes. When there&#8217;s a match, the route&#8217;s
+associated handler is executed.</p></div>
+<div class="paragraph"><p>Routes need to be compiled before they can be used by Cowboy.
+The result of the compilation is the dispatch rules.</p></div>
+<div class="sect1">
+<h2 id="_syntax">Syntax</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The general structure for the routes is defined as follow.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">Routes</span> <span style="color: #990000">=</span> [<span style="color: #009900">Host1</span>, <span style="color: #009900">Host2</span>, <span style="color: #990000">...</span> <span style="color: #009900">HostN</span>]<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Each host contains matching rules for the host along with optional
+constraints, and a list of routes for the path component.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">Host1</span> <span style="color: #990000">=</span> {<span style="color: #009900">HostMatch</span>, <span style="color: #009900">PathsList</span>}<span style="color: #990000">.</span>
+<span style="color: #009900">Host2</span> <span style="color: #990000">=</span> {<span style="color: #009900">HostMatch</span>, <span style="color: #009900">Constraints</span>, <span style="color: #009900">PathsList</span>}<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>The list of routes for the path component is defined similar to the
+list of hosts.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">PathsList</span> <span style="color: #990000">=</span> [<span style="color: #009900">Path1</span>, <span style="color: #009900">Path2</span>, <span style="color: #990000">...</span> <span style="color: #009900">PathN</span>]<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Finally, each path contains matching rules for the path along with
+optional constraints, and gives us the handler module to be used
+along with its initial state.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">Path1</span> <span style="color: #990000">=</span> {<span style="color: #009900">PathMatch</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">InitialState</span>}<span style="color: #990000">.</span>
+<span style="color: #009900">Path2</span> <span style="color: #990000">=</span> {<span style="color: #009900">PathMatch</span>, <span style="color: #009900">Constraints</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">InitialState</span>}<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Continue reading to learn more about the match syntax and the optional
+constraints.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_match_syntax">Match syntax</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The match syntax is used to associate host names and paths with their
+respective handlers.</p></div>
+<div class="paragraph"><p>The match syntax is the same for host and path with a few subtleties.
+Indeed, the segments separator is different, and the host is matched
+starting from the last segment going to the first. All examples will
+feature both host and path match rules and explain the differences
+when encountered.</p></div>
+<div class="paragraph"><p>Excluding special values that we will explain at the end of this section,
+the simplest match value is a host or a path. It can be given as either
+a <code>string()</code> or a <code>binary()</code>.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">PathMatch1</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/"</span><span style="color: #990000">.</span>
+<span style="color: #009900">PathMatch2</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/path/to/resource"</span><span style="color: #990000">.</span>
+
+<span style="color: #009900">HostMatch1</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"cowboy.example.org"</span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>As you can see, all paths defined this way must start with a slash
+character. Note that these two paths are identical as far as routing
+is concerned.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">PathMatch2</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/path/to/resource"</span><span style="color: #990000">.</span>
+<span style="color: #009900">PathMatch3</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/path/to/resource/"</span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Hosts with and without a trailing dot are equivalent for routing.
+Similarly, hosts with and without a leading dot are also equivalent.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">HostMatch1</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"cowboy.example.org"</span><span style="color: #990000">.</span>
+<span style="color: #009900">HostMatch2</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"cowboy.example.org."</span><span style="color: #990000">.</span>
+<span style="color: #009900">HostMatch3</span> <span style="color: #990000">=</span> <span style="color: #FF0000">".cowboy.example.org"</span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>It is possible to extract segments of the host and path and to store
+the values in the <code>Req</code> object for later use. We call these kind of
+values bindings.</p></div>
+<div class="paragraph"><p>The syntax for bindings is very simple. A segment that begins with
+the <code>:</code> character means that what follows until the end of the segment
+is the name of the binding in which the segment value will be stored.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/:name/prices"</span><span style="color: #990000">.</span>
+<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">":subdomain.example.org"</span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>If these two end up matching when routing, you will end up with two
+bindings defined, <code>subdomain</code> and <code>name</code>, each containing the
+segment value where they were defined. For example, the URL
+<code>http://test.example.org/hats/wild_cowboy_legendary/prices</code> will
+result in having the value <code>test</code> bound to the name <code>subdomain</code>
+and the value <code>wild_cowboy_legendary</code> bound to the name <code>name</code>.
+They can later be retrieved using <code>cowboy_req:binding/{2,3}</code>. The
+binding name must be given as an atom.</p></div>
+<div class="paragraph"><p>There is a special binding name you can use to mimic the underscore
+variable in Erlang. Any match against the <code>_</code> binding will succeed
+but the data will be discarded. This is especially useful for
+matching against many domain names in one go.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"ninenines.:_"</span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Similarly, it is possible to have optional segments. Anything
+between brackets is optional.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/[page/:number]"</span><span style="color: #990000">.</span>
+<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"[www.]ninenines.eu"</span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>You can also have imbricated optional segments.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/[page/[:number]]"</span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>You can retrieve the rest of the host or path using <code>[...]</code>.
+In the case of hosts it will match anything before, in the case
+of paths anything after the previously matched segments. It is
+a special case of optional segments, in that it can have
+zero, one or many segments. You can then find the segments using
+<code>cowboy_req:host_info/1</code> and <code>cowboy_req:path_info/1</code> respectively.
+They will be represented as a list of segments.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/[...]"</span><span style="color: #990000">.</span>
+<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"[...]ninenines.eu"</span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>If a binding appears twice in the routing rules, then the match
+will succeed only if they share the same value. This copies the
+Erlang pattern matching behavior.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/:name/:name"</span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>This is also true when an optional segment is present. In this
+case the two values must be identical only if the segment is
+available.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/:name/[:name]"</span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>If a binding is defined in both the host and path, then they must
+also share the same value.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/:user/[...]"</span><span style="color: #990000">.</span>
+<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">":user.github.com"</span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Finally, there are two special match values that can be used. The
+first is the atom <code>'_'</code> which will match any host or path.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF6600">'_'</span><span style="color: #990000">.</span>
+<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF6600">'_'</span><span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>The second is the special host match <code>"*"</code> which will match the
+wildcard path, generally used alongside the <code>OPTIONS</code> method.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"*"</span><span style="color: #990000">.</span></tt></pre></div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_constraints">Constraints</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>After the matching has completed, the resulting bindings can be tested
+against a set of constraints. Constraints are only tested when the
+binding is defined. They run in the order you defined them. The match
+will succeed only if they all succeed. If the match fails, then Cowboy
+tries the next route in the list.</p></div>
+<div class="paragraph"><p>The format used for constraints is the same as match functions in
+<code>cowboy_req</code>: they are provided as a list of fields which may have
+one or more constraints. While the router accepts the same format,
+it will skip fields with no constraints and will also ignore default
+values, if any.</p></div>
+<div class="paragraph"><p>Read more about <a href="../constraints">constraints</a>.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_compilation">Compilation</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The routes must be compiled before Cowboy can use them. The compilation
+step normalizes the routes to simplify the code and speed up the
+execution, but the routes are still looked up one by one in the end.
+Faster compilation strategies could be to compile the routes directly
+to Erlang code, but would require heavier dependencies.</p></div>
+<div class="paragraph"><p>To compile routes, just call the appropriate function:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>([
+ <span style="font-style: italic"><span style="color: #9A1900">%% {HostMatch, list({PathMatch, Handler, InitialState})}</span></span>
+ {<span style="color: #FF6600">'_'</span>, [{<span style="color: #FF6600">'_'</span>, <span style="color: #FF6600">my_handler</span>, #{}}]}
+]),
+<span style="font-style: italic"><span style="color: #9A1900">%% Name, NbAcceptors, TransOpts, ProtoOpts</span></span>
+<span style="font-weight: bold"><span style="color: #000000">cowboy:start_clear</span></span>(<span style="color: #FF6600">my_http_listener</span>,
+ [{<span style="color: #FF6600">port</span>, <span style="color: #993399">8080</span>}],
+ #{<span style="color: #0000FF">env</span> <span style="color: #990000">=&gt;</span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=&gt;</span> <span style="color: #009900">Dispatch</span>}}
+)<span style="color: #990000">.</span></tt></pre></div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_live_update">Live update</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>You can use the <code>cowboy:set_env/3</code> function for updating the dispatch
+list used by routing. This will apply to all new connections accepted
+by the listener:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>(<span style="color: #009900">Routes</span>),
+<span style="font-weight: bold"><span style="color: #000000">cowboy:set_env</span></span>(<span style="color: #FF6600">my_http_listener</span>, <span style="color: #FF6600">dispatch</span>, <span style="color: #009900">Dispatch</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Note that you need to compile the routes again before updating.</p></div>
+</div>
+</div>
+
+
+
<nav style="margin:1em 0">