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

HEP capture: sends every SIP message received or sent by the service to
a capture server (Homer, heplify-server...) with HEPv3 over UDP, from the
`[:caracola, :message, :received]` and `[:caracola, :message, :sent]`
telemetry events (see `Caracola.Telemetry`).

```
defmodule MyProxy do
  use Malla.Service,
    plugins: [Caracola.HEP],
    sip: [listen: "sip:all:5060"],
    hep: [host: "homer.example.com", port: 9060, capture_id: 101]
end
```

The capture starts and stops with the service. Each packet carries the
addresses and ports of both sides, the transport, the time, the
capture agent id, the Call-ID (as correlation id) and the message.
Keepalives are not sent. Messages are captured as parsed and
serialized again by Caracola, which may differ from the bytes on the
wire in spacing or header order.

## Configuration

Under the `:hep` key:

  * `:host` - the capture server (a hostname or an IP, required).
  * `:port` - its UDP port (default 9060).
  * `:capture_id` - the capture agent id (default 2001).
  * `:password` - the authentication key, if the server needs one.

# `packet`

```elixir
@type packet() :: %{
  src_ip: :inet.ip_address(),
  dst_ip: :inet.ip_address(),
  src_port: :inet.port_number(),
  dst_port: :inet.port_number(),
  transport: :udp | :tcp,
  time: integer(),
  capture_id: non_neg_integer(),
  password: String.t() | nil,
  correlation_id: String.t() | nil,
  payload: binary()
}
```

A HEP packet, as encoded by `encode/1` and decoded by `decode/1`.

# `decode`

```elixir
@spec decode(binary()) :: {:ok, packet()} | :error
```

Decodes a HEPv3 packet (for tests and tools).

# `encode`

```elixir
@spec encode(packet()) :: binary()
```

Encodes a HEPv3 packet with a SIP message. `time` is in microseconds of
system time.

---

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