feat: Add plugin support for node.

Author: kinyoklion

packages/sdk/server-node/__tests__/LDClientNode.plugin.test.ts

@@ -0,0 +1,259 @@
+import { integrations, LDContext, LDLogger } from '@launchdarkly/js-server-sdk-common';
+
+import { LDOptions } from '../src/api/LDOptions';
+import { LDPlugin } from '../src/api/LDPlugin';
+import LDClientNode from '../src/LDClientNode';
+import NodeInfo from '../src/platform/NodeInfo';
+
+// Test for plugin registration
+it('registers plugins and executes hooks during initialization', async () => {
+  const logger: LDLogger = {
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+  };
+
+  const mockHook: integrations.Hook = {
+    getMetadata(): integrations.HookMetadata {
+      return {
+        name: 'test-hook',
+      };
+    },
+    beforeEvaluation: jest.fn(() => ({})),
+    afterEvaluation: jest.fn(() => ({})),
+  };
+
+  const mockPlugin: LDPlugin = {
+    getMetadata: () => ({ name: 'test-plugin' }),
+    register: jest.fn(),
+    getHooks: () => [mockHook],
+  };
+
+  const client = new LDClientNode('test', { offline: true, logger, plugins: [mockPlugin] });
+
+  // Verify the plugin was registered
+  expect(mockPlugin.register).toHaveBeenCalled();
+
+  // Now test that hooks work by calling identify and variation
+  const context: LDContext = { key: 'user-key', kind: 'user' };
+
+  await client.variation('flag-key', context, false);
+
+  expect(mockHook.beforeEvaluation).toHaveBeenCalledWith(
+    {
+      context,
+      defaultValue: false,
+      flagKey: 'flag-key',
+      method: 'LDClient.variation',
+      environmentId: undefined,
+    },
+    {},
+  );
+
+  expect(mockHook.afterEvaluation).toHaveBeenCalled();
+});
+
+// Test for multiple plugins with hooks
+it('registers multiple plugins and executes all hooks', async () => {
+  const logger: LDLogger = {
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+  };
+
+  const mockHook1: integrations.Hook = {
+    getMetadata(): integrations.HookMetadata {
+      return {
+        name: 'test-hook-1',
+      };
+    },
+    beforeEvaluation: jest.fn(() => ({})),
+    afterEvaluation: jest.fn(() => ({})),
+  };
+
+  const mockHook2: integrations.Hook = {
+    getMetadata(): integrations.HookMetadata {
+      return {
+        name: 'test-hook-2',
+      };
+    },
+    beforeEvaluation: jest.fn(() => ({})),
+    afterEvaluation: jest.fn(() => ({})),
+  };
+
+  const mockPlugin1: LDPlugin = {
+    getMetadata: () => ({ name: 'test-plugin-1' }),
+    register: jest.fn(),
+    getHooks: () => [mockHook1],
+  };
+
+  const mockPlugin2: LDPlugin = {
+    getMetadata: () => ({ name: 'test-plugin-2' }),
+    register: jest.fn(),
+    getHooks: () => [mockHook2],
+  };
+
+  const client = new LDClientNode('test', {
+    offline: true,
+    logger,
+    plugins: [mockPlugin1, mockPlugin2],
+  });
+
+  // Verify plugins were registered
+  expect(mockPlugin1.register).toHaveBeenCalled();
+  expect(mockPlugin2.register).toHaveBeenCalled();
+
+  // Test that both hooks work
+  const context: LDContext = { key: 'user-key', kind: 'user' };
+  await client.variation('flag-key', context, false);
+
+  expect(mockHook1.beforeEvaluation).toHaveBeenCalled();
+  expect(mockHook1.afterEvaluation).toHaveBeenCalled();
+  expect(mockHook2.beforeEvaluation).toHaveBeenCalled();
+  expect(mockHook2.afterEvaluation).toHaveBeenCalled();
+});
+
+it('passes correct environmentMetadata to plugin getHooks and register functions', async () => {
+  const logger: LDLogger = {
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+  };
+
+  const mockHook: integrations.Hook = {
+    getMetadata(): integrations.HookMetadata {
+      return {
+        name: 'test-hook',
+      };
+    },
+    beforeEvaluation: jest.fn(() => ({})),
+    afterEvaluation: jest.fn(() => ({})),
+  };
+
+  const mockPlugin: LDPlugin = {
+    getMetadata: () => ({ name: 'test-plugin' }),
+    register: jest.fn(),
+    getHooks: jest.fn(() => [mockHook]),
+  };
+
+  const options: LDOptions = {
+    wrapperName: 'test-wrapper',
+    wrapperVersion: '2.0.0',
+    application: {
+      id: 'test-app',
+      name: 'TestApp',
+      version: '3.0.0',
+      versionName: '3',
+    },
+    offline: true,
+    logger,
+    plugins: [mockPlugin],
+  };
+
+  // eslint-disable-next-line no-new
+  new LDClientNode('test', options);
+  const platformInfo = new NodeInfo(options);
+  const sdkData = platformInfo.sdkData();
+  expect(sdkData.name).toBeDefined();
+  expect(sdkData.version).toBeDefined();
+
+  // Verify getHooks was called with correct environmentMetadata
+  expect(mockPlugin.getHooks).toHaveBeenCalledWith({
+    sdk: {
+      name: sdkData.userAgentBase,
+      version: sdkData.version,
+      wrapperName: options.wrapperName,
+      wrapperVersion: options.wrapperVersion,
+    },
+    application: {
+      id: options.application?.id,
+      name: options.application?.name,
+      version: options.application?.version,
+      versionName: options.application?.versionName,
+    },
+    sdkKey: 'test',
+  });
+
+  // Verify register was called with correct environmentMetadata
+  expect(mockPlugin.register).toHaveBeenCalledWith(
+    expect.any(Object), // client
+    {
+      sdk: {
+        name: sdkData.userAgentBase,
+        version: sdkData.version,
+        wrapperName: options.wrapperName,
+        wrapperVersion: options.wrapperVersion,
+      },
+      application: {
+        id: options.application?.id,
+        version: options.application?.version,
+        name: options.application?.name,
+        versionName: options.application?.versionName,
+      },
+      sdkKey: 'test',
+    },
+  );
+});
+
+it('passes correct environmentMetadata without optional fields', async () => {
+  const logger: LDLogger = {
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+  };
+
+  const mockHook: integrations.Hook = {
+    getMetadata(): integrations.HookMetadata {
+      return {
+        name: 'test-hook',
+      };
+    },
+    beforeEvaluation: jest.fn(() => ({})),
+    afterEvaluation: jest.fn(() => ({})),
+  };
+
+  const mockPlugin: LDPlugin = {
+    getMetadata: () => ({ name: 'test-plugin' }),
+    register: jest.fn(),
+    getHooks: jest.fn(() => [mockHook]),
+  };
+
+  const options: LDOptions = {
+    offline: true,
+    logger,
+    plugins: [mockPlugin],
+  };
+
+  // eslint-disable-next-line no-new
+  new LDClientNode('test', options);
+
+  const platformInfo = new NodeInfo(options);
+  const sdkData = platformInfo.sdkData();
+  expect(sdkData.name).toBeDefined();
+  expect(sdkData.version).toBeDefined();
+
+  // Verify getHooks was called with correct environmentMetadata
+  expect(mockPlugin.getHooks).toHaveBeenCalledWith({
+    sdk: {
+      name: sdkData.userAgentBase,
+      version: sdkData.version,
+    },
+    sdkKey: 'test',
+  });
+
+  // Verify register was called with correct environmentMetadata
+  expect(mockPlugin.register).toHaveBeenCalledWith(
+    expect.any(Object), // client
+    {
+      sdk: {
+        name: sdkData.userAgentBase,
+        version: sdkData.version,
+      },
+      sdkKey: 'test',
+    },
+  );
+});

packages/sdk/server-node/src/LDClientNode.ts

@@ -4,24 +4,53 @@ import { format } from 'util';
 
 import {
   BasicLogger,
+  internal,
   LDClientImpl,
-  LDOptions,
+  LDPluginEnvironmentMetadata,
+  Platform,
   SafeLogger,
+  TypeValidators,
 } from '@launchdarkly/js-server-sdk-common';
+import { LDClientCallbacks } from '@launchdarkly/js-server-sdk-common/dist/LDClientImpl';
+import { ServerInternalOptions } from '@launchdarkly/js-server-sdk-common/dist/options/ServerInternalOptions';
 
-import { BigSegmentStoreStatusProvider } from './api';
+import { BigSegmentStoreStatusProvider, LDClient } from './api';
+import { LDOptions } from './api/LDOptions';
+import { LDPlugin } from './api/LDPlugin';
 import BigSegmentStoreStatusProviderNode from './BigSegmentsStoreStatusProviderNode';
 import { Emits } from './Emits';
 import NodePlatform from './platform/NodePlatform';
 
-class ClientEmitter extends EventEmitter {}
-
 /**
- * @ignore
+ * @internal
+ * Extend the base client implementation with an event emitter.
+ *
+ * The LDClientNode implementation must satisfy the LDClient interface,
+ * which is why we extend the base client implementation with an event emitter
+ * and then inherit from that. This adds everything we need to the implementation
+ * to comply with the interface.
+ *
+ * This allows re-use of the `Emits` mixin for this and big segments.
  */
-class LDClientNode extends LDClientImpl {
+class ClientBaseWithEmitter extends LDClientImpl {
   emitter: EventEmitter;
 
+  constructor(
+    sdkKey: string,
+    platform: Platform,
+    options: LDOptions,
+    callbacks: LDClientCallbacks,
+    internalOptions?: ServerInternalOptions,
+  ) {
+    super(sdkKey, platform, options, callbacks, internalOptions);
+    this.emitter = new EventEmitter();
+  }
+}
+
+/**
+ * @ignore
+ */
+class LDClientNode extends Emits(ClientBaseWithEmitter) implements LDClient {
   bigSegmentStoreStatusProvider: BigSegmentStoreStatusProvider;
 
   constructor(sdkKey: string, options: LDOptions) {
@@ -32,9 +61,19 @@ class LDClientNode extends LDClientImpl {
       formatter: format,
     });
 
-    const emitter = new ClientEmitter();
-
     const logger = options.logger ? new SafeLogger(options.logger, fallbackLogger) : fallbackLogger;
+    const emitter = new EventEmitter();
+
+    const pluginValidator = TypeValidators.createTypeArray('LDPlugin', {});
+    const plugins: LDPlugin[] = [];
+    if (options.plugins) {
+      if (pluginValidator.is(options.plugins)) {
+        plugins.push(...options.plugins);
+      } else {
+        logger.warn('Could not validate plugins.');
+      }
+    }
+
     super(
       sdkKey,
       new NodePlatform({ ...options, logger }),
@@ -65,13 +104,21 @@ class LDClientNode extends LDClientImpl {
                 name === 'update' || (typeof name === 'string' && name.startsWith('update:')),
             ),
       },
+      {
+        getImplementationHooks: (environmentMetadata: LDPluginEnvironmentMetadata) =>
+          internal.safeGetHooks(logger, environmentMetadata, plugins),
+      },
     );
+    // TODO: It would be good if we could re-arrange this emitter situation so we don't have to
+    // create two emitters. It isn't harmful, but it isn't ideal.
     this.emitter = emitter;
 
     this.bigSegmentStoreStatusProvider = new BigSegmentStoreStatusProviderNode(
       this.bigSegmentStatusProviderInternal,
     ) as BigSegmentStoreStatusProvider;
+
+    internal.safeRegisterPlugins(logger, this.environmentMetadata, this, plugins);
   }
 }
 
-export default Emits(LDClientNode);
+export default LDClientNode;

packages/sdk/server-node/src/api/LDOptions.ts

@@ -0,0 +1,19 @@
+import { LDOptions as LDOptionsCommon } from '@launchdarkly/js-server-sdk-common';
+
+import { LDPlugin } from './LDPlugin';
+
+/**
+ * LaunchDarkly initialization options.
+ *
+ * @privateRemarks
+ * The plugins implementation is SDK specific, so these options exist to extend the base options
+ * with the node specific plugin configuration.
+ */
+export interface LDOptions extends LDOptionsCommon {
+  /**
+   * A list of plugins to be used with the SDK.
+   *
+   * Plugin support is currently experimental and subject to change.
+   */
+  plugins?: LDPlugin[];
+}

packages/sdk/server-node/src/api/LDPlugin.ts

@@ -0,0 +1,12 @@
+import { integrations, LDPluginBase } from '@launchdarkly/js-server-sdk-common';
+
+import { LDClient } from './LDClient';
+
+/**
+ * Interface for plugins to the LaunchDarkly SDK.
+ *
+ * @privateRemarks
+ * The plugin interface must be in the leaf-sdk implementations to ensure it uses the correct LDClient intrface.
+ * The LDClient in the shared server code doesn't match the LDClient interface of the individual SDKs.
+ */
+export interface LDPlugin extends LDPluginBase<LDClient, integrations.Hook> {}