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

SIP transport layer: listeners, connections and sending. Replaces the
parts of NkPACKET used by NkSIP.

  * UDP listeners also listen on TCP on the same port, as RFC 3261 §18
    requires. Incoming TCP, TLS, WS and WSS connections are handled by
    ThousandIsland.
  * SIP over WebSocket (RFC 7118) uses the `sip` subprotocol, with each
    message in a WebSocket message.
  * Connections are kept in a table keyed by service, transport and peer
    address, and reused to send to the same peer. They are closed after
    `:idle_timeout` milliseconds without traffic.
  * UDP messages are sent from the listener socket, so that they come
    from the listening port.
  * Received messages are given to the listener's handler, see
    `Caracola.Transport.Handler`.

`service` is any term identifying the owner of listeners and connections
(the Malla service id).

# `target`

```elixir
@type target() :: binary() | Caracola.URI.t() | Caracola.DNS.target()
```

Where to send: a URI (as a binary or `Caracola.URI`) or an already resolved target.

# `connection_port`

```elixir
@spec connection_port(pid()) :: {:ok, Caracola.Transport.Port.t()} | :error
```

Returns the port of a TCP, TLS, WS or WSS connection process.

# `connections`

```elixir
@spec connections(term()) :: [Caracola.Transport.Port.t()]
```

Returns the TCP, TLS, WS and WSS connections of a service.

# `get_connected`

```elixir
@spec get_connected(
  term(),
  Caracola.Transport.Port.transport(),
  :inet.ip_address(),
  :inet.port_number()
) :: [Caracola.Transport.Port.t()]
```

Returns the shared connections to a peer (at most one), excluding the ones
started with `new_connection: true`.

# `listener_port`

```elixir
@spec listener_port(pid()) :: {:ok, Caracola.Transport.Port.t()} | :error
```

Returns the port of a listener process.

# `listener_ports`

```elixir
@spec listener_ports(pid()) :: [Caracola.Transport.Port.t()]
```

Returns the listening ports of a listener started with `start_listener/3`.

# `listener_spec`

```elixir
@spec listener_spec(term(), Caracola.Transport.Port.transport(), keyword()) ::
  Supervisor.child_spec()
```

Child spec of a listener, to start it under another supervisor. Options
as in `start_listener/3`.

# `listeners`

```elixir
@spec listeners(term(), Caracola.Transport.Port.transport() | nil) :: [
  Caracola.Transport.Port.t()
]
```

Returns the listeners of a service, optionally only for a transport.

# `local?`

```elixir
@spec local?(term(), Caracola.URI.t(), keyword()) :: boolean()
```

Returns `true` if `uri` points to one of the listeners of the service:
same port (the default one of the transport if missing) and an address
of the listener, `localhost`, or the `:local_host` and `:local_host6` of
`config`. Host names are not resolved.

# `send`

```elixir
@spec send(Caracola.Transport.Port.t(), iodata() | Caracola.Message.t()) ::
  {:ok, Caracola.Transport.Port.t()} | {:error, term()}
```

Sends data (or a message) through an existing UDP port with a peer or a
connection, usually the one a message was received from.

# `send`

```elixir
@spec send(term(), target(), iodata() | Caracola.Message.t(), keyword()) ::
  {:ok, Caracola.Transport.Port.t()} | {:error, term()}
```

Sends data (or a message) to a target: a URI (resolved following
RFC 3263, trying each destination in order until one works) or a
`{transport, ip, port}` tuple.

A listener for the transport (and IP family) is required. Returns the
port used, whose `listen_ip` and `listen_port` are those of the listener.

Options:

  * `:new_connection` - open a new, dedicated connection instead of
    reusing an existing one.
  * `:udp_max_size` - messages over UDP larger than this (the maximum
    datagram size by default) fail with `:udp_too_large`, or go over TCP if
    `:udp_to_tcp` is `true`.
  * `:idle_timeout` and `:connect_timeout` - for new connections.
  * `:tls` - `:ssl` client options, merged with the defaults (peer
    verification against the system CAs and, when the target is a URI with
    a host name, hostname checking).
  * `:ws_path` - HTTP path for new WS and WSS connections, the path of the
    target URI or `/` by default.
  * DNS options, see `Caracola.DNS.resolve/2`.

# `send_message`

```elixir
@spec send_message(Caracola.Transport.Port.t(), (Caracola.Transport.Port.t() -&gt;
                                             iodata() | Caracola.Message.t())) ::
  {:ok, Caracola.Transport.Port.t(), iodata() | Caracola.Message.t()}
  | {:error, term()}
```

Like `send/2`, but the message is generated by `make`, called with the
port it will be sent through. Returns the port and the generated message.

# `send_message`

```elixir
@spec send_message(
  term(),
  target(),
  (Caracola.Transport.Port.t() -&gt; iodata() | Caracola.Message.t()),
  keyword()
) ::
  {:ok, Caracola.Transport.Port.t(), iodata() | Caracola.Message.t()}
  | {:error, term()}
```

Like `send/4`, but the message is generated by `make`, called with the
port it will be sent through (for new connections, the listener port with
the remote address). As the transport may change (UDP to TCP, or another
destination after a failure), `make` can be called several times.

# `start_listener`

```elixir
@spec start_listener(term(), Caracola.Transport.Port.transport(), keyword()) ::
  {:ok, pid()} | {:error, term()}
```

Starts a listener for `service`.

Options:

  * `:ip` - address to listen on (tuple or string), `{0, 0, 0, 0}` by default.
  * `:port` - the default port of the transport if not given, `0` for a
    random one. For UDP, the TCP listener uses the same port.
  * `:handler` - `{module, arg}` receiving the messages.
  * `:idle_timeout` - for incoming connections, in milliseconds (three
    minutes by default).
  * `:tls` - `:ssl` options for TLS and WSS listeners (`certfile`,
    `keyfile`...).
  * `:path` - for WS and WSS, the only HTTP path accepted (any by default).

# `stop_listener`

```elixir
@spec stop_listener(pid()) :: :ok | {:error, :not_found}
```

Stops a listener started with `start_listener/3`.

---

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