feat(flagd)!: add file mode to flagd provider (open-feature#648)

Signed-off-by: Raphael Wigoutschnigg <[email protected]>

Author: raphael-wigoutschnigg-dt

providers/flagd/README.md

@@ -22,7 +22,8 @@ Flag evaluations take place remotely at the connected flagd instance.
 To use in this mode, set the provider to the `openfeature` global singleton as shown below (using default values which align with those of `flagd`)
 
 ```go
-openfeature.SetProvider(flagd.NewProvider())
+provider, err := flagd.NewProvider()
+openfeature.SetProvider(provider)
 ```  
 
 ### In-process resolver
@@ -33,30 +34,12 @@ Flag configurations for evaluation are obtained via gRPC protocol using [sync pr
 Consider following example to create a `FlagdProvider` with in-process evaluations,
 
 ```go
-provider := flagd.NewProvider(
-        flagd.WithInProcessResolver(),
-        flagd.WithHost("localhost"),
-        flagd.WithPort(8013))
+provider, err := flagd.NewProvider(flagd.WithInProcessResolver())
 openfeature.SetProvider(provider)
 ```
 
 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/flagd-definitions.json).
 
-#### Offline mode
-
-In-process resolvers can also work in an offline mode.
-To enable this mode, you should provide a [valid flag configuration](https://flagd.dev/reference/flag-definitions/) file with the option `WithOfflineFilePath`.
-
-```go
-provider := flagd.NewProvider(
-        flagd.WithInProcessResolver(),
-        flagd.WithOfflineFilePath(OFFLINE_FLAG_PATH))
-openfeature.SetProvider(provider)
-```
-
-The provider will attempt to detect file changes, but this is a best-effort attempt as file system events differ between operating systems.
-This mode is useful for local development, tests and offline applications.
-
 #### Custom sync provider
 
 In-process resolver can also be configured with a custom sync provider to change how the in-process resolver fetches flags.
@@ -65,28 +48,44 @@ The custom sync provider must implement the [sync.ISync interface](https://githu
 ```go
 var syncProvider sync.ISync = MyAwesomeSyncProvider{}
 
-provider := flagd.NewProvider(
+provider, err := flagd.NewProvider(
         flagd.WithInProcessResolver(),
-        flagd.WithCustomSyncProvider(syncProvider))
+        flagd.WithCustomSyncProvider(syncProvider),
+)
 openfeature.SetProvider(provider)
 ```
 
 ```go
 var syncProvider sync.ISync = MyAwesomeSyncProvider{}
 var syncProviderUri string = "myawesome://sync.uri"
 
-provider := flagd.NewProvider(
+provider, err := flagd.NewProvider(
         flagd.WithInProcessResolver(),
-        flagd.WithCustomSyncProviderAndUri(syncProvider, syncProviderUri))
+        flagd.WithCustomSyncProviderAndUri(syncProvider, syncProviderUri),
+)
 openfeature.SetProvider(provider)
 ```
 
 > [!IMPORTANT]
 > Note that the in-process resolver can only use a single flag source.
 > If multiple sources are configured then only one would be selected based on the following order of preference:
 >   1. Custom sync provider
->   2. Offline file
->   3. gRPC
+>   2. gRPC
+
+### File mode
+
+This mode obtains the flag configurations from a local file and performs flag evaluations locally.
+
+```go
+provider, err := flagd.NewProvider(
+        flagd.WithFileResolver(),
+        flagd.WithOfflineFilePath(OFFLINE_FLAG_PATH),
+)
+openfeature.SetProvider(provider)
+```
+
+The provider will attempt to detect file changes, but this is a best-effort attempt as file system events differ between operating systems.
+This mode is useful for local development, tests and offline applications.
 
 ## Configuration options
 
@@ -102,7 +101,7 @@ Configuration can be provided as constructor options or as environment variables
 | WithCertificatePath                                      | FLAGD_SERVER_CERT_PATH         | string                      | ""        | rpc & in-process    |
 | WithLRUCache<br/>WithBasicInMemoryCache<br/>WithoutCache | FLAGD_CACHE                    | string (lru, mem, disabled) | lru       | rpc                 |
 | WithEventStreamConnectionMaxAttempts                     | FLAGD_MAX_EVENT_STREAM_RETRIES | int                         | 5         | rpc                 |
-| WithOfflineFilePath                                      | FLAGD_OFFLINE_FLAG_SOURCE_PATH | string                      | ""        | in-process          |
+| WithOfflineFilePath                                      | FLAGD_OFFLINE_FLAG_SOURCE_PATH | string                      | ""        | file                |
 | WithProviderID                                           | FLAGD_SOURCE_PROVIDER_ID       | string                      | ""        | in-process          |
 | WithSelector                                             | FLAGD_SOURCE_SELECTOR          | string                      | ""        | in-process          | 
 
@@ -115,10 +114,11 @@ In the event that another configuration option is passed to the `flagd.NewProvid
 
 e.g. below the values set by `FromEnv()` overwrite the value set by `WithHost("localhost")`.
 ```go
-openfeature.SetProvider(flagd.NewProvider(
+provider, err := flagd.NewProvider(
         flagd.WithHost("localhost"),
         flagd.FromEnv(),
-    ))
+)
+openfeature.SetProvider(provider)
 ```
 
 ### Caching
@@ -138,10 +138,11 @@ and one custom resolver for `envoy` proxy resolution. For more details, please r
 [RFC](https://github.com/open-feature/flagd/blob/main/docs/reference/specifications/proposal/rfc-grpc-custom-name-resolver.md) document.
 
 ```go
-openfeature.SetProvider(flagd.NewProvider(
+provider, err := flagd.NewProvider(
         flagd.WithInProcessResolver(),
         flagd.WithTargetUri("envoy://localhost:9211/test.service"),
-    ))
+)
+openfeature.SetProvider(provider)
 ```
 
 ### gRPC DialOptions override
@@ -158,11 +159,12 @@ dialOptions := []grpc.DialOption{
         grpc.WithAuthority(...),
     }
 
-openfeature.SetProvider(flagd.NewProvider(
+provider, err := flagd.NewProvider(
         flagd.WithInProcessResolver(),
         flagd.WithHost("example.com/flagdSyncApi"), flagd.WithPort(443),
         flagd.WithGrpcDialOptionsOverride(dialOptions),
-    ))
+)
+openfeature.SetProvider(provider)
 ```
 
 ## Supported Events
@@ -199,7 +201,7 @@ for many of the popular logger packages.
 var l logr.Logger
 l = integratedlogr.New() // replace with your chosen integrator
 
-provider := flagd.NewProvider(flagd.WithLogger(l)) // set the provider's logger
+provider, err := flagd.NewProvider(flagd.WithLogger(l)) // set the provider's logger
 ```
 
 [logr](https://github.com/go-logr/logr) uses incremental verbosity levels (akin to named levels but in integer form).

providers/flagd/e2e/evaluation_test.go

@@ -25,7 +25,13 @@ func TestETestEvaluationFlagdInRPC(t *testing.T) {
 	testSuite := godog.TestSuite{
 		Name: name,
 		TestSuiteInitializer: integration.InitializeTestSuite(func() openfeature.FeatureProvider {
-			return flagd.NewProvider(flagd.WithPort(8013))
+			provider, err := flagd.NewProvider(flagd.WithPort(8013))
+
+			if err != nil {
+				t.Fatal("Creating provider failed:", err)
+			}
+
+			return provider
 		}),
 		ScenarioInitializer: integration.InitializeEvaluationScenario,
 		Options: &godog.Options{
@@ -54,7 +60,13 @@ func TestJsonEvaluatorFlagdInProcess(t *testing.T) {
 	testSuite := godog.TestSuite{
 		Name: name,
 		TestSuiteInitializer: integration.InitializeTestSuite(func() openfeature.FeatureProvider {
-			return flagd.NewProvider(flagd.WithInProcessResolver(), flagd.WithPort(9090))
+			provider, err := flagd.NewProvider(flagd.WithInProcessResolver(), flagd.WithPort(9090))
+
+			if err != nil {
+				t.Fatal("Creating provider failed:", err)
+			}
+
+			return provider
 		}),
 		ScenarioInitializer: integration.InitializeEvaluationScenario,
 		Options: &godog.Options{

providers/flagd/e2e/json_evalutor_test.go

@@ -25,7 +25,13 @@ func TestJsonEvaluatorInRPC(t *testing.T) {
 	testSuite := godog.TestSuite{
 		Name: name,
 		TestSuiteInitializer: integration.InitializeFlagdJsonTestSuite(func() openfeature.FeatureProvider {
-			return flagd.NewProvider(flagd.WithPort(8013))
+			provider, err := flagd.NewProvider(flagd.WithPort(8013))
+
+			if err != nil {
+				t.Fatal("Creating provider failed:", err)
+			}
+
+			return provider
 		}),
 		ScenarioInitializer: integration.InitializeFlagdJsonScenario,
 		Options: &godog.Options{
@@ -54,7 +60,13 @@ func TestJsonEvaluatorInProcess(t *testing.T) {
 	testSuite := godog.TestSuite{
 		Name: name,
 		TestSuiteInitializer: integration.InitializeFlagdJsonTestSuite(func() openfeature.FeatureProvider {
-			return flagd.NewProvider(flagd.WithInProcessResolver(), flagd.WithPort(9090))
+			provider, err := flagd.NewProvider(flagd.WithInProcessResolver(), flagd.WithPort(9090))
+
+			if err != nil {
+				t.Fatal("Creating provider failed:", err)
+			}
+
+			return provider
 		}),
 		ScenarioInitializer: integration.InitializeFlagdJsonScenario,
 		Options: &godog.Options{

providers/flagd/pkg/configuration.go

@@ -26,6 +26,7 @@ const (
 
 	rpc       ResolverType = "rpc"
 	inProcess ResolverType = "in-process"
+	file      ResolverType = "file"
 
 	flagdHostEnvironmentVariableName                  = "FLAGD_HOST"
 	flagdPortEnvironmentVariableName                  = "FLAGD_PORT"
@@ -155,6 +156,8 @@ func (cfg *providerConfiguration) updateFromEnvVar() {
 			cfg.Resolver = rpc
 		case inProcess:
 			cfg.Resolver = inProcess
+		case file:
+			cfg.Resolver = file
 		default:
 			cfg.log.Info("invalid resolver type: %s, falling back to default: %s", resolver, defaultResolver)
 			cfg.Resolver = defaultResolver

providers/flagd/pkg/provider.go

@@ -2,6 +2,7 @@ package flagd
 
 import (
 	"context"
+	"errors"
 	"fmt"
 
 	parallel "sync"
@@ -31,7 +32,7 @@ type Provider struct {
 	eventStream chan of.Event
 }
 
-func NewProvider(opts ...ProviderOption) *Provider {
+func NewProvider(opts ...ProviderOption) (*Provider, error) {
 	log := logr.New(logger.Logger{})
 
 	// initialize with default configurations
@@ -50,12 +51,12 @@ func NewProvider(opts ...ProviderOption) *Provider {
 		opt(provider)
 	}
 
-	if provider.providerConfiguration.Port == 0 {
-		if provider.providerConfiguration.Resolver == inProcess {
-			provider.providerConfiguration.Port = defaultInProcessPort
-		} else {
-			provider.providerConfiguration.Port = defaultRpcPort
-		}
+	configureProvider(provider)
+
+	err := validateProvider(provider)
+
+	if err != nil {
+		return nil, err
 	}
 
 	cacheService := cache.NewCacheService(
@@ -77,7 +78,7 @@ func NewProvider(opts ...ProviderOption) *Provider {
 			cacheService,
 			provider.logger,
 			provider.providerConfiguration.EventStreamConnectionMaxAttempts)
-	} else {
+	} else if provider.providerConfiguration.Resolver == inProcess {
 		service = process.NewInProcessService(process.Configuration{
 			Host:                    provider.providerConfiguration.Host,
 			Port:                    provider.providerConfiguration.Port,
@@ -90,11 +91,39 @@ func NewProvider(opts ...ProviderOption) *Provider {
 			CustomSyncProviderUri:   provider.providerConfiguration.CustomSyncProviderUri,
 			GrpcDialOptionsOverride: provider.providerConfiguration.GrpcDialOptionsOverride,
 		})
+	} else {
+		service = process.NewInProcessService(process.Configuration{
+			OfflineFlagSource: provider.providerConfiguration.OfflineFlagSourcePath,
+		})
 	}
 
 	provider.service = service
 
-	return provider
+	return provider, nil
+}
+
+func configureProvider(p *Provider) {
+	if len(p.providerConfiguration.OfflineFlagSourcePath) > 0 && p.providerConfiguration.Resolver == inProcess {
+		p.providerConfiguration.Resolver = file
+	}
+
+	if p.providerConfiguration.Port == 0 {
+		switch p.providerConfiguration.Resolver {
+		case rpc:
+			p.providerConfiguration.Port = defaultRpcPort
+		case inProcess:
+			p.providerConfiguration.Port = defaultInProcessPort
+		}
+	}
+}
+
+func validateProvider(p *Provider) error {
+	// We need a file path for file mode
+	if len(p.providerConfiguration.OfflineFlagSourcePath) == 0 && p.providerConfiguration.Resolver == file {
+		return errors.New("Resolver Type 'file' requires a OfflineFlagSourcePath")
+	}
+
+	return nil
 }
 
 func (p *Provider) Init(_ of.EvaluationContext) error {
@@ -315,14 +344,20 @@ func WithInProcessResolver() ProviderOption {
 	}
 }
 
-// WithOfflineFilePath file path to obtain flags to run provider in offline mode with in-process evaluations.
-// This is only useful with inProcess resolver type
+// WithOfflineFilePath file path to obtain flags used for provider in file mode.
 func WithOfflineFilePath(path string) ProviderOption {
 	return func(p *Provider) {
 		p.providerConfiguration.OfflineFlagSourcePath = path
 	}
 }
 
+// WithFileResolver sets flag resolver to File
+func WithFileResolver() ProviderOption {
+	return func(p *Provider) {
+		p.providerConfiguration.Resolver = file
+	}
+}
+
 // WithSelector sets the selector to be used for InProcess flag sync calls
 func WithSelector(selector string) ProviderOption {
 	return func(p *Provider) {