# Getting Started with Malla

```elixir
# Check hex.pm/packages/malla for the latest version
Mix.install([{:malla, "~> 0.1"}])
```

## Introduction

Welcome to Malla! This tutorial will guide you through building distributed services with a plugin-based architecture. You'll learn how to:

1. Create a simple service with an API
2. Extract functionality into reusable plugins
3. Compose plugins to modify behavior
4. Dynamically reconfigure services at runtime

Let's build a simple calculator service to demonstrate these concepts.

## Part 1: Creating a Basic Service

First, let's create a simple calculator service that can add numbers.

```elixir
defmodule Calculator do
  use Malla.Service

  # A plain function - other nodes can call it with Malla.remote/4
  def add(a, b) do
    a + b
  end

  # Callback that participates in the plugin chain
  defcb calculate(:add, a, b), do: {:ok, a + b}
end

# Start the service
{:ok, _pid} = Calculator.start_link([])

# Test the API
IO.puts("2 + 3 = #{Calculator.add(2, 3)}")

# Test the callback
{:ok, result} = Calculator.calculate(:add, 5, 7)
IO.puts("5 + 7 = #{result}")
```

Great! We have a working service. The `calculate/3` callback is special - it participates in a **callback chain** where plugins can intercept and modify behavior.

## Part 2: Moving Functionality into a Plugin

Now let's extract the addition logic into a reusable plugin. This makes it easier to share functionality across multiple services.

```elixir
defmodule AdditionPlugin do
  use Malla.Plugin

  # This callback will be part of the chain
  defcb calculate(:add, a, b), do: {:ok, a + b}

  # If we don't support this, let other plugins process it
  defcb calculate(_, _, _), do: :cont
end

# Create a new calculator that uses the plugin
defmodule CalculatorV2 do
  use Malla.Service, plugins: [AdditionPlugin]

  # The service doesn't need to implement calculate/3
  # The plugin handles it!
end

# Start and test
{:ok, _pid} = CalculatorV2.start_link([])
{:ok, result} = CalculatorV2.calculate(:add, 10, 20)
IO.puts("Using plugin: 10 + 20 = #{result}")
```

Notice how the service became simpler? The plugin now handles the calculation logic.

## Part 3: Adding More Functionality with Another Plugin

Let's add multiplication by creating another plugin. This demonstrates how plugins **compose** together.

```elixir
defmodule MultiplicationPlugin do
  use Malla.Plugin

  defcb calculate(:multiply, a, b), do: {:ok, a * b}
  defcb calculate(_, _, _), do: :cont
end

# Create a calculator with both plugins
defmodule CalculatorV3 do
  use Malla.Service,
    plugins: [
      AdditionPlugin,
      MultiplicationPlugin
    ]
end

# Start and test both operations
{:ok, _pid} = CalculatorV3.start_link([])

{:ok, sum} = CalculatorV3.calculate(:add, 8, 4)
IO.puts("8 + 4 = #{sum}")

{:ok, product} = CalculatorV3.calculate(:multiply, 8, 4)
IO.puts("8 × 4 = #{product}")
```

### How the Callback Chain Works

Only the modules that define `calculate/3` are in its chain, in the order of the plugin chain. `CalculatorV3` does not define it, so it is not asked. Plugins that do not depend on each other are called in the order of the `plugins:` list, so `AdditionPlugin` comes first. You can see the chain:

```elixir
Malla.Service.get_callbacks(CalculatorV3, :calculate)
# [{{:calculate, 3}, [{AdditionPlugin, :calculate}, {MultiplicationPlugin, :calculate}]}]
```

When you call `CalculatorV3.calculate(:multiply, 8, 4)`, here's what happens:

1. **AdditionPlugin** checks first - the operation is `:multiply`, so it returns `:cont`
2. **MultiplicationPlugin** checks - it handles `:multiply` and returns `{:ok, 32}` ✓
3. **Chain stops** - the result is returned to the caller

The chain walks from top to bottom until a plugin returns something other than `:cont`. If the last module of a chain also returned `:cont`, that raw `:cont` would be the result.

## Part 4: Plugin Dependencies and Chain Ordering

A plugin can declare dependencies on other plugins using `plugin_deps`. This has two effects:

1. **Automatic inclusion** - dependent plugins are pulled in transitively, so the service only needs to list the top-level plugin.
2. **Chain ordering** - the dependent plugin is placed **above** its dependencies in the callback chain, so it gets called first.

Let's create a `LoggingPlugin` that depends on both math plugins and logs every operation to screen before letting them handle it.

```elixir
defmodule LoggingPlugin do
  use Malla.Plugin,
    plugin_deps: [AdditionPlugin, MultiplicationPlugin]

  defcb calculate(operation, a, b) do
    # This runs BEFORE the math plugins because LoggingPlugin
    # is above them in the chain (it depends on them).
    IO.puts(">> calculate(#{operation}, #{a}, #{b})")

    # Return :cont to let the math plugins handle the actual computation
    :cont
  end
end

# We only need to list LoggingPlugin - its dependencies
# (AdditionPlugin and MultiplicationPlugin) are included automatically.
defmodule CalculatorV4 do
  use Malla.Service,
    plugins: [LoggingPlugin]
end

# Start and test - watch the logs!
{:ok, _pid} = CalculatorV4.start_link([])

{:ok, sum} = CalculatorV4.calculate(:add, 6, 7)
IO.puts("= #{sum}\n")

{:ok, product} = CalculatorV4.calculate(:multiply, 6, 7)
IO.puts("= #{product}")
```

### Chain Order with Dependencies

The plugin chain of `CalculatorV4` is `CalculatorV4 → LoggingPlugin → AdditionPlugin → MultiplicationPlugin → Malla.Plugins.Base` (the dependencies of a plugin are placed in the order of its `plugin_deps`). `CalculatorV4` itself does not define `calculate/3`, so it is skipped. For `CalculatorV4.calculate(:multiply, 6, 7)`:

1. **LoggingPlugin** - prints `>> calculate(multiply, 6, 7)`, returns `:cont`
2. **AdditionPlugin** - the operation is not `:add`, returns `:cont`
3. **MultiplicationPlugin** - handles `:multiply`, returns `{:ok, 42}`
4. **Chain stops** - the result is returned

By declaring `plugin_deps`, we told Malla that LoggingPlugin sits above the math plugins. No need to manually order the `plugins:` list. You can print the order with `CalculatorV4.service().plugin_chain`.

## Part 5: Extending Behavior Without Modifying Existing Plugins

A key benefit of the plugin architecture is that you can add new behavior **without touching existing code**. Let's create a `FloatPlugin` that converts all results to floats. It depends on `LoggingPlugin`, so it sits above everything in the chain.

```elixir
defmodule FloatPlugin do
  use Malla.Plugin,
    plugin_deps: [LoggingPlugin, MultiplicationPlugin, AdditionPlugin]

  defcb calculate(operation, a, b) do
    # Convert arguments to floats before passing them down the chain
    {:cont, [operation, a / 1, b / 1]}
  end
end

# FloatPlugin depends on LoggingPlugin, which depends on both math plugins.
# All four plugins are included automatically.
defmodule CalculatorV4b do
  use Malla.Service,
    plugins: [FloatPlugin]
end

{:ok, _pid} = CalculatorV4b.start_link([])

{:ok, sum} = CalculatorV4b.calculate(:add, 6, 7)
IO.puts("= #{sum}")
# => 13.0 (float!)

{:ok, product} = CalculatorV4b.calculate(:multiply, 6, 7)
IO.puts("= #{product}")
# => 42.0 (float!)
```

Notice that we didn't modify `AdditionPlugin`, `MultiplicationPlugin`, or `LoggingPlugin`. FloatPlugin uses `{:cont, [operation, a / 1, b / 1]}` to pass **modified arguments** down the chain, converting integers to floats before the math plugins see them. The existing plugins work unchanged - they just receive floats instead of integers.

## Part 6: Adding and Removing Plugins at Runtime

Malla can add or remove plugins from a running service without stopping it. The service is not restarted: its callback chain is rebuilt with the new plugin list. This is useful for debugging in production, feature rollouts, or disabling problematic plugins.

Let's start a calculator with `FloatPlugin` and then remove it at runtime.

```elixir
defmodule CalculatorV6 do
  use Malla.Service,
    plugins: [FloatPlugin, MultiplicationPlugin, AdditionPlugin]
end

{:ok, _pid} = CalculatorV6.start_link([])

IO.puts("--- With FloatPlugin ---")
IO.inspect(CalculatorV6.calculate(:add, 6, 7))
# => {:ok, 13.0}

# Remove FloatPlugin at runtime
IO.puts("\n--- Removing FloatPlugin ---")
Malla.Service.del_plugin(CalculatorV6, FloatPlugin)
Process.sleep(100)

IO.inspect(CalculatorV6.calculate(:add, 6, 7))
# => {:ok, 13}

# Add it back
IO.puts("\n--- Adding FloatPlugin back ---")
Malla.Service.add_plugin(CalculatorV6, FloatPlugin)
Process.sleep(100)

IO.inspect(CalculatorV6.calculate(:add, 6, 7))
# => {:ok, 13.0}
```

**No code changes and no restart of the service.** `del_plugin/2` and `add_plugin/3` rebuild the callback chain (the dispatch module of the service is recompiled, which takes a moment), and the plugin is started or stopped inside the running service. Note that `LoggingPlugin` was part of the chain only because `FloatPlugin` depends on it: it left with it, and came back with it.

## Part 7: Runtime Configuration and Reconfiguration

Malla services can be configured through `use Malla.Service` and reconfigured at runtime with `Malla.Service.reconfigure/2`. By convention, configuration is organized as keyword lists under keys named after each plugin or the service itself.

Plugins can read service configuration inside callbacks using `Malla.get_service_id!/0` and `srv_id.get_config/0`.

The update that `reconfigure/2` receives is **deep-merged** into the current configuration by default: nested keyword lists are merged key by key, so you only pass the keys that change. (Values that are not keyword lists, such as maps, are replaced instead of merged, so use keyword lists for what you want to update partially.) A plugin only needs to implement `plugin_config_merge/3` to validate or reject an update, which is not needed here.

```elixir
defmodule RoundingPlugin do
  use Malla.Plugin,
    plugin_deps: [AdditionPlugin, MultiplicationPlugin]

  defcb calculate(operation, a, b) do
    srv_id = Malla.get_service_id!()
    config = srv_id.get_config()
    decimals = get_in(config, [:rounding_plugin, :decimals]) || 2

    # Modify the arguments by rounding, then continue the chain
    {:cont, [operation, Float.round(a / 1, decimals), Float.round(b / 1, decimals)]}
  end
end

defmodule CalculatorV7 do
  use Malla.Service,
    plugins: [RoundingPlugin],
    # Default config: round to 1 decimal place (a keyword list)
    rounding_plugin: [decimals: 1]
end

{:ok, _pid} = CalculatorV7.start_link([])

IO.puts("--- Rounding to 1 decimal (default) ---")
IO.inspect(CalculatorV7.calculate(:add, 1.5, 2.25))
# => {:ok, 3.8}

# Change rounding precision at runtime
IO.puts("\n--- Reconfiguring to 2 decimals ---")
:ok = Malla.Service.reconfigure(CalculatorV7, rounding_plugin: [decimals: 2])

IO.inspect(CalculatorV7.calculate(:add, 1.5, 2.25))
# => {:ok, 3.75}

# You can also pass config at startup via start_link
# CalculatorV7.start_link(rounding_plugin: [decimals: 0])
```

## Key Takeaways

1. **Services** are the main building blocks - they define what your system does
2. **Plugins** are reusable pieces of functionality that can be composed together
3. **Callbacks** (defined with `defcb`) form chains that execute top-to-bottom
4. **Plugin dependencies control chain order** - dependent plugins run before their dependencies
5. **Return `:cont`** to continue the chain, or any other value to stop and return
6. **Configuration** - any non-reserved key in `use Malla.Service` becomes config, readable with `get_config/0` and changeable with `reconfigure/2`
7. **Plugins can be added/removed at runtime** with `add_plugin/3` and `del_plugin/2`, without restarting the service
8. **The last module of a chain** decides what the caller gets when everybody returns `:cont`: it returns the raw `:cont`, so end your chains with a plugin that answers

## Next Steps

This tutorial only scratches the surface of what Malla offers. Check out the [guides](../guides/01-introduction.md) and API documentation for the full picture: service lifecycle, distributed service discovery, remote calls, request handling, tracing, and more.
