umgeher/cowboy
0
Fork 0
mirror of https://github.com/ninenines/cowboy.git synced 2025-07-14 20:30:23 +00:00
Code Issues Wiki Activity

Update the routing chapter

Browse source
This commit is contained in:
Loïc Hoguin 2016-09-04 19:47:09 +02:00
parent 8777f631ca
commit 06e1e2be68
1 changed files with 13 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

29
doc/src/guide/routing.asciidoc
View file

@ -3,19 +3,17 @@
Cowboy does nothing by default. Cowboy does nothing by default.
To make Cowboy useful, you need to map URLs 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 When Cowboy receives a request, it tries to match the requested host and
path to the resources given in the dispatch rules. If it matches, then path to the configured routes. When there's a match, the route's
the associated Erlang code will be executed. associated handler is executed.
Routing rules are given per host. Cowboy will first match on the host,
and then try to find a matching path.
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.
=== Structure === Syntax
The general structure for the routes is defined as follow. The general structure for the routes is defined as follow.
@ -190,11 +188,13 @@ Read more about xref:constraints[constraints].
=== Compilation === Compilation
The structure defined in this chapter needs to be compiled before it is The routes must be compiled before Cowboy can use them. The compilation
passed to Cowboy. This allows Cowboy to efficiently lookup the correct step normalizes the routes to simplify the code and speed up the
handler to run instead of having to parse the routes repeatedly. 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.
This can be done with a simple call to `cowboy_router:compile/1`. To compile routes, just call the appropriate function:
[source,erlang] [source,erlang]
---- ----
@ -209,16 +209,13 @@ cowboy:start_clear(my_http_listener, 100,
). ).
---- ----
Note that this function will return `{error, badarg}` if the structure
given is incorrect.
=== Live update === Live update
You can use the `cowboy:set_env/3` function for updating the dispatch You can use the `cowboy:set_env/3` function for updating the dispatch
list used by routing. This will apply to all new connections accepted list used by routing. This will apply to all new connections accepted
by the listener. by the listener:
[source,erlang] [source,erlang]
cowboy:set_env(my_http_listener, dispatch, cowboy_router:compile(Dispatch)). cowboy:set_env(my_http_listener, dispatch, cowboy_router:compile(Dispatch)).
Note that you need to compile the routes before updating. Note that you need to compile the routes again before updating.