toggly 0.1.0

data/lib/toggly/definitions_provider.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+begin
+  require "websocket-client-simple"
+  HAS_WEBSOCKET = true
+rescue LoadError
+  HAS_WEBSOCKET = false
+end
+
+module Toggly
+  # Provider for fetching feature definitions from Toggly API.
+  class DefinitionsProvider
+    # Fallback HTTP refresh interval when WebSocket is connected (20 minutes)
+    FALLBACK_REFRESH_INTERVAL = 20 * 60
+
+    # Delay before attempting WebSocket reconnection (seconds)
+    WS_RECONNECT_DELAY = 5
+
+    # @return [Boolean] Whether the WebSocket connection is active
+    attr_reader :ws_connected
+
+    # @param config [Config] Configuration
+    # @param logger [Logger, nil] Optional logger
+    # @param on_definitions_updated [Proc, nil] Callback when WS signals an update
+    def initialize(config:, logger: nil, on_definitions_updated: nil)
+      @config = config
+      @logger = logger
+      @on_definitions_updated = on_definitions_updated
+      @etag = nil
+      @last_modified = nil
+
+      # WebSocket state
+      @ws = nil
+      @ws_connected = false
+      @ws_thread = nil
+      @ws_closing = false
+      @last_fallback_refresh = nil
+    end
+
+    # Fetch definitions from the API
+    #
+    # @param force [Boolean] Force fetch even if cached
+    # @return [Hash, nil] Hash of definitions, or nil if not modified
+    # @raise [NetworkError] On network failures
+    # @raise [DefinitionsError] On API errors
+    def fetch(force: false)
+      return nil if @config.offline_mode?
+
+      uri = URI.parse(@config.definitions_endpoint)
+      http = build_http(uri)
+      request = build_request(uri, force)
+
+      response = http.request(request)
+      handle_response(response)
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      raise NetworkError, "Request timeout: #{e.message}"
+    rescue SocketError, Errno::ECONNREFUSED => e
+      raise NetworkError, "Connection failed: #{e.message}"
+    rescue StandardError => e
+      raise NetworkError, "Request failed: #{e.message}"
+    end
+
+    # Reset cached headers (force full fetch next time)
+    def reset_cache
+      @etag = nil
+      @last_modified = nil
+    end
+
+    # Check whether the periodic refresh should be skipped because the
+    # WebSocket connection is active and the fallback interval has not elapsed.
+    #
+    # @return [Boolean] true if the refresh should be skipped
+    def should_skip_refresh?
+      return false unless @ws_connected
+      return false if @last_fallback_refresh.nil?
+
+      if (Time.now - @last_fallback_refresh) < FALLBACK_REFRESH_INTERVAL
+        log_debug("WebSocket connected; skipping periodic HTTP refresh")
+        true
+      else
+        @last_fallback_refresh = Time.now
+        false
+      end
+    end
+
+    # Start a WebSocket connection for live definition updates.
+    # Requires the `websocket-client-simple` gem. If the gem is not installed
+    # this method logs a message and returns without error.
+    def start_websocket
+      unless HAS_WEBSOCKET
+        log_debug("websocket-client-simple gem not available; live updates disabled")
+        return
+      end
+
+      return if @config.offline_mode?
+
+      @ws_closing = false
+
+      @ws_thread = Thread.new do
+        loop do
+          break if @ws_closing
+
+          connect_websocket
+          break if @ws_closing
+
+          log_debug("WebSocket disconnected, reconnecting in #{WS_RECONNECT_DELAY}s")
+          sleep(WS_RECONNECT_DELAY)
+        end
+      end
+
+      @ws_thread.abort_on_exception = false
+    end
+
+    # Stop the WebSocket connection and its management thread.
+    def stop_websocket
+      @ws_closing = true
+      @ws_connected = false
+
+      if @ws
+        begin
+          @ws.close
+        rescue StandardError
+          # Ignore errors during close
+        end
+        @ws = nil
+      end
+
+      return unless @ws_thread
+
+      @ws_thread.kill
+      @ws_thread = nil
+    end
+
+    private
+
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @config.http_timeout
+      http.read_timeout = @config.http_timeout
+      http
+    end
+
+    def build_request(uri, force)
+      request = Net::HTTP::Get.new(uri)
+      request["Accept"] = "application/json"
+      request["User-Agent"] = "toggly-ruby/#{Toggly::VERSION}"
+
+      # Add app version if configured
+      request["X-App-Version"] = @config.app_version if @config.app_version
+
+      # Add instance name if configured
+      request["X-Instance-Name"] = @config.instance_name if @config.instance_name
+
+      # Add conditional headers unless forcing
+      unless force
+        request["If-None-Match"] = @etag if @etag
+        request["If-Modified-Since"] = @last_modified if @last_modified
+      end
+
+      request
+    end
+
+    def handle_response(response)
+      case response.code.to_i
+      when 200
+        parse_definitions(response)
+      when 304
+        # Not modified
+        log_debug("Definitions not modified")
+        nil
+      when 401, 403
+        raise DefinitionsError, "Authentication failed: #{response.code}"
+      when 404
+        raise DefinitionsError, "Definitions not found (check app_key and environment)"
+      else
+        raise NetworkError.new(
+          "API error: #{response.code}",
+          status_code: response.code.to_i,
+          response_body: response.body
+        )
+      end
+    end
+
+    def parse_definitions(response)
+      # Cache headers for conditional requests
+      @etag = response["ETag"]
+      @last_modified = response["Last-Modified"]
+
+      data = JSON.parse(response.body)
+      features = if data.is_a?(Hash)
+                   data["defs"] || data["features"] || data
+                 else
+                   data
+                 end
+
+      # Handle both array and object formats
+      if features.is_a?(Array)
+        features.each_with_object({}) do |item, hash|
+          definition = FeatureDefinition.from_hash(item)
+          hash[definition.feature_key] = definition
+        end
+      elsif features.is_a?(Hash)
+        features.transform_values { |v| FeatureDefinition.from_hash(v) }
+      else
+        raise DefinitionsError, "Invalid definitions format"
+      end
+    rescue JSON::ParserError => e
+      raise DefinitionsError, "Failed to parse definitions: #{e.message}"
+    end
+
+    def build_websocket_url
+      base = @config.definitions_url || @config.base_url
+      ws_url = base.gsub(%r{^https://}, "wss://").gsub(%r{^http://}, "ws://")
+      ws_url = ws_url.chomp("/")
+      "#{ws_url}/#{@config.app_key}/ws"
+    end
+
+    def connect_websocket
+      url = build_websocket_url
+      log_debug("Connecting WebSocket to: #{url}")
+
+      provider = self
+      connected_flag = false
+
+      begin
+        @ws = WebSocket::Client::Simple.connect(url)
+      rescue StandardError => e
+        log_error("Failed to create WebSocket: #{e.message}")
+        @ws = nil
+        return
+      end
+
+      @ws.on :open do
+        provider.instance_variable_set(:@ws_connected, true)
+        provider.instance_variable_set(:@last_fallback_refresh, Time.now)
+        connected_flag = true
+        provider.send(:log_debug, "WebSocket connected")
+      end
+
+      @ws.on :message do |msg|
+        text = msg.data.to_s
+        data = JSON.parse(text)
+        msg_type = data["type"]
+
+        next if msg_type == "ping"
+
+        if %w[flags-updated update].include?(msg_type)
+          provider.send(:log_debug, "WebSocket: definitions updated, refreshing")
+          provider.instance_variable_get(:@on_definitions_updated)&.call
+        end
+      rescue JSON::ParserError
+        # Non-JSON message - check for plain text signals
+        plain = msg.data.to_s.strip
+        if %w[update flags-updated].include?(plain)
+          provider.send(:log_debug, "WebSocket: definitions updated (plain text), refreshing")
+          provider.instance_variable_get(:@on_definitions_updated)&.call
+        end
+      end
+
+      @ws.on :error do |e|
+        provider.send(:log_error, "WebSocket error: #{e.message}")
+      end
+
+      @ws.on :close do |_e|
+        provider.instance_variable_set(:@ws_connected, false)
+        provider.instance_variable_set(:@ws, nil)
+        connected_flag = false
+        provider.send(:log_debug, "WebSocket connection closed")
+      end
+
+      # Block until disconnected or closing
+      sleep(0.1) until !@ws || @ws_closing || (@ws && !@ws.open?)
+    end
+
+    def log_debug(message)
+      @logger&.debug("[Toggly] #{message}")
+    end
+
+    def log_error(message)
+      @logger&.error("[Toggly] #{message}")
+    end
+  end
+end

data/lib/toggly/errors.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Toggly
+  # Base error class for all Toggly errors
+  class Error < StandardError; end
+
+  # Raised when configuration is invalid
+  class ConfigError < Error; end
+
+  # Raised when network requests fail
+  class NetworkError < Error
+    attr_reader :status_code, :response_body
+
+    def initialize(message, status_code: nil, response_body: nil)
+      super(message)
+      @status_code = status_code
+      @response_body = response_body
+    end
+  end
+
+  # Raised when definitions cannot be fetched
+  class DefinitionsError < Error; end
+
+  # Raised when feature evaluation fails
+  class EvaluationError < Error
+    attr_reader :feature_key
+
+    def initialize(message, feature_key: nil)
+      super(message)
+      @feature_key = feature_key
+    end
+  end
+
+  # Raised when snapshot operations fail
+  class SnapshotError < Error; end
+
+  # Raised when signed definitions verification fails
+  class SignatureError < Error; end
+
+  # Raised when the client is not initialized
+  class NotInitializedError < Error
+    def initialize(message = "Toggly client is not initialized")
+      super
+    end
+  end
+
+  # Raised when a feature is not found
+  class FeatureNotFoundError < Error
+    attr_reader :feature_key
+
+    def initialize(feature_key)
+      @feature_key = feature_key
+      super("Feature not found: #{feature_key}")
+    end
+  end
+end

data/lib/toggly/evaluation_engine.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Toggly
+  # Engine for evaluating feature flags.
+  #
+  # Processes feature definitions and their rules to determine
+  # if a feature should be enabled for a given context.
+  class EvaluationEngine
+    # @param registry [Registry] Evaluator registry
+    # @param logger [Logger, nil] Optional logger
+    def initialize(registry: nil, logger: nil)
+      @registry = registry || Registry.new
+      @logger = logger
+    end
+
+    # Evaluate a feature for a context
+    #
+    # @param definition [FeatureDefinition] The feature definition
+    # @param context [Context, nil] The evaluation context
+    # @return [Boolean] Whether the feature is enabled
+    def evaluate(definition, context = nil)
+      return false unless definition
+
+      # If feature is globally disabled, return false
+      return false unless definition.enabled
+
+      # If no rules, feature is simply on/off based on enabled flag
+      return definition.enabled unless definition.rules?
+
+      # Evaluate rules in order
+      evaluate_rules(definition, context)
+    end
+
+    # Evaluate with detailed result
+    #
+    # @param definition [FeatureDefinition] The feature definition
+    # @param context [Context, nil] The evaluation context
+    # @return [EvaluationResult] Detailed evaluation result
+    def evaluate_with_details(definition, context = nil)
+      result = EvaluationResult.new(
+        feature_key: definition&.feature_key,
+        enabled: false,
+        reason: "unknown"
+      )
+
+      unless definition
+        result.reason = "feature_not_found"
+        return result
+      end
+
+      unless definition.enabled
+        result.reason = "globally_disabled"
+        return result
+      end
+
+      unless definition.rules?
+        result.enabled = true
+        result.reason = "globally_enabled"
+        return result
+      end
+
+      result.enabled = evaluate_rules(definition, context, result)
+      result
+    end
+
+    # @return [Registry]
+    attr_reader :registry
+
+    private
+
+    def evaluate_rules(definition, context, result = nil)
+      definition.rules.each_with_index do |rule, index|
+        rule_type = rule["type"] || rule[:type] || "always_on"
+        evaluator = @registry.get(rule_type)
+
+        unless evaluator
+          log_warn("Unknown evaluator type: #{rule_type} for feature #{definition.feature_key}")
+          next
+        end
+
+        begin
+          evaluation = evaluator.evaluate(rule, context, feature_key: definition.feature_key)
+
+          # nil means continue to next rule
+          next if evaluation.nil?
+
+          if result
+            result.matched_rule = rule
+            result.matched_rule_index = index
+            result.reason = "rule_matched"
+          end
+
+          return evaluation
+        rescue StandardError => e
+          log_error("Error evaluating rule #{index} for #{definition.feature_key}: #{e.message}")
+          next
+        end
+      end
+
+      # No rules matched, default to enabled (since the feature itself is enabled)
+      result&.reason = "default_enabled"
+      true
+    end
+
+    def log_warn(message)
+      @logger&.warn("[Toggly] #{message}")
+    end
+
+    def log_error(message)
+      @logger&.error("[Toggly] #{message}")
+    end
+  end
+
+  # Result of a feature evaluation with details
+  class EvaluationResult
+    attr_accessor :feature_key, :enabled, :reason, :matched_rule, :matched_rule_index
+
+    def initialize(feature_key:, enabled:, reason:)
+      @feature_key = feature_key
+      @enabled = enabled
+      @reason = reason
+      @matched_rule = nil
+      @matched_rule_index = nil
+    end
+
+    def to_h
+      {
+        feature_key: @feature_key,
+        enabled: @enabled,
+        reason: @reason,
+        matched_rule: @matched_rule,
+        matched_rule_index: @matched_rule_index
+      }
+    end
+  end
+end

data/lib/toggly/evaluators/always_off.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Evaluators
+    # Evaluator that always returns false.
+    #
+    # Used for features that should be disabled for everyone.
+    class AlwaysOff < Base
+      def self.type
+        "always_off"
+      end
+
+      # @param rule [Hash] The rule configuration (ignored)
+      # @param context [Context] The evaluation context (ignored)
+      # @param feature_key [String] The feature key
+      # @return [Boolean] Always returns false
+      def evaluate(_rule, _context, feature_key: nil)
+        false
+      end
+    end
+  end
+end

data/lib/toggly/evaluators/always_on.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Evaluators
+    # Evaluator that always returns true.
+    #
+    # Used for features that should be enabled for everyone.
+    class AlwaysOn < Base
+      def self.type
+        "always_on"
+      end
+
+      # @param rule [Hash] The rule configuration (ignored)
+      # @param context [Context] The evaluation context (ignored)
+      # @param feature_key [String] The feature key
+      # @return [Boolean] Always returns true
+      def evaluate(_rule, _context, feature_key: nil)
+        true
+      end
+    end
+  end
+end

data/lib/toggly/evaluators/base.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Evaluators
+    # Base class for feature evaluators.
+    #
+    # Evaluators determine whether a feature should be enabled
+    # based on rules and context.
+    class Base
+      # @return [String] Evaluator type identifier
+      def self.type
+        raise NotImplementedError, "Subclass must implement .type"
+      end
+
+      # Evaluate a rule against a context
+      #
+      # @param rule [Hash] The rule configuration
+      # @param context [Context] The evaluation context
+      # @param feature_key [String] The feature key (for logging)
+      # @return [Boolean, nil] true/false for match, nil to continue evaluation
+      def evaluate(rule, context, feature_key: nil)
+        raise NotImplementedError, "Subclass must implement #evaluate"
+      end
+
+      # Check if this evaluator handles a rule type
+      #
+      # @param rule_type [String] The rule type
+      # @return [Boolean]
+      def handles?(rule_type)
+        rule_type.to_s.downcase == self.class.type.to_s.downcase
+      end
+
+      protected
+
+      # Get a value from rule with fallback
+      #
+      # @param rule [Hash] The rule
+      # @param key [String, Symbol] The key to lookup
+      # @param default [Object] Default value
+      # @return [Object]
+      def rule_value(rule, key, default = nil)
+        rule[key.to_s] || rule[key.to_sym] || default
+      end
+
+      # Log evaluation result (if logger available)
+      #
+      # @param feature_key [String] The feature key
+      # @param result [Boolean] The evaluation result
+      # @param reason [String] The reason for the result
+      def log_evaluation(feature_key, result, reason)
+        # Subclasses can override to add logging
+      end
+    end
+  end
+end

data/lib/toggly/evaluators/contextual_targeting.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Evaluators
+    # Evaluator for contextual targeting based on traits.
+    #
+    # Supports various comparison operators on trait values.
+    class ContextualTargeting < Base
+      # Supported operators
+      OPERATORS = %w[
+        eq ne gt gte lt lte
+        contains not_contains
+        starts_with ends_with
+        in not_in
+        matches
+        exists not_exists
+      ].freeze
+
+      def self.type
+        "contextual"
+      end
+
+      # Evaluate contextual targeting rule
+      #
+      # @param rule [Hash] Rule with "conditions" array
+      # @param context [Context] Evaluation context with traits
+      # @param feature_key [String] The feature key
+      # @return [Boolean, nil] True if all conditions match, nil if no conditions
+      def evaluate(rule, context, feature_key: nil)
+        conditions = Array(rule_value(rule, "conditions"))
+        return nil if conditions.empty?
+        return nil unless context
+
+        match_type = rule_value(rule, "matchType") || rule_value(rule, "match_type") || "all"
+
+        if match_type == "any"
+          conditions.any? { |condition| evaluate_condition(condition, context) }
+        else
+          conditions.all? { |condition| evaluate_condition(condition, context) }
+        end
+      end
+
+      private
+
+      def evaluate_condition(condition, context)
+        trait_key = condition["trait"] || condition["key"] || condition["attribute"]
+        return false unless trait_key
+
+        operator = (condition["operator"] || condition["op"] || "eq").to_s.downcase
+        expected = condition["value"] || condition["values"]
+
+        actual = context.trait(trait_key)
+
+        case operator
+        when "eq", "equals", "=="
+          compare_equal(actual, expected)
+        when "ne", "not_equals", "!="
+          !compare_equal(actual, expected)
+        when "gt", ">"
+          compare_numeric(actual, expected) { |a, e| a > e }
+        when "gte", ">="
+          compare_numeric(actual, expected) { |a, e| a >= e }
+        when "lt", "<"
+          compare_numeric(actual, expected) { |a, e| a < e }
+        when "lte", "<="
+          compare_numeric(actual, expected) { |a, e| a <= e }
+        when "contains"
+          actual.to_s.include?(expected.to_s)
+        when "not_contains"
+          !actual.to_s.include?(expected.to_s)
+        when "starts_with"
+          actual.to_s.start_with?(expected.to_s)
+        when "ends_with"
+          actual.to_s.end_with?(expected.to_s)
+        when "in"
+          Array(expected).map(&:to_s).include?(actual.to_s)
+        when "not_in"
+          !Array(expected).map(&:to_s).include?(actual.to_s)
+        when "matches", "regex"
+          actual.to_s.match?(Regexp.new(expected.to_s))
+        when "exists"
+          context.trait?(trait_key)
+        when "not_exists"
+          !context.trait?(trait_key)
+        else
+          false
+        end
+      rescue RegexpError
+        false
+      end
+
+      def compare_equal(actual, expected)
+        return actual.to_s.downcase == expected.to_s.downcase if actual.is_a?(String) || expected.is_a?(String)
+
+        actual == expected
+      end
+
+      def compare_numeric(actual, expected)
+        actual_num = to_number(actual)
+        expected_num = to_number(expected)
+
+        return false if actual_num.nil? || expected_num.nil?
+
+        yield(actual_num, expected_num)
+      end
+
+      def to_number(value)
+        return value if value.is_a?(Numeric)
+
+        Float(value)
+      rescue ArgumentError, TypeError
+        nil
+      end
+    end
+  end
+end