Caracola.Transport (Caracola v0.1.0-rc.1)

Copy Markdown View Source

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).

Summary

Types

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

Functions

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

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

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

Returns the port of a listener process.

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

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

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

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.

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

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.

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.

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.

Starts a listener for service.

Stops a listener started with start_listener/3.

Types

target()

@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.

Functions

connection_port(pid)

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

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

connections(service)

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

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

get_connected(service, transport, ip, port)

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

listener_port(pid)

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

Returns the port of a listener process.

listener_ports(pid)

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

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

listener_spec(service, transport, opts)

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

listeners(service, transport \\ nil)

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

local?(service, uri, config \\ [])

@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(port, data)

@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(service, target, data, opts \\ [])

@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(port, make)

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(service, target, make, opts \\ [])

@spec send_message(
  term(),
  target(),
  (Caracola.Transport.Port.t() -> 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(service, transport, opts \\ [])

@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(pid)

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

Stops a listener started with start_listener/3.