|
|
@@ -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)]
|
Loïc Hoguin