feat!: Implement context support. (#16)

kinyoklion · keelerm84 · web-flow · commit 0f2b7a665a06 · 2023-02-15T10:34:54.000-08:00
build(deps): Update the node-server-sdk to version 7.x.

Co-authored-by: Matthew M. Keeler &lt;keelerm84@gmail.com&gt;
diff --git a/README.md b/README.md
@@ -44,15 +44,91 @@ Refer to the [SDK reference guide](https://docs.launchdarkly.com/sdk/server-side
 
 ## OpenFeature Specific Considerations
 
-When evaluating an `LDUser` with the LaunchDarkly Node SDK a string `key` attribute would normally be required. When using OpenFeature the `targetingKey` attribute should be used instead of `key`. If a `key` attribute is provided in the `EvaluationContext`, then it will be discarded in favor of `targetingKey`. If a `targetingKey` is not provided, or if the `EvaluationContext` is omitted entirely, then the `defaultValue` will be returned from OpenFeature evaluation methods.
+LaunchDarkly evaluates contexts, and it can either evaluate a single-context, or a multi-context. When using OpenFeature both single and multi-contexts must be encoded into a single `EvaluationContext`. This is accomplished by looking for an attribute named `kind` in the `EvaluationContext`.
 
-Other fields normally included in an `LDUser` may be added to the `EvaluationContext`. Any `custom` attributes can
-be added to the top level of the evaluation context, and they will operate as if they were `custom` attributes on an `LDUser`. Attributes which are typically top level on an `LDUser` should be of the same types that are specified for
-an `LDUser` or they will not operate as intended.
+There are 4 different scenarios related to the `kind`:
+1. There is no `kind` attribute. In this case the provider will treat the context as a single context containing a "user" kind.
+2. There is a `kind` attribute, and the value of that attribute is "multi". This will indicate to the provider that the context is a multi-context.
+3. There is a `kind` attribute, and the value of that attribute is a string other than "multi". This will indicate to the provider a single context of the kind specified.
+4. There is a `kind` attribute, and the attribute is not a string. In this case the value of the attribute will be discarded, and the context will be treated as a "user". An error message will be logged.
 
-If a top level `custom` attribute is defined on the `EvaluationContext`, then that will be a `custom` attribute inside `custom` for an `LDUser`.
+The `kind` attribute should be a string containing only contain ASCII letters, numbers, `.`, `_` or `-`.
 
-If a custom attribute is provided, whose value is an object, then that attribute will be discarded.
+The OpenFeature specification allows for an optional targeting key, but LaunchDarkly requires a key for evaluation. A targeting key must be specified for each context being evaluated. It may be specified using either `targetingKey`, as it is in the OpenFeature specification, or `key`, which is the typical LaunchDarkly identifier for the targeting key. If a `targetingKey` and a `key` are specified, then the `targetingKey` will take precedence.
+
+There are several other attributes which have special functionality within a single or multi-context. 
+- A key of `privateAttributes`. Must be an array of string values. [Equivalent to '_meta.privateAttributes' in the SDK.](https://launchdarkly.github.io/node-server-sdk/interfaces/_launchdarkly_node_server_sdk_.LDContextMeta.html#privateAttributes)
+- A key of `anonymous`. Must be a boolean value.  [Equivalent to 'anonymous' in the SDK.](https://launchdarkly.github.io/node-server-sdk/interfaces/_launchdarkly_node_server_sdk_.LDSingleKindContext.html#anonymous)
+- A key of `name`. Must be a string. [Equivalent to 'name' in the SDK.](https://launchdarkly.github.io/node-server-sdk/interfaces/_launchdarkly_node_server_sdk_.LDSingleKindContext.html#name)
+
+### Examples
+
+#### A single user context
+
+```typescript
+const evaluationContext = {
+    targetingKey: 'my-user-key'
+};
+```
+
+#### A single context of kind "organization"
+
+```typescript
+const evaluationContext = {
+    kind: 'organization',
+    targetingKey: 'my-org-key'
+};
+```
+
+#### A multi-context containing a "user" and an "organization"
+
+```typescript
+
+const evaluationContext = {
+    kind: 'multi',
+    organization: {
+        targetingKey: 'my-org-key',
+        myCustomAttribute: 'myAttributeValue'
+    },
+    user: {
+        targetingKey: 'my-user-key'
+    }
+};
+```
+
+#### Setting private attributes in a single context
+
+```typescript
+const evaluationContext = {
+    kind: 'organization',
+    name: 'the-org-name',
+    targetingKey: 'my-org-key',
+    myCustomAttribute: 'myCustomValue',
+    privateAttributes: ['myCustomAttribute']
+};
+```
+
+#### Setting private attributes in a multi-context
+
+```typescript
+const evaluationContext = {
+    kind: 'multi',
+    organization: {
+        targetingKey: 'my-org-key',
+        name: 'the-org-name',
+        // This will ONLY apply to the "organization" attributes.
+        privateAttributes: ['myCustomAttribute'],
+        // This attribute will be private.
+        myCustomAttribute: 'myAttributeValue'
+    },
+    user: {
+        targetingKey: 'my-user-key',
+        anonymous: true,
+        // This attribute will not be private.
+        myCustomAttribute: 'myAttributeValue'
+    }
+};
+```
 
 ## Learn more
 
diff --git a/__tests__/translateContext.test.ts b/__tests__/translateContext.test.ts
@@ -3,12 +3,24 @@ import TestLogger from './TestLogger';
 
 it('Uses the targetingKey as the user key', () => {
   const logger = new TestLogger();
-  expect(translateContext(logger, { targetingKey: 'the-key' })).toEqual({ key: 'the-key' });
+  expect(translateContext(logger, { targetingKey: 'the-key' })).toEqual({ key: 'the-key', kind: 'user' });
   expect(logger.logs.length).toEqual(0);
 });
 
+it('gives targetingKey precedence over key', () => {
+  const logger = new TestLogger();
+  expect(translateContext(
+    logger,
+    { targetingKey: 'target-key', key: 'key-key' },
+  )).toEqual({
+    key: 'target-key',
+    kind: 'user',
+  });
+  // Should log a warning about both being defined.
+  expect(logger.logs.length).toEqual(1);
+});
+
 describe.each([
-  ['secondary', 'value1'],
   ['name', 'value2'],
   ['firstName', 'value3'],
   ['lastName', 'value4'],
@@ -26,20 +38,26 @@ describe.each([
     )).toEqual({
       key: 'the-key',
       [key]: value,
+      kind: 'user',
     });
     expect(logger.logs.length).toEqual(0);
   });
 });
 
+it.each(['key', 'targetingKey'])('handles key or targetingKey', (key) => {
+  const logger = new TestLogger();
+  expect(translateContext(
+    logger,
+    { [key]: 'the-key' },
+  )).toEqual({
+    key: 'the-key',
+    kind: 'user',
+  });
+  expect(logger.logs.length).toEqual(0);
+});
+
 describe.each([
-  ['secondary', false],
   ['name', 17],
-  ['firstName', new Date()],
-  ['lastName', true],
-  ['email', () => { }],
-  ['avatar', {}],
-  ['ip', []],
-  ['country', 42],
   ['anonymous', 'value'],
 ])('given incorrect built-in attributes', (key, value) => {
   it('the bad key is omitted', () => {
@@ -49,6 +67,7 @@ describe.each([
       { targetingKey: 'the-key', [key]: value },
     )).toEqual({
       key: 'the-key',
+      kind: 'user',
     });
     expect(logger.logs[0]).toMatch(new RegExp(`The attribute '${key}' must be of type.*`));
   });
@@ -58,21 +77,12 @@ it('accepts custom attributes', () => {
   const logger = new TestLogger();
   expect(translateContext(logger, { targetingKey: 'the-key', someAttr: 'someValue' })).toEqual({
     key: 'the-key',
-    custom: {
-      someAttr: 'someValue',
-    },
+    kind: 'user',
+    someAttr: 'someValue',
   });
   expect(logger.logs.length).toEqual(0);
 });
 
-it('ignores custom attributes that are objects', () => {
-  const logger = new TestLogger();
-  expect(translateContext(logger, { targetingKey: 'the-key', someAttr: {} })).toEqual({
-    key: 'the-key',
-  });
-  expect(logger.logs[0]).toEqual("The attribute 'someAttr' is of an unsupported type 'object'");
-});
-
 it('accepts string/boolean/number arrays', () => {
   const logger = new TestLogger();
   expect(translateContext(logger, {
@@ -82,40 +92,137 @@ it('accepts string/boolean/number arrays', () => {
     booleans: [true, false],
   })).toEqual({
     key: 'the-key',
-    custom: {
-      strings: ['a', 'b', 'c'],
-      numbers: [1, 2, 3],
-      booleans: [true, false],
-    },
+    kind: 'user',
+    strings: ['a', 'b', 'c'],
+    numbers: [1, 2, 3],
+    booleans: [true, false],
   });
   expect(logger.logs.length).toEqual(0);
 });
 
-it('discards invalid array types', () => {
+it('converts date to ISO strings', () => {
+  const date = new Date();
   const logger = new TestLogger();
   expect(translateContext(
     logger,
-    {
-      targetingKey: 'the-key',
-      dates: [new Date()],
-    },
+    { targetingKey: 'the-key', date },
   )).toEqual({
     key: 'the-key',
+    kind: 'user',
+    date: date.toISOString(),
   });
-  expect(logger.logs[0]).toEqual("The attribute 'dates' is an unsupported array type.");
+  expect(logger.logs.length).toEqual(0);
 });
 
-it('converts date to ISO strings', () => {
-  const date = new Date();
+it('can convert a single kind context', () => {
+  const evaluationContext = {
+    kind: 'organization',
+    targetingKey: 'my-org-key',
+  };
+
+  const expectedContext = {
+    kind: 'organization',
+    key: 'my-org-key',
+  };
+
   const logger = new TestLogger();
-  expect(translateContext(
-    logger,
-    { targetingKey: 'the-key', date },
-  )).toEqual({
-    key: 'the-key',
-    custom: {
-      date: date.toISOString(),
+  expect(translateContext(logger, evaluationContext)).toEqual(expectedContext);
+  expect(logger.logs.length).toEqual(0);
+});
+
+it('can convert a multi-context', () => {
+  const evaluationContext = {
+    kind: 'multi',
+    organization: {
+      targetingKey: 'my-org-key',
+      myCustomAttribute: 'myAttributeValue',
     },
-  });
+    user: {
+      targetingKey: 'my-user-key',
+    },
+  };
+
+  const expectedContext = {
+    kind: 'multi',
+    organization: {
+      key: 'my-org-key',
+      myCustomAttribute: 'myAttributeValue',
+    },
+    user: {
+      key: 'my-user-key',
+    },
+  };
+
+  const logger = new TestLogger();
+  expect(translateContext(logger, evaluationContext)).toEqual(expectedContext);
+  expect(logger.logs.length).toEqual(0);
+});
+
+it('can handle privateAttributes in a single context', () => {
+  const evaluationContext = {
+    kind: 'organization',
+    name: 'the-org-name',
+    targetingKey: 'my-org-key',
+    myCustomAttribute: 'myCustomValue',
+    privateAttributes: ['myCustomAttribute'],
+  };
+
+  const expectedContext = {
+    kind: 'organization',
+    name: 'the-org-name',
+    key: 'my-org-key',
+    myCustomAttribute: 'myCustomValue',
+    _meta: {
+      privateAttributes: ['myCustomAttribute'],
+    },
+  };
+
+  const logger = new TestLogger();
+  expect(translateContext(logger, evaluationContext)).toEqual(expectedContext);
+  expect(logger.logs.length).toEqual(0);
+});
+
+it('detects a cycle and logs an error', () => {
+  const a = {
+    b: { c: {} },
+  };
+
+  a.b.c = a;
+  const evaluationContext = {
+    key: 'a-key',
+    kind: 'singularity',
+    a,
+  };
+
+  const expectedContext = {
+    key: 'a-key',
+    kind: 'singularity',
+    a: { b: {} },
+  };
+
+  const logger = new TestLogger();
+  expect(translateContext(logger, evaluationContext)).toEqual(expectedContext);
+  expect(logger.logs.length).toEqual(1);
+});
+
+it('allows references in different branches', () => {
+  const a = { test: 'test' };
+
+  const evaluationContext = {
+    key: 'a-key',
+    kind: 'singularity',
+    b: { a },
+    c: { a },
+  };
+
+  const expectedContext = {
+    key: 'a-key',
+    kind: 'singularity',
+    b: { a: { test: 'test' } },
+    c: { a: { test: 'test' } },
+  };
+
+  const logger = new TestLogger();
+  expect(translateContext(logger, evaluationContext)).toEqual(expectedContext);
   expect(logger.logs.length).toEqual(0);
 });
diff --git a/package.json b/package.json
@@ -21,7 +21,7 @@
   "license": "Apache-2.0",
   "peerDependencies": {
     "@openfeature/js-sdk": "^1.0.0",
-    "launchdarkly-node-server-sdk": "6.x"
+    "launchdarkly-node-server-sdk": "7.x"
   },
   "devDependencies": {
     "@openfeature/js-sdk": "^1.0.0",
@@ -34,7 +34,7 @@
     "eslint-plugin-import": "^2.26.0",
     "jest": "^27.5.1",
     "jest-junit": "^14.0.1",
-    "launchdarkly-node-server-sdk": "6.x",
+    "launchdarkly-node-server-sdk": "7.x",
     "ts-jest": "^27.1.4",
     "typescript": "^4.7.4"
   }
diff --git a/src/translateContext.ts b/src/translateContext.ts
