flagd

README

flagD

Flagd is a simple command line tool for fetching and presenting feature flags to services. It is designed to conform to OpenFeature schema for flag definitions.

Example usage

1. Generate the prerequisites make generate
2. Build the flagd binary: make build
3. Start the process: ./flagd start -f config/samples/example_flags.json --service-provider http --sync-provider filepath

This now provides an accessible http or https endpoint for the flags:

Resolve a boolean value

Command:

curl -X POST "localhost:8013/flags/myBoolFlag/resolve/boolean"

Result:

{"value":true,"reason":"STATIC","variant":"on"}

Resolve a string value

Command:

curl -X POST "localhost:8013/flags/myStringFlag/resolve/string"

Result:

{"value":"val1","reason":"STATIC","variant":"key1"}

Resolve a integer value

Command:

curl -X POST "localhost:8013/flags/myIntFlag/resolve/int"

Result:

{"value":"1","reason":"STATIC","variant":"one"}

Why is this int response a string?

Resolve a float value

Command:

curl -X POST "localhost:8013/flags/myFloatFlag/resolve/float"

Result:

{"value":1.23,"reason":"STATIC","variant":"one"}

Resolve an object value

Command:

curl -X POST "localhost:8013/flags/myObjectFlag/resolve/object"

Result:

{"value":{"key":"val"},"reason":"STATIC","variant":"object1"}

Resolve a boolean value with evaluation context

Command:

curl -X POST "localhost:8013/flags/isColorYellow/resolve/boolean" -d '{"color": "yellow"}'

Result:

{"value":true,"reason":"TARGETING_MATCH","variant":"on"}

Return value type mismatch error

A type mismatch error is returned when the resolved value of a flag does not match the type requested. In the example below, the resolved value of myBoolFlag is a boolean but the request expects a string to be returned.

Command:

curl -X POST "localhost:8013/flags/myBoolFlag/resolve/string"

Result:

{"error_code":"TYPE_MISMATCH","reason":"ERROR"}

Return flag not found error

The flag not found error is returned when flag key in the request doesn't match any configured flags.

Command:

curl -X POST "localhost:8013/flags/aMissingFlag/resolve/string"

Result:

{"error_code":"FLAG_NOT_FOUND","reason":"ERROR"}

https

When it is desired to use TLS for increased security, flagD can be started with the following cert and key information.

flagd start --server-cert-path ./example-cert.pem --server-key-path ./example-key.pem

This enables you to use an upgraded connection for the previous example requests, such as the following:

$ curl -X POST "https://localhost:8013/flags/myBoolFlag/resolve/boolean"
// {"value":true,"reason":"STATIC","variant":"on"}

Multiple source example

Multiple providers can be supplied as the following:

./flagd start -f config/samples/example_flags.json -f config/samples/example_flags_secondary.json --service-provider http --sync-provider filepath

In case of collision between flags definition the priority goes to the later (e.g. example_flags < example_flags_secondary).

Installation

Systemd

To install as a systemd service run sudo make install this will place the binary by default in /usr/local/bin

There will also be a default provider and sync enabled ( http / filepath ) both of which can be modified in the flagd.service.

Validation can be run with systemctl status flagd And result similar to below will be seen

● flagd.service - "A generic feature flag daemon"
     Loaded: loaded (/etc/systemd/system/flagd.service; disabled; vendor preset: enabled)
     Active: active (running) since Mon 2022-05-30 12:19:55 BST; 5min ago
   Main PID: 64610 (flagd)
      Tasks: 7 (limit: 4572)
     Memory: 1.4M
     CGroup: /system.slice/flagd.service
             └─64610 /usr/local/bin/flagd start -f=/etc/flagd/flags.json

May 30 12:19:55 foo systemd[1]: Started "A generic feature flag daemon".

Running in a container

1. IMG=flagd-local make docker-build
2. docker run -p 8013:8013 -it flagd-local start --uri ./examples/example_flags.json

Targeting Rules

The flag object has a field named "targeting", this can be populated with a JsonLogic rule. Any data in the body of a flag evaluation call is processed by the JsonLogic rule to determine the result of flag evaluation. If this result is null or an invalid (undefined) variant then the default variant is returned.

JsonLogic provides a playground for evaluating your rules against data.

Example

A flag is defined as such:

{
  "flags": {
    "isColorYellowFlag": {
      "state": "ENABLED",
      "variants": {
        "on": true,
        "off": false
      },
      "defaultVariant": "off",
      "targeting": {
        "if": [
          {
            "==": [
              {
                "var": [
                  "color"
                ]
              },
              "yellow"
            ]
          },
          "on",
          "off"
        ]
      }
    }
  }
}

The rule provided returns "on" if var color == "yellow" and "off" otherwise:

$ curl -X POST "localhost:8013/flags/isColorYellow/resolve/boolean" -d '{"color": "yellow"}'

returns

{"value":true,"reason":"TARGETING_MATCH","variant":"on"}

whereas

$ curl -X POST "localhost:8013/flags/isColorYellow/resolve/boolean" -d '{"color": "white"}'

returns

{"value":true,"reason":"TARGETING_MATCH","variant":"off"}

Reusable targeting rules

Fractional Evaluation

The people who make flagD great 💜