aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/manual/cowboy_router.asciidoc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/manual/cowboy_router.asciidoc')
-rw-r--r--doc/src/manual/cowboy_router.asciidoc91
1 files changed, 64 insertions, 27 deletions
diff --git a/doc/src/manual/cowboy_router.asciidoc b/doc/src/manual/cowboy_router.asciidoc
index 9142930..a830618 100644
--- a/doc/src/manual/cowboy_router.asciidoc
+++ b/doc/src/manual/cowboy_router.asciidoc
@@ -2,55 +2,92 @@
== Name
-cowboy_router - router middleware
+cowboy_router - Router middleware
== Description
The `cowboy_router` middleware maps the requested host and
path to the handler to be used for processing the request.
-It uses the dispatch rules compiled from the routes given
-to the `compile/1` function for this purpose. It adds the
-handler name and options to the environment as the values
-`handler` and `handler_opts` respectively.
-=== Environment input
+The router takes the `dispatch` rules as input from the
+middleware environment. Dispatch rules are generated by
+calling the
+link:man:cowboy_router:compile(3)[cowboy_router:compile(3)]
+function.
-dispatch = dispatch_rules():: Dispatch table.
+When a route matches, the router sets the `handler` and
+`handler_opts` middleware environment values containing
+the handler module and initial state, respectively.
-=== Environment output
+The router will stop execution when no route matches.
+It will send a 400 response if no host was found, and
+a 404 response otherwise.
-handler = module():: Handler module.
-handler_opts = any():: Handler options.
+== Exports
+
+* link:man:cowboy_router:compile(3)[cowboy_router:compile(3)] - Compile routes to the resources
== Types
-=== bindings() = [{atom(), binary()}]
+=== bindings()
-List of bindings found during routing.
+[source,erlang]
+----
+bindings() :: [{atom(), binary()}]
+----
-=== dispatch_rules() - opaque to the user
+Bindings found during routing.
-Rules for dispatching request used by Cowboy.
+=== dispatch_rules()
-=== routes() = [{Host, Paths} | {Host, cowboy:fields(), Paths}]
+Opaque type containing the compiled routes.
-With types:
+=== routes()
-* Host = Path = '_' | iodata()
-* Paths = [{Path, Handler, Opts} | {Path, cowboy:fields(), Handler, HandlerOpts}]
-* Handler = module()
-* HandlerOpts = any()
+[source,erlang]
+----
+routes() = [
+ {Host, PathList} |
+ {Host, Fields, PathList}
+]
-Human readable list of routes mapping hosts and paths to handlers.
+PathList :: [
+ {Path, Handler, InitialState} |
+ {Path, Fields, Handler, InitialState}
+]
-The syntax for routes is defined in the user guide.
+Host :: '_' | iodata()
+Path :: '_' | iodata()
+Fields :: cowboy:fields()
+Handler :: module()
+InitialState :: any()
+----
-=== tokens() = [binary()]
+Human readable list of routes to handlers.
-List of host_info and path_info tokens found during routing.
+Cowboy uses this list to map hosts and paths, optionally
+augmented with constraints applied to the bindings, to
+handler modules.
-== Exports
+The syntax for routes is currently defined in the user guide.
+
+// @todo The syntax should probably be in this module,
+// and the user guide show more practical examples.
+
+=== tokens()
+
+[source,erlang]
+----
+tokens() :: [binary()]
+----
+
+List of `host_info` and `path_info` tokens that were found
+using the `...` syntax.
-=== compile(routes()) -> dispatch_rules()
+== See also
-Compile the routes for use by Cowboy.
+link:man:cowboy(7)[cowboy(7)],
+link:man:cowboy_req:binding(3)[cowboy_req:binding(3)],
+link:man:cowboy_req:bindings(3)[cowboy_req:bindings(3)],
+link:man:cowboy_req:host_info(3)[cowboy_req:host_info(3)],
+link:man:cowboy_req:path_info(3)[cowboy_req:path_info(3)]