toggly 0.1.0

data/lib/toggly/evaluators/percentage.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Evaluators
+    # Evaluator for percentage-based rollouts.
+    #
+    # Uses FNV-1a hash for consistent bucketing based on
+    # feature key and user identity.
+    class Percentage < Base
+      # FNV-1a hash constants (32-bit)
+      FNV_PRIME = 0x01000193
+      FNV_OFFSET_BASIS = 0x811c9dc5
+
+      def self.type
+        "percentage"
+      end
+
+      # Evaluate percentage rollout
+      #
+      # @param rule [Hash] Rule with "percentage" or "value" key (0-100)
+      # @param context [Context] Evaluation context with identity
+      # @param feature_key [String] The feature key
+      # @return [Boolean] True if user falls within percentage
+      def evaluate(rule, context, feature_key: nil)
+        percentage = rule_value(rule, "percentage") ||
+                     rule_value(rule, "value") ||
+                     0
+
+        percentage = percentage.to_f
+
+        # 0% always off, 100% always on
+        return false if percentage <= 0
+        return true if percentage >= 100
+
+        # Need identity for percentage rollouts
+        return false unless context&.identity?
+
+        # Calculate bucket using FNV-1a hash
+        bucket_key = "#{feature_key}:#{context.identity}"
+        bucket = calculate_bucket(bucket_key)
+
+        bucket < percentage
+      end
+
+      private
+
+      # Calculate bucket (0-100) using FNV-1a hash
+      #
+      # @param key [String] The key to hash
+      # @return [Float] Bucket value 0-100
+      def calculate_bucket(key)
+        hash = fnv1a_hash(key)
+        (hash % 10_000) / 100.0
+      end
+
+      # FNV-1a hash implementation
+      #
+      # @param data [String] Data to hash
+      # @return [Integer] 32-bit hash value
+      def fnv1a_hash(data)
+        hash = FNV_OFFSET_BASIS
+
+        data.each_byte do |byte|
+          hash ^= byte
+          hash = (hash * FNV_PRIME) & 0xFFFFFFFF
+        end
+
+        hash
+      end
+    end
+  end
+end

data/lib/toggly/evaluators/targeting.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Evaluators
+    # Evaluator for user/group targeting rules.
+    #
+    # Supports targeting by:
+    # - Specific user identities
+    # - Group membership
+    class Targeting < Base
+      def self.type
+        "targeting"
+      end
+
+      # Evaluate targeting rule
+      #
+      # @param rule [Hash] Rule with "users" and/or "groups" arrays
+      # @param context [Context] Evaluation context
+      # @param feature_key [String] The feature key
+      # @return [Boolean, nil] True if matched, false if excluded, nil to continue
+      def evaluate(rule, context, feature_key: nil)
+        return nil unless context
+
+        # Check user targeting
+        users = Array(rule_value(rule, "users"))
+        excluded_users = Array(rule_value(rule, "excludedUsers") || rule_value(rule, "excluded_users"))
+
+        if context.identity?
+          # Check exclusion first
+          return false if excluded_users.any? { |u| u.to_s == context.identity }
+
+          # Check inclusion
+          return true if users.any? { |u| u.to_s == context.identity }
+        end
+
+        # Check group targeting
+        groups = Array(rule_value(rule, "groups"))
+        excluded_groups = Array(rule_value(rule, "excludedGroups") || rule_value(rule, "excluded_groups"))
+
+        # Check group exclusion
+        return false if excluded_groups.any? { |g| context.in_group?(g) }
+
+        # Check group inclusion
+        return true if groups.any? { |g| context.in_group?(g) }
+
+        # No match, continue evaluation
+        nil
+      end
+    end
+  end
+end

data/lib/toggly/evaluators/time_window.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Evaluators
+    # Evaluator for time-based feature windows.
+    #
+    # Enables features within a specific time range.
+    class TimeWindow < Base
+      def self.type
+        "time_window"
+      end
+
+      # Evaluate time window rule
+      #
+      # @param rule [Hash] Rule with "startTime"/"start_time" and/or "endTime"/"end_time"
+      # @param context [Context] Evaluation context (ignored)
+      # @param feature_key [String] The feature key
+      # @return [Boolean] True if current time is within window
+      def evaluate(rule, _context, feature_key: nil)
+        now = Time.now.utc
+
+        start_time = parse_time(
+          rule_value(rule, "startTime") || rule_value(rule, "start_time")
+        )
+        end_time = parse_time(
+          rule_value(rule, "endTime") || rule_value(rule, "end_time")
+        )
+
+        # No time constraints means always valid
+        return true if start_time.nil? && end_time.nil?
+
+        # Check start time
+        return false if start_time && now < start_time
+
+        # Check end time
+        return false if end_time && now > end_time
+
+        true
+      end
+
+      private
+
+      def parse_time(value)
+        return nil if value.nil?
+        return value if value.is_a?(Time)
+
+        Time.parse(value.to_s).utc
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/toggly/feature_definition.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Toggly
+  # Represents a feature flag definition.
+  #
+  # @example
+  #   definition = Toggly::FeatureDefinition.new(
+  #     feature_key: "dark-mode",
+  #     feature_type: "Release",
+  #     enabled: true,
+  #     rules: [{ "type" => "percentage", "value" => 50 }]
+  #   )
+  class FeatureDefinition
+    # @return [String] Unique feature key
+    attr_reader :feature_key
+
+    # @return [String] Feature type (Release, Experiment, Ops, Permission)
+    attr_reader :feature_type
+
+    # @return [Boolean] Whether the feature is globally enabled
+    attr_reader :enabled
+
+    # @return [Array<Hash>] Evaluation rules
+    attr_reader :rules
+
+    # @return [Hash] Additional metadata
+    attr_reader :metadata
+
+    # @return [Time, nil] When the feature was created
+    attr_reader :created_at
+
+    # @return [Time, nil] When the feature was last updated
+    attr_reader :updated_at
+
+    # @return [String, nil] Feature description
+    attr_reader :description
+
+    # Feature types
+    TYPES = %w[Release Experiment Ops Permission].freeze
+
+    def initialize(
+      feature_key:,
+      feature_type: "Release",
+      enabled: false,
+      rules: [],
+      metadata: {},
+      description: nil,
+      created_at: nil,
+      updated_at: nil
+    )
+      @feature_key = feature_key.to_s
+      @feature_type = validate_type(feature_type)
+      @enabled = enabled ? true : false
+      @rules = Array(rules)
+      @metadata = metadata || {}
+      @description = description
+      @created_at = parse_time(created_at)
+      @updated_at = parse_time(updated_at)
+    end
+
+    # Create from a hash (e.g., from JSON)
+    #
+    # @param hash [Hash] Feature definition hash
+    # @return [FeatureDefinition]
+    def self.from_hash(hash)
+      hash = symbolize_keys(hash)
+
+      # Map API "filters" to internal "rules" format
+      rules = hash[:rules] || hash[:filters] || []
+
+      # In Toggly's model, features are enabled based on filter evaluation.
+      # If the API doesn't send "enabled", derive it from whether filters exist.
+      enabled = if hash.key?(:enabled)
+                  hash[:enabled]
+                else
+                  !rules.empty?
+                end
+
+      new(
+        feature_key: hash[:featureKey] || hash[:feature_key],
+        feature_type: hash[:featureType] || hash[:feature_type] || "Release",
+        enabled: enabled,
+        rules: rules,
+        metadata: hash[:metadata] || {},
+        description: hash[:description],
+        created_at: hash[:createdAt] || hash[:created_at],
+        updated_at: hash[:updatedAt] || hash[:updated_at]
+      )
+    end
+
+    # Convert to hash for serialization
+    #
+    # @return [Hash]
+    def to_h
+      {
+        feature_key: @feature_key,
+        feature_type: @feature_type,
+        enabled: @enabled,
+        rules: @rules,
+        metadata: @metadata,
+        description: @description,
+        created_at: @created_at&.iso8601,
+        updated_at: @updated_at&.iso8601
+      }
+    end
+
+    # Check if feature has rules
+    #
+    # @return [Boolean]
+    def rules?
+      !@rules.empty?
+    end
+
+    # Check if feature is a release toggle
+    #
+    # @return [Boolean]
+    def release?
+      @feature_type == "Release"
+    end
+
+    # Check if feature is an experiment
+    #
+    # @return [Boolean]
+    def experiment?
+      @feature_type == "Experiment"
+    end
+
+    # Check if feature is an ops toggle
+    #
+    # @return [Boolean]
+    def ops?
+      @feature_type == "Ops"
+    end
+
+    # Check if feature is a permission toggle
+    #
+    # @return [Boolean]
+    def permission?
+      @feature_type == "Permission"
+    end
+
+    # Equality check
+    #
+    # @param other [FeatureDefinition]
+    # @return [Boolean]
+    def ==(other)
+      return false unless other.is_a?(FeatureDefinition)
+
+      @feature_key == other.feature_key &&
+        @feature_type == other.feature_type &&
+        @enabled == other.enabled &&
+        @rules == other.rules
+    end
+    alias eql? ==
+
+    # Hash code for use in collections
+    #
+    # @return [Integer]
+    def hash
+      [@feature_key, @feature_type, @enabled, @rules].hash
+    end
+
+    private
+
+    def validate_type(type)
+      type_str = type.to_s
+      return type_str if TYPES.include?(type_str)
+
+      "Release"
+    end
+
+    def parse_time(value)
+      return nil if value.nil?
+      return value if value.is_a?(Time)
+
+      Time.parse(value.to_s)
+    rescue ArgumentError
+      nil
+    end
+
+    def self.symbolize_keys(hash)
+      return hash unless hash.is_a?(Hash)
+
+      hash.transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
+    end
+    private_class_method :symbolize_keys
+  end
+end

data/lib/toggly/registry.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Toggly
+  # Registry for evaluators.
+  #
+  # Manages the collection of evaluators and dispatches
+  # evaluation requests to the appropriate handler.
+  class Registry
+    def initialize
+      @evaluators = {}
+      @mutex = Mutex.new
+      register_defaults
+    end
+
+    # Register an evaluator
+    #
+    # @param evaluator [Evaluators::Base] The evaluator instance
+    # @return [self]
+    def register(evaluator)
+      @mutex.synchronize do
+        @evaluators[evaluator.class.type.to_s.downcase] = evaluator
+      end
+      self
+    end
+
+    # Get an evaluator by type
+    #
+    # @param type [String] The evaluator type
+    # @return [Evaluators::Base, nil]
+    def get(type)
+      @mutex.synchronize do
+        @evaluators[type.to_s.downcase]
+      end
+    end
+
+    # Check if an evaluator exists for a type
+    #
+    # @param type [String] The evaluator type
+    # @return [Boolean]
+    def registered?(type)
+      @mutex.synchronize do
+        @evaluators.key?(type.to_s.downcase)
+      end
+    end
+
+    # List all registered evaluator types
+    #
+    # @return [Array<String>]
+    def types
+      @mutex.synchronize do
+        @evaluators.keys
+      end
+    end
+
+    # Unregister an evaluator
+    #
+    # @param type [String] The evaluator type
+    # @return [Evaluators::Base, nil] The removed evaluator
+    def unregister(type)
+      @mutex.synchronize do
+        @evaluators.delete(type.to_s.downcase)
+      end
+    end
+
+    # Clear all evaluators
+    #
+    # @return [self]
+    def clear
+      @mutex.synchronize do
+        @evaluators.clear
+      end
+      self
+    end
+
+    private
+
+    def register_defaults
+      register(Evaluators::AlwaysOn.new)
+      register(Evaluators::AlwaysOff.new)
+      register(Evaluators::Percentage.new)
+      register(Evaluators::Targeting.new)
+      register(Evaluators::TimeWindow.new)
+      register(Evaluators::ContextualTargeting.new)
+    end
+  end
+end

data/lib/toggly/snapshot_providers/base.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Toggly
+  module SnapshotProviders
+    # Base class for snapshot providers.
+    #
+    # Snapshot providers persist feature definitions for
+    # offline access and faster startup.
+    class Base
+      # Save definitions snapshot
+      #
+      # @param definitions [Hash<String, FeatureDefinition>] Definitions to save
+      # @param metadata [Hash] Optional metadata (e.g., version, timestamp)
+      # @raise [NotImplementedError]
+      def save(definitions, metadata = {})
+        raise NotImplementedError, "Subclass must implement #save"
+      end
+
+      # Load definitions snapshot
+      #
+      # @return [Hash, nil] Hash with :definitions and :metadata, or nil if not found
+      # @raise [NotImplementedError]
+      def load
+        raise NotImplementedError, "Subclass must implement #load"
+      end
+
+      # Clear the snapshot
+      #
+      # @raise [NotImplementedError]
+      def clear
+        raise NotImplementedError, "Subclass must implement #clear"
+      end
+
+      # Check if a snapshot exists
+      #
+      # @return [Boolean]
+      def exists?
+        !load.nil?
+      rescue StandardError
+        false
+      end
+
+      protected
+
+      # Serialize definitions to a storable format
+      #
+      # @param definitions [Hash<String, FeatureDefinition>] Definitions
+      # @return [Array<Hash>]
+      def serialize_definitions(definitions)
+        definitions.values.map(&:to_h)
+      end
+
+      # Deserialize definitions from stored format
+      #
+      # @param data [Array<Hash>] Serialized definitions
+      # @return [Hash<String, FeatureDefinition>]
+      def deserialize_definitions(data)
+        return {} unless data.is_a?(Array)
+
+        data.each_with_object({}) do |item, hash|
+          definition = FeatureDefinition.from_hash(item)
+          hash[definition.feature_key] = definition
+        end
+      end
+    end
+  end
+end

data/lib/toggly/snapshot_providers/file.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Toggly
+  module SnapshotProviders
+    # File-based snapshot provider.
+    #
+    # Persists feature definitions to a JSON file.
+    class File < Base
+      # @return [String] Path to the snapshot file
+      attr_reader :path
+
+      # @param path [String] Path to the snapshot file
+      def initialize(path:)
+        super()
+        @path = path
+        @mutex = Mutex.new
+      end
+
+      # Save definitions to file
+      #
+      # @param definitions [Hash<String, FeatureDefinition>] Definitions
+      # @param metadata [Hash] Optional metadata
+      def save(definitions, metadata = {})
+        @mutex.synchronize do
+          ensure_directory_exists
+
+          data = {
+            "definitions" => serialize_definitions(definitions),
+            "metadata" => metadata.merge("saved_at" => Time.now.utc.iso8601)
+          }
+
+          # Write to temp file first, then rename (atomic operation)
+          temp_path = "#{@path}.tmp"
+          ::File.write(temp_path, JSON.pretty_generate(data))
+          ::File.rename(temp_path, @path)
+        end
+      rescue StandardError => e
+        raise SnapshotError, "Failed to save snapshot: #{e.message}"
+      end
+
+      # Load definitions from file
+      #
+      # @return [Hash, nil] Hash with :definitions and :metadata
+      def load
+        @mutex.synchronize do
+          return nil unless ::File.exist?(@path)
+
+          content = ::File.read(@path)
+          data = JSON.parse(content)
+
+          {
+            definitions: deserialize_definitions(data["definitions"]),
+            metadata: symbolize_keys(data["metadata"] || {})
+          }
+        end
+      rescue JSON::ParserError => e
+        raise SnapshotError, "Failed to parse snapshot: #{e.message}"
+      rescue StandardError => e
+        raise SnapshotError, "Failed to load snapshot: #{e.message}"
+      end
+
+      # Clear the snapshot file
+      def clear
+        @mutex.synchronize do
+          FileUtils.rm_f(@path)
+        end
+      rescue StandardError => e
+        raise SnapshotError, "Failed to clear snapshot: #{e.message}"
+      end
+
+      # Check if snapshot file exists
+      #
+      # @return [Boolean]
+      def exists?
+        ::File.exist?(@path)
+      end
+
+      private
+
+      def ensure_directory_exists
+        dir = ::File.dirname(@path)
+        FileUtils.mkdir_p(dir) unless ::File.directory?(dir)
+      end
+
+      def symbolize_keys(hash)
+        return {} unless hash.is_a?(Hash)
+
+        hash.transform_keys(&:to_sym)
+      end
+    end
+  end
+end

data/lib/toggly/snapshot_providers/memory.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Toggly
+  module SnapshotProviders
+    # In-memory snapshot provider.
+    #
+    # Useful for testing or when persistence is not needed.
+    class Memory < Base
+      def initialize
+        super
+        @data = nil
+        @mutex = Mutex.new
+      end
+
+      # Save definitions to memory
+      #
+      # @param definitions [Hash<String, FeatureDefinition>] Definitions
+      # @param metadata [Hash] Optional metadata
+      def save(definitions, metadata = {})
+        @mutex.synchronize do
+          @data = {
+            definitions: serialize_definitions(definitions),
+            metadata: metadata.merge(saved_at: Time.now.utc.iso8601)
+          }
+        end
+      end
+
+      # Load definitions from memory
+      #
+      # @return [Hash, nil] Hash with :definitions and :metadata
+      def load
+        @mutex.synchronize do
+          return nil unless @data
+
+          {
+            definitions: deserialize_definitions(@data[:definitions]),
+            metadata: @data[:metadata]
+          }
+        end
+      end
+
+      # Clear the snapshot
+      def clear
+        @mutex.synchronize do
+          @data = nil
+        end
+      end
+
+      # Check if snapshot exists
+      #
+      # @return [Boolean]
+      def exists?
+        @mutex.synchronize do
+          !@data.nil?
+        end
+      end
+    end
+  end
+end

data/lib/toggly/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Toggly
+  VERSION = "0.1.0"
+end