Unleash

Unleash is a client for the Unleash Toggle Service.

The primary use is Unleash.enabled?/2 or Unleash.enabled?/3 to check whether or not the given feature flag is enabled.

iex> Unleash.enabled?(:my_feature)

false



iex> Unleash.enabled?(:my_feature, true)

true



iex> context = %{user_id: "ID", custom_field: "Unleash"}



iex> Unleash.enabled?(:my_feature, context)

true



iex> Unleash.enabled?(:my_feature, context, false)

true

Context fields are transformed internally when validated against constraints, e.g. :user_id becomes "userId".

Installation

If available in Hex, the package can be installed by adding unleash_ex to your list of dependencies in mix.exs:

def deps do

  [

    {:unleash, "~> 1.11"}

  ]

end

Unleash works by default with Req, so make sure to explicit declare it in your list of dependencies. For backward compatibility reasons, Unleash also works with Mojito. You can use your own HTTP client module by implementing the Unleash.HTTPClientAdapter behaviour and passing the module name in the :http_client configuration.

Configuration

There are many configuration options available, and they are listed below with their defaults. These go into the relevant config/*.exs file.

config :unleash, Unleash,

  url: "", # The URL of the Unleash server to connect to, should include up to http://base.url/api

  appname: "", # The app name, used for registration

  instance_id: "", # The instance ID, used for metrics tracking

  metrics_period: 10 * 60 * 1000, # Send metrics every 10 minutes, in milliseconds

  features_period: 15 * 1000, # Poll for new flags every 15 seconds, in milliseconds

  strategies: Unleash.Strategies, # Which module to request for toggle strategies

  backup_file: nil, # Backup file in the event that contacting the server fails

  custom_http_headers: [], # A keyword list of custom headers to send to the server

  disable_client: false, # Whether or not to enable the client

  disable_metrics: false, # Whether or not to send metrics,

  retries: -1 # How many times to retry on failure, -1 disables limit

  app_env: :dev # Which environment we're in

  http_client: Unleash.ReqClient # What http client will be used. can be Unleash.ReqClient or Unleash.MojitoClient out of the box

:custom_http_headers should follow the format prescribed by t:Unleash.HTTPClientAdapter/0

:strategies should be a module that implements c:Unleash.Strategies.strategies/0. See Extensibility for more information.

Extensibility

If you need to create your own strategies, you can extend the Unleash client by implementing the callbacks in both Unleash.Strategy and Unleash.Strategies as well as passing your new Strategies module in as configuration:

  1. Create your new strategy. See Unleash.Strategy for details on the correct API and Unleash.Strategy.Utils for helpful utilities.

    defmodule MyApp.Strategy.Environment do

      use Unleash.Strategy

    

      def enabled?(%{"environments" => environments}, _context) do

        with {:ok, environment} <- MyApp.Config.get_environment(),

             environment = List.to_string(environment) do

          {Utils.in_list?(environments, environment, &String.downcase/1),

           %{environment: environment, environments: environments}}

        end

      end

    end

  2. Create a new strategies module. See Unleash.Strategies for details on the correct API.

    defmodule MyApp.Strategies do

      @behaviour Unleash.Strategies

    

      def strategies do

        [{"environment", MyApp.Strategy.Environment}] ++ Unleash.Strategies.strateges()

      end

    end

  3. Configure your application to use your new strategies list.

    config :unleash, Unleash, strategies: MyApp.Strategies

Telemetry events

From Unleash 1.9, telemetry events are emitted by the Unleash client library. You can attach to these events and collect metrics or use the Logger, for example:

# An example of checking if Unleash server is reachable during the periodic

# features fetch.

:ok =

  :telemetry.attach_many(

    :duffel_core_feature_heatbeat_metric,

    [

      [:unleash, :client, :fetch_features, :stop],

      [:unleash, :client, :fetch_features, :exception]

    ],

    fn [:unleash, :client, :fetch_features, action],

        _measurements,

        metadata,

        _config ->

      require Logger



      http_status = metadata[:http_response_status]



      if action == :stop and http_status in [200, 304] do

        Logger.info("Fetching features are ok")

      else

        Logger.info("Error on fetching features!!!")

      end

    end,

    %{}

  )

The following events are emitted by the Unleash library: