erps v0.3.0 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
socket()
View Source
socket() :: :inet.socket() | :ssl.sslsocket()
socket() :: :inet.socket() | :ssl.sslsocket()
Link to this section Functions
listen(port, options!) View Source
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
accept(socket, timeout) View Source
(server) temporarily blocks the server waiting for a connection request.
connect(arg1, arg2, keyword)
View Source
connect(:inet.ip_address(), :inet.port_number(), keyword()) ::
{:ok, socket()} | {:error, any()}
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.
handshake(arg1, keyword)
View Source
handshake(:inet.socket(), keyword()) :: {:ok, socket()} | {:error, any()}
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.
listen(arg1, keyword)
View Source
listen(:inet.port_number(), keyword()) :: {:ok, socket()} | {:error, any()}
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.
send(socket, iodata) View Source
(both) sends a packet down the appropriate transport channel
transport_type()
View Source
transport_type() :: :tcp | :ssl
transport_type() :: :tcp | :ssl
(both) provides a hint to GenServer.handle_info/2
as to what sorts of
active packet messages to expect.
upgrade!(arg1, keyword)
View Source
upgrade!(:inet.socket(), keyword()) :: socket()
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.