Function middleware for explicitly annotated definitions.

Basic Usage

Patterns.Middleware wraps functions that opt in with @middleware:

defmodule Blog do
  use Patterns.Middleware

  @middleware [Blog.Middlewares.AuthorizeEditor, Blog.Middlewares.RecordAuditLog]
  def create_post(attrs) do
    {:ok, attrs}
  end
end

Public API

• Entrypoints: @middleware annotations and run/4.
• Callback flow: process/2 and yield/2.
• get_private/3, put_private/3, update_private/4, and delete_private/2 store middleware metadata on the resolution.
• get_super/1, put_super/2, and update_super/2 inspect or replace the operation called after the last middleware yields.

Middleware Modules

Middleware modules can use Patterns.Middleware to import yield/2 and the super helpers, but they should still declare @behaviour Patterns.Middleware explicitly.

Middleware modules implement process/2. For middleware attached to a function, the first argument passed to process/2 is a list containing the arguments passed to the wrapped function. The second argument is a Patterns.Middleware.Resolution with metadata about the call.

For annotated functions, input is always the wrapped function argument list. For direct run/4 callers, input is whatever value was passed to run/4 or the previous yield/2.

process/2 must return {result, resolution}. Calling yield/2 continues to the next middleware, or to the wrapped function when there is no middleware left. Returning {result, resolution} without calling yield/2 halts the stack.

Return Values

Calling an annotated function returns only the wrapped result. Middleware callbacks, yield/2, and run/4 return {result, resolution}. If the wrapped function returns {:ok, post}, middleware receives and returns {{:ok, post}, resolution}.

defmodule Blog.Middlewares.RecordAuditLog do
  use Patterns.Middleware

  @behaviour Patterns.Middleware

  @impl Patterns.Middleware
  def process(args, resolution) do
    yield(args, resolution)
  end
end

Function Arguments

Calling Blog.create_post(%{title: "Hello"}) passes [%{title: "Hello"}] as args to the first middleware. Calling a wrapped function with multiple arguments, such as Blog.publish_post(123, force: true), passes [123, [force: true]].

resolution.args stores the original argument list. If middleware passes a changed value to yield/2, the changed value is passed to the rest of the stack, but resolution.args still refers to the original call.

Private Metadata

Middleware can use private metadata to communicate with later or earlier middleware in the same invocation. Because yield/2 returns the updated resolution, middleware can inspect private metadata written by later middleware.

def process(args, resolution) do
  {result, resolution} = yield(args, resolution)

  if get_private(resolution, :paginated?) do
    {{:paginated, result}, resolution}
  else
    {result, resolution}
  end
end

Stacking Middleware

Middleware can be attached to public or private functions. A stack can be declared as a list, or by repeating @middleware before the function:

@middleware Blog.Middlewares.AuthorizeEditor
@middleware Blog.Middlewares.RecordAuditLog
def publish_post(post_id) do
  {:ok, {:published, post_id}}
end

@middleware [Blog.Middlewares.AuthorizeEditor, Blog.Middlewares.RecordAuditLog]
defp persist_post(attrs) do
  {:ok, attrs}
end

@middleware is captured by the next def or defp. Middleware is tracked per function name and arity, not per clause, so an annotated clause wraps the whole function/arity. For functions with multiple clauses or default arguments, prefer annotating the function head. Different stacks for different clauses of the same function are rejected at compile time.

@middleware Blog.Middlewares.AuthorizeEditor
def publish_post(post_id, opts \ [])

def publish_post(post_id, opts) do
  {:ok, {post_id, opts}}
end

Yielding

Middleware continues the stack by calling yield/2. Passing a changed argument list to yield/2 calls the wrapped function with those changed arguments.

yield/2 returns {result, resolution} so middleware can inspect the return value and any resolution changes made by later middleware.

For function middleware, pass a list matching the wrapped function arity. If the final input cannot be matched to the wrapped arity, the generated wrapper raises.

Middleware runs in the order it is declared. In a stack like [AuthorizeEditor, RecordAuditLog], AuthorizeEditor runs first and RecordAuditLog runs inside it. When the innermost, rightmost middleware calls yield/2, Patterns.Middleware calls the original wrapped function.

Code before yield/2 runs before the rest of the stack and the wrapped function. Code after yield/2 runs after the wrapped function returns.

def process([attrs], resolution) do
  attrs = Map.update!(attrs, :title, &String.trim/1)

  case yield([attrs], resolution) do
    {{:ok, post}, resolution} ->
      {{:ok, Map.put(post, :audited, true)}, resolution}

    {error, resolution} ->
      {error, resolution}
  end
end

Super

The super function is the operation called when the last middleware yields. For functions wrapped with @middleware, super calls the original function body. Code that uses run/4 directly can provide a different super function.

{result, resolution} =
  Patterns.Middleware.run(stack, args, resolution, fn args, resolution ->
    call_existing_operation(args, resolution)
  end)

Middleware can replace super before continuing the stack:

def process(args, resolution) do
  resolution =
    put_super(resolution, fn args, resolution ->
      call_remote_operation(args, resolution)
    end)

  yield(args, resolution)
end

Middleware can also wrap super before continuing the stack. super returns the wrapped operation's raw result, not {result, resolution}. In this example, {:ok, result} is the wrapped operation result.

def process(args, resolution) do
  resolution =
    update_super(resolution, fn super ->
      fn args, resolution ->
        {:ok, result} = super.(args, resolution)
        {:ok, Map.put(result, :audited, true)}
      end
    end)

  {result, resolution} = yield(args, resolution)

  {result, resolution}
end

If multiple middleware wrap super before yielding, later middleware in the stack wrap the super function produced by earlier middleware.

Super changes affect only the current invocation because super is stored on the resolution.

Caveats

Halting

Middleware can also halt the stack by returning {result, resolution} without calling yield/2.

def process([user | _] = args, resolution) do
  if user.admin? do
    yield(args, resolution)
  else
    {{:error, :unauthorized}, resolution}
  end
end