Feature Flags module

Feature flags are a way to enable or disable features in your application. They are useful for many reasons, including:

  • Allowing you to test features in production before releasing them to all users.

  • Allowing you to do a gradual rollout of a feature to a percentage of users.

Currently, feature flags are only read from the configuration file and cannot be changed at runtime. This means that you will need to restart your application to change the value of a feature flag. In the future, we plan to add support for changing feature flags at runtime and storing them in a database.

Creating a feature flag

Feature flags are defined in the feature-flags section of the configuration file.

feature-flags:
  enabled: true #(1)
  flags:
    - name: feature-1 #(2)
      status: enabled #(3)
    - name: feature-2
      status: disabled
1 Whether feature flags are enabled or not. If this is set to false, all feature flags will be disabled.
2 The name of the feature flag.
3 The status of the feature flag. Possible values are enabled and disabled.

Using a feature flag

Feature flags can be used in your application by using the flags module on Pillars.

import pillars.flags.* //(1)

val flag = flag"feature-1" //(2)
for
    enabled <- pillars.flags.isEnabled(flag) //(3)
    _       <- IO.whenA(enabled)(IO.println("Feature 1 is enabled")) //(4)
    // or
    _       <- pillars.whenEnabled(flag"feature-2")(IO.println("Feature 2 is enabled")) //(5)
    // or
    _       <- flag"feature-3".whenEnabled(IO.println("Feature 3 is enabled")) //(6)
yield ()
1 Import the flags module to enable the flag string interpolator and the flags property on Pillars.
2 Create a Flag instance by using the flag string interpolator.
3 Check if the feature flag is enabled.
4 If the feature flag is enabled, perform the action you want.
5 Use the pillars.whenEnabled method to perform an action if the feature flag is enabled.
6 Use the whenEnabled method on the FeatureFlag.Name instance to perform an action if the feature flag is enabled.

Endpoints

Feature flags are exposed on the admin server.

Get all feature flags

The GET /admin/flags endpoint returns all feature flags.

curl -X GET http://localhost:19876/admin/flags

The response is a JSON array of feature flags.

[
  {
    "name": "feature-1",
    "status": "enabled"
  },
  {
    "name": "feature-2",
    "status": "disabled"
  }
]

Get a specific feature flag

The GET /admin/flags/+{name}+ endpoint returns a specific feature flag.

curl -X GET http://localhost:19876/admin/flags/feature-1

The response is a JSON object with the name and status of the feature flag.

{
  "name": "feature-1",
  "status": "enabled"
}

Update a specific feature flag

The PUT /admin/flags/+{name}+ endpoint updates a specific feature flag.

curl -X PUT -H "Content-Type: application/json" -d '{"status": "disabled"}' http://localhost:19876/admin/flags/feature-1

The request body should be a JSON object with the new status of the feature flag.

{
  "status": "disabled"
}

The response is a JSON object with the name and status of the feature flag.

{
  "name": "feature-1",
  "status": "disabled"
}