Bug 1997373 - Store original gecko pref values for Fenix Gecko integration

This patch begins storing a `Vec<PreviousGeckoPrefState>` on `ExperimentEnrollment` when it is of type `EnrollmentStatus::Enrolled`
for managing the original value of gecko prefs used in an experiment.

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

Author: ohall-m

CHANGELOG.md

@@ -1,4 +1,6 @@
 # v148.0 (In progress)
+### Nimbus
+* Adds `PreviousGeckoPrefState` on `ExperimentEnrollment` when it is of type `EnrollmentStatus::Enrolled` and getters and setters. This is to support returning to an original value on 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.PreviousGeckoPrefState
 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 getPreviousGeckoPrefStates(experimentSlug: String): List<PreviousGeckoPrefState>? {
+        return nimbusClient.getPreviousGeckoPrefStates(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.PreviousGeckoPrefState
 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 list of previous states, if available on an enrolled experiment, from a given slug.
+     *
+     * @param experimentSlug The slug of the experiment.
+     * @return The previous Gecko pref state of the given slug. Will return null if not available or invalid slug.
+     */
+    fun getPreviousGeckoPrefStates(
+        experimentSlug: String,
+    ): List<PreviousGeckoPrefState>? = 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,14 @@ 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.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 +853,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 +915,37 @@ 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 previousStates = nimbus.getPreviousGeckoPrefStates("test-experiment")
+        shadowOf(Looper.getMainLooper()).idle()
+
+        assertNotNull(previousStates)
+        val geckoPreviousStates = previousStates as List<PreviousGeckoPrefState>
+        assertEquals(1, geckoPreviousStates.size)
+        assertEquals("1", geckoPreviousStates[0].originalValue.value)
+        assertEquals("pref.number", geckoPreviousStates[0].originalValue.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,20 @@ impl Display for DisqualifiedReason {
     }
 }
 
-// Every experiment has an ExperimentEnrollment, even when we aren't enrolled.
+// The previous state of a Gecko pref before enrollment took place.
+// ⚠️ 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_value: OriginalGeckoPref,
+    pub feature_id: String,
+    pub variable: String,
+}
 
+// 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 +440,23 @@ impl ExperimentEnrollment {
         }
     }
 
+    // Previous gecko pref state is only settable on Enrolled experiments
+    #[cfg(feature = "stateful")]
+    pub(crate) fn on_add_gecko_pref_state(
+        &self,
+        prev_gecko_pref_states: Vec<PreviousGeckoPrefState>,
+    ) -> ExperimentEnrollment {
+        let mut next = self.clone();
+        if let EnrollmentStatus::Enrolled { reason, branch, .. } = &self.status {
+            next.status = EnrollmentStatus::Enrolled {
+                prev_gecko_pref_states: Some(prev_gecko_pref_states),
+                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 +558,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")]
+        prev_gecko_pref_states: Option<Vec<PreviousGeckoPrefState>>,
     },
     NotEnrolled {
         reason: NotEnrolledReason,
@@ -577,6 +607,8 @@ impl EnrollmentStatus {
         EnrollmentStatus::Enrolled {
             reason,
             branch: branch.to_owned(),
+            #[cfg(feature = "stateful")]
+            prev_gecko_pref_states: 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::PreviousGeckoPrefState;
+
 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 prev_gecko_pref_states: Option<Vec<PreviousGeckoPrefState>>,
 }
 
 #[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")]
+            prev_gecko_pref_states: None,
         }
     }
 }

components/nimbus/src/nimbus.udl

@@ -101,6 +101,14 @@ dictionary EnrollmentStatusExtraDef {
     string? reason;
     string? slug;
     string? status;
+    sequence<PreviousGeckoPrefState>? prev_gecko_pref_states;
+};
+
+
+dictionary PreviousGeckoPrefState {
+    OriginalGeckoPref original_value;
+    string feature_id;
+    string variable;
 };
 
 dictionary FeatureExposureExtraDef {
@@ -139,12 +147,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 +378,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]
+    sequence<PreviousGeckoPrefState>? get_previous_gecko_pref_states(string experiment_slug);
 };
 
 interface NimbusTargetingHelper {