@callback plugin_config(Malla.id(), config :: keyword()) ::
  :ok | {:ok, config :: keyword()} | {:error, term()}

Optional callback called before service's start. It allows the plugin to check and, if needed, modify the config.

See Configuration.

Top level plugins are called first, so they could update the config for other plugins they declared as dependants.

@callback plugin_config_merge(Malla.id(), old_config :: keyword(), update :: keyword()) ::
  :ok | {:ok, merged_config :: keyword()} | {:error, term()}

Optional callback called when merging configuration updates.

This callback is invoked during service initialization (when runtime config is merged with static config) and when Malla.Service.reconfigure/2 is used.

By default, if a plugin doesn't implement this callback, configurations are deep-merged automatically. Implement this callback when you need custom merge logic for your plugin's configuration keys.

Top-level plugins (service itself, then declared plugins) are called first, allowing higher-level plugins to process configuration before lower-level ones.

@callback plugin_module(service :: Malla.Service.t()) :: Macro.t()

Optional compile-time callback that injects code into the service module.

Unlike the other plugin callbacks, plugin_module/1 is invoked while the service module is being compiled (via a @before_compile hook), not at runtime. For each plugin in the service's Malla.Service.t/0 plugin chain, if plugin_module/1 is exported, its return value (a quoted expression) is spliced into the body of the service module.

This allows a plugin to generate functions, module attributes, or even nested submodules that become part of the service module itself, parameterized by the service's compile-time data: id, plugin_chain, static config, the resolved callbacks map, etc.

The callback is invoked once per service compilation, in plugin chain order (top-level plugins first, Malla.Plugins.Base last). It runs after the callback dispatch logic has been generated, so service.callbacks is fully populated.

Because the injected code lives on the service module, it is visible across the cluster through the same virtual-module mechanism used for remote calls.

Example

defmodule MyApp.MetricsPlugin do
  use Malla.Plugin

  def plugin_module(service) do
    prefix = "malla." <> Atom.to_string(service.id)

    quote do
      def metric_prefix, do: unquote(prefix)
    end
  end
end

After the service compiles, MyService.metric_prefix/0 is a regular function on the service module.

@callback plugin_start(Malla.id(), config :: keyword()) ::
  :ok | {:ok, [start_opt()]} | {:error, term()}

Optional callback called during service's start.

Plugins will be started on service init, starting with lower-level plugins up to the service itself (that is also a Plugin). See Lifecycle for details.

Plugin can return a child specification, in this case a Supervisor will be started with the specified children.

The service will monitor this supervisor, and, if it fails, the whole service will be marked as 'failed' and we will retry to start it, calling this function again.

@callback plugin_stop(Malla.id(), config :: keyword()) :: :ok | {:error, term()}

Optional callback called if service needs to 'stop' this plugin.

This can happen if we mark the service as inactive. Top-level plugins will be stopped first starting with the service itself (that is also a Plugin), up to lower level plugins in order.

It can also happen if this plugin is removed from the service.

After calling this function, service will stop the started children supervisor, if it was defined and it is already running.

@callback plugin_updated(
  Malla.id(),
  old_config :: keyword(),
  new_config :: keyword()
) :: :ok | {:ok, [updated_opts()]} | {:error, term()}

Optional callback called after service's reconfiguration. (See Malla.Service.reconfigure/2). You are presented with old and new config, and you have the chance to restart the plugin.

Lower level plugins are called first.