ThousandIsland.Transport behaviour (Thousand Island v0.4.6) View Source

This module describes the behaviour required for Thousand Island to interact with low-level sockets. It is largely internal to Thousand Island, 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 Thousand Island by passing its name as the transport_module option when starting up a server, as described in ThousandIsland.

Link to this section Summary

Types

listener_socket()

A listener socket used to wait for connections

negotiated_protocol_info()

The return value from a negotiated_protocol/1 call

on_handshake()

The return value from a handshake/1 call

on_recv()

The return value from a recv/3 call

socket()

A socket representing a client connection

socket_info()

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

socket_options()

Options which can be set on a socket via setopts/2

socket_stats()

Connection statistics for a given socket

way()

The direction in which to shutdown a connection in advance of closing it

Callbacks

accept(listener_socket)

Wait for a client connection on the given listener socket. This call blocks until such a connection arrives, or an error occurs (such as the listener socket being closed).

close(arg1)

Closes the given socket.

controlling_process(socket, pid)

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

getstat(socket)

Returns stats about the connection on the socket.

handshake(socket)

Performs an initial handshake on a new client connection (such as that done when negotiating an SSL connection). Transports which do not have such a handshake can simply pass the socket through unchanged.

listen(port_number, keyword)

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

listen_port(listener_socket)

Return the local port number that the given listener socket is accepting connections on.

local_info(socket)

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

negotiated_protocol(socket)

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

peer_info(socket)

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

recv(socket, num_bytes, timeout)

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.

secure?()

Returns whether or not this protocol is secure.

send(socket, data)

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

sendfile(socket, filename, offset, length)

Sends the contents of the given file based on the provided offset & length

setopts(socket, socket_options)

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

shutdown(socket, way)

Shuts down the socket in the given direction.

Link to this section Types

listener_socket()

Specs

listener_socket() :: any()

A listener socket used to wait for connections

negotiated_protocol_info()

Specs

negotiated_protocol_info() ::
  {:ok, binary()} | {:error, :protocol_not_negotiated}

The return value from a negotiated_protocol/1 call

on_handshake()

Specs

on_handshake() :: {:ok, socket()} | {:error, any()}

The return value from a handshake/1 call

on_recv()

Specs

on_recv() :: {:ok, binary()} | {:error, String.t()}

The return value from a recv/3 call

socket()

Specs

socket() :: any()

A socket representing a client connection

socket_info()

Specs

socket_info() :: %{
  address: :inet.ip_address(),
  port: :inet.port_number(),
  ssl_cert: String.t() | nil
}

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

socket_options()

Specs

socket_options() :: [:inet.socket_setopt()]

Options which can be set on a socket via setopts/2

socket_stats()

Specs

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

Connection statistics for a given socket

way()

Specs

way() :: :read | :write | :read_write

The direction in which to shutdown a connection in advance of closing it

Link to this section Callbacks

accept(listener_socket)

Specs

accept(listener_socket()) :: {:ok, socket()} | {:error, any()}

Wait for a client connection on the given listener socket. This call blocks until such a connection arrives, or an error occurs (such as the listener socket being closed).

close(arg1)

Specs

close(socket() | listener_socket()) :: :ok

Closes the given socket.

controlling_process(socket, pid)

Specs

controlling_process(socket(), pid()) :: :ok | {:error, any()}

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

getstat(socket)

Specs

getstat(socket()) :: socket_stats()

Returns stats about the connection on the socket.

handshake(socket)

Specs

handshake(socket()) :: on_handshake()

listen(port_number, keyword)

Specs

listen(:inet.port_number(), keyword()) :: {:ok, listener_socket()}

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

listen_port(listener_socket)

Specs

listen_port(listener_socket()) :: {:ok, :inet.port_number()}

Return the local port number that the given listener socket is accepting connections on.

local_info(socket)

Specs

local_info(socket()) :: socket_info()

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

negotiated_protocol(socket)

Specs

negotiated_protocol(socket()) :: negotiated_protocol_info()

peer_info(socket)

Specs

peer_info(socket()) :: socket_info()

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

recv(socket, num_bytes, timeout)

Specs

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

secure?()

Specs

secure?() :: boolean()

Returns whether or not this protocol is secure.

send(socket, data)

Specs

send(socket(), data :: IO.chardata()) :: :ok | {:error, String.t()}

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

sendfile(socket, filename, offset, length)

Specs

sendfile(
  socket(),
  filename :: String.t(),
  offset :: non_neg_integer(),
  length :: non_neg_integer()
) :: {:ok, non_neg_integer()} | {:error, String.t()}

Sends the contents of the given file based on the provided offset & length

setopts(socket, socket_options)

Specs

setopts(socket(), socket_options()) :: :ok | {:error, String.t()}

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

shutdown(socket, way)

Specs

shutdown(socket(), way()) :: :ok

Shuts down the socket in the given direction.