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,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.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 +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,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.originalValues[0].prefValue)
+        assertEquals("pref.number", geckoPreviousState.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},
@@ -134,6 +134,34 @@ impl Display for DisqualifiedReason {
     }
 }
 
+// The previous state of a feature before enrollment.
+// ⚠️ 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. ⚠️
+#[derive(Deserialize, Serialize, Debug, Clone, Hash, Eq, PartialEq)]
+#[cfg(feature = "stateful")]
+pub enum PreviousState {
+    GeckoPref {
+        original_values: Vec<OriginalGeckoPref>,
+        feature_id: String,
+        variable: String,
+    },
+}
+#[cfg(feature = "stateful")]
+impl Display for PreviousState {
+    fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
+        match self {
+            PreviousState::GeckoPref {
+                original_values,
+                feature_id,
+                variable,
+            } => write!(
+                f,
+                "original_values = {:?} feature_id = {} variable = {}",
+                original_values, feature_id, variable
+            ),
+        }
+    }
+}
 // Every experiment has an ExperimentEnrollment, even when we aren't enrolled.
 
 // ⚠️ Attention : Changes to this type should be accompanied by a new test  ⚠️
@@ -430,6 +458,22 @@ impl ExperimentEnrollment {
         }
     }
 
+    // Previous state is only settable on Enrolled experiments
+    #[cfg(feature = "stateful")]
+    pub(crate) fn on_add_state(&self, previous_state: PreviousState) -> ExperimentEnrollment {
+        match self.status.clone() {
+            EnrollmentStatus::Enrolled { reason, branch, .. } => ExperimentEnrollment {
+                status: EnrollmentStatus::Enrolled {
+                    previous_state: Some(previous_state),
+                    reason,
+                    branch,
+                },
+                ..self.clone()
+            },
+            _ => self.clone(),
+        }
+    }
+
     /// Reset identifiers in response to application-level telemetry reset.
     ///
     /// We move any enrolled experiments to the "disqualified" state, since their further
@@ -537,6 +581,9 @@ 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 +624,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

@@ -101,6 +101,12 @@ dictionary EnrollmentStatusExtraDef {
     string? reason;
     string? slug;
     string? status;
+    PreviousState? previous_state;
+};
+
+[Enum]
+interface PreviousState {
+  GeckoPref(sequence<OriginalGeckoPref> original_values, string feature_id, string variable);
 };
 
 dictionary FeatureExposureExtraDef {
@@ -139,12 +145,20 @@ enum PrefBranch {
     "User",
 };
 
+dictionary OriginalGeckoPref {
+    string pref;
+    PrefBranch branch;
+    PrefValue? pref_value;
+};
+
+
 enum PrefUnenrollReason {
     "Changed",
     "FailedToSet",
 };
 
 dictionary PrefEnrollmentData {
+    string experiment_slug;
     PrefValue pref_value;
     string feature_id;
     string variable;
@@ -362,6 +376,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(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,47 @@ pub fn unenroll_for_pref(
     Ok(events)
 }
 
+pub fn add_previous_state_for_experiment(
+    db: &Database,
+    writer: &mut Writer,
+    experiment_slug: &str,
+    previous_state: PreviousState,
+) -> Result<()> {
+    let enr_store = db.get_store(StoreId::Enrollments);
+
+    if let Ok(Some(existing_enrollment)) =
+        enr_store.get::<ExperimentEnrollment, Writer>(writer, experiment_slug)
+    {
+        // Previous state is only valid on Enrolled experiments
+        let updated_state = &existing_enrollment.on_add_state(previous_state);
+        enr_store.put(writer, experiment_slug, updated_state)?;
+    }
+    Ok(())
+}
+
+pub fn get_previous_state_for_experiment<'r>(
+    db: &Database,
+    reader: &'r impl Readable<'r>,
+    experiment_slug: &str,
+) -> Result<Option<PreviousState>> {
+    let enr_store = db.get_store(StoreId::Enrollments);
+
+    match enr_store.get::<ExperimentEnrollment, _>(reader, experiment_slug)? {
+        Some(enrollment) => {
+            if let EnrollmentStatus::Enrolled {
+                previous_state: Some(previous_state),
+                ..
+            } = enrollment.status
+            {
+                Ok(Some(previous_state))
+            } else {
+                Ok(None)
+            }
+        }
+        None => Ok(None),
+    }
+}
+
 pub fn get_experiment_participation<'r>(
     db: &Database,
     reader: &'r impl Readable<'r>,