Abyss.Transport behaviour (Abyss v0.2.1)

View Source

This module describes the behaviour required for Abyss to interact with low-level sockets. It is largely internal to Abyss, however users are free to implement their own versions of this behaviour backed by whatever underlying transport they choose. Such a module can be used in Abyss by passing its name as the transport_module option when starting up a server, as described in Abyss.

Summary

Types

A socket address

A listener socket options

A listener socket used to wait for connections

The return value from a close/1 call

The return value from a controlling_process/2 call

The return value from a getopts/2 call

The return value from a listen/2 call

The return value from a negotiated_protocol/1 call

The return value from a open/2 call

The return value from a peername/1 call

The return value from a recv/3 call

The return value from a send/2 call

The return value from a setopts/2 call

The return value from a sockname/1 call

The return value from a upgrade/2 call

The return data format of :gen_udp.recv

A socket representing a client connection

Options which can be set on a socket via setopts/2 (or returned from getopts/1)

Information about an endpoint, either remote ('peer') or local

Options which can be set on a socket via setopts/2 (or returned from getopts/1)

Connection statistics for a given socket

Callbacks

Closes the given socket.

Transfers ownership of the given socket to the given process. This will always be called by the process which currently owns the socket.

Gets the given options on the socket.

Returns stats about the connection on the socket.

Create and return a listener socket bound to the given port and configured per the provided options.

Returns the protocol negotiated as part of handshaking. Most typically this is via TLS' ALPN or NPN extensions. If the underlying transport does not support protocol negotiation (or if one was not negotiated), {:error, :protocol_not_negotiated} is returned

Returns information in the form of t:socket_info() about the remote end of the socket.

Returns available bytes on the given socket. Up to num_bytes bytes will be returned (0 can be passed in to get the next 'available' bytes, typically the next packet). If insufficient bytes are available, the function can wait timeout milliseconds for data to arrive.

Sends the given data (specified as a binary or an IO list) on the given socket.

Sets the given options on the socket. Should disallow setting of options which are not compatible with Abyss

Returns information in the form of t:socket_info() about the local end of the socket.

Types

address()

@type address() ::
  :inet.ip_address()
  | :inet.local_address()
  | {:local, binary()}
  | :unspec
  | {:undefined, any()}

A socket address

listen_options()

@type listen_options() :: [:inet.inet_backend() | :gen_udp.open_option()]

A listener socket options

listener_socket()

@type listener_socket() :: :inet.socket()

A listener socket used to wait for connections

on_close()

@type on_close() :: :ok | {:error, any()}

The return value from a close/1 call

on_controlling_process()

@type on_controlling_process() ::
  :ok | {:error, :closed | :not_owner | :badarg | :inet.posix()}

The return value from a controlling_process/2 call

on_getopts()

@type on_getopts() :: {:ok, [:inet.socket_optval()]} | {:error, :inet.posix()}

The return value from a getopts/2 call

on_listen()

@type on_listen() ::
  {:ok, listener_socket()} | {:error, :system_limit} | {:error, :inet.posix()}

The return value from a listen/2 call

on_negotiated_protocol()

@type on_negotiated_protocol() ::
  {:ok, binary()} | {:error, :protocol_not_negotiated | :closed}

The return value from a negotiated_protocol/1 call

on_open()

@type on_open() :: {:ok, socket()} | {:error, :system_limit} | {:error, :inet.posix()}

The return value from a open/2 call

on_peername()

@type on_peername() :: {:ok, socket_info()} | {:error, :inet.posix()}

The return value from a peername/1 call

on_recv()

@type on_recv() :: {:ok, recv_data()} | {:error, :closed | :timeout | :inet.posix()}

The return value from a recv/3 call

on_send()

@type on_send() ::
  :ok | {:error, :closed | {:timeout, rest_data :: binary()} | :inet.posix()}

The return value from a send/2 call

on_setopts()

@type on_setopts() :: :ok | {:error, :inet.posix()}

The return value from a setopts/2 call

on_sockname()

@type on_sockname() :: {:ok, socket_info()} | {:error, :inet.posix()}

The return value from a sockname/1 call

on_upgrade()

@type on_upgrade() :: {:ok, socket()} | {:error, term()}

The return value from a upgrade/2 call

recv_data()

@type recv_data() ::
  {address(), :inet.port_number(), binary() | charlist()}
  | {address(), :inet.port_number(), :inet.ancillary_data(),
     binary() | charlist()}

The return data format of :gen_udp.recv

socket()

@type socket() :: :inet.socket()

A socket representing a client connection

socket_get_options()

@type socket_get_options() :: [:inet.socket_getopt()]

Options which can be set on a socket via setopts/2 (or returned from getopts/1)

socket_info()

Information about an endpoint, either remote ('peer') or local

socket_set_options()

@type socket_set_options() :: [:inet.socket_setopt()]

Options which can be set on a socket via setopts/2 (or returned from getopts/1)

socket_stats()

@type socket_stats() ::
  {:ok, [{:inet.stat_option(), integer()}]} | {:error, :inet.posix()}

Connection statistics for a given socket

Callbacks

close(arg1)

@callback close(socket() | listener_socket()) :: on_close()

Closes the given socket.

controlling_process(socket, pid)

@callback controlling_process(socket(), pid()) :: on_controlling_process()

Transfers ownership of the given socket to the given process. This will always be called by the process which currently owns the socket.

getopts(socket, socket_get_options)

@callback getopts(socket(), socket_get_options()) :: on_getopts()

Gets the given options on the socket.

getstat(socket)

@callback getstat(socket()) :: socket_stats()

Returns stats about the connection on the socket.

listen(port_number, listen_options)

@callback listen(:inet.port_number(), listen_options()) ::
  {:ok, listener_socket()} | {:error, any()}

Create and return a listener socket bound to the given port and configured per the provided options.

negotiated_protocol(socket)

@callback negotiated_protocol(socket()) :: on_negotiated_protocol()

Returns the protocol negotiated as part of handshaking. Most typically this is via TLS' ALPN or NPN extensions. If the underlying transport does not support protocol negotiation (or if one was not negotiated), {:error, :protocol_not_negotiated} is returned

peername(socket)

@callback peername(socket()) :: on_peername()

Returns information in the form of t:socket_info() about the remote end of the socket.

recv(socket, num_bytes, timeout)

@callback recv(socket(), num_bytes :: non_neg_integer(), timeout :: timeout()) ::
  on_recv()

Returns available bytes on the given socket. Up to num_bytes bytes will be returned (0 can be passed in to get the next 'available' bytes, typically the next packet). If insufficient bytes are available, the function can wait timeout milliseconds for data to arrive.

send(socket, data)

@callback send(socket(), data :: iodata()) :: on_send()

Sends the given data (specified as a binary or an IO list) on the given socket.

setopts(socket, socket_set_options)

@callback setopts(socket(), socket_set_options()) :: on_setopts()

Sets the given options on the socket. Should disallow setting of options which are not compatible with Abyss

sockname(arg1)

@callback sockname(socket() | listener_socket()) :: on_sockname()

Returns information in the form of t:socket_info() about the local end of the socket.