feat: add LruBanditLogger (#65)

* feat: add LruBanditLogger

* docs: update readme for LruBanditLogger

* test: add flip-flop test for LruBanditLogger

Author: rasendubi

README.md

@@ -203,30 +203,32 @@ event store. This increases the cost of storage as well as warehouse costs durin
 
 To mitigate this, an in-memory assignment cache is optionally available with expiration based on the least recently accessed time.
 
-It can be configured with a maximum size to fit your desired memory allocation.
+The caching can be configured individually for assignment logs and bandit action logs using `LruAssignmentLogger` and `LruBanditLogger` respectively.
+Both loggers are configured with a maximum size to fit your desired memory allocation.
 
 ```go
 import (
-  "github.com/Eppo-exp/golang-sdk/v5/eppoclient"
+	"github.com/Eppo-exp/golang-sdk/v5/eppoclient"
 )
 
 var eppoClient *eppoclient.EppoClient
 
 func main() {
-  assignmentLogger := NewExampleAssignmentLogger()
+	assignmentLogger := NewExampleAssignmentLogger()
 
-  eppoClient, _ = eppoclient.InitClient(eppoclient.Config{
-    ApiKey:           "<your_sdk_key>",
-    // 10000 is the maximum number of assignments to cache
-    // Depending on the length of your flag and subject keys, taking a median
-    // length of 32 characters, each assignment cache entry uses approximately 112 bytes.
-    // Use this calculation to determine the maximum number of assignments to cache
-    // for the memory you wish to allocate.
-    AssignmentLogger: eppoclient.NewLruAssignmentLogger(assignmentLogger, 10000),
-  })
+	// 10000 is the maximum number of assignments to cache.
+	assignmentLogger = eppoclient.NewLruAssignmentLogger(assignmentLogger, 10000)
+	assignmentLogger = eppoclient.NewLruBanditLogger(assignmentLogger, 10000)
+
+	eppoClient, _ = eppoclient.InitClient(eppoclient.Config{
+		ApiKey:           "<your_sdk_key>",
+		AssignmentLogger: assignmentLogger,
+	})
 }
 ```
 
+Internally, both loggers are simple proxying wrappers around [`lru.TwoQueueCache`](https://pkg.go.dev/github.com/hashicorp/golang-lru/v2#TwoQueueCache). If you require more customized caching behavior, you can copy the implementation and modify it to suit your needs. (We’d love to hear about your use case if you do!)
+
 ## Philosophy
 
 Eppo's SDKs are built for simplicity, speed and reliability. Flag configurations are compressed and distributed over a global CDN (Fastly), typically reaching your servers in under 15ms. Server SDKs continue polling Eppo’s API at 10-second intervals. Configurations are then cached locally, ensuring that each assignment is made instantly. Evaluation logic within each SDK consists of a few lines of simple numeric and string comparisons. The typed functions listed above are all developers need to understand, abstracting away the complexity of the Eppo's underlying (and expanding) feature set.

eppoclient/initclient.go

@@ -4,7 +4,7 @@ package eppoclient
 
 import "net/http"
 
-var __version__ = "5.1.1"
+var __version__ = "5.2.0"
 
 // InitClient is required to start polling of experiments configurations and create
 // an instance of EppoClient, which could be used to get assignments information.

eppoclient/lrubanditlogger.go

@@ -0,0 +1,61 @@
+package eppoclient
+
+import (
+	"fmt"
+
+	lru "github.com/hashicorp/golang-lru/v2"
+)
+
+type LruBanditLogger struct {
+	cache *lru.TwoQueueCache[lruBanditKey, lruBanditValue]
+	inner IAssignmentLogger
+}
+
+type lruBanditKey struct {
+	flagKey    string
+	subjectKey string
+}
+type lruBanditValue struct {
+	banditKey string
+	actionKey string
+}
+
+func NewLruBanditLogger(logger IAssignmentLogger, cacheSize int) (IAssignmentLogger, error) {
+	cache, err := lru.New2Q[lruBanditKey, lruBanditValue](cacheSize)
+	if err != nil {
+		// err is only returned if `cacheSize` is invalid
+		// (e.g., <0) which should normally never happen.
+		return nil, fmt.Errorf("failed to create LRU cache: %w", err)
+	}
+	return &LruBanditLogger{
+		cache: cache,
+		inner: logger,
+	}, nil
+}
+
+func (logger *LruBanditLogger) LogAssignment(event AssignmentEvent) {
+	logger.inner.LogAssignment(event)
+}
+
+func (logger *LruBanditLogger) LogBanditAction(event BanditEvent) {
+	inner, ok := logger.inner.(BanditActionLogger)
+	if !ok {
+		return
+	}
+
+	key := lruBanditKey{
+		flagKey:    event.FlagKey,
+		subjectKey: event.Subject,
+	}
+	value := lruBanditValue{
+		banditKey: event.BanditKey,
+		actionKey: event.Action,
+	}
+	previousValue, recentlyLogged := logger.cache.Get(key)
+	if !recentlyLogged || previousValue != value {
+		inner.LogBanditAction(event)
+		// Adding to cache after `LogBanditAction` returned in
+		// case it panics.
+		logger.cache.Add(key, value)
+	}
+}

eppoclient/lrubanditlogger_test.go

@@ -0,0 +1,111 @@
+package eppoclient
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/mock"
+)
+
+func Test_LruBanditLogger_cacheBanditAction(t *testing.T) {
+	innerLogger := new(mockLogger)
+	innerLogger.On("LogAssignment", mock.Anything).Return()
+	innerLogger.On("LogBanditAction", mock.Anything).Return()
+
+	logger, err := NewLruBanditLogger(innerLogger, 1000)
+	assert.NoError(t, err)
+
+	event := BanditEvent{
+		FlagKey:                      "flag",
+		BanditKey:                    "bandit",
+		Subject:                      "subject",
+		Action:                       "action",
+		ActionProbability:            0.1,
+		OptimalityGap:                0.1,
+		ModelVersion:                 "model-version",
+		Timestamp:                    "timestamp",
+		SubjectNumericAttributes:     map[string]float64{},
+		SubjectCategoricalAttributes: map[string]string{},
+		ActionNumericAttributes:      map[string]float64{},
+		ActionCategoricalAttributes:  map[string]string{},
+		MetaData:                     map[string]string{},
+	}
+
+	banditLogger := logger.(BanditActionLogger)
+	banditLogger.LogBanditAction(event)
+	banditLogger.LogBanditAction(event)
+
+	innerLogger.AssertNumberOfCalls(t, "LogBanditAction", 1)
+}
+
+func Test_LruBanditLogger_flipFlopAction(t *testing.T) {
+	innerLogger := new(mockLogger)
+	innerLogger.On("LogAssignment", mock.Anything).Return()
+	innerLogger.On("LogBanditAction", mock.Anything).Return()
+
+	logger, err := NewLruBanditLogger(innerLogger, 1000)
+	assert.NoError(t, err)
+	banditLogger := logger.(BanditActionLogger)
+
+	event := BanditEvent{
+		FlagKey:                      "flag",
+		BanditKey:                    "bandit",
+		Subject:                      "subject",
+		Action:                       "action1",
+		ActionProbability:            0.1,
+		OptimalityGap:                0.1,
+		ModelVersion:                 "model-version",
+		Timestamp:                    "timestamp",
+		SubjectNumericAttributes:     map[string]float64{},
+		SubjectCategoricalAttributes: map[string]string{},
+		ActionNumericAttributes:      map[string]float64{},
+		ActionCategoricalAttributes:  map[string]string{},
+		MetaData:                     map[string]string{},
+	}
+
+	event.Action = "action1"
+	banditLogger.LogBanditAction(event)
+	banditLogger.LogBanditAction(event)
+
+	innerLogger.AssertNumberOfCalls(t, "LogBanditAction", 1)
+
+	event.Action = "action2"
+	banditLogger.LogBanditAction(event)
+
+	innerLogger.AssertNumberOfCalls(t, "LogBanditAction", 2)
+
+	event.Action = "action1"
+	banditLogger.LogBanditAction(event)
+
+	innerLogger.AssertNumberOfCalls(t, "LogBanditAction", 3)
+}
+
+func Test_LruBanditLogger_okIfInnerLoggerIsNotBandit(t *testing.T) {
+	innerLogger := new(mockNonBanditLogger)
+	innerLogger.On("LogAssignment", mock.Anything).Return()
+
+	logger, err := NewLruBanditLogger(innerLogger, 1000)
+	assert.NoError(t, err)
+
+	event := BanditEvent{
+		FlagKey:                      "flag",
+		BanditKey:                    "bandit",
+		Subject:                      "subject",
+		Action:                       "action",
+		ActionProbability:            0.1,
+		OptimalityGap:                0.1,
+		ModelVersion:                 "model-version",
+		Timestamp:                    "timestamp",
+		SubjectNumericAttributes:     map[string]float64{},
+		SubjectCategoricalAttributes: map[string]string{},
+		ActionNumericAttributes:      map[string]float64{},
+		ActionCategoricalAttributes:  map[string]string{},
+		MetaData:                     map[string]string{},
+	}
+
+	banditLogger := logger.(BanditActionLogger)
+	banditLogger.LogBanditAction(event)
+	banditLogger.LogBanditAction(event)
+
+	innerLogger.AssertNumberOfCalls(t, "LogBanditAction", 0)
+}

eppoclient/mocks_test.go

@@ -15,3 +15,13 @@ func (ml *mockLogger) LogAssignment(event AssignmentEvent) {
 func (ml *mockLogger) LogBanditAction(event BanditEvent) {
 	ml.MethodCalled("LogBanditAction", event)
 }
+
+// `mockNonBanditLogger` is missing `LogBanditAction` and therefore
+// does not implement `BanditActionLogger`.
+type mockNonBanditLogger struct {
+	mock.Mock
+}
+
+func (ml *mockNonBanditLogger) LogAssignment(event AssignmentEvent) {
+	ml.MethodCalled("LogAssignment", event)
+}