defmodule ConfigCat do
@moduledoc """
The ConfigCat Elixir SDK.
`ConfigCat` provides a `Supervisor` that must be added to your applications
supervision tree and an API for accessing your ConfigCat settings.
## Add ConfigCat to Your Supervision Tree
Your application's supervision tree might need to be different, but the most
basic approach is to add `ConfigCat` as a child of your top-most supervisor.
```elixir
# lib/my_app/application.ex
def start(_type, _args) do
children = [
# ... other children ...
{ConfigCat, [sdk_key: "YOUR SDK KEY"]}
]
opts = [strategy: :one_for_one, name: MyApp.Supervisor]
Supervisor.start_link(children, opts)
end
```
### Options
`ConfigCat` takes a number of keyword arguments:
- `sdk_key`: **REQUIRED** The SDK key for accessing your ConfigCat settings.
Go to the [Connect your application](https://app.configcat.com/sdkkey) tab
to get your SDK key.
```elixir
{ConfigCat, [sdk_key: "YOUR SDK KEY"]}
```
- `base_url`: **OPTIONAL** Allows you to specify a custom URL for fetching
your ConfigCat settings.
```elixir
{ConfigCat, [sdk_key: "YOUR SDK KEY", base_url: "https://my-cdn.example.com"]}
```
- `cache`: **OPTIONAL** Custom cache implementation. By default, `ConfigCat`
uses its own in-memory cache, but you can also provide the name of a module
that implements the `ConfigCat.ConfigCache` behaviour if you want to provide
your own cache (e.g. based on Redis). If your cache implementation requires
supervision, it is your application's responsibility to provide that.
```elixir
{ConfigCat, [sdk_key: "YOUR SDK KEY", cache: MyCustomCacheModule]}
```
- `cache_policy`: **OPTIONAL** Specifies the [polling
mode](https://configcat.com/docs/sdk-reference/elixir#polling-modes) used by
`ConfigCat`. Defaults to auto-polling mode with a 60 second poll interval.
You can specify a different polling mode or polling interval using
`ConfigCat.CachePolicy.auto/1`, `ConfigCat.CachePolicy.lazy/1`, or
`ConfigCat.CachePolicy.manual/0`.
```elixir
{ConfigCat, [sdk_key: "YOUR SDK KEY", cache_policy: ConfigCat.CachePolicy.manual()]}
```
- `connect_timeout_milliseconds`: **OPTIONAL** timeout for establishing a TCP
or SSL connection, in milliseconds. Default is 8000.
```elixir
{ConfigCat, [sdk_key: "YOUR SDK KEY", connect_timeout_milliseconds: 8000]}
```
- `data_governance`: **OPTIONAL** Describes the location of your feature flag
and setting data within the ConfigCat CDN. This parameter needs to be in
sync with your Data Governance preferences. Defaults to `:global`. [More
about Data Governance](https://configcat.com/docs/advanced/data-governance).
```elixir
{ConfigCat, [sdk_key: "YOUR SDK KEY", data_governance: :eu_only]}
```
- `default_user`: **OPTIONAL** user object that will be used as fallback when
there's no user parameter is passed to the getValue() method.
```elixir
{ConfigCat, [sdk_key: "YOUR SDK KEY", default_user: User.new("test@test.com")]}
```
- `flag_overrides`: **OPTIONAL** Specify a data source to use for [local flag
overrides](https://configcat.com/docs/sdk-reference/elixir#flag-overrides).
The data source must implement the `ConfigCat.OverrideDataSource` protocol.
`ConfigCat.LocalFileDataSource` and `ConfigCat.LocalMapDataSource` are
provided for you to use.
- `hooks`: **OPTIONAL** Specify callback functions to be called when
particular events are fired by the SDK. See `ConfigCat.Hooks`.
- `http_proxy`: **OPTIONAL** Specify this option if you need to use a proxy
server to access your ConfigCat settings. You can provide a simple URL, like
`https://my_proxy.example.com` or include authentication information, like
`https://user:password@my_proxy.example.com/`.
```elixir
{ConfigCat, [sdk_key: "YOUR SDK KEY", http_proxy: "https://my_proxy.example.com"]}
```
- `name`: **OPTIONAL** A unique identifier for this instance of `ConfigCat`.
Defaults to `ConfigCat`. Must be provided if you need to run more than one
instance of `ConfigCat` in the same application. If you provide a `name`,
you must then pass that name to all of the API functions using the `client`
option. See `Multiple Instances` below.
```elixir
{ConfigCat, [sdk_key: "YOUR SDK KEY", name: :unique_name]}
```
```elixir
ConfigCat.get_value("setting", "default", client: :unique_name)
```
- `offline`: **OPTIONAL** # Indicates whether the SDK should be initialized
in offline mode or not.
```elixir
{ConfigCat, [sdk_key: "YOUR SDK KEY", offline: true]}
```
- `read_timeout_milliseconds`: **OPTIONAL** timeout for receiving an HTTP
response from the socket, in milliseconds. Default is 5000.
```elixir
{ConfigCat, [sdk_key: "YOUR SDK KEY", read_timeout_milliseconds: 5000]}
```
### Multiple Instances
If you need to run more than one instance of `ConfigCat`, there are two ways
you can do it.
#### Module-Based
You can create a module that `use`s `ConfigCat` and then call the ConfigCat
API functions on that module. This is the recommended option, as it makes the
calling code a bit clearer and simpler.
You can pass any of the options listed above as arguments to `use ConfigCat`
or specify them in your supervisor. Arguments specified by the supervisor take
precedence over those provided to `use ConfigCat`.
```elixir
# lib/my_app/first_flags.ex
defmodule MyApp.FirstFlags do
use ConfigCat, sdk_key: "sdk_key_1"
end
# lib/my_app/second_flags.ex
defmodule MyApp.SecondFlags do
use ConfigCat, sdk_key: "sdk_key_2"
end
# lib/my_app/application.ex
def start(_type, _args) do
children = [
# ... other children ...
FirstFlags,
SecondFlags,
]
opts = [strategy: :one_for_one, name: MyApp.Supervisor]
Supervisor.start_link(children, opts)
end
# Calling code:
FirstFlags.get_value("someKey", "default value")
SecondFlags.get_value("otherKey", "other default")
```
#### Explicit Client
If you prefer not to use the module-based solution, you can instead add
multiple `ConfigCat` children to your application's supervision tree. You will
need to give `ConfigCat` a unique `name` option for each, as well as using
`Supervisor.child_spec/2` to provide a unique `id` for each instance.
When calling the ConfigCat API functions, you'll pass a `client:` keyword
argument with the unique `name` you gave to that instance.
```elixir
# lib/my_app/application.ex
def start(_type, _args) do
children = [
# ... other children ...
Supervisor.child_spec({ConfigCat, [sdk_key: "sdk_key_1", name: :first]}, id: :config_cat_1),
Supervisor.child_spec({ConfigCat, [sdk_key: "sdk_key_2", name: :second]}, id: :config_cat_2),
]
opts = [strategy: :one_for_one, name: MyApp.Supervisor]
Supervisor.start_link(children, opts)
end
# Calling code:
ConfigCat.get_value("someKey", "default value", client: :first)
ConfigCat.get_value("otherKey", "other default", client: :second)
```
## Use the API
Once `ConfigCat` has been started as part of your application's supervision
tree, you can use its API to access your settings.
```elixir
ConfigCat.get_value("isMyAwesomeFeatureEnabled", false)
```
By default, all of the public API functions will communicate with the default
instance of the `ConfigCat` application.
If you are running multiple instances of `ConfigCat`, you must provide the
`client` option to the functions, passing along the unique name you specified
above.
```elixir
ConfigCat.get_value("isMyAwesomeFeatureEnabled", false, client: :second)
```
"""
alias ConfigCat.CachePolicy
alias ConfigCat.Client
alias ConfigCat.Config
alias ConfigCat.EvaluationDetails
alias ConfigCat.Hooks
alias ConfigCat.OverrideDataSource
alias ConfigCat.User
require ConfigCat.Constants, as: Constants
@typedoc "Options that can be passed to all API functions."
@type api_option :: {:client, instance_id()}
@typedoc """
Data Governance mode
[More about Data Governance](https://configcat.com/docs/advanced/data-governance)
"""
@type data_governance :: :eu_only | :global
@typedoc "Identifier of a specific instance of `ConfigCat`."
@type instance_id :: atom()
@typedoc "The name of a configuration setting."
@type key :: Config.key()
@typedoc "An option that can be provided when starting `ConfigCat`."
@type option ::
{:base_url, String.t()}
| {:cache, module()}
| {:cache_policy, CachePolicy.t()}
| {:connect_timeout_milliseconds, non_neg_integer()}
| {:data_governance, data_governance()}
| {:default_user, User.t()}
| {:flag_overrides, OverrideDataSource.t()}
| {:hooks, [Hooks.option()]}
| {:http_proxy, String.t()}
| {:name, instance_id()}
| {:offline, boolean()}
| {:read_timeout_milliseconds, non_neg_integer()}
| {:sdk_key, String.t()}
@type options :: [option()]
@typedoc "The return value of the `force_refresh/1` function."
@type refresh_result :: :ok | {:error, String.t()}
@typedoc "The actual value of a configuration setting."
@type value :: Config.value()
@typedoc "The name of a variation being tested."
@type variation_id :: Config.variation_id()
@doc """
Builds a child specification to use in a Supervisor.
Normally not called directly by your code. Instead, it will be
called by your application's Supervisor once you add `ConfigCat`
to its supervision tree.
"""
@spec child_spec(options()) :: Supervisor.child_spec()
defdelegate child_spec(options), to: ConfigCat.Supervisor
@doc """
Queries all settings keys in your configuration.
### Options
- `client`: If you are running multiple instances of `ConfigCat`,
provide the `client: :unique_name` option, specifying the name you
configured for the instance you want to access.
"""
@spec get_all_keys([api_option()]) :: [key()]
def get_all_keys(options \\ []) do
options
|> client()
|> GenServer.call(:get_all_keys, Constants.fetch_timeout())
end
@doc "See `get_value/4`."
@spec get_value(key(), value(), User.t() | [api_option()]) :: value()
def get_value(key, default_value, user_or_options \\ []) do
if Keyword.keyword?(user_or_options) do
get_value(key, default_value, nil, user_or_options)
else
get_value(key, default_value, user_or_options, [])
end
end
@doc """
Retrieves a setting value from your configuration.
Retrieves the setting named `key` from your configuration. To use ConfigCat's
[targeting](https://configcat.com/docs/advanced/targeting) feature, provide a
`ConfigCat.User` struct containing the information used by the targeting
rules.
Returns the value of the setting, or `default_value` if an error occurs.
### Options
- `client`: If you are running multiple instances of `ConfigCat`, provide the
`client: :unique_name` option, specifying the name you configured for the
instance you want to access.
"""
@spec get_value(key(), value(), User.t() | nil, [api_option()]) :: value()
def get_value(key, default_value, user, options) do
options
|> client()
|> GenServer.call({:get_value, key, default_value, user}, Constants.fetch_timeout())
end
@doc "See `get_value_details/4`."
@spec get_value_details(key(), value(), User.t() | [api_option()]) :: EvaluationDetails.t()
def get_value_details(key, default_value, user_or_options \\ []) do
if Keyword.keyword?(user_or_options) do
get_value_details(key, default_value, nil, user_or_options)
else
get_value_details(key, default_value, user_or_options, [])
end
end
@doc """
Fetches the value and evaluation details of a feature flag or setting.
Retrieves the setting named `key` from your configuration. To use ConfigCat's
[targeting](https://configcat.com/docs/advanced/targeting) feature, provide a
`ConfigCat.User` struct containing the information used by the targeting
rules.
Returns the evaluation details for the setting, including the value. If an
error occurs while performing the evaluation, it will be captured in the
`:error` field of the `ConfigCat.EvaluationDetails` struct.
### Options
- `client`: If you are running multiple instances of `ConfigCat`, provide the
`client: :unique_name` option, specifying the name you configured for the
instance you want to access.
"""
@spec get_value_details(key(), value(), User.t() | nil, [api_option()]) :: EvaluationDetails.t()
def get_value_details(key, default_value, user, options) do
options
|> client()
|> GenServer.call({:get_value_details, key, default_value, user}, Constants.fetch_timeout())
end
@doc "See `get_all_value_details/2`."
@spec get_all_value_details(User.t() | [api_option()]) :: [EvaluationDetails.t()]
def get_all_value_details(user_or_options \\ []) do
if Keyword.keyword?(user_or_options) do
get_all_value_details(nil, user_or_options)
else
get_all_value_details(user_or_options, [])
end
end
@doc """
Fetches the values and evaluation details of all feature flags and settings.
To use ConfigCat's [targeting](https://configcat.com/docs/advanced/targeting)
feature, provide a `ConfigCat.User` struct containing the information used by
the targeting rules.
Returns evaluation details for all settings and feature flags, including their
values. If an error occurs while performing the evaluation, it will be
captured in the `:error` field of the individual `ConfigCat.EvaluationDetails`
structs.
### Options
- `client`: If you are running multiple instances of `ConfigCat`, provide the
`client: :unique_name` option, specifying the name you configured for the
instance you want to access.
"""
@spec get_all_value_details(User.t() | nil, [api_option()]) :: [EvaluationDetails.t()]
def get_all_value_details(user, options) do
options
|> client()
|> GenServer.call({:get_all_value_details, user}, Constants.fetch_timeout())
end
@doc """
Fetches the name and value of the setting corresponding to a variation id.
Returns a tuple containing the setting name and value, or `nil` if an error
occurs.
### Options
- `client`: If you are running multiple instances of `ConfigCat`, provide the
`client: :unique_name` option, specifying the name you configured for the
instance you want to access.
"""
@spec get_key_and_value(variation_id(), [api_option()]) :: {key(), value()} | nil
def get_key_and_value(variation_id, options \\ []) do
options
|> client()
|> GenServer.call({:get_key_and_value, variation_id}, Constants.fetch_timeout())
end
@doc """
Fetches the values of all feature flags or settings from your configuration.
To use ConfigCat's [targeting](https://configcat.com/docs/advanced/targeting)
feature, provide a `ConfigCat.User` struct containing the information used by
the targeting rules.
Returns a map of all key value pairs.
### Options
- `client`: If you are running multiple instances of `ConfigCat`, provide the
`client: :unique_name` option, specifying the name you configured for the
instance you want to access.
"""
@spec get_all_values(User.t() | nil, [api_option()]) :: %{key() => value()}
def get_all_values(user, options \\ []) do
options
|> client()
|> GenServer.call({:get_all_values, user}, Constants.fetch_timeout())
end
@doc """
Force a refresh of the configuration from ConfigCat's CDN.
Depending on the polling mode you're using, `ConfigCat` may automatically
fetch your configuration during normal operation. Call this function to
force a manual refresh when you want one.
If you are using manual polling mode (`ConfigCat.CachePolicy.manual/0`),
this is the only way to fetch your configuration.
Returns `:ok`.
### Options
- `client`: If you are running multiple instances of `ConfigCat`, provide the
`client: :unique_name` option, specifying the name you configured for the
instance you want to access.
"""
@spec force_refresh([api_option()]) :: refresh_result()
def force_refresh(options \\ []) do
options
|> client()
|> GenServer.call(:force_refresh, Constants.fetch_timeout())
end
@doc """
Sets the default user.
Returns `:ok`.
### Options
- `client`: If you are running multiple instances of `ConfigCat`, provide the
`client: :unique_name` option, specifying the name you configured for the
instance you want to access.
"""
@spec set_default_user(User.t(), [api_option()]) :: :ok
def set_default_user(user, options \\ []) do
options
|> client()
|> GenServer.call({:set_default_user, user}, Constants.fetch_timeout())
end
@doc """
Clears the default user.
Returns `:ok`.
### Options
- `client`: If you are running multiple instances of `ConfigCat`, provide the
`client: :unique_name` option, specifying the name you configured for the
instance you want to access.
"""
@spec clear_default_user([api_option()]) :: :ok
def clear_default_user(options \\ []) do
options
|> client()
|> GenServer.call(:clear_default_user, Constants.fetch_timeout())
end
@doc """
Configures the SDK to allow HTTP requests.
Returns `:ok`.
### Options
- `client`: If you are running multiple instances of `ConfigCat`, provide the
`client: :unique_name` option, specifying the name you configured for the
instance you want to access.
"""
@spec set_online([api_option()]) :: :ok
def set_online(options \\ []) do
options
|> client()
|> GenServer.call(:set_online, Constants.fetch_timeout())
end
@doc """
Configures the SDK to not initiate HTTP requests and work only from its cache.
Returns `:ok`.
### Options
- `client`: If you are running multiple instances of `ConfigCat`, provide the
`client: :unique_name` option, specifying the name you configured for the
instance you want to access.
"""
@spec set_offline([api_option()]) :: :ok
def set_offline(options \\ []) do
options
|> client()
|> GenServer.call(:set_offline, Constants.fetch_timeout())
end
@doc """
Returns `true` when the SDK is configured not to initiate HTTP requests, otherwise `false`.
### Options
- `client`: If you are running multiple instances of `ConfigCat`, provide the
`client: :unique_name` option, specifying the name you configured for the
instance you want to access.
"""
@spec offline?([api_option()]) :: boolean()
def offline?(options \\ []) do
options
|> client()
|> GenServer.call(:offline?, Constants.fetch_timeout())
end
@doc """
Return the current hook callbacks.
### Options
- `client`: If you are running multiple instances of `ConfigCat`, provide the
`client: :unique_name` option, specifying the name you configured for the
instance you want to access.
"""
@spec hooks([api_option()]) :: Hooks.t()
def hooks(options \\ []) do
Keyword.get(options, :client, __MODULE__)
end
defp client(options) do
options
|> Keyword.get(:client, __MODULE__)
|> Client.via_tuple()
end
defmacro __using__(default_options) do
quote do
@client Keyword.get(unquote(default_options), :name, __MODULE__)
@spec child_spec(ConfigCat.options()) :: Supervisor.child_spec()
def child_spec(options) do
options =
unquote(default_options)
|> Keyword.merge(options)
|> Keyword.put_new(:name, @client)
Supervisor.child_spec({ConfigCat, options}, id: @client)
end
@spec get_all_keys :: [ConfigCat.key()]
def get_all_keys do
ConfigCat.get_all_keys(client: @client)
end
@spec get_value(ConfigCat.key(), ConfigCat.value(), ConfigCat.User.t() | nil) ::
ConfigCat.value()
def get_value(key, default_value, user \\ nil) do
ConfigCat.get_value(key, default_value, user, client: @client)
end
@spec get_value_details(ConfigCat.key(), ConfigCat.value(), ConfigCat.User.t() | nil) ::
ConfigCat.EvaluationDetails.t()
def get_value_details(key, default_value, user \\ nil) do
ConfigCat.get_value_details(key, default_value, user, client: @client)
end
@spec get_all_value_details(ConfigCat.User.t() | nil) :: [EvaluationDetails.t()]
def get_all_value_details(user \\ nil) do
ConfigCat.get_all_value_details(user, client: @client)
end
@spec get_key_and_value(ConfigCat.variation_id()) ::
{ConfigCat.key(), ConfigCat.value()} | nil
def get_key_and_value(variation_id) do
ConfigCat.get_key_and_value(variation_id, client: @client)
end
@spec get_all_values(ConfigCat.User.t() | nil) :: %{ConfigCat.key() => ConfigCat.value()}
def get_all_values(user \\ nil) do
ConfigCat.get_all_values(user, client: @client)
end
@spec force_refresh :: ConfigCat.refresh_result()
def force_refresh do
ConfigCat.force_refresh(client: @client)
end
@spec set_default_user(ConfigCat.User.t()) :: :ok
def set_default_user(user) do
ConfigCat.set_default_user(user, client: @client)
end
@spec clear_default_user :: :ok
def clear_default_user do
ConfigCat.clear_default_user(client: @client)
end
@spec set_online :: :ok
def set_online do
ConfigCat.set_online(client: @client)
end
@spec set_offline :: :ok
def set_offline do
ConfigCat.set_offline(client: @client)
end
@spec offline? :: boolean()
def offline? do
ConfigCat.offline?(client: @client)
end
@spec hooks :: ConfigCat.Hooks.t()
def hooks do
ConfigCat.hooks(client: @client)
end
end
end
end
