Repository files navigation

GO Feature Flag is a simple, complete and lightweight self-hosted feature flag solution 100% Open Source.

🙏 If you are usingGO Feature Flag please consider to add yourself in theadopters list.
This simple act significantly boosts the project's visibility and credibility, making a substantial contribution to its advancement.

If you want to support me and GO Feature Flag, you can alsobecome a sponsor.

• 🎛️ GO Feature Flag
  • What is GO Feature Flag?
  • What can I do with GO Feature Flag?
  • Part of the OpenFeature Ecosystem
  • Getting started with GO Feature Flag
  • Can I use GO Feature Flag with any language?
  • Where do I store my flags file?
  • Flags file format
  • Rule format
  • Evaluation Context
  • Variations
  • Rollout
    • Complex rollout strategy available
  • Notifiers
  • Export data
  • Linter
• How can I contribute?
  • Contributors
  • Sponsors
  • Adopters

GO Feature Flag is a lightweight and open-source solution that provides a simple and complete feature flag implementation.

The solution has been built to facilitate the usage of feature flags in your code with the easiest setup possible.

Originally,GO Feature Flag was designed as a solution exclusively for theGO language. With the new standardization of feature flags by theOpenfeature project, the solution is now available for multiple languages(list of supported languages) through a simple API server called the relay proxy, which can be hosted.

• Use the feature flag standardOpenFeature in your favorite language(see list).
• Storing your configuration flags file on various locations (HTTP,S3,Kubernetes,see full list).
• Configuring your flags in variousformat (JSON,TOML andYAML).
• Adding complexrules to target your users.
• Use a complex rollout strategy for your flags :
  • Run A/B testing experimentation.
  • Progressively rollout a feature.
  • Schedule your flag updates.
• Exporting your flags usage data to various destinations such as(S3,Google cloud storage,file,kubernetes, see thefull list).
• Getting notified when a flag has been changed(webhook andslack).
• Support your full stack, from the backend to the frontend including your mobile apps.

The code of this demo is available inexamples/demo repository.

At GO Feature Flag, we believe in the power of open standards and, the importance of vendor neutrality. That's why we've chosen to rely on Open Feature for our SDKs.

By adopting GO Feature Flag you embrace the OpenFeature standard and you get all the benefits of the ecosystem.

• Open-Source standard SDKs
• No Vendor Lock-In
• OpenFeature community based support for SDKs

# 20% of the users will use the variation "my-new-feature"test-flag:variations:my-new-feature:truemy-old-feature:falsedefaultRule:percentage:my-new-feature:20my-old-feature:80

server:mode:httpport:1031pollingInterval:1000startWithRetrieverError:falseretriever:kind:filepath:/goff/flag-config.yamlexporter:kind:log

# Launch the containerdocker run \  -p 1031:1031 \  -v$(pwd)/flag-config.yaml:/goff/flag-config.yaml \  -v$(pwd)/goff-proxy.yaml:/goff/goff-proxy.yaml \  gofeatureflag/go-feature-flag:latest

npm i @openfeature/server-sdk @openfeature/go-feature-flag-provider

const{OpenFeature}=require("@openfeature/server-sdk");const{GoFeatureFlagProvider}=require("@openfeature/go-feature-flag-provider");// init Open Feature SDK with GO Feature Flag providerconstgoFeatureFlagProvider=newGoFeatureFlagProvider({endpoint:'http://localhost:1031/'// DNS of your instance of relay proxy});OpenFeature.setProvider(goFeatureFlagProvider);constfeatureFlagClient=OpenFeature.getClient('my-app')

// Context of your flag evaluation.// With GO Feature Flag you MUST provide a targetingKey that is a unique identifier of the user.constevaluationContext={targetingKey:'1d1b9238-2591-4a47-94cf-d2bc080892f1',// user unique identifier (mandatory)firstname:'john',lastname:'doe',email:'john.doe@gofeatureflag.org',admin:true,// this field is used in the targeting rule of the flag "flag-only-for-admin"// ...};constadminFlag=awaitfeatureFlagClient.getBooleanValue('flag-only-for-admin',false,evaluationContext);if(adminFlag){// flag "flag-only-for-admin" is true for the userconsole.log("new feature");}else{// flag "flag-only-for-admin" is false for the user}

go get github.com/thomaspoignant/go-feature-flag

# 20% of the users will use the variation "my-new-feature"test-flag:variations:my-new-feature:truemy-old-feature:falsedefaultRule:percentage:my-new-feature:20my-old-feature:80

err:=ffclient.Init(ffclient.Config{PollingInterval:3*time.Second,Retriever:&fileretriever.Retriever{Path:"flag-config.goff.yaml",  },})deferffclient.Close()

user:=ffcontext.NewEvaluationContext("user-unique-key")hasFlag,_:=ffclient.BoolVariation("test-flag",user,false)ifhasFlag {// flag "test-flag" is true for the user}else {// flag "test-flag" is false for the user}

Originally GO Feature Flag was built to be a GOlang only library, but it limits the ecosystem too much.
To be compatible with more languages we have implemented theGO Feature Flag Relay Proxy.It is a service you can host that provides an API to evaluate your flags, you can call it using HTTP to get your variation.

Since we believe in standardization we are also implementingOpenFeature providers to interact with this API in the language of your choice.
(OpenFeature is still at an early stage, so not all languages are supported and expect some changes in the future)

For now, we have providers for:

Language	Provider Source	Version
Go	Go Provider
Java / Kotlin (server)	Java Provider
Android / Kotlin (client)	Kotlin Provider
Javascript/Typescript (server)	Server Provider
Javascript/Typescript (client)	Client Provider
Python	Python Provider
.Net	.Net Provider
Ruby	Ruby Provider
Swift	Swift Provider
PHP	PHP Provider

The module supports different ways of retrieving the flag file.
The available retrievers are:

• GitHub
• GitLab
• HTTP endpoint
• AWS S3
• Local file
• Google Cloud Storage
• Kubernetes ConfigMaps
• MongoDB
• Redis
• BitBucket
• AzBlobStorage
• ...

See the full list and more information.

GO Feature Flag core feature is to centralize all your feature flags in a single file and to avoid hosting and maintaining a backend server to manage them.

Your file should be aYAML,JSON orTOML file with a list of flags(examples:YAML,JSON,TOML).

The easiest way to create your configuration file is to useGO Feature Flag Editor available athttps://editor.gofeatureflag.org.
If you prefer to do it manually please follow the instruction below.

A flag configuration looks like this:

# This is your configuration for your first flagfirst-flag:variations:# All possible return value for your feature flagA:falseB:truetargeting:# If you want to target a subset of your users in particular    -query:key eq "random-key"percentage:A:0B:100defaultRule:# When no targeting match we use the defaultRulevariation:A# A second example of a flag configurationsecond-flag:variations:A:"valueA"B:"valueB"defaultValue:"a default value"targeting:    -name:notkey_rulequery:key eq "not-a-key"percentage:A:10B:90defaultRule:variation:defaultValueversion:"12"experimentation:start:2021-03-20T00:00:00.1-05:00end:2021-03-21T00:00:00.1-05:00

{"first-flag": {"variations": {"A":false,"B":true    },"targeting": [      {"query":"key eq\"random-key\"","percentage": {"A":0,"B":100        }      }    ],"defaultRule": {"variation":"A"    }  },"second-flag": {"variations": {"A":"valueA","B":"valueB","defaultValue":"a default value"    },"targeting": [      {"name":"notkey_rule","query":"key eq\"not-a-key\"","percentage": {"A":10,"B":90        }      }    ],"defaultRule": {"variation":"defaultValue"    },"version":"12","experimentation": {"start":"2021-03-20T05:00:00.100Z","end":"2021-03-21T05:00:00.100Z"    }  }}

[first-flag.variations]A =falseB =true[[first-flag.targeting]]query ='key eq "random-key"'[first-flag.targeting.percentage]A =0B =100[first-flag.defaultRule]variation ="A"[second-flag]version ="12"[second-flag.variations]A ="valueA"B ="valueB"defaultValue ="a default value"[[second-flag.targeting]]name ="notkey_rule"query ='key eq "not-a-key"'[second-flag.targeting.percentage]A =10B =90[second-flag.defaultRule]variation ="defaultValue"[second-flag.experimentation]start =2021-03-20T05:00:00.100Zend =2021-03-21T05:00:00.100Z

For detailed information on the fields required to create a flag, please refer to thedocumentation.

The query format is based on thenikunjy/rules library.

All the operations can be written in capitalized or lowercase (ex:eq orEQ can be used).
Logical Operations supported areANDOR.

Compare Expression and their definitions (a|b means you can use either one of the twoa orb):

eq|==: equals to ne|!=: not equals tolt|<: less than gt|>: greater thanle|<=: less than equal toge|>=: greater than equal to co: contains sw: starts with ew: ends within: in a listpr: presentnot: not of a logical expression

• Select a specific user:key eq "example@example.com"
• Select all identified users:anonymous ne true
• Select a user with a custom property:userId eq "12345"

An evaluation context in a feature flagging system is crucial for determining the output of a feature flag evaluation. It's a collection of pertinent data about the conditions under which the evaluation is being made. This data can be supplied through a mix of static information(server name, IP, etc ...) and dynamic inputs (information about the user performing the action, etc ...), along with state information that is implicitly carried through the execution of the program.

When using GO Feature Flag, it's often necessary to personalize the experience for different users. This is where the concept of atargeting key comes into play. A targeting key is a unique identifier that represents the context of the evaluation(email, session id, a fingerprint or anything that is consistent), ensuring that they are consistently exposed to the same variation of a feature, even across multiple visits or sessions.

For instance, GO Feature Flag ensures that in cases where a feature is being rolled out to a percentage of users, based on the targeting key, they will see the same variation each time they encounter the feature flag.

The targeting key is a fundamental part of the evaluation context because it directly affects the determination of which feature variant is served to a particular user, and it maintains that continuity over time. To do so GO Feature Flag to do a hash to define if the flag can apply to this evaluation context or not.
We recommend using a hash if possible.

Feature flag targeting and rollouts are all determined by the user you pass to your evaluation calls.

In some cases, you might need tobucket users based on a different key, e.g. ateamId, so that users within the same team get exposed to the same flag variation and get a consistent experience.

This can be achieved by defining thebucketingKey field in the flag configuration. When present, the value corresponding to thebucketingKey will be extracted from the attributes, and that value used for hashing and determining the outcome in place of thetargetingKey.

Variations are the different values possible for a feature flag.
GO Feature Flag can manage more than justboolean values; the value of your flag can be any of the following types:

• bool
• int
• float
• string
• json array
• json object

Booleanresult =featureFlagClient.getBooleanValue("your.feature.key",false,userContext);// this example is using the java SDK// result is now true or false depending on the setting of this boolean feature flag

Variation methods take the featureflag key, anevaluation context, and adefault value.

Why do we need a default value? If we have any error during the evaluation of the flag, we will return the default value, you will always get a value return from the function and we will never throw an error.

In the example, if the flagyour.feature.key does not exist, the result will befalse.
Note that the result will always provide a usable value.

A critical part of every new feature release is orchestrating the actual launch schedule between the Product, Engineering, and Marketing teams.

Delivering powerful user experiences typically requires software teams to manage complex releases and make manual updates at inconvenient times.

But it does not have to, having a complexrollout strategy allows you to have a lifecycle for your flags.

• Percentages rollout - impact randomly a subset of your users.
• Progressive rollout - increase the percentage of your flag over time.
• Scheduled rollout - update your flag over time.
• Experimentation rollout - serve your feature only for a determined time(perfect for A/B testing).

If you want to be informed when a flag has changed, you can configure anotifier.

A notifier will send one notification to the targeted system to inform them that a new flag configuration has been loaded.

ℹ️GO Feature Flag can handle more than one notifier at a time.

Available notifiers are:

• Slack
• Webhook
• Discord
• Microsoft Teams

GO Feature Flag allows you to export data about the usage of your flags.
It collects all variation events and can save these events in several locations:

• Local file- create local files with the variation usages.
• Log- use your logger to write the variation usages.
• AWS S3- export your variation usages to S3.
• AWS Kinesis- publish your variation usages to AWS Kinesis Stream.
• Google Cloud Storage- export your variation usages to Google Cloud Storage.
• Webhook- export your variation usages by calling a webhook.
• AWS SQS- export your variation usages by sending events to SQS.
• Google PubSub- export your variation usages by publishing events to PubSub topic.

Currently, we are supporting only feature events.
It represents individual flag evaluations and is considered "full fidelity" events.

An example feature event below:

{"kind":"feature","contextKind":"anonymousUser","userKey":"ABCD","creationDate":1618228297,"key":"test-flag","variation":"Default","value":false,"default":false,"source":"SERVER"}

The format of the data isdescribed in the documentation.Events are collected and sent in bulk to avoid spamming your exporter.

A command line tool is available to help you lint your configuration file:go-feature-flag-lint.

This project welcomes contributions from the community. If you're interested in contributing, see thecontributors' guide for some helpful tips.

Thanks so much to our contributors.

Become a sponsor and show your support to GO Feature Flag.

These are our really cool sponsors!

If you are usinggo-feature-flag, we encourage you to include your company's name in this list. This simple act significantly boosts the project's visibility and credibility, making a substantial contribution to its advancement. To do so, kindly add yourself toadopters.

Here is the list ofadopters.