Spear.Connection (Spear v0.1.4) 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/3s 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/3s 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. See GenServer.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]) a Keyword.t/0 of options to pass directly to Mint.HTTP.connect/4. See the Mint.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

Types

t()

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

Link to this function

fetch_subscription(s, monitor_ref)

View Source

Specs

fetch_subscription(
  %Spear.Connection{
    config: term(),
    conn: term(),
    credentials: term(),
    requests: term()
  },
  reference()
) ::
  {:ok,
   %Spear.Connection.Request{
     buffer: term(),
     continuation: term(),
     from: term(),
     monitor_ref: term(),
     request_ref: term(),
     response: term(),
     status: term(),
     type: term()
   }}
  | :error

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)