feat: hybrid assignment cache to dedupe logging by the async init methods for eppo clients (#74)

* Comment code that isn't ready

* Confirm functionality of hybrid assignment cache

* Add hybrid assignment cache to both async init methods

* Remove useNonExpiringInMemoryAssignmentCache

* Add hybrid cache test for variation change

* Change flag key to check for a new logAssignment call

* Md5 hash storage key suffix

* Move and edit comment

* v3.5.3

Author: sameerank

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eppo/react-native-sdk",
-  "version": "3.5.2",
+  "version": "3.5.3",
   "description": "Eppo React Native SDK",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",
@@ -53,7 +53,7 @@
   "dependencies": {
     "@eppo/js-client-sdk-common": "4.8.4",
     "@react-native-async-storage/async-storage": "^1.18.0",
-    "md5": "^2.3.0"
+    "spark-md5": "^3.0.2"
   },
   "devDependencies": {
     "@evilmartians/lefthook": "^1.2.2",
@@ -62,6 +62,7 @@
     "@types/jest": "^28.1.2",
     "@types/react": "~17.0.21",
     "@types/react-native": "0.70.0",
+    "@types/spark-md5": "^3.0.5",
     "del-cli": "^5.0.0",
     "eslint": "^8.4.1",
     "eslint-config-prettier": "^8.5.0",

src/__tests__/hybrid-assignment-cache.test.tsx

@@ -0,0 +1,90 @@
+import { AsyncStorageAssignmentCache } from '../cache/async-storage-assignment-cache';
+import HybridAssignmentCache from '../cache/hybrid-assignment-cache';
+import SimpleAssignmentCache from '../cache/simple-assignment-cache';
+
+describe('HybridStorageAssignmentCache', () => {
+  let asyncStorageCache: AsyncStorageAssignmentCache;
+  let simpleCache: SimpleAssignmentCache;
+  let hybridCache: HybridAssignmentCache;
+
+  beforeEach(() => {
+    asyncStorageCache = new AsyncStorageAssignmentCache('test');
+    simpleCache = new SimpleAssignmentCache();
+    hybridCache = new HybridAssignmentCache(simpleCache, asyncStorageCache);
+  });
+
+  it('has should return false if cache is empty', async () => {
+    const cacheKey = {
+      subjectKey: 'subject-1',
+      flagKey: 'flag-1',
+      allocationKey: 'allocation-1',
+      variationKey: 'control',
+    };
+    await hybridCache.init();
+    expect(hybridCache.has(cacheKey)).toBeFalsy();
+  });
+
+  it('has should return true if cache key is present', async () => {
+    const cacheKey = {
+      subjectKey: 'subject-1',
+      flagKey: 'flag-1',
+      allocationKey: 'allocation-1',
+      variationKey: 'control',
+    };
+    await hybridCache.init();
+    expect(hybridCache.has(cacheKey)).toBeFalsy();
+    expect(simpleCache.has(cacheKey)).toBeFalsy();
+    hybridCache.set(cacheKey);
+    expect(hybridCache.has(cacheKey)).toBeTruthy();
+    expect(simpleCache.has(cacheKey)).toBeTruthy();
+  });
+
+  it('should populate asyncStorageCache from simpleCache', async () => {
+    const key1 = {
+      subjectKey: 'subject-1',
+      flagKey: 'flag-1',
+      allocationKey: 'allocation-1',
+      variationKey: 'control',
+    };
+    const key2 = {
+      subjectKey: 'subject-2',
+      flagKey: 'flag-2',
+      allocationKey: 'allocation-2',
+      variationKey: 'control',
+    };
+    expect(simpleCache.has(key1)).toBeFalsy();
+    asyncStorageCache.set(key1);
+    asyncStorageCache.set(key2);
+    await hybridCache.init();
+    expect(simpleCache.has(key1)).toBeTruthy();
+    expect(simpleCache.has(key2)).toBeTruthy();
+    expect(simpleCache.has({ ...key1, allocationKey: 'foo' })).toBeFalsy();
+  });
+
+  it('should handle variation changes for same subject, flag, and allocation', async () => {
+    const baseKey = {
+      subjectKey: 'subject-1',
+      flagKey: 'flag-1',
+      allocationKey: 'allocation-1',
+    };
+
+    const originalAssignment = {
+      ...baseKey,
+      variationKey: 'control',
+    };
+
+    const newAssignment = {
+      ...baseKey,
+      variationKey: 'treatment',
+    };
+
+    await hybridCache.init();
+    hybridCache.set(originalAssignment);
+    expect(hybridCache.has(originalAssignment)).toBeTruthy();
+
+    hybridCache.set(newAssignment);
+
+    expect(hybridCache.has(originalAssignment)).toBeFalsy();
+    expect(hybridCache.has(newAssignment)).toBeTruthy();
+  });
+});

src/__tests__/index.test.tsx

@@ -397,6 +397,42 @@ describe('EppoPrecomputedReactNativeClient E2E test', () => {
       format: 'PRECOMPUTED',
     });
   });
+
+  it('deduplicates assignment logging', () => {
+    // Reset the mock logger and assignment cache before this test
+    const assignmentCacheMockLogger = td.object<IAssignmentLogger>();
+    globalClient.useNonExpiringInMemoryAssignmentCache();
+    globalClient.setAssignmentLogger(assignmentCacheMockLogger);
+
+    expect(
+      td.explain(assignmentCacheMockLogger.logAssignment).callCount
+    ).toEqual(0);
+    globalClient.getStringAssignment('string-flag', 'default');
+    expect(
+      td.explain(assignmentCacheMockLogger.logAssignment).callCount
+    ).toEqual(1);
+    globalClient.getStringAssignment('string-flag', 'default');
+    expect(
+      td.explain(assignmentCacheMockLogger.logAssignment).callCount
+    ).toEqual(1);
+    globalClient.getBooleanAssignment('boolean-flag', false);
+    expect(
+      td.explain(assignmentCacheMockLogger.logAssignment).callCount
+    ).toEqual(2);
+
+    expect(
+      td.explain(assignmentCacheMockLogger.logAssignment).calls[0]?.args[0]
+    ).toMatchObject({
+      featureFlag: 'string-flag',
+      subject: 'test-subject',
+    });
+    expect(
+      td.explain(assignmentCacheMockLogger.logAssignment).calls[1]?.args[0]
+    ).toMatchObject({
+      featureFlag: 'boolean-flag',
+      subject: 'test-subject',
+    });
+  });
 });
 
 describe('getPrecomputedInstance', () => {

src/cache/assignment-cache-factory.ts

@@ -0,0 +1,24 @@
+import type { AssignmentCache } from '@eppo/js-client-sdk-common';
+
+import SimpleAssignmentCache from './simple-assignment-cache';
+import HybridAssignmentCache from './hybrid-assignment-cache';
+import { AsyncStorageAssignmentCache } from './async-storage-assignment-cache';
+
+export function assignmentCacheFactory({
+  forceMemoryOnly = false,
+  storageKeySuffix,
+}: {
+  forceMemoryOnly?: boolean;
+  storageKeySuffix: string;
+}): AssignmentCache {
+  const simpleCache = new SimpleAssignmentCache();
+  if (forceMemoryOnly) {
+    return simpleCache;
+  }
+  const asyncStorageCache = new AsyncStorageAssignmentCache(storageKeySuffix);
+  const hybridAssignmentCache = new HybridAssignmentCache(
+    simpleCache,
+    asyncStorageCache
+  );
+  return hybridAssignmentCache;
+}

src/cache/async-storage-assignment-cache.ts

@@ -0,0 +1,28 @@
+import { AbstractAssignmentCache } from '@eppo/js-client-sdk-common';
+
+import type {
+  BulkReadAssignmentCache,
+  BulkWriteAssignmentCache,
+} from './hybrid-assignment-cache';
+import { AsyncStorageAssignmentShim } from './async-storage-assignment-shim';
+
+export class AsyncStorageAssignmentCache
+  extends AbstractAssignmentCache<AsyncStorageAssignmentShim>
+  implements BulkReadAssignmentCache, BulkWriteAssignmentCache
+{
+  constructor(storageKeySuffix: string) {
+    super(new AsyncStorageAssignmentShim(storageKeySuffix));
+  }
+
+  setEntries(entries: [string, string][]): void {
+    entries.forEach(([key, value]) => {
+      if (key && value) {
+        this.delegate.set(key, value);
+      }
+    });
+  }
+
+  getEntries(): Promise<[string, string][]> {
+    return Promise.resolve(Array.from(this.entries()));
+  }
+}

src/cache/async-storage-assignment-shim.ts

@@ -0,0 +1,81 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+export class AsyncStorageAssignmentShim implements Map<string, string> {
+  private readonly storageKey: string;
+  private cache: Map<string, string>;
+
+  public constructor(storageKeySuffix: string) {
+    const keySuffix = storageKeySuffix ? `-${storageKeySuffix}` : '';
+    this.storageKey = `eppo-assignment${keySuffix}`;
+    this.cache = new Map();
+    this.initCache();
+  }
+
+  private async initCache(): Promise<void> {
+    const stored = await AsyncStorage.getItem(this.storageKey);
+    this.cache = stored ? new Map(JSON.parse(stored)) : new Map();
+  }
+
+  private async persistCache(): Promise<void> {
+    await AsyncStorage.setItem(
+      this.storageKey,
+      JSON.stringify(Array.from(this.cache.entries()))
+    );
+  }
+
+  clear(): void {
+    this.cache.clear();
+    AsyncStorage.removeItem(this.storageKey).catch(console.error);
+  }
+
+  delete(key: string): boolean {
+    const result = this.cache.delete(key);
+    this.persistCache().catch(console.error);
+    return result;
+  }
+
+  forEach(
+    callbackfn: (value: string, key: string, map: Map<string, string>) => void,
+    thisArg?: any
+  ): void {
+    this.cache.forEach(callbackfn, thisArg);
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+
+  entries(): IterableIterator<[string, string]> {
+    return this.cache.entries();
+  }
+
+  keys(): IterableIterator<string> {
+    return this.cache.keys();
+  }
+
+  values(): IterableIterator<string> {
+    return this.cache.values();
+  }
+
+  [Symbol.iterator](): IterableIterator<[string, string]> {
+    return this.cache[Symbol.iterator]();
+  }
+
+  get [Symbol.toStringTag](): string {
+    return this.cache[Symbol.toStringTag];
+  }
+
+  has(key: string): boolean {
+    return this.cache.has(key);
+  }
+
+  get(key: string): string | undefined {
+    return this.cache.get(key);
+  }
+
+  set(key: string, value: string): this {
+    this.cache.set(key, value);
+    this.persistCache().catch(console.error);
+    return this;
+  }
+}

src/cache/hybrid-assignment-cache.ts

@@ -0,0 +1,43 @@
+import type {
+  AssignmentCache,
+  AssignmentCacheEntry,
+} from '@eppo/js-client-sdk-common';
+
+/** An {@link AssignmentCache} that can write (set) multiple entries at once (in bulk). */
+export type BulkWriteAssignmentCache = AssignmentCache & {
+  /** Sets all entries in the cache to the provided array of [key, value] pairs. */
+  setEntries(entries: [string, string][]): void;
+};
+
+/** An {@link AssignmentCache} that can read (get) all entries at once. */
+export type BulkReadAssignmentCache = AssignmentCache & {
+  /** Returns all entries in the cache as an array of [key, value] pairs. */
+  getEntries(): Promise<[string, string][]>;
+};
+
+/**
+ * An {@link AssignmentCache} implementation that, upon `init`, reads from a persistent and async {@link BulkReadAssignmentCache}
+ * and writes to a synchronous {@link BulkWriteAssignmentCache} for serving the cache.
+ * */
+export default class HybridAssignmentCache implements AssignmentCache {
+  constructor(
+    private readonly servingStore: BulkWriteAssignmentCache,
+    private readonly persistentStore: BulkReadAssignmentCache
+  ) {}
+
+  async init(): Promise<void> {
+    const entries = await this.persistentStore.getEntries();
+    if (entries) {
+      this.servingStore.setEntries(entries);
+    }
+  }
+
+  set(key: AssignmentCacheEntry): void {
+    this.servingStore.set(key);
+    this.persistentStore.set(key);
+  }
+
+  has(key: AssignmentCacheEntry): boolean {
+    return this.servingStore.has(key);
+  }
+}

src/cache/simple-assignment-cache.ts

@@ -0,0 +1,42 @@
+import {
+  AbstractAssignmentCache,
+  NonExpiringInMemoryAssignmentCache,
+  AssignmentCacheEntry,
+} from '@eppo/js-client-sdk-common';
+
+import type {
+  BulkReadAssignmentCache,
+  BulkWriteAssignmentCache,
+} from './hybrid-assignment-cache';
+
+/** An {@link BulkWriteAssignmentCache} assignment cache backed by an in-memory {@link Map} */
+export default class SimpleAssignmentCache
+  implements BulkWriteAssignmentCache, BulkReadAssignmentCache
+{
+  private readonly store: Map<string, string>;
+  private readonly cache: AbstractAssignmentCache<Map<string, string>>;
+
+  constructor() {
+    this.store = new Map<string, string>();
+    this.cache = new NonExpiringInMemoryAssignmentCache(this.store);
+  }
+
+  set(key: AssignmentCacheEntry): void {
+    this.cache.set(key);
+  }
+
+  has(key: AssignmentCacheEntry): boolean {
+    return this.cache.has(key);
+  }
+
+  setEntries(entries: [string, string][]): void {
+    const { store } = this;
+    // it's important to call store.set() directly here because we want to set the raw entries into the cache, bypassing
+    // the AbstractAssignmentCache logic, which takes an AssignmentCacheKey instead.
+    entries.forEach(([key, value]) => store.set(key, value));
+  }
+
+  getEntries(): Promise<[string, string][]> {
+    return Promise.resolve(Array.from(this.cache.entries()));
+  }
+}