Add OpenFeature providers to SDK reference

configcat · Sep 5, 2024 · a7b1416 · a7b1416
1 parent 4a381b4
commit a7b1416
Show file tree

Hide file tree

Showing 25 changed files with 1,643 additions and 19 deletions.
diff --git a/website/docs/sdk-reference/go.mdx b/website/docs/sdk-reference/go.mdx
@@ -114,7 +114,7 @@ If you want to use multiple SDK Keys in the same application, create only one _C
 
 ## Anatomy of `Get[TYPE]Value()`
 
-Basically all of the value evaluator methods share the same signature, they only differ in their served value type. `GetBoolValue()` is for evaluating feature flags, `GetIntValue()` and `GetFloatValue()` are for numeric and `GetStringValue()` is for textual settings.
+All feature flag evaluator methods share the same signature, they only differ in their served value type. `GetBoolValue()` is for evaluating feature flags, `GetIntValue()` and `GetFloatValue()` are for numeric and `GetStringValue()` is for textual settings.
 
 | Parameters     | Description                                                                                        |
 | -------------- | -------------------------------------------------------------------------------------------------- |

diff --git a/website/docs/sdk-reference/java.mdx b/website/docs/sdk-reference/java.mdx
@@ -265,8 +265,8 @@ User user = User.newBuilder().build("[email protected]");
 
 ```java
 java.util.Map<String,Object> customAttributes = new java.util.HashMap<String,Object>();
-    customAttributes.put("SubscriptionType", "Pro");
-    customAttributes.put("UserRole", "Admin");
+customAttributes.put("SubscriptionType", "Pro");
+customAttributes.put("UserRole", "Admin");
 
 User user = User.newBuilder()
     .email("[email protected]")
@@ -279,9 +279,9 @@ The `Custom` dictionary also allows attribute values other than `String` values:
 
 ```java
 java.util.Map<String,Object> customAttributes = new java.util.HashMap<String,Object>();
-    customAttributes.put("Rating", 4.5);
-    customAttributes.put("RegisteredAt", new Date("2023-11-22 12:34:56 +00:00"));
-    customAttributes.put("Roles", new String[]{"Role1", "Role2"});
+customAttributes.put("Rating", 4.5);
+customAttributes.put("RegisteredAt", new Date("2023-11-22 12:34:56 +00:00"));
+customAttributes.put("Roles", new String[]{"Role1", "Role2"});
 
 User user = User.newBuilder()
     .email("[email protected]")
@@ -395,7 +395,7 @@ Use the `cacheRefreshIntervalInSeconds` option parameter of the `PollingModes.la
 
 ```java
 ConfigCatClient client = ConfigCatClient.get("#YOUR-SDK-KEY#", options -> {
-        options.pollingMode(PollingModes.lazyLoad(60 /* the cache will expire in 120 seconds */));
+    options.pollingMode(PollingModes.lazyLoad(60 /* the cache will expire in 120 seconds */));
 });
 ```
 
@@ -413,7 +413,7 @@ Manual polling gives you full control over when the `config JSON` (with the sett
 
 ```java
 ConfigCatClient client = ConfigCatClient.get("#YOUR-SDK-KEY#", options ->{
-        options.pollingMode(PollingModes.manualPoll());
+    options.pollingMode(PollingModes.manualPoll());
 });
 
 client.forceRefresh();
@@ -699,7 +699,7 @@ map.put("doubleSetting", 3.14);
 map.put("stringSetting", "test");
 
 ConfigCatClient client = ConfigCatClient.get("localhost", options -> {
-        options.flagOverrides(OverrideDataSourceBuilder.map(map), OverrideBehaviour.LOCAL_ONLY)
+    options.flagOverrides(OverrideDataSourceBuilder.map(map), OverrideBehaviour.LOCAL_ONLY)
 });
 ```
 

diff --git a/website/docs/sdk-reference/openfeature/dotnet.mdx b/website/docs/sdk-reference/openfeature/dotnet.mdx
@@ -0,0 +1,108 @@
+---
+id: dotnet
+title: OpenFeature Provider for .NET
+description: ConfigCat OpenFeature Provider for .NET. This is a step-by-step guide on how to use ConfigCat with the OpenFeature .NET SDK.
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<a href="https://github.com/open-feature/dotnet-sdk-contrib/tree/main/src/OpenFeature.Contrib.Providers.ConfigCat" target="_blank">ConfigCat OpenFeature Provider for .NET on GitHub</a>
+
+## Getting started
+
+### 1. Install the provider
+
+<Tabs groupId="dotnet-install">
+<TabItem value="Powershell / NuGet Package Manager Console" label="Powershell / NuGet Package Manager Console">
+
+```powershell
+Install-Package OpenFeature.Contrib.Providers.ConfigCat
+```
+
+</TabItem>
+<TabItem value=".NET CLI" label=".NET CLI">
+
+```bash
+dotnet add package OpenFeature.Contrib.Providers.ConfigCat
+```
+
+</TabItem>
+<TabItem value="Package Reference" label="Package Reference">
+
+```xml
+<PackageReference Include="OpenFeature.Contrib.Providers.ConfigCat" />
+```
+
+</TabItem>
+</Tabs>
+### 2. Initialize the provider
+
+The `ConfigCatProvider` constructor takes the SDK key and an optional `ConfigCatClientOptions` argument containing the additional configuration options for the [ConfigCat .NET SDK](../../dotnet/#creating-the-configcat-client):
+
+```cs
+using OpenFeature.Contrib.Providers.ConfigCat;
+
+// Build options for the ConfigCat SDK.
+var options = new ConfigCatClientOptions
+{
+    PollingMode = PollingModes.AutoPoll(pollInterval: TimeSpan.FromSeconds(60));
+    Logger = new ConsoleLogger(LogLevel.Warning);
+    // ...
+};
+
+// Configure the provider.
+OpenFeature.Api.Instance.SetProvider(new ConfigCatProvider("#YOUR-SDK-KEY#", options));
+
+// Create a client.
+var client = OpenFeature.Api.Instance.GetClient();
+```
+
+For more information about all the configuration options, see the [.NET SDK documentation](../../dotnet/#creating-the-configcat-client).
+
+### 3. Evaluate your feature flag
+
+```cs
+var isAwesomeFeatureEnabled = await client.GetBooleanValueAsync("isAwesomeFeatureEnabled", false);
+if(isAwesomeFeatureEnabled)
+{
+    doTheNewThing();
+}
+else
+{
+    doTheOldThing();
+}
+```
+
+## Evaluation Context
+
+An <a href="https://openfeature.dev/docs/reference/concepts/evaluation-context" target="_blank">evaluation context</a> in the OpenFeature specification is a container for arbitrary contextual data that can be used as a basis for feature flag evaluation.
+The ConfigCat provider translates these evaluation contexts to ConfigCat [User Objects](../../dotnet/#user-object).
+
+The following table shows how the different context attributes are mapped to User Object attributes.
+
+| Evaluation context | User Object  | Required |
+| ------------------ | ------------ | -------- |
+| `Id`/`Identifier`  | `Identifier` | &#9745;  | 
+| `Email`            | `Email`      |          | 
+| `Country`          | `Country`    |          | 
+| Any other          | `Custom`     |          | 
+
+To evaluate feature flags for a context, use the <a href="https://openfeature.dev/docs/reference/concepts/evaluation-api/" target="_blank">OpenFeature Evaluation API</a>:
+
+```cs
+var context = new EvaluationContext()
+    .Set("Id", "#SOME-USER-ID#")
+    .Set("Email", "[email protected]")
+    .Set("Country", "CountryID")
+    .Set("Rating", 4.5)
+    .Set("RegisteredAt", DateTime.Parse("2023-11-22 12:34:56 +00:00", CultureInfo.InvariantCulture))
+    .Build();
+
+var isAwesomeFeatureEnabled = await client.GetBooleanValueAsync("isAwesomeFeatureEnabled", false, context);
+```
+
+## Look under the hood
+
+- <a href="https://github.com/open-feature/dotnet-sdk-contrib/tree/main/src/OpenFeature.Contrib.Providers.ConfigCat" target="_blank">ConfigCat OpenFeature Provider's repository on GitHub</a>
+- <a href="https://www.nuget.org/packages/OpenFeature.Contrib.Providers.ConfigCat" target="_blank">ConfigCat OpenFeature Provider on nuget.org</a>
diff --git a/website/docs/sdk-reference/openfeature/go.mdx b/website/docs/sdk-reference/openfeature/go.mdx
@@ -0,0 +1,91 @@
+---
+id: go
+title: OpenFeature Provider for Go
+description: ConfigCat OpenFeature Provider for Go. This is a step-by-step guide on how to use ConfigCat with the OpenFeature Go SDK.
+---
+
+<a href="https://github.com/open-feature/go-sdk-contrib/tree/main/providers/configcat" target="_blank">ConfigCat OpenFeature Provider for Go on GitHub</a>
+
+## Getting started
+
+### 1. Install the provider
+
+```bash
+go get github.com/open-feature/go-sdk-contrib/providers/configcat
+```
+
+### 2. Initialize the provider
+
+The ConfigCat Provider needs a pre-configured [ConfigCat Go SDK](../../go/#creating-the-configcat-client) client:
+
+```go
+import (
+    "context"
+
+    sdk "github.com/configcat/go-sdk/v9"
+    configcat "github.com/open-feature/go-sdk-contrib/providers/configcat/pkg"
+    "github.com/open-feature/go-sdk/openfeature"
+)
+
+// Configure the ConfigCat SDK.
+configcatClient := sdk.NewCustomClient(sdk.Config{SDKKey: "#YOUR-SDK-KEY#",
+    PollingMode: sdk.AutoPoll,
+    PollInterval: time.Second * 60})
+
+// Configure the provider.
+openfeature.SetProvider(configcat.NewProvider(configcatClient))
+
+# Create a client.
+client := openfeature.NewClient("app")
+```
+
+For more information about all the configuration options, see the [Go SDK documentation](../../go/#creating-the-configcat-client).
+
+### 3. Evaluate your feature flag
+
+```rust
+isAwesomeFeatureEnabled, err := client.BooleanValue(
+    context.Background(), "isAwesomeFeatureEnabled", false, openfeature.EvaluationContext{},
+)
+
+if err == nil && isAwesomeFeatureEnabled {
+    doTheNewThing()
+} else {
+    doTheOldThing()
+}
+```
+
+## Evaluation Context
+
+An <a href="https://openfeature.dev/docs/reference/concepts/evaluation-context" target="_blank">evaluation context</a> in the OpenFeature specification is a container for arbitrary contextual data that can be used as a basis for feature flag evaluation.
+The ConfigCat provider translates these evaluation contexts to ConfigCat [User Objects](../../go/#user-object).
+
+The following table shows how the different context attributes are mapped to User Object attributes.
+
+| Evaluation context              | User Object  | Required |
+| ------------------------------- | ------------ | -------- |
+| `openfeature.TargetingKey`      | `Identifier` | &#9745;  | 
+| `configcat.EmailKey`            | `Email`      |          | 
+| `configcat.CountryKey`          | `Country`    |          | 
+| Any other                       | `Custom`     |          | 
+
+To evaluate feature flags for a context, use the <a href="https://openfeature.dev/docs/reference/concepts/evaluation-api/" target="_blank">OpenFeature Evaluation API</a>:
+
+```go
+registeredAt, _ := time.Parse(time.DateTime, "2023-11-22 12:34:56")
+context := openfeature.NewEvaluationContext("#SOME-USER-ID#", map[string]any{
+    configcat.EmailKey: "[email protected]",
+    configcat.CountryKey: "CountryID",
+    "Rating": 4.5,
+    "RegisteredAt": registeredAt,
+    "Roles": []string{"Role1","Role2"},
+})
+
+isAwesomeFeatureEnabled, err := client.BooleanValue(
+    context.Background(), "isAwesomeFeatureEnabled", false, context,
+)
+```
+
+## Look under the hood
+
+- <a href="https://github.com/open-feature/go-sdk-contrib/tree/main/providers/configcat" target="_blank">ConfigCat OpenFeature Provider's repository on GitHub</a>
diff --git a/website/docs/sdk-reference/openfeature/java.mdx b/website/docs/sdk-reference/openfeature/java.mdx
@@ -0,0 +1,102 @@
+---
+id: java
+title: OpenFeature Provider for Java
+description: ConfigCat OpenFeature Provider for Java. This is a step-by-step guide on how to use ConfigCat with the OpenFeature Java SDK.
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<a href="https://github.com/open-feature/java-sdk-contrib/tree/main/providers/configcat" target="_blank">ConfigCat OpenFeature Provider for Java on GitHub</a>
+
+## Getting started
+
+### 1. Install the provider
+
+<Tabs groupId="java-install">
+<TabItem value="Gradle" label="Gradle">
+
+```groovy title="build.gradle"
+dependencies {
+    implementation 'dev.openfeature.contrib.providers:configcat:0.0.4'
+}
+```
+
+</TabItem>
+<TabItem value="Maven" label="Maven">
+
+```xml title="pom.xml"
+<dependency>
+  <groupId>dev.openfeature.contrib.providers</groupId>
+  <artifactId>configcat</artifactId>
+  <version>0.0.4</version>
+</dependency>
+```
+
+</TabItem>
+</Tabs>
+### 2. Initialize the provider
+
+The `ConfigCatProvider` constructor takes a `ConfigCatProviderConfig` argument containing the configuration options for the [ConfigCat Java SDK](../../java/#creating-the-configcat-client):
+
+```java
+// Build options for the ConfigCat SDK.
+ConfigCatProviderConfig configCatProviderConfig = ConfigCatProviderConfig.builder()
+    .sdkKey("#YOUR-SDK-KEY#")
+    .pollingMode(PollingModes.autoPoll())
+    .logLevel(LogLevel.WARNING)
+    .build();
+
+// Configure the provider.
+OpenFeatureAPI.getInstance().setProviderAndWait(new ConfigCatProvider(configCatProviderConfig));
+
+// Create a client.
+Client client = OpenFeatureAPI.getInstance().getClient();
+```
+
+For more information about all the configuration options, see the [Java SDK documentation](../../java/#creating-the-configcat-client).
+
+### 3. Evaluate your feature flag
+
+```cs
+boolean isAwesomeFeatureEnabled = client.getBooleanValue("isAwesomeFeatureEnabled", false);
+if(isAwesomeFeatureEnabled)
+{
+    doTheNewThing();
+}
+else
+{
+    doTheOldThing();
+}
+```
+
+## Evaluation Context
+
+An <a href="https://openfeature.dev/docs/reference/concepts/evaluation-context" target="_blank">evaluation context</a> in the OpenFeature specification is a container for arbitrary contextual data that can be used as a basis for feature flag evaluation.
+The ConfigCat provider translates these evaluation contexts to ConfigCat [User Objects](../../java/#user-object).
+
+The following table shows how the different context attributes are mapped to User Object attributes.
+
+| Evaluation context | User Object  | Required |
+| ------------------ | ------------ | -------- |
+| `TargetingKey`     | `identifier` | &#9745;  | 
+| `Email`            | `email`      |          | 
+| `Country`          | `country`    |          | 
+| Any other          | `custom`     |          | 
+
+To evaluate feature flags for a context, use the <a href="https://openfeature.dev/docs/reference/concepts/evaluation-api/" target="_blank">OpenFeature Evaluation API</a>:
+
+```cs
+MutableContext evaluationContext = new MutableContext();
+evaluationContext.setTargetingKey("#SOME-USER-ID#");
+evaluationContext.add("Email", "[email protected]");
+evaluationContext.add("Country", "CountryID");
+evaluationContext.add("Rating", 4.5);
+
+boolean isAwesomeFeatureEnabled = client.getBooleanValue("isAwesomeFeatureEnabled", false, context);
+```
+
+## Look under the hood
+
+- <a href="https://github.com/open-feature/java-sdk-contrib/tree/main/providers/configcat" target="_blank">ConfigCat OpenFeature Provider's repository on GitHub</a>
+- <a href="https://search.maven.org/artifact/dev.openfeature.contrib.providers/configcat" target="_blank">ConfigCat OpenFeature Provider on Maven Central</a>