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
sipsubprotocol, 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_timeoutmilliseconds 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
@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
@spec connection_port(pid()) :: {:ok, Caracola.Transport.Port.t()} | :error
Returns the port of a TCP, TLS, WS or WSS connection process.
@spec connections(term()) :: [Caracola.Transport.Port.t()]
Returns the TCP, TLS, WS and WSS connections of a service.
@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.
@spec listener_port(pid()) :: {:ok, Caracola.Transport.Port.t()} | :error
Returns the port of a listener process.
@spec listener_ports(pid()) :: [Caracola.Transport.Port.t()]
Returns the listening ports of a listener started with start_listener/3.
@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.
@spec listeners(term(), Caracola.Transport.Port.transport() | nil) :: [ Caracola.Transport.Port.t() ]
Returns the listeners of a service, optionally only for a transport.
@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.
@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.
@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_tcpistrue.:idle_timeoutand:connect_timeout- for new connections.:tls-:sslclient 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.
@spec send_message(Caracola.Transport.Port.t(), (Caracola.Transport.Port.t() -> 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.
@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.
@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,0for 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-:ssloptions for TLS and WSS listeners (certfile,keyfile...).:path- for WS and WSS, the only HTTP path accepted (any by default).
@spec stop_listener(pid()) :: :ok | {:error, :not_found}
Stops a listener started with start_listener/3.