eppo-server-sdk 0.3.0 → 3.0.0

data/Cargo.toml

@@ -0,0 +1,7 @@
+# This Cargo.toml is here to let externals tools (IDEs, etc.) know that this is
+# a Rust project. Your extensions dependencies should be added to the Cargo.toml
+# in the ext/ directory.
+
+[workspace]
+members = ["./ext/eppo_client"]
+resolver = "2"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Eppo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,22 @@
+# 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.)

data/Rakefile

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require_relative 'lib/eppo_client/version'
+
+GEM_NAME = 'eppo-server-sdk'
+GEM_VERSION = EppoClient::VERSION
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+require "rb_sys/extensiontask"
+
+task default: :build
+
+GEMSPEC = Gem::Specification.load("eppo-server-sdk.gemspec")
+
+RbSys::ExtensionTask.new("eppo_client", GEMSPEC) do |ext|
+  ext.lib_dir = "lib/eppo_client"
+end
+
+task build: :compile do
+  system "gem build #{GEM_NAME}.gemspec"
+end
+
+task install: :build do
+  system "gem install #{GEM_NAME}-#{GEM_VERSION}.gem"
+end
+
+task devinstall: :build do
+  system "gem install #{GEM_NAME}-#{GEM_VERSION}.gem --dev"
+end
+
+task publish: :build do
+  system "gem push #{GEM_NAME}-#{GEM_VERSION}.gem"
+end
+
+task :clean do
+  system 'rm *.gem'
+end
+
+RSpec::Core::RakeTask.new(:test) do |task|
+  root_dir = Rake.application.original_dir
+  task.pattern = "#{root_dir}/spec/*_spec.rb"
+  task.verbose = false
+end
+
+task test: :devinstall
+task test_refreshed_data: [:devinstall, 'test-data']

data/Steepfile

@@ -0,0 +1,27 @@
+# D = Steep::Diagnostic
+#
+target :lib do
+  signature "sig"
+
+  check "lib"                       # Directory name
+
+  library "singleton"
+  library "logger"
+
+  # configure_code_diagnostics(D::Ruby.default)      # `default` diagnostics setting (applies by default)
+  # configure_code_diagnostics(D::Ruby.strict)       # `strict` diagnostics setting
+  # configure_code_diagnostics(D::Ruby.lenient)      # `lenient` diagnostics setting
+  # configure_code_diagnostics(D::Ruby.silent)       # `silent` diagnostics setting
+  # configure_code_diagnostics do |hash|             # You can setup everything yourself
+  #   hash[D::Ruby::NoMethod] = :information
+  # end
+end
+
+target :test do
+  signature "sig", "sig-private"
+
+  check "test"
+
+  library "singleton"
+  library "logger"
+end

data/ext/eppo_client/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "eppo_client"
+version = "3.0.0"
+edition = "2021"
+license = "MIT"
+publish = false
+rust-version = "1.71.1"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+env_logger = { version = "0.11.3", features = ["unstable-kv"] }
+eppo_core = { version = "1.0.0" }
+log = { version = "0.4.21", features = ["kv_serde"] }
+magnus = { version = "0.6.2" }
+serde = { version = "1.0.203", features = ["derive"] }
+serde_magnus = "0.8.1"
+rb-sys = "0.9"

data/ext/eppo_client/build.rs

@@ -0,0 +1,5 @@
+fn main() {
+    // Without this flag, building via `cargo build` fails with undefined references to ruby
+    // library. This is fine as `eppo_client` is going to be loaded as an extension by the host Ruby.
+    println!("cargo:rustc-link-arg=-Wl,-undefined,dynamic_lookup");
+}

data/ext/eppo_client/extconf.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rb_sys/mkmf"
+
+create_rust_makefile("eppo_client")

data/ext/eppo_client/src/client.rs

@@ -0,0 +1,119 @@
+use std::{cell::RefCell, sync::Arc};
+
+use eppo_core::{
+    configuration_fetcher::ConfigurationFetcher, configuration_store::ConfigurationStore,
+    poller_thread::PollerThread, ufc::VariationType, Attributes, ContextAttributes,
+};
+use magnus::{error::Result, exception, prelude::*, Error, TryConvert, Value};
+
+#[derive(Debug)]
+#[magnus::wrap(class = "EppoClient::Core::Config", size, free_immediately)]
+pub struct Config {
+    api_key: String,
+    base_url: String,
+}
+
+impl TryConvert for Config {
+    // `val` is expected to be of type EppoClient::Config.
+    fn try_convert(val: magnus::Value) -> Result<Self> {
+        let api_key = String::try_convert(val.funcall("api_key", ())?)?;
+        let base_url = String::try_convert(val.funcall("base_url", ())?)?;
+        Ok(Config { api_key, base_url })
+    }
+}
+
+#[magnus::wrap(class = "EppoClient::Core::Client")]
+pub struct Client {
+    configuration_store: Arc<ConfigurationStore>,
+    // Magnus only allows sharing aliased references (&T) through the API, so we need to use RefCell
+    // to get interior mutability.
+    //
+    // This should be safe as Ruby only uses a single OS thread, and `Client` lives in the Ruby
+    // world.
+    poller_thread: RefCell<Option<PollerThread>>,
+}
+
+impl Client {
+    pub fn new(config: Config) -> Client {
+        let configuration_store = Arc::new(ConfigurationStore::new());
+
+        let poller_thread = PollerThread::start(
+            ConfigurationFetcher::new(
+                eppo_core::configuration_fetcher::ConfigurationFetcherConfig {
+                    base_url: config.base_url,
+                    api_key: config.api_key,
+                    sdk_name: "ruby".to_owned(),
+                    sdk_version: env!("CARGO_PKG_VERSION").to_owned(),
+                },
+            ),
+            configuration_store.clone(),
+        )
+        .expect("should be able to start poller thread");
+
+        Client {
+            configuration_store,
+            poller_thread: RefCell::new(Some(poller_thread)),
+        }
+    }
+
+    pub fn get_assignment(
+        &self,
+        flag_key: String,
+        subject_key: String,
+        subject_attributes: Value,
+        expected_type: Value,
+    ) -> Result<Value> {
+        let expected_type: VariationType = serde_magnus::deserialize(expected_type)?;
+        let subject_attributes: Attributes = serde_magnus::deserialize(subject_attributes)?;
+
+        let config = self.configuration_store.get_configuration();
+        let result = config
+            .get_assignment(
+                &flag_key,
+                &subject_key,
+                &subject_attributes,
+                Some(expected_type),
+            )
+            // TODO: maybe expose possible errors individually.
+            .map_err(|err| Error::new(exception::runtime_error(), err.to_string()))?;
+
+        Ok(serde_magnus::serialize(&result).expect("assignment value should be serializable"))
+    }
+
+    pub fn get_bandit_action(
+        &self,
+        flag_key: String,
+        subject_key: String,
+        subject_attributes: Value,
+        actions: Value,
+        default_variation: String,
+    ) -> Result<Value> {
+        let subject_attributes = serde_magnus::deserialize::<_, ContextAttributes>(
+            subject_attributes,
+        )
+        .map_err(|err| {
+            Error::new(
+                exception::runtime_error(),
+                format!("enexpected value for subject_attributes: {err}"),
+            )
+        })?;
+        let actions = serde_magnus::deserialize(actions)?;
+
+        let config = self.configuration_store.get_configuration();
+        let result = config.get_bandit_action(
+            &flag_key,
+            &subject_key,
+            &subject_attributes,
+            &actions,
+            &default_variation,
+        );
+
+        serde_magnus::serialize(&result)
+    }
+
+    pub fn shutdown(&self) {
+        if let Some(t) = self.poller_thread.take() {
+            let _ = t.shutdown();
+        }
+    }
+}

data/ext/eppo_client/src/lib.rs

@@ -0,0 +1,26 @@
+mod client;
+
+use magnus::{function, method, prelude::*, Error, Object, Ruby};
+
+use crate::client::Client;
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    env_logger::Builder::from_env(env_logger::Env::new().default_filter_or("eppo")).init();
+
+    let eppo_client = ruby.define_module("EppoClient")?;
+    let core = eppo_client.define_module("Core")?;
+
+    let core_client = core.define_class("Client", magnus::class::object())?;
+    core_client.define_singleton_method("new", function!(Client::new, 1))?;
+    core_client.define_method("get_assignment", method!(Client::get_assignment, 4))?;
+    core_client.define_method("get_bandit_action", method!(Client::get_bandit_action, 5))?;
+    core_client.define_method("shutdown", method!(Client::shutdown, 0))?;
+
+    core.const_set(
+        "DEFAULT_BASE_URL",
+        eppo_core::configuration_fetcher::DEFAULT_BASE_URL,
+    )?;
+
+    Ok(())
+}

data/lib/eppo_client/assignment_logger.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
-require_relative 'custom_errors'
+require_relative "custom_errors"
 
 module EppoClient
   # The base assignment logger class to override
   class AssignmentLogger
-    def log_assignment(_assignment)
-      raise(EppoClient::AssignmentLoggerError, 'log_assignment has not been set up')
+    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

@@ -1,238 +1,141 @@
 # 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
+    def shutdown
+      @core.shutdown
     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
+    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_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
+    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_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
+    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_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
+    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_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, nil,
-                                                    logger)
-      assigned_variation&.value
+    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
-    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
-        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
+    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)
 
-      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
+      log_assignment(result[:assignment_event])
+      log_bandit_action(result[:bandit_event])
 
-      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
-      end
+      return {:variation => result[:variation], :action=>result[:action]}
+    end
 
-      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)
-      end
+    private
 
-      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
+    # 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][expected_type]
+      rescue StandardError => error
+        logger.debug("[Eppo SDK] Failed to get assignment: #{error}")
+
+        # TODO: non-graceful mode?
+        default_value
       end
+    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