eppo-server-sdk 3.2.2-x86_64-linux-musl → 3.2.7-x86_64-linux-musl

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c22565d875c7b40a28dcbffe1032a9d49f06b44f3043ec6dfc31aa1df66eac1c
-  data.tar.gz: f3f4e6cd79b4c2474bf931a7bebcaaac5cbd6909f74a484be5f59b1eac3c868f
+  metadata.gz: 3f22fae84d379957d4c998ab883d780fd6a7bc3fbab81ab1fc3318d5ec87226a
+  data.tar.gz: 38dbfe398495c75c34c084510a6b683bee664bd7ad0f1ef91a0560bf14e2f69f
 SHA512:
-  metadata.gz: 317e0cf947b0c7893292814529211f4ad2bb622db64d603c8b50b0b1fb00e3af01da4467caf9a54f8c5e967b7d1686e45a68db68307d61abeab09abea7fcae53
-  data.tar.gz: 7e6c1d2f0f91c44e4a7a164fe593769a57718fcceb2f21494c4e4347154502fe107bf9aec55bb1a2ed53c64175ef52e624421ca9bba050b136ffa41a665c860c
+  metadata.gz: 2068819797f3e979a4d5e4fec13c77c4c323f6d361884a007a20c392730100364337183573ca402e28c6a4bd47c85b7f836d50d22497a6efc6c6c0f467928c85
+  data.tar.gz: 127cf70d19bbf83da41f950074593613c2ae09fe58e1f2ef182abd759227d520f746e5789c81ba2a40002cba8bb492418212d64de429671913abe877f6fa4e7b

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: x86_64-linux-musl
 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.so
 - lib/eppo_client/3.1/eppo_client.so
 - lib/eppo_client/3.2/eppo_client.so
 - lib/eppo_client/3.3/eppo_client.so
+- 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