Xirsys.Sockets.Transport behaviour (xturn_sockets v2.2.0)

View Source

Uniform socket I/O behaviour for TCP, UDP, TLS, DTLS, and SCTP.

Implementations live under Xirsys.Sockets.Transport.*. Acceptor and DatagramServer call these callbacks; they never talk to :gen_tcp / :gen_udp / :ssl directly.

Optional callbacks: peername/1, controlling_process/2, connect/3.

Summary

Types

from()

Peer address for a datagram, or nil for a connected stream socket.

ip_address()

IPv4 or IPv6 address tuple.

port_number()

UDP/TCP port in 0..65535.

socket()

Opaque socket handle returned by the underlying driver.

Callbacks

accept(socket, timeout)

Accepts one inbound connection from a listen socket.

close(socket)

Closes socket. Always returns :ok.

connect(ip_address, port_number, keyword)

Opens an outbound connection.

controlling_process(socket, pid)

Transfers socket ownership to pid after accept.

framing()

How this transport frames application payloads on the wire.

handle_message(term, socket)

Normalizes a driver message into a drain-engine event.

listen(ip_address, port_number, keyword)

Opens a listening socket.

peername(socket)

Remote address of a connected socket.

send(socket, iodata, from)

Sends data on socket.

setopts(socket, keyword)

Applies socket options (typically [:binary, active: :once] to re-arm).

sockname(socket)

Local address of socket.

Types

from()

@type from() :: {ip_address(), port_number()} | nil

Peer address for a datagram, or nil for a connected stream socket.

ip_address()

@type ip_address() :: :inet.ip_address()

IPv4 or IPv6 address tuple.

port_number()

@type port_number() :: :inet.port_number()

UDP/TCP port in 0..65535.

socket()

@type socket() :: term()

Opaque socket handle returned by the underlying driver.

Callbacks

accept(socket, timeout)

@callback accept(socket(), timeout()) :: {:ok, socket()} | {:error, term()}

Accepts one inbound connection from a listen socket.

Connectionless transports return {:error, :connectionless}.

Parameters

  • socket - listen socket from listen/3
  • timeout - milliseconds to wait, or :infinity

close(socket)

@callback close(socket()) :: :ok

Closes socket. Always returns :ok.

Parameters

  • socket - socket to close

connect(ip_address, port_number, keyword)

(optional) 
@callback connect(ip_address(), port_number(), keyword()) ::
  {:ok, socket()} | {:error, term()}

Opens an outbound connection.

Optional. Used when this library is the TCP client.

Parameters

  • ip - destination address
  • port - destination port
  • opts - extra connect options merged after library defaults

controlling_process(socket, pid)

(optional) 
@callback controlling_process(socket(), pid()) :: :ok | {:error, term()}

Transfers socket ownership to pid after accept.

Optional. Required for stream acceptors that spawn a Connection process.

Parameters

  • socket - accepted client socket
  • pid - process that will receive subsequent messages

framing()

@callback framing() :: :stream | :datagram

How this transport frames application payloads on the wire.

  • :stream - bytes are a continuous stream; 4-byte alignment is applied when a caller asks for it
  • :datagram - each send is one message; no padding

handle_message(term, socket)

@callback handle_message(term(), socket()) ::
  {:data, binary(), from()} | {:closed, term()} | {:icmp, map()} | :ignore

Normalizes a driver message into a drain-engine event.

Parameters

  • message - raw handle_info/2 payload ({:tcp, ...}, {:udp, ...}, ...)
  • socket - socket the message belongs to

Returns

  • {:data, binary(), from()} - payload ready to push into the accumulator
  • {:closed, reason} - peer or error close
  • {:icmp, map()} - ICMP error from a datagram socket (relay sockets)
  • :ignore - nothing to drain (unknown or control message)

listen(ip_address, port_number, keyword)

@callback listen(ip_address(), port_number(), keyword()) ::
  {:ok, socket()} | {:error, term()}

Opens a listening socket.

Parameters

  • ip - bind address ({0, 0, 0, 0} or {0, 0, 0, 0, 0, 0, 0, 0})
  • port - bind port; 0 lets the OS assign one
  • opts - extra listen options merged after library defaults

peername(socket)

(optional) 
@callback peername(socket()) ::
  {:ok, {ip_address(), port_number()}}
  | {:local, binary()}
  | {:unspec, <<_::0>>}
  | {:undefined, any()}
  | {:error, term()}

Remote address of a connected socket.

Optional. Datagram transports typically return {:error, :connectionless}.

Parameters

  • socket - connected socket

send(socket, iodata, from)

@callback send(socket(), iodata(), from()) :: :ok | {:error, term()}

Sends data on socket.

Parameters

  • socket - connected or datagram socket
  • data - payload
  • from - {ip, port} for datagrams; ignored (nil) on streams

setopts(socket, keyword)

@callback setopts(
  socket(),
  keyword()
) :: :ok | {:error, term()}

Applies socket options (typically [:binary, active: :once] to re-arm).

Parameters

  • socket - open socket
  • opts - option keyword list understood by the driver

sockname(socket)

@callback sockname(socket()) ::
  {:ok, {ip_address(), port_number()}}
  | {:local, binary()}
  | {:unspec, <<_::0>>}
  | {:undefined, any()}
  | {:error, term()}

Local address of socket.

Parameters

  • socket - open socket