feat: Auto-assignment tracking

packages/node/package.json

@@ -30,6 +30,8 @@
   "homepage": "https://github.com/amplitude/experiment-node-server#readme",
   "gitHead": "e8ceef5275b6daf4f7f26c6ac2e1683eeba7aca6",
   "dependencies": {
-    "@amplitude/evaluation-js": "1.1.0"
+    "@amplitude/evaluation-js": "1.1.0",
+    "@amplitude/analytics-node": "^1.3.1",
+    "@amplitude/analytics-types": "^1.3.1"
   }
 }

packages/node/src/assignment/assignment-filter.ts

@@ -0,0 +1,25 @@
+import { Assignment, AssignmentFilter } from 'src/assignment/assignment';
+import { DAY_MILLIS } from 'src/assignment/assignment-service';
+import { LRUCache } from 'src/util/lrucache';
+
+export const DEFAULT_FILTER_CAPACITY = 65536;
+
+export class LRUAssignmentFilter implements AssignmentFilter {
+  private readonly cache: LRUCache<number>;
+
+  constructor(size: number) {
+    this.cache = new LRUCache<number>(size);
+  }
+
+  public shouldTrack(assignment: Assignment): boolean {
+    const now = Date.now();
+    const canonicalAssignment = assignment.canonicalize();
+    const lastSent = this.cache.get(canonicalAssignment);
+    if (lastSent == null || now > lastSent + DAY_MILLIS) {
+      this.cache.set(canonicalAssignment, now);
+      return true;
+    } else {
+      return false;
+    }
+  }
+}

packages/node/src/assignment/assignment-service.ts

@@ -0,0 +1,59 @@
+import { BaseEvent } from '@amplitude/analytics-types';
+import { CoreClient } from '@amplitude/analytics-types';
+import {
+  Assignment,
+  AssignmentFilter,
+  AssignmentService,
+} from 'src/assignment/assignment';
+import { hashCode } from 'src/util/hash';
+
+export const DAY_MILLIS = 24 * 60 * 60 * 1000;
+
+export class AmplitudeAssignmentService implements AssignmentService {
+  private readonly amplitude: CoreClient;
+  private readonly assignmentFilter: AssignmentFilter;
+
+  constructor(amplitude: CoreClient, assignmentFilter: AssignmentFilter) {
+    this.amplitude = amplitude;
+    this.assignmentFilter = assignmentFilter;
+  }
+
+  async track(assignment: Assignment): Promise<void> {
+    if (this.assignmentFilter.shouldTrack(assignment)) {
+      this.amplitude.logEvent(this.toEvent(assignment));
+    }
+  }
+
+  public toEvent(assignment: Assignment): BaseEvent {
+    const event: BaseEvent = {
+      event_type: '[Experiment] Assignment',
+      user_id: assignment.user.user_id,
+      device_id: assignment.user.device_id,
+      event_properties: {},
+      user_properties: {},
+    };
+
+    for (const resultsKey in assignment.results) {
+      event.event_properties[`${resultsKey}.variant`] =
+        assignment.results[resultsKey].value;
+    }
+
+    const set = {};
+    const unset = {};
+    for (const resultsKey in assignment.results) {
+      if (assignment.results[resultsKey].isDefaultVariant) {
+        unset[`[Experiment] ${resultsKey}`] = '-';
+      } else {
+        set[`[Experiment] ${resultsKey}`] =
+          assignment.results[resultsKey].value;
+      }
+    }
+    event.user_properties['$set'] = set;
+    event.user_properties['$unset'] = unset;
+
+    event.insert_id = `${event.user_id} ${event.device_id} ${hashCode(
+      assignment.canonicalize(),
+    )} ${assignment.timestamp / DAY_MILLIS}`;
+    return event;
+  }
+}

packages/node/src/assignment/assignment.ts

@@ -0,0 +1,31 @@
+import { ExperimentUser } from 'src/types/user';
+import { Results } from 'src/types/variant';
+
+export class Assignment {
+  public user: ExperimentUser;
+  public results: Results;
+  public timestamp: number = Date.now();
+
+  public constructor(user: ExperimentUser, results: Results) {
+    this.user = user;
+    this.results = results;
+  }
+
+  public canonicalize(): string {
+    let sb =
+      this.user.user_id?.trim() + ' ' + this.user.device_id?.trim() + ' ';
+    for (const key of Object.keys(this.results).sort()) {
+      const value = this.results[key];
+      sb += key.trim() + ' ' + value?.value?.trim() + ' ';
+    }
+    return sb;
+  }
+}
+
+export interface AssignmentService {
+  track(assignment: Assignment): Promise<void>;
+}
+
+export interface AssignmentFilter {
+  shouldTrack(assignment: Assignment): boolean;
+}

packages/node/src/local/client.ts

@@ -1,4 +1,11 @@
+import * as amplitude from '@amplitude/analytics-node';
 import evaluation from '@amplitude/evaluation-js';
+import { Assignment, AssignmentService } from 'src/assignment/assignment';
+import {
+  DEFAULT_FILTER_CAPACITY,
+  LRUAssignmentFilter,
+} from 'src/assignment/assignment-filter';
+import { AmplitudeAssignmentService } from 'src/assignment/assignment-service';
 
 import { FetchHttpClient } from '../transport/http';
 import {
@@ -25,6 +32,7 @@ export class LocalEvaluationClient {
   private readonly config: LocalEvaluationConfig;
   private readonly poller: FlagConfigPoller;
   private flags: FlagConfig[];
+  private readonly assignmentService: AssignmentService;
 
   /**
    * Directly access the client's flag config cache.
@@ -60,6 +68,21 @@ export class LocalEvaluationClient {
       this.config.flagConfigPollingIntervalMillis,
       this.config.debug,
     );
+
+    if (config.assignmentConfiguration) {
+      const instance = amplitude.createInstance();
+      instance.init(
+        config.assignmentConfiguration.apiKey,
+        config.assignmentConfiguration,
+      );
+      const filterCapacity = config.assignmentConfiguration?.filterCapacity
+        ? config.assignmentConfiguration?.filterCapacity
+        : DEFAULT_FILTER_CAPACITY;
+      this.assignmentService = new AmplitudeAssignmentService(
+        instance,
+        new LRUAssignmentFilter(filterCapacity),
+      );
+    }
   }
 
   /**
@@ -85,6 +108,7 @@ export class LocalEvaluationClient {
       this.flags,
     );
     const results: Results = evaluation.evaluate(this.flags, user);
+    void this.assignmentService?.track(new Assignment(user, results));
     const variants: Variants = {};
     const filter = flagKeys && flagKeys.length > 0;
     for (const flagKey in results) {

packages/node/src/types/config.ts

@@ -1,5 +1,7 @@
 import https from 'https';
 
+import { NodeConfig } from '@amplitude/analytics-node/lib/cjs/config';
+
 import { FlagConfig } from './flag';
 
 /**
@@ -140,8 +142,23 @@ export type LocalEvaluationConfig = {
    * The agent used to send http requests.
    */
   httpAgent?: https.Agent;
+
+  /**
+   * Configuration for automatically tracking assignment events after an
+   * evaluation.
+   */
+  assignmentConfiguration?: AssignmentConfiguration;
 };
 
+export type AssignmentConfiguration = {
+  /**
+   * The maximum number of assignments stored in the assignment cache
+   *
+   * Default: 65536
+   */
+  filterCapacity?: number;
+} & NodeConfig;
+
 /**
  Defaults for {@link LocalEvaluationConfig} options.
 

packages/node/src/types/variant.ts

@@ -23,8 +23,8 @@ export type Variants = {
 
 export type FlagResult = {
   value: string;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  payload: any | null | undefined;
+  payload: string;
+  isDefaultVariant: boolean;
   expKey: string | null | undefined;
   deployed: boolean;
   type: string;

packages/node/src/util/hash.ts

@@ -0,0 +1,13 @@
+export function hashCode(s: string): number {
+  let hash = 0,
+    i,
+    chr,
+    len;
+  if (s.length === 0) return hash;
+  for (i = 0, len = s.length; i < len; i++) {
+    chr = s.charCodeAt(i);
+    hash = (hash << 5) - hash + chr;
+    hash |= 0;
+  }
+  return hash;
+}

packages/node/src/util/lrucache.ts

@@ -0,0 +1,41 @@
+// Define an interface for the cache items with key-value pairs
+interface CacheItem<T> {
+  key: string;
+  value: T;
+}
+
+export class LRUCache<T> {
+  private readonly maxSize: number;
+  private cache: Map<string, CacheItem<T>>;
+
+  constructor(maxSize: number) {
+    this.maxSize = maxSize;
+    this.cache = new Map<string, CacheItem<T>>();
+  }
+
+  set(key: string, value: T): void {
+    if (this.cache.size >= this.maxSize) {
+      const lruKey = this.cache.keys().next().value;
+      this.cache.delete(lruKey);
+    }
+    this.cache.set(key, { key, value });
+  }
+
+  get(key: string): T | undefined {
+    const item = this.cache.get(key);
+    if (item) {
+      this.cache.delete(key);
+      this.cache.set(key, item);
+      return item.value;
+    }
+    return undefined;
+  }
+
+  delete(key: string): void {
+    this.cache.delete(key);
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+}