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

Configuration schema for SIP services, placed under the `:sip` key.

Equivalent to NkSIP's `nksip_syntax:app_syntax/0` (without the `sip_` prefix).
Defaults match NkSIP's `nksip_syntax:make_config/1`.

## Options

* `:listen` (`t:String.t/0`) - Listening URIs, for example `"sip:all:5060, <sip:all:5061;transport=tls>"`. For WS and WSS, a path accepts only that HTTP path (`"<sip:all:8080/ws;transport=ws>"`).

* `:allow` - Methods sent in the Allow header. The default value is `["INVITE", "ACK", "CANCEL", "BYE", "OPTIONS", "INFO", "UPDATE", "SUBSCRIBE", "NOTIFY", "REFER", "MESSAGE"]`.

* `:supported` - Option tags sent in the Supported header. The default value is `["path"]`.

* `:timer_t1` - Timer T1 (msecs). The default value is `500`.

* `:timer_t2` - Timer T2 (msecs). The default value is `4000`.

* `:timer_t4` - Timer T4 (msecs). The default value is `5000`.

* `:timer_c` (`t:pos_integer/0`) - Timer C (secs). The default value is `180`.

* `:trans_timeout` - Transaction timeout (secs): every `2 * trans_timeout` seconds, calls remove the transactions older than that, replying `{:error, :timeout}` to their callers. The default value is `900`.

* `:dialog_timeout` - Dialog timeout (secs): dialogs without activity are ended with a BYE (and removed after twice this time). The default value is `1800`.

* `:event_expires` (`t:pos_integer/0`) - Default subscription expiration (secs). The default value is `60`.

* `:event_expires_offset` (`t:non_neg_integer/0`) - Extra time before a subscription is removed (secs). The default value is `5`.

* `:session_expires` - Session interval for session timers (secs, see `Caracola.SessionTimers`). The default value is `1800`.

* `:min_se` (`t:pos_integer/0`) - Minimum session interval accepted for session timers (secs). The default value is `90`.

* `:digest_algorithms` - Digest algorithms accepted from clients (RFC 8760): `:md5`, `:sha256` and `:sha512_256`. Challenges offer them, the strongest first. The default value is `[:md5]`.

* `:nonce_timeout` - Validity of digest auth nonces (secs). The default value is `30`.

* `:from` (`t:String.t/0`) - Default From URI.

* `:accept` - Default Accept values.

* `:events` - Supported event packages. The default value is `[]`.

* `:info_packages` - INFO packages received (RFC 6086), sent in the Recv-Info header of INVITEs and their responses. Without it, no Recv-Info is sent (see `Caracola.InfoPackages`).

* `:route` (list of `t:String.t/0`) - Default Route URIs. The default value is `[]`.

* `:no_100` (`t:boolean/0`) - Do not send automatic 100 Trying. The default value is `false`.

* `:max_calls` - Maximum concurrent calls. The default value is `100000`.

* `:local_host` - Host used in Via and Contact (IPv4). The default value is `:auto`.

* `:local_host6` - Host used in Via and Contact (IPv6). The default value is `:auto`.

* `:tls` (`t:keyword/0`) - `:ssl` options for TLS and WSS listeners (`certfile`, `keyfile`...). The default value is `[]`.

* `:tls_client` (`t:keyword/0`) - `:ssl` options for outgoing TLS connections, merged with the defaults.

* `:password` (`t:term/0`) - Passwords to answer digest challenges: a password, an HA1 (`{:ha1, hex}` for MD5 or `{:ha1, algorithm, hex}`, see `Caracola.Digest.ha1/4`), `{realm, password}` or a list of them. Used after the ones in the request options.

* `:auto_auth_max_tries` (`t:non_neg_integer/0`) - Maximum number of times a challenged request is sent again with credentials. The default value is `5`.

* `:udp_max_size` (`t:non_neg_integer/0`) - Requests larger than this are sent over TCP. The default value is `1300`.

* `:via_params` (list of tuple of `t:String.t/0`,  values) - Parameters added to the Via of the requests sent, as `{name, value}` (for plugins). The default value is `[]`.

* `:instance_id` (`t:String.t/0`) - Instance id (RFC 5626 `+sip.instance`, used by outbound and GRUU), like `"<urn:uuid:...>"`. By default, one derived from the service and node names.

# `t`

```elixir
@type t() :: keyword()
```

The validated sip configuration of a service, as a keyword list.

# `add_values`

```elixir
@spec add_values(keyword(), :allow | :supported | :events | :info_packages, [
  String.t()
]) :: keyword()
```

Adds values to the `:allow`, `:supported`, `:events` or `:info_packages` list of the sip configuration
of a service, for plugins (in their `c:Malla.Plugin.plugin_config/2`):

    def plugin_config(_srv_id, config),
      do: {:ok, Caracola.Config.add_values(config, :supported, ["myext"])}

# `validate`

```elixir
@spec validate(keyword()) :: {:ok, t()} | {:error, NimbleOptions.ValidationError.t()}
```

Validates SIP options and fills in defaults.

---

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