feat: ability to export precomputed assignments (#160)

* precomputed flags and tests
* add flag obfuscation
*ConfigurationWire
* salted hashing

Author: typotter

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eppo/js-client-sdk-common",
-  "version": "4.6.3",
+  "version": "4.7.0",
   "description": "Common library for Eppo JavaScript SDKs (web, react native, and node)",
   "main": "dist/index.js",
   "files": [

src/client/eppo-client.spec.ts

@@ -13,10 +13,13 @@ import {
   validateTestAssignments,
 } from '../../test/testHelpers';
 import { IAssignmentLogger } from '../assignment-logger';
+import { IConfigurationWire } from '../configuration';
 import { IConfigurationStore } from '../configuration-store/configuration-store';
 import { MemoryOnlyConfigurationStore } from '../configuration-store/memory.store';
 import { MAX_EVENT_QUEUE_SIZE, DEFAULT_POLL_INTERVAL_MS, POLL_JITTER_PCT } from '../constants';
+import { decodePrecomputedFlag } from '../decoding';
 import { Flag, ObfuscatedFlag, VariationType } from '../interfaces';
+import { setSaltOverrideForTests } from '../obfuscation';
 import { AttributeType } from '../types';
 
 import EppoClient, { FlagConfigurationRequestParameters, checkTypeMatch } from './eppo-client';
@@ -177,6 +180,114 @@ describe('EppoClient E2E test', () => {
     });
   });
 
+  describe('precomputed flags', () => {
+    beforeAll(() => {
+      storage.setEntries({
+        [flagKey]: mockFlag,
+        disabledFlag: { ...mockFlag, enabled: false },
+        anotherFlag: {
+          ...mockFlag,
+          allocations: [
+            {
+              key: 'allocation-b',
+              rules: [],
+              splits: [
+                {
+                  shards: [],
+                  variationKey: 'b',
+                },
+              ],
+              doLog: true,
+            },
+          ],
+        },
+      });
+    });
+
+    let client: EppoClient;
+    beforeEach(() => {
+      client = new EppoClient({ flagConfigurationStore: storage });
+    });
+
+    afterEach(() => {
+      setSaltOverrideForTests(null);
+    });
+
+    it('skips disabled flags', () => {
+      const encodedPrecomputedWire = client.getPrecomputedAssignments('subject', {});
+      const { precomputed } = JSON.parse(encodedPrecomputedWire) as IConfigurationWire;
+      if (!precomputed) {
+        fail('Precomputed data not in Configuration response');
+      }
+      const precomputedResponse = JSON.parse(precomputed.response);
+
+      expect(precomputedResponse).toBeTruthy();
+      const precomputedFlags = precomputedResponse?.flags ?? {};
+      expect(Object.keys(precomputedFlags)).toContain('anotherFlag');
+      expect(Object.keys(precomputedFlags)).toContain(flagKey);
+      expect(Object.keys(precomputedFlags)).not.toContain('disabledFlag');
+    });
+
+    it('evaluates and returns assignments', () => {
+      const encodedPrecomputedWire = client.getPrecomputedAssignments('subject', {});
+      const { precomputed } = JSON.parse(encodedPrecomputedWire) as IConfigurationWire;
+      if (!precomputed) {
+        fail('Precomputed data not in Configuration response');
+      }
+      const precomputedResponse = JSON.parse(precomputed.response);
+
+      expect(precomputedResponse).toBeTruthy();
+      const precomputedFlags = precomputedResponse?.flags ?? {};
+      const firstFlag = precomputedFlags[flagKey];
+      const secondFlag = precomputedFlags['anotherFlag'];
+      expect(firstFlag.variationValue).toEqual('variation-a');
+      expect(secondFlag.variationValue).toEqual('variation-b');
+    });
+
+    it('obfuscates assignments', () => {
+      // Use a known salt to produce deterministic hashes
+      setSaltOverrideForTests({
+        base64String: 'BzURTg==',
+        saltString: '0735114e',
+        bytes: new Uint8Array([7, 53, 17, 78]),
+      });
+
+      const encodedPrecomputedWire = client.getPrecomputedAssignments('subject', {}, true);
+      const { precomputed } = JSON.parse(encodedPrecomputedWire) as IConfigurationWire;
+      if (!precomputed) {
+        fail('Precomputed data not in Configuration response');
+      }
+      const precomputedResponse = JSON.parse(precomputed.response);
+
+      expect(precomputedResponse).toBeTruthy();
+      expect(precomputedResponse.salt).toEqual('BzURTg==');
+
+      const precomputedFlags = precomputedResponse?.flags ?? {};
+      expect(Object.keys(precomputedFlags)).toContain('ddc24ede545855b9bbae82cfec6a83a1'); // flagKey, md5 hashed
+      expect(Object.keys(precomputedFlags)).toContain('2b439e5a0104d62400dc44c34230f6f2'); // 'anotherFlag', md5 hashed
+
+      const decodedFirstFlag = decodePrecomputedFlag(
+        precomputedFlags['ddc24ede545855b9bbae82cfec6a83a1'],
+      );
+      expect(decodedFirstFlag.flagKey).toEqual('ddc24ede545855b9bbae82cfec6a83a1');
+      expect(decodedFirstFlag.variationType).toEqual(VariationType.STRING);
+      expect(decodedFirstFlag.variationKey).toEqual('a');
+      expect(decodedFirstFlag.variationValue).toEqual('variation-a');
+      expect(decodedFirstFlag.doLog).toEqual(true);
+      expect(decodedFirstFlag.extraLogging).toEqual({});
+
+      const decodedSecondFlag = decodePrecomputedFlag(
+        precomputedFlags['2b439e5a0104d62400dc44c34230f6f2'],
+      );
+      expect(decodedSecondFlag.flagKey).toEqual('2b439e5a0104d62400dc44c34230f6f2');
+      expect(decodedSecondFlag.variationType).toEqual(VariationType.STRING);
+      expect(decodedSecondFlag.variationKey).toEqual('b');
+      expect(decodedSecondFlag.variationValue).toEqual('variation-b');
+      expect(decodedSecondFlag.doLog).toEqual(true);
+      expect(decodedSecondFlag.extraLogging).toEqual({});
+    });
+  });
+
   describe('UFC Shared Test Cases', () => {
     const testCases = testCasesByFileName<IAssignmentTestCase>(ASSIGNMENT_TEST_DATA_DIR);
 

src/client/eppo-client.ts

@@ -9,6 +9,13 @@ import { AssignmentCache } from '../cache/abstract-assignment-cache';
 import { LRUInMemoryAssignmentCache } from '../cache/lru-in-memory-assignment-cache';
 import { NonExpiringInMemoryAssignmentCache } from '../cache/non-expiring-in-memory-cache-assignment';
 import { TLRUInMemoryAssignmentCache } from '../cache/tlru-in-memory-assignment-cache';
+import {
+  IConfigurationWire,
+  ConfigurationWireV1,
+  IPrecomputedConfiguration,
+  ObfuscatedPrecomputedConfiguration,
+  PrecomputedConfiguration,
+} from '../configuration';
 import ConfigurationRequestor from '../configuration-requestor';
 import { IConfigurationStore } from '../configuration-store/configuration-store';
 import {
@@ -35,6 +42,7 @@ import {
   ConfigDetails,
   Flag,
   ObfuscatedFlag,
+  PrecomputedFlag,
   Variation,
   VariationType,
 } from '../interfaces';
@@ -876,6 +884,85 @@ export default class EppoClient {
     throw err;
   }
 
+  private getAllAssignments(
+    subjectKey: string,
+    subjectAttributes: Attributes = {},
+  ): Record<string, PrecomputedFlag> {
+    const configDetails = this.getConfigDetails();
+    const flagKeys = this.getFlagKeys();
+    const flags: Record<string, PrecomputedFlag> = {};
+
+    // Evaluate all the enabled flags for the user
+    flagKeys.forEach((flagKey) => {
+      const flag = this.getFlag(flagKey);
+      if (!flag) {
+        logger.debug(`[Eppo SDK] No assigned variation. Flag does not exist.`);
+        return;
+      }
+
+      // Evaluate the flag for this subject.
+      const evaluation = this.evaluator.evaluateFlag(
+        flag,
+        configDetails,
+        subjectKey,
+        subjectAttributes,
+        this.isObfuscated,
+      );
+
+      // allocationKey is set along with variation when there is a result. this check appeases typescript below
+      if (!evaluation.variation || !evaluation.allocationKey) {
+        logger.debug(`[Eppo SDK] No assigned variation: ${flagKey}`);
+        return;
+      }
+
+      // Transform into a PrecomputedFlag
+      flags[flagKey] = {
+        flagKey,
+        allocationKey: evaluation.allocationKey,
+        doLog: evaluation.doLog,
+        extraLogging: evaluation.extraLogging,
+        variationKey: evaluation.variation.key,
+        variationType: flag.variationType,
+        variationValue: evaluation.variation.value.toString(),
+      };
+    });
+
+    return flags;
+  }
+
+  /**
+   * Computes and returns assignments for a subject from all loaded flags.
+   *
+   * @param subjectKey an identifier of the experiment subject, for example a user ID.
+   * @param subjectAttributes optional attributes associated with the subject, for example name and email.
+   * @param obfuscated optional whether to obfuscate the results.
+   */
+  getPrecomputedAssignments(
+    subjectKey: string,
+    subjectAttributes: Attributes = {},
+    obfuscated = false,
+  ): string {
+    const configDetails = this.getConfigDetails();
+    const flags = this.getAllAssignments(subjectKey, subjectAttributes);
+
+    const precomputedConfig: IPrecomputedConfiguration = obfuscated
+      ? new ObfuscatedPrecomputedConfiguration(
+          subjectKey,
+          flags,
+          subjectAttributes,
+          configDetails.configEnvironment,
+        )
+      : new PrecomputedConfiguration(
+          subjectKey,
+          flags,
+          subjectAttributes,
+          configDetails.configEnvironment,
+        );
+
+    const configWire: IConfigurationWire = new ConfigurationWireV1(precomputedConfig);
+    return JSON.stringify(configWire);
+  }
+
   /**
    * [Experimental] Get a detailed return of assignment for a particular subject and flag.
    *

src/client/eppo-precomputed-client.spec.ts

@@ -92,6 +92,7 @@ describe('EppoPrecomputedClient E2E test', () => {
 
   const precomputedFlagKey = 'mock-flag';
   const mockPrecomputedFlag: PrecomputedFlag = {
+    flagKey: precomputedFlagKey,
     variationKey: 'a',
     variationValue: 'variation-a',
     allocationKey: 'allocation-a',
@@ -736,6 +737,7 @@ describe('EppoPrecomputedClient E2E test', () => {
 
       await store.setEntries({
         'test-flag': {
+          flagKey: precomputedFlagKey,
           variationType: VariationType.STRING,
           variationKey: 'control',
           variationValue: 'test-value',

src/configuration.ts

@@ -0,0 +1,88 @@
+import { Environment, FormatEnum, PrecomputedFlag } from './interfaces';
+import { generateSalt, obfuscatePrecomputedFlags, Salt } from './obfuscation';
+import { Attributes, ContextAttributes } from './types';
+
+export interface IPrecomputedConfigurationResponse {
+  // `format` is always `PRECOMPUTED`
+  readonly format: FormatEnum;
+  readonly obfuscated: boolean;
+  // Salt used for hashing md5-encoded strings.
+  readonly salt: string;
+  readonly createdAt: string;
+  // Environment might be missing if configuration was absent during evaluation.
+  readonly environment?: Environment;
+  readonly flags: Record<string, PrecomputedFlag>;
+}
+
+export interface IPrecomputedConfiguration {
+  // JSON encoded `PrecomputedConfigurationResponse`
+  readonly response: string;
+  readonly subjectKey: string;
+  // Optional in case server does not want to expose attributes to a client.
+  readonly subjectAttributes?: Attributes | ContextAttributes;
+}
+
+export class PrecomputedConfiguration implements IPrecomputedConfiguration {
+  readonly format = FormatEnum.PRECOMPUTED;
+  readonly response: string;
+
+  constructor(
+    readonly subjectKey: string,
+    flags: Record<string, PrecomputedFlag>,
+    readonly subjectAttributes?: Attributes | ContextAttributes,
+    environment?: Environment,
+  ) {
+    const precomputedResponse: IPrecomputedConfigurationResponse = {
+      format: FormatEnum.PRECOMPUTED,
+      obfuscated: false,
+      salt: '',
+      createdAt: new Date().toISOString(),
+      environment,
+      flags,
+    };
+    this.response = JSON.stringify(precomputedResponse);
+  }
+}
+
+export class ObfuscatedPrecomputedConfiguration implements IPrecomputedConfiguration {
+  readonly format = FormatEnum.PRECOMPUTED;
+  readonly response: string;
+  private saltBase: Salt;
+
+  constructor(
+    readonly subjectKey: string,
+    flags: Record<string, PrecomputedFlag>,
+    readonly subjectAttributes?: Attributes | ContextAttributes,
+    environment?: Environment,
+  ) {
+    this.saltBase = generateSalt();
+
+    const precomputedResponse: IPrecomputedConfigurationResponse = {
+      format: FormatEnum.PRECOMPUTED,
+      obfuscated: true,
+      salt: this.saltBase.base64String,
+      createdAt: new Date().toISOString(),
+      environment,
+      flags: obfuscatePrecomputedFlags(this.saltBase.saltString, flags),
+    };
+    this.response = JSON.stringify(precomputedResponse);
+  }
+}
+
+// "Wire" in the name means "in-transit"/"file" format.
+// In-memory representation may differ significantly and is up to SDKs.
+export interface IConfigurationWire {
+  /**
+   * Version field should be incremented for breaking format changes.
+   * For example, removing required fields or changing field type/meaning.
+   */
+  readonly version: number;
+
+  // TODO: Add flags and bandits for offline/non-precomputed initialization
+  readonly precomputed?: IPrecomputedConfiguration;
+}
+
+export class ConfigurationWireV1 implements IConfigurationWire {
+  version = 1;
+  constructor(readonly precomputed?: IPrecomputedConfiguration) {}
+}

src/http-client.ts

@@ -1,11 +1,11 @@
 import ApiEndpoints from './api-endpoints';
+import { IPrecomputedConfigurationResponse } from './configuration';
 import {
   BanditParameters,
   BanditVariation,
   Environment,
   Flag,
   FormatEnum,
-  PrecomputedFlag,
   PrecomputedFlagsPayload,
 } from './interfaces';
 import { Attributes } from './types';
@@ -42,19 +42,12 @@ export interface IBanditParametersResponse {
   bandits: Record<string, BanditParameters>;
 }
 
-export interface IPrecomputedFlagsResponse {
-  createdAt: string;
-  format: FormatEnum;
-  environment: Environment;
-  flags: Record<string, PrecomputedFlag>;
-}
-
 export interface IHttpClient {
   getUniversalFlagConfiguration(): Promise<IUniversalFlagConfigResponse | undefined>;
   getBanditParameters(): Promise<IBanditParametersResponse | undefined>;
   getPrecomputedFlags(
     payload: PrecomputedFlagsPayload,
-  ): Promise<IPrecomputedFlagsResponse | undefined>;
+  ): Promise<IPrecomputedConfigurationResponse | undefined>;
   rawGet<T>(url: URL): Promise<T | undefined>;
   rawPost<T, P>(url: URL, payload: P): Promise<T | undefined>;
 }
@@ -74,9 +67,12 @@ export default class FetchHttpClient implements IHttpClient {
 
   async getPrecomputedFlags(
     payload: PrecomputedFlagsPayload,
-  ): Promise<IPrecomputedFlagsResponse | undefined> {
+  ): Promise<IPrecomputedConfigurationResponse | undefined> {
     const url = this.apiEndpoints.precomputedFlagsEndpoint();
-    return await this.rawPost<IPrecomputedFlagsResponse, PrecomputedFlagsPayload>(url, payload);
+    return await this.rawPost<IPrecomputedConfigurationResponse, PrecomputedFlagsPayload>(
+      url,
+      payload,
+    );
   }
 
   async rawGet<T>(url: URL): Promise<T | undefined> {