open-feature
/
flagd
mirror of https://github.com/open-feature/flagd.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: removed RPC section and fixed grammatical issues (#945) 

## This PR

- remove RPC section from the in-process docs
- addressed various grammatical issues

---------

Signed-off-by: Michael Beemer <beeme1mr@users.noreply.github.com>
Co-authored-by: Todd Baert <todd.baert@dynatrace.com>
This commit is contained in:
Michael Beemer 2023-09-29 10:56:36 -04:00 committed by GitHub
parent e7cee41630
commit 0089dc3122
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 9 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
docs/reference/specifications/in-process-providers.md
View File

@ -1,12 +1,7 @@
# Creating an in-process flagd provider # Creating an in-process flagd provider
By default, **flagd** is a remote service that is accessed via **grpc** by a client application to retrieve feature flags. An in-process flagd provider is designed to be embedded into the application, and therefore no communication outside the process of the application for feature flag evaluation is needed.
Depending on the environment, flagd therefore is usually deployed as a standalone service, e.g. as a Kubernetes Deployment, This can be desirable in some cases, particularly if latency is a concern.
or injected as a sidecar container into the pod running the client application,
as it is done in the [OpenFeature Operator](https://github.com/open-feature/open-feature-operator).
An in-process flagd provider, on the other hand, is designed to be embedded into the application and therefore
no communication outside the process of the application for feature flag evaluation is needed. This can be desired by some architectures,
especially if flag retrievals should not take longer than a certain amount of time.
The in-process flagd provider is responsible for creating an abstraction between the [JsonLogic](https://jsonlogic.com) based evaluation of flag configurations following the [flag configuration scheme](https://github.com/open-feature/schemas/blob/main/json/flagd-definitions.json) used by `flagd` and the OpenFeature SDK (for the [chosen technology](https://openfeature.dev/docs/reference/technologies/)). The in-process flagd provider is responsible for creating an abstraction between the [JsonLogic](https://jsonlogic.com) based evaluation of flag configurations following the [flag configuration scheme](https://github.com/open-feature/schemas/blob/main/json/flagd-definitions.json) used by `flagd` and the OpenFeature SDK (for the [chosen technology](https://openfeature.dev/docs/reference/technologies/)).
@ -24,7 +19,7 @@ An implementation of an in-process flagd-provider must accept the following envi
- `FLAGD_SOURCE_URI`: The URI identifying the sync source. Depending on the sync provider type, this can be the URI of a gRPC service providing the `sync` API required by the in-process flagd provider, or the name of a [core.openfeature.dev/v1alpha2.FeatureFlagConfiguration](https://github.com/open-feature/open-feature-operator/blob/main/docs/crds.md#featureflagconfiguration-1) Custom Resource containing the flag definition. - `FLAGD_SOURCE_URI`: The URI identifying the sync source. Depending on the sync provider type, this can be the URI of a gRPC service providing the `sync` API required by the in-process flagd provider, or the name of a [core.openfeature.dev/v1alpha2.FeatureFlagConfiguration](https://github.com/open-feature/open-feature-operator/blob/main/docs/crds.md#featureflagconfiguration-1) Custom Resource containing the flag definition.
- `FLAGD_SOURCE_PROVIDER_TYPE`: The type of the provider. E.g. `grpc` or `kubernetes`. - `FLAGD_SOURCE_PROVIDER_TYPE`: The type of the provider. E.g. `grpc` or `kubernetes`.
- `FLAGD_SOURCE_SELECTOR`: Optional selector for the feature flag definition of interest. This is used as a `selector` for the flagd-proxie's sync API to identify a flag definition within a collection of feature flag definition. - `FLAGD_SOURCE_SELECTOR`: Optional selector for the feature flag definition of interest. This is used as a `selector` for the flagd-proxie's sync API to identify a flag definition within a collection of feature flag definitions.
An implementation of an in-process flagd provider should provide a source for retrieving the flag definition, namely a gRPC source. An implementation of an in-process flagd provider should provide a source for retrieving the flag definition, namely a gRPC source.
Other sources may be desired eventually, so separation of concerns should be maintained between the abstractions evaluating flags and those retrieving confirmation. Other sources may be desired eventually, so separation of concerns should be maintained between the abstractions evaluating flags and those retrieving confirmation.
@ -42,7 +37,7 @@ Protobuf schemas define the contract between a client (flagd or the in-process p
#### Code generation for gRPC sync #### Code generation for gRPC sync
Leverage the [buf CLI](https://docs.buf.build/installation) or protoc to generate a `flagd-proxy` client in the chosen technology: Leverage the [buf CLI](https://docs.buf.build/installation) or [protoc](https://grpc.io/docs/protoc-installation/) to generate a `flagd-proxy` client in the chosen technology:
Add the [open-feature schema repository](https://github.com/open-feature/schemas) as a submodule Add the [open-feature schema repository](https://github.com/open-feature/schemas) as a submodule
@ -75,7 +70,7 @@ If available, the JsonLogic library for the chosen technology should be used.
In addition to the built-in evaluators provided by JsonLogic, the following custom targeting rules should be implemented by the provider: In addition to the built-in evaluators provided by JsonLogic, the following custom targeting rules should be implemented by the provider:
- [Fractional operation](../../reference/custom-operations/fractional-operation.md): - [Fractional operation](../../reference/custom-operations/fractional-operation.md):
This evaluator allows to split the returned variants of a feature flag into different buckets, where each bucket This evaluator allows splitting of the returned variants of a feature flag into different buckets, where each bucket
can be assigned a percentage, representing how many requests will resolve to the corresponding variant. can be assigned a percentage, representing how many requests will resolve to the corresponding variant.
The sum of all weights must be 100, and the distribution must be performed by using the value of a referenced The sum of all weights must be 100, and the distribution must be performed by using the value of a referenced
from the evaluation context to hash that value and map it to a value between [0, 100]. from the evaluation context to hash that value and map it to a value between [0, 100].
@ -179,13 +174,13 @@ In-process flagd providers should do the following to make use of OpenFeature v0
- note that the SDK will automatically emit `PROVIDER_READY`/`PROVIDER_ERROR` according to the termination of the `initialization` function - note that the SDK will automatically emit `PROVIDER_READY`/`PROVIDER_ERROR` according to the termination of the `initialization` function
- throw an exception or terminate abnormally if a connection cannot be established during `initialization` - throw an exception or terminate abnormally if a connection cannot be established during `initialization`
- For gRPC based sources (i.e. flagd-proxy), attempt to restore the streaming connection to flagd-proxy (if the connection cannot be established or is broken): - For gRPC based sources (i.e. flagd-proxy), attempt to restore the streaming connection to flagd-proxy (if the connection cannot be established or is broken):
- If flag definition have been retrieved previously, go into `STALE` state to indicate that flag resolution responsees are based on potentially outdated Flag definition. - If flag definition have been retrieved previously, go into `STALE` state to indicate that flag resolution responses are based on potentially outdated Flag definition.
- reconnection should be attempted with an exponential back-off, with a max-delay of `maxSyncRetryInterval` (see [configuration](#configuration)) - reconnection should be attempted with an exponential back-off, with a max-delay of `maxSyncRetryInterval` (see [configuration](#configuration))
- reconnection should be attempted up to `maxSyncRetryDelay` times (see [configuration](#configuration)) - reconnection should be attempted up to `maxSyncRetryDelay` times (see [configuration](#configuration))
- `PROVIDER_READY` and `PROVIDER_CONFIGURATION_CHANGED` should be emitted, in that order, after successful reconnection - `PROVIDER_READY` and `PROVIDER_CONFIGURATION_CHANGED` should be emitted, in that order, after successful reconnection
- For Kubernetes sync sources, retry to retrieve the FlagConfiguration resource, using an exponential back-off strategy, with a max-delay of `maxSyncRetryInterval` (see [configuration](#configuration)) - For Kubernetes sync sources, retry to retrieve the FlagConfiguration resource, using an exponential back-off strategy, with a max-delay of `maxSyncRetryInterval` (see [configuration](#configuration))
- emit `PROVIDER_CONFIGURATION_CHANGED` event and update ruleset when a `configuration_change` message is received on the streaming connection - emit `PROVIDER_CONFIGURATION_CHANGED` event and update the ruleset when a `configuration_change` message is received on the streaming connection
- close the streaming connection in the`shutdown` function - close the streaming connection in the `shutdown` function
```mermaid ```mermaid
stateDiagram-v2 stateDiagram-v2
@ -243,5 +238,4 @@ The following steps will extend the reach of the newly created provider to other
### Open an issue to document the provider ### Open an issue to document the provider
Create an issue in openfeature.dev [here](https://github.com/open-feature/openfeature.dev/issues/new?assignees=&labels=provider&template=document-provider.yaml&title=%5BProvider%5D%3A+). Create an issue [here](https://github.com/open-feature/openfeature.dev/issues/new?assignees=&labels=provider&template=document-provider.yaml&title=%5BProvider%5D%3A+) for adding the provider to [openfeature.dev](https://openfeature.dev).
This will ensure the provider is added to OpenFeature's website.