Spear.Connection (Spear v0.1.3) View Source
A GenServer which brokers a connection to an EventStoreDB
Spear.Connection
will attempt to connect immediately after GenServer init.
Failures to connect will result in back-off retries in segments of 500ms.
Any GenServer to a connection process may return {:error, :closed}
if the
connection process is alive but the HTTP2 connection to the EventStoreDB
is not yet (re)established. Spear.Connection
will automatically attempt
to re-connect to the EventStoreDB if the connection is severed.
Spear.Connection
processes accept GenServer.call/3
s of :close
to
force a disconnect from an EventStoreDB and a subsequent GenServer.cast/2
of :connect
to reconnect based on the configuration supplied at init-time.
If configuration parameters must change between disconnects and reconnects,
spawning and killing connections with a DynamicSupervisor
is recommended.
Spear.Connection
will attempt to connect immediately after GenServer init.
Failures to connect will result in back-off retries in segments of 500ms.
Any GenServer to a connection process may return {:error, :closed}
if the
connection process is alive but the HTTP2 connection to the EventStoreDB
is not yet (re)established. Spear.Connection
will automatically attempt
to re-connect to the EventStoreDB if the connection is severed.
Spear.Connection
processes accept GenServer.call/3
s of :close
to
force a disconnect from an EventStoreDB and a subsequent GenServer.cast/2
of :connect
to reconnect based on the configuration supplied at init-time.
If configuration parameters must change between disconnects and reconnects,
spawning and killing connections with a DynamicSupervisor
is recommended.
Configuration
:name
- the name of the GenServer. SeeGenServer.name/0
for more information. When not provided, the spawned process is not aliased to a name and is only addressable through its PID.:connection_string
- (required) the connection string to parse containing all connection information:opts
- (default:[protocols: [:http2], mode: :active]
) aKeyword.t/0
of options to pass directly toMint.HTTP.connect/4
. See theMint.HTTP.connect/4
documentation for a full reference. This can be used to specify a custom CA certificate when using EventStoreDB in secure mode (the default in 20+) with a custom set of certificates. The default options cannot be overridden: explicitly passed:protocols
or:mode
will be ignored.:credentials
- (default:nil
) a pair (2-element) tuple providing a username and password to use for authentication with the EventStoreDB. E.g. the default username+password of{"admin", "changeit"}
.
TLS/SSL configuration and credentials
See the Security guide for information about certificates, credentials, and access control lists (ACLs).
Examples
iex> {:ok, conn} = Spear.Connection.start_link(connection_string: "esdb://localhost:2113")
iex> Spear.stream!(conn, "es_supported_clients") |> Enum.take(3)
[%Spear.Event{}, %Spear.Event{}, %Spear.Event{}]
Link to this section Summary
Functions
Starts a connection process
Link to this section Types
Specs
t() :: pid() | GenServer.name()
A connection process
A connection process (either referred to as conn
or connection
in the
documentation) may either be a PID or a name such as a module or otherwise
atom.
Examples
iex> {:ok, conn} = Spear.Connection.start_link(connection_string: "esdb://localhost:2113")
{:ok, #PID<0.225.0>}
iex> Spear.read_stream(conn, "es_supported_clients", max_count: 1)
{:ok,
#Stream<[
enum: #Function<62.80860365/2 in Stream.unfold/2>,
funs: [#Function<48.80860365/1 in Stream.map/2>]
]>}
Link to this section Functions
Specs
start_link(opts :: Keyword.t()) :: {:ok, t()} | GenServer.on_start()
Starts a connection process
This function can be called directly in order to link it to the current
process, but the more common workflow is to start a Spear.Connection
GenServer as a part of a supervision tree.
Examples
E.g. in an application's supervision tree defined in
lib/my_app/application.ex
:
children = [
{Spear.Connection, connection_string: "esdb://localhost:2113"}
]
Supervisor.start_link(children, strategy: :one_for_one)