togglecraft 1.0.0

data/lib/togglecraft/evaluator.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module ToggleCraft
+  # Flag evaluation engine for ToggleCraft Ruby SDK
+  # Evaluates boolean, multivariate, and percentage flags based on rules and context
+  class Evaluator
+    def initialize
+      @flags = Concurrent::Map.new
+    end
+
+    # Update the flags data
+    # @param flags [Hash] The flags payload
+    def update_flags(flags)
+      @flags.clear
+      flags&.each { |key, value| @flags[key] = value }
+    end
+
+    # Evaluate a boolean flag
+    # @param flag_key [String] The flag key
+    # @param context [Hash] The evaluation context
+    # @param default_value [Boolean] Default value if flag not found
+    # @return [Boolean]
+    def evaluate_boolean(flag_key, context = {}, default_value = false)
+      flag = @flags[flag_key]
+
+      # Flag doesn't exist
+      return default_value unless flag
+
+      # Flag is not a boolean type
+      unless flag[:type] == 'boolean'
+        warn "[ToggleCraft] Flag #{flag_key} is not a boolean flag"
+        return default_value
+      end
+
+      # Flag is disabled
+      return false unless flag[:enabled]
+
+      # Evaluate targeting rules
+      if flag[:rules]&.any?
+        flag[:rules].each do |rule|
+          if evaluate_rule(rule, context)
+            return rule[:value].nil? ? flag[:value] : rule[:value]
+          end
+        end
+      end
+
+      # Return default flag value
+      flag[:value].nil? ? default_value : flag[:value]
+    end
+
+    # Evaluate a multivariate flag
+    # @param flag_key [String] The flag key
+    # @param context [Hash] The evaluation context
+    # @param default_variant [String, nil] Default variant if flag not found
+    # @return [String, nil]
+    def evaluate_multivariate(flag_key, context = {}, default_variant = nil)
+      flag = @flags[flag_key]
+
+      # Flag doesn't exist
+      return default_variant unless flag
+
+      # Flag is not a multivariate type
+      unless flag[:type] == 'multivariate'
+        warn "[ToggleCraft] Flag #{flag_key} is not a multivariate flag"
+        return default_variant
+      end
+
+      # Flag is disabled
+      return default_variant unless flag[:enabled]
+
+      # Evaluate targeting rules
+      if flag[:rules]&.any?
+        flag[:rules].each do |rule|
+          return rule[:variant] || flag[:default_variant] || default_variant if evaluate_rule(rule, context)
+        end
+      end
+
+      # Use weighted distribution if weights are defined
+      if flag[:weights]&.any?
+        variant = select_variant_by_weight(flag_key, flag[:weights], context)
+        return variant if variant
+      end
+
+      # Return default variant
+      flag[:default_variant] || default_variant
+    end
+
+    # Evaluate a percentage rollout flag
+    # @param flag_key [String] The flag key
+    # @param context [Hash] The evaluation context
+    # @param default_value [Boolean] Default value if flag not found
+    # @return [Boolean]
+    def evaluate_percentage(flag_key, context = {}, default_value = false)
+      flag = @flags[flag_key]
+
+      # Flag doesn't exist
+      return default_value unless flag
+
+      # Flag is not a percentage type
+      unless flag[:type] == 'percentage'
+        warn "[ToggleCraft] Flag #{flag_key} is not a percentage flag"
+        return default_value
+      end
+
+      # Flag is disabled
+      return false unless flag[:enabled]
+
+      # Evaluate targeting rules first
+      if flag[:rules]&.any?
+        flag[:rules].each do |rule|
+          return rule[:enabled].nil? || rule[:enabled] if evaluate_rule(rule, context)
+        end
+      end
+
+      # Get current percentage (considering rollout stages)
+      percentage = current_percentage_for_flag(flag)
+
+      # Check percentage boundaries
+      return false if percentage <= 0
+      return true if percentage >= 100
+
+      # Use consistent hashing based on user ID or random value
+      user_id = context.dig(:user, :id) || context.dig(:user, :email) || SecureRandom.uuid
+      hash_value = Utils.hash_key("#{flag_key}:#{user_id}")
+
+      hash_value < percentage
+    end
+
+    # Calculate the current percentage for a flag based on rollout stages
+    # @param flag [Hash] The percentage flag object
+    # @return [Integer] The current percentage to use
+    def current_percentage_for_flag(flag)
+      # If no rollout stages, use base percentage
+      return flag[:percentage] if flag[:rollout_stages].nil? || flag[:rollout_stages].empty?
+
+      now = Time.now
+      active_stage = nil
+      latest_start_time = nil
+
+      # Find the most recent active stage
+      flag[:rollout_stages].each do |stage|
+        start_at = Time.parse(stage[:start_at])
+        end_at = stage[:end_at] ? Time.parse(stage[:end_at]) : nil
+
+        # Check if stage is currently active
+        is_active = start_at <= now && (end_at.nil? || end_at > now)
+
+        if is_active && (latest_start_time.nil? || start_at > latest_start_time)
+          active_stage = stage
+          latest_start_time = start_at
+        end
+      end
+
+      # Return active stage percentage, or fall back to base percentage
+      active_stage ? active_stage[:percentage] : flag[:percentage]
+    end
+
+    # Get the current percentage value of a flag
+    # @param flag_key [String] The flag key
+    # @return [Integer, nil]
+    def percentage(flag_key)
+      flag = @flags[flag_key]
+
+      return nil unless flag && flag[:type] == 'percentage'
+
+      current_percentage_for_flag(flag)
+    end
+
+    # Evaluate a single rule
+    # @param rule [Hash] The rule to evaluate
+    # @param context [Hash] The evaluation context
+    # @return [Boolean]
+    def evaluate_rule(rule, context)
+      return false if rule[:conditions].nil? || rule[:conditions].empty?
+
+      result = nil
+      previous_combinator = nil
+
+      rule[:conditions].each do |condition|
+        condition_result = evaluate_condition(condition, context)
+
+        result = if result.nil?
+                   condition_result
+                 else
+                   # Apply combinator logic
+                   case previous_combinator
+                   when 'OR'
+                     result || condition_result
+                   else
+                     # Default to AND
+                     result && condition_result
+                   end
+                 end
+
+        previous_combinator = condition[:combinator] || 'AND'
+
+        # Early exit for AND conditions
+        return false if !result && previous_combinator == 'AND'
+
+        # Early exit for OR conditions
+        return true if result && previous_combinator == 'OR'
+      end
+
+      result || false
+    end
+
+    # Evaluate a single condition
+    # @param condition [Hash] The condition to evaluate
+    # @param context [Hash] The evaluation context
+    # @return [Boolean]
+    def evaluate_condition(condition, context)
+      attribute_value = Utils.get_nested_property(context, condition[:attribute])
+      Utils.evaluate_operator(attribute_value, condition[:operator], condition[:values] || [])
+    end
+
+    # Select a variant based on weights using consistent hashing
+    # @param flag_key [String] The flag key
+    # @param weights [Hash] Variant weights
+    # @param context [Hash] The evaluation context
+    # @return [String, nil]
+    def select_variant_by_weight(flag_key, weights, context)
+      # Calculate total weight
+      total_weight = 0
+      variants = []
+
+      weights.each do |variant, weight|
+        total_weight += weight
+        variants << { variant: variant.to_s, weight: weight }
+      end
+
+      return nil if total_weight.zero?
+
+      # Use consistent hashing
+      user_id = context.dig(:user, :id) || context.dig(:user, :email) || SecureRandom.uuid
+      hash = Utils.hash_key("#{flag_key}:#{user_id}")
+      scaled_hash = (hash.to_f / 100) * total_weight
+
+      # Select variant based on hash
+      accumulator = 0
+      variants.each do |v|
+        accumulator += v[:weight]
+        return v[:variant] if scaled_hash < accumulator
+      end
+
+      # Fallback to last variant
+      variants.last&.dig(:variant)
+    end
+
+    # Check if a flag exists
+    # @param flag_key [String] The flag key
+    # @return [Boolean]
+    def has_flag?(flag_key)
+      @flags.key?(flag_key)
+    end
+
+    # Get all flag keys
+    # @return [Array<String>]
+    def flag_keys
+      @flags.keys
+    end
+
+    # Get flag metadata
+    # @param flag_key [String] The flag key
+    # @return [Hash, nil]
+    def flag_metadata(flag_key)
+      flag = @flags[flag_key]
+      return nil unless flag
+
+      metadata = {
+        type: flag[:type],
+        enabled: flag[:enabled]
+      }
+
+      case flag[:type]
+      when 'multivariate'
+        metadata[:variants] = flag[:variants]
+        metadata[:default_variant] = flag[:default_variant]
+      when 'percentage'
+        metadata[:percentage] = flag[:percentage]
+      end
+
+      metadata
+    end
+
+    # Evaluate any flag type
+    # @param flag_key [String] The flag key
+    # @param context [Hash] The evaluation context
+    # @param default_value [Object] Default value
+    # @return [Object]
+    def evaluate(flag_key, context = {}, default_value = false)
+      flag = @flags[flag_key]
+      return default_value unless flag
+
+      case flag[:type]
+      when 'boolean'
+        evaluate_boolean(flag_key, context, default_value)
+      when 'multivariate'
+        evaluate_multivariate(flag_key, context, default_value)
+      when 'percentage'
+        evaluate_percentage(flag_key, context, default_value)
+      else
+        warn "[ToggleCraft] Unknown flag type: #{flag[:type]}"
+        default_value
+      end
+    end
+  end
+end

data/lib/togglecraft/shared_sse_connection.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+module ToggleCraft
+  # Shared SSE connection wrapper
+  # Manages a single SSE connection that can be shared by multiple SDK clients
+  class SharedSSEConnection
+    attr_reader :pool_key
+
+    def initialize(config, pool_key)
+      @config = config
+      @pool_key = pool_key
+      @clients = Concurrent::Set.new
+      @connection = nil
+      @last_payload = nil
+      @is_connecting = Concurrent::AtomicBoolean.new(false)
+      @connection_promise = nil
+      @debug = config[:debug] || false
+      @on_empty_callback = nil
+      @mutex = Mutex.new
+    end
+
+    # Add a client to this shared connection
+    # @param client [Object] The ToggleCraftClient instance
+    # @return [void]
+    def add_client(client)
+      log "Adding client to shared connection (#{@clients.size + 1} total clients)"
+      @clients.add(client)
+
+      # If connection is already established, simulate initialization for new client
+      return unless connected? && @last_payload
+
+      log 'Connection already established - simulating initialization for new client'
+
+      # Simulate connection event
+      client.handle_connect if client.respond_to?(:handle_connect)
+
+      # Send cached flags
+      client.handle_flags_update(@last_payload) if client.respond_to?(:handle_flags_update)
+    end
+
+    # Remove a client from this shared connection
+    # @param client [Object] The ToggleCraftClient instance
+    # @return [void]
+    def remove_client(client)
+      log "Removing client from shared connection (#{@clients.size - 1} remaining)"
+      @clients.delete(client)
+
+      # If no more clients, clean up the connection
+      return unless @clients.empty?
+
+      log 'No more clients, closing shared connection'
+      cleanup
+      @on_empty_callback&.call
+    end
+
+    # Connect to the SSE server
+    # @param client_to_add [Object, nil] Optional client to add when connecting
+    # @return [void]
+    def connect(client_to_add = nil)
+      # If already connecting, wait for completion
+      if @is_connecting.value
+        log 'Connection already in progress, waiting...'
+        # Just add the client, connection will complete
+        add_client(client_to_add) if client_to_add
+        return
+      end
+
+      # If already connected, just add the client
+      if connected?
+        log 'Already connected'
+        add_client(client_to_add) if client_to_add
+        return
+      end
+
+      @is_connecting.make_true
+
+      begin
+        create_connection
+        add_client(client_to_add) if client_to_add
+      ensure
+        @is_connecting.make_false
+      end
+    end
+
+    # Disconnect from the SSE server
+    # @return [void]
+    def disconnect
+      log 'Disconnect called on shared connection'
+      @connection&.disconnect
+    end
+
+    # Force disconnect (used by pool cleanup)
+    # @return [void]
+    def force_disconnect
+      log 'Force disconnecting shared connection'
+      @connection&.disconnect
+      @clients.clear
+    end
+
+    # Reconnect to the SSE server
+    # @return [void]
+    def reconnect
+      log 'Reconnecting shared connection'
+
+      # Notify all clients about reconnection
+      @clients.each do |client|
+        client.emit(:reconnecting) if client.respond_to?(:emit)
+      end
+
+      if @connection
+        @connection.reconnect
+      else
+        connect
+      end
+    end
+
+    # Check if connected
+    # @return [Boolean]
+    def connected?
+      @connection&.connected?
+    end
+
+    # Get the number of connected clients
+    # @return [Integer]
+    def client_count
+      @clients.size
+    end
+
+    # Set callback for when connection becomes empty
+    # @param callback [Proc] Callback to invoke
+    # @return [void]
+    def on_empty(&callback)
+      @on_empty_callback = callback
+    end
+
+    # Enable or disable debug logging
+    # @param enabled [Boolean]
+    # @return [void]
+    def set_debug(enabled)
+      @debug = enabled
+      return unless @connection
+
+      @connection.instance_variable_set(:@options,
+                                        @connection.instance_variable_get(:@options).merge(debug: enabled))
+    end
+
+    private
+
+    # Create the actual SSE connection
+    # @return [void]
+    def create_connection
+      log 'Creating new 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: @debug,
+        on_message: method(:handle_message),
+        on_connect: method(:handle_connect),
+        on_disconnect: method(:handle_disconnect),
+        on_error: method(:handle_error)
+      )
+
+      @connection.connect
+    end
+
+    # Handle incoming messages from SSE
+    # @param payload [Hash] Message payload
+    # @return [void]
+    def handle_message(payload)
+      log "Broadcasting message to #{@clients.size} clients"
+
+      # Cache the last payload for new clients
+      @last_payload = payload if payload[:flags]
+
+      # Broadcast to all connected clients
+      @clients.each do |client|
+        next unless client.respond_to?(:handle_flags_update)
+
+        begin
+          client.handle_flags_update(payload)
+        rescue StandardError => e
+          warn "Error handling flags update in client: #{e.message}"
+        end
+      end
+    end
+
+    # Handle SSE connection
+    # @return [void]
+    def handle_connect
+      log 'SSE connected'
+
+      # Notify all clients
+      @clients.each do |client|
+        next unless client.respond_to?(:handle_connect)
+
+        begin
+          client.handle_connect
+        rescue StandardError => e
+          warn "Error handling connect in client: #{e.message}"
+        end
+      end
+    end
+
+    # Handle SSE disconnection
+    # @return [void]
+    def handle_disconnect
+      log 'SSE disconnected'
+
+      # Notify all clients
+      @clients.each do |client|
+        next unless client.respond_to?(:handle_disconnect)
+
+        begin
+          client.handle_disconnect
+        rescue StandardError => e
+          warn "Error handling disconnect in client: #{e.message}"
+        end
+      end
+    end
+
+    # Handle SSE errors
+    # @param error [Exception] Error that occurred
+    # @return [void]
+    def handle_error(error)
+      log "SSE error: #{error.message}"
+
+      # Broadcast error to all clients
+      @clients.each do |client|
+        next unless client.respond_to?(:handle_error)
+
+        begin
+          client.handle_error(error)
+        rescue StandardError => e
+          warn "Error handling error in client: #{e.message}"
+        end
+      end
+    end
+
+    # Clean up resources
+    # @return [void]
+    def cleanup
+      log 'Cleaning up shared connection'
+
+      @connection&.disconnect
+      @connection = nil
+      @last_payload = nil
+      @is_connecting.make_false
+      @connection_promise = nil
+    end
+
+    # Log debug messages
+    # @param message [String] Message to log
+    # @return [void]
+    def log(message)
+      return unless @debug
+
+      puts "[ToggleCraft SharedSSEConnection #{@pool_key}] #{message}"
+    end
+  end
+end