trails (trails v3.0.0)
View SourceTrails main interface.
Use the functions provided in this module to interact with trails.
Summary
Types
Metadata associated with each HTTP method.
HTTP Method.
Trail specification.
Trail specifications (With or without metadata).
API
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.
Returns the list of host matches for a given server.
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.
Returns the list of known servers.
Equivalent to compile([{'_', Trails}]).
Store the given list of trails.
Store the given list of trails for a particular server.
Equivalent to trail(PathMatch, ModuleHandler, Options, #{}, []).
Equivalent to trail(PathMatch, ModuleHandler, Options, MetaData, []).
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.
Types
-nominal metadata(X) :: #{method() => X}.
Metadata associated with each HTTP method.
-nominal method() :: get | put | post | delete | patch | head | options.
HTTP Method.
-opaque trail()
Trail specification.
-type trails() :: [trail() | route_path()].
Trail specifications (With or without metadata).
API
-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.
Gets the handler from the given trail.
-spec host_matches(ranch:ref()) -> [route_match()].
Returns the list of host matches for a given server.
Gets the metadata from the given trail.
Gets the options from the given trail.
-spec path_match(trail()) -> route_match().
Gets the path_match from the given trail.
Fetch the trail that matches with the given path.
-spec retrieve(HostMatch :: route_match(), PathMatch :: string()) -> trail() | notfound.
Fetch the trail that matches with the given host and path.
-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()].
Returns the list of known servers.
-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.
Store the given list of trails for a particular server.
-spec trail(route_match(), module()) -> trail().
Equivalent to trail(PathMatch, ModuleHandler, [], #{}, []).
-spec trail(route_match(), module(), term()) -> trail().
Equivalent to trail(PathMatch, ModuleHandler, Options, #{}, []).
-spec trail(route_match(), module(), term(), map()) -> trail().
Equivalent to trail(PathMatch, ModuleHandler, Options, MetaData, []).
-spec trail(route_match(), module(), term(), 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.
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.
Exported from `cowboy_router`
-nominal route_match() :: '_' | iodata().
-nominal route_path() :: {Path :: route_match(), Handler :: module(), Opts :: term()} | {Path :: route_match(), cowboy:fields(), Handler :: module(), Opts :: term()}.