# `Chronicle.Connections.Connection`
[🔗](https://github.com/Cratis/Chronicle.Elixir/blob/main/lib/chronicle/connections/connection.ex#L4)

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.

# `option`

```elixir
@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()}
```

# `channel`

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

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

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `connect`

```elixir
@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?`

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

Returns `true` if the channel is currently connected.

# `disconnect`

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

Disconnects the active channel and stops reconnect attempts.

The process exits normally after this call.

# `start_link`

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

Starts a Chronicle connection process linked to the current process.

---

*Consult [api-reference.md](api-reference.md) for complete listing*