# `Caracola.Dispatcher`
[🔗](https://github.com/netkubes/caracola/blob/v0.1.0-rc.1/lib/caracola/dispatcher.ex#L1)

Groups of destinations (gateways, media servers, other proxies) for a
proxy, with load balancing, health checks and failover.

```
defmodule MyProxy do
  use Malla.Service,
    plugins: [Caracola.Dispatcher],
    sip: [listen: "sip:all:5060"],
    dispatcher: [
      groups: [
        gateways: [
          destinations: ["sip:10.0.0.1", {"sip:10.0.0.2;transport=tcp", 2}],
          strategy: :weighted
        ]
      ]
    ]

  defcb sip_route(_scheme, _user, _domain, req, call),
    do: Caracola.Dispatcher.route(:gateways, req, call, [:record_route])
end
```

`route/4` proxies a request to the destinations of a group, in the order
given by its strategy, one after another (serial forking, see
[Proxies](07-proxy.md)): if a destination fails, the next one is tried.
`select/3` returns that order, to build other routes.

## Strategies

  * `:priority` (default) - in the configured order: the first
    destination gets all the requests while it is up.
  * `:round_robin` - each request starts with the next destination.
  * `:weighted` - random, each destination proportionally to its weight
    (1 by default).
  * `:hash` - by a key (the Call-ID in `route/4`): requests with the same
    key go to the same destination while it is up, and the requests of a
    destination that goes down are spread among the others (rendezvous
    hashing).

## Health checks

Every destination is sent an OPTIONS request periodically. Any response
but a 408 or 503 means it is up; after a number of failures in a row it
is marked as down, and not used until a check succeeds again. Destinations
start as up. Changes emit the `[:caracola, :dispatcher, :status]`
telemetry event, with the `:service`, `:uri` (a string) and `:status`
(`:up` or `:down`) as metadata. `set_status/3` changes the status by
hand, for example after a failure seen by the application, until the
next check.

## Configuration

Under the `:dispatcher` key:

  * `:groups` - keyword list of groups, each with:
    * `:destinations` - list of URIs, or `{uri, weight}`.
    * `:strategy` - `:priority`, `:round_robin`, `:weighted` or `:hash`.
  * `:probe` - health checks, `false` to disable them:
    * `:interval` - milliseconds between checks (default 30000).
    * `:timeout` - milliseconds to wait for the response (default 5000).
    * `:failures` - failures in a row to mark a destination as down
      (default 2).

# `destination`

```elixir
@type destination() :: %{
  uri: Caracola.URI.t(),
  weight: pos_integer(),
  status: :up | :down
}
```

A destination of a group: its URI, its weight and whether it is up or down.

# `strategy`

```elixir
@type strategy() :: :priority | :round_robin | :weighted | :hash
```

How a group chooses a destination.

# `destinations`

```elixir
@spec destinations(module(), atom()) :: [destination()]
```

The destinations of a group, with their weight and status.

# `route`

```elixir
@spec route(atom(), Caracola.Message.t(), Caracola.Call.t(), list()) ::
  {:proxy, [[Caracola.URI.t()]], list()} | {:reply, :service_unavailable}
```

A `sip_route/5` result proxying a request to the destinations of a group
(with `proxy_opts`, see [Proxies](07-proxy.md)), tried one after
another, or a 503 if none is up.

The Request-URI is sent to each destination with its user, if the
destination URI has none.

# `select`

```elixir
@spec select(module(), atom(), keyword()) :: [Caracola.URI.t()]
```

The destinations of a group that are up, in the order of its strategy.

Options:

  * `:key` - the key for the `:hash` strategy.
  * `:max` - maximum number of destinations.

# `set_status`

```elixir
@spec set_status(module(), String.t() | Caracola.URI.t(), :up | :down) :: :ok
```

Changes the status of a destination (in all its groups), until the next
health check.

---

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