Chronicle.Connections.Connection (cratis_chronicle v2.1.1)

Copy Markdown View Source

Manages a resilient Chronicle gRPC channel with automatic reconnection.

Connection is a GenServer that maintains a gRPC channel to a Chronicle kernel. It handles connection failures with exponential backoff and notifies callers waiting for the connection to become ready.

On every connect/reconnect attempt it re-resolves the connection string's addresses — a static multi-host list, or a fresh DNS SRV lookup for chronicle+srv:// (see Chronicle.Connections.DnsResolver) — and picks one via the configured load-balancer strategy (see Chronicle.Connections.LoadBalancer) before dialing. Re-resolving on every attempt means a chronicle+srv:// record change, or a host coming back up, is picked up automatically without a separate background refresh loop.

Usage

Start it as part of your supervision tree, typically via Chronicle.Client:

{Chronicle.Client,
  connection_string: "chronicle://localhost:35000",
  ...}

Or start it directly for lower-level use:

{:ok, conn} = Chronicle.Connections.Connection.start_link(
  connection_string: "chronicle://localhost:35000",
  name: :my_conn
)
:ok = Chronicle.Connections.Connection.connect(:my_conn)
{:ok, channel} = Chronicle.Connections.Connection.channel(:my_conn)

Options

  • :connection_string — a Chronicle.Connections.ConnectionString struct or a connection string binary. Defaults to ConnectionString.default/0.
  • :server_address — alternative to :connection_string; a "host:port" string.
  • :skip_tls_validation — overrides the connection string's skipTlsValidation query option. When true, the gRPC channel and the OAuth2 token fetch skip TLS certificate chain validation instead of validating against the system trust store.
  • :load_balancer — overrides the connection string's loadBalancer query option (:least_connections, :round_robin, or :random).
  • :grpc_options — additional options passed to GRPC.Stub.connect/2.
  • :retry_attempts — maximum reconnect attempts before giving up (default: 5).
  • :reconnect_base_delay — base reconnect delay in milliseconds (default: 1000).
  • :reconnect_max_delay — maximum reconnect delay in milliseconds (default: 10000).
  • :auto_connect — whether to connect immediately on start (default: true).
  • :resolve_fun — resolves a chronicle+srv:// host to candidate addresses. Defaults to Chronicle.Connections.DnsResolver.resolve/2. Test-only seam, mirroring :connect_fun/:disconnect_fun below.
  • :probe_fun — performs the :least_connections HTTP probe. Defaults to Chronicle.Connections.LoadBalancer.default_probe/3. Test-only seam.
  • :connect_fun — test-only seam replacing GRPC.Stub.connect/2.
  • :disconnect_fun — test-only seam replacing GRPC.Stub.disconnect/1.
  • :name — registered name for the GenServer process.

Summary

Types

option()

Functions

channel(connection)

Returns {:ok, channel} when connected, or {:error, :not_connected}.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

connect(connection, timeout \\ 10000)

Waits until the connection is ready, or returns {:error, :timeout}.

connected?(connection)

Returns true if the channel is currently connected.

disconnect(connection)

Disconnects the active channel and stops reconnect attempts.

start_link(options \\ [])

Starts a Chronicle connection process linked to the current process.

Types

option()

@type option() ::
  {:connection_string, String.t() | Chronicle.Connections.ConnectionString.t()}
  | {:server_address, String.t()}
  | {:skip_tls_validation, boolean()}
  | {:load_balancer,
     Chronicle.Connections.ConnectionString.load_balancer_strategy()}
  | {:grpc_options, keyword()}
  | {:retry_attempts, non_neg_integer()}
  | {:reconnect_base_delay, non_neg_integer()}
  | {:reconnect_max_delay, non_neg_integer()}
  | {:resolve_fun,
     (String.t(), String.t() | nil ->
        {:ok, [Chronicle.Connections.ConnectionString.ServerAddress.t()]}
        | {:error, term()})}
  | {:probe_fun, Chronicle.Connections.LoadBalancer.probe_fun()}
  | {:connect_fun, (String.t(), keyword() -> {:ok, term()} | {:error, term()})}
  | {:disconnect_fun, (term() -> any())}
  | {:name, GenServer.name()}
  | {:auto_connect, boolean()}

Functions

channel(connection)

@spec channel(GenServer.server()) :: {:ok, term()} | {:error, :not_connected}

Returns {:ok, channel} when connected, or {:error, :not_connected}.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

connect(connection, timeout \\ 10000)

@spec connect(GenServer.server(), timeout()) :: :ok | {:error, :timeout}

Waits until the connection is ready, or returns {:error, :timeout}.

Blocks the caller until the gRPC channel is established or timeout milliseconds elapse.

connected?(connection)

@spec connected?(GenServer.server()) :: boolean()

Returns true if the channel is currently connected.

disconnect(connection)

@spec disconnect(GenServer.server()) :: :ok

Disconnects the active channel and stops reconnect attempts.

The process exits normally after this call.

start_link(options \\ [])

@spec start_link([option()]) :: GenServer.on_start()

Starts a Chronicle connection process linked to the current process.