feat: Support inline context for custom and migration events (#810)

**Requirements**

- [x] I have added test coverage for new or changed functionality
- [x] I have followed the repository's [pull request submission
guidelines](../blob/main/CONTRIBUTING.md#submitting-pull-requests)
- [x] I have validated my changes against all supported platform
versions

**Describe the solution you've provided**

- Support inlining context for custom events. The logic for this needs
to happen in EventProcessor which is shared between server and client
sdks in js-core. It has been verified with product analytics that this
is ok for the client sdks.
- Support inlining context for migration events. This causes a change in
the public interface for `LDClient.trackMigration` where the
`LDMigrationOpEvent` parameter has been modified. `contextKeys` has been
made optional and deprecated in favor of `context` and all internal uses
of `LDMigrationOpEvent` have been changed to use `context`.

BEGIN_COMMIT_OVERRIDE
feat: Support inline context for custom and migration events
fix: Deprecate LDMigrationOpEvent.contextKeys in favor of
LDMigrationOpEvent.context
END_COMMIT_OVERRIDE

Author: abarker-launchdarkly

contract-tests/index.js

@@ -34,7 +34,7 @@ app.get('/', (req, res) => {
       'event-sampling',
       'strongly-typed',
       'polling-gzip',
-      'inline-context',
+      'inline-context-all',
       'anonymous-redaction',
       'evaluation-hooks',
       'wrapper',

packages/sdk/browser/__tests__/BrowserClient.test.ts

@@ -145,8 +145,9 @@ describe('given a mock platform for a BrowserClient', () => {
       kind: 'custom',
       creationDate: 1726704000000,
       key: 'user-key',
-      contextKeys: {
-        user: 'user-key',
+      context: {
+        key: 'user-key',
+        kind: 'user',
       },
       metricValue: 1,
       url: 'http://browserclientintegration.com',
@@ -178,8 +179,9 @@ describe('given a mock platform for a BrowserClient', () => {
       kind: 'custom',
       creationDate: 1726704000000,
       key: 'user-key',
-      contextKeys: {
-        user: 'user-key',
+      context: {
+        key: 'user-key',
+        kind: 'user',
       },
       metricValue: 1,
       url: 'http://filtered.org',

packages/sdk/browser/contract-tests/entity/src/TestHarnessWebSocket.ts

@@ -38,7 +38,7 @@ export default class TestHarnessWebSocket {
             'service-endpoints',
             'tags',
             'user-type',
-            'inline-context',
+            'inline-context-all',
             'anonymous-redaction',
             'strongly-typed',
             'client-prereq-events',

packages/sdk/browser/contract-tests/suppressions.txt

@@ -4,3 +4,15 @@ streaming/requests/URL path is computed correctly/no environment filter/base URI
 streaming/requests/context properties/single kind minimal/REPORT
 streaming/requests/context properties/single kind with all attributes/REPORT
 streaming/requests/context properties/multi-kind/REPORT
+tags/stream requests/{"applicationId":null,"applicationVersion":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678"}
+tags/stream requests/{"applicationId":null,"applicationVersion":"________________________________________________________________"}
+tags/stream requests/{"applicationId":"","applicationVersion":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678"}
+tags/stream requests/{"applicationId":"","applicationVersion":"________________________________________________________________"}
+tags/stream requests/{"applicationId":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678","applicationVersion":null}
+tags/stream requests/{"applicationId":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678","applicationVersion":""}
+tags/stream requests/{"applicationId":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678","applicationVersion":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678"}
+tags/stream requests/{"applicationId":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678","applicationVersion":"________________________________________________________________"}
+tags/stream requests/{"applicationId":"________________________________________________________________","applicationVersion":null}
+tags/stream requests/{"applicationId":"________________________________________________________________","applicationVersion":""}
+tags/stream requests/{"applicationId":"________________________________________________________________","applicationVersion":"._-abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ012345678"}
+tags/stream requests/{"applicationId":"________________________________________________________________","applicationVersion":"________________________________________________________________"}

packages/shared/common/__tests__/internal/events/EventProcessor.test.ts

@@ -671,9 +671,7 @@ describe('given an event processor', () => {
         key: 'eventkey',
         data: { thing: 'stuff' },
         creationDate: 1000,
-        contextKeys: {
-          user: 'userKey',
-        },
+        context: { ...user, kind: 'user' },
       },
     ]);
   });
@@ -701,9 +699,7 @@ describe('given an event processor', () => {
         key: 'eventkey',
         data: { thing: 'stuff' },
         creationDate: 1000,
-        contextKeys: {
-          user: 'anon-user',
-        },
+        context: { ...anonUser, kind: 'user' },
       },
     ]);
   });
@@ -733,9 +729,7 @@ describe('given an event processor', () => {
         key: 'eventkey',
         data: { thing: 'stuff' },
         creationDate: 1000,
-        contextKeys: {
-          user: 'userKey',
-        },
+        context: { ...user, kind: 'user' },
         metricValue: 1.5,
       },
     ]);

packages/shared/common/src/internal/events/EventProcessor.ts

@@ -32,7 +32,7 @@ interface CustomOutputEvent {
   kind: 'custom';
   creationDate: number;
   key: string;
-  contextKeys: Record<string, string>;
+  context: FilteredContext;
   data?: any;
   metricValue?: number;
   samplingRatio?: number;
@@ -83,9 +83,11 @@ interface PageviewOutputEvent {
  */
 type DiagnosticEvent = any;
 
-interface MigrationOutputEvent extends Omit<InputMigrationEvent, 'samplingRatio'> {
+interface MigrationOutputEvent extends Omit<InputMigrationEvent, 'samplingRatio' | 'context'> {
   // Make the sampling ratio optional so we can omit it when it is one.
   samplingRatio?: number;
+  // Context is optional because contextKeys is supported for backwards compatbility and may be provided instead of context.
+  context?: FilteredContext;
 }
 
 type OutputEvent =
@@ -236,6 +238,7 @@ export default class EventProcessor implements LDEventProcessor {
       if (shouldSample(inputEvent.samplingRatio)) {
         const migrationEvent: MigrationOutputEvent = {
           ...inputEvent,
+          context: inputEvent.context ? this._contextFilter.filter(inputEvent.context) : undefined,
         };
         if (migrationEvent.samplingRatio === 1) {
           delete migrationEvent.samplingRatio;
@@ -331,7 +334,7 @@ export default class EventProcessor implements LDEventProcessor {
           kind: 'custom',
           creationDate: event.creationDate,
           key: event.key,
-          contextKeys: event.context.kindsAndKeys,
+          context: this._contextFilter.filter(event.context),
         };
 
         if (event.samplingRatio !== 1) {

packages/shared/common/src/internal/events/InputMigrationEvent.ts

@@ -2,12 +2,17 @@
 // shared implementation contains minimal typing. If/When migration events are
 // to be supported by client-side SDKs the appropriate types would be moved
 // to the common implementation.
+import Context from '../../Context';
 
 export default interface InputMigrationEvent {
   kind: 'migration_op';
   operation: string;
   creationDate: number;
-  contextKeys: Record<string, string>;
+  /**
+   * @deprecated Use 'context' instead.
+   */
+  contextKeys?: Record<string, string>;
+  context?: Context;
   evaluation: any;
   measurements: any[];
   samplingRatio: number;

packages/shared/sdk-server/__tests__/MigrationOpEventConversion.test.ts

@@ -0,0 +1,86 @@
+import { LDContext, LDMigrationOpEvent, LDMigrationStage } from '../src';
+import migrationOpEventToInputEvent from '../src/MigrationOpEventConversion';
+
+const baseEvent: LDMigrationOpEvent = {
+  kind: 'migration_op',
+  operation: 'read',
+  creationDate: new Date().getTime(),
+  evaluation: {
+    default: LDMigrationStage.Off,
+    key: 'flag',
+    reason: { kind: 'FALLTHROUGH' },
+    value: LDMigrationStage.Off,
+  },
+  measurements: [],
+  samplingRatio: 1,
+};
+
+it('handles event without either context or contextKeys', () => {
+  expect(migrationOpEventToInputEvent(baseEvent)).toBeUndefined();
+});
+
+it('handles event with only context', () => {
+  const outEvent = migrationOpEventToInputEvent({
+    ...baseEvent,
+    context: { key: 'user-key' },
+  });
+  expect(outEvent).toBeDefined();
+  expect(outEvent?.context?.key()).toEqual('user-key');
+  expect(outEvent?.context?.kind).toEqual('user');
+  expect(outEvent?.contextKeys).toBeUndefined();
+});
+
+it('handles event with only contextKeys', () => {
+  const outEvent = migrationOpEventToInputEvent({
+    ...baseEvent,
+    contextKeys: { user: 'bob' },
+  });
+  expect(outEvent).toBeDefined();
+  expect(outEvent?.context).toBeUndefined();
+  expect(outEvent?.contextKeys).toEqual({ user: 'bob' });
+});
+
+it('handles invalid context', () => {
+  const outEvent = migrationOpEventToInputEvent({
+    ...baseEvent,
+    context: {} as LDContext,
+  });
+  expect(outEvent).toBeUndefined();
+});
+
+it('handles invalid context even if contextKeys is provided', () => {
+  const outEvent = migrationOpEventToInputEvent({
+    ...baseEvent,
+    context: {} as LDContext,
+    contextKeys: { user: 'bob' },
+  });
+  expect(outEvent).toBeUndefined();
+});
+
+it('handles invalid key in contextKeys', () => {
+  const outEvent = migrationOpEventToInputEvent({
+    ...baseEvent,
+    contextKeys: { kind: 'user' },
+  });
+  expect(outEvent).toBeUndefined();
+});
+
+it('handles invalid value in contextKeys', () => {
+  const outEvent = migrationOpEventToInputEvent({
+    ...baseEvent,
+    contextKeys: { user: '' },
+  });
+  expect(outEvent).toBeUndefined();
+});
+
+it('uses context if both context and contextKeys are provided', () => {
+  const outEvent = migrationOpEventToInputEvent({
+    ...baseEvent,
+    context: { key: 'user-key' },
+    contextKeys: { user: 'bob' },
+  });
+  expect(outEvent).toBeDefined();
+  expect(outEvent?.context?.key()).toEqual('user-key');
+  expect(outEvent?.context?.kind).toEqual('user');
+  expect(outEvent?.contextKeys).toBeUndefined();
+});