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-keyMultiple hosts
A chronicle:// connection string may list more than one host, comma-separated.
Every configured host is a candidate the load balancer can pick between (see
Chronicle.Connections.Connection):
chronicle://host1:35000,host2:35000,host3:35000
chronicle://client-id:secret@host1:35000,host2:35000IPv6 literals must use bracket notation, exactly like standard URLs:
chronicle://[::1]:35000
chronicle://[2001:db8::1]:35000,[2001:db8::2]:35000A host without an explicit port uses the default (35000).
DNS SRV discovery
chronicle+srv:// resolves its single host to a set of Chronicle server
addresses via a DNS SRV lookup (query name _chronicle._tcp.<host>) instead of
listing hosts explicitly. It is re-resolved on every connect/reconnect attempt,
so membership changes are picked up automatically:
chronicle+srv://my-chronicle-serviceA chronicle+srv:// connection string supports only a single host; use
srvNameServer to query a specific DNS server instead of the system resolver.
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
apiKeyquery parameter:chronicle://host:35000?apiKey=my-key
Query Parameters
apiKey— API key for authenticationdisableTls— set to"true"to disable TLS (only for connecting through something else that terminates TLS for you, such as a plaintext-terminating proxy; the Chronicle kernel requires TLS on its single port, including in development)skipTlsValidation— set to"false"to require full TLS certificate chain validation against the system trust store. Distinct fromdisableTls: TLS stays on either way, this only controls whether the chain is validated. Defaults totrue— a Chronicle kernel commonly serves an auto-generated self-signed certificate, so validation is skipped unless explicitly turned on.certificatePath— path to a client certificate filecertificatePassword— password for the client certificateloadBalancer— strategy used to pick among multiple hosts (or SRV-resolved addresses):"least-connections"(default),"round-robin", or"random". SeeChronicle.Connections.LoadBalancer.srvNameServer— forchronicle+srv://, a specific DNS server ("host"or"host:port") to query instead of the system resolver.
Examples
iex> cs = Chronicle.Connections.ConnectionString.default()
iex> Chronicle.Connections.ConnectionString.server_address(cs).host
"localhost"
iex> cs = Chronicle.Connections.ConnectionString.parse("chronicle://localhost:35000?disableTls=true")
iex> cs.disable_tls
trueSummary
Functions
Returns the configured authentication mode for the connection string.
Returns the default local development connection string without authentication.
Returns the Chronicle development connection string with default credentials.
Converts the connection string struct back to its URI string representation.
Parses a Chronicle connection string into a ConnectionString struct.
Returns the first configured server address.
Returns a new connection string with the given API key.
Returns a new connection string with the given client credentials.
Types
@type load_balancer_strategy() :: :least_connections | :round_robin | :random
@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(), load_balancer: load_balancer_strategy(), password: String.t() | nil, query_parameters: %{optional(String.t()) => String.t()}, scheme: String.t(), server_addresses: [Chronicle.Connections.ConnectionString.ServerAddress.t()], skip_tls_validation: boolean(), srv_name_server: String.t() | nil, username: String.t() | nil }
Functions
@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@spec default() :: t()
Returns the default local development connection string without authentication.
Connects to localhost:35000 with no TLS or credentials.
@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.
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"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"@spec server_address(t()) :: Chronicle.Connections.ConnectionString.ServerAddress.t() | nil
Returns the first configured server address.
Provided as a convenience for callers that only need a single address — such
as the OAuth2 token endpoint, which authenticates against the first
configured host rather than the address the load balancer eventually picks
for the gRPC channel itself. Multi-host and chronicle+srv:// connection
strings still resolve and select among every address for the channel; see
Chronicle.Connections.Connection and Chronicle.Connections.LoadBalancer.
Returns a new connection string with the given API key.
Removes any existing client credentials.
Returns a new connection string with the given client credentials.
Removes any existing API key.