Implement assignment logic

ploomiz · ploomiz · commit 6caf55f2d809 · 2022-06-17T09:41:30.000-07:00
diff --git a/docs/js-client-sdk.getinstance.md b/docs/js-client-sdk.getinstance.md
@@ -0,0 +1,19 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@eppo/js-client-sdk](./js-client-sdk.md) &gt; [getInstance](./js-client-sdk.getinstance.md)
+
+## getInstance() function
+
+Used to access a singleton SDK client instance. Use the method after calling init() to initialize the client.
+
+<b>Signature:</b>
+
+```typescript
+export declare function getInstance(): IEppoClient;
+```
+<b>Returns:</b>
+
+IEppoClient
+
+a singleton client instance
+
diff --git a/docs/js-client-sdk.iclientconfig.apikey.md b/docs/js-client-sdk.iclientconfig.apikey.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@eppo/js-client-sdk](./js-client-sdk.md) &gt; [IClientConfig](./js-client-sdk.iclientconfig.md) &gt; [apiKey](./js-client-sdk.iclientconfig.apikey.md)
+
+## IClientConfig.apiKey property
+
+Eppo API key
+
+<b>Signature:</b>
+
+```typescript
+apiKey: string;
+```
diff --git a/docs/js-client-sdk.iclientconfig.baseurl.md b/docs/js-client-sdk.iclientconfig.baseurl.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@eppo/js-client-sdk](./js-client-sdk.md) &gt; [IClientConfig](./js-client-sdk.iclientconfig.md) &gt; [baseUrl](./js-client-sdk.iclientconfig.baseurl.md)
+
+## IClientConfig.baseUrl property
+
+Base URL of the Eppo API. Clients should use the default setting in most cases.
+
+<b>Signature:</b>
+
+```typescript
+baseUrl?: string;
+```
diff --git a/docs/js-client-sdk.iclientconfig.md b/docs/js-client-sdk.iclientconfig.md
@@ -0,0 +1,23 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@eppo/js-client-sdk](./js-client-sdk.md) &gt; [IClientConfig](./js-client-sdk.iclientconfig.md)
+
+## IClientConfig interface
+
+Configuration used for initializing the Eppo client
+
+<b>Signature:</b>
+
+```typescript
+export interface IClientConfig 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [apiKey](./js-client-sdk.iclientconfig.apikey.md) | string | Eppo API key |
+|  [baseUrl?](./js-client-sdk.iclientconfig.baseurl.md) | string | <i>(Optional)</i> Base URL of the Eppo API. Clients should use the default setting in most cases. |
+|  [subjectAttributes?](./js-client-sdk.iclientconfig.subjectattributes.md) | Record&lt;string, AttributeValueType&gt; | <i>(Optional)</i> Optional attributes associated with the subject, for example name and email. The subject attributes are used for evaluating any targeting rules tied to the experiment. |
+|  [subjectKey](./js-client-sdk.iclientconfig.subjectkey.md) | string | An identifier of the experiment subject, for example a user ID. |
+
diff --git a/docs/js-client-sdk.iclientconfig.subjectattributes.md b/docs/js-client-sdk.iclientconfig.subjectattributes.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@eppo/js-client-sdk](./js-client-sdk.md) &gt; [IClientConfig](./js-client-sdk.iclientconfig.md) &gt; [subjectAttributes](./js-client-sdk.iclientconfig.subjectattributes.md)
+
+## IClientConfig.subjectAttributes property
+
+Optional attributes associated with the subject, for example name and email. The subject attributes are used for evaluating any targeting rules tied to the experiment.
+
+<b>Signature:</b>
+
+```typescript
+subjectAttributes?: Record<string, AttributeValueType>;
+```
diff --git a/docs/js-client-sdk.iclientconfig.subjectkey.md b/docs/js-client-sdk.iclientconfig.subjectkey.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@eppo/js-client-sdk](./js-client-sdk.md) &gt; [IClientConfig](./js-client-sdk.iclientconfig.md) &gt; [subjectKey](./js-client-sdk.iclientconfig.subjectkey.md)
+
+## IClientConfig.subjectKey property
+
+An identifier of the experiment subject, for example a user ID.
+
+<b>Signature:</b>
+
+```typescript
+subjectKey: string;
+```
diff --git a/docs/js-client-sdk.init.md b/docs/js-client-sdk.init.md
@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@eppo/js-client-sdk](./js-client-sdk.md) &gt; [init](./js-client-sdk.init.md)
+
+## init() function
+
+Initializes the Eppo client with configuration parameters. This method should be called once on application startup. After invocation of this method, the SDK will poll Eppo's API at regular intervals to retrieve assignment configurations.
+
+<b>Signature:</b>
+
+```typescript
+export declare function init(config: IClientConfig): Promise<IEppoClient>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  config | [IClientConfig](./js-client-sdk.iclientconfig.md) | client configuration |
+
+<b>Returns:</b>
+
+Promise&lt;IEppoClient&gt;
+
diff --git a/docs/js-client-sdk.md b/docs/js-client-sdk.md
@@ -8,5 +8,12 @@
 
 |  Function | Description |
 |  --- | --- |
-|  [dummy()](./js-client-sdk.dummy.md) | Test documentation |
+|  [getInstance()](./js-client-sdk.getinstance.md) | Used to access a singleton SDK client instance. Use the method after calling init() to initialize the client. |
+|  [init(config)](./js-client-sdk.init.md) | Initializes the Eppo client with configuration parameters. This method should be called once on application startup. After invocation of this method, the SDK will poll Eppo's API at regular intervals to retrieve assignment configurations. |
+
+## Interfaces
+
+|  Interface | Description |
+|  --- | --- |
+|  [IClientConfig](./js-client-sdk.iclientconfig.md) | Configuration used for initializing the Eppo client |
 
diff --git a/js-client-sdk.api.md b/js-client-sdk.api.md
@@ -4,8 +4,22 @@
 
 ```ts
 
+// Warning: (ae-forgotten-export) The symbol "IEppoClient" needs to be exported by the entry point index.d.ts
+//
 // @public
-export function dummy(): string;
+export function getInstance(): IEppoClient;
+
+// @public
+export interface IClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+    // Warning: (ae-forgotten-export) The symbol "AttributeValueType" needs to be exported by the entry point index.d.ts
+    subjectAttributes?: Record<string, AttributeValueType>;
+    subjectKey: string;
+}
+
+// @public
+export function init(config: IClientConfig): Promise<IEppoClient>;
 
 // (No @packageDocumentation comment for this package)
 
diff --git a/src/constants.ts b/src/constants.ts
@@ -0,0 +1,2 @@
+export const REQUEST_TIMEOUT_MILLIS = 1000;
+export const BASE_URL = 'https://eppo.cloud/api';
diff --git a/src/eppo-client.ts b/src/eppo-client.ts
@@ -0,0 +1,76 @@
+import { createHash } from 'crypto';
+
+import { IExperimentConfiguration } from './experiment/experiment-configuration';
+import ExperimentConfigurationRequestor from './experiment/experiment-configuration-requestor';
+import { Rule } from './experiment/rule';
+import { matchesAnyRule } from './rule_evaluator';
+import { getShard, isShardInRange } from './shard';
+import { validateNotBlank } from './validation';
+
+/**
+ * Client for assigning experiment variations.
+ * @public
+ */
+export interface IEppoClient {
+  /**
+   * Maps a subject to a variation for a given experiment.
+   *
+   * @param experimentKey experiment identifier
+   * @returns a variation value if the subject is part of the experiment sample, otherwise null
+   * @public
+   */
+  getAssignment(experimentKey: string): string;
+}
+
+export default class EppoClient implements IEppoClient {
+  constructor(
+    private subjectKey: string,
+    private configurationRequestor: ExperimentConfigurationRequestor,
+    private subjectAttributes = {},
+  ) {}
+
+  getAssignment(experimentKey: string): string {
+    validateNotBlank(experimentKey, 'Invalid argument: experimentKey cannot be blank');
+    const experimentConfig = this.configurationRequestor.getConfiguration(experimentKey);
+    if (
+      !experimentConfig?.enabled ||
+      !this.subjectAttributesSatisfyRules(experimentConfig.rules) ||
+      !this.isInExperimentSample(experimentKey, experimentConfig)
+    ) {
+      return null;
+    }
+    const override = this.getSubjectVariationOverride(experimentConfig);
+    if (override) {
+      return override;
+    }
+    const { variations, subjectShards } = experimentConfig;
+    const shard = getShard(`assignment-${this.subjectKey}-${experimentKey}`, subjectShards);
+    return variations.find((variation) => isShardInRange(shard, variation.shardRange)).name;
+  }
+
+  private subjectAttributesSatisfyRules(rules?: Rule[]) {
+    if (!rules || rules.length === 0) {
+      return true;
+    }
+    return matchesAnyRule(this.subjectAttributes || {}, rules);
+  }
+
+  private getSubjectVariationOverride(experimentConfig: IExperimentConfiguration): string {
+    const subjectHash = createHash('md5').update(this.subjectKey).digest('hex');
+    return experimentConfig.overrides[subjectHash];
+  }
+
+  /**
+   * This checks whether the subject is included in the experiment sample.
+   * It is used to determine whether the subject should be assigned to a variant.
+   * Given a hash function output (bucket), check whether the bucket is between 0 and exposure_percent * total_buckets.
+   */
+  private isInExperimentSample(
+    experimentKey: string,
+    experimentConfig: IExperimentConfiguration,
+  ): boolean {
+    const { percentExposure, subjectShards } = experimentConfig;
+    const shard = getShard(`exposure-${this.subjectKey}-${experimentKey}`, subjectShards);
+    return shard <= percentExposure * subjectShards;
+  }
+}
diff --git a/src/experiment/experiment-configuration-requestor.ts b/src/experiment/experiment-configuration-requestor.ts
@@ -0,0 +1,24 @@
+import HttpClient from '../http-client';
+import { EppoSessionStorage } from '../storage';
+
+import { IExperimentConfiguration } from './experiment-configuration';
+
+const RAC_ENDPOINT = '/randomized_assignment/config';
+
+interface IRandomizedAssignmentConfig {
+  experiments: Record<string, IExperimentConfiguration>;
+}
+
+export default class ExperimentConfigurationRequestor {
+  constructor(private configurationStore: EppoSessionStorage, private httpClient: HttpClient) {}
+
+  getConfiguration(experiment: string): IExperimentConfiguration {
+    return this.configurationStore.get<IExperimentConfiguration>(experiment);
+  }
+
+  async fetchAndStoreConfigurations(): Promise<Record<string, IExperimentConfiguration>> {
+    const responseData = await this.httpClient.get<IRandomizedAssignmentConfig>(RAC_ENDPOINT);
+    this.configurationStore.setEntries<IExperimentConfiguration>(responseData.experiments);
+    return responseData.experiments;
+  }
+}
diff --git a/src/experiment/experiment-configuration.ts b/src/experiment/experiment-configuration.ts
@@ -0,0 +1,12 @@
+import { Rule } from './rule';
+import { IVariation } from './variation';
+
+export interface IExperimentConfiguration {
+  name: string;
+  percentExposure: number;
+  enabled: boolean;
+  subjectShards: number;
+  variations: IVariation[];
+  overrides: Record<string, string>;
+  rules?: Rule[];
+}
diff --git a/src/experiment/rule.ts b/src/experiment/rule.ts
@@ -0,0 +1,19 @@
+export type AttributeValueType = string | number;
+
+export enum OperatorType {
+  MATCHES = 'MATCHES',
+  GTE = 'GTE',
+  GT = 'GT',
+  LTE = 'LTE',
+  LT = 'LT',
+}
+
+export interface Condition {
+  operator: OperatorType;
+  attribute: string;
+  value: AttributeValueType;
+}
+
+export interface Rule {
+  conditions: Condition[];
+}
diff --git a/src/experiment/variation.ts b/src/experiment/variation.ts
@@ -0,0 +1,9 @@
+export interface IShardRange {
+  start: number;
+  end: number;
+}
+
+export interface IVariation {
+  name: string;
+  shardRange: IShardRange;
+}
diff --git a/src/http-client.ts b/src/http-client.ts
@@ -0,0 +1,34 @@
+import { AxiosInstance } from 'axios';
+
+interface ISdkParams {
+  apiKey: string;
+  sdkVersion: string;
+  sdkName: string;
+}
+
+export class HttpRequestError extends Error {
+  constructor(public message: string, public status: number) {
+    super(message);
+  }
+}
+
+export default class HttpClient {
+  constructor(private axiosInstance: AxiosInstance, private sdkParams: ISdkParams) {}
+
+  async get<T>(resource: string): Promise<T> {
+    try {
+      const response = await this.axiosInstance.get<T>(resource, {
+        params: this.sdkParams,
+      });
+      return response.data;
+    } catch (error) {
+      this.handleHttpError(error);
+    }
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private handleHttpError(error: any) {
+    const status = error?.response?.status;
+    throw new HttpRequestError(error.message, status);
+  }
+}
diff --git a/src/index.ts b/src/index.ts
diff --git a/src/rule.ts b/src/rule.ts
diff --git a/src/rule_evaluator.ts b/src/rule_evaluator.ts
diff --git a/src/sdk-data.ts b/src/sdk-data.ts
diff --git a/src/shard.ts b/src/shard.ts
diff --git a/src/storage.spec.ts b/src/storage.spec.ts
diff --git a/src/storage.ts b/src/storage.ts
diff --git a/src/validation.ts b/src/validation.ts

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+export const REQUEST_TIMEOUT_MILLIS = 1000;`
	`2`	`+export const BASE_URL = 'https://eppo.cloud/api';`