FlagBuffer class and interface, add to scope._contexts. Remove old flag field and methods

Author: aliu39

packages/core/src/scope.ts

@@ -11,7 +11,6 @@ import type {
   EventProcessor,
   Extra,
   Extras,
-  FeatureFlag,
   Primitive,
   PropagationContext,
   RequestSession,
@@ -23,7 +22,6 @@ import type {
   User,
 } from '@sentry/types';
 import {
-  LRUMap,
   dateTimestampInSeconds,
   generatePropagationContext,
   isPlainObject,
@@ -105,12 +103,6 @@ class ScopeClass implements ScopeInterface {
   /** Contains the last event id of a captured event.  */
   protected _lastEventId?: string;
 
-  /** LRU cache of flags last evaluated by a feature flag provider. Used by FF integrations. */
-  protected _flagBuffer: LRUMap<FeatureFlag['flag'], FeatureFlag['result']>;
-
-  /** Max size of the flagBuffer */
-  protected _flagBufferSize: number; // TODO: make const?
-
   // NOTE: Any field which gets added here should get added not only to the constructor but also to the `clone` method.
 
   public constructor() {
@@ -125,9 +117,6 @@ class ScopeClass implements ScopeInterface {
     this._contexts = {};
     this._sdkProcessingMetadata = {};
     this._propagationContext = generatePropagationContext();
-
-    this._flagBufferSize = 100;
-    this._flagBuffer = new LRUMap<FeatureFlag['flag'], FeatureFlag['result']>(this._flagBufferSize);
   }
 
   /**
@@ -516,24 +505,6 @@ class ScopeClass implements ScopeInterface {
     return this._propagationContext;
   }
 
-  /**
-   * @inheritDoc
-   */
-  public getFlags(): FeatureFlag[] {
-    const flags: FeatureFlag[] = [];
-    this._flagBuffer.keys().forEach(key => {
-      flags.push({ flag: key, result: this._flagBuffer.get(key) as boolean });
-    });
-    return flags;
-  }
-
-  /**
-   * @inheritDoc
-   */
-  public insertFlag(name: string, value: boolean): void {
-    this._flagBuffer.set(name, value);
-  }
-
   /**
    * @inheritDoc
    */

packages/launchdarkly/src/core/integration.ts

@@ -45,10 +45,11 @@ export const launchDarklyIntegration = ((_options?: LaunchDarklyOptions) => {
 export class SentryInspector implements LDInspectionFlagUsedHandler {
   public name = 'sentry-flag-auditor';
 
-  public synchronous = true; // TODO: T or F?
-
   public type = 'flag-used' as const;
 
+  // We don't want the handler to impact the performance of the user's flag evaluations.
+  public synchronous = false;
+
   /**
    * TODO: docstring
    */

packages/types/src/context.ts

@@ -1,5 +1,6 @@
 import type { Primitive } from './misc';
 import type { SpanOrigin } from './span';
+import type { FlagBufferInterface } from './flags'
 
 export type Context = Record<string, unknown>;
 
@@ -13,6 +14,7 @@ export interface Contexts extends Record<string, Context | undefined> {
   cloud_resource?: CloudResourceContext;
   state?: StateContext;
   profile?: ProfileContext;
+  flags?: FeatureFlagContext;
 }
 
 export interface StateContext extends Record<string, unknown> {
@@ -124,3 +126,7 @@ export interface MissingInstrumentationContext extends Record<string, unknown> {
   package: string;
   ['javascript.is_cjs']?: boolean;
 }
+
+export interface FeatureFlagContext extends Record<string, unknown> {
+  flag_buffer: FlagBufferInterface;
+}

packages/types/src/flags.ts

@@ -1,2 +1,35 @@
 // Key names match the type used by Sentry frontend.
 export type FeatureFlag = { flag: string; result: boolean };
+
+/**
+ * Ordered LRU cache for storing feature flags in the scope context. The name
+ * of each flag in the buffer is unique, and the output of getAll() is ordered
+ * from oldest to newest.
+ */
+export interface FlagBufferInterface {
+  readonly maxSize: number;
+
+  /**
+   * Returns a deep copy of the current FlagBuffer.
+   */
+  clone(): FlagBufferInterface;
+
+  /**
+   * Returns an ordered array of the flags currently stored in the buffer.
+   * This is in the order of insertion (oldest to newest).
+   */
+  getAll(): readonly FeatureFlag[];
+
+  /**
+   * Add a flag to the buffer. After inserting, the flag is guaranteed to be at
+   * the end of the buffer, with no other flags of the same name in it.
+   *
+   * @param flag
+   */
+  insert(name: string, value: boolean): void;
+
+  /**
+   * Clear the buffer. Returns the number of flags removed.
+   */
+  clear(): number;
+}

packages/types/src/scope.ts

@@ -1,12 +1,10 @@
-
 import type { Attachment } from './attachment';
 import type { Breadcrumb } from './breadcrumb';
 import type { Client } from './client';
 import type { Context, Contexts } from './context';
 import type { Event, EventHint } from './event';
 import type { EventProcessor } from './eventprocessor';
 import type { Extra, Extras } from './extra';
-import type { FeatureFlag } from './flags';
 import type { Primitive } from './misc';
 import type { RequestSession, Session } from './session';
 import type { SeverityLevel } from './severity';
@@ -233,17 +231,6 @@ export interface Scope {
    */
   getPropagationContext(): PropagationContext;
 
-  /**
-   * Return the list of recently accessed feature flags.
-   */
-  getFlags(): FeatureFlag[];
-
-  /**
-   * When an integration sends data that a flag name and its value have been evaluated,
-   * add it to the list of recently accessed feature flags.
-   */
-  insertFlag(name: string, value: boolean): void;
-
   /**
    * Capture an exception for this scope.
    *

packages/utils/src/flagBuffer.ts

@@ -0,0 +1,72 @@
+import type { FeatureFlag } from '@sentry/types';
+import type { FlagBufferInterface } from '@sentry/types/build/types/flags';
+
+export const DEFAULT_FLAG_BUFFER_SIZE = 100;
+
+/**
+ * Array implementation of types/FlagBufferInterface.
+ *
+ * Ordered LRU cache for storing feature flags in the scope context. The name
+ * of each flag in the buffer is unique, and the output of getAll() is ordered
+ * from oldest to newest.
+ */
+export class FlagBuffer implements FlagBufferInterface {
+  public readonly maxSize: number;
+
+  private readonly _flags: FeatureFlag[];
+
+  public constructor(_maxSize: number = DEFAULT_FLAG_BUFFER_SIZE, _initialFlags: FeatureFlag[] = []) {
+    this.maxSize = _maxSize;
+    if (_initialFlags.length > _maxSize) {
+      throw Error(`_initialFlags param exceeds the maxSize of ${_maxSize}`);
+    }
+    this._flags = _initialFlags;
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public clone(): FlagBuffer {
+    return new FlagBuffer(this.maxSize, this._flags);
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public getAll(): readonly FeatureFlag[] {
+    return [...this._flags]; // shallow copy
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public insert(name: string, value: boolean): void {
+    // Check if the flag is already in the buffer
+    const index = this._flags.findIndex(f => f.flag === name);
+
+    if (index !== -1) {
+      // The flag was found, remove it from its current position - O(n)
+      this._flags.splice(index, 1);
+    }
+
+    if (this._flags.length === this.maxSize) {
+      // If at capacity, pop the earliest flag - O(n)
+      this._flags.shift();
+    }
+
+    // Push the flag to the end - O(1)
+    this._flags.push({
+      flag: name,
+      result: value,
+    });
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public clear(): number {
+    const length = this._flags.length;
+    this._flags.splice(0, length); // O(n)
+    return length;
+  }
+}

packages/utils/src/index.ts

@@ -40,3 +40,4 @@ export * from './buildPolyfills';
 export * from './propagationContext';
 export * from './vercelWaitUntil';
 export * from './version';
+export * from './flagBuffer';