mirror of
https://github.com/ninenines/cowboy.git
synced 2025-07-15 20:50:24 +00:00
Convert the documentation to Asciidoc
A few small revisions were made, and Erlang.mk has been updated.
This commit is contained in:
Loïc Hoguin
parent
b7d666cfc7
commit
4023e7f4e4
55 changed files with 5701 additions and 1889 deletions
|
|
@ -1,239 +0,0 @@
|
|||
::: Routing
|
||||
|
||||
Cowboy does nothing by default.
|
||||
|
||||
To make Cowboy useful, you need to map URLs 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 resources given in the dispatch rules. If it matches, then
|
||||
the associated Erlang code will be 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.
|
||||
|
||||
:: Structure
|
||||
|
||||
The general structure for the routes is defined as follow.
|
||||
|
||||
``` erlang
|
||||
Routes = [Host1, Host2, ... HostN].
|
||||
```
|
||||
|
||||
Each host contains matching rules for the host along with optional
|
||||
constraints, and a list of routes for the path component.
|
||||
|
||||
``` erlang
|
||||
Host1 = {HostMatch, PathsList}.
|
||||
Host2 = {HostMatch, Constraints, PathsList}.
|
||||
```
|
||||
|
||||
The list of routes for the path component is defined similar to the
|
||||
list of hosts.
|
||||
|
||||
``` erlang
|
||||
PathsList = [Path1, Path2, ... PathN].
|
||||
```
|
||||
|
||||
Finally, each path contains matching rules for the path along with
|
||||
optional constraints, and gives us the handler module to be used
|
||||
along with options that will be given to it on initialization.
|
||||
|
||||
``` erlang
|
||||
Path1 = {PathMatch, Handler, Opts}.
|
||||
Path2 = {PathMatch, Constraints, Handler, Opts}.
|
||||
```
|
||||
|
||||
Continue reading to learn more about the match syntax and the optional
|
||||
constraints.
|
||||
|
||||
:: Match syntax
|
||||
|
||||
The match syntax is used to associate host names and paths with their
|
||||
respective handlers.
|
||||
|
||||
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.
|
||||
|
||||
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 `string()` or a `binary()`.
|
||||
|
||||
``` erlang
|
||||
PathMatch1 = "/".
|
||||
PathMatch2 = "/path/to/resource".
|
||||
|
||||
HostMatch1 = "cowboy.example.org".
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
``` erlang
|
||||
PathMatch2 = "/path/to/resource".
|
||||
PathMatch3 = "/path/to/resource/".
|
||||
```
|
||||
|
||||
Hosts with and without a trailing dot are equivalent for routing.
|
||||
Similarly, hosts with and without a leading dot are also equivalent.
|
||||
|
||||
``` erlang
|
||||
HostMatch1 = "cowboy.example.org".
|
||||
HostMatch2 = "cowboy.example.org.".
|
||||
HostMatch3 = ".cowboy.example.org".
|
||||
```
|
||||
|
||||
It is possible to extract segments of the host and path and to store
|
||||
the values in the `Req` object for later use. We call these kind of
|
||||
values bindings.
|
||||
|
||||
The syntax for bindings is very simple. A segment that begins with
|
||||
the `:` 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.
|
||||
|
||||
``` erlang
|
||||
PathMatch = "/hats/:name/prices".
|
||||
HostMatch = ":subdomain.example.org".
|
||||
```
|
||||
|
||||
If these two end up matching when routing, you will end up with two
|
||||
bindings defined, `subdomain` and `name`, each containing the
|
||||
segment value where they were defined. For example, the URL
|
||||
`http://test.example.org/hats/wild_cowboy_legendary/prices` will
|
||||
result in having the value `test` bound to the name `subdomain`
|
||||
and the value `wild_cowboy_legendary` bound to the name `name`.
|
||||
They can later be retrieved using `cowboy_req:binding/{2,3}`. The
|
||||
binding name must be given as an atom.
|
||||
|
||||
There is a special binding name you can use to mimic the underscore
|
||||
variable in Erlang. Any match against the `_` binding will succeed
|
||||
but the data will be discarded. This is especially useful for
|
||||
matching against many domain names in one go.
|
||||
|
||||
``` erlang
|
||||
HostMatch = "ninenines.:_".
|
||||
```
|
||||
|
||||
Similarly, it is possible to have optional segments. Anything
|
||||
between brackets is optional.
|
||||
|
||||
``` erlang
|
||||
PathMatch = "/hats/[page/:number]".
|
||||
HostMatch = "[www.]ninenines.eu".
|
||||
```
|
||||
|
||||
You can also have imbricated optional segments.
|
||||
|
||||
``` erlang
|
||||
PathMatch = "/hats/[page/[:number]]".
|
||||
```
|
||||
|
||||
You can retrieve the rest of the host or path using `[...]`.
|
||||
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
|
||||
`cowboy_req:host_info/1` and `cowboy_req:path_info/1` respectively.
|
||||
They will be represented as a list of segments.
|
||||
|
||||
``` erlang
|
||||
PathMatch = "/hats/[...]".
|
||||
HostMatch = "[...]ninenines.eu".
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
``` erlang
|
||||
PathMatch = "/hats/:name/:name".
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
``` erlang
|
||||
PathMatch = "/hats/:name/[:name]".
|
||||
```
|
||||
|
||||
If a binding is defined in both the host and path, then they must
|
||||
also share the same value.
|
||||
|
||||
``` erlang
|
||||
PathMatch = "/:user/[...]".
|
||||
HostMatch = ":user.github.com".
|
||||
```
|
||||
|
||||
Finally, there are two special match values that can be used. The
|
||||
first is the atom `'_'` which will match any host or path.
|
||||
|
||||
``` erlang
|
||||
PathMatch = '_'.
|
||||
HostMatch = '_'.
|
||||
```
|
||||
|
||||
The second is the special host match `"*"` which will match the
|
||||
wildcard path, generally used alongside the `OPTIONS` method.
|
||||
|
||||
``` erlang
|
||||
HostMatch = "*".
|
||||
```
|
||||
|
||||
:: Constraints
|
||||
|
||||
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.
|
||||
|
||||
The format used for constraints is the same as match functions in
|
||||
`cowboy_req`: 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.
|
||||
|
||||
Read more about ^constraints^.
|
||||
|
||||
:: Compilation
|
||||
|
||||
The structure defined in this chapter needs to be compiled before it is
|
||||
passed to Cowboy. This allows Cowboy to efficiently lookup the correct
|
||||
handler to run instead of having to parse the routes repeatedly.
|
||||
|
||||
This can be done with a simple call to `cowboy_router:compile/1`.
|
||||
|
||||
``` erlang
|
||||
Dispatch = cowboy_router:compile([
|
||||
%% {HostMatch, list({PathMatch, Handler, Opts})}
|
||||
{'_', [{'_', my_handler, []}]}
|
||||
]),
|
||||
%% Name, NbAcceptors, TransOpts, ProtoOpts
|
||||
cowboy:start_http(my_http_listener, 100,
|
||||
[{port, 8080}],
|
||||
[{env, [{dispatch, Dispatch}]}]
|
||||
).
|
||||
```
|
||||
|
||||
Note that this function will return `{error, badarg}` if the structure
|
||||
given is incorrect.
|
||||
|
||||
:: Live update
|
||||
|
||||
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
|
||||
by the listener.
|
||||
|
||||
``` erlang
|
||||
cowboy:set_env(my_http_listener, dispatch,
|
||||
cowboy_router:compile(Dispatch)).
|
||||
```
|
||||
|
||||
Note that you need to compile the routes before updating.
|
||||
Loading…
Add table
Add a link
Reference in a new issue