abmeter 0.0.2 → 0.2.0

data/lib/abmeter/core/assignment_config/feature_flag.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module ABMeter
+  module Core
+    module AssignmentConfig
+      class FeatureFlag
+        include Exposable
+
+        attr_reader :id, :variant, :audience
+
+        def initialize(id:, variant:, audience:)
+          @id = id
+          @variant = variant
+          @audience = audience
+        end
+
+        def self.from_json(json)
+          json.map do |flag|
+            new(
+              id: flag[:id],
+              audience: Audience.from_json(flag[:audience]),
+              variant: Variant.from_json(flag[:variant])
+            )
+          end
+        end
+
+        def serialize(*_)
+          {
+            id: id,
+            audience: audience.serialize,
+            variant: variant.serialize
+          }
+        end
+
+        # Expose parameter for feature flags
+        def expose_parameter(user, parameter)
+          validate_expose_parameter_args!(user.user_id, parameter, audience)
+          raise ArgumentError, 'Variant must be provided for feature flags' unless variant
+
+          make_exposure(user, parameter, 'FeatureFlag', id, audience, variant)
+        end
+      end
+    end
+  end
+end

data/lib/abmeter/core/assignment_config/parameter.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ABMeter
+  module Core
+    module AssignmentConfig
+      class Parameter
+        attr_reader :id, :slug, :parameter_type, :default_value, :space_id
+
+        def initialize(id:, slug:, parameter_type:, default_value:, space_id:)
+          @id = id
+          @slug = slug
+          @parameter_type = parameter_type
+          @default_value = default_value
+          @space_id = space_id
+        end
+
+        def self.from_json(json)
+          json.map do |param|
+            new(
+              id: param[:id],
+              slug: param[:slug],
+              default_value: ABMeter::Core::Protocol.cast!(param[:default_value], param[:parameter_type]),
+              parameter_type: param[:parameter_type],
+              space_id: param[:space_id]
+            )
+          end
+        end
+
+        def serialize(*_)
+          {
+            id: id,
+            slug: slug,
+            parameter_type: parameter_type,
+            default_value: default_value.to_s,
+            space_id: space_id
+          }
+        end
+      end
+    end
+  end
+end

data/lib/abmeter/core/assignment_config/space.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ABMeter
+  module Core
+    module AssignmentConfig
+      class Space
+        attr_reader :id, :salt
+
+        def initialize(id:, salt:)
+          @id = id
+          @salt = salt
+        end
+
+        def self.from_json(json)
+          json.map do |space|
+            new(
+              id: space[:id],
+              salt: space[:salt]
+            )
+          end
+        end
+
+        def serialize
+          {
+            id: id,
+            salt: salt
+          }
+        end
+      end
+    end
+  end
+end

data/lib/abmeter/core/assignment_config/variant.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ABMeter
+  module Core
+    module AssignmentConfig
+      class Variant
+        attr_reader :id, :parameter_values
+
+        def initialize(id:, parameter_values:)
+          @id = id
+          @parameter_values = parameter_values
+        end
+
+        def parameter_value(parameter_slug)
+          @parameter_values[parameter_slug]
+        end
+
+        def self.from_json(variant)
+          parameter_values = variant[:parameter_values].map { |pv| [pv[:slug], pv[:value]] }.to_h
+          Variant.new(id: variant[:id], parameter_values: parameter_values)
+        end
+
+        def serialize
+          {
+            id: id,
+            parameter_values: parameter_values.map do |parameter_slug, value|
+              {
+                slug: parameter_slug,
+                value: value
+              }
+            end
+          }
+        end
+      end
+    end
+  end
+end

data/lib/abmeter/core/assignment_config.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module ABMeter
+  module Core
+    module AssignmentConfig
+      class Config
+        attr_reader :feature_flags, :experiments, :parameters, :spaces
+
+        def initialize(feature_flags:, experiments:, parameters:, spaces:)
+          @feature_flags = feature_flags
+          @experiments = experiments
+          @parameters = parameters
+          @spaces = spaces
+        end
+
+        def to_json(*_)
+          serialize.to_json
+        end
+
+        def serialize
+          {
+            spaces: spaces.sort_by(&:id).map(&:serialize),
+            parameters: parameters.sort_by(&:id).map(&:serialize),
+            feature_flags: feature_flags.sort_by(&:id).map(&:serialize),
+            experiments: experiments.sort_by(&:id).map(&:serialize)
+          }
+        end
+      end
+
+      def self.from_json(json)
+        parsed_json = JSON.parse(json, symbolize_names: true)
+
+        spaces = Space.from_json(parsed_json[:spaces])
+        space_salts = spaces.to_h { |space| [space.id, space.salt] }
+        parameters = Parameter.from_json(parsed_json[:parameters])
+        feature_flags = FeatureFlag.from_json(parsed_json[:feature_flags])
+        experiments = parsed_json[:experiments] ? Experiment.from_json(parsed_json[:experiments], space_salts) : []
+
+        Config.new(
+          spaces: spaces,
+          feature_flags: feature_flags,
+          experiments: experiments,
+          parameters: parameters
+        )
+      end
+    end
+  end
+end

data/lib/abmeter/core/protocol/type.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module ABMeter
+  module Core
+    module Protocol
+      # Type name constants
+      STRING = 'String'
+      INTEGER = 'Integer'
+      FLOAT = 'Float'
+      BOOLEAN = 'Boolean'
+
+      class Type
+        attr_reader :name
+
+        def initialize(name)
+          @name = name
+        end
+
+        def numerical?
+          false
+        end
+
+        def cast!(value)
+          value
+        end
+
+        def to_s
+          name
+        end
+      end
+
+      class StringType < Type
+        def initialize
+          super(STRING)
+        end
+
+        def cast!(value)
+          value.to_s
+        end
+      end
+
+      class IntegerType < Type
+        def initialize
+          super(INTEGER)
+        end
+
+        def numerical?
+          true
+        end
+
+        def cast!(value)
+          Integer(value)
+        end
+      end
+
+      class FloatType < Type
+        def initialize
+          super(FLOAT)
+        end
+
+        def numerical?
+          true
+        end
+
+        def cast!(value)
+          Float(value)
+        end
+      end
+
+      class BooleanType < Type
+        def initialize
+          super(BOOLEAN)
+        end
+
+        def cast!(value)
+          case value
+          when true, 'true', 'TRUE', 't', 'T', '1', 1
+            true
+          when false, 'false', 'FALSE', 'f', 'F', '0', 0, nil, ''
+            false
+          else
+            raise ArgumentError, "Cannot cast #{value.inspect} to Boolean"
+          end
+        end
+      end
+
+      class TypeRegistry
+        def initialize
+          @types = {}
+          register_default_types
+        end
+
+        def register(type)
+          @types[type.name] = type
+        end
+
+        def get(type_name)
+          @types[type_name] || raise("Unknown type: #{type_name}")
+        end
+
+        def all
+          @types.values
+        end
+
+        def numerical_types
+          @_numerical_types ||= all.select(&:numerical?)
+        end
+
+        private
+
+        def register_default_types
+          register(StringType.new)
+          register(IntegerType.new)
+          register(FloatType.new)
+          register(BooleanType.new)
+        end
+      end
+
+      # Protocol class methods
+      class << self
+        def string
+          type(STRING)
+        end
+
+        def integer
+          type(INTEGER)
+        end
+
+        def float
+          type(FLOAT)
+        end
+
+        def boolean
+          type(BOOLEAN)
+        end
+
+        def type(name)
+          registry.get(name)
+        end
+
+        def all_types
+          registry.all.map(&:name)
+        end
+
+        def numerical?(type_name)
+          type(type_name).numerical?
+        rescue StandardError
+          false
+        end
+
+        def cast!(value, type_name)
+          type(type_name).cast!(value)
+        end
+
+        def valid_for_type?(value, type_name)
+          cast!(value, type_name)
+          true
+        rescue ArgumentError
+          false
+        end
+
+        private
+
+        def registry
+          @registry ||= TypeRegistry.new
+        end
+      end
+    end
+  end
+end

data/lib/abmeter/core/user.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ABMeter
+  module Core
+    class User
+      attr_reader :user_id, :email
+
+      def initialize(user_id:, email:)
+        @user_id = user_id
+        @email = email
+      end
+    end
+  end
+end

data/lib/abmeter/core/user_parameter_resolver.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module ABMeter
+  module Core
+    class UserParameterResolver
+      attr_reader :config
+
+      def initialize(config:)
+        @config = config
+      end
+
+      def exposure_for(user:, parameter_slug:)
+        validate_user!(user)
+
+        # Find parameter once, upfront
+        parameter = @config.parameters.find { |p| p.slug == parameter_slug }
+        raise "Parameter '#{parameter_slug}' not found" unless parameter
+
+        # First check feature flags that control this parameter
+        feature_flag = find_matching_feature_flag(user, parameter_slug)
+        return feature_flag.expose_parameter(user, parameter) if feature_flag
+
+        # Then check experiments that control this parameter
+        experiment_result = find_matching_experiment_variant(user, parameter_slug)
+        if experiment_result
+          variant, experiment, audience = experiment_result
+          return experiment.expose_parameter(user, parameter, variant, audience)
+        end
+
+        {
+          parameter_id: parameter.id,
+          space_id: parameter.space_id,
+          resolved_value: parameter.default_value,
+          user_id: nil,
+          exposable_type: nil,
+          exposable_id: nil,
+          audience_id: nil,
+          resolved_at: Time.now
+        }
+      end
+
+      private
+
+      def validate_user!(user)
+        raise ArgumentError, 'User must have user_id' unless user.respond_to?(:user_id)
+        raise ArgumentError, 'User must have email' unless user.respond_to?(:email)
+      end
+
+      def find_matching_feature_flag(user, parameter_slug)
+        @config.feature_flags.find do |feature_flag|
+          # Only match if user is in audience AND the flag's variant controls this parameter
+          feature_flag.audience.matches?(user) &&
+            feature_flag_controls_parameter?(feature_flag, parameter_slug)
+        end
+      end
+
+      def feature_flag_controls_parameter?(feature_flag, parameter_slug)
+        feature_flag.variant&.parameter_values&.key?(parameter_slug)
+      end
+
+      def find_matching_experiment_variant(user, parameter_slug)
+        @config.experiments.each do |experiment|
+          # Skip experiments that don't control this parameter
+          next unless experiment_controls_parameter?(experiment, parameter_slug)
+
+          # Check if user is allocated to this experiment using space salt
+          experiment_percentage = ABMeter::Core::Utils::NumUtils.to_percentage(experiment.space_salt, user.user_id)
+          next unless experiment.range.include?(experiment_percentage)
+
+          # Then check which audience the user belongs to using experiment salt
+          user_percentage = ABMeter::Core::Utils::NumUtils.to_percentage(experiment.salt, user.user_id)
+
+          assigned_av = experiment.audience_variants.find do |av|
+            av.first.range.include?(user_percentage)
+          end
+
+          return [assigned_av.last, experiment, assigned_av.first] if assigned_av
+        end
+        nil
+      end
+
+      def experiment_controls_parameter?(experiment, parameter_slug)
+        experiment.audience_variants.any? do |av|
+          variant = av.last
+          variant&.parameter_values&.key?(parameter_slug)
+        end
+      end
+    end
+  end
+end

data/lib/abmeter/core/utils/num_utils.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module ABMeter
+  module Core
+    module Utils
+      # NumUtils provides deterministic percentage assignment for A/B testing
+      #
+      # This implementation uses SHA256 + multiply-and-shift algorithm:
+      # - Zero external dependencies (uses Ruby's built-in Digest)
+      # - Fast execution (< 2 microseconds per assignment)
+      # - Cryptographically secure randomness
+      # - Distribution quality sufficient for A/B testing:
+      #   - 10K samples: ~3% average deviation (normal for this sample size)
+      #   - 100K samples: ~0.9% average deviation (good for statistical significance)
+      #   - 1M samples: ~0.7% average deviation (excellent uniformity)
+      #
+      # The multiply-and-shift method avoids modulo bias by scaling the hash
+      # value proportionally across the entire 64-bit space before mapping
+      # to the 1-100 range.
+      class NumUtils
+        def self.to_percentage(salt, id)
+          # Use a hash function to generate a deterministic but random-looking number
+          hash = Digest::SHA256.hexdigest("#{salt}:#{id}")
+
+          # Convert first 16 characters (64 bits) to integer for better distribution
+          # This gives us a number between 0 and 2^64-1
+          num = hash[0..15].to_i(16)
+
+          # Industry-standard multiply-and-shift method for uniform distribution
+          # This avoids modulo bias by scaling the 64-bit space proportionally
+          # Formula: (num * range) >> bits = (num * 100) >> 64
+          # This maps [0, 2^64) uniformly to [0, 100)
+          percentage = (num * 100) >> 64
+          
+          # Add 1 to get 1-100 range instead of 0-99
+          percentage + 1
+        end
+
+        # [10, 20, 30, 40] -> [(1..10) (11..30), (31..60), (61..100)]
+        def self.percentages_to_ranges(percentages)
+          ranges = []
+          percentages.each do |percentage|
+            last_end = ranges.last&.end || 0
+            start_val = last_end + 1
+            end_val = last_end + percentage
+            ranges << (start_val..end_val)
+          end
+          ranges
+        end
+      end
+    end
+  end
+end

data/lib/abmeter/core.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'ostruct'
+require_relative 'version'
+
+# Utils
+require_relative 'core/utils/num_utils'
+
+# Protocol types
+require_relative 'core/protocol/type'
+
+# Assignment Config - order matters
+require_relative 'core/assignment_config/exposable'
+require_relative 'core/assignment_config/space'
+require_relative 'core/assignment_config/parameter'
+require_relative 'core/assignment_config/variant'
+require_relative 'core/assignment_config/audience'
+require_relative 'core/assignment_config/experiment'
+require_relative 'core/assignment_config/feature_flag'
+require_relative 'core/assignment_config'
+
+# Parameter resolution
+require_relative 'core/user_parameter_resolver'
+
+# Domain objects
+require_relative 'core/user'
+
+module ABMeter
+  module Core
+    class Error < StandardError; end
+
+    class << self
+      # Get type object by name
+      def type(type_name)
+        Protocol.type(type_name)
+      end
+
+      # Get all available types
+      def all_types
+        Protocol.all_types
+      end
+
+      # Check if type is numerical
+      def numerical?(type_name)
+        Protocol.numerical?(type_name)
+      end
+
+      # Cast value to given type (strict - raises ArgumentError on invalid)
+      def cast!(value, type_name)
+        Protocol.cast!(value, type_name)
+      end
+
+      # Check if value is valid for type
+      def valid_for_type?(value, type_name)
+        Protocol.valid_for_type?(value, type_name)
+      end
+
+      # Build a resolver from JSON configuration
+      def build_resolver_from_json(json)
+        config = AssignmentConfig.from_json(json)
+        UserParameterResolver.new(config: config)
+      end
+
+      # Provide convenience access to utilities
+      def num_utils
+        Utils::NumUtils
+      end
+
+      # Convert percentages to ranges for experiment allocation
+      def percentages_to_ranges(percentages)
+        Utils::NumUtils.percentages_to_ranges(percentages)
+      end
+    end
+  end
+end

data/lib/abmeter/error_safety.rb

@@ -0,0 +1,39 @@
+module ABMeter
+  module ErrorSafety
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # DSL method to wrap methods with error handling
+      # Usage: error_safe :method_name
+      def error_safe(method_name)
+        original_method = instance_method(method_name)
+
+        define_method(method_name) do |*args, **kwargs, &block|
+          original_method.bind(self).call(*args, **kwargs, &block)
+        rescue StandardError => e
+          log_error("Failed to execute #{method_name}", e)
+          call_error_callback(e) if @config&.error_callback
+
+          nil
+        end
+      end
+    end
+
+    private
+
+    def log_error(message, error)
+      return unless @config&.logger
+
+      @config.logger.error("#{message}: #{error.class} - #{error.message}")
+    end
+
+    def call_error_callback(error)
+      @config.error_callback&.call(error)
+    rescue StandardError => e
+      # Don't let callback errors escape either
+      log_error('Error in error callback', e)
+    end
+  end
+end