feat(go): Materialization fallback

Author: fabriziodemaria

openfeature-provider/go/README.md

@@ -82,6 +82,7 @@ The `ProviderConfig` struct contains all configuration options for the provider:
 #### Optional Fields
 
 - `Logger` (*slog.Logger): Custom logger for provider operations. If not provided, a default text logger is created. See [Logging](#logging) for details.
+- `StickyResolveStrategy` (StickyResolveStrategy): Strategy for handling sticky resolve scenarios. Defaults to `RemoteResolverFallback`. See [Sticky Resolve](#sticky-resolve) for details.
 - `ConnFactory` (func): Custom gRPC connection factory for advanced use cases (e.g., custom interceptors, TLS configuration)
 
 #### Advanced: Testing with Custom State Provider
@@ -102,6 +103,118 @@ provider, err := confidence.NewProviderWithStateProvider(ctx,
 
 **Important**: This configuration disables automatic state fetching and exposure logging. For production deployments, always use `NewProvider()` with `ProviderConfig`.
 
+## Sticky Resolve
+
+Sticky Resolve ensures users receive the same variant throughout an experiment, even if their targeting attributes change or you pause new assignments.
+
+**Two main use cases:**
+1. **Consistent experience** - User moves countries but keeps the same variant
+2. **Pause intake** - Stop new assignments while maintaining existing ones
+
+### Default: Server-Side Storage (RemoteResolverFallback)
+
+By default, the provider uses `RemoteResolverFallback` which automatically handles sticky assignments via network calls to Confidence when needed.
+
+**Flow:**
+1. Local WASM resolver attempts to resolve
+2. If sticky data needed → network call to Confidence
+3. Confidence checks its sticky repository, returns variant
+4. Assignment stored server-side with 90-day TTL (auto-renewed on access)
+
+**Server-side configuration (in Confidence UI):**
+- Optionally skip targeting criteria for sticky assignments
+- Pause/resume new entity intake
+- Automatic TTL management
+
+### Custom: Local Storage (MaterializationRepository)
+
+Implement `MaterializationRepository` to store assignments locally and eliminate network calls:
+
+```go
+type MaterializationRepository interface {
+    StickyResolveStrategy
+
+    // LoadMaterializedAssignmentsForUnit loads assignments for a unit.
+    // Returns a map of materialization name to MaterializationInfo.
+    LoadMaterializedAssignmentsForUnit(ctx context.Context, unit, materialization string) (map[string]*MaterializationInfo, error)
+
+    // StoreAssignment stores materialization assignments for a unit.
+    StoreAssignment(ctx context.Context, unit string, assignments map[string]*MaterializationInfo) error
+}
+
+type MaterializationInfo struct {
+    // UnitInMaterialization indicates if the unit exists in the materialization
+    UnitInMaterialization bool
+    // RuleToVariant maps rule IDs to their assigned variant names
+    RuleToVariant map[string]string
+}
+```
+
+### Example: In-Memory Repository
+
+```go
+type InMemoryMaterializationRepository struct {
+    mu       sync.RWMutex
+    storage  map[string]map[string]*confidence.MaterializationInfo // unit -> materialization -> info
+}
+
+func (r *InMemoryMaterializationRepository) LoadMaterializedAssignmentsForUnit(
+    ctx context.Context, unit, materialization string,
+) (map[string]*confidence.MaterializationInfo, error) {
+    r.mu.RLock()
+    defer r.mu.RUnlock()
+
+    if unitData, ok := r.storage[unit]; ok {
+        result := make(map[string]*confidence.MaterializationInfo)
+        for k, v := range unitData {
+            result[k] = v
+        }
+        return result, nil
+    }
+    return make(map[string]*confidence.MaterializationInfo), nil
+}
+
+func (r *InMemoryMaterializationRepository) StoreAssignment(
+    ctx context.Context, unit string, assignments map[string]*confidence.MaterializationInfo,
+) error {
+    r.mu.Lock()
+    defer r.mu.Unlock()
+
+    if r.storage == nil {
+        r.storage = make(map[string]map[string]*confidence.MaterializationInfo)
+    }
+    if r.storage[unit] == nil {
+        r.storage[unit] = make(map[string]*confidence.MaterializationInfo)
+    }
+
+    for k, v := range assignments {
+        r.storage[unit][k] = v
+    }
+    return nil
+}
+
+func (r *InMemoryMaterializationRepository) Close() {}
+```
+
+**Usage:**
+
+```go
+provider, err := confidence.NewProvider(ctx, confidence.ProviderConfig{
+    APIClientID:           "your-api-client-id",
+    APIClientSecret:       "your-api-client-secret",
+    ClientSecret:          "your-client-secret",
+    StickyResolveStrategy: &InMemoryMaterializationRepository{},
+})
+```
+
+### Choosing a Strategy
+
+| Strategy | Best For | Trade-offs |
+|----------|----------|------------|
+| **RemoteResolverFallback** (default) | Most apps | Simple, managed by Confidence. Network calls when needed. |
+| **MaterializationRepository** (in-memory) | Single-instance apps, testing | Fast, no network. Lost on restart. |
+| **MaterializationRepository** (Redis/DB) | Distributed/Multi instance apps | No network calls. Requires storage infra. |
+
 ## Credentials
 
 Get your client secret from your [Confidence dashboard](https://confidence.spotify.com/):

openfeature-provider/go/confidence/integration_test.go

@@ -191,13 +191,13 @@ func createProviderWithTestState(
 	runtime := wazero.NewRuntimeWithConfig(ctx, runtimeConfig)
 
 	// Create SwapWasmResolverApi without initial state (lazy initialization)
-	resolverAPI, err := NewSwapWasmResolverApi(ctx, runtime, defaultWasmBytes, logger, slog.New(slog.NewTextHandler(os.Stderr, nil)))
+	resolverAPI, err := NewSwapWasmResolverApi(ctx, runtime, defaultWasmBytes, logger, slog.New(slog.NewTextHandler(os.Stderr, nil)), nil)
 	if err != nil {
 		return nil, err
 	}
 
 	// Create provider with the client secret from test state
 	// The test state includes client secret: mkjJruAATQWjeY7foFIWfVAcBWnci2YF
-	provider := NewLocalResolverProvider(resolverAPI, stateProvider, logger, "mkjJruAATQWjeY7foFIWfVAcBWnci2YF", slog.New(slog.NewTextHandler(os.Stderr, nil)))
+	provider := NewLocalResolverProvider(resolverAPI, stateProvider, logger, "mkjJruAATQWjeY7foFIWfVAcBWnci2YF", slog.New(slog.NewTextHandler(os.Stderr, nil)), nil)
 	return provider, nil
 }

openfeature-provider/go/confidence/local_resolver_provider.go

@@ -21,15 +21,16 @@ const defaultPollIntervalSeconds = 10
 // LocalResolverProvider implements the OpenFeature FeatureProvider interface
 // for local flag resolution using the Confidence WASM resolver
 type LocalResolverProvider struct {
-	resolverAPI   WasmResolverApi
-	stateProvider StateProvider
-	flagLogger    FlagLogger
-	clientSecret  string
-	logger        *slog.Logger
-	cancelFunc    context.CancelFunc
-	wg            sync.WaitGroup
-	mu            sync.Mutex
-	pollInterval  time.Duration
+	resolverAPI           WasmResolverApi
+	stateProvider         StateProvider
+	flagLogger            FlagLogger
+	clientSecret          string
+	logger                *slog.Logger
+	cancelFunc            context.CancelFunc
+	wg                    sync.WaitGroup
+	mu                    sync.Mutex
+	pollInterval          time.Duration
+	stickyResolveStrategy StickyResolveStrategy
 }
 
 // Compile-time interface conformance checks
@@ -45,6 +46,7 @@ func NewLocalResolverProvider(
 	flagLogger FlagLogger,
 	clientSecret string,
 	logger *slog.Logger,
+	stickyResolveStrategy StickyResolveStrategy,
 ) *LocalResolverProvider {
 	// Create a default logger if none provided
 	if logger == nil {
@@ -54,12 +56,13 @@ func NewLocalResolverProvider(
 	}
 
 	return &LocalResolverProvider{
-		resolverAPI:   resolverAPI,
-		stateProvider: stateProvider,
-		flagLogger:    flagLogger,
-		clientSecret:  clientSecret,
-		logger:        logger,
-		pollInterval:  getPollIntervalSeconds(),
+		resolverAPI:           resolverAPI,
+		stateProvider:         stateProvider,
+		flagLogger:            flagLogger,
+		clientSecret:          clientSecret,
+		logger:                logger,
+		pollInterval:          getPollIntervalSeconds(),
+		stickyResolveStrategy: stickyResolveStrategy,
 	}
 }
 
@@ -261,16 +264,23 @@ func (p *LocalResolverProvider) ObjectEvaluation(
 		},
 	}
 
+	// Determine if we should fail fast on sticky (use fallback) or not
+	// ResolverFallback uses fail fast, MaterializationRepository retries with loaded data
+	failFastOnSticky := false
+	if _, ok := p.stickyResolveStrategy.(ResolverFallback); ok {
+		failFastOnSticky = true
+	}
+
 	// Create ResolveWithSticky request
 	stickyRequest := &resolver.ResolveWithStickyRequest{
 		ResolveRequest:          request,
 		MaterializationsPerUnit: make(map[string]*resolver.MaterializationMap),
-		FailFastOnSticky:        true,
+		FailFastOnSticky:        failFastOnSticky,
 		NotProcessSticky:        false,
 	}
 
 	// Resolve flags with sticky support
-	stickyResponse, err := p.resolverAPI.ResolveWithSticky(stickyRequest)
+	response, err := p.resolverAPI.ResolveWithSticky(ctx, stickyRequest)
 	if err != nil {
 		p.logger.Error("Failed to resolve flag", "flag", flagPath, "error", err)
 		return openfeature.InterfaceResolutionDetail{
@@ -282,31 +292,6 @@ func (p *LocalResolverProvider) ObjectEvaluation(
 		}
 	}
 
-	// Extract the actual resolve response from the sticky response
-	var response *resolver.ResolveFlagsResponse
-	switch result := stickyResponse.ResolveResult.(type) {
-	case *resolver.ResolveWithStickyResponse_Success_:
-		response = result.Success.Response
-	case *resolver.ResolveWithStickyResponse_MissingMaterializations_:
-		p.logger.Error("Missing materializations for flag", "flag", flagPath)
-		return openfeature.InterfaceResolutionDetail{
-			Value: defaultValue,
-			ProviderResolutionDetail: openfeature.ProviderResolutionDetail{
-				Reason:          openfeature.ErrorReason,
-				ResolutionError: openfeature.NewGeneralResolutionError("missing materializations"),
-			},
-		}
-	default:
-		p.logger.Error("Unexpected resolve result type for flag", "flag", flagPath)
-		return openfeature.InterfaceResolutionDetail{
-			Value: defaultValue,
-			ProviderResolutionDetail: openfeature.ProviderResolutionDetail{
-				Reason:          openfeature.ErrorReason,
-				ResolutionError: openfeature.NewGeneralResolutionError("unexpected resolve result"),
-			},
-		}
-	}
-
 	// Check if flag was found
 	if len(response.ResolvedFlags) == 0 {
 		p.logger.Info("No active flag was found", "flag", flagPath)
@@ -450,6 +435,14 @@ func (p *LocalResolverProvider) Shutdown() {
 		}
 	}
 
+	// Close sticky resolve strategy
+	if p.stickyResolveStrategy != nil {
+		p.stickyResolveStrategy.Close()
+		if p.logger != nil {
+			p.logger.Info("Closed sticky resolve strategy")
+		}
+	}
+
 	if p.logger != nil {
 		p.logger.Info("Provider shut down")
 	}

openfeature-provider/go/confidence/local_resolver_provider_resolve_test.go

@@ -34,7 +34,7 @@ func TestLocalResolverProvider_ReturnsDefaultOnError(t *testing.T) {
 	stateBytes, _ := proto.Marshal(state)
 
 	flagLogger := NewNoOpWasmFlagLogger()
-	swap, err := NewSwapWasmResolverApi(ctx, runtime, defaultWasmBytes, flagLogger, slog.New(slog.NewTextHandler(os.Stderr, nil)))
+	swap, err := NewSwapWasmResolverApi(ctx, runtime, defaultWasmBytes, flagLogger, slog.New(slog.NewTextHandler(os.Stderr, nil)), nil)
 	if err != nil {
 		t.Fatalf("Failed to create SwapWasmResolverApi: %v", err)
 	}
@@ -46,7 +46,7 @@ func TestLocalResolverProvider_ReturnsDefaultOnError(t *testing.T) {
 	}
 
 	// Use different client secret that won't match
-	openfeature.SetProviderAndWait(NewLocalResolverProvider(swap, nil, nil, "test-secret", slog.New(slog.NewTextHandler(os.Stderr, nil))))
+	openfeature.SetProviderAndWait(NewLocalResolverProvider(swap, nil, nil, "test-secret", slog.New(slog.NewTextHandler(os.Stderr, nil)), nil))
 	client := openfeature.NewClient("test-client")
 
 	evalCtx := openfeature.NewTargetlessEvaluationContext(map[string]interface{}{
@@ -85,7 +85,7 @@ func TestLocalResolverProvider_ReturnsCorrectValue(t *testing.T) {
 	testAcctID := loadTestAccountID(t)
 
 	flagLogger := NewNoOpWasmFlagLogger()
-	swap, err := NewSwapWasmResolverApi(ctx, runtime, defaultWasmBytes, flagLogger, slog.New(slog.NewTextHandler(os.Stderr, nil)))
+	swap, err := NewSwapWasmResolverApi(ctx, runtime, defaultWasmBytes, flagLogger, slog.New(slog.NewTextHandler(os.Stderr, nil)), nil)
 	if err != nil {
 		t.Fatalf("Failed to create SwapWasmResolverApi: %v", err)
 	}
@@ -97,7 +97,7 @@ func TestLocalResolverProvider_ReturnsCorrectValue(t *testing.T) {
 	}
 
 	// Use the correct client secret from test data
-	openfeature.SetProviderAndWait(NewLocalResolverProvider(swap, nil, nil, "mkjJruAATQWjeY7foFIWfVAcBWnci2YF", slog.New(slog.NewTextHandler(os.Stderr, nil))))
+	openfeature.SetProviderAndWait(NewLocalResolverProvider(swap, nil, nil, "mkjJruAATQWjeY7foFIWfVAcBWnci2YF", slog.New(slog.NewTextHandler(os.Stderr, nil)), nil))
 	client := openfeature.NewClient("test-client")
 
 	evalCtx := openfeature.NewTargetlessEvaluationContext(map[string]interface{}{
@@ -172,7 +172,7 @@ func TestLocalResolverProvider_MissingMaterializations(t *testing.T) {
 		testAcctID := loadTestAccountID(t)
 
 		flagLogger := NewNoOpWasmFlagLogger()
-		swap, err := NewSwapWasmResolverApi(ctx, runtime, defaultWasmBytes, flagLogger, slog.New(slog.NewTextHandler(os.Stderr, nil)))
+		swap, err := NewSwapWasmResolverApi(ctx, runtime, defaultWasmBytes, flagLogger, slog.New(slog.NewTextHandler(os.Stderr, nil)), nil)
 		if err != nil {
 			t.Fatalf("Failed to create SwapWasmResolverApi: %v", err)
 		}
@@ -183,7 +183,7 @@ func TestLocalResolverProvider_MissingMaterializations(t *testing.T) {
 			t.Fatalf("Failed to initialize swap with state: %v", err)
 		}
 
-		openfeature.SetProviderAndWait(NewLocalResolverProvider(swap, nil, nil, "mkjJruAATQWjeY7foFIWfVAcBWnci2YF", slog.New(slog.NewTextHandler(os.Stderr, nil))))
+		openfeature.SetProviderAndWait(NewLocalResolverProvider(swap, nil, nil, "mkjJruAATQWjeY7foFIWfVAcBWnci2YF", slog.New(slog.NewTextHandler(os.Stderr, nil)), nil))
 		client := openfeature.NewClient("test-client")
 
 		evalCtx := openfeature.NewTargetlessEvaluationContext(map[string]interface{}{
@@ -217,7 +217,7 @@ func TestLocalResolverProvider_MissingMaterializations(t *testing.T) {
 		accountId := "test-account"
 
 		flagLogger := NewNoOpWasmFlagLogger()
-		swap, err := NewSwapWasmResolverApi(ctx, runtime, defaultWasmBytes, flagLogger, slog.New(slog.NewTextHandler(os.Stderr, nil)))
+		swap, err := NewSwapWasmResolverApi(ctx, runtime, defaultWasmBytes, flagLogger, slog.New(slog.NewTextHandler(os.Stderr, nil)), nil)
 		if err != nil {
 			t.Fatalf("Failed to create SwapWasmResolverApi: %v", err)
 		}
@@ -228,7 +228,7 @@ func TestLocalResolverProvider_MissingMaterializations(t *testing.T) {
 			t.Fatalf("Failed to initialize swap with state: %v", err)
 		}
 
-		openfeature.SetProviderAndWait(NewLocalResolverProvider(swap, nil, nil, "test-secret", slog.New(slog.NewTextHandler(os.Stderr, nil))))
+		openfeature.SetProviderAndWait(NewLocalResolverProvider(swap, nil, nil, "test-secret", slog.New(slog.NewTextHandler(os.Stderr, nil)), nil))
 		client := openfeature.NewClient("test-client")
 
 		evalCtx := openfeature.NewTargetlessEvaluationContext(map[string]interface{}{
@@ -239,8 +239,8 @@ func TestLocalResolverProvider_MissingMaterializations(t *testing.T) {
 		result, error := client.BooleanValueDetails(ctx, "sticky-test-flag.enabled", defaultValue, evalCtx)
 		if error == nil {
 			t.Error("Expected error when materializations missing, got nil")
-		} else if error.Error() != "error code: GENERAL: missing materializations" {
-			t.Errorf("Expected 'error code: GENERAL: missing materializations', got: %v", error.Error())
+		} else if error.Error() != "error code: GENERAL: resolve failed: missing materializations and no sticky resolve strategy configured" {
+			t.Errorf("Expected 'error code: GENERAL: resolve failed: missing materializations and no sticky resolve strategy configured', got: %v", error.Error())
 		}
 
 		if result.Value != defaultValue {