Skip to content

Commit a4cd7f5

Browse files
aepfliaepfli
committed
feat: migrate file evaluation to own provider type
Signed-off-by: Simon Schrottner <simon.schrottner@dynatrace.com>
1 parent eeae9a6 commit a4cd7f5

File tree

1 file changed

+35
-29
lines changed

1 file changed

+35
-29
lines changed

‎docs/reference/specifications/providers.md

Lines changed: 35 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,15 @@ This document outlines their behavior and configuration.
1717

1818
Consistent with our [naming conventions](../naming.md), the flagd provider name (no matter what language or runtime is in use) is `flagd`.
1919

20-
## In-Process vs RPC Evaluation
20+
## Overview of Resolver Types
2121

22-
There are two modes of operation (`resolvers`) for flagd providers; _in-process_ and _RPC_.
23-
Both modes have their advantages and disadvantages.
24-
For more information on the architectural implications of these different modes, see the [RPC vs In-Process Evaluation](../../architecture.md#rpc-vs-in-process-evaluation) page.
22+
There are three resolver types for flagd providers:
23+
24+
- RPC Resolver: Evaluates flags remotely by connecting to a flagd instance using the gRPC evaluation protocol.
25+
- In-Process Resolver: Downloads the flag set rules from a flagd instance and evaluates them locally, offering low-latency performance.
26+
- File Resolver: Operates offline by reading flag definitions from a file, ideal for environments without network connectivity.
27+
28+
Each resolver type has unique characteristics and use cases. Below, we delve into their specifics.
2529

2630
## flagd Provider Lifecycle
2731

@@ -117,7 +121,7 @@ While the provider is in state `STALE` the provider resolves values from its cac
117121
When the time since the last disconnect first exceeds `retryGracePeriod`, the provider emits `ERROR`.
118122
The provider attempts to reconnect indefinitely, with a maximum interval of `retryBackoffMaxMs`.
119123

120-
## RPC Evaluation
124+
## RPC Resolver
121125

122126
RPC providers use the [evaluation protocol](./protos.md#flagdevaluationv1evaluationproto) to connect to flagd, initiate the [event stream](./protos.md#eventstreamresponse), listen for changes in the flag definitions, and evaluate flags remotely by calling flagd.
123127
RPC providers are relatively simple to implement since they essentially call a remote flagd instance with relevant parameters, and then flagd responds with the resolved flag value.
@@ -188,7 +192,7 @@ This pattern is consistent with OpenFeature's [static context paradigm](https://
188192

189193
The provider metadata includes properties returned from the [provider_ready event payload](./protos.md#eventstreamresponse) data.
190194

191-
## In-Process Evaluation
195+
## In-Process Resolver
192196

193197
In-process providers use the [sync schema](./protos.md#syncflagsresponse) to connect to flagd, initiate the [sync stream](./protos.md#eventstreamresponse), and download the `flag set` rules to evaluate them locally.
194198
In-process providers are relatively complex (compared to RPC providers) to implement since they essentially must implement more of flagd's logic to evaluate flags locally.
@@ -237,11 +241,13 @@ If only a subset of the sync-metadata response is desired to be injected into th
237241

238242
The provider metadata includes the top-level metadata properties in the [flag definition](../flag-definitions.md).
239243

240-
### Offline (File) Mode
244+
## File Resolver (Offline Mode)
241245

242246
The in-process resolver mode can also use a file based [flag definition](../flag-definitions.md).
243247
This does not connect to a flagd instance or gRPC sync implementation, and instead polls a flag definition from a file.
244-
If the file has been modified since the last poll (based on the file metadata) and [flags have changed](#changed-flags), a `PROVIDER_CONFIGURATION_CHANGED` event with the appropriate `changed flags` field is emitted.
248+
If the file has been modified since the last poll (based on the file metadata) and [flags have changed](#changed-flags), a `PROVIDER_CONFIGURATION_CHANGED` event with the appropriate `changed flags` field is emitted.
249+
250+
The Evaluation uses [JsonLogic](#jsonlogic-evaluation) and [custom JsonLogic evaluators](#custom-jsonlogic-evaluators) like the [InProcess Resolver](#in-process-resolver).
245251

246252
!!! note
247253

@@ -256,27 +262,27 @@ precedence.
256262

257263
Below are the supported configuration parameters (note that not all apply to both resolver modes):
258264

259-
| Option name | Environment variable name | Explanation | Type & Values | Default | Compatible resolver |
260-
|-----------------------|--------------------------------|------------------------------------------------------------------------| ---------------------------- | ----------------------------- | ------------------- |
261-
| resolver | FLAGD_RESOLVER | mode of operation | String - `rpc`, `in-process` | rpc | rpc & in-process |
262-
| host | FLAGD_HOST | remote host | String | localhost | rpc & in-process |
263-
| port | FLAGD_PORT | remote port | int | 8013 (rpc), 8015 (in-process) | rpc & in-process |
264-
| targetUri | FLAGD_TARGET_URI | alternative to host/port, supporting custom name resolution | string | null | rpc & in-process |
265-
| tls | FLAGD_TLS | connection encryption | boolean | false | rpc & in-process |
266-
| socketPath | FLAGD_SOCKET_PATH | alternative to host port, unix socket | String | null | rpc & in-process |
267-
| certPath | FLAGD_SERVER_CERT_PATH | tls cert path | String | null | rpc & in-process |
268-
| deadlineMs | FLAGD_DEADLINE_MS | deadline for unary calls, and timeout for initialization | int | 500 | rpc & in-process |
269-
| streamDeadlineMs | FLAGD_STREAM_DEADLINE_MS | deadline for streaming calls, useful as an application-layer keepalive | int | 600000 | rpc & in-process |
270-
| retryBackoffMs | FLAGD_RETRY_BACKOFF_MS | initial backoff for stream retry | int | 1000 | rpc & in-process |
271-
| retryBackoffMaxMs | FLAGD_RETRY_BACKOFF_MAX_MS | maximum backoff for stream retry | int | 120000 | rpc & in-process |
272-
| retryGracePeriod | FLAGD_RETRY_GRACE_PERIOD | period in seconds before provider moves from STALE to ERROR state | int | 5 | rpc & in-process |
273-
| keepAliveTime | FLAGD_KEEP_ALIVE_TIME_MS | http 2 keepalive | long | 0 | rpc & in-process |
274-
| cache | FLAGD_CACHE | enable cache of static flags | String - `lru`, `disabled` | lru | rpc |
275-
| maxCacheSize | FLAGD_MAX_CACHE_SIZE | max size of static flag cache | int | 1000 | rpc |
276-
| selector | FLAGD_SOURCE_SELECTOR | selects a single sync source to retrieve flags from only that source | string | null | in-process |
277-
| offlineFlagSourcePath | FLAGD_OFFLINE_FLAG_SOURCE_PATH | offline, file-based flag definitions, overrides host/port/targetUri | string | null | in-process |
278-
| offlinePollIntervalMs | FLAGD_OFFLINE_POLL_MS | poll interval for reading offlineFlagSourcePath | int | 5000 | in-process |
279-
| contextEnricher | - | sync-metadata to evaluation context mapping function | function | identity function | in-process |
265+
| Option name | Environment variable name | Explanation | Type & Values | Default | Compatible resolver |
266+
|-----------------------|--------------------------------|------------------------------------------------------------------------|------------------------------|-------------------------------|-------------------------|
267+
| resolver | FLAGD_RESOLVER | mode of operation | String - `rpc`, `in-process` | rpc | rpc & in-process |
268+
| host | FLAGD_HOST | remote host | String | localhost | rpc & in-process |
269+
| port | FLAGD_PORT | remote port | int | 8013 (rpc), 8015 (in-process) | rpc & in-process |
270+
| targetUri | FLAGD_TARGET_URI | alternative to host/port, supporting custom name resolution | string | null | rpc & in-process |
271+
| tls | FLAGD_TLS | connection encryption | boolean | false | rpc & in-process |
272+
| socketPath | FLAGD_SOCKET_PATH | alternative to host port, unix socket | String | null | rpc & in-process |
273+
| certPath | FLAGD_SERVER_CERT_PATH | tls cert path | String | null | rpc & in-process |
274+
| deadlineMs | FLAGD_DEADLINE_MS | deadline for unary calls, and timeout for initialization | int | 500 | rpc & in-process & file |
275+
| streamDeadlineMs | FLAGD_STREAM_DEADLINE_MS | deadline for streaming calls, useful as an application-layer keepalive | int | 600000 | rpc & in-process |
276+
| retryBackoffMs | FLAGD_RETRY_BACKOFF_MS | initial backoff for stream retry | int | 1000 | rpc & in-process |
277+
| retryBackoffMaxMs | FLAGD_RETRY_BACKOFF_MAX_MS | maximum backoff for stream retry | int | 120000 | rpc & in-process |
278+
| retryGracePeriod | FLAGD_RETRY_GRACE_PERIOD | period in seconds before provider moves from STALE to ERROR state | int | 5 | rpc & in-process & file |
279+
| keepAliveTime | FLAGD_KEEP_ALIVE_TIME_MS | http 2 keepalive | long | 0 | rpc & in-process |
280+
| cache | FLAGD_CACHE | enable cache of static flags | String - `lru`, `disabled` | lru | rpc |
281+
| maxCacheSize | FLAGD_MAX_CACHE_SIZE | max size of static flag cache | int | 1000 | rpc |
282+
| selector | FLAGD_SOURCE_SELECTOR | selects a single sync source to retrieve flags from only that source | string | null | in-process |
283+
| offlineFlagSourcePath | FLAGD_OFFLINE_FLAG_SOURCE_PATH | offline, file-based flag definitions, overrides host/port/targetUri | string | null | file |
284+
| offlinePollIntervalMs | FLAGD_OFFLINE_POLL_MS | poll interval for reading offlineFlagSourcePath | int | 5000 | file |
285+
| contextEnricher | - | sync-metadata to evaluation context mapping function | function | identity function | in-process |
280286

281287
### Custom Name Resolution
282288

0 commit comments

Comments
 (0)