Raxol.Core.Runtime.Plugins.Plugin behaviour (Raxol v0.3.0)

View Source

Defines the behaviour for Raxol plugins.

Plugins must implement this behaviour to be loaded and managed by the PluginManager.

Summary

Callbacks

Called when the plugin is disabled.

Called when the plugin is enabled after being disabled.

Optional callback to filter or react to system events before they reach the application.

Optional callback to declare commands provided by the plugin.

Optional callback to handle commands delegated by the PluginManager.

Called when the plugin is first initialized.

Called when the plugin is terminated (e.g., during shutdown or unload).

Types

command()

@type command() :: atom() | tuple()

config()

@type config() :: map()

event()

@type event() :: Raxol.Core.Runtime.Events.Event.t() | term()

state()

@type state() :: map()

Callbacks

disable(state)

@callback disable(state :: state()) :: {:ok, state()} | {:error, any()}

Called when the plugin is disabled.

Should return {:ok, new_state} or {:error, reason}.

enable(state)

@callback enable(state :: state()) :: {:ok, state()} | {:error, any()}

Called when the plugin is enabled after being disabled.

Should return {:ok, new_state} or {:error, reason}.

filter_event(event, state)

@callback filter_event(event :: event(), state :: state()) ::
  {:ok, event()} | :halt | any()

Optional callback to filter or react to system events before they reach the application.

Return {:ok, event} to pass the event through (potentially modified). Return :halt to stop the event from propagating further. Return any other value to indicate an error.

get_commands()

@callback get_commands() :: [{atom(), atom(), non_neg_integer()}]

Optional callback to declare commands provided by the plugin.

Should return a list of {name_atom, function_atom, arity_integer} tuples. Example: [{:do_something, :handle_do_something_command, 2}] The name_atom will be converted to a string command name. The plugin module itself will be used as the namespace. These will be registered in the CommandRegistry via CommandHelper.

handle_command(command, args, state)

@callback handle_command(
  command :: command(),
  args :: list(),
  state :: state()
) :: {:ok, state(), any()} | {:error, any(), state()}

Optional callback to handle commands delegated by the PluginManager.

Should return {:ok, new_state, result} or {:error, reason, new_state}. The result can be sent back to the original command requester if needed.

init(config)

@callback init(config :: config()) :: {:ok, state()} | {:error, any()}

Called when the plugin is first initialized.

Should return {:ok, initial_state} or {:error, reason}. The initial_state will be managed by the PluginManager.

terminate(reason, state)

@callback terminate(reason :: any(), state :: state()) :: any()

Called when the plugin is terminated (e.g., during shutdown or unload).

Allows the plugin to perform cleanup. The return value is ignored.