View Source trails (trails v2.3.1)

Trails main interface. Use the functions provided in this module to inteact with trails.

Link to this section Summary

Functions

Retrieves all stored trails.
Retrieves all stored trails for the given HostMatch
Retrieves all stored trails for the given Server and HostMatch
Get api_root env param value if any, empty otherwise.
Set api_root env param to the given Path.
Compiles the given list of trails routes, also compatible with cowboy routes.
Gets the constraints from the given trail.
Gets the handler from the given trail.
Gets the metadata from the given trail.
Gets the options from the given trail.
Gets the path_match from the given trail.
Fetch the trail that matches with the given path.
Fetch the trail that matches with the given host and path.
Fetch the trail that matches with the given server and host and path.
Store the given list of trails.
This function allows you to add additional information to the cowboy handler, such as: resource path, handler module, options and metadata. Normally used to document handlers.
This function allows you to define the routes on each resource handler, instead of defining them all in one place (as you're required to do with cowboy). Your handler must implement the callback trails_handler:trails/0 and return the specific routes for that handler. That callback is invoked for each given module and then the results are concatenated.

Link to this section Types

-type metadata(X) :: #{method() => X}.
-type method() :: get | put | post | delete | patch | head | options.
-type route_match() :: '_' | iodata().
-type route_path() ::
    {Path :: route_match(), Handler :: module(), Opts :: any()} |
    {Path :: route_match(), cowboy:fields(), Handler :: module(), Opts :: any()}.
-type route_rule() ::
    {Host :: route_match(), Paths :: [route_path()]} |
    {Host :: route_match(), cowboy:fields(), Paths :: [route_path()]}.
-opaque trail()
-type trails() :: [trail() | route_path()].

Link to this section Functions

-spec all() -> [trail()].
Retrieves all stored trails.
-spec all(HostMatch :: route_match()) -> [trail()].
Retrieves all stored trails for the given HostMatch
-spec all(Server :: ranch:ref(), HostMatch :: route_match()) -> [trail()].
Retrieves all stored trails for the given Server and HostMatch
-spec api_root() -> string().
Get api_root env param value if any, empty otherwise.
-spec api_root(string()) -> ok.
Set api_root env param to the given Path.
-spec compile([{Host :: route_match(), Trails :: trails()}]) -> cowboy_router:dispatch_rules().
Compiles the given list of trails routes, also compatible with cowboy routes.
-spec constraints(trail()) -> cowboy:fields().
Gets the constraints from the given trail.
-spec handler(trail()) -> module().
Gets the handler from the given trail.
-spec host_matches(ranch:ref()) -> [route_match()].
-spec metadata(trail()) -> map().
Gets the metadata from the given trail.
-spec options(trail()) -> any().
Gets the options from the given trail.
-spec path_match(trail()) -> route_match().
Gets the path_match from the given trail.
-spec retrieve(PathMatch :: string()) -> trail() | notfound.
Fetch the trail that matches with the given path.
Link to this function

retrieve(HostMatch, PathMatch)

View Source
-spec retrieve(HostMatch :: route_match(), PathMatch :: string()) -> trail() | notfound.
Fetch the trail that matches with the given host and path.
Link to this function

retrieve(Server, HostMatch, PathMatch)

View Source
-spec retrieve(Server :: ranch:ref(), HostMatch :: route_match(), PathMatch :: string()) ->
            trail() | notfound.
Fetch the trail that matches with the given server and host and path.
-spec servers() -> [ranch:ref()].
Link to this function

single_host_compile(Trails)

View Source
-spec single_host_compile(trails()) -> cowboy_router:dispatch_rules().

Equivalent to compile([{'_', Trails}]).

-spec store(Trails :: trails() | [{HostMatch :: route_match(), Trails :: trails()}]) -> ok.
Store the given list of trails.
-spec store(Server :: ranch:ref(),
      Trails :: trails() | [{HostMatch :: route_match(), Trails :: trails()}]) ->
         ok.
Link to this function

trail(PathMatch, ModuleHandler)

View Source
-spec trail(route_match(), module()) -> trail().

Equivalent to trail(PathMatch, ModuleHandler, [], #{}, []).

Link to this function

trail(PathMatch, ModuleHandler, Options)

View Source
-spec trail(route_match(), module(), any()) -> trail().

Equivalent to trail(PathMatch, ModuleHandler, Options, #{}, []).

Link to this function

trail(PathMatch, ModuleHandler, Options, MetaData)

View Source
-spec trail(route_match(), module(), any(), map()) -> trail().

Equivalent to trail(PathMatch, ModuleHandler, Options, MetaData, []).

Link to this function

trail(PathMatch, ModuleHandler, Options, MetaData, Constraints)

View Source
-spec trail(route_match(), module(), any(), map(), cowboy:fields()) -> trail().
This function allows you to add additional information to the cowboy handler, such as: resource path, handler module, options and metadata. Normally used to document handlers.
-spec trails(module() | [module()] | {module(), map()} | [{module(), map()}]) -> trails().
This function allows you to define the routes on each resource handler, instead of defining them all in one place (as you're required to do with cowboy). Your handler must implement the callback trails_handler:trails/0 and return the specific routes for that handler. That callback is invoked for each given module and then the results are concatenated.