You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+1-3Lines changed: 1 addition & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -28,11 +28,9 @@ We use `pytest` for our unit testing, making use of `parametrized` to inject cas
28
28
29
29
The Flagd provider utilizes the [gherkin integration tests](https://github.com/open-feature/test-harness/blob/main/features/evaluation.feature) to validate against a live, seeded Flagd instance.
30
30
31
-
To run the integration tests:
31
+
To run the integration tests you need to have a container runtime, like docker, ranger, etc. installed.
32
32
33
33
```bash
34
-
cd providers/openfeature-provider-flagd
35
-
docker-compose up -d # this runs the flagd sidecars
The flagd provider can operate in two modes: [RPC](#remote-resolver-rpc) (evaluation takes place in flagd, via gRPC calls) or [in-process](#in-process-resolver) (evaluation takes place in-process, with the provider getting a ruleset from a compliant sync-source).
15
+
16
+
### Remote resolver (RPC)
17
+
18
+
This is the default mode of operation of the provider.
19
+
In this mode, `FlagdProvider` communicates with [flagd](https://github.com/open-feature/flagd) via the gRPC protocol.
20
+
Flag evaluations take place remotely at the connected flagd instance.
21
+
13
22
Instantiate a new FlagdProvider instance and configure the OpenFeature SDK to use it:
14
23
15
24
```python
@@ -19,8 +28,11 @@ from openfeature.contrib.provider.flagd import FlagdProvider
19
28
api.set_provider(FlagdProvider())
20
29
```
21
30
31
+
### In-process resolver
22
32
23
-
To use in-process evaluation with flagd gRPC sync service:
33
+
This mode performs flag evaluations locally (in-process). Flag configurations for evaluation are obtained via gRPC protocol using [sync protobuf schema](https://buf.build/open-feature/flagd/file/main:sync/v1/sync_service.proto) service definition.
34
+
35
+
Consider the following example to create a `FlagdProvider` with in-process evaluations,
To use in-process evaluation in offline mode with a file as source:
47
+
In the above example, in-process handlers attempt to connect to a sync service on address `localhost:8013` to obtain [flag definitions](https://github.com/open-feature/schemas/blob/main/json/flags.json).
48
+
49
+
<!--
50
+
#### Sync-metadata
51
+
52
+
To support the injection of contextual data configured in flagd for in-process evaluation, the provider exposes a `getSyncMetadata` accessor which provides the most recent value returned by the [GetMetadata RPC](https://buf.build/open-feature/flagd/docs/main:flagd.sync.v1#flagd.sync.v1.FlagSyncService.GetMetadata).
53
+
The value is updated with every (re)connection to the sync implementation.
54
+
This can be used to enrich evaluations with such data.
55
+
If the `in-process` mode is not used, and before the provider is ready, the `getSyncMetadata` returns an empty map.
56
+
-->
57
+
#### Offline mode
58
+
59
+
In-process resolvers can also work in an offline mode.
60
+
To enable this mode, you should provide a valid flag configuration file with the option `offlineFlagSourcePath`.
> Some configurations are only applicable for RPC resolver.
105
+
106
+
107
+
<!--
108
+
### Unix socket support
109
+
110
+
Unix socket communication with flagd is facilitated by usaging of the linux-native `epoll` library on `linux-x86_64`
111
+
only (ARM support is pending the release of `netty-transport-native-epoll` v5).
112
+
Unix sockets are not supported on other platforms or architectures.
113
+
-->
114
+
115
+
### Reconnection
116
+
117
+
Reconnection is supported by the underlying gRPC connections.
118
+
If the connection to flagd is lost, it will reconnect automatically.
119
+
A failure to connect will result in an [error event](https://openfeature.dev/docs/reference/concepts/events#provider_error) from the provider, though it will attempt to reconnect
120
+
indefinitely.
121
+
122
+
### Deadlines
123
+
124
+
Deadlines are used to define how long the provider waits to complete initialization or flag evaluations.
125
+
They behave differently based on the resolver type.
126
+
127
+
#### Deadlines with Remote resolver (RPC)
128
+
129
+
If the remote evaluation call is not completed within this deadline, the gRPC call is terminated with the error `DEADLINE_EXCEEDED`
130
+
and the evaluation will default.
131
+
132
+
#### Deadlines with In-process resolver
133
+
134
+
In-process resolver with remote evaluation uses the `deadline` for synchronous gRPC calls to fetch metadata from flagd as part of its initialization process.
135
+
If fetching metadata fails within this deadline, the provider will try to reconnect.
136
+
The `streamDeadlineMs` defines a deadline for the streaming connection that listens to flag configuration updates from
137
+
flagd. After the deadline is exceeded, the provider closes the gRPC stream and will attempt to reconnect.
138
+
139
+
In-process resolver with offline evaluation uses the `deadline` for file reads to fetch flag definitions.
140
+
If the provider cannot open and read the file within this deadline, the provider will default the evaluation.
141
+
142
+
143
+
### TLS
144
+
145
+
TLS is available in situations where flagd is running on another host.
146
+
147
+
<!--
148
+
You may optionally supply an X.509 certificate in PEM format. Otherwise, the default certificate store will be used.
149
+
150
+
```java
151
+
FlagdProvider flagdProvider = new FlagdProvider(
152
+
FlagdOptions.builder()
153
+
.host("myflagdhost")
154
+
.tls(true) // use TLS
155
+
.certPath("etc/cert/ca.crt") // PEM cert
156
+
.build());
157
+
```
158
+
-->
159
+
160
+
### Caching (RPC only)
161
+
162
+
> [!NOTE]
163
+
> The in-process resolver does not benefit from caching since all evaluations are done locally and do not involve I/O.
164
+
165
+
The provider attempts to establish a connection to flagd's event stream (up to 5 times by default).
166
+
If the connection is successful and caching is enabled, each flag returned with the reason `STATIC` is cached until an event is received
167
+
concerning the cached flag (at which point it is removed from the cache).
168
+
169
+
On invocation of a flag evaluation (if caching is available), an attempt is made to retrieve the entry from the cache, if
170
+
found the flag is returned with the reason `CACHED`.
171
+
172
+
By default, the provider is configured to
173
+
use [least recently used (lru)](https://pypi.org/project/cachebox/)
0 commit comments