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

Parses and formats Chronicle connection strings.

Chronicle connection strings use the `chronicle://` or `chronicle+srv://` scheme:

    chronicle://localhost:35000
    chronicle://client-id:client-secret@server:35000
    chronicle://server:35000?apiKey=my-key&disableTls=true

## Authentication

Two authentication modes are supported:

  * **Client credentials** — provide username and password in the URL userinfo:
    `chronicle://client-id:secret@host:35000`
  * **API key** — provide an `apiKey` query parameter:
    `chronicle://host:35000?apiKey=my-key`

## Query Parameters

  * `apiKey` — API key for authentication
  * `disableTls` — set to `"true"` to disable TLS (useful for local development)
  * `certificatePath` — path to a client certificate file
  * `certificatePassword` — password for the client certificate

## Examples

    iex> cs = Chronicle.Connections.ConnectionString.default()
    iex> cs.server_address.host
    "localhost"

    iex> cs = Chronicle.Connections.ConnectionString.parse("chronicle://localhost:35000?disableTls=true")
    iex> cs.disable_tls
    true

# `t`

```elixir
@type t() :: %Chronicle.Connections.ConnectionString{
  api_key: String.t() | nil,
  auth_port: non_neg_integer() | nil,
  certificate_password: String.t() | nil,
  certificate_path: String.t() | nil,
  disable_tls: boolean(),
  password: String.t() | nil,
  query_parameters: %{optional(String.t()) => String.t()},
  scheme: String.t(),
  server_address:
    Chronicle.Connections.ConnectionString.ServerAddress.t() | nil,
  username: String.t() | nil
}
```

# `authentication_mode`

```elixir
@spec authentication_mode(t()) :: :client_credentials | :api_key | :none
```

Returns the configured authentication mode for the connection string.

Returns `:client_credentials` if username and password are set,
`:api_key` if an API key is set, or `:none` if no authentication is configured.

Raises `ArgumentError` if both client credentials and API key are specified.

## Examples

    iex> cs = Chronicle.Connections.ConnectionString.parse("chronicle://user:pass@server:35000")
    iex> Chronicle.Connections.ConnectionString.authentication_mode(cs)
    :client_credentials

# `default`

```elixir
@spec default() :: t()
```

Returns the default local development connection string without authentication.

Connects to `localhost:35000` with no TLS or credentials.

# `development`

```elixir
@spec development() :: t()
```

Returns the Chronicle development connection string with default credentials.

Uses the built-in development client ID and secret for a local Chronicle instance.

# `format`

```elixir
@spec format(t()) :: String.t()
```

Converts the connection string struct back to its URI string representation.

## Examples

    iex> cs = Chronicle.Connections.ConnectionString.default()
    iex> Chronicle.Connections.ConnectionString.format(cs)
    "chronicle://localhost:35000"

# `parse`

```elixir
@spec parse(String.t()) :: t()
```

Parses a Chronicle connection string into a `ConnectionString` struct.

Raises `ArgumentError` if the connection string is malformed.

## Examples

    iex> cs = Chronicle.Connections.ConnectionString.parse("chronicle://server:35000?apiKey=abc")
    iex> cs.api_key
    "abc"

# `with_api_key`

```elixir
@spec with_api_key(t(), String.t()) :: t()
```

Returns a new connection string with the given API key.

Removes any existing client credentials.

# `with_credentials`

```elixir
@spec with_credentials(t(), String.t(), String.t()) :: t()
```

Returns a new connection string with the given client credentials.

Removes any existing API key.

---

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