feat: Add experimental plugin support

- Add Plugin interface and metadata classes following plugin specs
- Extend Config class to accept plugins parameter
- Modify LDClient to register plugins and collect their hooks
- Add comprehensive tests for plugin functionality
- Follow existing Ruby SDK patterns and conventions

Co-Authored-By: [email protected] <[email protected]>

Author: devin-ai-integration[bot]

lib/ldclient-rb/config.rb

@@ -45,6 +45,7 @@ class Config
     # @option opts [String] :payload_filter_key See {#payload_filter_key}
     # @option opts [Boolean] :omit_anonymous_contexts See {#omit_anonymous_contexts}
     # @option hooks [Array<Interfaces::Hooks::Hook]
+    # @option plugins [Array<Interfaces::Plugins::Plugin]
     #
     def initialize(opts = {})
       @base_uri = (opts[:base_uri] || Config.default_base_uri).chomp("/")
@@ -79,6 +80,7 @@ def initialize(opts = {})
       @application = LaunchDarkly::Impl::Util.validate_application_info(opts[:application] || {}, @logger)
       @payload_filter_key = LaunchDarkly::Impl::Util.validate_payload_filter_key(opts[:payload_filter_key] , @logger)
       @hooks = (opts[:hooks] || []).keep_if { |hook| hook.is_a? Interfaces::Hooks::Hook }
+      @plugins = (opts[:plugins] || []).keep_if { |plugin| plugin.is_a? Interfaces::Plugins::Plugin }
       @omit_anonymous_contexts = opts.has_key?(:omit_anonymous_contexts) && opts[:omit_anonymous_contexts]
       @data_source_update_sink = nil
       @instance_id = nil
@@ -412,6 +414,14 @@ def diagnostic_opt_out?
     #
     attr_reader :hooks
 
+    #
+    # Initial set of plugins for the client.
+    #
+    # Plugins provide an interface which allows for initialization, access to credentials, and hook registration
+    # in a single interface.
+    #
+    attr_reader :plugins
+
     #
     # Sets whether anonymous contexts should be omitted from index and identify events.
     #

lib/ldclient-rb/interfaces.rb

@@ -970,5 +970,138 @@ def initialize(key, context, default_value, method)
         end
       end
     end
+
+    module Plugins
+      #
+      # Metadata about the SDK.
+      #
+      class SdkMetadata
+        # The id of the SDK (e.g., "ruby-server-sdk")
+        # @return [String]
+        attr_reader :name
+        
+        # The version of the SDK
+        # @return [String]
+        attr_reader :version
+        
+        # The wrapper name if this SDK is a wrapper
+        # @return [String, nil]
+        attr_reader :wrapper_name
+        
+        # The wrapper version if this SDK is a wrapper
+        # @return [String, nil]
+        attr_reader :wrapper_version
+
+        def initialize(name:, version:, wrapper_name: nil, wrapper_version: nil)
+          @name = name
+          @version = version
+          @wrapper_name = wrapper_name
+          @wrapper_version = wrapper_version
+        end
+      end
+
+      #
+      # Metadata about the application using the SDK.
+      #
+      class ApplicationMetadata
+        # The id of the application
+        # @return [String, nil]
+        attr_reader :id
+        
+        # The version of the application
+        # @return [String, nil]
+        attr_reader :version
+
+        def initialize(id: nil, version: nil)
+          @id = id
+          @version = version
+        end
+      end
+
+      #
+      # Metadata about the environment in which the SDK is running.
+      #
+      class EnvironmentMetadata
+        # Information about the SDK
+        # @return [SdkMetadata]
+        attr_reader :sdk
+        
+        # Information about the application
+        # @return [ApplicationMetadata, nil]
+        attr_reader :application
+        
+        # The SDK key used to initialize the SDK
+        # @return [String, nil]
+        attr_reader :sdk_key
+
+        def initialize(sdk:, application: nil, sdk_key: nil)
+          @sdk = sdk
+          @application = application
+          @sdk_key = sdk_key
+        end
+      end
+
+      #
+      # Metadata about a plugin implementation.
+      #
+      class PluginMetadata
+        # A name representing the plugin instance
+        # @return [String]
+        attr_reader :name
+
+        def initialize(name)
+          @name = name
+        end
+      end
+
+      #
+      # Mixin for extending SDK functionality via plugins.
+      #
+      # All provided plugin implementations **MUST** include this mixin. Plugins without this mixin will be ignored.
+      #
+      # This mixin includes default implementations for optional methods. This allows LaunchDarkly to expand the list
+      # of plugin methods without breaking customer integrations.
+      #
+      # Plugins provide an interface which allows for initialization, access to credentials, and hook registration
+      # in a single interface.
+      #
+      module Plugin
+        #
+        # Get metadata about the plugin implementation.
+        #
+        # @return [PluginMetadata]
+        #
+        def metadata
+          PluginMetadata.new('UNDEFINED')
+        end
+
+        #
+        # Register the plugin with the SDK client.
+        #
+        # This method is called during SDK initialization to allow the plugin to set up any necessary integrations,
+        # register hooks, or perform other initialization tasks.
+        #
+        # @param client [LDClient] The LDClient instance
+        # @param environment_metadata [EnvironmentMetadata] Metadata about the environment in which the SDK is running
+        # @return [void]
+        #
+        def register(client, environment_metadata)
+          # Default implementation does nothing
+        end
+
+        #
+        # Get a list of hooks that this plugin provides.
+        #
+        # This method is called before register() to collect all hooks from plugins. The hooks returned will be
+        # added to the SDK's hook configuration.
+        #
+        # @param environment_metadata [EnvironmentMetadata] Metadata about the environment in which the SDK is running
+        # @return [Array<Interfaces::Hooks::Hook>] A list of hooks to be registered with the SDK
+        #
+        def get_hooks(environment_metadata)
+          []
+        end
+      end
+    end
   end
 end

lib/ldclient-rb/ldclient.rb

@@ -89,7 +89,10 @@ def postfork(wait_for_sec = 5)
     end
 
     private def start_up(wait_for_sec)
-      @hooks = Concurrent::Array.new(@config.hooks)
+      environment_metadata = get_environment_metadata
+      plugin_hooks = get_plugin_hooks(environment_metadata)
+      
+      @hooks = Concurrent::Array.new(@config.hooks + plugin_hooks)
 
       @shared_executor = Concurrent::SingleThreadExecutor.new
 
@@ -156,6 +159,8 @@ def postfork(wait_for_sec = 5)
         @data_source = data_source_or_factory
       end
 
+      register_plugins(environment_metadata)
+
       ready = @data_source.start
 
       return unless wait_for_sec > 0
@@ -172,6 +177,51 @@ def postfork(wait_for_sec = 5)
       end
     end
 
+    private def get_environment_metadata
+      sdk_metadata = Interfaces::Plugins::SdkMetadata.new(
+        name: "ruby-server-sdk",
+        version: LaunchDarkly::VERSION,
+        wrapper_name: @config.wrapper_name,
+        wrapper_version: @config.wrapper_version
+      )
+
+      application_metadata = nil
+      if @config.application && (!@config.application.empty?)
+        application_metadata = Interfaces::Plugins::ApplicationMetadata.new(
+          id: @config.application[:id],
+          version: @config.application[:version]
+        )
+      end
+
+      Interfaces::Plugins::EnvironmentMetadata.new(
+        sdk: sdk_metadata,
+        application: application_metadata,
+        sdk_key: @sdk_key
+      )
+    end
+
+    private def get_plugin_hooks(environment_metadata)
+      hooks = []
+      @config.plugins.each do |plugin|
+        begin
+          hooks.concat(plugin.get_hooks(environment_metadata))
+        rescue => e
+          @config.logger.error { "[LDClient] Error getting hooks from plugin #{plugin.metadata.name}: #{e}" }
+        end
+      end
+      hooks
+    end
+
+    private def register_plugins(environment_metadata)
+      @config.plugins.each do |plugin|
+        begin
+          plugin.register(self, environment_metadata)
+        rescue => e
+          @config.logger.error { "[LDClient] Error registering plugin #{plugin.metadata.name}: #{e}" }
+        end
+      end
+    end
+
     #
     # Add a hook to the client. In order to register a hook before the client starts, please use the `hooks` property of
     # {#LDConfig}.