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

SIP overload control (RFC 7339) with the loss-based algorithm: an
overloaded server tells its clients, in the Via of its responses, the
percentage of requests they should stop sending it, and the clients do.

```
defmodule MyProxy do
  use Malla.Service,
    plugins: [Caracola.OverloadControl],
    sip: [listen: "sip:all:5060", max_calls: 10_000],
    overload_control: [start: 0.8]
end
```

## As server

Requests whose top Via has the `oc` parameter come from clients
supporting overload control. Their responses get, in that Via, the
current reduction (`oc`, a percentage, 0 when not overloaded),
`oc-algo="loss"`, `oc-validity` (`:validity` milliseconds) and an
increasing `oc-seq`.

The reduction is the highest of:

  * the one set with `set_loss/3`, for example from the load of the
    application;
  * the one from the number of calls of the service: from 0 when they
    are the `:start` fraction of the `max_calls` of the sip configuration
    (0.8 by default), to 100 when they reach it. `nil` disables it.

## As client

Requests sent by the service (as user agent or proxy) get `oc` and
`oc-algo="loss"` in their Via. When a response has a reduction for a
server (identified by its IP address), that percentage of the new
requests (without To tag, except ACK and CANCEL) sent to it during the
validity are not sent: they fail with `{:error, :service_unavailable}`
(see `Caracola.UAC`), and a proxy tries the next destination, as when a
destination can not be reached (see `Caracola.Dispatcher`).

Requests not sent emit the `[:caracola, :overload_control, :drop]`
telemetry event, with the `:service`, the `:ip` of the server and its
`:loss` as metadata.

## Configuration

Under the `:overload_control` key:

  * `:start` - fraction of `max_calls` at which the reduction starts
    (default 0.8), `nil` to only use `set_loss/3`.
  * `:validity` - milliseconds the reduction sent to clients is valid
    (default 500).

# `clear`

```elixir
@spec clear(module()) :: :ok
```

Forgets the reductions asked by servers to a service, and the one it set.

# `loss`

```elixir
@spec loss(module()) :: 0..100
```

The reduction the service asks its clients for now.

# `server_loss`

```elixir
@spec server_loss(module(), :inet.ip_address()) :: 0..100
```

The reduction a server (by IP address) asked the service for, if still
valid.

# `set_loss`

```elixir
@spec set_loss(module(), 0..100, pos_integer() | :infinity) :: :ok
```

Sets the reduction (0 to 100) the service asks its clients for, for
`time` milliseconds (or until changed).

---

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