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

View Source

Defines the behaviour for Raxol plugins.

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

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 plugin manager.

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.

This callback allows plugins to register their commands with the command registry. Each command is specified as a tuple containing:

  • The command name as an atom
  • The function to handle the command
  • The arity of the handler function

Returns

  • List of command specifications in the format [{name_atom, function_atom, arity_integer}]

Examples

def get_commands do
  [
    {:do_something, :handle_do_something_command, 2},
    {:process_data, :handle_process_data_command, 1}
  ]
end

Notes

  • The command name will be converted to a string when registered
  • The plugin module itself will be used as the namespace
  • Commands 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 plugin manager.

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 plugin manager.

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.