Conveniences for building pipelines.

defmodule MyApp do
  use Pluggable.StepBuilder

  step SomeLibrary.Logger
  step :hello, upper: true

  # A function from another module can be plugged too, provided it's
  # imported into the current module first.
  import AnotherModule, only: [interesting_step: 2]
  step :interesting_step

  def hello(token, opts) do
    body = if opts[:upper], do: "WORLD", else: "world"
    send_resp(token, 200, body)
  end
endcopy

Multiple steps can be defined with the step/2 macro, forming a pipeline. The steps in the pipeline will be executed in the order they've been added through the step/2 macro. In the example above, SomeLibrary.Logger will be called first and then the :hello function step will be called on the resulting token.

Options

When used, the following options are accepted by Pluggable.StepBuilder:

• :init_mode - the environment to initialize the step's options, one of :compile or :runtime. Defaults :compile.

• :log_on_halt - accepts the level to log whenever the request is halted

• :copy_opts_to_assign - an atom representing an assign. When supplied, it will copy the options given to the Step initialization to the given token assign

step behaviour

Internally, Pluggable.StepBuilder implements the Pluggable behaviour, which means both the init/1 and call/2 functions are defined.

By implementing the Pluggable API, Pluggable.StepBuilder guarantees this module is a pluggable step and can be run via Pluggable.run/3 or used as part of another pipeline.

Overriding the default Pluggable API functions

Both the init/1 and call/2 functions defined by Pluggable.StepBuilder can be manually overridden. For example, the init/1 function provided by Pluggable.StepBuilder returns the options that it receives as an argument, but its behaviour can be customized:

defmodule StepWithCustomOptions do
  use Pluggable.StepBuilder
  step SomeLibrary.Logger

  def init(opts) do
    opts
  end
endcopy

The call/2 function that Pluggable.StepBuilder provides is used internally to execute all the steps listed using the step macro, so overriding the call/2 function generally implies using super in order to still call the step chain:

defmodule StepWithCustomCall do
  use Pluggable.StepBuilder
  step SomeLibrary.Logger
  step SomeLibrary.AddMeta

  def call(token, opts) do
    token
    |> super(opts) # calls SomeLibrary.Logger and SomeLibrary.AddMeta
    |> assign(:called_all_steps, true)
  end
endcopy

Halting a pluggable step pipeline

A pluggable step pipeline can be halted with Pluggable.Token.halt/1. The builder will prevent further steps downstream from being invoked and return the current token. In the following example, the SomeLibrary.Logger step never gets called:

defmodule StepUsingHalt do
  use Pluggable.StepBuilder

  step :stopper
  step SomeLibrary.Logger

  def stopper(token, _opts) do
    halt(token)
  end
endcopy