eppo-server-sdk 3.5.1 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8736dc91a90cc3bfcd7341761de970c6e6aedc5838945064cfc74be41b7e3104
-  data.tar.gz: 9124f779092595e25273103af99bc04f4abafd6b8df4a0f1af971c01592a6f23
+  metadata.gz: ed54b4025fdfa3a664fc17bfa16f370680b206f1f59322f73008b1ac747b8f1c
+  data.tar.gz: 50c0af964af522fa426435d740e4f545706cdf308007475fd11b6ee016bc61f6
 SHA512:
-  metadata.gz: 02ab023a78d693752224e6a122a89935c7ea2c43694fba2fe921d2693444448d545457cee3c465d314015c5b3cba4073f6441f2306ff5412a4ee256e1f2b51d6
-  data.tar.gz: 9b9ce37027e9ff048663b60ad8162ef7e84a25ae0506a674c620ba9793ea63659a1ae9bd0576dbc2fb2d83960ccabd40888f55fa07c16fa086bd5ad474e45835
+  metadata.gz: b00e011ec1ab5875f802db649f0205d06989a2e4f1a9acadc31afd014e32825ab1868f1f64791c5bd9e1c85bc27afca5580a6d752be0836e114a2b3a0fd4ef3b
+  data.tar.gz: 59977570627cfbc0897a16897657fe66560bb9af0a62d20af9e1a5896d558d8cb189ece6a8cbe5d5fe0ceded6652f86b4fccebf9a63c4c67c632266dafdee76d

data/Cargo.lock

@@ -335,7 +335,7 @@ dependencies = [
 
 [[package]]
 name = "eppo_client"
-version = "3.5.1"
+version = "3.7.0"
 dependencies = [
  "env_logger",
  "eppo_core",
@@ -345,13 +345,14 @@ dependencies = [
  "serde",
  "serde_json",
  "serde_magnus",
+ "tokio",
 ]
 
 [[package]]
 name = "eppo_core"
-version = "9.1.0"
+version = "9.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "228932170e61e7fcafc6ae6f7955cff96a60706c07d0be7809067b5d4ec6d61e"
+checksum = "9221e1c149196a97d292a5b6f14cdc87ef54b2c5f83334df3c24a3b0780a6ac7"
 dependencies = [
  "base64",
  "chrono",
@@ -889,9 +890,9 @@ checksum = "830d08ce1d1d941e6b30645f1a0eb5643013d835ce3779a5fc208261dbe10f55"
 
 [[package]]
 name = "libc"
-version = "0.2.167"
+version = "0.2.171"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "09d6582e104315a817dff97f75133544b2e094ee22447d2acf4a74e189ba06fc"
+checksum = "c19937216e9d3aa9956d9bb8dfc0b0c8beb6058fc4f7a4dc4d850edf86a237d6"
 
 [[package]]
 name = "libloading"
@@ -1785,9 +1786,9 @@ checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
 
 [[package]]
 name = "tokio"
-version = "1.41.1"
+version = "1.44.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "22cfb5bee7a6a52939ca9224d6ac897bb669134078daa8735560897f69de4d33"
+checksum = "f382da615b842244d4b8738c82ed1275e6c5dd90c459a30941cd07080b06c91a"
 dependencies = [
  "backtrace",
  "bytes",
@@ -1801,9 +1802,9 @@ dependencies = [
 
 [[package]]
 name = "tokio-macros"
-version = "2.4.0"
+version = "2.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "693d596312e88961bc67d7f1f97af8a70227d9f90c31bba5806eec004978d752"
+checksum = "6e06d43f1345a3bcd39f6a56dbb7dcab2ba47e68e8ac134855e7e2bdbaf8cab8"
 dependencies = [
  "proc-macro2",
  "quote",

data/ext/eppo_client/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "eppo_client"
 # TODO: this version and lib/eppo_client/version.rb should be in sync
-version = "3.5.1"
+version = "3.7.0"
 edition = "2021"
 license = "MIT"
 publish = false
@@ -12,10 +12,11 @@ crate-type = ["cdylib"]
 
 [dependencies]
 env_logger = { version = "0.11.3", features = ["unstable-kv"] }
-eppo_core = { version = "=9.1.0", features = ["magnus", "event_ingestion"] }
+eppo_core = { version = "=9.2.0", features = ["magnus", "event_ingestion"] }
 log = { version = "0.4.21", features = ["kv_serde"] }
 magnus = { version = "0.7.1" }
 serde = { version = "1.0.203", features = ["derive"] }
 serde_magnus = "0.9.0"
 rb-sys = "0.9.102"
 serde_json = "1.0.128"
+tokio = { version = "1.44.1", default-features = false, features = ["time"] }

data/ext/eppo_client/src/client.rs

@@ -238,6 +238,33 @@ impl Client {
         serde_magnus::serialize(&result)
     }
 
+    pub fn wait_for_initialization(&self, timeout_secs: f64) {
+        log::info!(target: "eppo", "waiting for initialization");
+        let thread = self.background_thread.borrow();
+        let Some(thread) = thread.as_ref() else {
+            log::warn!(target: "eppo", "failed to wait for initialization: background thread is not running");
+            return;
+        };
+        let Some(poller) = &self.configuration_poller else {
+            log::warn!(target: "eppo", "failed to wait for initialization: configuration poller has not been started");
+            return;
+        };
+
+        let _ = thread
+            .runtime()
+            .async_runtime
+            .block_on(async {
+                tokio::time::timeout(
+                    Duration::from_secs_f64(timeout_secs),
+                    poller.wait_for_configuration(),
+                )
+                .await
+            })
+            .inspect_err(|err| {
+                log::warn!(target: "eppo", "failed to wait for initialization: {err:?}");
+            });
+    }
+
     pub fn get_configuration(&self) -> Option<Configuration> {
         self.configuration_store
             .get_configuration()

data/ext/eppo_client/src/lib.rs

@@ -29,6 +29,10 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
         method!(Client::get_bandit_action_details, 5),
     )?;
     core_client.define_method("track", method!(Client::track, 2))?;
+    core_client.define_method(
+        "wait_for_initialization",
+        method!(Client::wait_for_initialization, 1),
+    )?;
     core_client.define_method("configuration", method!(Client::get_configuration, 0))?;
     core_client.define_method("configuration=", method!(Client::set_configuration, 1))?;
     core_client.define_method("shutdown", method!(Client::shutdown, 0))?;

data/lib/eppo_client/client.rb

@@ -31,64 +31,210 @@ module EppoClient
       @core = EppoClient::Core::Client.new(config)
     end
 
+    ##
+    # Waits for client to fetch configuration and get ready to serve
+    # assignments.
+    #
+    # This method blocks the current thread until configuration is
+    # successfully fetched or +timeout+ seconds passed.
+    #
+    # Note: this method returns immediately if configuration poller
+    # has been disabled.
+    #
+    # @param timeout [Numeric] Maximum time to wait in seconds
+    # @return [nil]
+    def wait_for_initialization(timeout=1)
+      return unless @core
+      @core.wait_for_initialization(timeout)
+    end
+
+    ##
+    # Returns the currently active configuration.
     def configuration
       @core.configuration
     end
 
+    ##
+    # Sets the currently active configuration.
     def configuration=(configuration)
       @core.configuration = configuration
     end
 
+    ##
+    # Prepare the client for shutdown.
+    #
+    # This method stops the configuration poller and any other background threads.
+    #
+    # @return [nil]
     def shutdown
       @core.shutdown
     end
 
-    # Unstable
-    # Enqueues an arbitrary event. Events must have a type and a payload
+    ##
+    # Tracks an arbitrary event. Events must have a type and a payload.
+    #
+    # @note This method is considered unstable and may change in future versions.
+    #
+    # @param event_type [String] The type of the event to track.
+    # @param payload [Hash] The payload of the event to track.
     def unstable_track(event_type, payload)
       @core.track(event_type, payload)
     end
 
+    ##
+    # Returns a string assignment for the given flag key and subject.
+    #
+    # @param flag_key [String] The key of the flag to get an assignment for.
+    # @param subject_key [String] The key of the subject to get an assignment for.
+    # @param subject_attributes [Hash] The attributes of the subject to get an assignment for.
+    # @param default_value [String] The default value to return if the flag is not found or no assignment can be made.
+    # @return [String] The assignment for the given flag key and subject.
     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
 
+    ##
+    # Returns a numeric assignment for the given flag key and subject.
+    #
+    # @param flag_key [String] The key of the flag to get an assignment for.
+    # @param subject_key [String] The key of the subject to get an assignment for.
+    # @param subject_attributes [Hash] The attributes of the subject to get an assignment for.
+    # @param default_value [Numeric] The default value to return if the flag is not found or no assignment can be made.
+    # @return [Numeric] The assignment for the given flag key and subject.
     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
 
+    ##
+    # Returns an integer assignment for the given flag key and subject.
+    #
+    # @param flag_key [String] The key of the flag to get an assignment for.
+    # @param subject_key [String] The key of the subject to get an assignment for.
+    # @param subject_attributes [Hash] The attributes of the subject to get an assignment for.
+    # @param default_value [Integer] The default value to return if the flag is not found or no assignment can be made.
+    # @return [Integer] The assignment for the given flag key and subject.
     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
 
+    ##
+    # Returns a boolean assignment for the given flag key and subject.
+    #
+    # @param flag_key [String] The key of the flag to get an assignment for.
+    # @param subject_key [String] The key of the subject to get an assignment for.
+    # @param subject_attributes [Hash] The attributes of the subject to get an assignment for.
+    # @param default_value [Boolean] The default value to return if the flag is not found or no assignment can be made.
+    # @return [Boolean] The assignment for the given flag key and subject.
     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
 
+    ##
+    # Returns a JSON assignment for the given flag key and subject.
+    #
+    # @param flag_key [String] The key of the flag to get an assignment for.
+    # @param subject_key [String] The key of the subject to get an assignment for.
+    # @param subject_attributes [Hash] The attributes of the subject to get an assignment for.
+    # @param default_value [Hash] The default value to return if the flag is not found or no assignment can be made.
+    # @return [Hash] The assignment for the given flag key and subject.
     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
 
+    ##
+    # Returns detailed information about a string assignment for the given flag key and subject.
+    #
+    # @note This method is intended for debugging purposes and is discouraged from use in
+    #   production. It is a couple of times slower than the non-detail methods. The evaluation
+    #   details format is primarily designed for human consumption (debugging) and is therefore
+    #   unstable and may change between SDK versions.
+    #
+    # @param flag_key [String] The key of the flag to get an assignment for.
+    # @param subject_key [String] The key of the subject to get an assignment for.
+    # @param subject_attributes [Hash] The attributes of the subject to get an assignment for.
+    # @param default_value [String] The default value to return if the flag is not found or no assignment can be made.
+    # @return [Hash] A hash containing {:variation => assigned_value, :action => nil, :evaluationDetails => {detailed_evaluation_info}}
     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
 
+    ##
+    # Returns detailed information about a numeric assignment for the given flag key and subject.
+    #
+    # @note This method is intended for debugging purposes and is discouraged from use in
+    #   production. It is a couple of times slower than the non-detail methods. The evaluation
+    #   details format is primarily designed for human consumption (debugging) and is therefore
+    #   unstable.
+    #
+    # @param flag_key [String] The key of the flag to get an assignment for.
+    # @param subject_key [String] The key of the subject to get an assignment for.
+    # @param subject_attributes [Hash] The attributes of the subject to get an assignment for.
+    # @param default_value [Numeric] The default value to return if the flag is not found or no assignment can be made.
+    # @return [Hash] A hash containing {:variation => assigned_value, :action => nil, :evaluationDetails => {detailed_evaluation_info}}
     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
 
+    ##
+    # Returns detailed information about an integer assignment for the given flag key and subject.
+    #
+    # @note This method is intended for debugging purposes and is discouraged from use in
+    #   production. It is a couple of times slower than the non-detail methods. The evaluation
+    #   details format is primarily designed for human consumption (debugging) and is therefore
+    #   unstable and may change between SDK versions.
+    #
+    # @param flag_key [String] The key of the flag to get an assignment for.
+    # @param subject_key [String] The key of the subject to get an assignment for.
+    # @param subject_attributes [Hash] The attributes of the subject to get an assignment for.
+    # @param default_value [Integer] The default value to return if the flag is not found or no assignment can be made.
+    # @return [Hash] A hash containing {:variation => assigned_value, :action => nil, :evaluationDetails => {detailed_evaluation_info}}
     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
 
+    ##
+    # Returns detailed information about a boolean assignment for the given flag key and subject.
+    #
+    # @note This method is intended for debugging purposes and is discouraged from use in
+    #   production. It is a couple of times slower than the non-detail methods. The evaluation
+    #   details format is primarily designed for human consumption (debugging) and is therefore
+    #   unstable and may change between SDK versions.
+    #
+    # @param flag_key [String] The key of the flag to get an assignment for.
+    # @param subject_key [String] The key of the subject to get an assignment for.
+    # @param subject_attributes [Hash] The attributes of the subject to get an assignment for.
+    # @param default_value [Boolean] The default value to return if the flag is not found or no assignment can be made.
+    # @return [Hash] A hash containing {:variation => assigned_value, :action => nil, :evaluationDetails => {detailed_evaluation_info}}
     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
 
+    ##
+    # Returns detailed information about a JSON assignment for the given flag key and subject.
+    #
+    # @note This method is intended for debugging purposes and is discouraged from use in
+    #   production. It is a couple of times slower than the non-detail methods. The evaluation
+    #   details format is primarily designed for human consumption (debugging) and is therefore
+    #   unstable and may change between SDK versions.
+    #
+    # @param flag_key [String] The key of the flag to get an assignment for.
+    # @param subject_key [String] The key of the subject to get an assignment for.
+    # @param subject_attributes [Hash] The attributes of the subject to get an assignment for.
+    # @param default_value [Hash] The default value to return if the flag is not found or no assignment can be made.
+    # @return [Hash] A hash containing {:variation => assigned_value, :action => nil, :evaluationDetails => {detailed_evaluation_info}}
     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
 
+    ##
+    # Returns a bandit action based on the flag key, subject, and available actions.
+    #
+    # @param flag_key [String] The key of the flag to get an action for.
+    # @param subject_key [String] The key of the subject to get an action for.
+    # @param subject_attributes [Hash] The attributes of the subject.
+    # @param actions [Hash] A map of available actions and their attributes.
+    # @param default_variation [String] The default variation to return if no assignment can be made.
+    # @return [Hash] A hash containing the assigned variation and action.
     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)] }
@@ -103,6 +249,20 @@ module EppoClient
       }
     end
 
+    ##
+    # Returns detailed information about a bandit action based on the flag key, subject, and available actions.
+    #
+    # @note This method is intended for debugging purposes and is discouraged from use in
+    #   production. It is a couple of times slower than the non-detail methods. The evaluation
+    #   details format is primarily designed for human consumption (debugging) and is therefore
+    #   unstable and may change between SDK versions.
+    #
+    # @param flag_key [String] The key of the flag to get an action for.
+    # @param subject_key [String] The key of the subject to get an action for.
+    # @param subject_attributes [Hash] The attributes of the subject.
+    # @param actions [Hash] A map of available actions and their attributes.
+    # @param default_variation [String] The default variation to return if no assignment can be made.
+    # @return [Hash] A hash containing {:variation => assigned_variation, :action => assigned_action, :evaluationDetails => {detailed_evaluation_info}}
     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)] }
@@ -120,7 +280,6 @@ module EppoClient
 
     private
 
-    # rubocop:disable Metrics/MethodLength
     def get_assignment_inner(flag_key, subject_key, subject_attributes, expected_type, default_value)
       logger = Logger.new($stdout)
       begin

data/lib/eppo_client/version.rb

@@ -2,5 +2,5 @@
 
 # TODO: this version and ext/eppo_client/Cargo.toml should be in sync
 module EppoClient
-  VERSION = "3.5.1"
+  VERSION = "3.7.0"
 end

data/lib/eppo_client.rb

@@ -6,6 +6,14 @@ 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
+  ##
+  # Initializes the Eppo client singleton.
+  #
+  # @note The client returned by this method may still be in the process of initializing.
+  #       Use the `#wait_for_initialization` method to wait for the client to be ready.
+  #
+  # @param config [EppoClient::Config] The configuration for the client.
+  # @return [EppoClient::Client] The client.
   def init(config)
     client = EppoClient::Client.instance
     client.init(config)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: eppo-server-sdk
 version: !ruby/object:Gem::Version
-  version: 3.5.1
+  version: 3.7.0
 platform: ruby
 authors:
 - Eppo
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-14 00:00:00.000000000 Z
+date: 2025-04-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys