openfeature-provider-flagd 0.1.4__tar.gz → 0.2.0__tar.gz

{openfeature_provider_flagd-0.1.4 → openfeature_provider_flagd-0.2.0}/.gitignore

@@ -51,3 +51,6 @@ docs/_build/
 
 # Virtual env directories
 .venv
+
+# vscode
+.vscode/

openfeature_provider_flagd-0.2.0/CHANGELOG.md

@@ -0,0 +1,118 @@
+# Changelog
+
+## [0.2.0](https://github.com/open-feature/python-sdk-contrib/compare/openfeature-provider-flagd/v0.1.5...openfeature-provider-flagd/v0.2.0) (2025-02-18)
+
+
+### ⚠ BREAKING CHANGES
+
+* drop Python 3.8 support ([#187](https://github.com/open-feature/python-sdk-contrib/issues/187))
+* **flagd-rpc:** add events for rpc mode, some breaking config fixes ([#108](https://github.com/open-feature/python-sdk-contrib/issues/108))
+
+### 🐛 Bug Fixes
+
+* **flagd:** fix semver version parsing to allow "v" prefix([#106](https://github.com/open-feature/python-sdk-contrib/issues/106)) ([#107](https://github.com/open-feature/python-sdk-contrib/issues/107)) ([93fee85](https://github.com/open-feature/python-sdk-contrib/commit/93fee8593c8c278dff6371b68b21366bea9d5f01))
+* **flagd:** improve targeting and fix fractional issue([#92](https://github.com/open-feature/python-sdk-contrib/issues/92)) ([#105](https://github.com/open-feature/python-sdk-contrib/issues/105)) ([eb31b83](https://github.com/open-feature/python-sdk-contrib/commit/eb31b8324662df113cd27205eb12f09a1cf30b06))
+* object resolution for RPC and Object types, add test-harness ([ca76802](https://github.com/open-feature/python-sdk-contrib/commit/ca7680242085fb9b77d9b0844147468544010074))
+* object resolution for RPC and Object types, add test-harness. ([#103](https://github.com/open-feature/python-sdk-contrib/issues/103)) ([ca76802](https://github.com/open-feature/python-sdk-contrib/commit/ca7680242085fb9b77d9b0844147468544010074))
+* remove modifications to license files ([#81](https://github.com/open-feature/python-sdk-contrib/issues/81)) ([a23f61e](https://github.com/open-feature/python-sdk-contrib/commit/a23f61e1c14c70e45a4bce4a014d5599813f1d28))
+
+
+### ✨ New Features
+
+* attempts with connection improvements ([#118](https://github.com/open-feature/python-sdk-contrib/issues/118)) ([8e23a70](https://github.com/open-feature/python-sdk-contrib/commit/8e23a700244a85291671b41083b1be82670cf79d))
+* Change fractional custom op from percentage-based to relative weighting. ([#91](https://github.com/open-feature/python-sdk-contrib/issues/91)) ([7b34822](https://github.com/open-feature/python-sdk-contrib/commit/7b34822afdabfb89e991ae81a91681cafcbdfbd3))
+* **flagd-rpc:** add caching  ([#110](https://github.com/open-feature/python-sdk-contrib/issues/110)) ([16179e3](https://github.com/open-feature/python-sdk-contrib/commit/16179e3e68eb5bc18b5d12ec80caf511b7dec762))
+* **flagd-rpc:** add events for rpc mode, some breaking config fixes ([#108](https://github.com/open-feature/python-sdk-contrib/issues/108)) ([b62d3d1](https://github.com/open-feature/python-sdk-contrib/commit/b62d3d1ab5ce40f275e795ae2682ae3fe315f431))
+* **flagd-rpc:** adding grace attempts ([#117](https://github.com/open-feature/python-sdk-contrib/issues/117)) ([41d0ad8](https://github.com/open-feature/python-sdk-contrib/commit/41d0ad8b6a5b32272c75684cfcbabffb57e53470))
+* **flagd:** add custom cert path ([#131](https://github.com/open-feature/python-sdk-contrib/issues/131)) ([f50351a](https://github.com/open-feature/python-sdk-contrib/commit/f50351a0435064111fb98753a49139fafa8307e6))
+* **flagd:** Add in-process evaluator ([#104](https://github.com/open-feature/python-sdk-contrib/issues/104)) ([01285e7](https://github.com/open-feature/python-sdk-contrib/commit/01285e726baa3acbf1b5d6ed0e802be54342a6d9))
+* **flagd:** add ssl cert path option ([f50351a](https://github.com/open-feature/python-sdk-contrib/commit/f50351a0435064111fb98753a49139fafa8307e6))
+* **flagd:** migrate to new provider mode file and update e2e tests ([#121](https://github.com/open-feature/python-sdk-contrib/issues/121)) ([eed1ee0](https://github.com/open-feature/python-sdk-contrib/commit/eed1ee053191ecaca21f82749da9fe443712206f))
+* **flagd:** use test-harness version number for integration tests ([#120](https://github.com/open-feature/python-sdk-contrib/issues/120)) ([3c3e9c8](https://github.com/open-feature/python-sdk-contrib/commit/3c3e9c86e7111fc165eebd650453069a0e8f4dae))
+
+
+### 🧹 Chore
+
+* **deps:** update dependency grpcio-health-checking to v1.68.1 ([#125](https://github.com/open-feature/python-sdk-contrib/issues/125)) ([4e75a36](https://github.com/open-feature/python-sdk-contrib/commit/4e75a366468ab0f588031587a7224d16ae6cd0c6))
+* **deps:** update dependency grpcio-health-checking to v1.69.0 ([#147](https://github.com/open-feature/python-sdk-contrib/issues/147)) ([905b42b](https://github.com/open-feature/python-sdk-contrib/commit/905b42b6e654c86c9161f02d87a812ad4ac42bed))
+* **deps:** update dependency grpcio-health-checking to v1.70.0 ([#168](https://github.com/open-feature/python-sdk-contrib/issues/168)) ([06a9b58](https://github.com/open-feature/python-sdk-contrib/commit/06a9b5880093680575422e3e16d14a81f2cd7bef))
+* **deps:** update dependency providers/openfeature-provider-flagd/openfeature/test-harness to v0.5.21 ([#145](https://github.com/open-feature/python-sdk-contrib/issues/145)) ([1495263](https://github.com/open-feature/python-sdk-contrib/commit/149526337c5fd9948e10a1e3aab0176f2d1e7c8b))
+* **deps:** update dependency providers/openfeature-provider-flagd/openfeature/test-harness to v2 ([#178](https://github.com/open-feature/python-sdk-contrib/issues/178)) ([ce16a54](https://github.com/open-feature/python-sdk-contrib/commit/ce16a5406e7e2d36fabe1ebe704f3a528e72027f))
+* **deps:** update dependency providers/openfeature-provider-flagd/openfeature/test-harness to v2.2.0 ([#190](https://github.com/open-feature/python-sdk-contrib/issues/190)) ([9db9ad6](https://github.com/open-feature/python-sdk-contrib/commit/9db9ad62445deae3bb50505cb9d6a902d3234d34))
+* **deps:** update pre-commit hook astral-sh/ruff-pre-commit to v0.9.0 ([#149](https://github.com/open-feature/python-sdk-contrib/issues/149)) ([24b11e1](https://github.com/open-feature/python-sdk-contrib/commit/24b11e14599251a47d70ee5b4080a326206f85a6))
+* **deps:** update providers/openfeature-provider-flagd/openfeature/schemas digest to 76d611f ([#138](https://github.com/open-feature/python-sdk-contrib/issues/138)) ([853ece7](https://github.com/open-feature/python-sdk-contrib/commit/853ece72feb558b208cad5680c358c4b09aabf91))
+* **deps:** update providers/openfeature-provider-flagd/openfeature/schemas digest to b81a56e ([#134](https://github.com/open-feature/python-sdk-contrib/issues/134)) ([a2a0ba0](https://github.com/open-feature/python-sdk-contrib/commit/a2a0ba0d9a59c763829fa630fdc2f28b93b2f037))
+* **deps:** update providers/openfeature-provider-flagd/openfeature/spec digest to 54952f3 ([#188](https://github.com/open-feature/python-sdk-contrib/issues/188)) ([d88b29a](https://github.com/open-feature/python-sdk-contrib/commit/d88b29a01b14d411027007395e6de881602e91a1))
+* **deps:** update providers/openfeature-provider-flagd/openfeature/spec digest to 5b07065 ([#171](https://github.com/open-feature/python-sdk-contrib/issues/171)) ([6f45c15](https://github.com/open-feature/python-sdk-contrib/commit/6f45c15b4da2a404cc0583fa3c4f8d22de13fad1))
+* **deps:** update providers/openfeature-provider-flagd/openfeature/spec digest to 6c673d7 ([#151](https://github.com/open-feature/python-sdk-contrib/issues/151)) ([1c2c650](https://github.com/open-feature/python-sdk-contrib/commit/1c2c650bd7f0f5b5953bbb3948c3d657172e46ff))
+* **deps:** update providers/openfeature-provider-flagd/openfeature/spec digest to 8d6eeb3 ([#177](https://github.com/open-feature/python-sdk-contrib/issues/177)) ([02dcfc0](https://github.com/open-feature/python-sdk-contrib/commit/02dcfc02089f3a0a3f300e3a2485e9f847ff765e))
+* **deps:** update providers/openfeature-provider-flagd/openfeature/spec digest to 95fe981 ([#184](https://github.com/open-feature/python-sdk-contrib/issues/184)) ([f1fb247](https://github.com/open-feature/python-sdk-contrib/commit/f1fb2477f61a1a37ecfcbd858a80bdfac277340b))
+* **deps:** update providers/openfeature-provider-flagd/openfeature/spec digest to a69f748 ([#193](https://github.com/open-feature/python-sdk-contrib/issues/193)) ([4251f36](https://github.com/open-feature/python-sdk-contrib/commit/4251f36d8ac1fbb70e44a87bea3b2755bcf09ecf))
+* **deps:** update providers/openfeature-provider-flagd/openfeature/spec digest to be56f22 ([#186](https://github.com/open-feature/python-sdk-contrib/issues/186)) ([a15d5a2](https://github.com/open-feature/python-sdk-contrib/commit/a15d5a230e5a7d5a66a2cce4341f312bf98a3503))
+* **deps:** update providers/openfeature-provider-flagd/openfeature/spec digest to d261f68 ([#140](https://github.com/open-feature/python-sdk-contrib/issues/140)) ([6801522](https://github.com/open-feature/python-sdk-contrib/commit/68015220ea9005286c0a45d4cdeb3891d9f43b3b))
+* **deps:** update providers/openfeature-provider-flagd/openfeature/spec digest to ed0f9ef ([#135](https://github.com/open-feature/python-sdk-contrib/issues/135)) ([bee9205](https://github.com/open-feature/python-sdk-contrib/commit/bee9205d475473b5005fbbea9b4b5c756ad1d20e))
+* drop Python 3.8 support ([#187](https://github.com/open-feature/python-sdk-contrib/issues/187)) ([b55cc1e](https://github.com/open-feature/python-sdk-contrib/commit/b55cc1e0f823d05a330c12af6861dbd3bec69c3a))
+
+
+### 🔄 Refactoring
+
+* replace typing_extensions import ([#98](https://github.com/open-feature/python-sdk-contrib/issues/98)) ([adb8a69](https://github.com/open-feature/python-sdk-contrib/commit/adb8a69d9ed1b0b03cb96d924b2269d973822794))
+
+## [0.1.5](https://github.com/open-feature/python-sdk-contrib/compare/openfeature-provider-flagd/v0.1.4...openfeature-provider-flagd/v0.1.5) (2024-04-11)
+
+
+### ✨ New Features
+
+* in-process offline flagd resolver ([#74](https://github.com/open-feature/python-sdk-contrib/issues/74)) ([8cea506](https://github.com/open-feature/python-sdk-contrib/commit/8cea5066ee96f637f3108a9dc3a7539c450a14be))
+
+## [0.1.4](https://github.com/open-feature/python-sdk-contrib/compare/openfeature-provider-flagd/v0.1.3...openfeature-provider-flagd/v0.1.4) (2024-03-26)
+
+
+### 🐛 Bug Fixes
+
+* include targetingKey in flagd serialized evaluation context ([#58](https://github.com/open-feature/python-sdk-contrib/issues/58)) ([ddd79a4](https://github.com/open-feature/python-sdk-contrib/commit/ddd79a49b765aa0679a2c1938447c61b37b6d0fe))
+* respect timeout setting in grpc method calls ([#60](https://github.com/open-feature/python-sdk-contrib/issues/60)) ([0149cf7](https://github.com/open-feature/python-sdk-contrib/commit/0149cf7ced8116f54a9b220549834a1970460bd9))
+* return proper metadata object in FlagdProvider ([#59](https://github.com/open-feature/python-sdk-contrib/issues/59)) ([6508234](https://github.com/open-feature/python-sdk-contrib/commit/6508234486ba0b650e849cbee22505988233131a))
+
+
+### ✨ New Features
+
+* implement environment-variable based config ([#62](https://github.com/open-feature/python-sdk-contrib/issues/62)) ([a8b78b2](https://github.com/open-feature/python-sdk-contrib/commit/a8b78b28fe44ca712b00db04ac1a23a9c9bc6d9b))
+* replace schema with tls argument in FlagdProvider constructor ([#61](https://github.com/open-feature/python-sdk-contrib/issues/61)) ([7a7210f](https://github.com/open-feature/python-sdk-contrib/commit/7a7210f6f63a9cba886f4d512c01ebac39d910a9))
+
+
+### 🧹 Chore
+
+* exclude generated protobuf files from coverage report ([#51](https://github.com/open-feature/python-sdk-contrib/issues/51)) ([660a0cb](https://github.com/open-feature/python-sdk-contrib/commit/660a0cbc9bb932ac0dd9cb09f1d75177b161601b))
+
+
+### 🔄 Refactoring
+
+* add mypy and fix typing issues ([#72](https://github.com/open-feature/python-sdk-contrib/issues/72)) ([b405925](https://github.com/open-feature/python-sdk-contrib/commit/b4059255045cdb7054a35bc338207e23c42ce068))
+
+## [0.1.3](https://github.com/open-feature/python-sdk-contrib/compare/openfeature-provider-flagd/v0.1.2...openfeature-provider-flagd/v0.1.3) (2024-02-23)
+
+
+### 🐛 Bug Fixes
+
+* include proto file in build for openfeature-provider-flagd ([#45](https://github.com/open-feature/python-sdk-contrib/issues/45)) ([7783cc8](https://github.com/open-feature/python-sdk-contrib/commit/7783cc8e7fb8fe0f9b812938efcd1f4c07e3ff68))
+
+## [0.1.2](https://github.com/open-feature/python-sdk-contrib/compare/openfeature-provider-flagd-v0.1.1...openfeature-provider-flagd/v0.1.2) (2024-02-22)
+
+
+### 🐛 Bug Fixes
+
+* remove mention of local eval in readme ([41df80e](https://github.com/open-feature/python-sdk-contrib/commit/41df80e1b3044356e3b228a484f3a13c92068d91))
+* remove setup from flagd tests ([#39](https://github.com/open-feature/python-sdk-contrib/issues/39)) ([85661ff](https://github.com/open-feature/python-sdk-contrib/commit/85661ff170b378d37b0a3d5d0a955dad3417f538))
+
+
+### 🧹 Chore
+
+* **main:** release providers/flagd 0.1.1 ([#40](https://github.com/open-feature/python-sdk-contrib/issues/40)) ([d42ee1e](https://github.com/open-feature/python-sdk-contrib/commit/d42ee1e531249e0023456dbe46db2f4f0c52a5c5))
+
+## [0.1.1](https://github.com/open-feature/python-sdk-contrib/compare/providers/flagd-v0.1.0...providers/flagd/v0.1.1) (2024-02-22)
+
+
+### 🐛 Bug Fixes
+
+* remove setup from flagd tests ([#39](https://github.com/open-feature/python-sdk-contrib/issues/39)) ([85661ff](https://github.com/open-feature/python-sdk-contrib/commit/85661ff170b378d37b0a3d5d0a955dad3417f538))

{openfeature_provider_flagd-0.1.4 → openfeature_provider_flagd-0.2.0}/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright The OpenTelemetry Authors
+   Copyright [yyyy] [name of copyright owner]
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

{openfeature_provider_flagd-0.1.4 → openfeature_provider_flagd-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: openfeature-provider-flagd
-Version: 0.1.4
+Version: 0.2.0
 Summary: OpenFeature provider for the flagd flag evaluation engine
 Project-URL: Homepage, https://github.com/open-feature/python-sdk-contrib
 Author-email: OpenFeature <openfeature-core@groups.io>
@@ -192,7 +192,7 @@ License:                                  Apache License
               same "printed page" as the copyright notice for easier
               identification within third-party archives.
         
-           Copyright The OpenTelemetry Authors
+           Copyright [yyyy] [name of copyright owner]
         
            Licensed under the Apache License, Version 2.0 (the "License");
            you may not use this file except in compliance with the License.
@@ -209,15 +209,20 @@ License-File: LICENSE
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.8
-Requires-Dist: grpcio>=1.60.0
-Requires-Dist: openfeature-sdk>=0.4.0
-Requires-Dist: protobuf>=4.25.2
+Requires-Python: >=3.9
+Requires-Dist: cachebox
+Requires-Dist: grpcio>=1.68.1
+Requires-Dist: mmh3>=4.1.0
+Requires-Dist: openfeature-sdk>=0.6.0
+Requires-Dist: panzi-json-logic>=1.0.1
+Requires-Dist: protobuf>=4.29.2
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: semver<4,>=3
 Description-Content-Type: text/markdown
 
 # flagd Provider for OpenFeature
 
-This provider is designed to use flagd's [evaluation protocol](https://github.com/open-feature/schemas/blob/main/protobuf/schema/v1/schema.proto).
+This provider is designed to use flagd's [evaluation protocol](https://github.com/open-feature/schemas/blob/main/protobuf/schema/v1/schema.proto), or locally evaluate flags defined in a flagd [flag definition](https://github.com/open-feature/schemas/blob/main/json/flagd-definitions.json) via the OpenFeature Python SDK.
 
 ## Installation
 
@@ -227,6 +232,14 @@ pip install openfeature-provider-flagd
 
 ## Configuration and Usage
 
+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).
+
+### Remote resolver (RPC)
+
+This is the default mode of operation of the provider.
+In this mode, `FlagdProvider` communicates with [flagd](https://github.com/open-feature/flagd) via the gRPC protocol.
+Flag evaluations take place remotely at the connected flagd instance.
+
 Instantiate a new FlagdProvider instance and configure the OpenFeature SDK to use it:
 
 ```python
@@ -236,16 +249,121 @@ from openfeature.contrib.provider.flagd import FlagdProvider
 api.set_provider(FlagdProvider())
 ```
 
+### In-process resolver
+
+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.
+
+Consider the following example to create a `FlagdProvider` with in-process evaluations,
+
+```python
+from openfeature import api
+from openfeature.contrib.provider.flagd import FlagdProvider
+from openfeature.contrib.provider.flagd.config import ResolverType
+
+api.set_provider(FlagdProvider(
+    resolver_type=ResolverType.IN_PROCESS,
+))
+```
+
+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).
+
+<!--
+#### Sync-metadata
+
+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).
+The value is updated with every (re)connection to the sync implementation.
+This can be used to enrich evaluations with such data.
+If the `in-process` mode is not used, and before the provider is ready, the `getSyncMetadata` returns an empty map.
+-->
+### File mode
+
+In-process resolvers can also work in an offline mode.
+To enable this mode, you should provide a valid flag configuration file with the option `offlineFlagSourcePath`.
+
+```python
+from openfeature import api
+from openfeature.contrib.provider.flagd import FlagdProvider
+from openfeature.contrib.provider.flagd.config import ResolverType
+
+api.set_provider(FlagdProvider(
+    resolver_type=ResolverType.FILE,
+    offline_flag_source_path="my-flag.json",
+))
+```
+
+Provider will attempt to detect file changes using polling.
+Polling happens at 5 second intervals and this is currently unconfigurable.
+This mode is useful for local development, tests and offline applications.
+
 ### Configuration options
 
 The default options can be defined in the FlagdProvider constructor.
 
-| Option name    | Type & Values | Default   |
-|----------------|---------------|-----------|
-| host           | str           | localhost |
-| port           | int           | 8013      |
-| schema         | str           | http      |
-| timeout        | int           | 2         |
+| Option name              | Environment variable name      | Type & Values              | Default                       | Compatible resolver |
+|--------------------------|--------------------------------|----------------------------|-------------------------------|---------------------|
+| resolver_type            | FLAGD_RESOLVER                 | enum - `rpc`, `in-process` | rpc                           |                     |
+| host                     | FLAGD_HOST                     | str                        | localhost                     | rpc & in-process    |
+| port                     | FLAGD_PORT                     | int                        | 8013 (rpc), 8015 (in-process) | rpc & in-process    |
+| tls                      | FLAGD_TLS                      | bool                       | false                         | rpc & in-process    |
+| cert_path                | FLAGD_SERVER_CERT_PATH         | String                     | null                          | rpc & in-process    |
+| deadline                 | FLAGD_DEADLINE_MS              | int                        | 500                           | rpc & in-process    |
+| stream_deadline_ms       | FLAGD_STREAM_DEADLINE_MS       | int                        | 600000                        | rpc & in-process    |
+| keep_alive_time          | FLAGD_KEEP_ALIVE_TIME_MS       | int                        | 0                             | rpc & in-process    |
+| selector                 | FLAGD_SOURCE_SELECTOR          | str                        | null                          | in-process          |
+| cache_type               | FLAGD_CACHE                    | enum - `lru`, `disabled`   | lru                           | rpc                 |
+| max_cache_size           | FLAGD_MAX_CACHE_SIZE           | int                        | 1000                          | rpc                 |
+| retry_backoff_ms         | FLAGD_RETRY_BACKOFF_MS         | int                        | 1000                          | rpc                 |
+| offline_flag_source_path | FLAGD_OFFLINE_FLAG_SOURCE_PATH | str                        | null                          | in-process          |
+
+<!-- not implemented
+| target_uri               | FLAGD_TARGET_URI               | alternative to host/port, supporting custom name resolution | string    | null                | rpc & in-process |
+| socket_path              | FLAGD_SOCKET_PATH              | alternative to host port, unix socket                       | String    | null                | rpc & in-process |
+| context_enricher         | -                              | sync-metadata to evaluation context mapping function        | function  | identity function   | in-process       |
+| offline_pollIntervalMs   | FLAGD_OFFLINE_POLL_MS          | poll interval for reading offlineFlagSourcePath             | int       | 5000                | in-process       |
+ -->
+
+> [!NOTE]
+> Some configurations are only applicable for RPC resolver.
+
+<!--
+### Unix socket support
+Unix socket communication with flagd is facilitated by usaging of the linux-native `epoll` library on `linux-x86_64`
+only (ARM support is pending the release of `netty-transport-native-epoll` v5).
+Unix sockets are not supported on other platforms or architectures.
+-->
+
+### Reconnection
+
+Reconnection is supported by the underlying gRPC connections.
+If the connection to flagd is lost, it will reconnect automatically.
+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 indefinitely.
+
+### Deadlines
+
+Deadlines are used to define how long the provider waits to complete initialization or flag evaluations.
+They behave differently based on the resolver type.
+
+#### Deadlines with Remote resolver (RPC)
+
+If the remote evaluation call is not completed within this deadline, the gRPC call is terminated with the error `DEADLINE_EXCEEDED`
+and the evaluation will default.
+
+### TLS
+
+TLS is available in situations where flagd is running on another host.
+
+
+You may optionally supply an X.509 certificate in PEM format. Otherwise, the default certificate store will be used.
+
+```python
+from openfeature import api
+from openfeature.contrib.provider.flagd import FlagdProvider
+
+api.set_provider(FlagdProvider(
+    tls=True,                        # use TLS
+    cert_path="etc/cert/ca.crt"      # PEM cert
+))
+```
 
 ## License
 

openfeature_provider_flagd-0.2.0/README.md

@@ -0,0 +1,148 @@
+# flagd Provider for OpenFeature
+
+This provider is designed to use flagd's [evaluation protocol](https://github.com/open-feature/schemas/blob/main/protobuf/schema/v1/schema.proto), or locally evaluate flags defined in a flagd [flag definition](https://github.com/open-feature/schemas/blob/main/json/flagd-definitions.json) via the OpenFeature Python SDK.
+
+## Installation
+
+```
+pip install openfeature-provider-flagd
+```
+
+## Configuration and Usage
+
+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).
+
+### Remote resolver (RPC)
+
+This is the default mode of operation of the provider.
+In this mode, `FlagdProvider` communicates with [flagd](https://github.com/open-feature/flagd) via the gRPC protocol.
+Flag evaluations take place remotely at the connected flagd instance.
+
+Instantiate a new FlagdProvider instance and configure the OpenFeature SDK to use it:
+
+```python
+from openfeature import api
+from openfeature.contrib.provider.flagd import FlagdProvider
+
+api.set_provider(FlagdProvider())
+```
+
+### In-process resolver
+
+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.
+
+Consider the following example to create a `FlagdProvider` with in-process evaluations,
+
+```python
+from openfeature import api
+from openfeature.contrib.provider.flagd import FlagdProvider
+from openfeature.contrib.provider.flagd.config import ResolverType
+
+api.set_provider(FlagdProvider(
+    resolver_type=ResolverType.IN_PROCESS,
+))
+```
+
+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).
+
+<!--
+#### Sync-metadata
+
+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).
+The value is updated with every (re)connection to the sync implementation.
+This can be used to enrich evaluations with such data.
+If the `in-process` mode is not used, and before the provider is ready, the `getSyncMetadata` returns an empty map.
+-->
+### File mode
+
+In-process resolvers can also work in an offline mode.
+To enable this mode, you should provide a valid flag configuration file with the option `offlineFlagSourcePath`.
+
+```python
+from openfeature import api
+from openfeature.contrib.provider.flagd import FlagdProvider
+from openfeature.contrib.provider.flagd.config import ResolverType
+
+api.set_provider(FlagdProvider(
+    resolver_type=ResolverType.FILE,
+    offline_flag_source_path="my-flag.json",
+))
+```
+
+Provider will attempt to detect file changes using polling.
+Polling happens at 5 second intervals and this is currently unconfigurable.
+This mode is useful for local development, tests and offline applications.
+
+### Configuration options
+
+The default options can be defined in the FlagdProvider constructor.
+
+| Option name              | Environment variable name      | Type & Values              | Default                       | Compatible resolver |
+|--------------------------|--------------------------------|----------------------------|-------------------------------|---------------------|
+| resolver_type            | FLAGD_RESOLVER                 | enum - `rpc`, `in-process` | rpc                           |                     |
+| host                     | FLAGD_HOST                     | str                        | localhost                     | rpc & in-process    |
+| port                     | FLAGD_PORT                     | int                        | 8013 (rpc), 8015 (in-process) | rpc & in-process    |
+| tls                      | FLAGD_TLS                      | bool                       | false                         | rpc & in-process    |
+| cert_path                | FLAGD_SERVER_CERT_PATH         | String                     | null                          | rpc & in-process    |
+| deadline                 | FLAGD_DEADLINE_MS              | int                        | 500                           | rpc & in-process    |
+| stream_deadline_ms       | FLAGD_STREAM_DEADLINE_MS       | int                        | 600000                        | rpc & in-process    |
+| keep_alive_time          | FLAGD_KEEP_ALIVE_TIME_MS       | int                        | 0                             | rpc & in-process    |
+| selector                 | FLAGD_SOURCE_SELECTOR          | str                        | null                          | in-process          |
+| cache_type               | FLAGD_CACHE                    | enum - `lru`, `disabled`   | lru                           | rpc                 |
+| max_cache_size           | FLAGD_MAX_CACHE_SIZE           | int                        | 1000                          | rpc                 |
+| retry_backoff_ms         | FLAGD_RETRY_BACKOFF_MS         | int                        | 1000                          | rpc                 |
+| offline_flag_source_path | FLAGD_OFFLINE_FLAG_SOURCE_PATH | str                        | null                          | in-process          |
+
+<!-- not implemented
+| target_uri               | FLAGD_TARGET_URI               | alternative to host/port, supporting custom name resolution | string    | null                | rpc & in-process |
+| socket_path              | FLAGD_SOCKET_PATH              | alternative to host port, unix socket                       | String    | null                | rpc & in-process |
+| context_enricher         | -                              | sync-metadata to evaluation context mapping function        | function  | identity function   | in-process       |
+| offline_pollIntervalMs   | FLAGD_OFFLINE_POLL_MS          | poll interval for reading offlineFlagSourcePath             | int       | 5000                | in-process       |
+ -->
+
+> [!NOTE]
+> Some configurations are only applicable for RPC resolver.
+
+<!--
+### Unix socket support
+Unix socket communication with flagd is facilitated by usaging of the linux-native `epoll` library on `linux-x86_64`
+only (ARM support is pending the release of `netty-transport-native-epoll` v5).
+Unix sockets are not supported on other platforms or architectures.
+-->
+
+### Reconnection
+
+Reconnection is supported by the underlying gRPC connections.
+If the connection to flagd is lost, it will reconnect automatically.
+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 indefinitely.
+
+### Deadlines
+
+Deadlines are used to define how long the provider waits to complete initialization or flag evaluations.
+They behave differently based on the resolver type.
+
+#### Deadlines with Remote resolver (RPC)
+
+If the remote evaluation call is not completed within this deadline, the gRPC call is terminated with the error `DEADLINE_EXCEEDED`
+and the evaluation will default.
+
+### TLS
+
+TLS is available in situations where flagd is running on another host.
+
+
+You may optionally supply an X.509 certificate in PEM format. Otherwise, the default certificate store will be used.
+
+```python
+from openfeature import api
+from openfeature.contrib.provider.flagd import FlagdProvider
+
+api.set_provider(FlagdProvider(
+    tls=True,                        # use TLS
+    cert_path="etc/cert/ca.crt"      # PEM cert
+))
+```
+
+## License
+
+Apache 2.0 - See [LICENSE](./LICENSE) for more information.

openfeature_provider_flagd-0.2.0/pyproject.toml

@@ -0,0 +1,136 @@
+# pyproject.toml
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openfeature-provider-flagd"
+version = "0.2.0"
+description = "OpenFeature provider for the flagd flag evaluation engine"
+readme = "README.md"
+authors = [{ name = "OpenFeature", email = "openfeature-core@groups.io" }]
+license = { file = "LICENSE" }
+classifiers = [
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+]
+keywords = []
+dependencies = [
+  "openfeature-sdk>=0.6.0",
+  "grpcio>=1.68.1",
+  "protobuf>=4.29.2",
+  "mmh3>=4.1.0",
+  "panzi-json-logic>=1.0.1",
+  "semver>=3,<4",
+  "pyyaml>=6.0.1",
+  "cachebox"
+]
+requires-python = ">=3.9"
+
+[project.urls]
+Homepage = "https://github.com/open-feature/python-sdk-contrib"
+
+[tool.hatch]
+
+[tool.hatch.envs.hatch-test]
+dependencies = [
+  "coverage[toml]>=6.5",
+  "pytest",
+  "pytest-bdd",
+  "testcontainers",
+  "asserts",
+  "grpcio-health-checking==1.70.0",
+]
+pre-install-commands = [
+  "hatch build",
+]
+
+[tool.hatch.envs.hatch-test.scripts]
+run = "pytest {args:tests}"
+run-cov = "coverage run -m pytest {args:tests}"
+cov-combine = "coverage combine"
+cov-report = [
+  "coverage xml",
+  "coverage html",
+  "coverage report",
+]
+cov = [
+  "test-cov",
+  "cov-report",
+]
+
+
+[tool.hatch.envs.mypy]
+dependencies = [
+  "mypy[faster-cache]>=1.13.0",
+  "types-protobuf",
+  "types-pyyaml",
+]
+pre-install-commands = [
+  "hatch build",
+]
+
+[tool.hatch.envs.mypy.scripts]
+run = "mypy"
+
+[tool.hatch.build.hooks.protobuf]
+generate_pyi = false
+dependencies = [
+    "hatch-protobuf",
+    "mypy-protobuf~=3.0",
+]
+proto_paths = [
+  ".",
+]
+output_path = "src/"
+
+[[tool.hatch.build.hooks.protobuf.generators]]
+name = "mypy"
+outputs = ["{proto_path}/{proto_name}_pb2.pyi"]
+
+[[tool.hatch.build.hooks.protobuf.generators]]
+name = "mypy_grpc"
+outputs = ["{proto_path}/{proto_name}_pb2_grpc.pyi"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+  ".gitignore",
+  "/openfeature",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openfeature"]
+
+[tool.coverage.run]
+omit = [
+  # exclude generated files
+  "src/openfeature/schemas/*",
+  "tests/**",
+]
+
+[tool.mypy]
+mypy_path = "src"
+files = "src"
+
+python_version = "3.9" # should be identical to the minimum supported version
+namespace_packages = true
+explicit_package_bases = true
+local_partial_types = true
+pretty = true
+
+strict = true
+disallow_any_generics = false
+
+[[tool.mypy.overrides]]
+module = [
+    "grpc.*",
+    "json_logic.*",
+]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = [
+    "openfeature.schemas.*"
+]
+warn_unused_ignores = false

openfeature_provider_flagd-0.2.0/pytest.ini

@@ -0,0 +1,22 @@
+[pytest]
+markers =
+    rpc: tests for rpc mode.
+    in-process: tests for in-process mode.
+    file: tests for file mode.
+    unavailable: tests for unavailable providers.
+    customCert: Supports custom certs.
+    unixsocket: Supports unixsockets.
+    targetURI: Supports targetURI.
+    grace: Supports grace attempts.
+    targeting: Supports targeting.
+    fractional: Supports fractional.
+    string: Supports string.
+    semver: Supports semver.
+    reconnect: Supports reconnect.
+    events: Supports events.
+    sync: Supports sync.
+    caching: Supports caching.
+    offline: Supports offline.
+    os.linux: linux mark.
+    stream: Supports streams.
+bdd_features_base_dir = tests/features