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

SIP message parser. Port of NkSIP's `nksip_parse_sipmsg` and `nksip_parse`.

`parse/2` frames the message using `Content-Length` and parses it into a
`Caracola.Message`:

  * On stream transports (`:tcp`, `:tls`) `Content-Length` is mandatory and
    `:partial` is returned while the message is incomplete.
  * On message transports (`:udp`, `:sctp`, `:ws`, `:wss`) a missing
    `Content-Length` means that the body is the rest of the packet.
  * Any bytes after the message are returned as `rest`.

Known headers are validated in the same order as NkSIP, so the reason of a
`400 Invalid <header>` response is the same.

# `result`

```elixir
@type result() ::
  {:ok, Caracola.Message.t(), rest :: binary()}
  | :partial
  | {:error, Caracola.ParseError.t()}
```

The result of parsing: a message and the rest of the data, `:partial` if more data is needed, or an error.

# `parse`

```elixir
@spec parse(binary(), Caracola.Via.transport()) :: result()
```

Parses a SIP message received over `transport`.

# `parse!`

```elixir
@spec parse!(binary(), Caracola.Via.transport()) ::
  {Caracola.Message.t(), binary()} | :partial
```

Same as `parse/2` but raises `Caracola.ParseError` on errors.

---

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