Skip to content

Commit 4b234e6

Browse files
thomaspoignantthomaspoignant
committed
Update readme
Signed-off-by: Thomas Poignant <[email protected]>
1 parent 76ab14c commit 4b234e6

File tree

2 files changed

+91
-73
lines changed

2 files changed

+91
-73
lines changed

‎providers/go-feature-flag/README.md

Lines changed: 89 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,125 @@
1-
# GO Feature Flag Java Provider
1+
# GO Feature Flag - OpenFeature Java provider
2+
[![Maven Central Version](https://img.shields.io/maven-central/v/dev.openfeature.contrib.providers/go-feature-flag?color=blue&style=flat-square)](https://search.maven.org/artifact/dev.openfeature.contrib.providers/go-feature-flag)
23

3-
GO Feature Flag provider allows you to connect to your [GO Feature Flag relay proxy](https://gofeatureflag.org) instance.
44

5-
## How to use this provider?
5+
> [!WARNING]
6+
> This version of the provider requires to use GO Feature Flag relay-proxy `v1.45.0` or above.
7+
> If you have an older version of the relay-proxy, please use the version `0.4.3` of the provider.
68
7-
To use your instance please follow this example:
9+
This is the official OpenFeature Java provider for accessing your feature flags with GO Feature Flag.
10+
11+
In conjuction with the [OpenFeature SDK](https://openfeature.dev/docs/reference/concepts/provider) you will be able to evaluate your feature flags in your java/kotlin applications.
12+
13+
For documentation related to flags management in GO Feature Flag, refer to the [GO Feature Flag documentation website](https://gofeatureflag.org/docs).
14+
15+
### Functionalities:
16+
17+
- Manage the integration of the OpenFeature Java SDK and GO Feature Flag relay-proxy.
18+
- 2 types of evaluations available:
19+
- **In process**: fetch the flag configuration from the GO Feature Flag relay-proxy API and evaluate the flags directly in the provider.
20+
- **Remote**: Call the GO Feature Flag relay-proxy for each flag evaluation.
21+
- Collect and send evaluation data to the GO Feature Flag relay-proxy for statistics and monitoring purposes.
22+
- Support the OpenFeature [tracking API](https://openfeature.dev/docs/reference/concepts/tracking/) to associate metrics or KPIs with feature flag evaluation contexts.
23+
24+
## Dependency Setup
25+
26+
<!-- x-release-please-start-version -->
27+
```xml
28+
<dependency>
29+
<groupId>dev.openfeature.contrib.providers</groupId>
30+
<artifactId>go-feature-flag</artifactId>
31+
<version>0.4.3</version>
32+
</dependency>
33+
```
34+
<!-- x-release-please-end-version -->
35+
36+
## Getting started
37+
### Initialize the provider
38+
GO Feature Flag provider needs to be created and then set in the global OpenFeatureAPI.
39+
40+
The only required option to create a `GoFeatureFlagProvider` is the endpoint to your GO Feature Flag relay-proxy instance.
841

942
```java
1043
import dev.openfeature.contrib.providers.gofeatureflag;
44+
//...
1145

12-
// ...
1346
FeatureProvider provider = new GoFeatureFlagProvider(
14-
GoFeatureFlagProviderOptions
15-
.builder()
16-
.endpoint("https://my-gofeatureflag-instance.org")
17-
.timeout(1000)
18-
.build());
47+
GoFeatureFlagProviderOptions.builder()
48+
.endpoint("https://my-gofeatureflag-instance.org")
49+
.build());
1950

2051
OpenFeatureAPI.getInstance().setProviderAndWait(provider);
21-
2252
// ...
23-
24-
Client client = OpenFeatureAPI.getInstance().getClient("my-provider");
53+
Client client = OpenFeatureAPI.getInstance().getClient("my-goff-provider");
2554

2655
// targetingKey is mandatory for each evaluation
2756
String targetingKey = "ad0c6f75-f5d6-4b17-b8eb-6c923d8d4698";
2857
EvaluationContext evaluationContext = new ImmutableContext(targetingKey);
2958

30-
FlagEvaluationDetails<Boolean> booleanFlagEvaluationDetails = client.getBooleanDetails("feature_flag1", false, evaluationContext);
31-
Boolean value = booleanFlagEvaluationDetails.getValue();
32-
33-
// ...
34-
35-
provider.shutdown();
59+
// Example of a boolean flag evaluation
60+
FlagEvaluationDetails<Boolean> booleanFlagEvaluation = client.getBooleanValue("bool_targeting_match", false, evaluationContext);
3661
```
3762

38-
You will have a new instance ready to be used with your `open-feature` java SDK.
39-
40-
### Options
63+
The evaluation context is the way for the client to specify contextual data that GO Feature Flag uses to evaluate the feature flags, it allows to define rules on the flag.
4164

42-
| name | mandatory | Description |
43-
|-----------------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
44-
| **`endpoint`** | `true` | endpoint contains the DNS of your GO Feature Flag relay proxy _(ex: https://mydomain.com/gofeatureflagproxy/)_ |
45-
| **`timeout`** | `false` | timeout in millisecond we are waiting when calling the go-feature-flag relay proxy API. _(default: 10000)_ |
46-
| **`maxIdleConnections`** | `false` | maxIdleConnections is the maximum number of connexions in the connexion pool. _(default: 1000)_ |
47-
| **`keepAliveDuration`** | `false` | keepAliveDuration is the time in millisecond we keep the connexion open. _(default: 7200000 (2 hours))_ |
48-
| **`apiKey`** | `false` | If the relay proxy is configured to authenticate the requests, you should provide an API Key to the provider. Please ask the administrator of the relay proxy to provide an API Key. (This feature is available only if you are using GO Feature Flag relay proxy v1.7.0 or above). _(default: null)_ |
49-
| **`enableCache`** | `false` | enable cache value. _(default: true)_ |
50-
| **`cacheConfig`** | `false` | If cache custom configuration is wanted, you should provide a [Caffeine](https://github.com/ben-manes/caffeine) configuration object. _(default: null)_ |
51-
| **`flushIntervalMs`** | `false` | interval time we publish statistics collection data to the proxy. The parameter is used only if the cache is enabled, otherwise the collection of the data is done directly when calling the evaluation API. _(default: 1000 ms)_ |
52-
| **`maxPendingEvents`** | `false` | max pending events aggregated before publishing for collection data to the proxy. When event is added while events collection is full, event is omitted. _(default: 10000)_ |
53-
| **`flagChangePollingIntervalMs`** | `false` | interval time we poll the proxy to check if the configuration has changed.<br/>If the cache is enabled, we will poll the relay-proxy every X milliseconds to check if the configuration has changed. _(default: 120000)_ |
54-
| **`disableDataCollection`** | `false` | set to true if you don't want to collect the usage of flags retrieved in the cache. _(default: false)_ |
65+
The `targetingKey` is mandatory for GO Feature Flag in order to evaluate the feature flag, it could be the id of a user, a session ID or anything you find relevant to use as identifier during the evaluation.
5566

56-
## Breaking changes
67+
### Configure the provider
68+
You can configure the provider with several options to customize its behavior. The following options are available:
5769

58-
### 0.4.0 - Cache Implementation Change: Guava to Caffeine
5970

60-
In this release, we have updated the cache implementation from Guava to Caffeine. This change was made because Caffeine is now the recommended caching solution by the maintainers of Guava due to its performance improvements and enhanced features.
71+
| name | mandatory | Description |
72+
|-----------------------------------|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
73+
| **`endpoint`** | `true` | endpoint contains the DNS of your GO Feature Flag relay proxy _(ex: https://mydomain.com/gofeatureflagproxy/)_ |
74+
| **`evaluationType`** | `false` | evaluationType is the type of evaluation you want to use.<ul><li>If you want to have a local evaluation, you should use IN_PROCESS.</li><li>If you want to have an evaluation on the relay-proxy directly, you should use REMOTE.</li></ul>Default: IN_PROCESS<br/> |
75+
| **`timeout`** | `false` | timeout in millisecond we are waiting when calling the relay proxy API. _(default: `10000`)_ |
76+
| **`maxIdleConnections`** | `false` | maxIdleConnections is the maximum number of connections in the connection pool. _(default: `1000`)_ |
77+
| **`keepAliveDuration`** | `false` | keepAliveDuration is the time in millisecond we keep the connection open. _(default: `7200000` (2 hours))_ |
78+
| **`apiKey`** | `false` | If the relay proxy is configured to authenticate the requests, you should provide an API Key to the provider. Please ask the administrator of the relay proxy to provide an API Key. (This feature is available only if you are using GO Feature Flag relay proxy v1.7.0 or above). _(default: null)_ |
79+
| **`flushIntervalMs`** | `false` | interval time we publish statistics collection data to the proxy. The parameter is used only if the cache is enabled, otherwise the collection of the data is done directly when calling the evaluation API. default: `1000` ms |
80+
| **`maxPendingEvents`** | `false` | max pending events aggregated before publishing for collection data to the proxy. When event is added while events collection is full, event is omitted. _(default: `10000`)_ |
81+
| **`disableDataCollection`** | `false` | set to true if you don't want to collect the usage of flags retrieved in the cache. _(default: `false`)_ |
82+
| **`exporterMetadata`** | `false` | exporterMetadata is the metadata we send to the GO Feature Flag relay proxy when we report the evaluation data usage. |
83+
| **`evaluationFlagList`** | `false` | If you are using in process evaluation, by default we will load in memory all the flags available in the relay proxy. If you want to limit the number of flags loaded in memory, you can use this parameter. By setting this parameter, you will only load the flags available in the list. <p>If null or empty, all the flags available in the relay proxy will be loaded.</p> |
84+
| **`flagChangePollingIntervalMs`** | `false` | interval time we poll the proxy to check if the configuration has changed. It is used for the in process evaluation to check if we should refresh our internal cache. default: `120000` |
6185

62-
Because of this, the cache configuration on `GoFeatureFlagProviderOptions` that used Guava's `CacheBuilder` is now handled by `Caffeine`.
86+
### Evaluate a feature flag
87+
The OpenFeature client is used to retrieve values for the current `EvaluationContext`. For example, retrieving a boolean value for the flag **"my-flag"**:
6388

64-
#### How to migrate
89+
```java
90+
Client client = OpenFeatureAPI.getInstance().getClient("my-goff-provider");
91+
FlagEvaluationDetails<Boolean> booleanFlagEvaluation = client.getBooleanValue("bool_targeting_match", false, evaluationContext);
92+
```
6593

66-
Configuration cache with Guava used to be like this:
94+
GO Feature Flag supports different all OpenFeature supported types of feature flags, it means that you can use all the accessor directly
6795

6896
```java
69-
import com.google.common.cache.CacheBuilder;
70-
// ...
71-
CacheBuilder guavaCacheBuilder = CacheBuilder.newBuilder()
72-
.initialCapacity(100)
73-
.maximumSize(2000);
97+
// Boolean
98+
client.getBooleanValue("my-flag", false, evaluationContext);
7499

75-
FeatureProvider provider = new GoFeatureFlagProvider(
76-
GoFeatureFlagProviderOptions
77-
.builder()
78-
.endpoint("https://my-gofeatureflag-instance.org")
79-
.cacheBuilder(guavaCacheBuilder)
80-
.build());
100+
// String
101+
client.getStringValue("my-flag", "default", evaluationContext);
81102

82-
OpenFeatureAPI.getInstance().setProviderAndWait(provider);
103+
// Integer
104+
client.getIntegerValue("my-flag", 1, evaluationContext);
83105

84-
// ...
85-
```
106+
// Double
107+
client.getDoubleValue("my-flag", 1.1, evaluationContext);
86108

87-
Now with Caffeine it should be like this:
109+
// Object
110+
client.getObjectDetails("my-flag",Value.objectToValue(new MutableStructure().add("default", "true")), evaluationContext);
111+
```
88112

89-
```java
90-
import com.github.benmanes.caffeine.cache.Caffeine;
91-
// ...
92-
Caffeine caffeineCacheConfig = Caffeine.newBuilder()
93-
.initialCapacity(100)
94-
.maximumSize(2000);
113+
## How it works
114+
### In process evaluation
115+
When the provider is configured to use in process evaluation, it will fetch the flag configuration from the GO Feature Flag relay-proxy API and evaluate the flags directly in the provider.
95116

96-
FeatureProvider provider = new GoFeatureFlagProvider(
97-
GoFeatureFlagProviderOptions
98-
.builder()
99-
.endpoint("https://my-gofeatureflag-instance.org")
100-
.cacheConfig(caffeineCacheConfig)
101-
.build());
117+
The evaluation is done inside the provider using a webassembly module that is compiled from the GO Feature Flag source code.
118+
The `wasm` module is used to evaluate the flags and the source code is available in the [thomaspoignant/go-feature-flag](https://github.com/thomaspoignant/go-feature-flag/tree/main/wasm) repository.
102119

103-
OpenFeatureAPI.getInstance().setProviderAndWait(provider);
120+
The provider will call the GO Feature Flag relay-proxy API to fetch the flag configuration and then evaluate the flags using the `wasm` module.
104121

105-
// ...
106-
```
122+
### Remote evaluation
123+
When the provider is configured to use remote evaluation, it will call the GO Feature Flag relay-proxy for each flag evaluation.
107124

108-
For a complete list of customizations options available in Caffeine, please refer to the [Caffeine documentation](https://github.com/ben-manes/caffeine/wiki) for more details.
125+
It will perform an HTTP request to the GO Feature Flag relay-proxy API with the flag name and the evaluation context for each flag evaluation.

‎release-please-config.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,8 @@
3232
"bump-patch-for-minor-pre-major": true,
3333
"versioning": "default",
3434
"extra-files": [
35-
"pom.xml"
35+
"pom.xml",
36+
"README.md"
3637
]
3738
},
3839
"providers/jsonlogic-eval-provider": {

0 commit comments

Comments
 (0)