# `Malla.Service.Interface`
[🔗](https://github.com/netkubes/malla/blob/main/lib/malla/service/interface.ex#L1)

Behaviour defining the public interface for Malla services.

Any module using `Malla.Service` will implement this behaviour,
providing the standard API functions for starting, stopping,
configuring, and querying the service readily available inserted
in service module.

Sice they live at ther service module, the service ID is already known
(it is the module itself) so you don't need to provide it.

You cannot override these functions, they are included here only for
documentation purposes. Use the mechanism detailed in `Malla.Service`
and `Malla.Plugin` to use Malla's plugin system.

# `child_spec`

```elixir
@callback child_spec(start_opts :: keyword()) :: Supervisor.child_spec()
```

Provides a standard supervisor spec to start the Service.

Restart will be _transient_ so supervisor will not restart it if we stop it with `c:stop/0`.
Shutdown will be _infinity_ to allow plugins to stop.

# `get_config`

```elixir
@callback get_config() :: keyword() | :unknown
```

Gets current service configuration, or `:unknown` if not started,

# `get_status`

```elixir
@callback get_status() :: Malla.Service.running_status() | :unknown
```

Gets current service configurartion, or `:unknown` if not started.

# `malla_cb_in`

```elixir
@callback malla_cb_in(fun :: atom(), args :: list(), opts :: keyword()) :: any()
```

This function is called from functions like `Malla.remote/3` to call services
on remote nodes.

Once it receives the call:
* It sets process global leader to :user so that responses are not sent back to caller.
* It sets current module as current service in process's dictionary.
* It calls callback function `c:Malla.Plugins.Base.service_cb_in/3`.

# `reconfigure`

```elixir
@callback reconfigure(config :: keyword()) :: :ok | {:error, term()}
```

Reconfigures the service in real time. See `Malla.Service.reconfigure/2`.

# `set_admin_status`

```elixir
@callback set_admin_status(
  status :: :active | :pause | :inactive,
  reason :: atom()
) :: :ok | {:error, term()}
```

Changes service running status. See `Malla.Service.set_admin_status/3`.

# `start_link`

```elixir
@callback start_link() :: {:ok, pid()} | {:error, term()}
```

Starts the service. See `Malla.Service.start_link/2`.

# `start_link`

```elixir
@callback start_link(start_opts :: keyword()) :: {:ok, pid()} | {:error, term()}
```

Starts the service. See `Malla.Service.start_link/2`.

# `stop`

```elixir
@callback stop() :: :ok | {:error, term()}
```

Stops the service. See `Malla.Service.stop/1`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*