Honeybee v0.2.2 Honeybee View Source
Defines a Honeybee router.
Provides macros for routing http-requests.
Hello world example:
defmodule MyApplication.MyRouter do
use Honeybee
defmodule Handlers do
def init(opts), do: opts
def call(conn, opts), do: apply(Handlers, Keyword.fetch!(opts, :call), [conn, opts])
def hello_world(conn, _opts) do
IO.puts("Hello World!")
conn
end
end
get "/hello/world" do
plug Handlers, call: :hello_world
end
Honeybee provides routing capabilities to Plug apps. Honeybee heavily relies on the concept of plug pipelines, in order to provide a useful and intuitive api to developers.
Link to this section Summary
Functions
Declares a new plug composition with name
, containing plug_pipeline
An alias for match "CONNECT"
An alias for match "DELETE"
An alias for match "GET"
An alias for match "HEAD"
Adds a route matching http_method
requests on path
, containing plug_pipeline
An alias for match "OPTIONS"
An alias for match "PATCH"
Declares a plug
An alias for match "POST"
An alias for match "PUT"
Declares an isolated scope with the provided path
Link to this section Functions
composition(name, plug_pipeline) View Source (macro)
Declares a new plug composition with name
, containing plug_pipeline
Compositions allow you to compose plug_pipelines in-place, composition/2
uses Plug.Builder
under the hood.
A compossition compiles into a private function named name
, meaning you can plug it as any other function.
Inside compositions, the opts
variable is available.
The opts
var contains the options with which the composition was plugged.
Inside the composition you can manipulate the opts variable however you like.
Currently compositions evaluate options runtime,
which can be very slow when composed plugs have expensive init/1
methods.
In such cases, consider not using the composition method.
In a future release an option might be provided to resolve options using the opts
at compile-time.
Examples
composition :example do
plug :local_example1, opts
plug PluggableExmapleModule
end
connect(path, list) View Source (macro)
An alias for match "CONNECT"
delete(path, list) View Source (macro)
An alias for match "DELETE"
get(path, list) View Source (macro)
An alias for match "GET"
head(path, list) View Source (macro)
An alias for match "HEAD"
match(http_method, path, plug_pipeline) View Source (macro)
Adds a route matching http_method
requests on path
, containing plug_pipeline
.
When an incoming request hits a Honeybee router, the router attempts to match the request against the routes defined in the router. The router will only invoke the first route that matches the incoming request. The priority of the route is determined by the order of the match statements in the router.
When a match is made, the scoped pipelines for the route are invoked, then the route pipeline is invoked.
Honeybee will always match exactly one route to the request.
To provide a fallback route, use match _, "*" do ... end
.
Honeybee inserts a default fallback of this kind at the bottom of the route table which raises an error.
Method
The http_method
can be any of the following literals:
"HEAD"
(head/2
)"GET"
(get/2
)"POST"
(post/2
)"PUT"
(put/2
)"PATCH"
(patch/2
)"CONNECT"
(connect/2
)"OPTIONS"
(options/2
)"DELETE"
(delete/2
)
For each method literal, a shorthand method exists (see above.)
http_method
can also be a pattern, for example _
will match any http method.
Guards are currently not supported, but may receive support in future versions of Honeybee.
Path
path
is a pattern used to match incoming requests.
Paths can be any string literal, and also have parameter and glob support.
All parameters and globs are named.
Resolved parameters and globs are available using their name as key
in the :path_params
map in the Plug.Conn
struct.
A path parameter is declared using ":"
and a path glob is declared using "*"
"/api/v1/examples/:id"
will match requests of the form "/api/v1/examples/1"
,
resulting in %Plug.Conn{path_params: %{ "id" => "1" }}
.
"/api/v1/examples/*glob"
will match requests of the form "/api/v1/examples/something/somethingelse"
,
resulting in %Plug.Conn{path_params: %{ "glob" => ["something", "somethingelse"] }}
Glob and variable matches can be used in combination, for example "/api/v1/examples/:id/*glob"
.
They can also be applied on partial strings such as "/api/v1/examples/example-id-:id/example-*glob"
Since globs match the remainder of the requested path, nothing further can be matched after specifying a glob.
Path parameters are available to the plugs of the scoped pipeline as well as the route pipeline.
Plug pipeline
The plug_pipeline
contains the route pipeline, declared as a do-block of plugs.
Plugs in the route pipeline are invoked in order.
Examples
Using the get method to specify a route.
defmodule ExampleApp.Router do
use Honeybee
get "/api/v1/examples/:id" do
plug ExampleApp.Routes.Example, call: :get
end
end
Using the match method to specify the same route as above.
defmodule ExampleApp.Router do
use Honeybee
match "GET", "/api/v1/examples/:id" do
plug ExampleApp.Routes.Example, call: :get
end
end
options(path, list) View Source (macro)
An alias for match "OPTIONS"
patch(path, list) View Source (macro)
An alias for match "PATCH"
plug(plug, opts \\ []) View Source (macro)
Declares a plug.
post(path, list) View Source (macro)
An alias for match "POST"
put(path, list) View Source (macro)
An alias for match "PUT"
scope(path \\ "", list) View Source (macro)
Declares an isolated scope with the provided path
.
Scopes are used to encapsulate and isolate any enclosed routes and plugs.
Calling plug/2
inside a scope will not affect any routes declared outside that scope.
Scopes take an optional base path as the first argument.
Honeybee wraps the top level of the module in whats known as the root scope.
Scopes can be nested.
Examples
In the following example,
an http request "GET"
on "/"
will invoke RootHandler.call/2
.
An http request "GET"
on "/api/v1"
will invoke ExamplePlug.call/2
followed by V1Handler.call/2
defmodule ExampleApp.Router do
use Honeybee
scope "/api" do
plug ExamplePlug
get "/v1" do
plug V1Handler, call: :get
end
end
get "/" do
plug RootHandler, call: :get
end
end