Chronicle.Connections.Connection (chronicle v0.0.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.

Usage

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

{Chronicle.Client,
  connection_string: "chronicle://localhost:35000?disableTls=true",
  ...}

Or start it directly for lower-level use:

{:ok, conn} = Chronicle.Connections.Connection.start_link(
  connection_string: "chronicle://localhost:35000?disableTls=true",
  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.
  • :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).
  • :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()}
  | {:grpc_options, keyword()}
  | {:retry_attempts, non_neg_integer()}
  | {:reconnect_base_delay, non_neg_integer()}
  | {:reconnect_max_delay, non_neg_integer()}
  | {: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.