transport v0.1.0 Transport behaviour View Source

Encapsulates a common API which describes a transport strategy.

By using this API you can use TCP and TLS interchangeably, by specifying strategy modules in your server and client configurations. This API also seeks to iron out common missteps in setting up TLS connections and enforce some best practices for securing your WAN transmissions.

Currently the available transport strategies are:

Transport.Tcp: unencrypted, unauthenticated communication. Only appropriate in :dev and :test environments. Allows you to simplify early stage and test deployments.
Transport.Tls: two-way authenticated, encrypted communication, using X509 TLS encryption. This is the general use case for point-to-point API services including over untrusted networks.

You may use this API to implement your own transport layers, or use it to mock responses in tests.

Link to this section Summary

Types

socket()

Callbacks

accept(socket, timeout)

(for servers) blocks on a socket opened with b:listen/1,2 and waits for a connection request.

connect(identifier, port, keyword)

(for clients) initiates an unencrypted connection from the client to the server.

handshake(socket, keyword)

(for servers) upgrades an associated TCP connection to an authenticated, encrypted connection, if the transport module implements encryption.

listen(port)

listen(port, keyword)

(for servers) opens an unencrypted TCP port to listen for incoming connection requests.

recv(socket, length)

(for clients and servers) blocks until data of a requested length comes over the transport channel.

recv(socket, length, timeout)

(for clients and servers). Like b:recv/2 but with a timeout so the server doesn't block indefinitely.

send(socket, iodata)

(for clients and servers) sends iodata down the appropriate transport channel.

type()

returns an atom which is intended for matching on active packet messages.

upgrade(socket, options)

(for clients) upgrades a TCP connection to an authenticated, encrypted connection, if the transport module implements encryption.

Link to this section Types

socket()

socket() :: :inet.socket() | :ssl.sslsocket() | GenServer.server() | port()

Link to this section Callbacks

accept(socket, timeout)

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

(for servers) blocks on a socket opened with b:listen/1,2 and waits for a connection request.

The resulting opened socket will be unencrypted, and must be upgraded with b:handshake/2 to initiate secure communications.

connect(identifier, port, keyword)

connect(
  identifier :: :inet.ip_address(),
  port :: :inet.port_number(),
  keyword()
) :: {:ok, socket()} | {:error, any()}

(for clients) initiates an unencrypted connection from the client to the server.

This unencrypted connection can be upgraded to an encrypted connection later, using the b:upgrade/2 function. Implementation modules guarantee an active: false connection to ensure timing correctness when establishing the upgraded encryption.

If you need to set active: true or other connection options that the upgrade process is sensitive to, you can set them in the options argument of b:upgrade/2.

handshake(socket, keyword)

handshake(socket :: :inet.socket(), keyword()) ::
  {:ok, socket()} | {:error, any()}

(for servers) upgrades an associated TCP connection to an authenticated, encrypted connection, if the transport module implements encryption.

connection options that are incompatible with the handshake (such as active: true) should be passed into the options argument here.

listen(port)

listen(port :: :inet.port_number()) :: {:ok, socket()} | {:error, any()}

listen(port, keyword)

listen(port :: :inet.port_number(), keyword()) ::
  {:ok, socket()} | {:error, any()}

(for servers) opens an unencrypted TCP port to listen for incoming connection requests.

Implementation modules guarantee an active: false connection to ensure correct synchronization of handshake/2 events.

recv(socket, length)

recv(socket(), length :: non_neg_integer()) :: {:ok, binary()} | {:error, any()}

(for clients and servers) blocks until data of a requested length comes over the transport channel.

See :gen_tcp.recv/2 for more information.

recv(socket, length, timeout)

recv(socket(), length :: non_neg_integer(), timeout()) ::
  {:ok, binary()} | {:error, any()}

(for clients and servers). Like b:recv/2 but with a timeout so the server doesn't block indefinitely.

See :gen_tcp.recv/3 for more information.

send(socket, iodata)

send(socket(), iodata()) :: :ok | {:error, any()}

(for clients and servers) sends iodata down the appropriate transport channel.

If the data are bigger than the MTU, it may be broken into multiple packets over the line.

type()

type() :: atom()

returns an atom which is intended for matching on active packet messages.

When the connection is active: :true, the owning process will recieve messages of the form: {:tcp, <socket>, <data>} or {:ssl, <socket>, <data>}, this function helps you generically match the identifier on the front of this message tuple.

upgrade(socket, options)

upgrade(socket(), options :: keyword()) :: {:ok, socket()} | {:error, any()}

(for clients) upgrades a TCP connection to an authenticated, encrypted connection, if the transport module implements encryption.

connection options that are incompatible with encryption upgrading (such as active: true) should be passed into the options argument.