Pluggable

Pluggable helps to define Plug like pipelines but with arbitrary tokens. The library comes with almost exact copies of the module Plug and Plug.Builder. However, instead of passing around a %Plug.Conn{} struct, this library passes around a Token you define in your project.

Credits

Most of the code in this module was copied from the :plug library so credits go to the creators and maintainers of :plug.

Installation

The package can be installed by adding pluggable to your list of dependencies in mix.exs:

def deps do
  [
    {:pluggable, "~> 1.0"}
  ]
end

Usage

To use this library, you first have to define your token. Once that is done, use Pluggable.StepBuilder to build steps and pipelines.

Deriving Pluggable.Token

The easiest way to define a token is to create a module which derives Pluggable.Token and defines a struct which, among others defines the keys:

:halted - the boolean status on whether the pipeline was halted
:assigns - shared user data as a map

Example:

defmodule MyPipeline.Token do
  @derive Pluggable.Token
  defstruct [
    halted: false,
    assigns: %{},
    # other state
  ]
end

If the fields holding these two states are named differently, pass the fields as options to @derive:

defmodule MyPipeline.Token do
  @derive {Pluggable.Token, halted_key: :stopped, assigns_key: :shared_state}
  defstruct [
    stopped: false,
    shared_state: %{},
    # other state
  ]
end

Implementing Pluggable.Token

Pluggable.Token can be implemented. The following is the default implementation when deriving Pluggable.Token

  defmodule MyPipeline.Token do
    defstruct [
      halted: nil,
      assigns: %{},
      # other state
    ]
  end

  defimpl Pluggable.Token, for: MyPipeline.Token do
    def halted?(token), do: token.halted

    def halt(token), do: %{token | halted: true}

    def assign(%MyPipeline.Token{assigns: assigns} = token, key, value) when is_atom(key) do
      %{token | assigns: Map.put(assigns, key, value)}
    end
  end

Building Pipelines

Pluggable.StepBuilder works just like Plug.Builder. See the module documentation for instructions.

Code Formatting

When using the Pluggable.StepBuilder, you might want to format the usage of the step macro without parens. To configure the formatter not to add parens, add this to your .formatter.exs:

# .formatter.exs
[
  import_deps: [:pluggable]
]

mruoss / pluggable