flagkit 1.0.1

data/lib/flagkit/core/polling_manager.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module FlagKit
+  module Core
+    # Manages background polling for flag updates.
+    class PollingManager
+      MAX_BACKOFF_MULTIPLIER = 4
+
+      attr_reader :interval, :running
+
+      # @param interval [Integer] Polling interval in seconds
+      # @param on_update [Proc] Callback when updates are received
+      # @param logger [Object, nil] Logger instance
+      def initialize(interval:, on_update:, logger: nil)
+        @interval = interval
+        @on_update = on_update
+        @logger = logger
+        @running = false
+        @last_update_time = nil
+        @consecutive_errors = 0
+        @mutex = Mutex.new
+        @thread = nil
+      end
+
+      # Starts the polling loop.
+      def start
+        @mutex.synchronize do
+          return if @running
+
+          @running = true
+          @thread = Thread.new { polling_loop }
+        end
+      end
+
+      # Stops the polling loop.
+      def stop
+        @mutex.synchronize do
+          @running = false
+        end
+        @thread&.join(5)
+        @thread = nil
+      end
+
+      # Checks if polling is running.
+      #
+      # @return [Boolean]
+      def running?
+        @mutex.synchronize { @running }
+      end
+
+      # Gets the last update timestamp.
+      #
+      # @return [Time, nil]
+      def last_update_time
+        @mutex.synchronize { @last_update_time }
+      end
+
+      # Manually triggers a poll.
+      #
+      # @return [Boolean] Whether the poll was successful
+      def poll_now
+        perform_poll
+      end
+
+      private
+
+      def polling_loop
+        while running?
+          sleep(current_interval_with_jitter)
+          break unless running?
+
+          perform_poll
+        end
+      end
+
+      def perform_poll
+        @on_update.call(@last_update_time)
+        @mutex.synchronize do
+          @last_update_time = Time.now
+          @consecutive_errors = 0
+        end
+        true
+      rescue StandardError => e
+        @mutex.synchronize do
+          @consecutive_errors += 1
+        end
+        log(:error, "Polling failed: #{e.message}")
+        false
+      end
+
+      def current_interval_with_jitter
+        base = interval * backoff_multiplier
+        jitter = base * 0.1 * rand
+        base + jitter
+      end
+
+      def backoff_multiplier
+        errors = @mutex.synchronize { @consecutive_errors }
+        [2**errors, MAX_BACKOFF_MULTIPLIER].min
+      end
+
+      def log(level, message)
+        return unless @logger
+
+        @logger.send(level, "[FlagKit::PollingManager] #{message}")
+      end
+    end
+  end
+
+  # Alias for backward compatibility
+  PollingManager = Core::PollingManager
+end

data/lib/flagkit/core/streaming_manager.rb

@@ -0,0 +1,469 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module FlagKit
+  module Core
+    # Connection states for streaming
+    module StreamingState
+      DISCONNECTED = :disconnected
+      CONNECTING = :connecting
+      CONNECTED = :connected
+      RECONNECTING = :reconnecting
+      FAILED = :failed
+    end
+
+    # SSE error codes from server
+    STREAM_ERROR_CODES = {
+      TOKEN_INVALID: 'TOKEN_INVALID',
+      TOKEN_EXPIRED: 'TOKEN_EXPIRED',
+      SUBSCRIPTION_SUSPENDED: 'SUBSCRIPTION_SUSPENDED',
+      CONNECTION_LIMIT: 'CONNECTION_LIMIT',
+      STREAMING_UNAVAILABLE: 'STREAMING_UNAVAILABLE'
+    }.freeze
+
+    # SSE error event data structure
+    class StreamErrorData
+      # @return [String] Error code (one of STREAM_ERROR_CODES values)
+      attr_reader :code
+
+      # @return [String] Human-readable error message
+      attr_reader :message
+
+      # @param code [String] Error code
+      # @param message [String] Error message
+      def initialize(code:, message:)
+        @code = code
+        @message = message
+      end
+    end
+
+    # Streaming configuration
+    class StreamingConfig
+      attr_reader :enabled, :reconnect_interval, :max_reconnect_attempts, :heartbeat_interval
+
+      def initialize(
+        enabled: true,
+        reconnect_interval: 3.0,
+        max_reconnect_attempts: 3,
+        heartbeat_interval: 30.0
+      )
+        @enabled = enabled
+        @reconnect_interval = reconnect_interval
+        @max_reconnect_attempts = max_reconnect_attempts
+        @heartbeat_interval = heartbeat_interval
+      end
+
+      def self.default
+        new
+      end
+    end
+
+    # Manages Server-Sent Events (SSE) connection for real-time flag updates.
+    #
+    # Security: Uses token exchange pattern to avoid exposing API keys in URLs.
+    # 1. Fetches short-lived token via POST with API key in header
+    # 2. Connects to SSE endpoint with disposable token in URL
+    #
+    # Features:
+    # - Secure token-based authentication
+    # - Automatic token refresh before expiry
+    # - Automatic reconnection with exponential backoff
+    # - Graceful degradation to polling after max failures
+    # - Heartbeat monitoring for connection health
+    # - SSE error event handling with appropriate callbacks
+    class StreamingManager
+      attr_reader :state
+
+      # @param base_url [String] Base URL for API endpoints
+      # @param get_api_key [Proc] Callable that returns the current API key
+      # @param config [StreamingConfig, nil] Streaming configuration
+      # @param on_flag_update [Proc] Callback when flag is updated
+      # @param on_flag_delete [Proc] Callback when flag is deleted
+      # @param on_flags_reset [Proc] Callback when all flags are reset
+      # @param on_fallback_to_polling [Proc] Callback when streaming fails and falls back to polling
+      # @param on_subscription_error [Proc, nil] Callback when subscription error occurs (e.g., suspended)
+      # @param on_connection_limit_error [Proc, nil] Callback when connection limit is reached
+      # @param logger [Object, nil] Logger instance
+      def initialize(
+        base_url:,
+        get_api_key:,
+        config: nil,
+        on_flag_update:,
+        on_flag_delete:,
+        on_flags_reset:,
+        on_fallback_to_polling:,
+        on_subscription_error: nil,
+        on_connection_limit_error: nil,
+        logger: nil
+      )
+        @base_url = base_url
+        @get_api_key = get_api_key
+        @config = config || StreamingConfig.default
+        @on_flag_update = on_flag_update
+        @on_flag_delete = on_flag_delete
+        @on_flags_reset = on_flags_reset
+        @on_fallback_to_polling = on_fallback_to_polling
+        @on_subscription_error = on_subscription_error
+        @on_connection_limit_error = on_connection_limit_error
+        @logger = logger
+
+        @state = StreamingState::DISCONNECTED
+        @consecutive_failures = 0
+        @last_heartbeat = Time.now
+        @mutex = Mutex.new
+        @stop_requested = false
+        @connection_thread = nil
+        @token_refresh_thread = nil
+        @heartbeat_thread = nil
+        @retry_thread = nil
+      end
+
+      def connected?
+        @state == StreamingState::CONNECTED
+      end
+
+      def connect
+        @mutex.synchronize do
+          return if @state == StreamingState::CONNECTED || @state == StreamingState::CONNECTING
+
+          @state = StreamingState::CONNECTING
+          @stop_requested = false
+        end
+
+        @connection_thread = Thread.new { initiate_connection }
+      end
+
+      def disconnect
+        @mutex.synchronize do
+          cleanup
+          @state = StreamingState::DISCONNECTED
+          @consecutive_failures = 0
+        end
+
+        @logger&.debug('Streaming disconnected')
+      end
+
+      def retry_connection
+        @mutex.synchronize do
+          return if @state == StreamingState::CONNECTED || @state == StreamingState::CONNECTING
+
+          @consecutive_failures = 0
+        end
+
+        connect
+      end
+
+      private
+
+      def initiate_connection
+        # Step 1: Fetch short-lived stream token
+        token_response = fetch_stream_token
+
+        # Step 2: Schedule token refresh at 80% of TTL
+        schedule_token_refresh(token_response[:expires_in] * 0.8)
+
+        # Step 3: Create SSE connection with token
+        create_connection(token_response[:token])
+      rescue StandardError => e
+        @logger&.error("Failed to fetch stream token: #{e.message}")
+        handle_connection_failure
+      end
+
+      def fetch_stream_token
+        token_uri = URI("#{@base_url}/sdk/stream/token")
+
+        http = Net::HTTP.new(token_uri.host, token_uri.port)
+        http.use_ssl = token_uri.scheme == 'https'
+
+        request = Net::HTTP::Post.new(token_uri.path)
+        request['Content-Type'] = 'application/json'
+        request['X-API-Key'] = @get_api_key.call
+        request.body = '{}'
+
+        response = http.request(request)
+        raise "Failed to fetch stream token: #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+        data = JSON.parse(response.body)
+        { token: data['token'], expires_in: data['expiresIn'] }
+      end
+
+      def schedule_token_refresh(delay)
+        @token_refresh_thread&.kill
+
+        @token_refresh_thread = Thread.new do
+          sleep(delay)
+          begin
+            token_response = fetch_stream_token
+            schedule_token_refresh(token_response[:expires_in] * 0.8)
+          rescue StandardError => e
+            @logger&.warn("Failed to refresh stream token, reconnecting: #{e.message}")
+            disconnect
+            connect
+          end
+        end
+      end
+
+      def create_connection(token)
+        stream_uri = URI("#{@base_url}/sdk/stream?token=#{token}")
+
+        http = Net::HTTP.new(stream_uri.host, stream_uri.port)
+        http.use_ssl = stream_uri.scheme == 'https'
+        http.read_timeout = nil # No timeout for SSE
+
+        request = Net::HTTP::Get.new(stream_uri)
+        request['Accept'] = 'text/event-stream'
+        request['Cache-Control'] = 'no-cache'
+
+        http.request(request) do |response|
+          unless response.is_a?(Net::HTTPSuccess)
+            @logger&.error("SSE connection failed: #{response.code}")
+            handle_connection_failure
+            return
+          end
+
+          handle_open
+          read_events(response)
+        end
+      rescue StandardError => e
+        return if @stop_requested
+
+        @logger&.error("SSE connection error: #{e.message}")
+        handle_connection_failure
+      end
+
+      def handle_open
+        @mutex.synchronize do
+          @state = StreamingState::CONNECTED
+          @consecutive_failures = 0
+          @last_heartbeat = Time.now
+        end
+
+        start_heartbeat_monitor
+        @logger&.info('Streaming connected')
+      end
+
+      def read_events(response)
+        event_type = nil
+        data_buffer = +''
+
+        response.read_body do |chunk|
+          return if @stop_requested
+
+          chunk.each_line do |line|
+            line = line.strip
+
+            # Empty line = end of event
+            if line.empty?
+              if event_type && !data_buffer.empty?
+                process_event(event_type, data_buffer)
+                event_type = nil
+                data_buffer = +''
+              end
+              next
+            end
+
+            # Parse SSE format
+            if line.start_with?('event:')
+              event_type = line[6..].strip
+            elsif line.start_with?('data:')
+              data_buffer << line[5..].strip
+            end
+          end
+        end
+
+        # Connection closed
+        handle_connection_failure if @state == StreamingState::CONNECTED
+      end
+
+      def process_event(event_type, data)
+        case event_type
+        when 'flag_updated'
+          flag_data = JSON.parse(data)
+          flag = Types::FlagState.new(
+            key: flag_data['key'],
+            value: flag_data['value'],
+            enabled: flag_data['enabled'] || true,
+            version: flag_data['version'] || 0,
+            flag_type: flag_data['flagType'],
+            last_modified: flag_data['lastModified']
+          )
+          @on_flag_update.call(flag)
+
+        when 'flag_deleted'
+          delete_data = JSON.parse(data)
+          @on_flag_delete.call(delete_data['key'])
+
+        when 'flags_reset'
+          flags_data = JSON.parse(data)
+          flags = flags_data.map do |f|
+            Types::FlagState.new(
+              key: f['key'],
+              value: f['value'],
+              enabled: f['enabled'] || true,
+              version: f['version'] || 0,
+              flag_type: f['flagType'],
+              last_modified: f['lastModified']
+            )
+          end
+          @on_flags_reset.call(flags)
+
+        when 'heartbeat'
+          @mutex.synchronize { @last_heartbeat = Time.now }
+
+        when 'error'
+          handle_stream_error(data)
+        end
+      rescue StandardError => e
+        @logger&.warn("Failed to process event #{event_type}: #{e.message}")
+      end
+
+      # Handles SSE error events from server.
+      #
+      # Error codes:
+      # - TOKEN_INVALID: Re-authenticate completely
+      # - TOKEN_EXPIRED: Refresh token and reconnect
+      # - SUBSCRIPTION_SUSPENDED: Notify user, fall back to cached values
+      # - CONNECTION_LIMIT: Implement backoff or close other connections
+      # - STREAMING_UNAVAILABLE: Fall back to polling
+      #
+      # @param data [String] JSON error data
+      def handle_stream_error(data)
+        error_data = JSON.parse(data)
+        code = error_data['code']
+        message = error_data['message']
+
+        stream_error = StreamErrorData.new(code: code, message: message)
+
+        @logger&.warn("SSE error event received: code=#{code}, message=#{message}")
+
+        case code
+        when STREAM_ERROR_CODES[:TOKEN_EXPIRED]
+          # Token expired, refresh and reconnect
+          @logger&.info('Stream token expired, refreshing...')
+          cleanup
+          connect # Will fetch new token
+
+        when STREAM_ERROR_CODES[:TOKEN_INVALID]
+          # Token is invalid, need full re-authentication
+          @logger&.error('Stream token invalid, re-authenticating...')
+          cleanup
+          connect # Will fetch new token
+
+        when STREAM_ERROR_CODES[:SUBSCRIPTION_SUSPENDED]
+          # Subscription issue - notify and fall back
+          @logger&.error("Subscription suspended: #{message}")
+          @on_subscription_error&.call(message)
+          cleanup
+          @mutex.synchronize { @state = StreamingState::FAILED }
+          @on_fallback_to_polling.call
+
+        when STREAM_ERROR_CODES[:CONNECTION_LIMIT]
+          # Too many connections - implement backoff
+          @logger&.warn('Connection limit reached, backing off...')
+          @on_connection_limit_error&.call
+          handle_connection_failure
+
+        when STREAM_ERROR_CODES[:STREAMING_UNAVAILABLE]
+          # Streaming not available - fall back to polling
+          @logger&.warn('Streaming service unavailable, falling back to polling')
+          cleanup
+          @mutex.synchronize { @state = StreamingState::FAILED }
+          @on_fallback_to_polling.call
+
+        else
+          @logger&.warn("Unknown stream error code: #{code}")
+          handle_connection_failure
+        end
+      rescue JSON::ParserError => e
+        @logger&.warn("Failed to parse stream error: #{e.message}")
+        handle_connection_failure
+      end
+
+      def handle_connection_failure
+        @mutex.synchronize do
+          cleanup
+          @consecutive_failures += 1
+          failures = @consecutive_failures
+          max_attempts = @config.max_reconnect_attempts
+
+          if failures >= max_attempts
+            @state = StreamingState::FAILED
+            @logger&.warn("Streaming failed, falling back to polling. Failures: #{failures}")
+            @on_fallback_to_polling.call
+            schedule_streaming_retry
+          else
+            @state = StreamingState::RECONNECTING
+            schedule_reconnect
+          end
+        end
+      end
+
+      def schedule_reconnect
+        delay = get_reconnect_delay
+        @logger&.debug("Scheduling reconnect in #{delay}s, attempt #{@consecutive_failures}")
+
+        Thread.new do
+          sleep(delay)
+          connect
+        end
+      end
+
+      def get_reconnect_delay
+        base_delay = @config.reconnect_interval
+        backoff = 2**(@consecutive_failures - 1)
+        delay = base_delay * backoff
+        # Cap at 30 seconds
+        [delay, 30.0].min
+      end
+
+      def schedule_streaming_retry
+        @retry_thread&.kill
+
+        @retry_thread = Thread.new do
+          sleep(300) # 5 minutes
+          @logger&.info('Retrying streaming connection')
+          retry_connection
+        end
+      end
+
+      def start_heartbeat_monitor
+        stop_heartbeat_monitor
+
+        check_interval = @config.heartbeat_interval * 1.5
+
+        @heartbeat_thread = Thread.new do
+          sleep(check_interval)
+
+          time_since = Time.now - @last_heartbeat
+          threshold = @config.heartbeat_interval * 2
+
+          if time_since > threshold
+            @logger&.warn("Heartbeat timeout, reconnecting. Time since: #{time_since}s")
+            handle_connection_failure
+          else
+            start_heartbeat_monitor
+          end
+        end
+      end
+
+      def stop_heartbeat_monitor
+        @heartbeat_thread&.kill
+        @heartbeat_thread = nil
+      end
+
+      def cleanup
+        @stop_requested = true
+        @connection_thread&.kill
+        @connection_thread = nil
+        @token_refresh_thread&.kill
+        @token_refresh_thread = nil
+        stop_heartbeat_monitor
+        @retry_thread&.kill
+        @retry_thread = nil
+      end
+    end
+  end
+end

data/lib/flagkit/error/error_code.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module FlagKit
+  # Error codes for FlagKit SDK errors.
+  module ErrorCode
+    # Initialization errors
+    INIT_FAILED = "INIT_FAILED"
+    INIT_TIMEOUT = "INIT_TIMEOUT"
+    INIT_ALREADY_INITIALIZED = "INIT_ALREADY_INITIALIZED"
+    INIT_NOT_INITIALIZED = "INIT_NOT_INITIALIZED"
+
+    # Authentication errors
+    AUTH_INVALID_KEY = "AUTH_INVALID_KEY"
+    AUTH_EXPIRED_KEY = "AUTH_EXPIRED_KEY"
+    AUTH_MISSING_KEY = "AUTH_MISSING_KEY"
+    AUTH_UNAUTHORIZED = "AUTH_UNAUTHORIZED"
+    AUTH_PERMISSION_DENIED = "AUTH_PERMISSION_DENIED"
+    AUTH_ENVIRONMENT_MISMATCH = "AUTH_ENVIRONMENT_MISMATCH"
+    AUTH_IP_RESTRICTED = "AUTH_IP_RESTRICTED"
+    AUTH_ORGANIZATION_REQUIRED = "AUTH_ORGANIZATION_REQUIRED"
+    AUTH_SUBSCRIPTION_SUSPENDED = "AUTH_SUBSCRIPTION_SUSPENDED"
+
+    # Network errors
+    NETWORK_ERROR = "NETWORK_ERROR"
+    NETWORK_TIMEOUT = "NETWORK_TIMEOUT"
+    NETWORK_RETRY_LIMIT = "NETWORK_RETRY_LIMIT"
+    NETWORK_INVALID_RESPONSE = "NETWORK_INVALID_RESPONSE"
+    NETWORK_SERVICE_UNAVAILABLE = "NETWORK_SERVICE_UNAVAILABLE"
+
+    # Evaluation errors
+    EVAL_FLAG_NOT_FOUND = "EVAL_FLAG_NOT_FOUND"
+    EVAL_TYPE_MISMATCH = "EVAL_TYPE_MISMATCH"
+    EVAL_INVALID_KEY = "EVAL_INVALID_KEY"
+    EVAL_INVALID_VALUE = "EVAL_INVALID_VALUE"
+    EVAL_DISABLED = "EVAL_DISABLED"
+    EVAL_ERROR = "EVAL_ERROR"
+    EVAL_CONTEXT_ERROR = "EVAL_CONTEXT_ERROR"
+    EVAL_DEFAULT_USED = "EVAL_DEFAULT_USED"
+    EVAL_STALE_VALUE = "EVAL_STALE_VALUE"
+    EVAL_CACHE_MISS = "EVAL_CACHE_MISS"
+    EVAL_NETWORK_ERROR = "EVAL_NETWORK_ERROR"
+    EVAL_PARSE_ERROR = "EVAL_PARSE_ERROR"
+    EVAL_TIMEOUT_ERROR = "EVAL_TIMEOUT_ERROR"
+
+    # Cache errors
+    CACHE_READ_ERROR = "CACHE_READ_ERROR"
+    CACHE_WRITE_ERROR = "CACHE_WRITE_ERROR"
+    CACHE_INVALID_DATA = "CACHE_INVALID_DATA"
+    CACHE_EXPIRED = "CACHE_EXPIRED"
+    CACHE_STORAGE_ERROR = "CACHE_STORAGE_ERROR"
+
+    # Event errors
+    EVENT_QUEUE_FULL = "EVENT_QUEUE_FULL"
+    EVENT_INVALID_TYPE = "EVENT_INVALID_TYPE"
+    EVENT_INVALID_DATA = "EVENT_INVALID_DATA"
+    EVENT_SEND_FAILED = "EVENT_SEND_FAILED"
+    EVENT_FLUSH_FAILED = "EVENT_FLUSH_FAILED"
+    EVENT_FLUSH_TIMEOUT = "EVENT_FLUSH_TIMEOUT"
+
+    # Circuit breaker errors
+    CIRCUIT_OPEN = "CIRCUIT_OPEN"
+
+    # Configuration errors
+    CONFIG_INVALID_URL = "CONFIG_INVALID_URL"
+    CONFIG_INVALID_INTERVAL = "CONFIG_INVALID_INTERVAL"
+    CONFIG_MISSING_REQUIRED = "CONFIG_MISSING_REQUIRED"
+    CONFIG_INVALID_API_KEY = "CONFIG_INVALID_API_KEY"
+    CONFIG_INVALID_BASE_URL = "CONFIG_INVALID_BASE_URL"
+    CONFIG_INVALID_POLLING_INTERVAL = "CONFIG_INVALID_POLLING_INTERVAL"
+    CONFIG_INVALID_CACHE_TTL = "CONFIG_INVALID_CACHE_TTL"
+    CONFIG_INVALID_BOOTSTRAP = "CONFIG_INVALID_BOOTSTRAP"
+
+    # Security errors
+    SECURITY_LOCAL_PORT_IN_PRODUCTION = "SECURITY_LOCAL_PORT_IN_PRODUCTION"
+    SECURITY_PII_DETECTED = "SECURITY_PII_DETECTED"
+    SECURITY_ENCRYPTION_ERROR = "SECURITY_ENCRYPTION_ERROR"
+
+    # Streaming errors (1800-1899)
+    STREAMING_TOKEN_INVALID = "STREAMING_TOKEN_INVALID"
+    STREAMING_TOKEN_EXPIRED = "STREAMING_TOKEN_EXPIRED"
+    STREAMING_SUBSCRIPTION_SUSPENDED = "STREAMING_SUBSCRIPTION_SUSPENDED"
+    STREAMING_CONNECTION_LIMIT = "STREAMING_CONNECTION_LIMIT"
+    STREAMING_UNAVAILABLE = "STREAMING_UNAVAILABLE"
+
+    RECOVERABLE_CODES = [
+      NETWORK_ERROR, NETWORK_TIMEOUT, NETWORK_RETRY_LIMIT,
+      NETWORK_SERVICE_UNAVAILABLE,
+      CIRCUIT_OPEN, CACHE_EXPIRED, EVAL_STALE_VALUE,
+      EVAL_CACHE_MISS, EVAL_NETWORK_ERROR, EVENT_SEND_FAILED,
+      STREAMING_TOKEN_INVALID, STREAMING_TOKEN_EXPIRED,
+      STREAMING_CONNECTION_LIMIT, STREAMING_UNAVAILABLE
+    ].freeze
+
+    def self.recoverable?(code)
+      RECOVERABLE_CODES.include?(code)
+    end
+  end
+end