Flippant v0.4.0 Flippant View Source

Feature toggling for Elixir applications.

Flippant defines features in terms of actors, groups, and rules:

  • Actors - Typically an actor is a %User{} or some other persistent struct that identifies who is using your application.
  • Groups - Groups identify and qualify actors. For example, the admins group would identify actors that are admins, while beta-testers may identify a few actors that are testing a feature. It is entirely up to you to define groups in your application.
  • Rules - Rules bind groups with individual features. These are evaluated against actors to see if a feature should be enabled.

Let’s walk through setting up a few groups and rules.

Groups

First, a group that nobody can belong to. This is useful for disabling a feature without deleting it. Groups are registered with a name and an evalutation function. In this case the name of our group is “nobody”, and the function always returns false:

Flippant.register("nobody", fn(_actor, _values) -> false end)

Now the opposite, a group that everybody can belong to:

Flippant.register("everybody", fn(_actor, _values) -> true end)

To be more specific and define staff only features we define a “staff” group:

Flippant.register("staff", fn
  %User{staff?: staff?}, _values -> staff?
end)

Lastly, we’ll roll out a feature out to a percentage of the actors. It expects a list of integers between 1 and 10. If the user’s id modulo 10 is in the list, then the feature is enabled:

Flippant.register("adopters", fn
  _actor, [] -> false
  %User{id: id}, samples -> rem(id, 10) in samples
end)

With some core groups defined we can set up some rules now.

Rules

Rules are comprised of a name, a group, and an optional set of values. Starting with a simple example that builds on the groups we have already created, we’ll enable the “search” feature:

# Any staff can use the "search" feature
Flippant.enable("search", "staff")

# 30% of "adopters" can use the "search" feature as well
Flippant.enable("search", "adopters", [0, 1, 2])

Because rules are built of binaries and simple data they can be defined or refined at runtime. In fact, this is a crucial part of feature toggling. Rules can be added, removed or modified at runtime.

# Turn search off for adopters
Flippant.disable("search", "adopters")

# On second thought, enable it again for 10% of users
Flippant.enable("search", "adopters", [3])

With a set of groups and rules defined we can check whether a feature is enabled for a particular actor:

staff_user = %User{id: 1, staff?: true}
early_user = %User{id: 2, staff?: false}
later_user = %User{id: 3, staff?: false}

Flippant.enabled?("search", staff_user) #=> true, staff
Flippant.enabled?("search", early_user) #=> false, not an adopter
Flippant.enabled?("search", later_user) #=> true, is an adopter

If an actor qualifies for multiple groups and any of the rules evaluate to true that feature will be enabled for them. Think of the “nobody” and “everybody” groups that were defined earlier:

Flippant.enable("search", "everybody")
Flippant.enable("search", "nobody")

Flippant.enabled?("search", %User{}) #=> true

Breakdown

Evaluating rules requires a round trip to the database. Clearly, with a lot of rules it is inefficient to evaluate each one individually. The breakdown/1 function helps with this scenario:

Flippant.enable("search", "staff")
Flippant.enable("delete", "everybody")
Flippant.enable("invite", "nobody")

Flippant.breakdown(%User{id: 1, staff?: true})
#=> %{"search" => true, "delete" => true, "invite" => false}

The breakdown is a simple map of binary keys to boolean values. This is particularly useful for single page applications where you can serialize the breakdown on boot or send it back from an endpoint as JSON.

Adapters

Feature rules are stored in adapters. Flippant comes with a few base adapters:

  • Flippant.Adapters.Memory - An in-memory adapter, ideal for testing (see below).
  • Flippant.Adapters.Postgres - A postgrex powered PostgreSQL adapter.
  • Flippant.Adapters.Redis - A redix powered Redis adapter.

For adapter specific options reference the start_link/1 function of each.

Some adapters, notably the Postgres adapter, may require setup before they can be used. To simplify the setup process you can run Flippant.setup(), or see the adapters documentation for migration details.

Testing

Testing is simplest with the Memory adapter. Within config/test.exs override the :adapter:

config :flippant, adapter: Flippant.Adapters.Memory

The memory adapter will be cleared whenever the application is restarted, or it can be cleared between test runs using Flippant.clear(:features).

Defining Groups on Application Start

Group definitions are stored in a process, which requires the Flippant application to be started. That means they can’t be defined within a configuration file and should instead be linked from Application.start/2. You can make Flippant.register/2 calls directly from the application module, or put them into a separate module and start it as a temporary worker. Here we’re starting a temporary worker with the rest of an application:

defmodule MyApp do
  use Application

  def start(_type, _args) do
    import Supervisor.Spec, warn: false

    children = [
      worker(MyApp.Flippant, [], restart: :temporary)
    ]

    opts = [strategy: :one_for_one, name: MyApp.Supervisor]

    Supervisor.start_link(children, opts)
  end
end

Note that the worker is defined with restart: :temporary. Now, define the MyApp.Flippant module:

defmodule MyApp.Flippant do
  def start_link do
    Flippant.register("everybody", &everybody?/2)
    Flippant.register("nobody", &nobody?/2)
    Flippant.register("staff", &staff?/2)

    :ignore
  end

  def everybody?(_, _), do: true
  def nobody?(_, _), do: false
  def staff?(%User{staff?: staff?}, _), do: staff?
end

Customizing Serialization

Storing values along with rules is an important part of scoping features. Values can be any type of data structure, including integers, binaries, lists or maps. This adds a great deal of additional power to group evaluation, but it means that the values must be serialized in a high fidelity way.

By default, values are stored using Erlang’s binary term storage. This works perfectly fine, but isn’t especially readable and isn’t compatible with other languages. If you’d prefer to use JSON or MessagePack instead you can provide a custom serializer and configure Flippant to use that instead. For example, to use MessagePack via the Msgpax libary:

defmodule MyApp.Serializer do
  @behaviour Flippant.Serializer

  def dump(value), do: Msgpax.pack!(value)
  def load(value), do: Msgpax.unpack!(value)
end

Then, within config.exs set the serializer:

config :flippant, serializer: MyApp.Serializer

Not all adapters have customizable serialization. For example, the Postgres adapter uses the jsonb type and therefor requires a JSON serializer.

Link to this section Summary

Functions

Retrieve the pid of the configured adapter process

Add a new feature without any rules

Generate a mapping of all features and associated rules

Purge registered groups, features, or both

Disable a feature for a particular group

Enable a feature for a particular group

Check if a particular feature is enabled for an actor

Check whether a given feature has been registered

List all known features or only features enabled for a particular group

Register a new group name and function

List all of the registered groups as a map where the keys are the names and values are the functions

Fully remove a feature for all groups

Rename an existing feature

Prepare the adapter for usage

Link to this section Functions

Link to this function adapter() View Source
adapter() :: pid | nil

Retrieve the pid of the configured adapter process.

This will return nil if the adapter hasn’t been started.

Link to this function add(feature) View Source
add(binary) :: :ok

Add a new feature without any rules.

Adding a feature does not enable it for any groups, that can be done using enable/2 or enable/3.

Examples

Flippant.add("search")
#=> :ok
Link to this function breakdown(actor \\ :all) View Source
breakdown(map | struct | :all) :: map

Generate a mapping of all features and associated rules.

Breakdown without any arguments defaults to :all, and will list all registered features along with their group and value metadata. It is the only way to retrieve a snapshot of all the features in the system. The operation is optimized for round-trip efficiency.

Alternatively, breakdown takes a single actor argument, typically a %User{} struct or some other entity. It generates a map outlining which features are enabled for the actor.

Examples

Assuming the groups awesome, heinous, and radical, and the features search, delete and invite are enabled, the breakdown would look like:

Flippant.breakdown()
#=> %{"search" => %{"awesome" => [], "heinous" => []},
      "delete" => %{"radical" => []},
      "invite" => %{"heinous" => []}}

Getting the breakdown for a particular actor:

actor = %User{ id: 1, awesome?: true, radical?: false}
Flippant.breakdown(actor)
#=> %{"delete" => true, "search" => false}
Link to this function clear(selection \\ nil) View Source
clear(:features | :groups) :: :ok

Purge registered groups, features, or both.

This is particularly useful in testing when you want to reset to a clean slate after a test.

Examples

Clear everything:

Flippant.clear()
#=> :ok

Clear only features:

Flippant.clear(:features)
#=> :ok

Clear only groups:

Flippant.clear(:groups)
#=> :ok
Link to this function disable(feature, group, values \\ []) View Source

Disable a feature for a particular group.

The feature is kept in the registry, but any rules for that group are removed.

Examples

Disable the search feature for the adopters group:

Flippant.disable("search", "adopters")
#=> :ok

Alternatively, individual values may be disabled for a group. This is useful when a group should stay enabled and only a single value (i.e. user id) needs to be removed.

Disable search feature for a user in the adopters group:

Flippant.disable("search", "adopters", [123])
#=> :ok
Link to this function enable(feature, group, values \\ []) View Source
enable(binary, binary, [any]) :: :ok

Enable a feature for a particular group.

Features can be enabled for a group along with a set of values. The values will be passed along to the group’s registered function when determining whether a feature is enabled for a particular actor.

Values are useful when limiting a feature to a subset of actors by id or some other distinguishing factor. Value serialization can be customized by using an alternate module implementing the Flippant.Serializer behaviour.

Examples

Enable the search feature for the radical group, without any specific values:

Flippant.enable("search", "radical")
#=> :ok

Assuming the group awesome checks whether an actor’s id is in the list of values, you would enable the search feature for actors 1, 2 and 3 like this:

Flippant.enable("search", "awesome", [1, 2, 3])
#=> :ok
Link to this function enabled?(feature, actor) View Source
enabled?(binary, map | struct) :: boolean

Check if a particular feature is enabled for an actor.

If the actor belongs to any groups that have access to the feature then it will be enabled.

Examples

Flippant.enabled?("search", actor)
#=> false
Link to this function exists?(feature, group \\ :any) View Source
exists?(binary, binary | :any) :: boolean

Check whether a given feature has been registered.

If a group is provided it will check whether the feature has any rules for that group.

Examples

Flippant.exists?("search")
#=> false

Flippant.add("search")
Flippant.exists?("search")
#=> true
Link to this function features(group \\ :all) View Source
features(:all | binary) :: [binary]

List all known features or only features enabled for a particular group.

Examples

Given the features search and delete:

Flippant.features()
#=> ["search", "delete"]

Flippant.features(:all)
#=> ["search", "delete"]

If the search feature were only enabled for the awesome group:

Flippant.features("awesome")
#=> ["search"]
Link to this function register(group, fun) View Source
register(binary, (any, list -> boolean)) :: :ok

Register a new group name and function.

The function must have an arity of 2 or it won’t be accepted. Registering a group with the same name will overwrite the previous group.

Examples

Flippant.register("evens", & rem(&1.id, 2) == 0)
#=> :ok
Link to this function registered() View Source
registered() :: map

List all of the registered groups as a map where the keys are the names and values are the functions.

Examples

Flippant.registered()
#=> %{"staff" => #Function<20.50752066/0}
Link to this function remove(feature) View Source
remove(binary) :: :ok

Fully remove a feature for all groups.

Examples

Flippant.remove("search")
:ok
Link to this function rename(old_name, new_name) View Source
rename(binary, binary) :: :ok

Rename an existing feature.

If the new feature name already exists it will overwritten and all of the rules will be replaced.

Examples

Flippant.rename("search", "super-search")
:ok

Prepare the adapter for usage.

For adapters that don’t require any setup this is a no-op. For other adapters, such as Postgres, which require a schema/table to operate this will create the necessary table.

Examples

Flippant.setup()
:ok