@callback attach?(
  Xirsys.XTurn.Plugin.Allocation.t(),
  keyword()
) :: boolean()

Called once per allocation, at allocation time. Return false and no instance is created and nothing is added to this allocation's chain.

@callback handle_close(reason :: term(), state :: term()) :: :ok

Allocation teardown. Flush and close here. Passive only.

@callback handle_frame(
  payload :: binary(),
  Xirsys.XTurn.Plugin.Frame.t(),
  state :: term()
) ::
  {:ok, binary()} | :drop | {:error, term()} | {:ok, new_state :: term()}

Per-frame callback.

:active -> must return {:ok, binary} | :drop | {:error, term}. state is the

        immutable value from init/2; mutable state must be kept by the plugin
        itself (its own ETS table or process), because this is called
        concurrently from many processes.

:passive -> must return {:ok, new_state}. Runs in the instance process.

@callback handle_info(msg :: term(), state :: term()) :: {:ok, new_state :: term()}

Optional message handler for passive plugins.

A passive plugin's self() is the instance process, so Process.send_after(self(), ...) from init/2 or handle_frame/3 is the supported way to schedule periodic work.

@callback hooks() :: [direction()]

Which directions this plugin wants. Never called for others.

@callback init(
  Xirsys.XTurn.Plugin.Allocation.t(),
  keyword()
) :: {:ok, state :: term()} | :ignore

Called once per attached allocation. For :passive plugins this runs inside the instance process. Returning :ignore aborts attachment.

@callback mode() :: :active | :passive

Fixed for the lifetime of the module.