adding debug mode; version 2.1.1-alpha.0

Author: leoromanovsky

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eppo/js-client-sdk-common",
-  "version": "2.1.0",
+  "version": "2.1.1-alpha.0",
   "description": "Eppo SDK for client-side JavaScript applications (base for both web and react native)",
   "main": "dist/index.js",
   "files": [

src/client/eppo-client.spec.ts

@@ -164,7 +164,14 @@ describe('EppoClient E2E test', () => {
       expect(
         client.getParsedJSONAssignment('subject-identifer', flagKey, {}, mockHooks),
       ).toBeNull();
-      expect(client.getStringAssignment('subject-identifer', flagKey, {}, mockHooks)).toBeNull();
+      const assignmentWithReason = client._getStringAssignmentWithReason(
+        'subject-identifer',
+        flagKey,
+        {},
+        mockHooks,
+      );
+      expect(assignmentWithReason.reason).toContain('Error');
+      expect(assignmentWithReason.assignment).toBeNull();
     });
 
     it('throws error when graceful failure is false', async () => {
@@ -191,7 +198,7 @@ describe('EppoClient E2E test', () => {
       }).toThrow();
 
       expect(() => {
-        client.getStringAssignment('subject-identifer', flagKey, {}, mockHooks);
+        client._getStringAssignmentWithReason('subject-identifer', flagKey, {}, mockHooks);
       }).toThrow();
     });
   });
@@ -856,11 +863,13 @@ describe('EppoClient E2E test', () => {
           return EppoValue.Numeric(na);
         }
         case ValueTestType.StringType: {
-          const sa = globalClient.getStringAssignment(
+          const assignmentWithReason = globalClient._getStringAssignmentWithReason(
             subject.subjectKey,
             experiment,
             subject.subjectAttributes,
           );
+          const sa = assignmentWithReason.assignment;
+          console.log('Assigned ' + sa + ' because ' + assignmentWithReason.reason);
           if (sa === null) return null;
           return EppoValue.String(sa);
         }
@@ -966,9 +975,9 @@ describe('EppoClient E2E test', () => {
         expect(td.explain(mockHooks.onPostAssignment).callCount).toEqual(1);
         expect(td.explain(mockHooks.onPostAssignment).calls[0].args[0]).toEqual(flagKey);
         expect(td.explain(mockHooks.onPostAssignment).calls[0].args[1]).toEqual(subject);
-        expect(td.explain(mockHooks.onPostAssignment).calls[0].args[2]).toEqual(
-          EppoValue.String(variation ?? ''),
-        );
+        const eppoValue = EppoValue.String(variation ?? '');
+        eppoValue.reason = 'Normal assignment randomization';
+        expect(td.explain(mockHooks.onPostAssignment).calls[0].args[2]).toEqual(eppoValue);
       });
     });
   });
@@ -1069,13 +1078,15 @@ describe(' EppoClient getAssignment From Obfuscated RAC', () => {
           return EppoValue.Numeric(na);
         }
         case ValueTestType.StringType: {
-          const sa = globalClient.getStringAssignment(
+          const assignmentWithReason = globalClient._getStringAssignmentWithReason(
             subject.subjectKey,
             experiment,
             subject.subjectAttributes,
             undefined,
             true,
           );
+          const sa = assignmentWithReason.assignment;
+          console.log('Assigned ' + sa + ' because ' + assignmentWithReason.reason);
           if (sa === null) return null;
           return EppoValue.String(sa);
         }

src/client/eppo-client.ts

@@ -30,7 +30,7 @@ import { EppoValue, ValueType } from '../eppo_value';
 import ExperimentConfigurationRequestor from '../experiment-configuration-requestor';
 import HttpClient from '../http-client';
 import { getMD5Hash } from '../obfuscation';
-import initPoller, { IPoller } from '../poller';
+import initPoller, { IPoller, _pollerStats } from '../poller';
 import { findMatchingRule } from '../rule_evaluator';
 import { getShard, isShardInRange } from '../shard';
 import { validateNotBlank } from '../validation';
@@ -59,6 +59,18 @@ export interface IEppoClient {
     assignmentHooks?: IAssignmentHooks,
   ): string | null;
 
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  _pollerStats(): any;
+
+  _getStringAssignmentWithReason(
+    subjectKey: string,
+    flagKey: string,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    subjectAttributes?: Record<string, any>,
+    assignmentHooks?: IAssignmentHooks,
+    obfuscated?: boolean,
+  ): { assignment: string | null; reason: string };
+
   /**
    * Maps a subject to a variation for a given experiment.
    *
@@ -152,6 +164,13 @@ export default class EppoClient implements IEppoClient {
     this.configurationRequestConfig = configurationRequestConfig;
   }
 
+  /**
+   * @deprecated added for temporary debugging
+   */
+  public _pollerStats() {
+    return _pollerStats();
+  }
+
   public async fetchFlagConfigurations() {
     if (!this.configurationRequestConfig) {
       throw new Error(
@@ -253,6 +272,43 @@ export default class EppoClient implements IEppoClient {
     }
   }
 
+  /**
+   * @deprecated added for temporary debugging
+   */
+  public _getStringAssignmentWithReason(
+    subjectKey: string,
+    flagKey: string,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    subjectAttributes: Record<string, any> = {},
+    assignmentHooks?: IAssignmentHooks | undefined,
+    obfuscated = false,
+  ): { assignment: string | null; reason: string } {
+    let assignment: string | null = null;
+    let reason = 'Unknown; pre-getAssignmentVariation';
+    try {
+      const eppoValue = this.getAssignmentVariation(
+        subjectKey,
+        flagKey,
+        subjectAttributes,
+        assignmentHooks,
+        obfuscated,
+        ValueType.StringType,
+      );
+      const eppoValueAssignment = eppoValue.stringValue;
+      reason = eppoValue.reason ?? 'Unknown; post-getAssignmentVariation';
+      if (eppoValueAssignment === undefined) {
+        assignment = null;
+        reason += '; coalesced to null';
+      } else {
+        assignment = eppoValueAssignment;
+      }
+    } catch (error) {
+      reason = 'Caught error: ' + error.message + '\n' + error.stack;
+      this.rethrowIfNotGraceful(error);
+    }
+    return { assignment, reason };
+  }
+
   getBoolAssignment(
     subjectKey: string,
     flagKey: string,
@@ -420,21 +476,30 @@ export default class EppoClient implements IEppoClient {
       experimentConfig,
       expectedValueType,
     );
+    allowListOverride.reason = 'In override list';
 
     if (!allowListOverride.isNullType()) {
       if (!allowListOverride.isExpectedType()) {
+        nullAssignment.assignment.reason = 'Allow list override is not the expected type';
         return nullAssignment;
       }
       return { ...nullAssignment, assignment: allowListOverride };
     }
 
     // Check for disabled flag.
-    if (!experimentConfig?.enabled) return nullAssignment;
+    if (!experimentConfig?.enabled) {
+      nullAssignment.assignment.reason = 'Experiment is not enabled';
+      return nullAssignment;
+    }
 
     // check for overridden assignment via hook
     const overriddenAssignment = assignmentHooks?.onPreAssignment(flagKey, subjectKey);
     if (overriddenAssignment !== null && overriddenAssignment !== undefined) {
-      if (!overriddenAssignment.isExpectedType()) return nullAssignment;
+      if (!overriddenAssignment.isExpectedType()) {
+        nullAssignment.assignment.reason = 'Override via hook is wrong type';
+        return nullAssignment;
+      }
+      overriddenAssignment.reason = 'Overriden via hook';
       return { ...nullAssignment, assignment: overriddenAssignment };
     }
 
@@ -444,12 +509,17 @@ export default class EppoClient implements IEppoClient {
       experimentConfig.rules,
       obfuscated,
     );
-    if (!matchedRule) return nullAssignment;
+    if (!matchedRule) {
+      nullAssignment.assignment.reason = 'No matching targeting rule';
+      return nullAssignment;
+    }
 
     // Check if subject is in allocation sample.
     const allocation = experimentConfig.allocations[matchedRule.allocationKey];
-    if (!this.isInExperimentSample(subjectKey, flagKey, experimentConfig, allocation))
+    if (!this.isInExperimentSample(subjectKey, flagKey, experimentConfig, allocation)) {
+      nullAssignment.assignment.reason = 'Not in experiment sample';
       return nullAssignment;
+    }
 
     // Compute variation for subject.
     const { subjectShards } = experimentConfig;
@@ -458,23 +528,27 @@ export default class EppoClient implements IEppoClient {
     let assignedVariation: IVariation | undefined;
     let holdoutVariation = null;
 
+    let variationReason = '';
     const holdoutShard = getShard(`holdout-${subjectKey}`, subjectShards);
     const matchingHoldout = holdouts?.find((holdout) => {
       const { statusQuoShardRange, shippedShardRange } = holdout;
       if (isShardInRange(holdoutShard, statusQuoShardRange)) {
         assignedVariation = variations.find(
           (variation) => variation.variationKey === statusQuoVariationKey,
         );
+        variationReason = 'Holdout during in-flight experiment, status quo variation';
         // Only log the holdout variation if this is a rollout allocation
         // Only rollout allocations have shippedShardRange specified
         if (shippedShardRange) {
           holdoutVariation = HoldoutVariationEnum.STATUS_QUO;
+          variationReason = 'Holdout after rollout, status quo variation';
         }
       } else if (shippedShardRange && isShardInRange(holdoutShard, shippedShardRange)) {
         assignedVariation = variations.find(
           (variation) => variation.variationKey === shippedVariationKey,
         );
         holdoutVariation = HoldoutVariationEnum.ALL_SHIPPED;
+        variationReason = 'Holdout after rollout, shipped variation';
       }
       return assignedVariation;
     });
@@ -484,24 +558,33 @@ export default class EppoClient implements IEppoClient {
       assignedVariation = variations.find((variation) =>
         isShardInRange(assignmentShard, variation.shardRange),
       );
+      variationReason = 'Normal assignment randomization';
     }
 
+    const variationEppoValue = EppoValue.generateEppoValue(
+      expectedValueType,
+      assignedVariation?.value,
+      assignedVariation?.typedValue,
+    );
+    variationEppoValue.reason = variationReason;
+
+    const typeMismatchAssignment = nullAssignment;
+    typeMismatchAssignment.assignment.reason = 'Uexpected variation assignment type';
+
     const internalAssignment: {
       allocationKey: string;
       assignment: EppoValue;
       holdoutKey: string | null;
       holdoutVariation: NullableHoldoutVariationType;
     } = {
       allocationKey: matchedRule.allocationKey,
-      assignment: EppoValue.generateEppoValue(
-        expectedValueType,
-        assignedVariation?.value,
-        assignedVariation?.typedValue,
-      ),
+      assignment: variationEppoValue,
       holdoutKey,
       holdoutVariation: holdoutVariation as NullableHoldoutVariationType,
     };
-    return internalAssignment.assignment.isExpectedType() ? internalAssignment : nullAssignment;
+    return internalAssignment.assignment.isExpectedType()
+      ? internalAssignment
+      : typeMismatchAssignment;
   }
 
   public setLogger(logger: IAssignmentLogger) {

src/eppo_value.ts

@@ -17,6 +17,8 @@ export class EppoValue {
   public stringValue: string | undefined;
   public objectValue: object | undefined;
 
+  public reason: string | undefined;
+
   private constructor(
     valueType: ValueType,
     boolValue: boolean | undefined,

src/poller.spec.ts

@@ -1,7 +1,7 @@
 import * as td from 'testdouble';
 
 import { POLL_INTERVAL_MS, POLL_JITTER_PCT } from './constants';
-import initPoller from './poller';
+import initPoller, { pollerStats } from './poller';
 
 describe('poller', () => {
   const testIntervalMs = POLL_INTERVAL_MS;
@@ -15,6 +15,7 @@ describe('poller', () => {
   afterEach(() => {
     td.reset();
     jest.clearAllTimers();
+    console.log('>>>> POLLER STATS', pollerStats());
   });
 
   afterAll(() => {

src/poller.ts

@@ -9,6 +9,28 @@ export interface IPoller {
   stop: () => void;
 }
 
+// Basic stats
+let initializations = 0;
+let attemptedPolls = 0;
+let failedPolls = 0;
+let succeededPolls = 0;
+const pollDurations: number[] = [];
+const failureMessages: string[] = [];
+
+/**
+ * @deprecated added for temporary debugging
+ */
+export function _pollerStats() {
+  return {
+    initializations,
+    attemptedPolls,
+    failedPolls,
+    succeededPolls,
+    pollDurations,
+    failureMessages,
+  };
+}
+
 // TODO: change this to a class with methods instead of something that returns a function
 
 export default function initPoller(
@@ -24,6 +46,7 @@ export default function initPoller(
     pollAfterFailedStart?: boolean;
   },
 ): IPoller {
+  initializations += 1;
   let stopped = false;
   let failedAttempts = 0;
   let nextPollMs = intervalMs;
@@ -40,11 +63,17 @@ export default function initPoller(
 
     while (!startRequestSuccess && startAttemptsRemaining > 0) {
       try {
+        attemptedPolls += 1;
+        const timerStart = Date.now();
         await callback();
+        pollDurations.push(Date.now() - timerStart);
+        succeededPolls += 1;
         startRequestSuccess = true;
         previousPollFailed = false;
         console.log('Eppo SDK successfully requested initial configuration');
       } catch (pollingError) {
+        failedPolls += 1;
+        failureMessages.push(pollingError.message);
         previousPollFailed = true;
         console.warn(
           `Eppo SDK encountered an error with initial poll of configurations: ${pollingError.message}`,
@@ -104,15 +133,22 @@ export default function initPoller(
     }
 
     try {
+      attemptedPolls += 1;
+      const timerStart = Date.now();
       await callback();
+      pollDurations.push(Date.now() - timerStart);
       // If no error, reset any retrying
+      succeededPolls += 1;
       failedAttempts = 0;
       nextPollMs = intervalMs;
       if (previousPollFailed) {
         previousPollFailed = false;
         console.log('Eppo SDK poll successful; resuming normal polling');
       }
     } catch (error) {
+      failedPolls += 1;
+      failureMessages.push(error.message);
+
       previousPollFailed = true;
       console.warn(`Eppo SDK encountered an error polling configurations: ${error.message}`);
       const maxTries = 1 + (options?.maxPollRetries ?? DEFAULT_POLL_CONFIG_REQUEST_RETRIES);