FF-2678 flag evaluation details

.github/workflows/ci.yml

@@ -51,7 +51,7 @@ jobs:
 
       - name: Check Cargo.lock
         # Ensure that Cargo.lock matches Cargo.toml
-        run: cargo update --workspace --locked
+        run: cargo update --workspace --locked --verbose
         working-directory: ruby-sdk
 
       - name: Override eppo_core for testing

.github/workflows/msrv.yml

@@ -36,6 +36,13 @@ jobs:
           then
               cargo install cargo-msrv --locked
           fi
+
+      - name: Override eppo_core for testing against local version
+        run: |
+          mkdir -p ~/.cargo/
+          echo "[patch.crates-io.eppo_core]" >> "${CARGO_HOME:-$HOME/.cargo}/config.toml"
+          echo "path = '$PWD/eppo_core'" >> "${CARGO_HOME:-$HOME/.cargo}/config.toml"
+
       - name: Verify MSRV for each package
         run: |
           for dir in eppo_core rust-sdk ruby-sdk/ext/eppo_client; do

Cargo.toml

@@ -3,4 +3,9 @@ resolver = "2"
 members = [
   "eppo_core",
   "rust-sdk",
+  "ruby-sdk/ext/eppo_client",
 ]
+
+[patch.crates-io]
+# Local override for development.
+eppo_core = { path = './eppo_core' }

eppo_core/Cargo.toml

@@ -24,4 +24,9 @@ thiserror = "1.0.60"
 url = "2.5.0"
 
 [dev-dependencies]
+criterion = { version = "0.4", features = ["html_reports"] }
 env_logger = "0.11.3"
+
+[[bench]]
+name = "evaluation_details"
+harness = false

eppo_core/benches/evaluation_details.rs

@@ -0,0 +1,137 @@
+use std::collections::HashMap;
+use std::fs::File;
+
+use criterion::{black_box, criterion_group, criterion_main, Criterion, Throughput};
+
+use eppo_core::{
+    ufc::{get_assignment, get_assignment_details},
+    Configuration,
+};
+
+fn criterion_benchmark(c: &mut Criterion) {
+    let flags =
+        serde_json::from_reader(File::open("../sdk-test-data/ufc/flags-v1.json").unwrap()).unwrap();
+    let configuration = Configuration::from_server_response(flags, None);
+
+    {
+        let mut group = c.benchmark_group("new-user-onboarding");
+        group.throughput(Throughput::Elements(1));
+        let attributes = HashMap::new();
+        group.bench_function("get_assignment", |b| {
+            b.iter(|| {
+                get_assignment(
+                    black_box(Some(&configuration)),
+                    black_box("new-user-onboarding"),
+                    black_box("subject1"),
+                    black_box(&attributes),
+                    black_box(None),
+                )
+            })
+        });
+        group.bench_function("get_assignment_details", |b| {
+            b.iter(|| {
+                get_assignment_details(
+                    black_box(Some(&configuration)),
+                    black_box("new-user-onboarding"),
+                    black_box("subject1"),
+                    black_box(&attributes),
+                    black_box(None),
+                )
+            })
+        });
+        group.finish();
+    }
+
+    {
+        let mut group = c.benchmark_group("rollout");
+        group.throughput(Throughput::Elements(1));
+        let attributes = [("country".to_owned(), "US".into())].into();
+        group.bench_function("get_assignment", |b| {
+            b.iter(|| {
+                get_assignment(
+                    black_box(Some(&configuration)),
+                    black_box("new-user-onboarding"),
+                    black_box("subject1"),
+                    black_box(&attributes),
+                    black_box(None),
+                )
+            })
+        });
+        group.bench_function("get_assignment_details", |b| {
+            b.iter(|| {
+                get_assignment_details(
+                    black_box(Some(&configuration)),
+                    black_box("new-user-onboarding"),
+                    black_box("subject1"),
+                    black_box(&attributes),
+                    black_box(None),
+                )
+            })
+        });
+        group.finish();
+    }
+
+    {
+        let mut group = c.benchmark_group("json-config-flag");
+        group.throughput(Throughput::Elements(1));
+        let attributes = [].into();
+        group.bench_function("get_assignment", |b| {
+            b.iter(|| {
+                get_assignment(
+                    black_box(Some(&configuration)),
+                    black_box("json-config-flag"),
+                    black_box("subject1"),
+                    black_box(&attributes),
+                    black_box(None),
+                )
+            })
+        });
+        group.bench_function("get_assignment_details", |b| {
+            b.iter(|| {
+                get_assignment_details(
+                    black_box(Some(&configuration)),
+                    black_box("json-config-flag"),
+                    black_box("subject1"),
+                    black_box(&attributes),
+                    black_box(None),
+                )
+            })
+        });
+        group.finish();
+    }
+
+    {
+        let mut group = c.benchmark_group("numeric-one-of");
+        group.throughput(Throughput::Elements(1));
+        let attributes = [("number".to_owned(), 2.0.into())].into();
+        group.bench_function("get_assignment", |b| {
+            b.iter(|| {
+                get_assignment(
+                    black_box(Some(&configuration)),
+                    black_box("numeric-one-of"),
+                    black_box("subject1"),
+                    black_box(&attributes),
+                    black_box(None),
+                )
+            })
+        });
+        group.bench_function("get_assignment_details", |b| {
+            b.iter(|| {
+                get_assignment_details(
+                    black_box(Some(&configuration)),
+                    black_box("numeric-one-of"),
+                    black_box("subject1"),
+                    black_box(&attributes),
+                    black_box(None),
+                )
+            })
+        });
+        group.finish();
+    }
+}
+
+criterion_group!(
+    name = benches;
+    config = Criterion::default().noise_threshold(0.02);
+    targets = criterion_benchmark);
+criterion_main!(benches);

eppo_core/src/configuration.rs

@@ -1,42 +1,46 @@
 use std::collections::HashMap;
 
+use chrono::{DateTime, Utc};
+
 use crate::{
     bandits::{BanditConfiguration, BanditResponse},
     ufc::{BanditVariation, TryParse, UniversalFlagConfig},
 };
 
 /// Remote configuration for the eppo client. It's a central piece that defines client behavior.
-#[derive(Default, Clone)]
+#[derive(Clone)]
 pub struct Configuration {
+    /// Timestamp when configuration was fetched by the SDK.
+    pub fetched_at: DateTime<Utc>,
     /// Flags configuration.
-    pub flags: Option<UniversalFlagConfig>,
+    pub flags: UniversalFlagConfig,
     /// Bandits configuration.
     pub bandits: Option<BanditResponse>,
-    /// Mapping from flag key to flag variation value to bandit variation.
+    /// Mapping from flag key to flag variation value to bandit variation. Cached from
+    /// `self.flags.bandits`.
     pub flag_to_bandit_associations:
         HashMap</* flag_key: */ String, HashMap</* variation_key: */ String, BanditVariation>>,
 }
 
 impl Configuration {
     /// Create a new configuration from server responses.
-    pub fn new(
-        config: Option<UniversalFlagConfig>,
+    pub fn from_server_response(
+        config: UniversalFlagConfig,
         bandits: Option<BanditResponse>,
     ) -> Configuration {
-        if let Some(config) = &config {
-            // warn if some flags failed to parse
-            for (name, flag) in &config.flags {
-                if let TryParse::ParseFailed(_value) = flag {
-                    log::warn!(target: "eppo", "failed to parse flag configuration: {name:?}");
-                }
+        let now = Utc::now();
+
+        // warn if some flags failed to parse
+        for (name, flag) in &config.flags {
+            if let TryParse::ParseFailed(_value) = flag {
+                log::warn!(target: "eppo", "failed to parse flag configuration: {name:?}");
             }
         }
 
-        let flag_to_bandit_associations = config
-            .as_ref()
-            .map(get_flag_to_bandit_associations)
-            .unwrap_or_default();
+        let flag_to_bandit_associations = get_flag_to_bandit_associations(&config);
+
         Configuration {
+            fetched_at: now,
             flags: config,
             bandits,
             flag_to_bandit_associations,

eppo_core/src/configuration_fetcher.rs

@@ -1,6 +1,4 @@
 //! An HTTP client that fetches configuration from the server.
-use std::sync::Arc;
-
 use reqwest::{StatusCode, Url};
 
 use crate::{bandits::BanditResponse, ufc::UniversalFlagConfig, Configuration, Error, Result};
@@ -55,7 +53,7 @@ impl ConfigurationFetcher {
             Some(self.fetch_bandits_configuration()?)
         };
 
-        Ok(Configuration::new(Some(ufc), bandits))
+        Ok(Configuration::from_server_response(ufc, bandits))
     }
 
     fn fetch_ufc_configuration(&mut self) -> Result<UniversalFlagConfig> {

eppo_core/src/configuration_store.rs

@@ -8,18 +8,21 @@ use crate::Configuration;
 /// `ConfigurationStore` provides a thread-safe (`Sync`) storage for Eppo configuration that allows
 /// concurrent access for readers and writers.
 ///
-/// `Configuration` itself is always immutable and can only be replaced fully.
+/// `Configuration` itself is always immutable and can only be replaced completely.
 #[derive(Default)]
 pub struct ConfigurationStore {
-    configuration: RwLock<Arc<Configuration>>,
+    configuration: RwLock<Option<Arc<Configuration>>>,
 }
 
 impl ConfigurationStore {
+    /// Create a new empty configuration store.
     pub fn new() -> Self {
         ConfigurationStore::default()
     }
 
-    pub fn get_configuration(&self) -> Arc<Configuration> {
+    /// Get currently-active configuration. Returns None if configuration hasn't been fetched/stored
+    /// yet.
+    pub fn get_configuration(&self) -> Option<Arc<Configuration>> {
         // self.configuration.read() should always return Ok(). Err() is possible only if the lock
         // is poisoned (writer panicked while holding the lock), which should never happen.
         let configuration = self
@@ -38,35 +41,46 @@ impl ConfigurationStore {
             .write()
             .expect("thread holding configuration lock should not panic");
 
-        *configuration_slot = config;
+        *configuration_slot = Some(config);
     }
 }
 
 #[cfg(test)]
 mod tests {
     use std::{collections::HashMap, sync::Arc};
 
+    use chrono::Utc;
+
     use super::ConfigurationStore;
-    use crate::{ufc::UniversalFlagConfig, Configuration};
+    use crate::{
+        ufc::{Environment, UniversalFlagConfig},
+        Configuration,
+    };
 
     #[test]
     fn can_set_configuration_from_another_thread() {
         let store = Arc::new(ConfigurationStore::new());
 
+        assert!(store.get_configuration().is_none());
+
         {
             let store = store.clone();
             let _ = std::thread::spawn(move || {
-                store.set_configuration(Configuration::new(
-                    Some(UniversalFlagConfig {
+                store.set_configuration(Configuration::from_server_response(
+                    UniversalFlagConfig {
+                        created_at: Utc::now(),
+                        environment: Environment {
+                            name: "test".to_owned(),
+                        },
                         flags: HashMap::new(),
                         bandits: HashMap::new(),
-                    }),
+                    },
                     None,
                 ))
             })
             .join();
         }
 
-        assert!(store.get_configuration().flags.is_some());
+        assert!(store.get_configuration().is_some());
     }
 }