erps v0.2.1 Erps.Transport.Api behaviour View Source

Encapsulates a common API which describes a transport strategy.

Currently the available transport strategies are:

  • Erps.Transport.Tcp: unencrypted, unauthenticated communication. Only appropriate in :dev and :test environments.
  • Erps.Transport.Tls: two-way authenticated, encrypted communication, using X509 TLS encryption. This is the general use case for Erps, for point-to-point API services including over untrusted networks.
  • Erps.Transport.OneWayTls: one-way authenticated, encrypted communication, using X509 TLS encryption. The server must present its authentication tokens and the clients may call in. This is akin to traditional Web API or gRPC endpoints management, but still requires manual certificate distribution to your client endpoints.

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

Each of the API callbacks is either a client callback, a server callback, or a "both" callback.

Link to this section Summary

Functions

a generic "listen" which calls :gen_tcp.listen/2 that filters out any ssl options passed in (see listen/2)

Callbacks

(server) temporarily blocks the server waiting for a connection request.

(client) initiates a unencrypted connection from the client to the server.

(server) upgrades the TCP connection to an authenticated, encrypted connection.

(server) opens a TCP port to listen for incoming connection requests.

(both) sends a packet down the appropriate transport channel

(both) provides a hint to GenServer.handle_info/2 as to what sorts of active packet messages to expect.

(client) upgrades an TCP connection to an encrypted, authenticated connection.

Link to this section Types

Link to this section Functions

a generic "listen" which calls :gen_tcp.listen/2 that filters out any ssl options passed in (see listen/2)

Link to this section Callbacks

Link to this callback

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

(server) temporarily blocks the server waiting for a connection request.

Link to this callback

connect(arg1, arg2, keyword) View Source
connect(:inet.ip_address(), :inet.port_number(), keyword()) ::
  {:ok, socket()} | {:error, any()}

(client) initiates a unencrypted connection from the client to the server.

The connection must be opened with active: false, or upgrade guarantees cannot be ensured for X509-TLS connections.

Link to this callback

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

(server) upgrades the TCP connection to an authenticated, encrypted connection.

Also should upgrade the connection from active: false to active: true.

In the case of an unencrypted transport, e.g. Erps.Transport.Tcp, only performs the connection upgrade.

Link to this callback

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

(server) opens a TCP port to listen for incoming connection requests.

Opens the port in active: false to ensure correct synchronization of handshake/2 and upgrade!/2 events.

NB: tls options provided will be passed into listen to allow servers that require tls options to fail early when launching if the user doesn't supply them.

Link to this callback

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

(both) sends a packet down the appropriate transport channel

Link to this callback

transport_type() View Source
transport_type() :: :tcp | :ssl

(both) provides a hint to GenServer.handle_info/2 as to what sorts of active packet messages to expect.

Link to this callback

upgrade!(arg1, keyword) View Source
upgrade!(:inet.socket(), keyword()) :: socket()

(client) upgrades an TCP connection to an encrypted, authenticated connection.

Also should upgrade the connection from active: false to active: true

In the case of an unencrypted transport, e.g. Erps.Transport.Tcp, only perfroms the connection upgrade.