Context-aware instance manager (#1352)

* implement context aware instance manager selection with new TTL manager

* tidy

* remove line

* tidy

Author: wbrowne

backend/app/instance_provider.go

@@ -13,13 +13,13 @@ import (
 // InstanceFactoryFunc factory method for creating app instances.
 type InstanceFactoryFunc func(ctx context.Context, settings backend.AppInstanceSettings) (instancemgmt.Instance, error)
 
-// NewInstanceManager creates a new app instance manager,
+// NewInstanceManager creates a new app instance manager.
 //
 // This is a helper method for calling NewInstanceProvider and creating a new instancemgmt.InstanceProvider,
-// and providing that to instancemgmt.New.
+// and providing that to instancemgmt.NewInstanceManagerWrapper.
 func NewInstanceManager(fn InstanceFactoryFunc) instancemgmt.InstanceManager {
 	ip := NewInstanceProvider(fn)
-	return instancemgmt.New(ip)
+	return instancemgmt.NewInstanceManagerWrapper(ip)
 }
 
 // NewInstanceProvider create a new app instance provider,

backend/datasource/instance_provider.go

@@ -30,7 +30,7 @@ type InstanceFactoryFunc func(ctx context.Context, settings backend.DataSourceIn
 // and providing that to instancemgmt.New.
 func NewInstanceManager(fn InstanceFactoryFunc) instancemgmt.InstanceManager {
 	ip := NewInstanceProvider(fn)
-	return instancemgmt.New(ip)
+	return instancemgmt.NewInstanceManagerWrapper(ip)
 }
 
 // NewInstanceProvider create a new data source instance provider,

backend/instancemgmt/context_aware_manager.go

@@ -0,0 +1,53 @@
+package instancemgmt
+
+import (
+	"context"
+
+	"github.com/grafana/grafana-plugin-sdk-go/backend"
+	"github.com/grafana/grafana-plugin-sdk-go/experimental/featuretoggles"
+)
+
+// NewInstanceManagerWrapper creates a new instance manager that dynamically selects
+// between standard and TTL instance managers based on feature toggles from the Grafana config.
+func NewInstanceManagerWrapper(provider InstanceProvider) InstanceManager {
+	return &instanceManagerWrapper{
+		provider:        provider,
+		standardManager: New(provider),
+		ttlManager:      NewTTLInstanceManager(provider),
+	}
+}
+
+// instanceManagerWrapper is a wrapper that dynamically selects the appropriate
+// instance manager implementation based on feature toggles in the context.
+type instanceManagerWrapper struct {
+	provider        InstanceProvider
+	standardManager InstanceManager
+	ttlManager      InstanceManager
+}
+
+// selectManager returns the appropriate instance manager based on the feature toggle
+// from the Grafana config in the plugin context.
+func (c *instanceManagerWrapper) selectManager(_ context.Context, pluginContext backend.PluginContext) InstanceManager {
+	// Check if TTL instance manager feature toggle is enabled
+	if pluginContext.GrafanaConfig != nil {
+		featureToggles := pluginContext.GrafanaConfig.FeatureToggles()
+		if featureToggles.IsEnabled(featuretoggles.TTLInstanceManager) {
+			return c.ttlManager
+		}
+	}
+
+	// Default to standard instance manager
+	return c.standardManager
+}
+
+// Get returns an Instance using the appropriate manager based on feature toggles.
+func (c *instanceManagerWrapper) Get(ctx context.Context, pluginContext backend.PluginContext) (Instance, error) {
+	manager := c.selectManager(ctx, pluginContext)
+	return manager.Get(ctx, pluginContext)
+}
+
+// Do provides an Instance as argument to fn using the appropriate manager based on feature toggles.
+func (c *instanceManagerWrapper) Do(ctx context.Context, pluginContext backend.PluginContext, fn InstanceCallbackFunc) error {
+	manager := c.selectManager(ctx, pluginContext)
+	return manager.Do(ctx, pluginContext, fn)
+}

backend/instancemgmt/context_aware_manager_test.go

@@ -0,0 +1,115 @@
+package instancemgmt
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/grafana/grafana-plugin-sdk-go/backend"
+	"github.com/grafana/grafana-plugin-sdk-go/experimental/featuretoggles"
+)
+
+func TestInstanceManagerWrapper(t *testing.T) {
+	ctx := context.Background()
+	tip := &testInstanceProvider{}
+	im := NewInstanceManagerWrapper(tip)
+
+	t.Run("Should use standard manager when feature toggle is disabled", func(t *testing.T) {
+		pCtx := backend.PluginContext{
+			OrgID: 1,
+			AppInstanceSettings: &backend.AppInstanceSettings{
+				Updated: time.Now(),
+			},
+			GrafanaConfig: backend.NewGrafanaCfg(map[string]string{
+				featuretoggles.EnabledFeatures: "",
+			}),
+		}
+
+		manager := im.(*instanceManagerWrapper).selectManager(ctx, pCtx)
+		require.IsType(t, &instanceManager{}, manager)
+	})
+
+	t.Run("Should use TTL manager when feature toggle is enabled", func(t *testing.T) {
+		pCtx := backend.PluginContext{
+			OrgID: 1,
+			AppInstanceSettings: &backend.AppInstanceSettings{
+				Updated: time.Now(),
+			},
+			GrafanaConfig: backend.NewGrafanaCfg(map[string]string{
+				featuretoggles.EnabledFeatures: featuretoggles.TTLInstanceManager,
+			}),
+		}
+
+		manager := im.(*instanceManagerWrapper).selectManager(ctx, pCtx)
+		require.IsType(t, &instanceManagerWithTTL{}, manager)
+	})
+
+	t.Run("Should use standard manager when GrafanaConfig is nil", func(t *testing.T) {
+		pCtx := backend.PluginContext{
+			OrgID: 1,
+			AppInstanceSettings: &backend.AppInstanceSettings{
+				Updated: time.Now(),
+			},
+			GrafanaConfig: nil,
+		}
+
+		manager := im.(*instanceManagerWrapper).selectManager(ctx, pCtx)
+		require.IsType(t, &instanceManager{}, manager)
+	})
+
+	t.Run("Should use TTL manager when feature toggle is enabled with other flags", func(t *testing.T) {
+		pCtx := backend.PluginContext{
+			OrgID: 1,
+			AppInstanceSettings: &backend.AppInstanceSettings{
+				Updated: time.Now(),
+			},
+			GrafanaConfig: backend.NewGrafanaCfg(map[string]string{
+				featuretoggles.EnabledFeatures: "someOtherFlag," + featuretoggles.TTLInstanceManager + ",anotherFlag",
+			}),
+		}
+
+		manager := im.(*instanceManagerWrapper).selectManager(ctx, pCtx)
+		require.IsType(t, &instanceManagerWithTTL{}, manager)
+	})
+
+	t.Run("Should delegate Get calls correctly", func(t *testing.T) {
+		// Test with TTL manager enabled
+		pCtx := backend.PluginContext{
+			OrgID: 1,
+			AppInstanceSettings: &backend.AppInstanceSettings{
+				Updated: time.Now(),
+			},
+			GrafanaConfig: backend.NewGrafanaCfg(map[string]string{
+				featuretoggles.EnabledFeatures: featuretoggles.TTLInstanceManager,
+			}),
+		}
+
+		instance, err := im.Get(ctx, pCtx)
+		require.NoError(t, err)
+		require.NotNil(t, instance)
+		require.Equal(t, pCtx.OrgID, instance.(*testInstance).orgID)
+	})
+
+	t.Run("Should delegate Do calls correctly", func(t *testing.T) {
+		// Test with standard manager (no feature toggle)
+		pCtx := backend.PluginContext{
+			OrgID: 2,
+			AppInstanceSettings: &backend.AppInstanceSettings{
+				Updated: time.Now(),
+			},
+			GrafanaConfig: backend.NewGrafanaCfg(map[string]string{
+				featuretoggles.EnabledFeatures: "",
+			}),
+		}
+
+		var receivedInstance *testInstance
+		err := im.Do(ctx, pCtx, func(instance Instance) {
+			receivedInstance = instance.(*testInstance)
+		})
+		require.NoError(t, err)
+		require.NotNil(t, receivedInstance)
+		require.Equal(t, pCtx.OrgID, receivedInstance.orgID)
+	})
+}

backend/instancemgmt/doc.go

@@ -1,2 +1,23 @@
 // Package instancemgmt provides utilities for managing plugin instances.
+//
+// This package offers several instance manager implementations:
+//
+//  1. Standard Instance Manager (New): Uses sync.Map for caching instances
+//     and disposes them when they need updates.
+//
+//  2. TTL Instance Manager (NewTTLInstanceManager): Uses TTL-based caching
+//     that automatically evicts instances after a configurable time period.
+//
+//  3. Instance Manager Wrapper (NewInstanceManagerWrapper):
+//     Dynamically selects between standard and TTL managers based on
+//     feature toggles from the Grafana config in the context.
+//
+// The context-aware manager checks the "ttlPluginInstanceManager" feature toggle
+// from the Grafana configuration and automatically uses the appropriate
+// underlying implementation. This allows runtime switching without requiring
+// plugin restarts or static configuration.
+// Note: Both the standard and TTL instance managers maintain separate caches.
+// If the feature toggle for TTL instance manager is changed at runtime,
+// instances are not migrated between managers. This can result in duplicate
+// instances for the same plugin context until the old ones are disposed or evicted.
 package instancemgmt

backend/instancemgmt/instance_manager.go

@@ -18,9 +18,10 @@ var (
 		Name:      "active_instances",
 		Help:      "The number of active plugin instances",
 	})
-	disposeTTL = 5 * time.Second
 )
 
+const defaultDisposeTTL = 5 * time.Second // Time to wait before disposing an instance
+
 // Instance is a marker interface for an instance.
 type Instance interface{}
 
@@ -73,21 +74,31 @@ type InstanceProvider interface {
 
 // New create a new instance manager.
 func New(provider InstanceProvider) InstanceManager {
+	return newInstanceManager(provider, defaultDisposeTTL)
+}
+
+func newInstanceManager(provider InstanceProvider, disposeTTL time.Duration) *instanceManager {
 	if provider == nil {
 		panic("provider cannot be nil")
 	}
 
+	if disposeTTL <= 0 {
+		disposeTTL = defaultDisposeTTL
+	}
+
 	return &instanceManager{
-		provider: provider,
-		cache:    sync.Map{},
-		locker:   newLocker(),
+		provider:   provider,
+		cache:      sync.Map{},
+		locker:     newLocker(),
+		disposeTTL: disposeTTL,
 	}
 }
 
 type instanceManager struct {
-	locker   *locker
-	provider InstanceProvider
-	cache    sync.Map
+	locker     *locker
+	provider   InstanceProvider
+	cache      sync.Map
+	disposeTTL time.Duration
 }
 
 func (im *instanceManager) Get(ctx context.Context, pluginContext backend.PluginContext) (Instance, error) {
@@ -121,7 +132,7 @@ func (im *instanceManager) Get(ctx context.Context, pluginContext backend.Plugin
 		}
 
 		if disposer, valid := ci.instance.(InstanceDisposer); valid {
-			time.AfterFunc(disposeTTL, func() {
+			time.AfterFunc(im.disposeTTL, func() {
 				disposer.Dispose()
 				activeInstances.Dec()
 			})

backend/instancemgmt/instance_manager_test.go

@@ -7,8 +7,9 @@ import (
 	"testing"
 	"time"
 
-	"github.com/grafana/grafana-plugin-sdk-go/backend"
 	"github.com/stretchr/testify/require"
+
+	"github.com/grafana/grafana-plugin-sdk-go/backend"
 )
 
 func TestInstanceManager(t *testing.T) {
@@ -21,7 +22,7 @@ func TestInstanceManager(t *testing.T) {
 	}
 
 	tip := &testInstanceProvider{}
-	im := New(tip)
+	im := newInstanceManager(tip, time.Millisecond)
 
 	t.Run("When getting instance should create a new instance", func(t *testing.T) {
 		instance, err := im.Get(ctx, pCtx)
@@ -43,11 +44,6 @@ func TestInstanceManager(t *testing.T) {
 					Updated: time.Now(),
 				},
 			}
-			origDisposeTTL := disposeTTL
-			disposeTTL = time.Millisecond
-			t.Cleanup(func() {
-				disposeTTL = origDisposeTTL
-			})
 			newInstance, err := im.Get(ctx, pCtxUpdated)
 
 			t.Run("New instance should be created", func(t *testing.T) {
@@ -110,12 +106,6 @@ func TestInstanceManagerConcurrency(t *testing.T) {
 	})
 
 	t.Run("Check possible race condition issues when re-creating instance on settings update", func(t *testing.T) {
-		origDisposeTTL := disposeTTL
-		disposeTTL = time.Millisecond
-		t.Cleanup(func() {
-			disposeTTL = origDisposeTTL
-		})
-
 		ctx := context.Background()
 		initialPCtx := backend.PluginContext{
 			OrgID: 1,
@@ -124,7 +114,7 @@ func TestInstanceManagerConcurrency(t *testing.T) {
 			},
 		}
 		tip := &testInstanceProvider{}
-		im := New(tip)
+		im := newInstanceManager(tip, time.Millisecond)
 		// Creating initial instance with old contexts
 		instanceToDispose, _ := im.Get(ctx, initialPCtx)