togglecraft 1.0.0

data/lib/togglecraft/sse_connection.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+require 'http'
+require 'json'
+
+module ToggleCraft
+  # SSE (Server-Sent Events) connection manager
+  # Manages persistent connection to ToggleCraft SSE server with heartbeat
+  class SSEConnection
+    attr_reader :url, :sdk_key, :connected, :connection_id
+
+    # Initialize SSE connection
+    # @param url [String] SSE endpoint URL
+    # @param sdk_key [String] SDK key for authentication
+    # @param options [Hash] Connection options
+    def initialize(url:, sdk_key:, **options)
+      @url = url.sub(%r{/cable$}, '') # Remove /cable if present
+      @sdk_key = sdk_key
+      @options = {
+        reconnect_interval: 1,
+        max_reconnect_interval: 30,
+        max_reconnect_attempts: 10,
+        slow_reconnect_interval: 60,
+        heartbeat_domain: 'https://togglecraft.io',
+        heartbeat_interval: 300, # 5 minutes
+        debug: false
+      }.merge(options)
+
+      @connected = false
+      @connection_id = nil
+      @reconnect_attempts = 0
+      @should_reconnect = true
+
+      # Callbacks
+      @on_message = options[:on_message] || proc {}
+      @on_connect = options[:on_connect] || proc {}
+      @on_disconnect = options[:on_disconnect] || proc {}
+      @on_error = options[:on_error] || proc {}
+
+      # Threads
+      @connection_thread = nil
+      @heartbeat_thread = nil
+      @heartbeat_timer = nil
+    end
+
+    # Connect to SSE server
+    # @return [void]
+    def connect
+      return if @connected
+
+      @should_reconnect = true
+      start_connection
+    end
+
+    # Disconnect from SSE server
+    # @return [void]
+    def disconnect
+      log 'Disconnecting'
+      @should_reconnect = false
+      @connection_id = nil
+      stop_heartbeat
+      stop_connection
+      @connected = false
+    end
+
+    # Reconnect to SSE server
+    # @return [void]
+    def reconnect
+      disconnect
+      @should_reconnect = true
+      @reconnect_attempts = 0
+      connect
+    end
+
+    # Check if connected to SSE server
+    # @return [Boolean]
+    def connected?
+      @connected
+    end
+
+    private
+
+    # Start SSE connection in background thread
+    def start_connection
+      @connection_thread = Thread.new do
+        connect_sse
+      rescue StandardError => e
+        log "Connection error: #{e.message}"
+        handle_error(e)
+        handle_disconnection
+      end
+      @connection_thread.abort_on_exception = false
+    end
+
+    # Stop connection thread
+    def stop_connection
+      return unless @connection_thread
+
+      @connection_thread.kill if @connection_thread.alive?
+      @connection_thread = nil
+    end
+
+    # Connect to SSE server using HTTP streaming
+    def connect_sse
+      # Build SSE URL with channel identifier
+      channel_identifier = JSON.generate({
+                                           channel: 'FlagsChannel',
+                                           sdk_key: @sdk_key
+                                         })
+
+      sse_url = "#{@url}/events?identifier=#{CGI.escape(channel_identifier)}"
+      log "Connecting to #{sse_url}"
+
+      HTTP.get(sse_url) do |response|
+        raise "HTTP #{response.status}: #{response.status.reason}" unless response.status.success?
+
+        @connected = true
+        @reconnect_attempts = 0
+        @on_connect.call
+        start_heartbeat
+
+        # Read SSE stream
+        buffer = ''
+        response.body.each do |chunk|
+          buffer += chunk
+
+          # Process complete SSE messages (ending with \n\n)
+          while buffer.include?("\n\n")
+            message, buffer = buffer.split("\n\n", 2)
+            process_sse_message(message)
+          end
+        end
+      end
+    rescue StandardError => e
+      log "SSE error: #{e.message}"
+      raise
+    end
+
+    # Process SSE message
+    # @param message [String] Raw SSE message
+    def process_sse_message(message)
+      return if message.strip.empty?
+
+      # Parse SSE format: "event: type\ndata: {...}"
+      lines = message.split("\n")
+      event_type = nil
+      data = nil
+
+      lines.each do |line|
+        if line.start_with?('event:')
+          event_type = line.sub('event:', '').strip
+        elsif line.start_with?('data:')
+          data = line.sub('data:', '').strip
+        end
+      end
+
+      return unless data
+
+      begin
+        parsed_data = JSON.parse(data, symbolize_names: true)
+
+        # Extract connection ID from server messages
+        if parsed_data[:connection_id] && @connection_id != parsed_data[:connection_id]
+          log "Connection ID received: #{parsed_data[:connection_id]}"
+          @connection_id = parsed_data[:connection_id]
+        end
+
+        @on_message.call(parsed_data)
+      rescue JSON::ParserError => e
+        log "Failed to parse SSE data: #{e.message}"
+      end
+    end
+
+    # Handle disconnection and schedule reconnection
+    def handle_disconnection
+      return unless @connected
+
+      @connected = false
+      @connection_id = nil
+      stop_heartbeat
+      @on_disconnect.call
+
+      schedule_reconnection if @should_reconnect
+    end
+
+    # Handle errors
+    # @param error [Exception] The error that occurred
+    def handle_error(error)
+      @on_error.call(error)
+    end
+
+    # Schedule reconnection with exponential backoff
+    def schedule_reconnection
+      # Hybrid approach: switch to slow mode after max attempts
+      if @reconnect_attempts >= @options[:max_reconnect_attempts]
+        interval = @options[:slow_reconnect_interval]
+        log "Max fast reconnection attempts reached, switching to slow mode (every #{interval}s)"
+      else
+        @reconnect_attempts += 1
+        interval = [@options[:reconnect_interval] * (2**(@reconnect_attempts - 1)),
+                    @options[:max_reconnect_interval]].min
+        log "Scheduling reconnection attempt #{@reconnect_attempts}/" \
+            "#{@options[:max_reconnect_attempts]} in #{interval}s"
+      end
+
+      Thread.new do
+        sleep interval
+        connect if @should_reconnect
+      rescue StandardError => e
+        log "Reconnection failed: #{e.message}"
+      end
+    end
+
+    # Start heartbeat timer
+    def start_heartbeat
+      stop_heartbeat # Clear any existing timer
+
+      @heartbeat_timer = Thread.new do
+        loop do
+          sleep @options[:heartbeat_interval]
+
+          # Add random jitter (0-30 seconds)
+          jitter = rand(0..30)
+          sleep jitter
+
+          send_heartbeat if @connected
+        end
+      rescue StandardError => e
+        log "Heartbeat thread error: #{e.message}"
+      end
+
+      @heartbeat_timer.abort_on_exception = false
+      log "Heartbeat started (interval: #{@options[:heartbeat_interval]}s with 0-30s jitter)"
+    end
+
+    # Stop heartbeat timer
+    def stop_heartbeat
+      return unless @heartbeat_timer
+
+      @heartbeat_timer.kill if @heartbeat_timer.alive?
+      @heartbeat_timer = nil
+      log 'Heartbeat stopped'
+    end
+
+    # Send heartbeat via HTTP POST
+    # CRITICAL: Only send when connection is actually established
+    def send_heartbeat
+      unless @connected
+        log 'Skipping heartbeat - not connected'
+        return
+      end
+
+      unless @connection_id
+        log 'Skipping heartbeat - connection ID not yet received'
+        return
+      end
+
+      begin
+        heartbeat_url = "#{@options[:heartbeat_domain]}/api/v1/heartbeat"
+        log "Sending heartbeat to #{heartbeat_url}"
+
+        response = HTTP.timeout(10)
+                       .headers(
+                         'Content-Type' => 'application/json',
+                         'X-SDK-Key' => @sdk_key,
+                         'X-Connection-ID' => @connection_id
+                       )
+                       .post(heartbeat_url)
+
+        if response.status.success?
+          data = JSON.parse(response.body.to_s)
+          log "Heartbeat successful: #{data}"
+        elsif response.status.code == 404
+          # Connection not found on server - reconnect
+          log 'Connection not found on server, disconnecting and reconnecting'
+          disconnect
+          @should_reconnect = true
+          schedule_reconnection
+        else
+          log "Heartbeat failed: #{response.status}"
+        end
+      rescue StandardError => e
+        log "Heartbeat request failed: #{e.message}"
+        # Don't disconnect on heartbeat failure - might be temporary network issue
+      end
+    end
+
+    # Log debug messages
+    # @param message [String] Message to log
+    def log(message)
+      return unless @options[:debug]
+
+      puts "[ToggleCraft SSE] #{message}"
+    end
+  end
+end

data/lib/togglecraft/utils.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module ToggleCraft
+  module Utils
+    # Operators supported for rule evaluation
+    OPERATORS = %w[
+      equals not_equals contains not_contains starts_with ends_with
+      in not_in gt gte lt lte between regex
+      semver_eq semver_gt semver_gte semver_lt semver_lte
+    ].freeze
+
+    # Consistent hashing for percentage rollouts
+    # Returns a value between 0 and 100
+    # Mirrors the JavaScript implementation exactly for consistency
+    #
+    # @param key [String] The key to hash
+    # @return [Integer] A value between 0 and 100
+    def self.hash_key(key)
+      hash = 0
+      key.to_s.each_char do |char|
+        hash = ((hash << 5) - hash) + char.ord
+        hash &= hash # Convert to 32-bit integer
+      end
+      hash.abs % 100
+    end
+
+    # Deep get a nested property from a hash using dot notation
+    # Supports both string and symbol keys
+    #
+    # @param obj [Hash] The hash to query
+    # @param path [String] The path to the property (e.g., "user.email")
+    # @return [Object, nil] The value at the path or nil
+    def self.get_nested_property(obj, path)
+      return nil unless obj && path
+      return nil if path.to_s.strip.empty?
+
+      keys = path.to_s.split('.')
+      current = obj
+
+      keys.each do |key|
+        return nil if current.nil?
+
+        # Try both symbol and string keys
+        current = current[key.to_sym] || current[key.to_s]
+      end
+
+      current
+    end
+
+    # Compare semantic versions
+    # Returns -1 if version1 < version2, 0 if equal, 1 if version1 > version2
+    #
+    # @param version1 [String] First version
+    # @param version2 [String] Second version
+    # @return [Integer] -1, 0, or 1
+    def self.compare_semver(version1, version2)
+      v1_parts = version1.to_s.split('.').map(&:to_i)
+      v2_parts = version2.to_s.split('.').map(&:to_i)
+
+      3.times do |i|
+        part1 = v1_parts[i] || 0
+        part2 = v2_parts[i] || 0
+
+        return 1 if part1 > part2
+        return -1 if part1 < part2
+      end
+
+      0
+    end
+
+    # Generate random jitter delay to prevent thundering herd
+    # When many clients receive a version update simultaneously, jitter ensures
+    # they don't all fetch the new version at exactly the same time
+    #
+    # @param max_jitter_ms [Integer] Maximum jitter in milliseconds
+    # @return [Integer] Random delay between 0 and max_jitter_ms
+    def self.generate_jitter(max_jitter_ms = 1500)
+      rand(0..max_jitter_ms)
+    end
+
+    # Create a unique key for caching based on flag and context
+    #
+    # @param flag_key [String] The flag key
+    # @param context [Hash] The evaluation context
+    # @return [String] A unique cache key
+    def self.create_cache_key(flag_key, context)
+      user_id = context.dig(:user, :id) || context.dig(:user, :email) || 'anonymous'
+      "#{flag_key}:#{user_id}"
+    end
+
+    # Evaluate a condition operator
+    # Supports 14 different operators for flexible targeting rules
+    #
+    # @param attribute_value [Object] The actual value from context
+    # @param operator [String] The operator to use
+    # @param condition_values [Array] The values to compare against
+    # @return [Boolean] Whether the condition passes
+    def self.evaluate_operator(attribute_value, operator, condition_values)
+      # Handle nil/null values
+      return %w[not_equals not_in].include?(operator) if attribute_value.nil?
+
+      first_value = condition_values[0]
+      attribute_str = attribute_value.to_s.downcase
+      value_str = first_value.to_s.downcase
+
+      case operator
+      when 'equals'
+        attribute_str == value_str
+
+      when 'not_equals'
+        attribute_str != value_str
+
+      when 'contains'
+        attribute_str.include?(value_str)
+
+      when 'not_contains'
+        !attribute_str.include?(value_str)
+
+      when 'starts_with'
+        attribute_str.start_with?(value_str)
+
+      when 'ends_with'
+        attribute_str.end_with?(value_str)
+
+      when 'in'
+        condition_values.any? { |v| v.to_s.downcase == attribute_str }
+
+      when 'not_in'
+        condition_values.none? { |v| v.to_s.downcase == attribute_str }
+
+      when 'gt'
+        attribute_value.to_f > first_value.to_f
+
+      when 'gte'
+        attribute_value.to_f >= first_value.to_f
+
+      when 'lt'
+        attribute_value.to_f < first_value.to_f
+
+      when 'lte'
+        attribute_value.to_f <= first_value.to_f
+
+      when 'between'
+        return false if condition_values.length < 2
+
+        num = attribute_value.to_f
+        num.between?(condition_values[0].to_f, condition_values[1].to_f)
+
+      when 'regex'
+        begin
+          regex = Regexp.new(first_value.to_s)
+          regex.match?(attribute_value.to_s)
+        rescue RegexpError
+          false
+        end
+
+      when 'semver_eq'
+        compare_semver(attribute_value, first_value).zero?
+
+      when 'semver_gt'
+        compare_semver(attribute_value, first_value).positive?
+
+      when 'semver_gte'
+        compare_semver(attribute_value, first_value) >= 0
+
+      when 'semver_lt'
+        compare_semver(attribute_value, first_value).negative?
+
+      when 'semver_lte'
+        compare_semver(attribute_value, first_value) <= 0
+
+      else
+        # Unknown operator - log warning and return false
+        warn "[ToggleCraft] Unknown operator: #{operator}"
+        false
+      end
+    end
+  end
+end

data/lib/togglecraft/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ToggleCraft
+  VERSION = '1.0.0'
+end

data/lib/togglecraft.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+require 'http'
+require 'cgi'
+require 'timeout'
+
+require_relative 'togglecraft/version'
+require_relative 'togglecraft/utils'
+require_relative 'togglecraft/cache'
+require_relative 'togglecraft/evaluator'
+require_relative 'togglecraft/sse_connection'
+require_relative 'togglecraft/shared_sse_connection'
+require_relative 'togglecraft/connection_pool'
+require_relative 'togglecraft/client'
+
+module ToggleCraft
+  class Error < StandardError; end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'simplecov'
+SimpleCov.start do
+  add_filter '/spec/'
+end
+
+require 'togglecraft'
+require 'webmock/rspec'
+
+RSpec.configure do |config|
+  # Enable flags like --only-failures and --next-failure
+  config.example_status_persistence_file_path = '.rspec_status'
+
+  # Disable RSpec exposing methods globally on `Module` and `main`
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+
+  # Disable external HTTP requests during tests
+  config.before(:each) do
+    WebMock.disable_net_connect!(allow_localhost: true)
+  end
+end

data/spec/togglecraft/cache/memory_adapter_spec.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+RSpec.describe ToggleCraft::CacheAdapters::MemoryAdapter do
+  let(:adapter) { described_class.new }
+
+  describe '#get' do
+    it 'returns nil for non-existent keys' do
+      expect(adapter.get('missing')).to be_nil
+    end
+
+    it 'returns the stored value' do
+      adapter.set('key', 'value')
+      expect(adapter.get('key')).to eq('value')
+    end
+  end
+
+  describe '#set' do
+    it 'stores a value' do
+      adapter.set('key', 'value')
+      expect(adapter.get('key')).to eq('value')
+    end
+
+    it 'overwrites existing values' do
+      adapter.set('key', 'old')
+      adapter.set('key', 'new')
+      expect(adapter.get('key')).to eq('new')
+    end
+
+    it 'stores different types of values' do
+      adapter.set('string', 'text')
+      adapter.set('number', 123)
+      adapter.set('hash', { foo: 'bar' })
+      adapter.set('array', [1, 2, 3])
+
+      expect(adapter.get('string')).to eq('text')
+      expect(adapter.get('number')).to eq(123)
+      expect(adapter.get('hash')).to eq({ foo: 'bar' })
+      expect(adapter.get('array')).to eq([1, 2, 3])
+    end
+  end
+
+  describe '#delete' do
+    it 'removes a value and returns true' do
+      adapter.set('key', 'value')
+      result = adapter.delete('key')
+      expect(result).to be true
+      expect(adapter.get('key')).to be_nil
+    end
+
+    it 'returns false for non-existent keys' do
+      expect(adapter.delete('missing')).to be false
+    end
+  end
+
+  describe '#clear' do
+    it 'removes all values' do
+      adapter.set('key1', 'value1')
+      adapter.set('key2', 'value2')
+      adapter.set('key3', 'value3')
+
+      adapter.clear
+
+      expect(adapter.get('key1')).to be_nil
+      expect(adapter.get('key2')).to be_nil
+      expect(adapter.get('key3')).to be_nil
+    end
+  end
+
+  describe '#has?' do
+    it 'returns true for existing keys' do
+      adapter.set('key', 'value')
+      expect(adapter.has?('key')).to be true
+    end
+
+    it 'returns false for non-existent keys' do
+      expect(adapter.has?('missing')).to be false
+    end
+
+    it 'returns false after deletion' do
+      adapter.set('key', 'value')
+      adapter.delete('key')
+      expect(adapter.has?('key')).to be false
+    end
+  end
+
+  describe '#keys' do
+    it 'returns an empty array when no keys exist' do
+      expect(adapter.keys).to eq([])
+    end
+
+    it 'returns all stored keys' do
+      adapter.set('key1', 'value1')
+      adapter.set('key2', 'value2')
+      adapter.set('key3', 'value3')
+
+      keys = adapter.keys
+      expect(keys).to contain_exactly('key1', 'key2', 'key3')
+    end
+
+    it 'does not include deleted keys' do
+      adapter.set('key1', 'value1')
+      adapter.set('key2', 'value2')
+      adapter.delete('key1')
+
+      keys = adapter.keys
+      expect(keys).to contain_exactly('key2')
+    end
+  end
+
+  describe 'thread safety' do
+    it 'handles concurrent reads and writes' do
+      threads = 10.times.map do |i|
+        Thread.new do
+          100.times do |j|
+            key = "thread_#{i}_key_#{j}"
+            adapter.set(key, "value_#{j}")
+            expect(adapter.get(key)).to eq("value_#{j}")
+          end
+        end
+      end
+
+      threads.each(&:join)
+
+      # Verify all values were stored correctly
+      expect(adapter.keys.length).to eq(1000)
+    end
+  end
+end