[AC-154] Adds basic nimbus flag building to ads-client

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 [Full Changelog](In progress)
 
+## ✨ What's Changed ✨
+
+### Ads-Client
+
+- Add optional `nimbus_flags(...)` argument to ads-client builder, allowing passed nimbus flags to be read within the rust component itself.
+
 # v155.0 (_2026-08-13_)
 
 [Full Changelog](https://github.com/mozilla/application-services/compare/v154.0...v155.0)

components/ads-client/src/ffi.rs

@@ -20,6 +20,7 @@ use crate::mars::ad_response::{
 };
 use crate::mars::Environment;
 use crate::mars::ReportReason;
+use crate::nimbus::NimbusFlags;
 use crate::AdsClientUrl;
 use crate::MozAdsClient;
 use parking_lot::Mutex;
@@ -107,6 +108,7 @@ struct MozAdsClientBuilderInner {
     context_id_provider: Option<Arc<dyn MozAdsContextIdProvider>>,
     environment: Option<MozAdsEnvironment>,
     telemetry: Option<Arc<dyn MozAdsTelemetry>>,
+    nimbus_flags: Option<NimbusFlags>,
 }
 
 impl Default for MozAdsClientBuilder {
@@ -139,9 +141,9 @@ impl MozAdsClientBuilder {
                 .unwrap_or_else(MozAdsTelemetryWrapper::noop),
         };
         let client = AdsClient::new(client_config);
-        MozAdsClient {
-            inner: Mutex::new(client),
-        }
+        let flags = Arc::new(inner.nimbus_flags.clone().unwrap_or_default());
+        let inner = Mutex::new(client);
+        MozAdsClient { inner, flags }
     }
 
     pub fn cache_config(self: Arc<Self>, cache_config: MozAdsCacheConfig) -> Arc<Self> {
@@ -166,6 +168,11 @@ impl MozAdsClientBuilder {
         self.0.lock().telemetry = Some(Arc::from(telemetry));
         self
     }
+
+    pub fn nimbus_flags(self: Arc<Self>, flags: HashMap<String, bool>) -> Arc<Self> {
+        self.0.lock().nimbus_flags = Some(NimbusFlags::new(flags));
+        self
+    }
 }
 
 #[derive(Clone, Copy, Debug, Default, uniffi::Enum, Eq, PartialEq)]

components/ads-client/src/lib.rs

@@ -3,7 +3,7 @@
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 */
 
-use std::collections::HashMap;
+use std::{collections::HashMap, sync::Arc};
 
 use client::error::ComponentError;
 use error_support::handle_error;
@@ -19,11 +19,15 @@ mod client;
 mod ffi;
 pub mod http_cache;
 mod mars;
+pub mod nimbus;
 pub mod telemetry;
 
 pub use ffi::*;
 
-use crate::ffi::telemetry::MozAdsTelemetryWrapper;
+use crate::{
+    ffi::telemetry::MozAdsTelemetryWrapper,
+    nimbus::{NimbusFlag, NimbusFlags},
+};
 
 #[cfg(test)]
 mod test_utils;
@@ -39,6 +43,7 @@ uniffi::custom_type!(AdsClientUrl, String, {
 #[derive(uniffi::Object)]
 pub struct MozAdsClient {
     inner: Mutex<AdsClient<MozAdsTelemetryWrapper>>,
+    flags: Arc<NimbusFlags>,
 }
 
 #[uniffi::export]
@@ -174,3 +179,16 @@ impl MozAdsClient {
         Ok(response.into_iter().map(|(k, v)| (k, v.into())).collect())
     }
 }
+
+impl MozAdsClient {
+    pub fn check_nimbus_flag(&self, flag: &NimbusFlag) -> bool {
+        self.flags.check_flag(flag)
+    }
+}
+
+#[cfg(test)]
+impl MozAdsClient {
+    fn nimbus_test_flag(&self) -> bool {
+        self.flags.check_flag(&crate::nimbus::NimbusFlag::Test)
+    }
+}

components/ads-client/src/nimbus.rs

@@ -0,0 +1,72 @@
+use std::collections::HashMap;
+
+// At the current moment, nimbus usage exclusively inside of rust components is not fully realized.
+// Therefore, for now we will accept a series of string flags passed in from each surface (that are connected to nimbus).
+// The ads-client can then branch behavior based on the passed flags.
+#[derive(Clone, Default)]
+pub struct NimbusFlags {
+    flags: HashMap<NimbusFlag, bool>,
+}
+
+impl NimbusFlags {
+    // Parse and store flags in constructor.
+    // Allow unrecognized flags to be read as `Unknown`, so that extra irrelevant flags can be easily passed.
+    pub fn new(flags: HashMap<String, bool>) -> NimbusFlags {
+        NimbusFlags {
+            flags: flags
+                .into_iter()
+                .map(|(k, v)| (NimbusFlag::from_string(&k), v))
+                .collect(),
+        }
+    }
+
+    pub fn check_flag(&self, flag: &NimbusFlag) -> bool {
+        *self.flags.get(flag).unwrap_or(&false)
+    }
+}
+
+#[derive(Clone, Hash, PartialEq, Eq)]
+pub enum NimbusFlag {
+    // `ads-client.async-enabled`
+    AsyncEnabled,
+
+    // This allows unrecognized flags to be passed (parsed as `Unknown`)
+    Unknown(String),
+
+    #[cfg(test)]
+    Test,
+}
+
+impl NimbusFlag {
+    pub fn from_string(s: &str) -> NimbusFlag {
+        match s {
+            "ads-client.async-enabled" => NimbusFlag::AsyncEnabled,
+            #[cfg(test)]
+            "test" => NimbusFlag::Test,
+            s => NimbusFlag::Unknown(s.to_string()),
+        }
+    }
+}
+
+mod tests {
+    #[test]
+    fn nimbus_test_flag_active_on_test() {
+        let nimbus_flag_off = std::sync::Arc::new(crate::MozAdsClientBuilder::new())
+            .environment(crate::MozAdsEnvironment::Test)
+            .build();
+        assert!(
+            !nimbus_flag_off.nimbus_test_flag(),
+            "Nimbus `Test` flag should be disabled if no flags are passed"
+        );
+        let mut flags = std::collections::HashMap::new();
+        flags.insert("test".to_string(), true);
+        let nimbus_flag_on = std::sync::Arc::new(crate::MozAdsClientBuilder::new())
+            .environment(crate::MozAdsEnvironment::Test)
+            .nimbus_flags(flags)
+            .build();
+        assert!(
+            nimbus_flag_on.nimbus_test_flag(),
+            "Nimbus `Test` flag should be enabled if no flag is passed"
+        );
+    }
+}