Generic middleware pipeline for query execution and schema discovery hooks.

Each middleware module implements init/1 and call/2, following the standard Plug pattern:

defmodule MyApp.AuditPlug do
  def init(opts), do: opts

  def call(payload, opts) do
    {:cont, payload}   # continue to next middleware
    # or
    {:halt, "reason"}  # stop pipeline, Lotus returns {:error, reason}
  end
end

Pipeline Events

:vars is the map of bound query variables, by name, after defaults and caller-supplied values are merged (%{"start_date" => "2026-01-01"}). It is %{} for a raw statement run through Lotus.run_statement/3. A plug can enforce rules on the values a caller picked (date-range limits, tenant checks) without parsing the statement.

Discovery event ordering

Discovery calls (Lotus.list_schemas/2, list_tables/2, describe_table/3, list_relations/2) fire two events each:

1. The kind-specific event (:after_list_schemas, :after_list_tables, :after_describe_table, or :after_list_relations) — receives the kind-specific payload with a key matching the returned value.
2. The unified :after_discover event — receives a uniform payload %{kind:, source:, result:, context:} so a single middleware module can handle every discovery kind by dispatching on :kind.

If any middleware in either phase halts, later middleware do not run and the caller receives {:error, reason}.

Configuration

config :lotus,
  middleware: %{
    before_query: [
      {MyApp.AccessControlPlug, []},
      {MyApp.QueryAuditPlug, [repo: MyApp.AuditRepo]}
    ],
    after_query: [
      {MyApp.QueryAuditPlug, [repo: MyApp.AuditRepo]}
    ],
    after_list_tables: [
      {MyApp.TableFilterPlug, []}
    ]
  }

Context

A :context key carries opaque user data (e.g. the current user) through to middleware. Lotus never inspects this value.