From a1b52494a54ede247a5eb0448a94aeb76d61f74e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Thu, 22 Dec 2016 12:53:21 +0100 Subject: Update the cowboy_router manual --- doc/src/manual/cowboy_req.binding.asciidoc | 3 +- doc/src/manual/cowboy_req.bindings.asciidoc | 3 +- doc/src/manual/cowboy_req.host_info.asciidoc | 3 +- doc/src/manual/cowboy_req.path_info.asciidoc | 3 +- doc/src/manual/cowboy_router.asciidoc | 91 +++++++++++++++++++-------- doc/src/manual/cowboy_router.compile.asciidoc | 53 ++++++++++++++++ 6 files changed, 125 insertions(+), 31 deletions(-) create mode 100644 doc/src/manual/cowboy_router.compile.asciidoc (limited to 'doc/src/manual') 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)] -- cgit v1.2.3