togglecraft 1.0.0

data/spec/togglecraft/client_spec.rb

@@ -0,0 +1,728 @@
+# frozen_string_literal: true
+
+RSpec.describe ToggleCraft::Client do
+  let(:sdk_key) { 'test-sdk-key-12345' }
+  let(:client) { described_class.new(sdk_key: sdk_key, debug: false) }
+
+  after do
+    client.destroy if client
+    ToggleCraft::ConnectionPool.clear(force: true)
+  end
+
+  describe '#initialize' do
+    it 'requires sdk_key parameter' do
+      expect { described_class.new }.to raise_error(ArgumentError, /sdk_key/)
+    end
+
+    it 'raises error when sdk_key is nil' do
+      expect { described_class.new(sdk_key: nil) }.to raise_error(ArgumentError, 'sdk_key is required')
+    end
+
+    it 'raises error when sdk_key is empty string' do
+      expect { described_class.new(sdk_key: '') }.to raise_error(ArgumentError, 'sdk_key is required')
+    end
+
+    it 'sets default configuration options' do
+      expect(client.config[:url]).to eq('https://sse.togglecraft.io')
+      expect(client.config[:enable_cache]).to be true
+      expect(client.config[:cache_adapter]).to eq(:memory)
+      expect(client.config[:cache_ttl]).to eq(300)
+      expect(client.config[:reconnect_interval]).to eq(1)
+      expect(client.config[:max_reconnect_interval]).to eq(30)
+      expect(client.config[:max_reconnect_attempts]).to eq(10)
+      expect(client.config[:slow_reconnect_interval]).to eq(60)
+      expect(client.config[:share_connection]).to be true
+      expect(client.config[:debug]).to be false
+      expect(client.config[:enable_rollout_stage_polling]).to be true
+      expect(client.config[:rollout_stage_check_interval]).to eq(60)
+      expect(client.config[:fetch_jitter]).to eq(1500)
+    end
+
+    it 'allows custom configuration options' do
+      custom_client = described_class.new(
+        sdk_key: 'custom-key',
+        url: 'https://custom.example.com',
+        enable_cache: false,
+        cache_ttl: 600,
+        reconnect_interval: 5,
+        share_connection: false,
+        debug: true
+      )
+
+      expect(custom_client.config[:url]).to eq('https://custom.example.com')
+      expect(custom_client.config[:enable_cache]).to be false
+      expect(custom_client.config[:cache_ttl]).to eq(600)
+      expect(custom_client.config[:reconnect_interval]).to eq(5)
+      expect(custom_client.config[:share_connection]).to be false
+      expect(custom_client.config[:debug]).to be true
+
+      custom_client.destroy
+    end
+
+    it 'initializes ready state to false' do
+      expect(client.ready?).to be false
+    end
+
+    it 'initializes evaluator' do
+      evaluator = client.instance_variable_get(:@evaluator)
+      expect(evaluator).to be_a(ToggleCraft::Evaluator)
+    end
+
+    it 'initializes cache when enabled' do
+      cache = client.instance_variable_get(:@cache)
+      expect(cache).to be_a(ToggleCraft::Cache)
+    end
+
+    it 'does not initialize cache when disabled' do
+      no_cache_client = described_class.new(sdk_key: 'key', enable_cache: false)
+      cache = no_cache_client.instance_variable_get(:@cache)
+      expect(cache).to be_nil
+      no_cache_client.destroy
+    end
+
+    it 'initializes event listeners map' do
+      listeners = client.instance_variable_get(:@listeners)
+      expect(listeners.keys).to include(:ready, :flags_updated, :error, :disconnected, :reconnecting, :rollout_stage_changed)
+    end
+
+    it 'initializes connection (shared by default)' do
+      connection = client.instance_variable_get(:@connection)
+      expect(connection).to be_a(ToggleCraft::SharedSSEConnection)
+    end
+
+    it 'creates dedicated connection when share_connection is false' do
+      dedicated_client = described_class.new(sdk_key: 'key', share_connection: false)
+      connection = dedicated_client.instance_variable_get(:@connection)
+      expect(connection).to be_a(ToggleCraft::SSEConnection)
+      dedicated_client.destroy
+    end
+  end
+
+  describe '#ready?' do
+    it 'returns false initially' do
+      expect(client.ready?).to be false
+    end
+
+    it 'returns true after ready state is set' do
+      client.instance_variable_get(:@ready).make_true
+      expect(client.ready?).to be true
+    end
+
+    it 'returns false after disconnect' do
+      client.instance_variable_get(:@ready).make_true
+      client.handle_disconnect
+      expect(client.ready?).to be false
+    end
+  end
+
+  describe '#connected?' do
+    it 'returns false when connection is nil' do
+      client.instance_variable_set(:@connection, nil)
+      expect(client.connected?).to be false
+    end
+
+    it 'returns connection status when connection exists' do
+      connection = client.instance_variable_get(:@connection)
+      allow(connection).to receive(:connected?).and_return(true)
+      expect(client.connected?).to be true
+
+      allow(connection).to receive(:connected?).and_return(false)
+      expect(client.connected?).to be false
+    end
+  end
+
+  describe '#wait_for_ready' do
+    it 'returns immediately if already ready' do
+      client.instance_variable_get(:@ready).make_true
+      expect { client.wait_for_ready(timeout: 1) }.not_to raise_error
+    end
+
+    it 'waits for ready event' do
+      Thread.new do
+        sleep 0.1
+        client.instance_variable_get(:@ready).make_true
+        client.send(:emit, :ready)
+      end
+
+      expect { client.wait_for_ready(timeout: 2) }.not_to raise_error
+    end
+
+    it 'raises timeout error if not ready within timeout' do
+      expect do
+        client.wait_for_ready(timeout: 0.1)
+      end.to raise_error(Timeout::Error, /Timeout waiting for client to be ready/)
+    end
+
+    it 'attempts to clean up handler after timeout' do
+      # Test that timeout occurs without causing issues
+      expect do
+        client.wait_for_ready(timeout: 0.1)
+      end.to raise_error(Timeout::Error)
+
+      # Client should still be functional after timeout
+      expect(client.ready?).to be false
+    end
+  end
+
+  describe 'flag evaluation methods' do
+    before do
+      flags = {
+        'boolean-flag' => {
+          type: 'boolean',
+          enabled: true,
+          value: true
+        },
+        'multivariate-flag' => {
+          type: 'multivariate',
+          enabled: true,
+          default_variant: 'control',
+          variants: %w[control variant-a],
+          weights: { 'control' => 50, 'variant-a' => 50 }
+        },
+        'percentage-flag' => {
+          type: 'percentage',
+          enabled: true,
+          percentage: 50
+        }
+      }
+      evaluator = client.instance_variable_get(:@evaluator)
+      evaluator.update_flags(flags)
+    end
+
+    describe '#enabled?' do
+      it 'evaluates boolean flags' do
+        result = client.enabled?('boolean-flag')
+        expect(result).to be true
+      end
+
+      it 'returns default value for missing flags' do
+        expect(client.enabled?('missing', {}, default: false)).to be false
+        expect(client.enabled?('missing', {}, default: true)).to be true
+      end
+
+      it 'accepts context for evaluation' do
+        context = { user: { id: '123', role: 'admin' } }
+        result = client.enabled?('boolean-flag', context)
+        expect([true, false]).to include(result)
+      end
+
+      it 'caches evaluation results when cache is enabled' do
+        context = { user: { id: '123' } }
+        cache = client.instance_variable_get(:@cache)
+
+        client.enabled?('boolean-flag', context)
+
+        # Check cache was called
+        expect(cache.instance_variable_get(:@adapter).keys.any? { |k| k.start_with?('eval:') }).to be true
+      end
+
+      it 'does not cache when cache is disabled' do
+        no_cache_client = described_class.new(sdk_key: 'key', enable_cache: false)
+        evaluator = no_cache_client.instance_variable_get(:@evaluator)
+        evaluator.update_flags({ 'test' => { type: 'boolean', enabled: true, value: true } })
+
+        result = no_cache_client.enabled?('test', { user: { id: '123' } })
+        expect(result).to be true
+
+        no_cache_client.destroy
+      end
+    end
+
+    describe '#variant' do
+      it 'evaluates multivariate flags' do
+        context = { user: { id: '123' } }
+        result = client.variant('multivariate-flag', context)
+        expect(%w[control variant-a]).to include(result)
+      end
+
+      it 'returns default value for missing flags' do
+        expect(client.variant('missing', {}, default: 'default')).to eq('default')
+        expect(client.variant('missing', {}, default: nil)).to be_nil
+      end
+
+      it 'returns consistent variant for same user' do
+        context = { user: { id: 'user-123' } }
+        result1 = client.variant('multivariate-flag', context)
+        result2 = client.variant('multivariate-flag', context)
+        expect(result1).to eq(result2)
+      end
+
+      it 'caches evaluation results' do
+        context = { user: { id: '456' } }
+        cache = client.instance_variable_get(:@cache)
+
+        client.variant('multivariate-flag', context)
+
+        expect(cache.instance_variable_get(:@adapter).keys.any? { |k| k.start_with?('eval:') }).to be true
+      end
+    end
+
+    describe '#in_percentage?' do
+      it 'evaluates percentage flags' do
+        context = { user: { id: '123' } }
+        result = client.in_percentage?('percentage-flag', context)
+        expect([true, false]).to include(result)
+      end
+
+      it 'returns default value for missing flags' do
+        expect(client.in_percentage?('missing', {}, default: false)).to be false
+        expect(client.in_percentage?('missing', {}, default: true)).to be true
+      end
+
+      it 'returns consistent result for same user' do
+        context = { user: { id: 'consistent-user' } }
+        result1 = client.in_percentage?('percentage-flag', context)
+        result2 = client.in_percentage?('percentage-flag', context)
+        expect(result1).to eq(result2)
+      end
+    end
+
+    describe '#percentage' do
+      it 'returns current percentage for percentage flags' do
+        result = client.percentage('percentage-flag')
+        expect(result).to eq(50)
+      end
+
+      it 'returns nil for non-existent flags' do
+        expect(client.percentage('missing')).to be_nil
+      end
+
+      it 'returns nil for non-percentage flags' do
+        expect(client.percentage('boolean-flag')).to be_nil
+      end
+    end
+
+    describe '#evaluate' do
+      it 'evaluates any flag type' do
+        expect(client.evaluate('boolean-flag')).to be true
+        expect(%w[control variant-a]).to include(client.evaluate('multivariate-flag', { user: { id: '123' } }))
+        result = client.evaluate('percentage-flag', { user: { id: '123' } })
+        expect([true, false]).to include(result)
+      end
+
+      it 'returns default for missing flags' do
+        expect(client.evaluate('missing', {}, default: 'fallback')).to eq('fallback')
+      end
+    end
+
+    describe '#all_flag_keys' do
+      it 'returns all flag keys' do
+        keys = client.all_flag_keys
+        expect(keys).to include('boolean-flag', 'multivariate-flag', 'percentage-flag')
+        expect(keys.length).to eq(3)
+      end
+
+      it 'returns empty array when no flags' do
+        empty_client = described_class.new(sdk_key: 'key')
+        expect(empty_client.all_flag_keys).to eq([])
+        empty_client.destroy
+      end
+    end
+
+    describe '#flag_metadata' do
+      it 'returns metadata for existing flags' do
+        metadata = client.flag_metadata('boolean-flag')
+        expect(metadata[:type]).to eq('boolean')
+        expect(metadata[:enabled]).to be true
+      end
+
+      it 'returns nil for non-existent flags' do
+        expect(client.flag_metadata('missing')).to be_nil
+      end
+
+      it 'includes type-specific metadata' do
+        mv_metadata = client.flag_metadata('multivariate-flag')
+        expect(mv_metadata[:variants]).to eq(%w[control variant-a])
+        expect(mv_metadata[:default_variant]).to eq('control')
+
+        pct_metadata = client.flag_metadata('percentage-flag')
+        expect(pct_metadata[:percentage]).to eq(50)
+      end
+    end
+
+    describe '#has_flag?' do
+      it 'returns true for existing flags' do
+        expect(client.has_flag?('boolean-flag')).to be true
+      end
+
+      it 'returns false for non-existent flags' do
+        expect(client.has_flag?('missing')).to be false
+      end
+    end
+  end
+
+  describe 'event system' do
+    describe '#on' do
+      it 'registers event listener' do
+        called = false
+        client.on(:ready) { called = true }
+
+        client.send(:emit, :ready)
+        expect(called).to be true
+      end
+
+      it 'allows multiple listeners for same event' do
+        call_count = 0
+        client.on(:ready) { call_count += 1 }
+        client.on(:ready) { call_count += 1 }
+
+        client.send(:emit, :ready)
+        expect(call_count).to eq(2)
+      end
+
+      it 'passes arguments to listeners' do
+        received_data = nil
+        client.on(:flags_updated) { |data| received_data = data }
+
+        test_data = { 'flag' => 'value' }
+        client.send(:emit, :flags_updated, test_data)
+        expect(received_data).to eq(test_data)
+      end
+
+      it 'supports all event types' do
+        events_received = []
+
+        client.on(:ready) { events_received << :ready }
+        client.on(:flags_updated) { events_received << :flags_updated }
+        client.on(:error) { events_received << :error }
+        client.on(:disconnected) { events_received << :disconnected }
+        client.on(:reconnecting) { events_received << :reconnecting }
+        client.on(:rollout_stage_changed) { events_received << :rollout_stage_changed }
+
+        client.send(:emit, :ready)
+        client.send(:emit, :flags_updated, {})
+        client.send(:emit, :error, StandardError.new('test'))
+        client.send(:emit, :disconnected)
+        client.send(:emit, :reconnecting)
+        client.send(:emit, :rollout_stage_changed, {})
+
+        expect(events_received).to eq([:ready, :flags_updated, :error, :disconnected, :reconnecting, :rollout_stage_changed])
+      end
+
+      it 'handles errors in event listeners gracefully' do
+        client.on(:ready) { raise 'Listener error' }
+        client.on(:ready) { } # This should still be called
+
+        expect { client.send(:emit, :ready) }.not_to raise_error
+      end
+    end
+
+    describe '#once' do
+      it 'registers one-time event listener' do
+        call_count = 0
+        client.once(:ready) { call_count += 1 }
+
+        client.send(:emit, :ready)
+        client.send(:emit, :ready)
+
+        expect(call_count).to eq(1)
+      end
+
+      it 'receives event data' do
+        received = nil
+        client.once(:flags_updated) { |data| received = data }
+
+        client.send(:emit, :flags_updated, { test: 'data' })
+        expect(received).to eq({ test: 'data' })
+      end
+
+      it 'removes itself after execution' do
+        listeners_before = client.instance_variable_get(:@listeners)[:ready].length
+
+        client.once(:ready) { }
+        listeners_during = client.instance_variable_get(:@listeners)[:ready].length
+        expect(listeners_during).to eq(listeners_before + 1)
+
+        client.send(:emit, :ready)
+        listeners_after = client.instance_variable_get(:@listeners)[:ready].length
+        expect(listeners_after).to eq(listeners_before)
+      end
+    end
+
+    describe '#off' do
+      it 'removes specific listener' do
+        handler = -> { }
+        client.on(:ready, &handler)
+
+        client.off(:ready, handler)
+
+        listeners = client.instance_variable_get(:@listeners)[:ready]
+        expect(listeners).not_to include(handler)
+      end
+
+      it 'removes all listeners for event when no handler specified' do
+        client.on(:ready) { }
+        client.on(:ready) { }
+
+        client.off(:ready)
+
+        listeners = client.instance_variable_get(:@listeners)[:ready]
+        expect(listeners).to be_empty
+      end
+
+      it 'does not affect other events' do
+        client.on(:ready) { }
+        client.on(:error) { }
+
+        client.off(:ready)
+
+        expect(client.instance_variable_get(:@listeners)[:ready]).to be_empty
+        expect(client.instance_variable_get(:@listeners)[:error]).not_to be_empty
+      end
+    end
+  end
+
+  describe '#handle_flags_update' do
+    it 'processes full flags payload' do
+      payload = {
+        flags: {
+          'test-flag' => { type: 'boolean', enabled: true, value: true }
+        },
+        version: 1
+      }
+
+      client.handle_flags_update(payload)
+
+      expect(client.has_flag?('test-flag')).to be true
+      expect(client.instance_variable_get(:@current_version).get).to eq(1)
+    end
+
+    it 'handles version_update type messages' do
+      allow(client).to receive(:handle_version_update)
+
+      payload = {
+        type: 'version_update',
+        version: 2,
+        project_key: 'project',
+        environment_key: 'production'
+      }
+
+      client.handle_flags_update(payload)
+
+      expect(client).to have_received(:handle_version_update).with(payload)
+    end
+
+    it 'updates cache with new flags' do
+      cache = client.instance_variable_get(:@cache)
+
+      payload = {
+        flags: {
+          'cached-flag' => { type: 'boolean', enabled: true }
+        }
+      }
+
+      client.handle_flags_update(payload)
+
+      expect(cache.get('flag:cached-flag')).to eq({ type: 'boolean', enabled: true })
+    end
+
+    it 'emits ready event on first update' do
+      ready_called = false
+      client.on(:ready) { ready_called = true }
+
+      payload = {
+        flags: { 'flag' => { type: 'boolean', enabled: true } }
+      }
+
+      client.handle_flags_update(payload)
+
+      expect(ready_called).to be true
+      expect(client.ready?).to be true
+    end
+
+    it 'emits flags_updated event' do
+      flags_received = nil
+      client.on(:flags_updated) { |flags| flags_received = flags }
+
+      payload = {
+        flags: { 'flag' => { type: 'boolean', enabled: true } }
+      }
+
+      # Mark as ready first to avoid ready event
+      client.instance_variable_get(:@ready).make_true
+
+      client.handle_flags_update(payload)
+
+      expect(flags_received).to eq({ 'flag' => { type: 'boolean', enabled: true } })
+    end
+  end
+
+  describe '#handle_connect' do
+    it 'logs connection when debug is enabled' do
+      debug_client = described_class.new(sdk_key: 'key', debug: true)
+
+      expect { debug_client.handle_connect }.to output(/SSE connected/).to_stdout
+
+      debug_client.destroy
+    end
+
+    it 'does not raise errors' do
+      expect { client.handle_connect }.not_to raise_error
+    end
+  end
+
+  describe '#handle_disconnect' do
+    it 'sets ready state to false' do
+      client.instance_variable_get(:@ready).make_true
+
+      client.handle_disconnect
+
+      expect(client.ready?).to be false
+    end
+
+    it 'emits disconnected event' do
+      disconnected = false
+      client.on(:disconnected) { disconnected = true }
+
+      client.handle_disconnect
+
+      expect(disconnected).to be true
+    end
+  end
+
+  describe '#handle_error' do
+    it 'emits error event' do
+      error_received = nil
+      client.on(:error) { |e| error_received = e }
+
+      test_error = StandardError.new('Test error')
+      client.handle_error(test_error)
+
+      expect(error_received).to eq(test_error)
+    end
+
+    it 'logs error when debug is enabled' do
+      debug_client = described_class.new(sdk_key: 'key', debug: true)
+
+      expect do
+        debug_client.handle_error(StandardError.new('Test'))
+      end.to output(/Error: Test/).to_stdout
+
+      debug_client.destroy
+    end
+  end
+
+  describe '#destroy' do
+    it 'stops rollout stage polling' do
+      client.instance_variable_set(:@rollout_stage_timer, Thread.new { sleep })
+      timer = client.instance_variable_get(:@rollout_stage_timer)
+
+      client.destroy
+
+      sleep 0.1
+      expect(timer.alive?).to be false
+    end
+
+    it 'clears all listeners' do
+      client.on(:ready) { }
+      client.on(:error) { }
+
+      client.destroy
+
+      listeners = client.instance_variable_get(:@listeners)
+      expect(listeners[:ready]).to be_empty
+      expect(listeners[:error]).to be_empty
+    end
+
+    it 'clears flags' do
+      evaluator = client.instance_variable_get(:@evaluator)
+      evaluator.update_flags({ 'flag' => { type: 'boolean' } })
+
+      expect(client.all_flag_keys).not_to be_empty
+
+      flags = client.instance_variable_get(:@flags)
+      flags.clear
+
+      expect(client.instance_variable_get(:@flags)).to be_empty
+    end
+
+    it 'sets ready to false' do
+      client.instance_variable_get(:@ready).make_true
+
+      client.destroy
+
+      expect(client.ready?).to be false
+    end
+
+    it 'destroys cache when present' do
+      cache = client.instance_variable_get(:@cache)
+      expect(cache).to receive(:destroy).at_least(:once).and_call_original
+
+      client.destroy
+    end
+
+    it 'is safe to call multiple times' do
+      expect { client.destroy }.not_to raise_error
+      expect { client.destroy }.not_to raise_error
+    end
+  end
+
+  describe 'thread safety' do
+    it 'handles concurrent flag evaluations' do
+      evaluator = client.instance_variable_get(:@evaluator)
+      evaluator.update_flags({
+                               'flag' => { type: 'boolean', enabled: true, value: true }
+                             })
+
+      threads = 20.times.map do |i|
+        Thread.new do
+          100.times do
+            result = client.enabled?('flag', { user: { id: "user-#{i}" } })
+            expect(result).to be true
+          end
+        end
+      end
+
+      threads.each(&:join)
+    end
+
+    it 'handles concurrent listener registration' do
+      threads = 10.times.map do
+        Thread.new do
+          10.times do
+            client.on(:ready) { }
+          end
+        end
+      end
+
+      threads.each(&:join)
+
+      listeners = client.instance_variable_get(:@listeners)[:ready]
+      expect(listeners.length).to eq(100)
+    end
+
+    it 'handles concurrent event emission' do
+      call_count = Concurrent::AtomicFixnum.new(0)
+      client.on(:ready) { call_count.increment }
+
+      threads = 50.times.map do
+        Thread.new do
+          client.send(:emit, :ready)
+        end
+      end
+
+      threads.each(&:join)
+      expect(call_count.value).to eq(50)
+    end
+  end
+
+  describe 'connection mode' do
+    it 'uses shared connection by default' do
+      expect(client.instance_variable_get(:@using_shared_connection)).to be true
+      expect(client.instance_variable_get(:@connection)).to be_a(ToggleCraft::SharedSSEConnection)
+    end
+
+    it 'uses dedicated connection when share_connection is false' do
+      dedicated = described_class.new(sdk_key: 'key', share_connection: false)
+      expect(dedicated.instance_variable_get(:@using_shared_connection)).to be false
+      expect(dedicated.instance_variable_get(:@connection)).to be_a(ToggleCraft::SSEConnection)
+      dedicated.destroy
+    end
+
+    it 'enables debug on connection pool when debug is true and sharing is enabled' do
+      expect(ToggleCraft::ConnectionPool).to receive(:set_debug).with(true)
+      debug_client = described_class.new(sdk_key: 'key', debug: true, share_connection: true)
+      debug_client.destroy
+    end
+  end
+end