Add a framework for running experiments to improve push notification reliability

Author: jon-signal

service/config/sample.yml

@@ -116,6 +116,8 @@ dynamoDbTables:
     tableName: Example_Profiles
   pushChallenge:
     tableName: Example_PushChallenge
+  pushNotificationExperimentSamples:
+    tableName: Example_PushNotificationExperimentSamples
   redeemedReceipts:
     tableName: Example_RedeemedReceipts
     expiration: P30D # Duration of time until rows expire

service/src/main/java/org/whispersystems/textsecuregcm/configuration/DynamoDbTables.java

@@ -63,6 +63,7 @@ public Duration getExpiration() {
   private final Table phoneNumberIdentifiers;
   private final Table profiles;
   private final Table pushChallenge;
+  private final Table pushNotificationExperimentSamples;
   private final TableWithExpiration redeemedReceipts;
   private final TableWithExpiration registrationRecovery;
   private final Table remoteConfig;
@@ -88,6 +89,7 @@ public DynamoDbTables(
       @JsonProperty("phoneNumberIdentifiers") final Table phoneNumberIdentifiers,
       @JsonProperty("profiles") final Table profiles,
       @JsonProperty("pushChallenge") final Table pushChallenge,
+      @JsonProperty("pushNotificationExperimentSamples") final Table pushNotificationExperimentSamples,
       @JsonProperty("redeemedReceipts") final TableWithExpiration redeemedReceipts,
       @JsonProperty("registrationRecovery") final TableWithExpiration registrationRecovery,
       @JsonProperty("remoteConfig") final Table remoteConfig,
@@ -112,6 +114,7 @@ public DynamoDbTables(
     this.phoneNumberIdentifiers = phoneNumberIdentifiers;
     this.profiles = profiles;
     this.pushChallenge = pushChallenge;
+    this.pushNotificationExperimentSamples = pushNotificationExperimentSamples;
     this.redeemedReceipts = redeemedReceipts;
     this.registrationRecovery = registrationRecovery;
     this.remoteConfig = remoteConfig;
@@ -217,6 +220,12 @@ public Table getPushChallenge() {
     return pushChallenge;
   }
 
+  @NotNull
+  @Valid
+  public Table getPushNotificationExperimentSamples() {
+    return pushNotificationExperimentSamples;
+  }
+
   @NotNull
   @Valid
   public TableWithExpiration getRedeemedReceipts() {

service/src/main/java/org/whispersystems/textsecuregcm/experiment/PushNotificationExperiment.java

@@ -0,0 +1,68 @@
+package org.whispersystems.textsecuregcm.experiment;
+
+import org.whispersystems.textsecuregcm.storage.Account;
+import org.whispersystems.textsecuregcm.storage.Device;
+import javax.annotation.Nullable;
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * A push notification selects for eligible devices, applies a control or experimental treatment, and provides a
+ * mechanism for comparing device states before and after receiving the treatment.
+ *
+ * @param <T> the type of state object stored for this experiment
+ */
+public interface PushNotificationExperiment<T> {
+
+  /**
+   * Returns the unique name of this experiment.
+   *
+   * @return the unique name of this experiment
+   */
+  String getExperimentName();
+
+  /**
+   * Tests whether a device is eligible for this experiment. An eligible device may be assigned to either the control
+   * or experiment group within an experiment. Ineligible devices will not participate in the experiment in any way.
+   *
+   * @param account the account to which the device belongs
+   * @param device the device to test for eligibility in this experiment
+   *
+   * @return a future that yields a boolean value indicating whether the target device is eligible for this experiment
+   */
+  CompletableFuture<Boolean> isDeviceEligible(Account account, Device device);
+
+  /**
+   * Generates an experiment specific state "snapshot" of the given device. Experiment results are generally evaluated
+   * by comparing a device's state before a treatment is applied and its state after the treatment is applied.
+   *
+   * @param account the account to which the device belongs
+   * @param device the device for which to generate a state "snapshot"
+   *
+   * @return an experiment-specific state "snapshot" of the given device
+   */
+  T getState(@Nullable Account account, @Nullable Device device);
+
+  /**
+   * Applies a control treatment to the given device. In many cases (and by default) no action is taken for devices in
+   * the control group.
+   *
+   * @param account the account to which the device belongs
+   * @param device the device to which to apply the control treatment for this experiment
+   *
+   * @return a future that completes when the control treatment has been applied for the given device
+   */
+  default CompletableFuture<Void> applyControlTreatment(Account account, Device device) {
+    return CompletableFuture.completedFuture(null);
+  };
+
+  /**
+   * Applies an experimental treatment to the given device. This generally involves sending or scheduling a specific
+   * type of push notification for the given device.
+   *
+   * @param account the account to which the device belongs
+   * @param device the device to which to apply the experimental treatment for this experiment
+   *
+   * @return a future that completes when the experimental treatment has been applied for the given device
+   */
+  CompletableFuture<Void> applyExperimentTreatment(Account account, Device device);
+}

service/src/main/java/org/whispersystems/textsecuregcm/experiment/PushNotificationExperimentSample.java

@@ -0,0 +1,4 @@
+package org.whispersystems.textsecuregcm.experiment;
+
+public record PushNotificationExperimentSample<T>(boolean inExperimentGroup, T initialState, T finalState) {
+}