Bug 1997373 - Store original pref values for Fenix Gecko integration

This patch begins storing a `PreviousState` on `ExperimentEnrollment` when it is of type `EnrollmentStatus::Enrolled`.
It also introduces `PreviousState::GeckoPref` to hold Gecko original preference values
for Gecko pref based experiments.

The public APIs it opens are `registerPreviousGeckoPrefStates` and `getPreviousState`.

Author: ohall-m

CHANGELOG.md

@@ -1,4 +1,6 @@
 # v148.0 (In progress)
+### Nimbus
+* Adds `PreviousState` on `ExperimentEnrollment` when it is of type `EnrollmentStatus::Enrolled` and getters and setters. `PreviousState::GeckoPref` is added to support previous states for Gecko pref experiments.
 
 [Full Changelog](In progress)
 

components/nimbus/android/src/main/java/org/mozilla/experiments/nimbus/Nimbus.kt

@@ -44,6 +44,7 @@ import org.mozilla.experiments.nimbus.internal.NimbusClient
 import org.mozilla.experiments.nimbus.internal.NimbusClientInterface
 import org.mozilla.experiments.nimbus.internal.NimbusException
 import org.mozilla.experiments.nimbus.internal.PrefUnenrollReason
+import org.mozilla.experiments.nimbus.internal.PreviousState
 import org.mozilla.experiments.nimbus.internal.RecordedContext
 import java.io.File
 import java.io.IOException
@@ -438,6 +439,18 @@ open class Nimbus(
         return nimbusClient.unenrollForGeckoPref(geckoPrefState, prefUnenrollReason)
     }
 
+    override fun registerPreviousGeckoPrefStates(geckoPrefStates: List<GeckoPrefState>) {
+        dbScope.launch {
+            withCatchAll("registerPreviousGeckoPrefStates") {
+                nimbusClient.registerPreviousGeckoPrefStates(geckoPrefStates)
+            }
+        }
+    }
+
+    override fun getPreviousState(experimentSlug: String): PreviousState? {
+        return nimbusClient.getPreviousState(experimentSlug)
+    }
+
     @WorkerThread
     @VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
     internal fun optOutOnThisThread(experimentId: String) = withCatchAll("optOut") {

components/nimbus/android/src/main/java/org/mozilla/experiments/nimbus/NimbusInterface.kt

@@ -17,6 +17,7 @@ import org.mozilla.experiments.nimbus.internal.EnrollmentChangeEvent
 import org.mozilla.experiments.nimbus.internal.ExperimentBranch
 import org.mozilla.experiments.nimbus.internal.GeckoPrefState
 import org.mozilla.experiments.nimbus.internal.PrefUnenrollReason
+import org.mozilla.experiments.nimbus.internal.PreviousState
 import java.time.Duration
 import java.util.concurrent.TimeUnit
 
@@ -191,6 +192,26 @@ interface NimbusInterface : FeaturesInterface, NimbusMessagingInterface, NimbusE
         prefUnenrollReason: PrefUnenrollReason,
     ): List<EnrollmentChangeEvent> = listOf()
 
+    /**
+     * Add the original Gecko pref values as a previous state on each involved enrollment.
+     *
+     * @param geckoPrefStates The list of items that should have their enrollment state updated with
+     * original Gecko pref previous state information.
+     */
+    fun registerPreviousGeckoPrefStates(
+        geckoPrefStates: List<GeckoPrefState>,
+    ) = Unit
+
+    /**
+     * Retrieves a previous state, if available on an enrolled experiment, from a given slug.
+     *
+     * @param experimentSlug The slug of the experiment.
+     * @return The previous state of the given slug. Will return null if not available or invalid slug.
+     */
+    fun getPreviousState(
+        experimentSlug: String,
+    ): PreviousState? = null
+
     /**
      *  Reset internal state in response to application-level telemetry reset.
      *  Consumers should call this method when the user resets the telemetry state of the

components/nimbus/android/src/test/java/org/mozilla/experiments/nimbus/NimbusTests.kt

@@ -5,6 +5,7 @@
 package org.mozilla.experiments.nimbus
 
 import android.content.Context
+import android.os.Looper
 import android.util.Log
 import androidx.test.core.app.ApplicationProvider
 import kotlinx.coroutines.CancellationException
@@ -43,11 +44,15 @@ import org.mozilla.experiments.nimbus.internal.GeckoPrefState
 import org.mozilla.experiments.nimbus.internal.JsonObject
 import org.mozilla.experiments.nimbus.internal.NimbusException
 import org.mozilla.experiments.nimbus.internal.PrefBranch
+import org.mozilla.experiments.nimbus.internal.PrefEnrollmentData
 import org.mozilla.experiments.nimbus.internal.PrefUnenrollReason
+import org.mozilla.experiments.nimbus.internal.PreviousGeckoPrefState
+import org.mozilla.experiments.nimbus.internal.PreviousState
 import org.mozilla.experiments.nimbus.internal.RecordedContext
 import org.mozilla.experiments.nimbus.internal.getCalculatedAttributes
 import org.mozilla.experiments.nimbus.internal.validateEventQueries
 import org.robolectric.RobolectricTestRunner
+import org.robolectric.Shadows.shadowOf
 import java.io.File
 import java.util.Calendar
 import java.util.concurrent.Executors
@@ -849,7 +854,7 @@ class NimbusTests {
                 "number" to GeckoPrefState(
                     geckoPref = GeckoPref("pref.number", PrefBranch.DEFAULT),
                     geckoValue = "1",
-                    enrollmentValue = null,
+                    enrollmentValue = PrefEnrollmentData("test-experiment", "42", "about_welcome", "number"),
                     isUserSet = false,
                 ),
             ),
@@ -911,6 +916,36 @@ class NimbusTests {
         assertEquals(EnrollmentChangeEventType.DISQUALIFICATION, events[0].change)
         assertEquals(0, handler.setValues?.size)
     }
+
+    @Test
+    fun `register previous gecko states and check values`() {
+        val handler = TestGeckoPrefHandler()
+
+        val nimbus = createNimbus(geckoPrefHandler = handler)
+
+        suspend fun getString(): String {
+            return testExperimentsJsonString(appInfo, packageName)
+        }
+
+        val job = nimbus.applyLocalExperiments(::getString)
+        runBlocking {
+            job.join()
+        }
+
+        assertEquals(1, handler.setValues?.size)
+        assertEquals("42", handler.setValues?.get(0)?.enrollmentValue?.prefValue)
+
+        nimbus.registerPreviousGeckoPrefStates(handler.setValues!!)
+        shadowOf(Looper.getMainLooper()).idle()
+
+        val previousState = nimbus.getPreviousState("test-experiment")
+        shadowOf(Looper.getMainLooper()).idle()
+
+        assertNotNull(previousState)
+        val geckoPreviousState = previousState as PreviousState.GeckoPref
+        assertEquals("1", geckoPreviousState!!.v1.originalValues[0].value)
+        assertEquals("pref.number", geckoPreviousState!!.v1.originalValues[0].pref)
+    }
 }
 
 // Mocking utilities, from mozilla.components.support.test

components/nimbus/src/enrollment.rs

@@ -2,7 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 #[cfg(feature = "stateful")]
-use crate::stateful::gecko_prefs::PrefUnenrollReason;
+use crate::stateful::gecko_prefs::{OriginalGeckoPref, PrefUnenrollReason};
 use crate::{
     defaults::Defaults,
     error::{debug, warn, NimbusError, Result},
@@ -21,7 +21,7 @@ pub(crate) const PREVIOUS_ENROLLMENTS_GC_TIME: Duration = Duration::from_secs(36
 
 // These are types we use internally for managing enrollments.
 // ⚠️ Attention : Changes to this type should be accompanied by a new test  ⚠️
-// ⚠️ in `mod test_schema_bw_compat` below, and may require a DB migration. ⚠️
+// ⚠️ in `src/stateful/tests/test_enrollment_bw_compat.rs` below, and may require a DB migration. ⚠️
 #[derive(Deserialize, Serialize, Debug, Clone, Hash, Eq, PartialEq)]
 pub enum EnrolledReason {
     /// A normal enrollment as per the experiment's rules.
@@ -45,7 +45,7 @@ impl Display for EnrolledReason {
 // These are types we use internally for managing non-enrollments.
 
 // ⚠️ Attention : Changes to this type should be accompanied by a new test  ⚠️
-// ⚠️ in `mod test_schema_bw_compat` below, and may require a DB migration. ⚠️
+// ⚠️ in `src/stateful/tests/test_enrollment_bw_compat.rs` below, and may require a DB migration. ⚠️
 #[derive(Deserialize, Serialize, Debug, Clone, Hash, Eq, PartialEq)]
 pub enum NotEnrolledReason {
     /// The experiment targets a different application.
@@ -99,7 +99,7 @@ impl Default for Participation {
 // These are types we use internally for managing disqualifications.
 
 // ⚠️ Attention : Changes to this type should be accompanied by a new test  ⚠️
-// ⚠️ in `mod test_schema_bw_compat` below, and may require a DB migration. ⚠️
+// ⚠️ in `src/stateful/tests/test_enrollment_bw_compat.rs` below, and may require a DB migration. ⚠️
 #[derive(Deserialize, Serialize, Debug, Clone, Hash, Eq, PartialEq)]
 pub enum DisqualifiedReason {
     /// There was an error.
@@ -134,10 +134,26 @@ impl Display for DisqualifiedReason {
     }
 }
 
-// Every experiment has an ExperimentEnrollment, even when we aren't enrolled.
+// The previous state of a feature before enrollment.
+// ⚠️ Attention : Changes to this type should be accompanied by a new test  ⚠️
+// ⚠️ in `src/stateful/tests/test_enrollment_bw_compat.rs` below, and may require a DB migration. ⚠️
+#[derive(Deserialize, Serialize, Debug, Clone, Hash, Eq, PartialEq)]
+#[cfg(feature = "stateful")]
+pub struct PreviousGeckoPrefState {
+    pub original_values: Vec<OriginalGeckoPref>,
+    pub feature_id: String,
+    pub variable: String,
+}
+
+#[derive(Deserialize, Serialize, Debug, Clone, Hash, Eq, PartialEq, uniffi::Enum)]
+#[cfg(feature = "stateful")]
+pub enum PreviousState {
+    GeckoPref(PreviousGeckoPrefState),
+}
 
+// Every experiment has an ExperimentEnrollment, even when we aren't enrolled.
 // ⚠️ Attention : Changes to this type should be accompanied by a new test  ⚠️
-// ⚠️ in `mod test_schema_bw_compat` below, and may require a DB migration. ⚠️
+// ⚠️ in `src/stateful/tests/test_enrollment_bw_compat.rs` below, and may require a DB migration. ⚠️
 #[derive(Deserialize, Serialize, Debug, Clone, PartialEq, Eq)]
 pub struct ExperimentEnrollment {
     pub slug: String,
@@ -430,6 +446,20 @@ impl ExperimentEnrollment {
         }
     }
 
+    // Previous state is only settable on Enrolled experiments
+    #[cfg(feature = "stateful")]
+    pub(crate) fn on_add_state(&self, previous_state: PreviousState) -> ExperimentEnrollment {
+        let mut next = self.clone();
+        if let EnrollmentStatus::Enrolled { reason, branch, .. } = &self.status {
+            next.status = EnrollmentStatus::Enrolled {
+                previous_state: Some(previous_state),
+                reason: reason.clone(),
+                branch: branch.clone(),
+            };
+        }
+        next
+    }
+
     /// Reset identifiers in response to application-level telemetry reset.
     ///
     /// We move any enrolled experiments to the "disqualified" state, since their further
@@ -531,12 +561,15 @@ impl ExperimentEnrollment {
 }
 
 // ⚠️ Attention : Changes to this type should be accompanied by a new test  ⚠️
-// ⚠️ in `mod test_schema_bw_compat` below, and may require a DB migration. ⚠️
+// ⚠️ in `src/stateful/tests/test_enrollment_bw_compat.rs` below, and may require a DB migration. ⚠️
 #[derive(Deserialize, Serialize, Debug, Clone, Hash, Eq, PartialEq)]
 pub enum EnrollmentStatus {
     Enrolled {
         reason: EnrolledReason,
         branch: String,
+        #[cfg(feature = "stateful")]
+        #[serde(skip_serializing_if = "Option::is_none")]
+        previous_state: Option<PreviousState>,
     },
     NotEnrolled {
         reason: NotEnrolledReason,
@@ -577,6 +610,8 @@ impl EnrollmentStatus {
         EnrollmentStatus::Enrolled {
             reason,
             branch: branch.to_owned(),
+            #[cfg(feature = "stateful")]
+            previous_state: None,
         }
     }
 

components/nimbus/src/metrics.rs

@@ -2,6 +2,9 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
 
+#[cfg(feature = "stateful")]
+use crate::enrollment::PreviousState;
+
 use crate::{enrollment::ExperimentEnrollment, EnrolledFeature, EnrollmentStatus};
 use serde_derive::{Deserialize, Serialize};
 
@@ -28,6 +31,9 @@ pub struct EnrollmentStatusExtraDef {
     pub status: Option<String>,
     #[cfg(not(feature = "stateful"))]
     pub user_id: Option<String>,
+    #[cfg(feature = "stateful")]
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub previous_state: Option<PreviousState>,
 }
 
 #[cfg(test)]
@@ -93,6 +99,8 @@ impl From<ExperimentEnrollment> for EnrollmentStatusExtraDef {
             status: Some(enrollment.status.name()),
             #[cfg(not(feature = "stateful"))]
             user_id: None,
+            #[cfg(feature = "stateful")]
+            previous_state: None,
         }
     }
 }

components/nimbus/src/nimbus.udl

@@ -94,13 +94,23 @@ callback interface MetricsHandler {
     void record_malformed_feature_config(MalformedFeatureConfigExtraDef event);
 };
 
+typedef enum PreviousState;
+
 dictionary EnrollmentStatusExtraDef {
     string? branch;
     string? conflict_slug;
     string? error_string;
     string? reason;
     string? slug;
     string? status;
+    PreviousState? previous_state;
+};
+
+
+dictionary PreviousGeckoPrefState {
+    sequence<OriginalGeckoPref> original_values;
+    string feature_id;
+    string variable;
 };
 
 dictionary FeatureExposureExtraDef {
@@ -139,12 +149,20 @@ enum PrefBranch {
     "User",
 };
 
+dictionary OriginalGeckoPref {
+    string pref;
+    PrefBranch branch;
+    PrefValue? value;
+};
+
+
 enum PrefUnenrollReason {
     "Changed",
     "FailedToSet",
 };
 
 dictionary PrefEnrollmentData {
+    string experiment_slug;
     PrefValue pref_value;
     string feature_id;
     string variable;
@@ -362,6 +380,11 @@ interface NimbusClient {
     [Throws=NimbusError]
     sequence<EnrollmentChangeEvent> unenroll_for_gecko_pref(GeckoPrefState pref_state, PrefUnenrollReason pref_unenroll_reason);
 
+    [Throws=NimbusError]
+    void register_previous_gecko_pref_states([ByRef] sequence<GeckoPrefState> gecko_pref_states);
+
+    [Throws=NimbusError]
+    PreviousState? get_previous_state(string experiment_slug);
 };
 
 interface NimbusTargetingHelper {

components/nimbus/src/stateful/enrollment.rs

@@ -1,7 +1,7 @@
 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
-use crate::enrollment::Participation;
+use crate::enrollment::{Participation, PreviousState};
 use crate::stateful::persistence::{
     DB_KEY_EXPERIMENT_PARTICIPATION, DB_KEY_ROLLOUT_PARTICIPATION,
     DEFAULT_EXPERIMENT_PARTICIPATION, DEFAULT_ROLLOUT_PARTICIPATION,
@@ -180,6 +180,24 @@ pub fn unenroll_for_pref(
     Ok(events)
 }
 
+#[inline]
+pub fn get_previous_state_for_experiment<'r>(
+    db: &Database,
+    reader: &'r impl Readable<'r>,
+    experiment_slug: &str,
+) -> Result<Option<PreviousState>> {
+    Ok(db
+        .get_store(StoreId::Enrollments)
+        .get::<ExperimentEnrollment, _>(reader, experiment_slug)?
+        .and_then(|enrollment| {
+            if let EnrollmentStatus::Enrolled { previous_state, .. } = enrollment.status {
+                previous_state
+            } else {
+                None
+            }
+        }))
+}
+
 pub fn get_experiment_participation<'r>(
     db: &Database,
     reader: &'r impl Readable<'r>,