eppo-server-sdk 0.3.0 → 3.1.0

data/lib/eppo_client/client.rb

@@ -1,238 +1,192 @@
 # frozen_string_literal: true
 
-require 'singleton'
-require 'time'
+require "singleton"
+require "logger"
 
-require_relative 'constants'
-require_relative 'custom_errors'
-require_relative 'rules'
-require_relative 'shard'
-require_relative 'validation'
-require_relative 'variation_type'
+require_relative "config"
+require_relative "eppo_client"
 
 module EppoClient
   # The main client singleton
-  # rubocop:disable Metrics/ClassLength
   class Client
-    extend Gem::Deprecate
     include Singleton
-    attr_accessor :config_requestor, :assignment_logger, :poller
+    attr_accessor :assignment_logger
 
-    def instance
-      Client.instance
+    def init(config)
+      config.validate
+
+      if !@core.nil? then
+        STDERR.puts "Eppo Warning: multiple initialization of the client"
+        @core.shutdown
+      end
+
+      @assignment_logger = config.assignment_logger
+      @core = EppoClient::Core::Client.new(config)
     end
 
-    def get_string_assignment(
-      subject_key,
-      flag_key,
-      subject_attributes = {},
-      log_level = EppoClient::DEFAULT_LOGGER_LEVEL
-    )
-      logger = Logger.new($stdout)
-      logger.level = log_level
-      assigned_variation = get_assignment_variation(
-        subject_key, flag_key, subject_attributes,
-        EppoClient::VariationType::STRING_TYPE, logger
-      )
-      assigned_variation&.typed_value
-    end
-
-    def get_numeric_assignment(
-      subject_key,
-      flag_key,
-      subject_attributes = {},
-      log_level = EppoClient::DEFAULT_LOGGER_LEVEL
-    )
-      logger = Logger.new($stdout)
-      logger.level = log_level
-      assigned_variation = get_assignment_variation(
-        subject_key, flag_key, subject_attributes,
-        EppoClient::VariationType::NUMERIC_TYPE, logger
-      )
-      assigned_variation&.typed_value
-    end
-
-    def get_boolean_assignment(
-      subject_key,
-      flag_key,
-      subject_attributes = {},
-      log_level = EppoClient::DEFAULT_LOGGER_LEVEL
-    )
-      logger = Logger.new($stdout)
-      logger.level = log_level
-      assigned_variation = get_assignment_variation(
-        subject_key, flag_key, subject_attributes,
-        EppoClient::VariationType::BOOLEAN_TYPE, logger
-      )
-      assigned_variation&.typed_value
-    end
-
-    def get_parsed_json_assignment(
-      subject_key,
-      flag_key,
-      subject_attributes = {},
-      log_level = EppoClient::DEFAULT_LOGGER_LEVEL
-    )
-      logger = Logger.new($stdout)
-      logger.level = log_level
-      assigned_variation = get_assignment_variation(
-        subject_key, flag_key, subject_attributes,
-        EppoClient::VariationType::JSON_TYPE, logger
-      )
-      assigned_variation&.typed_value
-    end
-
-    def get_json_string_assignment(
-      subject_key,
-      flag_key,
-      subject_attributes = {},
-      log_level = EppoClient::DEFAULT_LOGGER_LEVEL
-    )
-      logger = Logger.new($stdout)
-      logger.level = log_level
-      assigned_variation = get_assignment_variation(
-        subject_key, flag_key, subject_attributes,
-        EppoClient::VariationType::JSON_TYPE, logger
-      )
-      assigned_variation&.value
-    end
-
-    def get_assignment(
-      subject_key,
-      flag_key,
-      subject_attributes = {},
-      log_level = EppoClient::DEFAULT_LOGGER_LEVEL
-    )
+    def shutdown
+      @core.shutdown
+    end
+
+    def get_string_assignment(flag_key, subject_key, subject_attributes, default_value)
+      get_assignment_inner(flag_key, subject_key, subject_attributes, "STRING", default_value)
+    end
+
+    def get_numeric_assignment(flag_key, subject_key, subject_attributes, default_value)
+      get_assignment_inner(flag_key, subject_key, subject_attributes, "NUMERIC", default_value)
+    end
+
+    def get_integer_assignment(flag_key, subject_key, subject_attributes, default_value)
+      get_assignment_inner(flag_key, subject_key, subject_attributes, "INTEGER", default_value)
+    end
+
+    def get_boolean_assignment(flag_key, subject_key, subject_attributes, default_value)
+      get_assignment_inner(flag_key, subject_key, subject_attributes, "BOOLEAN", default_value)
+    end
+
+    def get_json_assignment(flag_key, subject_key, subject_attributes, default_value)
+      get_assignment_inner(flag_key, subject_key, subject_attributes, "JSON", default_value)
+    end
+
+    def get_string_assignment_details(flag_key, subject_key, subject_attributes, default_value)
+      get_assignment_details_inner(flag_key, subject_key, subject_attributes, "STRING", default_value)
+    end
+
+    def get_numeric_assignment_details(flag_key, subject_key, subject_attributes, default_value)
+      get_assignment_details_inner(flag_key, subject_key, subject_attributes, "NUMERIC", default_value)
+    end
+
+    def get_integer_assignment_details(flag_key, subject_key, subject_attributes, default_value)
+      get_assignment_details_inner(flag_key, subject_key, subject_attributes, "INTEGER", default_value)
+    end
+
+    def get_boolean_assignment_details(flag_key, subject_key, subject_attributes, default_value)
+      get_assignment_details_inner(flag_key, subject_key, subject_attributes, "BOOLEAN", default_value)
+    end
+
+    def get_json_assignment_details(flag_key, subject_key, subject_attributes, default_value)
+      get_assignment_details_inner(flag_key, subject_key, subject_attributes, "JSON", default_value)
+    end
+
+    def get_bandit_action(flag_key, subject_key, subject_attributes, actions, default_variation)
+      attributes = coerce_context_attributes(subject_attributes)
+      actions = actions.to_h { |action, attributes| [action, coerce_context_attributes(attributes)] }
+      result = @core.get_bandit_action(flag_key, subject_key, attributes, actions, default_variation)
+
+      log_assignment(result[:assignment_event])
+      log_bandit_action(result[:bandit_event])
+
+      return {:variation => result[:variation], :action => result[:action]}
+    end
+
+    def get_bandit_action_details(flag_key, subject_key, subject_attributes, actions, default_variation)
+      attributes = coerce_context_attributes(subject_attributes)
+      actions = actions.to_h { |action, attributes| [action, coerce_context_attributes(attributes)] }
+      result, details = @core.get_bandit_action_details(flag_key, subject_key, attributes, actions, default_variation)
+
+      log_assignment(result[:assignment_event])
+      log_bandit_action(result[:bandit_event])
+
+      return {
+        :variation => result[:variation],
+        :action => result[:action],
+        :evaluationDetails => details
+      }
+    end
+
+    private
+
+    # rubocop:disable Metrics/MethodLength
+    def get_assignment_inner(flag_key, subject_key, subject_attributes, expected_type, default_value)
       logger = Logger.new($stdout)
-      logger.level = log_level
-      assigned_variation = get_assignment_variation(subject_key, flag_key,
-                                                    subject_attributes, nil,
-                                                    logger)
-      assigned_variation&.value
-    end
-    deprecate :get_assignment, 'the get_<typed>_assignment methods', 2024, 1
-
-    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-    def get_assignment_variation(
-      subject_key,
-      flag_key,
-      subject_attributes,
-      expected_variation_type,
-      logger
-    )
-      EppoClient.validate_not_blank('subject_key', subject_key)
-      EppoClient.validate_not_blank('flag_key', flag_key)
-      experiment_config = @config_requestor.get_configuration(flag_key)
-      override = get_subject_variation_override(experiment_config, subject_key)
-      unless override.nil?
-        unless expected_variation_type.nil?
-          variation_is_expected_type =
-            EppoClient::VariationType.expected_type?(
-              override, expected_variation_type
-            )
-          return nil unless variation_is_expected_type
+      begin
+        assignment = @core.get_assignment(flag_key, subject_key, subject_attributes, expected_type)
+        if not assignment then
+          return default_value
         end
-        return override
-      end
 
-      if experiment_config.nil? || experiment_config.enabled == false
-        logger.debug(
-          '[Eppo SDK] No assigned variation. No active experiment or flag for '\
-          "key: #{flag_key}"
-        )
-        return nil
-      end
+        log_assignment(assignment[:event])
 
-      matched_rule = EppoClient.find_matching_rule(subject_attributes, experiment_config.rules)
-      if matched_rule.nil?
-        logger.debug(
-          '[Eppo SDK] No assigned variation. Subject attributes do not match '\
-          "targeting rules: #{subject_attributes}"
-        )
-        return nil
-      end
+        return assignment[:value][:value]
+      rescue StandardError => error
+        logger.debug("[Eppo SDK] Failed to get assignment: #{error}")
 
-      allocation = experiment_config.allocations[matched_rule.allocation_key]
-      unless in_experiment_sample?(
-        subject_key,
-        flag_key,
-        experiment_config.subject_shards,
-        allocation.percent_exposure
-      )
-        logger.debug(
-          '[Eppo SDK] No assigned variation. Subject is not part of experiment'\
-          ' sample population'
-        )
-        return nil
+        # TODO: non-graceful mode?
+        default_value
       end
+    end
+    # rubocop:enable Metrics/MethodLength
 
-      shard = EppoClient.get_shard(
-        "assignment-#{subject_key}-#{flag_key}",
-        experiment_config.subject_shards
-      )
-      assigned_variation = allocation.variations.find do |var|
-        var.shard_range.shard_in_range?(shard)
+    # rubocop:disable Metrics/MethodLength
+    def get_assignment_details_inner(flag_key, subject_key, subject_attributes, expected_type, default_value)
+      result, event = @core.get_assignment_details(flag_key, subject_key, subject_attributes, expected_type)
+      log_assignment(event)
+
+      if not result[:variation] then
+        result[:variation] = default_value
+      else
+        # unwrap from AssignmentValue to untyped value
+        result[:variation] = result[:variation][:value]
       end
 
-      assigned_variation_value_to_log = nil
-      unless assigned_variation.nil?
-        assigned_variation_value_to_log = assigned_variation.value
-        unless expected_variation_type.nil?
-          variation_is_expected_type = EppoClient::VariationType.expected_type?(
-            assigned_variation, expected_variation_type
-          )
-          return nil unless variation_is_expected_type
-        end
-      end
+      return result
+    end
+    # rubocop:enable Metrics/MethodLength
 
-      assignment_event = {
-        "allocation": matched_rule.allocation_key,
-        "experiment": "#{flag_key}-#{matched_rule.allocation_key}",
-        "featureFlag": flag_key,
-        "variation": assigned_variation_value_to_log,
-        "subject": subject_key,
-        "timestamp": Time.now.utc.iso8601,
-        "subjectAttributes": subject_attributes
-      }
+    def log_assignment(event)
+      if not event then return end
 
+      # Because rust's AssignmentEvent has a #[flatten] extra_logging
+      # field, serde_magnus serializes it as a normal HashMap with
+      # string keys.
+      #
+      # Convert keys to symbols here, so that logger sees symbol-keyed
+      # events for both flag assignment and bandit actions.
+      event = event.to_h { |key, value| [key.to_sym, value]}
+
+      enrich_event_metadata(event)
       begin
-        @assignment_logger.log_assignment(assignment_event)
-      rescue EppoClient::AssignmentLoggerError => e
-        # Error means log_assignment was not set up. This is okay to ignore.
-      rescue StandardError => e
-        logger.error("[Eppo SDK] Error logging assignment event: #{e}")
+        @assignment_logger.log_assignment(event)
+      rescue EppoClient::AssignmentLoggerError
+      # Error means log_assignment was not set up. This is okay to ignore.
+      rescue StandardError => error
+        logger = Logger.new($stdout)
+        logger.error("[Eppo SDK] Error logging assignment event: #{error}")
       end
-
-      assigned_variation
     end
-    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
-    def shutdown
-      @poller.stop
-    end
+    def log_bandit_action(event)
+      if not event then return end
 
-    # rubocop:disable Metrics/MethodLength
-    def get_subject_variation_override(experiment_config, subject)
-      subject_hash = Digest::MD5.hexdigest(subject.to_s)
-      if experiment_config&.overrides &&
-         experiment_config.overrides[subject_hash] &&
-         experiment_config.typed_overrides[subject_hash]
-        EppoClient::VariationDto.new(
-          'override',
-          experiment_config.overrides[subject_hash],
-          experiment_config.typed_overrides[subject_hash],
-          EppoClient::ShardRange.new(0, 1000)
-        )
+      enrich_event_metadata(event)
+      begin
+        @assignment_logger.log_bandit_action(event)
+      rescue EppoClient::AssignmentLoggerError
+      # Error means log_assignment was not set up. This is okay to ignore.
+      rescue StandardError => error
+        logger = Logger.new($stdout)
+        logger.error("[Eppo SDK] Error logging bandit action event: #{error}")
       end
     end
-    # rubocop:enable Metrics/MethodLength
 
-    def in_experiment_sample?(subject, experiment_key, subject_shards,
-                              percent_exposure)
-      shard = EppoClient.get_shard("exposure-#{subject}-#{experiment_key}",
-                                   subject_shards)
-      shard <= percent_exposure * subject_shards
+    def enrich_event_metadata(event)
+      event[:metaData]["sdkName"] = "ruby"
+      event[:metaData]["sdkVersion"] = EppoClient::VERSION
+    end
+
+    def coerce_context_attributes(attributes)
+      numeric_attributes = attributes[:numeric_attributes] || attributes["numericAttributes"]
+      categorical_attributes = attributes[:categorical_attributes] || attributes["categoricalAttributes"]
+      if numeric_attributes || categorical_attributes then
+        {
+          numericAttributes: numeric_attributes.to_h do |key, value|
+            value.is_a?(Numeric) ? [key, value] : [nil, nil]
+          end.compact,
+          categoricalAttributes: categorical_attributes.to_h do |key, value|
+            value.nil? ? [nil, nil] : [key, value.to_s]
+          end.compact,
+        }
+      end
     end
   end
-  # rubocop:enable Metrics/ClassLength
 end

data/lib/eppo_client/config.rb

@@ -1,21 +1,21 @@
 # frozen_string_literal: true
 
-require_relative 'validation'
-require_relative 'assignment_logger'
+require_relative "validation"
+require_relative "assignment_logger"
 
 module EppoClient
   # The class for configuring the Eppo client singleton
   class Config
     attr_reader :api_key, :assignment_logger, :base_url
 
-    def initialize(api_key, assignment_logger: AssignmentLogger.new, base_url: 'https://fscdn.eppo.cloud/api')
+    def initialize(api_key, assignment_logger: AssignmentLogger.new, base_url: EppoClient::Core::DEFAULT_BASE_URL)
       @api_key = api_key
       @assignment_logger = assignment_logger
       @base_url = base_url
     end
 
     def validate
-      EppoClient.validate_not_blank('api_key', @api_key)
+      EppoClient.validate_not_blank("api_key", @api_key)
     end
 
     # Hide instance variables (specifically api_key) from logs

data/lib/eppo_client/custom_errors.rb

@@ -8,23 +8,6 @@ module EppoClient
     end
   end
 
-  # A custom error class for unauthorized requests
-  class UnauthorizedError < StandardError
-    def initialize(message)
-      super("Unauthorized: #{message}")
-    end
-  end
-
-  # A custom error class for HTTP requests
-  class HttpRequestError < StandardError
-    attr_reader :status_code
-
-    def initialize(message, status_code)
-      @status_code = status_code
-      super("HttpRequestError: #{message}")
-    end
-  end
-
   # A custom error class for invalid values
   class InvalidValueError < StandardError
     def initialize(message)

data/lib/eppo_client/validation.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-require_relative 'custom_errors'
+require_relative "custom_errors"
 
 # The helper module to validate keys
 module EppoClient
   module_function
 
   def validate_not_blank(field_name, field_value)
-    (field_value.nil? || field_value == '') && raise(
+    (field_value.nil? || field_value == "") && raise(
       EppoClient::InvalidValueError, "#{field_name} cannot be blank"
     )
   end

data/lib/eppo_client/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# TODO: this version and ext/eppo_rb/Cargo.toml should be in sync
 module EppoClient
-  VERSION = '0.3.0'
+  VERSION = "3.1.0"
 end

data/lib/eppo_client.rb

@@ -1,53 +1,15 @@
 # frozen_string_literal: true
 
-require_relative 'eppo_client/assignment_logger'
-require_relative 'eppo_client/http_client'
-require_relative 'eppo_client/poller'
-require_relative 'eppo_client/config'
-require_relative 'eppo_client/client'
-require_relative 'eppo_client/constants'
-require_relative 'eppo_client/configuration_requestor'
-require_relative 'eppo_client/configuration_store'
-require_relative 'eppo_client/version'
+require_relative "eppo_client/client"
+require_relative "eppo_client/version"
 
-# This module scopes all the client SDK's classes and functions
+# EppoClient is the main module for initializing the Eppo client.
+# It provides a method to initialize the client with a given configuration.
 module EppoClient
-  # rubocop:disable Metrics/MethodLength
-  def initialize_client(config_requestor, assignment_logger)
-    client = EppoClient::Client.instance
-    !client.poller.nil? && client.shutdown
-    client.config_requestor = config_requestor
-    client.assignment_logger = assignment_logger
-    client.poller = EppoClient::Poller.new(
-      EppoClient::POLL_INTERVAL_MILLIS,
-      EppoClient::POLL_JITTER_MILLIS,
-      proc { client.config_requestor.fetch_and_store_configurations }
-    )
-    client.poller.start
-    client
-  end
-  # rubocop:enable Metrics/MethodLength
-
-  # rubocop:disable Metrics/MethodLength
   def init(config)
-    config.validate
-    sdk_params = EppoClient::SdkParams.new(config.api_key, 'ruby',
-                                           EppoClient::VERSION)
-    http_client = EppoClient::HttpClient.new(config.base_url,
-                                             sdk_params.formatted)
-    config_store = EppoClient::ConfigurationStore.new(
-      EppoClient::MAX_CACHE_ENTRIES
-    )
-    config_store.lock.with_write_lock do
-      EppoClient.initialize_client(
-        EppoClient::ExperimentConfigurationRequestor.new(
-          http_client, config_store
-        ),
-        config.assignment_logger
-      )
-    end
+    client = EppoClient::Client.instance
+    client.init(config)
   end
-  # rubocop:enable Metrics/MethodLength
 
-  module_function :init, :initialize_client
+  module_function :init
 end

data/sig/eppo_server_sdk.rbs

@@ -0,0 +1,96 @@
+# EppoClient is the main module for initializing the Eppo client.
+# It provides a method to initialize the client with a given configuration.
+module EppoClient
+  def self.init: (Config config) -> void
+
+  # The base assignment logger class to override
+  class AssignmentLogger
+    def log_assignment: (untyped assignment_event) -> void
+
+    def log_bandit_action: (untyped assignment_event) -> void
+  end
+
+  # The main client singleton
+  class Client
+    @assignment_logger: AssignmentLogger
+    @core: Core::Client
+
+    include Singleton
+
+    attr_accessor assignment_logger: AssignmentLogger
+
+    def self.instance: () -> Client
+
+    def init: (Config config) -> void
+
+    def shutdown: () -> void
+
+    def get_string_assignment: (String flag_key, String subject_key, Hash[String, untyped] subject_attributes, String default_value) -> String
+
+    def get_numeric_assignment: (String flag_key, String subject_key, Hash[String, untyped] subject_attributes, Numeric default_value) -> Numeric
+
+    def get_integer_assignment: (String flag_key, String subject_key, Hash[String, untyped] subject_attributes, Integer default_value) -> Integer
+
+    def get_boolean_assignment: (String flag_key, String subject_key, Hash[String, untyped] subject_attributes, bool default_value) -> bool
+
+    def get_json_assignment: (String flag_key, String subject_key, Hash[String, untyped] subject_attributes, Object default_value) -> Object
+
+    def get_bandit_action: (String flag_key, String subject_key, Hash[String, untyped] subject_attributes, Hash[String, untyped] actions, String default_variation) -> { variation: untyped, action: untyped }
+
+    private
+
+    # rubocop:disable Metrics/MethodLength
+    def get_assignment_inner: (untyped flag_key, String subject_key, untyped subject_attributes, untyped expected_type, untyped default_value) -> untyped
+
+    def log_assignment: (untyped event) -> void
+
+    def log_bandit_action: (untyped event) -> void
+
+    def enrich_event_metadata: (untyped event) -> void
+
+    def coerce_context_attributes: (untyped attributes) -> untyped
+  end
+
+  # The class for configuring the Eppo client singleton
+  class Config
+    @api_key: String
+    @assignment_logger: AssignmentLogger
+    @base_url: String
+
+    attr_reader api_key: String
+    attr_reader assignment_logger: AssignmentLogger
+    attr_reader base_url: String
+
+    def initialize: (String api_key, ?assignment_logger: AssignmentLogger, ?base_url: String) -> void
+
+    def validate: () -> void
+
+    # Hide instance variables (specifically api_key) from logs
+    def inspect: () -> ::String
+  end
+
+  # A custom error class for AssignmentLogger
+  class AssignmentLoggerError < StandardError
+    def initialize: (String message) -> void
+  end
+
+  # A custom error class for invalid values
+  class InvalidValueError < StandardError
+    def initialize: (String message) -> void
+  end
+
+  def self?.validate_not_blank: (String field_name, String field_value) -> void
+
+  VERSION: String
+end
+
+# Exposed from Rust
+module EppoClient::Core
+  DEFAULT_BASE_URL: String
+  class Client
+    def self.new: (untyped config) -> Client
+    def shutdown: () -> void
+    def get_assignment: (String flag_key, String subject_key, untyped subject_attributes, String expected_type) -> untyped
+    def get_bandit_action: (String flag_key, String subject_key, untyped attributes, untyped actions, String default_variation) -> untyped
+  end
+end