feat: Add experimental plugin support. (#225)

The flutter SDK is arranged into a common-client package that is
independent of the flutter package to allow for eventually supporting
non-flutter usages such as dart command line applications. This means,
similar to JS, that plugins are a concern of the leaf-node of the SDK
because plugins depend on types that are not common to the leaf nodes.

A plugin for the flutter client SDK is registered with an instance of
the flutter client SDK and not an instance of the common client SDK. (In
flutter the common client is actually composed into the leaf-node and
not a base class, so this difference is even more meaningful.)

The work-around to this is to make common types for all the meta-data,
and then a generic base class to be extended by the leaf-node
implementations. That extended version makes the client concrete instead
of generic. The base operations that need to be done on plugins, such as
getting a list of hooks from them, and registering them, are handled via
generic methods in the common client package.

```mermaid
  graph TD
      subgraph "common_client package"
          A[PluginBase<TClient>]
      end

      subgraph "flutter_client_sdk package"
          B[Plugin]
          B --> |extends| A
      end

      subgraph "User Application"
          C[MyCustomPlugin]
          C --> |extends| B
      end

      A --> |Provides| D[register method<br/>hooks property<br/>abstract metadata property]
      B --> |Specializes for| E[LDClient type<br/>Flutter SDK context]
      C --> |Implements| F[Custom behavior via override of register<br/>Custom hooks via override of hooks property<br/>Concrete metadata property]

```

Author: kinyoklion

packages/common_client/lib/launchdarkly_common_client.dart

@@ -54,3 +54,17 @@ export 'src/hooks/hook.dart'
         EvaluationSeriesContext,
         IdentifySeriesContext,
         TrackSeriesContext;
+
+export 'src/hooks/operations.dart' show combineHooks;
+
+export 'src/plugins/plugin.dart'
+    show
+        PluginBase,
+        PluginCredentialInfo,
+        PluginEnvironmentMetadata,
+        PluginMetadata,
+        PluginSdkMetadata;
+
+export 'src/plugins/operations.dart' show safeGetHooks, safeRegisterPlugins;
+
+export 'src/config/defaults/credential_type.dart' show CredentialType;

packages/common_client/lib/src/config/defaults/credential_type.dart

@@ -1,4 +1,9 @@
+/// Represents the credential type used by the SDK. The credential type is
+/// determined by the platform the SDK is running on.
 enum CredentialType {
+  /// The SDK is using a mobile key credential.
   mobileKey,
+
+  /// The SDK is using a client-side ID.
   clientSideId,
 }

packages/common_client/lib/src/hooks/operations.dart

@@ -0,0 +1,14 @@
+import 'hook.dart';
+
+List<Hook>? combineHooks(List<Hook>? baseHooks, List<Hook>? extendedHooks) {
+  if (baseHooks == null) {
+    return extendedHooks;
+  }
+  if (extendedHooks == null) {
+    return baseHooks;
+  }
+  List<Hook> combined = [];
+  combined.addAll(baseHooks);
+  combined.addAll(extendedHooks);
+  return combined;
+}

packages/common_client/lib/src/ld_common_client.dart

@@ -850,4 +850,8 @@ final class LDCommonClient {
 
   /// Check if the initialization process is complete.
   bool get initialized => _startCompleter?.isCompleted ?? false;
+
+  /// Get the type of credential the SDK uses.
+  CredentialType get credentialType =>
+      DefaultConfig.credentialConfig.credentialType;
 }

packages/common_client/lib/src/ld_common_config.dart

@@ -1,3 +1,4 @@
+import 'dart:collection';
 import 'dart:math';
 
 import 'package:launchdarkly_dart_common/launchdarkly_dart_common.dart';
@@ -129,7 +130,7 @@ abstract class LDCommonConfig {
   final List<String> globalPrivateAttributes;
 
   /// An initial list of hooks.
-  final List<Hook>? hooks;
+  final UnmodifiableListView<Hook>? hooks;
 
   LDCommonConfig(this.sdkCredential, this.autoEnvAttributes,
       {this.applicationInfo,
@@ -142,7 +143,7 @@ abstract class LDCommonConfig {
       DataSourceConfig? dataSourceConfig,
       bool? allAttributesPrivate,
       List<String>? globalPrivateAttributes,
-      this.hooks})
+      List<Hook>? hooks})
       : httpProperties = httpProperties ?? HttpProperties(),
         serviceEndpoints =
             serviceEndpoints ?? client_endpoints.ServiceEndpoints(),
@@ -153,7 +154,8 @@ abstract class LDCommonConfig {
         dataSourceConfig = dataSourceConfig ?? DataSourceConfig(),
         allAttributesPrivate =
             allAttributesPrivate ?? DefaultConfig.allAttributesPrivate,
-        globalPrivateAttributes = globalPrivateAttributes ?? [];
+        globalPrivateAttributes = globalPrivateAttributes ?? [],
+        hooks = hooks != null ? UnmodifiableListView(List.from(hooks)) : null;
 }
 
 /// Enable / disable options for Auto Environment Attributes functionality.  When enabled, the SDK will automatically

packages/common_client/lib/src/plugins/operations.dart

@@ -0,0 +1,49 @@
+import 'package:launchdarkly_dart_common/launchdarkly_dart_common.dart'
+    show LDLogger;
+
+import 'plugin.dart';
+import '../hooks/hook.dart';
+
+const _unknownPlugin = 'unknown';
+
+String safeGetPluginName<TClient>(PluginBase<TClient> plugin, LDLogger logger) {
+  try {
+    return plugin.metadata.name;
+  } catch (err) {
+    logger.warn('Exception thrown access the name of a registered plugin.');
+    return _unknownPlugin;
+  }
+}
+
+List<Hook>? safeGetHooks<TClient>(
+    List<PluginBase<TClient>>? plugins, LDLogger logger) {
+  if (plugins == null) return null;
+
+  return plugins
+      .map<List<Hook>>((plugin) {
+        try {
+          return plugin.hooks;
+        } catch (err) {
+          logger.warn(
+              'Exception thrown getting hooks for plugin ${safeGetPluginName(plugin, logger)}. Unable to get hooks for plugin.');
+        }
+        return [];
+      })
+      .expand<Hook>((hooks) => hooks)
+      .toList();
+}
+
+void safeRegisterPlugins<TClient>(
+    TClient client,
+    PluginEnvironmentMetadata metadata,
+    List<PluginBase<TClient>>? plugins,
+    LDLogger logger) {
+  plugins?.forEach((plugin) {
+    try {
+      plugin.register(client, metadata);
+    } catch (err) {
+      logger.warn(
+          'Exception thrown when registering plugin ${safeGetPluginName(plugin, logger)}');
+    }
+  });
+}

packages/common_client/lib/src/plugins/plugin.dart

@@ -0,0 +1,135 @@
+import 'package:launchdarkly_dart_common/launchdarkly_dart_common.dart'
+    show ApplicationInfo;
+
+import '../config/defaults/credential_type.dart';
+import '../hooks/hook.dart' show Hook;
+
+/// Metadata about a plugin implementation.
+///
+/// May be used in logs and analytics to identify the plugin.
+final class PluginMetadata {
+  /// The name of the plugin.
+  final String name;
+
+  const PluginMetadata({required this.name});
+
+  @override
+  String toString() {
+    return 'PluginMetadata{name: $name}';
+  }
+}
+
+/// Metadata about the SDK that is running the plugin.
+final class PluginSdkMetadata {
+  /// The name of the SDK.
+  final String name;
+
+  /// The version of the SDK.
+  final String version;
+
+  /// If this is a wrapper SDK, then this is the name of the wrapper.
+  final String? wrapperName;
+
+  /// If this is a wrapper SDK, then this is the version of the wrapper.
+  final String? wrapperVersion;
+
+  const PluginSdkMetadata(
+      {required this.name,
+      required this.version,
+      this.wrapperName,
+      this.wrapperVersion});
+
+  @override
+  String toString() {
+    return 'PluginSdkMetadata{name: $name, version: $version,'
+        ' wrapperName: $wrapperName, wrapperVersion: $wrapperVersion}';
+  }
+}
+
+/// Information about the credential used to initialize the SDK.
+final class PluginCredentialInfo {
+  /// The type of credential.
+  final CredentialType type;
+
+  /// The value of the credential.
+  final String value;
+
+  const PluginCredentialInfo({required this.type, required this.value});
+
+  @override
+  String toString() {
+    return 'PluginCredentialInfo{type: $type, value: $value}';
+  }
+}
+
+/// Metadata about the environment where the plugin is running.
+final class PluginEnvironmentMetadata {
+  /// Metadata about the SDK that is running the plugin.
+  final PluginSdkMetadata sdk;
+
+  /// Metadata about the application where the LaunchDarkly SDK is running.
+  ///
+  /// Plugins only have access to application info collected during
+  /// configuration. Application information collected by environment reporting
+  /// is not available.
+  ///
+  /// If access to the environment reporting information is required, then it
+  /// is available via the [LDContext] by using hooks.
+  ///
+  /// Only present if any application information is available.
+  final ApplicationInfo? application;
+
+  /// Information about the credential used to initialize the SDK.
+  final PluginCredentialInfo credential;
+
+  PluginEnvironmentMetadata(
+      {required this.sdk, required this.credential, this.application});
+
+  @override
+  String toString() {
+    return 'PluginEnvironmentMetadata{sdk: $sdk, credential: $credential,'
+        ' application: $application}';
+  }
+}
+
+/// Base class from which all plugins must derive.
+///
+/// Implementation note: SDK packages must export a specialized version of this
+/// for their specific TClient type. This class cannot provide a type, because
+/// it would limit the API to methods available in the base client.
+abstract base class PluginBase<TClient> {
+  /// Metadata associated with this plugin.
+  ///
+  /// Plugin implementations must implement this property.
+  /// ```dart
+  /// final _metadata = PluginMetadata(name: 'MyPluginName');
+  ///
+  /// @override
+  /// PluginMetadata get metadata => _metadata;
+  /// ```
+  PluginMetadata get metadata;
+
+  /// Registers the plugin with the SDK. Called once during SDK initialization.
+  ///
+  /// The SDK initialization will typically not have been completed at this
+  /// point, so the plugin should take appropriate actions to ensure the SDK is
+  /// ready before sending track events or evaluating flags. For example the
+  /// plugin could wait for the [Hook.afterIdentify] stage to indicate success
+  /// before tracking any events.
+  ///
+  /// The [client] the plugin is registered with.
+  void register(
+      TClient client, PluginEnvironmentMetadata environmentMetadata) {}
+
+  /// Hooks which are bundled with this plugin.
+  ///
+  /// Implementations should override this method to return their bundled
+  /// hooks.
+  /// ```dart
+  /// @override
+  /// List<Hook> get hooks => [MyBundledHook()];
+  /// ```
+  List<Hook> get hooks => [];
+
+  PluginBase();
+}