togglecraft 1.0.0

data/lib/togglecraft/client.rb

@@ -0,0 +1,568 @@
+# frozen_string_literal: true
+
+module ToggleCraft
+  # Main ToggleCraft client class
+  # Provides the primary interface for feature flag evaluation with real-time updates
+  class Client
+    attr_reader :config, :ready
+
+    # Initialize the ToggleCraft client
+    # @param sdk_key [String] SDK key for authentication
+    # @param options [Hash] Configuration options
+    def initialize(sdk_key:, **options)
+      raise ArgumentError, 'sdk_key is required' if sdk_key.nil? || sdk_key.empty?
+
+      @config = {
+        url: 'https://sse.togglecraft.io',
+        enable_cache: true,
+        cache_adapter: :memory,
+        cache_ttl: 300, # 5 minutes
+        reconnect_interval: 1,
+        max_reconnect_interval: 30,
+        max_reconnect_attempts: 10,
+        slow_reconnect_interval: 60,
+        share_connection: true,
+        debug: false,
+        enable_rollout_stage_polling: true,
+        rollout_stage_check_interval: 60,
+        fetch_jitter: 1500, # milliseconds
+        api_domain: 'https://togglecraft.io'
+      }.merge(options).merge(sdk_key: sdk_key)
+
+      # Initialize components
+      @evaluator = Evaluator.new
+      @cache = @config[:enable_cache] ? Cache.new(adapter: @config[:cache_adapter], ttl: @config[:cache_ttl]) : nil
+
+      # State
+      @ready = Concurrent::AtomicBoolean.new(false)
+      @flags = Concurrent::Map.new
+      @current_version = Concurrent::AtomicReference.new(nil)
+      @project_key = Concurrent::AtomicReference.new(nil)
+      @environment_key = Concurrent::AtomicReference.new(nil)
+      @fetch_in_progress = Concurrent::AtomicBoolean.new(false)
+
+      # Event listeners
+      @listeners = Concurrent::Map.new
+      @listeners[:ready] = []
+      @listeners[:flags_updated] = []
+      @listeners[:error] = []
+      @listeners[:disconnected] = []
+      @listeners[:reconnecting] = []
+      @listeners[:rollout_stage_changed] = []
+      @listeners_mutex = Mutex.new
+
+      # Rollout stage polling
+      @rollout_stage_percentages = {}
+      @rollout_stage_timer = nil
+
+      # Initialize connection
+      initialize_connection
+
+      # Enable debug on connection pool if debug is enabled
+      ConnectionPool.set_debug(true) if @config[:debug] && @config[:share_connection]
+    end
+
+    # Connect to SSE server
+    # @return [void]
+    def connect
+      # Try to load from cache first
+      if @cache
+        cached_flags = @cache.all_flags
+        if cached_flags.any?
+          @flags.clear
+          cached_flags.each { |k, v| @flags[k] = v }
+          @evaluator.update_flags(cached_flags)
+          log 'Loaded flags from cache'
+        end
+      end
+
+      # Connect to SSE server
+      if @using_shared_connection
+        @connection.connect(self)
+      else
+        @connection.connect
+      end
+
+      log 'Connected to ToggleCraft'
+    rescue StandardError => e
+      handle_error(e)
+      raise
+    end
+
+    # Disconnect from SSE server
+    # @return [void]
+    def disconnect
+      log 'Disconnecting from SSE'
+      stop_rollout_stage_polling
+      @connection.disconnect
+      @ready.make_false
+    end
+
+    # Reconnect to SSE server
+    # @return [void]
+    def reconnect
+      emit(:reconnecting)
+      @connection.reconnect
+    end
+
+    # Check if client is ready
+    # @return [Boolean]
+    def ready?
+      @ready.value
+    end
+
+    # Check if connected to SSE server
+    # @return [Boolean]
+    def connected?
+      @connection&.connected? || false
+    end
+
+    # Wait for client to be ready
+    # @param timeout [Integer] Timeout in seconds
+    # @return [void]
+    # @raise [Timeout::Error] if timeout is reached
+    def wait_for_ready(timeout: 5)
+      return if ready?
+
+      ready_latch = Concurrent::CountDownLatch.new(1)
+      ready_handler = -> { ready_latch.count_down }
+
+      once(:ready, &ready_handler)
+
+      return if ready_latch.wait(timeout)
+
+      off(:ready, ready_handler)
+      raise Timeout::Error, 'Timeout waiting for client to be ready'
+    end
+
+    # Evaluate a boolean flag
+    # @param flag_key [String] Flag key
+    # @param context [Hash] Evaluation context
+    # @param default [Boolean] Default value
+    # @return [Boolean]
+    def enabled?(flag_key, context = {}, default: false)
+      result = @evaluator.evaluate_boolean(flag_key, context, default)
+
+      # Cache the result
+      cache_evaluation(flag_key, context, result) if @cache && context
+
+      result
+    end
+
+    # Get variant for multivariate flag
+    # @param flag_key [String] Flag key
+    # @param context [Hash] Evaluation context
+    # @param default [String, nil] Default variant
+    # @return [String, nil]
+    def variant(flag_key, context = {}, default: nil)
+      result = @evaluator.evaluate_multivariate(flag_key, context, default)
+
+      # Cache the result
+      cache_evaluation(flag_key, context, result) if @cache && context
+
+      result
+    end
+
+    # Check if in percentage rollout
+    # @param flag_key [String] Flag key
+    # @param context [Hash] Evaluation context
+    # @param default [Boolean] Default value
+    # @return [Boolean]
+    def in_percentage?(flag_key, context = {}, default: false)
+      result = @evaluator.evaluate_percentage(flag_key, context, default)
+
+      # Cache the result
+      cache_evaluation(flag_key, context, result) if @cache && context
+
+      result
+    end
+
+    # Get current percentage for a flag
+    # @param flag_key [String] Flag key
+    # @return [Integer, nil]
+    def percentage(flag_key)
+      @evaluator.percentage(flag_key)
+    end
+
+    # Evaluate any flag type
+    # @param flag_key [String] Flag key
+    # @param context [Hash] Evaluation context
+    # @param default [Object] Default value
+    # @return [Object]
+    def evaluate(flag_key, context = {}, default: false)
+      @evaluator.evaluate(flag_key, context, default)
+    end
+
+    # Get all flag keys
+    # @return [Array<String>]
+    def all_flag_keys
+      @evaluator.flag_keys
+    end
+
+    # Get flag metadata
+    # @param flag_key [String] Flag key
+    # @return [Hash, nil]
+    def flag_metadata(flag_key)
+      @evaluator.flag_metadata(flag_key)
+    end
+
+    # Check if flag exists
+    # @param flag_key [String] Flag key
+    # @return [Boolean]
+    def has_flag?(flag_key)
+      @evaluator.has_flag?(flag_key)
+    end
+
+    # Add event listener
+    # @param event [Symbol] Event type
+    # @param block [Proc] Event handler
+    # @return [void]
+    def on(event, &block)
+      @listeners_mutex.synchronize do
+        @listeners[event] ||= []
+        @listeners[event] << block
+      end
+    end
+
+    # Add one-time event listener
+    # @param event [Symbol] Event type
+    # @param block [Proc] Event handler
+    # @return [void]
+    def once(event, &block)
+      wrapper = lambda do |*args|
+        block.call(*args)
+        off(event, wrapper)
+      end
+      on(event, &wrapper)
+    end
+
+    # Remove event listener
+    # @param event [Symbol] Event type
+    # @param callable [Proc, nil] Specific handler to remove
+    # @return [void]
+    def off(event, callable = nil)
+      @listeners_mutex.synchronize do
+        if callable
+          @listeners[event]&.delete(callable)
+        else
+          @listeners[event] = []
+        end
+      end
+    end
+
+    # Clean up resources
+    # @return [void]
+    def destroy
+      log 'Destroying client instance'
+
+      stop_rollout_stage_polling
+
+      # Handle cleanup based on connection type
+      if @using_shared_connection && @connection
+        @connection.remove_client(self)
+      elsif @connection
+        disconnect
+      end
+
+      @cache&.destroy
+
+      # Clear all listeners
+      @listeners_mutex.synchronize do
+        @listeners.each_key { |key| @listeners[key] = [] }
+      end
+
+      @connection = nil
+      @flags.clear
+      @ready.make_false
+    end
+
+    # Handle SSE connection event
+    # @return [void]
+    def handle_connect
+      log 'SSE connected'
+    end
+
+    # Handle SSE disconnection event
+    # @return [void]
+    def handle_disconnect
+      @ready.make_false
+      emit(:disconnected)
+    end
+
+    # Handle error
+    # @param error [Exception] Error that occurred
+    # @return [void]
+    def handle_error(error)
+      log "Error: #{error.message}"
+      emit(:error, error)
+    end
+
+    # Handle flags update from SSE
+    # @param payload [Hash] Message payload
+    # @return [void]
+    def handle_flags_update(payload)
+      log "Received message: #{payload}"
+
+      # Handle version update notification
+      if payload[:type] == 'version_update'
+        handle_version_update(payload)
+        return
+      end
+
+      # Handle full flags payload
+      process_flags_payload(payload) if payload[:flags]
+    end
+
+    private
+
+    # Initialize connection (shared or dedicated)
+    # @return [void]
+    def initialize_connection
+      # Try to get a shared connection from the pool
+      shared_connection = ConnectionPool.get_connection(@config)
+
+      if shared_connection
+        @connection = shared_connection
+        @using_shared_connection = true
+        log 'Using shared SSE connection'
+      else
+        # Create dedicated SSE connection
+        @connection = SSEConnection.new(
+          url: @config[:url],
+          sdk_key: @config[:sdk_key],
+          reconnect_interval: @config[:reconnect_interval],
+          max_reconnect_interval: @config[:max_reconnect_interval],
+          max_reconnect_attempts: @config[:max_reconnect_attempts],
+          slow_reconnect_interval: @config[:slow_reconnect_interval],
+          heartbeat_domain: @config[:heartbeat_domain],
+          debug: @config[:debug],
+          on_message: method(:handle_flags_update),
+          on_connect: method(:handle_connect),
+          on_disconnect: method(:handle_disconnect),
+          on_error: method(:handle_error)
+        )
+        @using_shared_connection = false
+        log 'Using dedicated SSE connection'
+      end
+    end
+
+    # Handle version update notification
+    # @param data [Hash] Version update data
+    # @return [void]
+    def handle_version_update(data)
+      version = data[:version]
+      project_key = data[:project_key]
+      environment_key = data[:environment_key]
+
+      # Store project and environment keys from first message
+      @project_key.set(project_key) if project_key && @project_key.get.nil?
+      @environment_key.set(environment_key) if environment_key && @environment_key.get.nil?
+
+      # Check if we already have this version
+      if @current_version.get == version
+        log "Already have version #{version}"
+        return
+      end
+
+      log "New version available: old=#{@current_version.get}, new=#{version}, changed_flag=#{data[:changed_flag]}"
+
+      # Apply jitter to prevent thundering herd (only on updates, not initial connection)
+      is_initial_connection = @current_version.get.nil?
+      jitter = is_initial_connection ? 0 : Utils.generate_jitter(@config[:fetch_jitter])
+
+      if jitter.positive?
+        log "Applying #{jitter}ms jitter before fetching"
+        sleep(jitter.to_f / 1000)
+      end
+
+      # Fetch new version via HTTP
+      fetch_flags_via_http(version)
+    end
+
+    # Fetch flags via HTTP using versioned URL
+    # @param version [Integer] Version to fetch
+    # @return [void]
+    def fetch_flags_via_http(version)
+      return if @fetch_in_progress.true?
+
+      unless @project_key.get && @environment_key.get
+        log 'Project/environment keys not available yet, cannot fetch'
+        return
+      end
+
+      @fetch_in_progress.make_true
+
+      begin
+        versioned_url = "#{@config[:api_domain]}/api/v1/flags/#{@project_key.get}/#{@environment_key.get}/v/#{version}"
+        log "Fetching flags from #{versioned_url}"
+
+        response = HTTP.timeout(10).get(versioned_url)
+
+        raise "HTTP #{response.status}: #{response.status.reason}" unless response.status.success?
+
+        payload = JSON.parse(response.body.to_s, symbolize_names: true)
+        process_flags_payload(payload)
+
+        log "Flags updated via HTTP: version=#{payload[:version]}, flagCount=#{payload[:flags]&.size || 0}"
+      rescue StandardError => e
+        log "Failed to fetch flags via HTTP: #{e.message}"
+        handle_error(e)
+      ensure
+        @fetch_in_progress.make_false
+      end
+    end
+
+    # Process a full flags payload
+    # @param payload [Hash] Flags payload
+    # @return [void]
+    def process_flags_payload(payload)
+      log 'Processing flags payload'
+
+      @flags.clear
+      payload[:flags]&.each { |k, v| @flags[k] = v }
+      @evaluator.update_flags(payload[:flags] || {})
+
+      # Update version tracking
+      @current_version.set(payload[:version]) if payload[:version]
+
+      # Update cache
+      @cache&.set_all_flags(payload[:flags] || {})
+
+      # Initialize rollout stage tracking
+      initialize_rollout_stage_tracking
+
+      # Mark as ready on first update
+      unless @ready.value
+        @ready.make_true
+        emit(:ready)
+
+        # Start rollout stage polling
+        start_rollout_stage_polling if @config[:enable_rollout_stage_polling]
+      end
+
+      # Emit flags updated event
+      emit(:flags_updated, payload[:flags] || {})
+    end
+
+    # Initialize rollout stage tracking
+    # @return [void]
+    def initialize_rollout_stage_tracking
+      @rollout_stage_percentages = {}
+
+      @flags.each do |flag_key, flag|
+        next unless flag[:type] == 'percentage'
+        next unless flag[:rollout_stages]&.any?
+
+        @rollout_stage_percentages[flag_key] = @evaluator.current_percentage_for_flag(flag)
+      end
+    end
+
+    # Start rollout stage polling
+    # @return [void]
+    def start_rollout_stage_polling
+      stop_rollout_stage_polling
+
+      log "Starting rollout stage polling (interval: #{@config[:rollout_stage_check_interval]}s)"
+
+      @rollout_stage_timer = Thread.new do
+        loop do
+          sleep @config[:rollout_stage_check_interval]
+          check_rollout_stage_changes
+        end
+      rescue StandardError => e
+        log "Rollout stage polling error: #{e.message}"
+      end
+
+      @rollout_stage_timer.abort_on_exception = false
+    end
+
+    # Stop rollout stage polling
+    # @return [void]
+    def stop_rollout_stage_polling
+      return unless @rollout_stage_timer
+
+      @rollout_stage_timer.kill if @rollout_stage_timer.alive?
+      @rollout_stage_timer = nil
+      log 'Stopped rollout stage polling'
+    end
+
+    # Check for rollout stage changes
+    # @return [void]
+    def check_rollout_stage_changes
+      changed_flags = []
+
+      @flags.each do |flag_key, flag|
+        next unless flag[:type] == 'percentage'
+        next unless flag[:rollout_stages]&.any?
+
+        old_percentage = @rollout_stage_percentages[flag_key]
+        new_percentage = @evaluator.current_percentage_for_flag(flag)
+
+        next unless old_percentage != new_percentage
+
+        @rollout_stage_percentages[flag_key] = new_percentage
+        changed_flags << {
+          key: flag_key,
+          old_percentage: old_percentage,
+          new_percentage: new_percentage
+        }
+
+        log "Rollout stage changed for #{flag_key}: #{old_percentage}% → #{new_percentage}%"
+      end
+
+      return unless changed_flags.any?
+
+      # Clear evaluation cache for changed flags
+      clear_evaluation_cache_for_flags(changed_flags.map { |f| f[:key] })
+
+      # Emit rollout stage changed event
+      emit(:rollout_stage_changed, {
+             flags: changed_flags,
+             timestamp: Time.now.iso8601
+           })
+    end
+
+    # Clear evaluation cache for specific flags
+    # @param flag_keys [Array<String>] Flag keys to clear cache for
+    # @return [void]
+    def clear_evaluation_cache_for_flags(flag_keys)
+      return unless @cache
+
+      log "Clearing evaluation cache for flags: #{flag_keys.join(', ')}"
+      flag_keys.each { |key| @cache.clear_by_prefix("eval:#{key}:") }
+    end
+
+    # Cache an evaluation result
+    # @param flag_key [String] Flag key
+    # @param context [Hash] Evaluation context
+    # @param result [Object] Evaluation result
+    # @return [void]
+    def cache_evaluation(flag_key, context, result)
+      cache_key = Utils.create_cache_key(flag_key, context)
+      @cache.set("eval:#{cache_key}", result, ttl: 60) # Cache for 1 minute
+    end
+
+    # Emit an event
+    # @param event [Symbol] Event type
+    # @param args [Array] Event arguments
+    # @return [void]
+    def emit(event, *args)
+      handlers = @listeners_mutex.synchronize { @listeners[event]&.dup || [] }
+
+      handlers.each do |handler|
+        handler.call(*args)
+      rescue StandardError => e
+        warn "Error in #{event} listener: #{e.message}"
+      end
+    end
+
+    # Log debug message
+    # @param message [String] Message to log
+    # @return [void]
+    def log(message)
+      return unless @config[:debug]
+
+      puts "[ToggleCraft Client] #{message}"
+    end
+  end
+end

data/lib/togglecraft/connection_pool.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module ToggleCraft
+  # Connection pool manager for SSE connections
+  # Ensures that multiple SDK instances can share the same SSE connection
+  class ConnectionPool
+    class << self
+      # Get the connections map
+      # @return [Concurrent::Map]
+      def connections
+        @connections ||= Concurrent::Map.new
+      end
+
+      # Get or create a shared connection
+      # @param config [Hash] Client configuration
+      # @return [SharedSSEConnection, nil] Shared connection instance or nil if sharing disabled
+      def get_connection(config)
+        # If connection sharing is disabled, return nil to create a dedicated connection
+        unless config[:share_connection]
+          log 'Connection sharing disabled for this client'
+          return nil
+        end
+
+        pool_key = generate_pool_key(config)
+        log "Getting connection for pool key: #{pool_key}"
+
+        # Check if connection already exists
+        connection = connections[pool_key]
+
+        if connection
+          log "Reusing existing connection for #{pool_key} (#{connection.client_count} clients)"
+        else
+          # Create new shared SSE connection
+          log "Creating new shared SSE connection for #{pool_key}"
+          connection = SharedSSEConnection.new(config, pool_key)
+          connections[pool_key] = connection
+
+          # Set up cleanup when connection has no more clients
+          connection.on_empty do
+            log "Removing empty connection for #{pool_key}"
+            connections.delete(pool_key)
+          end
+        end
+
+        connection
+      end
+
+      # Generate a pool key from configuration
+      # @param config [Hash] Client configuration
+      # @return [String] Pool key for the connection
+      def generate_pool_key(config)
+        # Allow custom pool key for advanced users
+        return config[:connection_pool_key] if config[:connection_pool_key]
+
+        # Generate key from connection parameters
+        url = config[:url] || 'https://sse.togglecraft.io'
+        sdk_key = config[:sdk_key]
+        "#{url}:#{sdk_key}"
+      end
+
+      # Get statistics about the connection pool
+      # @return [Hash] Pool statistics
+      def stats
+        conn_stats = []
+        connections.each do |key, conn|
+          conn_stats << {
+            key: key,
+            client_count: conn.client_count,
+            connected: conn.connected?
+          }
+        end
+
+        {
+          total_connections: connections.size,
+          connections: conn_stats
+        }
+      end
+
+      # Clear all connections
+      # @param force [Boolean] Force disconnect all connections
+      # @return [void]
+      def clear(force: false)
+        connections.each_value(&:force_disconnect) if force
+        connections.clear
+      end
+
+      # Enable or disable debug logging
+      # @param enabled [Boolean]
+      # @return [void]
+      def set_debug(enabled)
+        @debug = enabled
+        # Also enable debug on existing connections
+        connections.each_value { |conn| conn.set_debug(enabled) }
+      end
+
+      # Get the number of active connections
+      # @return [Integer]
+      def connection_count
+        connections.size
+      end
+
+      # Get the total number of clients across all connections
+      # @return [Integer]
+      def total_client_count
+        connections.values.sum(&:client_count)
+      end
+
+      # Check if a specific pool key has an active connection
+      # @param pool_key [String]
+      # @return [Boolean]
+      def has_connection?(pool_key)
+        connections.key?(pool_key)
+      end
+
+      # Get connection by pool key (for testing/debugging)
+      # @param pool_key [String]
+      # @return [SharedSSEConnection, nil]
+      def get_connection_by_key(pool_key)
+        connections[pool_key]
+      end
+
+      private
+
+      # Log debug messages
+      # @param message [String] Message to log
+      # @return [void]
+      def log(message)
+        return unless @debug
+
+        puts "[ToggleCraft ConnectionPool] #{message}"
+      end
+    end
+  end
+end