nimbus/stateful/
nimbus_client.rs

1/* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
4
5#[cfg(test)]
6use crate::tests::helpers::{TestGeckoPrefHandler, TestMetrics, TestRecordedContext};
7use crate::{
8    defaults::Defaults,
9    enrollment::{
10        EnrolledFeature, EnrollmentChangeEvent, EnrollmentChangeEventType, EnrollmentsEvolver,
11        ExperimentEnrollment,
12    },
13    error::{info, warn, BehaviorError},
14    evaluator::{
15        get_calculated_attributes, is_experiment_available, CalculatedAttributes,
16        TargetingAttributes,
17    },
18    json::{JsonObject, PrefValue},
19    metrics::{
20        EnrollmentStatusExtraDef, FeatureExposureExtraDef, MalformedFeatureConfigExtraDef,
21        MetricsHandler,
22    },
23    schema::parse_experiments,
24    stateful::{
25        behavior::EventStore,
26        client::{create_client, SettingsClient},
27        dbcache::DatabaseCache,
28        enrollment::{
29            get_experiment_participation, get_rollout_participation, opt_in_with_branch, opt_out,
30            reset_telemetry_identifiers, set_experiment_participation, set_rollout_participation,
31            unenroll_for_pref,
32        },
33        gecko_prefs::{
34            GeckoPref, GeckoPrefHandler, GeckoPrefState, GeckoPrefStore, PrefBranch,
35            PrefEnrollmentData, PrefUnenrollReason,
36        },
37        matcher::AppContext,
38        persistence::{Database, StoreId, Writer},
39        targeting::{validate_event_queries, RecordedContext},
40        updating::{read_and_remove_pending_experiments, write_pending_experiments},
41    },
42    strings::fmt_with_map,
43    AvailableExperiment, AvailableRandomizationUnits, EnrolledExperiment, Experiment,
44    ExperimentBranch, NimbusError, NimbusTargetingHelper, Result,
45};
46use chrono::{DateTime, NaiveDateTime, Utc};
47use once_cell::sync::OnceCell;
48use remote_settings::RemoteSettingsConfig;
49use serde_json::Value;
50use std::collections::HashSet;
51use std::fmt::Debug;
52use std::path::{Path, PathBuf};
53use std::sync::{Arc, Mutex, MutexGuard};
54use uuid::Uuid;
55
56const DB_KEY_NIMBUS_ID: &str = "nimbus-id";
57pub const DB_KEY_INSTALLATION_DATE: &str = "installation-date";
58pub const DB_KEY_UPDATE_DATE: &str = "update-date";
59pub const DB_KEY_APP_VERSION: &str = "app-version";
60pub const DB_KEY_FETCH_ENABLED: &str = "fetch-enabled";
61
62// The main `NimbusClient` struct must not expose any methods that make an `&mut self`,
63// in order to be compatible with the uniffi's requirements on objects. This is a helper
64// struct to contain the bits that do actually need to be mutable, so they can be
65// protected by a Mutex.
66#[derive(Default)]
67pub struct InternalMutableState {
68    pub(crate) available_randomization_units: AvailableRandomizationUnits,
69    pub(crate) install_date: Option<DateTime<Utc>>,
70    pub(crate) update_date: Option<DateTime<Utc>>,
71    // Application level targeting attributes
72    pub(crate) targeting_attributes: TargetingAttributes,
73}
74
75impl InternalMutableState {
76    pub(crate) fn update_time_to_now(&mut self, now: DateTime<Utc>) {
77        self.targeting_attributes
78            .update_time_to_now(now, &self.install_date, &self.update_date);
79    }
80}
81
82/// Nimbus is the main struct representing the experiments state
83/// It should hold all the information needed to communicate a specific user's
84/// experimentation status
85pub struct NimbusClient {
86    settings_client: Mutex<Box<dyn SettingsClient + Send>>,
87    pub(crate) mutable_state: Mutex<InternalMutableState>,
88    app_context: AppContext,
89    pub(crate) db: OnceCell<Database>,
90    // Manages an in-memory cache so that we can answer certain requests
91    // without doing (or waiting for) IO.
92    database_cache: DatabaseCache,
93    db_path: PathBuf,
94    coenrolling_feature_ids: Vec<String>,
95    event_store: Arc<Mutex<EventStore>>,
96    recorded_context: Option<Arc<dyn RecordedContext>>,
97    pub(crate) gecko_prefs: Option<Arc<GeckoPrefStore>>,
98    metrics_handler: Arc<Box<dyn MetricsHandler>>,
99}
100
101impl NimbusClient {
102    // This constructor *must* not do any kind of I/O since it might be called on the main
103    // thread in the gecko Javascript stack, hence the use of OnceCell for the db.
104    pub fn new<P: Into<PathBuf>>(
105        app_context: AppContext,
106        recorded_context: Option<Arc<dyn RecordedContext>>,
107        coenrolling_feature_ids: Vec<String>,
108        db_path: P,
109        config: Option<RemoteSettingsConfig>,
110        metrics_handler: Box<dyn MetricsHandler>,
111        gecko_pref_handler: Option<Box<dyn GeckoPrefHandler>>,
112    ) -> Result<Self> {
113        let settings_client = Mutex::new(create_client(config)?);
114
115        let targeting_attributes: TargetingAttributes = app_context.clone().into();
116        let mutable_state = Mutex::new(InternalMutableState {
117            available_randomization_units: Default::default(),
118            targeting_attributes,
119            install_date: Default::default(),
120            update_date: Default::default(),
121        });
122
123        let mut prefs = None;
124        if let Some(handler) = gecko_pref_handler {
125            prefs = Some(Arc::new(GeckoPrefStore::new(Arc::new(handler))));
126        }
127
128        Ok(Self {
129            settings_client,
130            mutable_state,
131            app_context,
132            database_cache: Default::default(),
133            db_path: db_path.into(),
134            coenrolling_feature_ids,
135            db: OnceCell::default(),
136            event_store: Arc::default(),
137            recorded_context,
138            gecko_prefs: prefs,
139            metrics_handler: Arc::new(metrics_handler),
140        })
141    }
142
143    pub fn with_targeting_attributes(&mut self, targeting_attributes: TargetingAttributes) {
144        let mut state = self.mutable_state.lock().unwrap();
145        state.targeting_attributes = targeting_attributes;
146    }
147
148    pub fn get_targeting_attributes(&self) -> TargetingAttributes {
149        let mut state = self.mutable_state.lock().unwrap();
150        state.update_time_to_now(Utc::now());
151        state.targeting_attributes.clone()
152    }
153
154    pub fn initialize(&self) -> Result<()> {
155        let db = self.db()?;
156        // We're not actually going to write, we just want to exclude concurrent writers.
157        let mut writer = db.write()?;
158
159        let mut state = self.mutable_state.lock().unwrap();
160        self.begin_initialize(db, &mut writer, &mut state)?;
161        self.end_initialize(db, writer, &mut state)?;
162
163        Ok(())
164    }
165
166    // These are tasks which should be in the initialize and apply_pending_experiments
167    // but should happen before the enrollment calculations are done.
168    fn begin_initialize(
169        &self,
170        db: &Database,
171        writer: &mut Writer,
172        state: &mut MutexGuard<InternalMutableState>,
173    ) -> Result<()> {
174        self.read_or_create_nimbus_id(db, writer, state)?;
175        self.update_ta_install_dates(db, writer, state)?;
176        self.event_store
177            .lock()
178            .expect("unable to lock event_store mutex")
179            .read_from_db(db)?;
180
181        if let Some(recorded_context) = &self.recorded_context {
182            let targeting_helper = self.create_targeting_helper_with_context(match serde_json::to_value(
183                &state.targeting_attributes,
184            ) {
185                Ok(v) => v,
186                Err(e) => return Err(NimbusError::JSONError("targeting_helper = nimbus::stateful::nimbus_client::NimbusClient::begin_initialize::serde_json::to_value".into(), e.to_string()))
187            });
188            recorded_context.execute_queries(targeting_helper.as_ref())?;
189            state
190                .targeting_attributes
191                .set_recorded_context(recorded_context.to_json());
192        }
193
194        if let Some(gecko_prefs) = &self.gecko_prefs {
195            gecko_prefs.initialize()?;
196        }
197
198        Ok(())
199    }
200
201    // These are tasks which should be in the initialize and apply_pending_experiments
202    // but should happen after the enrollment calculations are done.
203    fn end_initialize(
204        &self,
205        db: &Database,
206        writer: Writer,
207        state: &mut MutexGuard<InternalMutableState>,
208    ) -> Result<()> {
209        self.update_ta_active_experiments(db, &writer, state)?;
210        let coenrolling_ids = self
211            .coenrolling_feature_ids
212            .iter()
213            .map(|s| s.as_str())
214            .collect();
215        self.database_cache.commit_and_update(
216            db,
217            writer,
218            &coenrolling_ids,
219            self.gecko_prefs.clone(),
220        )?;
221        self.record_enrollment_status_telemetry(state)?;
222        Ok(())
223    }
224
225    pub fn get_enrollment_by_feature(&self, feature_id: String) -> Result<Option<EnrolledFeature>> {
226        self.database_cache.get_enrollment_by_feature(&feature_id)
227    }
228
229    // Note: the contract for this function is that it never blocks on IO.
230    pub fn get_experiment_branch(&self, slug: String) -> Result<Option<String>> {
231        self.database_cache.get_experiment_branch(&slug)
232    }
233
234    pub fn get_feature_config_variables(&self, feature_id: String) -> Result<Option<String>> {
235        Ok(
236            if let Some(s) = self
237                .database_cache
238                .get_feature_config_variables(&feature_id)?
239            {
240                self.record_feature_activation_if_needed(&feature_id);
241                Some(s)
242            } else {
243                None
244            },
245        )
246    }
247
248    pub fn get_experiment_branches(&self, slug: String) -> Result<Vec<ExperimentBranch>> {
249        self.get_all_experiments()?
250            .into_iter()
251            .find(|e| e.slug == slug)
252            .map(|e| e.branches.into_iter().map(|b| b.into()).collect())
253            .ok_or(NimbusError::NoSuchExperiment(slug))
254    }
255
256    pub fn get_experiment_participation(&self) -> Result<bool> {
257        let db = self.db()?;
258        let reader = db.read()?;
259        get_experiment_participation(db, &reader)
260    }
261
262    pub fn get_rollout_participation(&self) -> Result<bool> {
263        let db = self.db()?;
264        let reader = db.read()?;
265        get_rollout_participation(db, &reader)
266    }
267
268    pub fn set_experiment_participation(
269        &self,
270        user_participating: bool,
271    ) -> Result<Vec<EnrollmentChangeEvent>> {
272        let db = self.db()?;
273        let mut writer = db.write()?;
274        let mut state = self.mutable_state.lock().unwrap();
275        set_experiment_participation(db, &mut writer, user_participating)?;
276
277        let existing_experiments: Vec<Experiment> =
278            db.get_store(StoreId::Experiments).collect_all(&writer)?;
279        let events = self.evolve_experiments(db, &mut writer, &mut state, &existing_experiments)?;
280        self.end_initialize(db, writer, &mut state)?;
281        Ok(events)
282    }
283
284    pub fn set_rollout_participation(
285        &self,
286        user_participating: bool,
287    ) -> Result<Vec<EnrollmentChangeEvent>> {
288        let db = self.db()?;
289        let mut writer = db.write()?;
290        let mut state = self.mutable_state.lock().unwrap();
291        set_rollout_participation(db, &mut writer, user_participating)?;
292
293        let existing_experiments: Vec<Experiment> =
294            db.get_store(StoreId::Experiments).collect_all(&writer)?;
295        let events = self.evolve_experiments(db, &mut writer, &mut state, &existing_experiments)?;
296        self.end_initialize(db, writer, &mut state)?;
297        Ok(events)
298    }
299
300    pub fn get_active_experiments(&self) -> Result<Vec<EnrolledExperiment>> {
301        self.database_cache.get_active_experiments()
302    }
303
304    pub fn get_all_experiments(&self) -> Result<Vec<Experiment>> {
305        let db = self.db()?;
306        let reader = db.read()?;
307        db.get_store(StoreId::Experiments)
308            .collect_all::<Experiment, _>(&reader)
309    }
310
311    pub fn get_available_experiments(&self) -> Result<Vec<AvailableExperiment>> {
312        let th = self.create_targeting_helper(None)?;
313        Ok(self
314            .get_all_experiments()?
315            .into_iter()
316            .filter(|exp| is_experiment_available(&th, exp, false))
317            .map(|exp| exp.into())
318            .collect())
319    }
320
321    pub fn opt_in_with_branch(
322        &self,
323        experiment_slug: String,
324        branch: String,
325    ) -> Result<Vec<EnrollmentChangeEvent>> {
326        let db = self.db()?;
327        let mut writer = db.write()?;
328        let result = opt_in_with_branch(db, &mut writer, &experiment_slug, &branch)?;
329        let mut state = self.mutable_state.lock().unwrap();
330        self.end_initialize(db, writer, &mut state)?;
331        Ok(result)
332    }
333
334    pub fn opt_out(&self, experiment_slug: String) -> Result<Vec<EnrollmentChangeEvent>> {
335        let db = self.db()?;
336        let mut writer = db.write()?;
337        let result = opt_out(db, &mut writer, &experiment_slug)?;
338        let mut state = self.mutable_state.lock().unwrap();
339        self.end_initialize(db, writer, &mut state)?;
340        Ok(result)
341    }
342
343    pub fn fetch_experiments(&self) -> Result<()> {
344        if !self.is_fetch_enabled()? {
345            return Ok(());
346        }
347        info!("fetching experiments");
348        let settings_client = self.settings_client.lock().unwrap();
349        let new_experiments = settings_client.fetch_experiments()?;
350        let db = self.db()?;
351        let mut writer = db.write()?;
352        write_pending_experiments(db, &mut writer, new_experiments)?;
353        writer.commit()?;
354        Ok(())
355    }
356
357    pub fn set_fetch_enabled(&self, allow: bool) -> Result<()> {
358        let db = self.db()?;
359        let mut writer = db.write()?;
360        db.get_store(StoreId::Meta)
361            .put(&mut writer, DB_KEY_FETCH_ENABLED, &allow)?;
362        writer.commit()?;
363        Ok(())
364    }
365
366    pub(crate) fn is_fetch_enabled(&self) -> Result<bool> {
367        let db = self.db()?;
368        let reader = db.read()?;
369        let enabled = db
370            .get_store(StoreId::Meta)
371            .get(&reader, DB_KEY_FETCH_ENABLED)?
372            .unwrap_or(true);
373        Ok(enabled)
374    }
375
376    /**
377     * Calculate the days since install and days since update on the targeting_attributes.
378     */
379    fn update_ta_install_dates(
380        &self,
381        db: &Database,
382        writer: &mut Writer,
383        state: &mut MutexGuard<InternalMutableState>,
384    ) -> Result<()> {
385        // Only set install_date and update_date with this method if it hasn't been set already.
386        // This cuts down on deriving the dates at runtime, but also allows us to use
387        // the test methods set_install_date() and set_update_date() to set up
388        // scenarios for test.
389        if state.install_date.is_none() {
390            let installation_date = self.get_installation_date(db, writer)?;
391            state.install_date = Some(installation_date);
392        }
393        if state.update_date.is_none() {
394            let update_date = self.get_update_date(db, writer)?;
395            state.update_date = Some(update_date);
396        }
397        state.update_time_to_now(Utc::now());
398
399        Ok(())
400    }
401
402    /**
403     * Calculates the active_experiments based on current enrollments for the targeting attributes.
404     */
405    fn update_ta_active_experiments(
406        &self,
407        db: &Database,
408        writer: &Writer,
409        state: &mut MutexGuard<InternalMutableState>,
410    ) -> Result<()> {
411        let enrollments_store = db.get_store(StoreId::Enrollments);
412        let prev_enrollments: Vec<ExperimentEnrollment> = enrollments_store.collect_all(writer)?;
413
414        state
415            .targeting_attributes
416            .update_enrollments(&prev_enrollments);
417
418        Ok(())
419    }
420
421    fn evolve_experiments(
422        &self,
423        db: &Database,
424        writer: &mut Writer,
425        state: &mut InternalMutableState,
426        experiments: &[Experiment],
427    ) -> Result<Vec<EnrollmentChangeEvent>> {
428        let mut targeting_helper = NimbusTargetingHelper::with_targeting_attributes(
429            &state.targeting_attributes,
430            self.event_store.clone(),
431            self.gecko_prefs.clone(),
432        );
433        if let Some(ref recorded_context) = self.recorded_context {
434            recorded_context.record();
435        }
436        let coenrolling_feature_ids = self
437            .coenrolling_feature_ids
438            .iter()
439            .map(|s| s.as_str())
440            .collect();
441        let mut evolver = EnrollmentsEvolver::new(
442            &state.available_randomization_units,
443            &mut targeting_helper,
444            &coenrolling_feature_ids,
445        );
446        evolver.evolve_enrollments_in_db(db, writer, experiments)
447    }
448
449    pub fn apply_pending_experiments(&self) -> Result<Vec<EnrollmentChangeEvent>> {
450        info!("updating experiment list");
451        let db = self.db()?;
452        let mut writer = db.write()?;
453
454        // We'll get the pending experiments which were stored for us, either by fetch_experiments
455        // or by set_experiments_locally.
456        let pending_updates = read_and_remove_pending_experiments(db, &mut writer)?;
457        let mut state = self.mutable_state.lock().unwrap();
458        self.begin_initialize(db, &mut writer, &mut state)?;
459
460        let res = match pending_updates {
461            Some(new_experiments) => {
462                self.update_ta_active_experiments(db, &writer, &mut state)?;
463                // Perform the enrollment calculations if there are pending experiments.
464                self.evolve_experiments(db, &mut writer, &mut state, &new_experiments)?
465            }
466            None => vec![],
467        };
468
469        // Finish up any cleanup, e.g. copying from database in to memory.
470        self.end_initialize(db, writer, &mut state)?;
471        Ok(res)
472    }
473
474    #[allow(deprecated)] // Bug 1960256 - use of deprecated chrono functions.
475    fn get_installation_date(&self, db: &Database, writer: &mut Writer) -> Result<DateTime<Utc>> {
476        // we first check our context
477        if let Some(context_installation_date) = self.app_context.installation_date {
478            let res = DateTime::<Utc>::from_naive_utc_and_offset(
479                NaiveDateTime::from_timestamp_opt(context_installation_date / 1_000, 0).unwrap(),
480                Utc,
481            );
482            info!("[Nimbus] Retrieved date from Context: {}", res);
483            return Ok(res);
484        }
485        let store = db.get_store(StoreId::Meta);
486        let persisted_installation_date: Option<DateTime<Utc>> =
487            store.get(writer, DB_KEY_INSTALLATION_DATE)?;
488        Ok(
489            if let Some(installation_date) = persisted_installation_date {
490                installation_date
491            } else if let Some(home_directory) = &self.app_context.home_directory {
492                let installation_date = match self.get_creation_date_from_path(home_directory) {
493                    Ok(installation_date) => installation_date,
494                    Err(e) => {
495                        warn!("[Nimbus] Unable to get installation date from path, defaulting to today: {:?}", e);
496                        Utc::now()
497                    }
498                };
499                let store = db.get_store(StoreId::Meta);
500                store.put(writer, DB_KEY_INSTALLATION_DATE, &installation_date)?;
501                installation_date
502            } else {
503                Utc::now()
504            },
505        )
506    }
507
508    fn get_update_date(&self, db: &Database, writer: &mut Writer) -> Result<DateTime<Utc>> {
509        let store = db.get_store(StoreId::Meta);
510
511        let persisted_app_version: Option<String> = store.get(writer, DB_KEY_APP_VERSION)?;
512        let update_date: Option<DateTime<Utc>> = store.get(writer, DB_KEY_UPDATE_DATE)?;
513        Ok(
514            match (
515                persisted_app_version,
516                &self.app_context.app_version,
517                update_date,
518            ) {
519                // The app been run before, but has not just been updated.
520                (Some(persisted), Some(current), Some(date)) if persisted == *current => date,
521                // The app has been run before, and just been updated.
522                (Some(persisted), Some(current), _) if persisted != *current => {
523                    let now = Utc::now();
524                    store.put(writer, DB_KEY_APP_VERSION, current)?;
525                    store.put(writer, DB_KEY_UPDATE_DATE, &now)?;
526                    now
527                }
528                // The app has just been installed
529                (None, Some(current), _) => {
530                    let now = Utc::now();
531                    store.put(writer, DB_KEY_APP_VERSION, current)?;
532                    store.put(writer, DB_KEY_UPDATE_DATE, &now)?;
533                    now
534                }
535                // The current version is not available, or the persisted date is not available.
536                (_, _, Some(date)) => date,
537                // Either way, this doesn't appear to be a good production environment.
538                _ => Utc::now(),
539            },
540        )
541    }
542
543    #[cfg(not(test))]
544    fn get_creation_date_from_path<P: AsRef<Path>>(&self, path: P) -> Result<DateTime<Utc>> {
545        info!("[Nimbus] Getting creation date from path");
546        let metadata = std::fs::metadata(path)?;
547        let system_time_created = metadata.created()?;
548        let date_time_created = DateTime::<Utc>::from(system_time_created);
549        info!(
550            "[Nimbus] Creation date retrieved form path successfully: {}",
551            date_time_created
552        );
553        Ok(date_time_created)
554    }
555
556    #[cfg(test)]
557    fn get_creation_date_from_path<P: AsRef<Path>>(&self, path: P) -> Result<DateTime<Utc>> {
558        use std::io::Read;
559        let test_path = path.as_ref().with_file_name("test.json");
560        let mut file = std::fs::File::open(test_path)?;
561        let mut buf = String::new();
562        file.read_to_string(&mut buf)?;
563
564        let res = match serde_json::from_str::<DateTime<Utc>>(&buf) {
565            Ok(v) => v,
566            Err(e) => return Err(NimbusError::JSONError("res = nimbus::stateful::nimbus_client::get_creation_date_from_path::serde_json::from_str".into(), e.to_string()))
567        };
568        Ok(res)
569    }
570
571    pub fn set_experiments_locally(&self, experiments_json: String) -> Result<()> {
572        let new_experiments = parse_experiments(&experiments_json)?;
573        let db = self.db()?;
574        let mut writer = db.write()?;
575        write_pending_experiments(db, &mut writer, new_experiments)?;
576        writer.commit()?;
577        Ok(())
578    }
579
580    /// Reset all enrollments and experiments in the database.
581    ///
582    /// This should only be used in testing.
583    pub fn reset_enrollments(&self) -> Result<()> {
584        let db = self.db()?;
585        let mut writer = db.write()?;
586        let mut state = self.mutable_state.lock().unwrap();
587        db.clear_experiments_and_enrollments(&mut writer)?;
588        self.end_initialize(db, writer, &mut state)?;
589        Ok(())
590    }
591
592    /// Reset internal state in response to application-level telemetry reset.
593    ///
594    /// When the user resets their telemetry state in the consuming application, we need learn
595    /// the new values of any external randomization units, and we need to reset any unique
596    /// identifiers used internally by the SDK. If we don't then we risk accidentally tracking
597    /// across the telemetry reset, since we could use Nimbus metrics to link their pings from
598    /// before and after the reset.
599    ///
600    pub fn reset_telemetry_identifiers(&self) -> Result<Vec<EnrollmentChangeEvent>> {
601        let mut events = vec![];
602        let db = self.db()?;
603        let mut writer = db.write()?;
604        let mut state = self.mutable_state.lock().unwrap();
605        // If we have no `nimbus_id` when we can safely assume that there's
606        // no other experiment state that needs to be reset.
607        let store = db.get_store(StoreId::Meta);
608        if store.get::<String, _>(&writer, DB_KEY_NIMBUS_ID)?.is_some() {
609            // Each enrollment state now opts out because we don't want to leak information between resets.
610            events = reset_telemetry_identifiers(db, &mut writer)?;
611
612            // Remove any stored event counts
613            db.clear_event_count_data(&mut writer)?;
614
615            // The `nimbus_id` itself is a unique identifier.
616            // N.B. we do this last, as a signal that all data has been reset.
617            store.delete(&mut writer, DB_KEY_NIMBUS_ID)?;
618            self.end_initialize(db, writer, &mut state)?;
619        }
620
621        // (No need to commit `writer` if the above check was false, since we didn't change anything)
622        state.available_randomization_units = Default::default();
623        state.targeting_attributes.nimbus_id = None;
624
625        Ok(events)
626    }
627
628    pub fn nimbus_id(&self) -> Result<Uuid> {
629        let db = self.db()?;
630        let mut writer = db.write()?;
631        let mut state = self.mutable_state.lock().unwrap();
632        let uuid = self.read_or_create_nimbus_id(db, &mut writer, &mut state)?;
633
634        // We don't know whether we needed to generate and save the uuid, so
635        // we commit just in case - this is hopefully close to a noop in that
636        // case!
637        writer.commit()?;
638        Ok(uuid)
639    }
640
641    /// Return the nimbus ID from the database, or create a new one and write it
642    /// to the database.
643    ///
644    /// The internal state will be updated with the nimbus ID.
645    fn read_or_create_nimbus_id(
646        &self,
647        db: &Database,
648        writer: &mut Writer,
649        state: &mut MutexGuard<'_, InternalMutableState>,
650    ) -> Result<Uuid> {
651        let store = db.get_store(StoreId::Meta);
652        let nimbus_id = match store.get(writer, DB_KEY_NIMBUS_ID)? {
653            Some(nimbus_id) => nimbus_id,
654            None => {
655                let nimbus_id = Uuid::new_v4();
656                store.put(writer, DB_KEY_NIMBUS_ID, &nimbus_id)?;
657                nimbus_id
658            }
659        };
660
661        state.available_randomization_units.nimbus_id = Some(nimbus_id.to_string());
662        state.targeting_attributes.nimbus_id = Some(nimbus_id.to_string());
663
664        Ok(nimbus_id)
665    }
666
667    // Sets the nimbus ID - TEST ONLY - should not be exposed to real clients.
668    // (Useful for testing so you can have some control over what experiments
669    // are enrolled)
670    pub fn set_nimbus_id(&self, uuid: &Uuid) -> Result<()> {
671        let db = self.db()?;
672        let mut writer = db.write()?;
673        db.get_store(StoreId::Meta)
674            .put(&mut writer, DB_KEY_NIMBUS_ID, uuid)?;
675        writer.commit()?;
676        Ok(())
677    }
678
679    pub(crate) fn db(&self) -> Result<&Database> {
680        self.db.get_or_try_init(|| Database::new(&self.db_path))
681    }
682
683    fn merge_additional_context(&self, context: Option<JsonObject>) -> Result<Value> {
684        let context = context.map(Value::Object);
685        let targeting = match serde_json::to_value(self.get_targeting_attributes()) {
686            Ok(v) => v,
687            Err(e) => return Err(NimbusError::JSONError("targeting = nimbus::stateful::nimbus_client::NimbusClient::merge_additional_context::serde_json::to_value".into(), e.to_string()))
688        };
689        let context = match context {
690            Some(v) => v.defaults(&targeting)?,
691            None => targeting,
692        };
693
694        Ok(context)
695    }
696
697    pub fn create_targeting_helper(
698        &self,
699        additional_context: Option<JsonObject>,
700    ) -> Result<Arc<NimbusTargetingHelper>> {
701        let context = self.merge_additional_context(additional_context)?;
702        let helper =
703            NimbusTargetingHelper::new(context, self.event_store.clone(), self.gecko_prefs.clone());
704        Ok(Arc::new(helper))
705    }
706
707    pub fn create_targeting_helper_with_context(
708        &self,
709        context: Value,
710    ) -> Arc<NimbusTargetingHelper> {
711        Arc::new(NimbusTargetingHelper::new(
712            context,
713            self.event_store.clone(),
714            self.gecko_prefs.clone(),
715        ))
716    }
717
718    pub fn create_string_helper(
719        &self,
720        additional_context: Option<JsonObject>,
721    ) -> Result<Arc<NimbusStringHelper>> {
722        let context = self.merge_additional_context(additional_context)?;
723        let helper = NimbusStringHelper::new(context.as_object().unwrap().to_owned());
724        Ok(Arc::new(helper))
725    }
726
727    /// Records an event for the purposes of behavioral targeting.
728    ///
729    /// This function is used to record and persist data used for the behavioral
730    /// targeting such as "core-active" user targeting.
731    pub fn record_event(&self, event_id: String, count: i64) -> Result<()> {
732        let mut event_store = self.event_store.lock().unwrap();
733        event_store.record_event(count as u64, &event_id, None)?;
734        event_store.persist_data(self.db()?)?;
735        Ok(())
736    }
737
738    /// Records an event for the purposes of behavioral targeting.
739    ///
740    /// This differs from the `record_event` method in that the event is recorded as if it were
741    /// recorded `seconds_ago` in the past. This makes it very useful for testing.
742    pub fn record_past_event(&self, event_id: String, seconds_ago: i64, count: i64) -> Result<()> {
743        if seconds_ago < 0 {
744            return Err(NimbusError::BehaviorError(BehaviorError::InvalidDuration(
745                "Time duration in the past must be positive".to_string(),
746            )));
747        }
748        let mut event_store = self.event_store.lock().unwrap();
749        event_store.record_past_event(
750            count as u64,
751            &event_id,
752            None,
753            chrono::Duration::seconds(seconds_ago),
754        )?;
755        event_store.persist_data(self.db()?)?;
756        Ok(())
757    }
758
759    /// Advances the event store's concept of `now` artificially.
760    ///
761    /// This works alongside `record_event` and `record_past_event` for testing purposes.
762    pub fn advance_event_time(&self, by_seconds: i64) -> Result<()> {
763        if by_seconds < 0 {
764            return Err(NimbusError::BehaviorError(BehaviorError::InvalidDuration(
765                "Time duration in the future must be positive".to_string(),
766            )));
767        }
768        let mut event_store = self.event_store.lock().unwrap();
769        event_store.advance_datum(chrono::Duration::seconds(by_seconds));
770        Ok(())
771    }
772
773    /// Clear all events in the Nimbus event store.
774    ///
775    /// This should only be used in testing or cases where the previous event store is no longer viable.
776    pub fn clear_events(&self) -> Result<()> {
777        let mut event_store = self.event_store.lock().unwrap();
778        event_store.clear(self.db()?)?;
779        Ok(())
780    }
781
782    pub fn event_store(&self) -> Arc<Mutex<EventStore>> {
783        self.event_store.clone()
784    }
785
786    pub fn dump_state_to_log(&self) -> Result<()> {
787        let experiments = self.get_active_experiments()?;
788        info!("{0: <65}| {1: <30}| {2}", "Slug", "Features", "Branch");
789        for exp in &experiments {
790            info!(
791                "{0: <65}| {1: <30}| {2}",
792                &exp.slug,
793                &exp.feature_ids.join(", "),
794                &exp.branch_slug
795            );
796        }
797        Ok(())
798    }
799
800    /// Given a Gecko pref state and a pref unenroll reason, unenroll from an experiment
801    pub fn unenroll_for_gecko_pref(
802        &self,
803        pref_state: GeckoPrefState,
804        pref_unenroll_reason: PrefUnenrollReason,
805    ) -> Result<Vec<EnrollmentChangeEvent>> {
806        if let Some(prefs) = self.gecko_prefs.clone() {
807            {
808                let mut pref_store_state = prefs.get_mutable_pref_state();
809                pref_store_state.update_pref_state(&pref_state);
810            }
811            let enrollments = self
812                .database_cache
813                .get_enrollments_for_pref(&pref_state.gecko_pref.pref)?;
814
815            let db = self.db()?;
816            let mut writer = db.write()?;
817
818            let mut results = Vec::new();
819            for experiment_slug in enrollments.unwrap() {
820                let result =
821                    unenroll_for_pref(db, &mut writer, &experiment_slug, pref_unenroll_reason)?;
822                results.push(result);
823            }
824
825            let mut state = self.mutable_state.lock().unwrap();
826            self.end_initialize(db, writer, &mut state)?;
827            return Ok(results.concat());
828        }
829        Ok(Vec::new())
830    }
831
832    #[cfg(test)]
833    pub fn get_metrics_handler(&self) -> &&TestMetrics {
834        let metrics = &**self.metrics_handler;
835        // SAFETY: The cast to TestMetrics is safe because the Rust instance is guaranteed to be
836        // a TestMetrics instance. TestMetrics is the only Rust-implemented version of
837        // MetricsHandler, and, like this method, is only used in tests.
838        unsafe { std::mem::transmute::<&&dyn MetricsHandler, &&TestMetrics>(&metrics) }
839    }
840
841    #[cfg(test)]
842    pub fn get_recorded_context(&self) -> &&TestRecordedContext {
843        self.recorded_context
844            .clone()
845            .map(|ref recorded_context|
846                // SAFETY: The cast to TestRecordedContext is safe because the Rust instance is
847                // guaranteed to be a TestRecordedContext instance. TestRecordedContext is the only
848                // Rust-implemented version of RecordedContext, and, like this method,  is only
849                // used in tests.
850                unsafe {
851                    std::mem::transmute::<&&dyn RecordedContext, &&TestRecordedContext>(
852                        &&**recorded_context,
853                    )
854                })
855            .expect("failed to unwrap RecordedContext object")
856    }
857
858    #[cfg(test)]
859    pub fn get_gecko_pref_store(&self) -> Arc<Box<TestGeckoPrefHandler>> {
860        self.gecko_prefs.clone()
861            .clone()
862            .map(|ref pref_store|
863                // SAFETY: The cast to TestGeckoPrefHandler is safe because the Rust instance is
864                // guaranteed to be a TestGeckoPrefHandler instance. TestGeckoPrefHandler is the only
865                // Rust-implemented version of GeckoPrefHandler, and, like this method,  is only
866                // used in tests.
867                unsafe {
868                    std::mem::transmute::<Arc<Box<dyn GeckoPrefHandler>>, Arc<Box<TestGeckoPrefHandler>>>(
869                        pref_store.clone().handler.clone(),
870                    )
871                })
872            .expect("failed to unwrap GeckoPrefHandler object")
873    }
874}
875
876impl NimbusClient {
877    pub fn set_install_time(&mut self, then: DateTime<Utc>) {
878        let mut state = self.mutable_state.lock().unwrap();
879        state.install_date = Some(then);
880        state.update_time_to_now(Utc::now());
881    }
882
883    pub fn set_update_time(&mut self, then: DateTime<Utc>) {
884        let mut state = self.mutable_state.lock().unwrap();
885        state.update_date = Some(then);
886        state.update_time_to_now(Utc::now());
887    }
888}
889
890impl NimbusClient {
891    /// This is only called from `get_feature_config_variables` which is itself is cached with
892    /// thread safety in the FeatureHolder.kt and FeatureHolder.swift
893    fn record_feature_activation_if_needed(&self, feature_id: &str) {
894        if let Ok(Some(f)) = self.database_cache.get_enrollment_by_feature(feature_id) {
895            if f.branch.is_some() && !self.coenrolling_feature_ids.contains(&f.feature_id) {
896                self.metrics_handler.record_feature_activation(f.into());
897            }
898        }
899    }
900
901    pub fn record_feature_exposure(&self, feature_id: String, slug: Option<String>) {
902        let event = if let Some(slug) = slug {
903            if let Ok(Some(branch)) = self.database_cache.get_experiment_branch(&slug) {
904                Some(FeatureExposureExtraDef {
905                    feature_id,
906                    branch: Some(branch),
907                    slug,
908                })
909            } else {
910                None
911            }
912        } else if let Ok(Some(f)) = self.database_cache.get_enrollment_by_feature(&feature_id) {
913            if f.branch.is_some() {
914                Some(f.into())
915            } else {
916                None
917            }
918        } else {
919            None
920        };
921
922        if let Some(event) = event {
923            self.metrics_handler.record_feature_exposure(event);
924        }
925    }
926
927    pub fn record_malformed_feature_config(&self, feature_id: String, part_id: String) {
928        let event = if let Ok(Some(f)) = self.database_cache.get_enrollment_by_feature(&feature_id)
929        {
930            MalformedFeatureConfigExtraDef::from(f, part_id)
931        } else {
932            MalformedFeatureConfigExtraDef::new(feature_id, part_id)
933        };
934        self.metrics_handler.record_malformed_feature_config(event);
935    }
936
937    fn record_enrollment_status_telemetry(
938        &self,
939        state: &mut MutexGuard<InternalMutableState>,
940    ) -> Result<()> {
941        let targeting_helper = NimbusTargetingHelper::new(
942            state.targeting_attributes.clone(),
943            self.event_store.clone(),
944            self.gecko_prefs.clone(),
945        );
946        let experiments = self
947            .database_cache
948            .get_experiments()?
949            .iter()
950            .filter_map(
951                |exp| match is_experiment_available(&targeting_helper, exp, true) {
952                    true => Some(exp.slug.clone()),
953                    false => None,
954                },
955            )
956            .collect::<HashSet<String>>();
957        self.metrics_handler.record_enrollment_statuses(
958            self.database_cache
959                .get_enrollments()?
960                .into_iter()
961                .filter_map(|e| match experiments.contains(&e.slug) {
962                    true => Some(e.into()),
963                    false => None,
964                })
965                .collect(),
966        );
967        Ok(())
968    }
969}
970
971pub struct NimbusStringHelper {
972    context: JsonObject,
973}
974
975impl NimbusStringHelper {
976    fn new(context: JsonObject) -> Self {
977        Self { context }
978    }
979
980    pub fn get_uuid(&self, template: String) -> Option<String> {
981        if template.contains("{uuid}") {
982            let uuid = Uuid::new_v4();
983            Some(uuid.to_string())
984        } else {
985            None
986        }
987    }
988
989    pub fn string_format(&self, template: String, uuid: Option<String>) -> String {
990        match uuid {
991            Some(uuid) => {
992                let mut map = self.context.clone();
993                map.insert("uuid".to_string(), Value::String(uuid));
994                fmt_with_map(&template, &map)
995            }
996            _ => fmt_with_map(&template, &self.context),
997        }
998    }
999}
1000
1001#[cfg(feature = "stateful-uniffi-bindings")]
1002uniffi::custom_type!(JsonObject, String, {
1003    remote,
1004    try_lift: |val| {
1005        let json: Value = serde_json::from_str(&val)?;
1006
1007        match json.as_object() {
1008            Some(obj) => Ok(obj.clone()),
1009            _ => Err(uniffi::deps::anyhow::anyhow!(
1010                "Unexpected JSON-non-object in the bagging area"
1011            )),
1012        }
1013    },
1014    lower: |obj| serde_json::Value::Object(obj).to_string(),
1015});
1016
1017#[cfg(feature = "stateful-uniffi-bindings")]
1018uniffi::custom_type!(PrefValue, String, {
1019    remote,
1020    try_lift: |val| {
1021        let json: Value = serde_json::from_str(&val)?;
1022        if json.is_string() || json.is_boolean() || (json.is_number() && !json.is_f64()) || json.is_null() {
1023            Ok(json)
1024        } else {
1025            Err(anyhow::anyhow!(format!("Value {} is not a string, boolean, number, or null, or is a float", json)))
1026        }
1027    },
1028    lower: |val| {
1029        val.to_string()
1030    }
1031});
1032
1033#[cfg(feature = "stateful-uniffi-bindings")]
1034uniffi::include_scaffolding!("nimbus");
nimbus/stateful/nimbus_client.rs

nimbus/stateful/
nimbus_client.rs
