Chronicle.Connections.Connection (cratis_chronicle v2.1.3)

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.

reconnect(connection)

Drops the current channel and dials a fresh one.

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.

reconnect(connection)

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

Drops the current channel and dials a fresh one.

For callers with independent evidence that the channel is unusable — such as the session watchdog detecting missed keepalives. A channel can die in ways this process cannot observe: the gRPC adapter reports transport death to the process that dialed (a completed connect task, not this server), and an expired auth token fails every new RPC while the transport stays healthy. Redialing re-resolves addresses and re-fetches authentication headers. No-op while a connect attempt is already in progress.

start_link(options \\ [])

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

Starts a Chronicle connection process linked to the current process.