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

Link to this macro

composition(name, plug_pipeline) View Source (macro)
composition(atom(), term()) :: nil

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
Link to this macro

connect(path, list) View Source (macro)
connect(String.t(), term()) :: nil

An alias for match "CONNECT"

Link to this macro

delete(path, list) View Source (macro)
delete(String.t(), term()) :: nil

An alias for match "DELETE"

Link to this macro

get(path, list) View Source (macro)
get(String.t(), term()) :: nil

An alias for match "GET"

Link to this macro

head(path, list) View Source (macro)
head(String.t(), term()) :: nil

An alias for match "HEAD"

Link to this macro

match(http_method, path, plug_pipeline) View Source (macro)
match(String.t() | Honeybee.Utils.Types.Var.t(), String.t(), term()) :: nil

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:

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
Link to this macro

options(path, list) View Source (macro)
options(String.t(), term()) :: nil

An alias for match "OPTIONS"

Link to this macro

patch(path, list) View Source (macro)
patch(String.t(), term()) :: nil

An alias for match "PATCH"

Link to this macro

plug(plug, opts \\ []) View Source (macro)
plug(atom() | Honeybee.Utils.Types.Alias.t(), keyword()) :: Honeybee.Plug.t()

Declares a plug.

For documentation regarding plug/2 go to Plug

Link to this macro

post(path, list) View Source (macro)
post(String.t(), term()) :: nil

An alias for match "POST"

Link to this macro

put(path, list) View Source (macro)
put(String.t(), term()) :: nil

An alias for match "PUT"

Link to this macro

scope(path \\ "", list) View Source (macro)
scope(String.t(), term()) :: nil

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