aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2016-12-22 12:53:21 +0100
committerLoïc Hoguin <[email protected]>2016-12-22 12:53:21 +0100
commita1b52494a54ede247a5eb0448a94aeb76d61f74e (patch)
tree87745c2bd5b872b46097f37ec236fc7852e2220e /doc/src
parent89120a360610ec5f04cad4eb362cbeccdb9adf0c (diff)
downloadcowboy-a1b52494a54ede247a5eb0448a94aeb76d61f74e.tar.gz
cowboy-a1b52494a54ede247a5eb0448a94aeb76d61f74e.tar.bz2
cowboy-a1b52494a54ede247a5eb0448a94aeb76d61f74e.zip
Update the cowboy_router manual
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/manual/cowboy_req.binding.asciidoc3
-rw-r--r--doc/src/manual/cowboy_req.bindings.asciidoc3
-rw-r--r--doc/src/manual/cowboy_req.host_info.asciidoc3
-rw-r--r--doc/src/manual/cowboy_req.path_info.asciidoc3
-rw-r--r--doc/src/manual/cowboy_router.asciidoc91
-rw-r--r--doc/src/manual/cowboy_router.compile.asciidoc53
6 files changed, 125 insertions, 31 deletions
diff --git a/doc/src/manual/cowboy_req.binding.asciidoc b/doc/src/manual/cowboy_req.binding.asciidoc
index 4e27f31..02f8209 100644
--- a/doc/src/manual/cowboy_req.binding.asciidoc
+++ b/doc/src/manual/cowboy_req.binding.asciidoc
@@ -64,4 +64,5 @@ Branch = cowboy_req:binding(branch, Req, <<"master">>)
link:man:cowboy_req(3)[cowboy_req(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)]
+link:man:cowboy_req:path_info(3)[cowboy_req:path_info(3)],
+link:man:cowboy_router(3)[cowboy_router(3)]
diff --git a/doc/src/manual/cowboy_req.bindings.asciidoc b/doc/src/manual/cowboy_req.bindings.asciidoc
index 3e89859..3099366 100644
--- a/doc/src/manual/cowboy_req.bindings.asciidoc
+++ b/doc/src/manual/cowboy_req.bindings.asciidoc
@@ -43,4 +43,5 @@ Bindings = cowboy_req:bindings(Req).
link:man:cowboy_req(3)[cowboy_req(3)],
link:man:cowboy_req:binding(3)[cowboy_req:binding(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)]
+link:man:cowboy_req:path_info(3)[cowboy_req:path_info(3)],
+link:man:cowboy_router(3)[cowboy_router(3)]
diff --git a/doc/src/manual/cowboy_req.host_info.asciidoc b/doc/src/manual/cowboy_req.host_info.asciidoc
index 77a4c11..ed613c6 100644
--- a/doc/src/manual/cowboy_req.host_info.asciidoc
+++ b/doc/src/manual/cowboy_req.host_info.asciidoc
@@ -45,4 +45,5 @@ HostInfo = cowboy_req:host_info(Req).
link:man:cowboy_req(3)[cowboy_req(3)],
link:man:cowboy_req:binding(3)[cowboy_req:binding(3)],
link:man:cowboy_req:bindings(3)[cowboy_req:bindings(3)],
-link:man:cowboy_req:path_info(3)[cowboy_req:path_info(3)]
+link:man:cowboy_req:path_info(3)[cowboy_req:path_info(3)],
+link:man:cowboy_router(3)[cowboy_router(3)]
diff --git a/doc/src/manual/cowboy_req.path_info.asciidoc b/doc/src/manual/cowboy_req.path_info.asciidoc
index d114640..d6d7541 100644
--- a/doc/src/manual/cowboy_req.path_info.asciidoc
+++ b/doc/src/manual/cowboy_req.path_info.asciidoc
@@ -45,4 +45,5 @@ PathInfo = cowboy_req:path_info(Req).
link:man:cowboy_req(3)[cowboy_req(3)],
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:host_info(3)[cowboy_req:host_info(3)],
+link:man:cowboy_router(3)[cowboy_router(3)]
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)]
diff --git a/doc/src/manual/cowboy_router.compile.asciidoc b/doc/src/manual/cowboy_router.compile.asciidoc
new file mode 100644
index 0000000..ab4eddc
--- /dev/null
+++ b/doc/src/manual/cowboy_router.compile.asciidoc
@@ -0,0 +1,53 @@
+= cowboy_router:compile(3)
+
+== Name
+
+cowboy_router:compile - Compile routes to the resources
+
+== Description
+
+[source,erlang]
+----
+compile(cowboy_router:routes()) -> cowboy_router:dispatch_rules()
+----
+
+Compile routes to the resources.
+
+Takes a human readable list of routes and transforms it
+into a form more efficient to process.
+
+== Arguments
+
+Routes::
+
+Human readable list of routes.
+
+== Return value
+
+An opaque dispatch rules value is returned. This value
+must be given to Cowboy as a middleware environment value.
+
+== Changelog
+
+* *1.0*: Function introduced.
+
+== Examples
+
+.Compile routes and start a listener
+[source,erlang]
+----
+Dispatch = cowboy_router:compile([
+ {'_', [
+ {"/", toppage_h, []},
+ {"/[...], cowboy_static, {priv_dir, my_example_app, ""}}
+ ]}
+]),
+
+{ok, _} = cowboy:start_clear(example, 100, [{port, 8080}], #{
+ env => #{dispatch => Dispatch}
+}).
+----
+
+== See also
+
+link:man:cowboy_router(3)[cowboy_router(3)]