feat: extend Configuration/Requestor to support precomputed

Author: rasendubi

src/client/eppo-client.ts

@@ -118,6 +118,18 @@ export type EppoClientParameters = {
   };
 
   configuration?: {
+    /**
+     * When specified, will run the client in the "precomputed"
+     * mode. Instead of fetching the full configuration from the
+     * server, the client will fetch flags and bandits precomputed for
+     * the specified subject.
+     */
+    precompute?: {
+      subjectKey: string;
+      subjectAttributes: Attributes | ContextAttributes;
+      banditActions?: Record</* flagKey: */ string, BanditActions>;
+    };
+
     /**
      * Strategy for fetching initial configuration.
      *
@@ -359,6 +371,24 @@ export default class EppoClient {
       this.configurationFeed,
       {
         wantsBandits: options.bandits?.enable ?? DEFAULT_ENABLE_BANDITS,
+        precomputed: options.configuration?.precompute
+          ? {
+              subjectKey: options.configuration.precompute.subjectKey,
+              subjectAttributes: ensureContextualSubjectAttributes(
+                options.configuration.precompute.subjectAttributes,
+              ),
+              banditActions: options.configuration.precompute.banditActions
+                ? Object.fromEntries(
+                    Object.entries(options.configuration.precompute.banditActions).map(
+                      ([banditKey, actions]) => [
+                        banditKey,
+                        ensureActionsWithContextualAttributes(actions),
+                      ],
+                    ),
+                  )
+                : undefined,
+            }
+          : undefined,
       },
     );
 

src/client/eppo-precomputed-client.ts

@@ -362,10 +362,6 @@ export default class EppoPrecomputedClient {
   }
 
   private getPrecomputedFlag(flagKey: string): DecodedPrecomputedFlag | null {
-    return this.getObfuscatedFlag(flagKey);
-  }
-
-  private getObfuscatedFlag(flagKey: string): DecodedPrecomputedFlag | null {
     const salt = this.precomputedFlagStore.salt;
     const saltedAndHashedFlagKey = getMD5Hash(flagKey, salt);
     const precomputedFlag: PrecomputedFlag | null = this.precomputedFlagStore.get(
@@ -376,6 +372,7 @@ export default class EppoPrecomputedClient {
 
   private getPrecomputedBandit(banditKey: string): IPrecomputedBandit | null {
     const obfuscatedBandit = this.getObfuscatedPrecomputedBandit(banditKey);
+
     return obfuscatedBandit ? decodePrecomputedBandit(obfuscatedBandit) : null;
   }
 

src/configuration-requestor.spec.ts

@@ -6,6 +6,7 @@ import {
 } from '../test/testHelpers';
 
 import ApiEndpoints from './api-endpoints';
+import { ensureContextualSubjectAttributes } from './attributes';
 import { BroadcastChannel } from './broadcast';
 import { ConfigurationFeed } from './configuration-feed';
 import ConfigurationRequestor from './configuration-requestor';
@@ -19,6 +20,32 @@ import FetchHttpClient, {
 import { StoreBackedConfiguration } from './i-configuration';
 import { BanditParameters, BanditVariation, Flag, VariationType } from './interfaces';
 
+const MOCK_PRECOMPUTED_RESPONSE = {
+  flags: {
+    'precomputed-flag-1': {
+      allocationKey: 'default',
+      variationKey: 'true-variation',
+      variationType: 'BOOLEAN',
+      variationValue: 'true',
+      extraLogging: {},
+      doLog: true,
+    },
+    'precomputed-flag-2': {
+      allocationKey: 'test-group',
+      variationKey: 'variation-a',
+      variationType: 'STRING',
+      variationValue: 'variation-a',
+      extraLogging: {},
+      doLog: true,
+    },
+  },
+  environment: {
+    name: 'production',
+  },
+  format: 'PRECOMPUTED',
+  createdAt: '2024-03-20T00:00:00Z',
+};
+
 describe('ConfigurationRequestor', () => {
   let configurationFeed: ConfigurationFeed;
   let configurationStore: ConfigurationStore;
@@ -532,4 +559,66 @@ describe('ConfigurationRequestor', () => {
       });
     });
   });
+
+  describe('Precomputed flags', () => {
+    let fetchSpy: jest.Mock;
+    beforeEach(() => {
+      configurationRequestor = new ConfigurationRequestor(httpClient, configurationFeed, {
+        precomputed: {
+          subjectKey: 'subject-key',
+          subjectAttributes: ensureContextualSubjectAttributes({
+            'attribute-key': 'attribute-value',
+          }),
+        },
+      });
+
+      fetchSpy = jest.fn(() => {
+        return Promise.resolve({
+          ok: true,
+          status: 200,
+          json: () => Promise.resolve(MOCK_PRECOMPUTED_RESPONSE),
+        });
+      }) as jest.Mock;
+      global.fetch = fetchSpy;
+    });
+
+    afterEach(() => {
+      jest.clearAllMocks();
+    });
+
+    afterAll(() => {
+      jest.restoreAllMocks();
+    });
+
+    it('Fetches precomputed flag configuration', async () => {
+      const configuration = await configurationRequestor.fetchConfiguration();
+
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+
+      expect(configuration.getFlagKeys().length).toBe(2);
+
+      const precomputed = configuration.getPrecomputedConfiguration();
+
+      const flag1 = precomputed?.response.flags['precomputed-flag-1'];
+      expect(flag1?.allocationKey).toBe('default');
+      expect(flag1?.variationKey).toBe('true-variation');
+      expect(flag1?.variationType).toBe('BOOLEAN');
+      expect(flag1?.variationValue).toBe('true');
+      expect(flag1?.extraLogging).toEqual({});
+      expect(flag1?.doLog).toBe(true);
+
+      const flag2 = precomputed?.response.flags['precomputed-flag-2'];
+      expect(flag2?.allocationKey).toBe('test-group');
+      expect(flag2?.variationKey).toBe('variation-a');
+      expect(flag2?.variationType).toBe('STRING');
+      expect(flag2?.variationValue).toBe('variation-a');
+      expect(flag2?.extraLogging).toEqual({});
+      expect(flag2?.doLog).toBe(true);
+
+      expect(precomputed?.response.format).toBe('PRECOMPUTED');
+
+      expect(precomputed?.response.environment).toStrictEqual({ name: 'production' });
+      expect(precomputed?.response.createdAt).toBe('2024-03-20T00:00:00Z');
+    });
+  });
 });

src/configuration-requestor.ts

@@ -1,9 +1,24 @@
 import { BanditsConfig, Configuration, FlagsConfig } from './configuration';
 import { ConfigurationFeed, ConfigurationSource } from './configuration-feed';
 import { IHttpClient } from './http-client';
+import { ContextAttributes, FlagKey } from './types';
 
+export class ConfigurationError extends Error {
+  public constructor(message: string) {
+    super(message);
+    this.name = 'ConfigurationError';
+  }
+}
+
+/** @internal */
 export type ConfigurationRequestorOptions = {
   wantsBandits: boolean;
+
+  precomputed?: {
+    subjectKey: string;
+    subjectAttributes: ContextAttributes;
+    banditActions?: Record<FlagKey, Record<string, ContextAttributes>>;
+  };
 };
 
 /**
@@ -35,19 +50,37 @@ export default class ConfigurationRequestor {
     });
   }
 
-  public async fetchConfiguration(): Promise<Configuration | null> {
+  public async fetchConfiguration(): Promise<Configuration> {
+    const configuration = this.options.precomputed
+      ? await this.fetchPrecomputedConfiguration(this.options.precomputed)
+      : await this.fetchRegularConfiguration();
+
+    this.latestConfiguration = configuration;
+    this.configurationFeed.broadcast(configuration, ConfigurationSource.Network);
+
+    return configuration;
+  }
+
+  private async fetchRegularConfiguration(): Promise<Configuration> {
     const flags = await this.httpClient.getUniversalFlagConfiguration();
     if (!flags?.response.flags) {
-      return null;
+      throw new ConfigurationError('empty response');
     }
 
     const bandits = await this.getBanditsFor(flags);
 
-    const configuration = Configuration.fromResponses({ flags, bandits });
-    this.latestConfiguration = configuration;
-    this.configurationFeed.broadcast(configuration, ConfigurationSource.Network);
+    return Configuration.fromResponses({ flags, bandits });
+  }
 
-    return configuration;
+  private async fetchPrecomputedConfiguration(
+    precomputed: NonNullable<ConfigurationRequestorOptions['precomputed']>,
+  ): Promise<Configuration> {
+    const response = await this.httpClient.getPrecomputedFlags(precomputed);
+    if (!response) {
+      throw new ConfigurationError('empty response');
+    }
+
+    return Configuration.fromResponses({ precomputed: response });
   }
 
   /**