eppo-server-sdk 3.2.2-arm64-darwin → 3.2.7-arm64-darwin

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7b5674af76373caf9c4fc98616fbc975bed876825f7e11d25bad6b0cd8dd2d9
-  data.tar.gz: b7a21824503acc2747af666919a9828e427b9bca4fad738ec6ae55025f916eb3
+  metadata.gz: 0ca4717e9e0c2f7c0e6260d71fdc015e857f2bed7c63580effe094b88a709201
+  data.tar.gz: 62cc406c07c9084d543131ea7a917102f30173dfb4ba938becefc322d90ee550
 SHA512:
-  metadata.gz: 41075419d1a099be78ed9ef21e731b77cfe78371b418f7049045de0d7553f66193adb53ea8eae2fc78d85730f5c82ef8a9a839cf16ceb3a213fabd320647c7e0
-  data.tar.gz: fd766c37435b07ad9bab319d897726b7990e6bc207e010bf2a793c865a075e87d439e07426908dc80ac91751f7b313d39f02b7dfe809cd8cd57cf84d18ab1617
+  metadata.gz: cb7e90a331f72f90258cb317fcb35dd47ddb01134a74291cb47dd6953e934b2a57c256451fa5749d9e4d064ec20f112ca6428c83985a91644e7d852f63796048
+  data.tar.gz: 381cffccff097a6866d9536ba4dd6025abd085dbf51700a745c6c0d5fdb0e891211aa14c422eeb1b2f94cceb23c8e04dc95b52c8701bcd22cc6c687cace51695

data/README.md

@@ -0,0 +1,28 @@
+# Eppo SDK for Ruby
+
+## Getting Started
+
+Refer to our [SDK documentation](https://docs.geteppo.com/feature-flags/sdks/ruby) for how to install and use the SDK.
+
+## Supported Ruby Versions
+This version of the SDK is compatible with Ruby 3.0.6 and above.
+
+# Contributing
+
+## Testing with local version of `eppo_core`
+
+To run build and tests against a local version of `eppo_core`, you should instruct Cargo to look for it at the local path.
+
+Add the following to `.cargo/config.toml` file (relative to `ruby-sdk`):
+```toml
+[patch.crates-io]
+eppo_core = { path = '../eppo_core' }
+```
+
+Make sure you remove the override before updating `Cargo.lock`. Otherwise, the lock file will be missing `eppo_core` checksum and will be unsuitable for release. (CI will warn you if you do this accidentally.)
+
+## Releasing
+
+* Bump versions in `ruby-sdk/lib/eppo_client/version.rb` and `ruby-sdk/ext/eppo_client/Cargo.toml`
+* Run `cargo update --workspace --verbose` to update `Cargo.lock`
+* Run `bundle` to update `Gemfile.lock`

data/lib/eppo_client/assignment_logger.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "custom_errors"
+
+module EppoClient
+  # The base assignment logger class to override
+  class AssignmentLogger
+    def log_assignment(_assignment_event)
+      raise(EppoClient::AssignmentLoggerError, "log_assignment has not been set up")
+    end
+
+    def log_bandit_action(_assignment_event)
+      raise(EppoClient::AssignmentLoggerError, "log_bandit_action has not been set up")
+    end
+  end
+end

data/lib/eppo_client/client.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "singleton"
+require "logger"
+
+require_relative "config"
+
+# Tries to require the extension for the current Ruby version first
+begin
+  RUBY_VERSION =~ /(\d+\.\d+)/
+  require_relative "#{Regexp.last_match(1)}/eppo_client"
+rescue LoadError
+  require_relative "eppo_client"
+end
+
+module EppoClient
+  # The main client singleton
+  class Client
+    include Singleton
+    attr_accessor :assignment_logger
+
+    def init(config)
+      config.validate
+
+      if !@core.nil?
+        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 configuration
+      @core.configuration
+    end
+
+    def configuration=(configuration)
+      @core.configuration = configuration
+    end
+
+    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)
+      begin
+        assignment = @core.get_assignment(flag_key, subject_key, subject_attributes, expected_type)
+        if not assignment then
+          return default_value
+        end
+
+        log_assignment(assignment[:event])
+
+        return assignment[:value][:value]
+      rescue StandardError => error
+        logger.debug("[Eppo SDK] Failed to get assignment: #{error}")
+
+        # TODO: non-graceful mode?
+        default_value
+      end
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    # 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
+
+      return result
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    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]}
+
+      begin
+        @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
+    end
+
+    def log_bandit_action(event)
+      if not event then return end
+
+      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
+
+    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
+end

data/lib/eppo_client/config.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+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, :poll_interval_seconds, :poll_jitter_seconds
+
+    def initialize(api_key, assignment_logger: AssignmentLogger.new, base_url: EppoClient::Core::DEFAULT_BASE_URL, poll_interval_seconds: EppoClient::Core::DEFAULT_POLL_INTERVAL_SECONDS, poll_jitter_seconds: EppoClient::Core::DEFAULT_POLL_JITTER_SECONDS, initial_configuration: nil)
+      @api_key = api_key
+      @assignment_logger = assignment_logger
+      @base_url = base_url
+      @poll_interval_seconds = poll_interval_seconds
+      @poll_jitter_seconds = poll_jitter_seconds
+    end
+
+    def validate
+      EppoClient.validate_not_blank("api_key", @api_key)
+    end
+
+    # Hide instance variables (specifically api_key) from logs
+    def inspect
+      "#<EppoClient::Config:#{object_id}>"
+    end
+  end
+end

data/lib/eppo_client/custom_errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module EppoClient
+  # A custom error class for AssignmentLogger
+  class AssignmentLoggerError < StandardError
+    def initialize(message)
+      super("AssignmentLoggerError: #{message}")
+    end
+  end
+
+  # A custom error class for invalid values
+  class InvalidValueError < StandardError
+    def initialize(message)
+      super("InvalidValueError: #{message}")
+    end
+  end
+end

data/lib/eppo_client/validation.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+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(
+      EppoClient::InvalidValueError, "#{field_name} cannot be blank"
+    )
+  end
+end

data/lib/eppo_client/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# TODO: this version and ext/eppo_client/Cargo.toml should be in sync
+module EppoClient
+  VERSION = "3.2.7"
+end

data/lib/eppo_client.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "eppo_client/client"
+require_relative "eppo_client/version"
+
+# 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 init(config)
+    client = EppoClient::Client.instance
+    client.init(config)
+  end
+
+  module_function :init
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: eppo-server-sdk
 version: !ruby/object:Gem::Version
-  version: 3.2.2
+  version: 3.2.7
 platform: arm64-darwin
 authors:
 - Eppo
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-10-17 00:00:00.000000000 Z
+date: 2024-10-22 00:00:00.000000000 Z
 dependencies: []
 description: 
 email:
@@ -17,10 +17,18 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
+- lib/eppo_client.rb
 - lib/eppo_client/3.0/eppo_client.bundle
 - lib/eppo_client/3.1/eppo_client.bundle
 - lib/eppo_client/3.2/eppo_client.bundle
 - lib/eppo_client/3.3/eppo_client.bundle
+- lib/eppo_client/assignment_logger.rb
+- lib/eppo_client/client.rb
+- lib/eppo_client/config.rb
+- lib/eppo_client/custom_errors.rb
+- lib/eppo_client/validation.rb
+- lib/eppo_client/version.rb
 homepage: https://github.com/Eppo-exp/ruby-sdk
 licenses:
 - MIT