Introduce the ping testing API

This commit adds testBeforeNextSubmit to execute a
validation function synchronously before the target ping
is collected.

Author: Dexterp37

glean/src/core/pings/index.ts

@@ -8,6 +8,8 @@ import collectAndStorePing from "../pings/maker.js";
 import type CommonPingData from "./common_ping_data.js";
 import { Context } from "../context.js";
 
+type ValidatorFunction = (reason?: string) => Promise<void>;
+
 /**
  * Stores information about a ping.
  *
@@ -20,11 +22,22 @@ class PingType implements CommonPingData {
   readonly sendIfEmpty: boolean;
   readonly reasonCodes: string[];
 
+  // The functions and promises required for the test API to
+  // execute and synchronize with the submission API.
+  private testResolutionFunction?: (value: void | PromiseLike<void>) => void;
+  private testValidator?: ValidatorFunction;
+  private testValidatorPromise: Promise<void>;
+
   constructor (meta: CommonPingData) {
     this.name = meta.name;
     this.includeClientId = meta.includeClientId;
     this.sendIfEmpty = meta.sendIfEmpty;
     this.reasonCodes = meta.reasonCodes ?? [];
+
+    // This promise should always be resolved to account for the
+    // fact that no testing API might be called. In production the
+    // `submit` function will await on this (no-op).
+    this.testValidatorPromise = Promise.resolve();
   }
 
   private isDeletionRequest(): boolean {
@@ -44,6 +57,31 @@ class PingType implements CommonPingData {
    *               `ping_info.reason` part of the payload.
    */
   submit(reason?: string): void {
+    // **** Read this before changing the following code! ****
+    //
+    // The Dispatcher does not allow dispatched tasks to await on
+    // other dispatched tasks. Unfortunately, this causes a deadlock.
+    // In order to work around that problem, we kick off validation
+    // right before the actual submission takes place, through another
+    // async function (and not through the dispatcher). We then await
+    // in the dispatched submission task on the related promise, which
+    // will always resolve due to the use of `finally`.
+    if (this.testValidator) {
+      this.testValidatorPromise = this.testValidator(reason)
+        .then(() => {
+          if (this.testResolutionFunction) {
+            this.testResolutionFunction();
+          }
+        })
+        .catch(
+          e => console.error(`There was an error validating ${this.name} (${reason ?? "no reason"}). Ignoring.`, e)
+        )
+        .finally(() => {
+          this.testResolutionFunction = undefined;
+          this.testValidator = undefined;
+        });
+    }
+
     Context.dispatcher.launch(async () => {
       if (!Context.initialized) {
         console.info("Glean must be initialized before submitting pings.");
@@ -60,12 +98,34 @@ class PingType implements CommonPingData {
         console.error(`Invalid reason code ${reason} from ${this.name}. Ignoring.`);
         correctedReason = undefined;
       }
-  
+
+      await this.testValidatorPromise;
+
       const identifier = generateUUIDv4();
       await collectAndStorePing(identifier, this, correctedReason);
       return;
     });
   }
+
+  /**
+   * **Test-only API**
+   *
+   * Runs a validation function before the ping is collected.
+   *
+   * TODO: Only allow this function to be called on test mode (depends on Bug 1682771).
+   *
+   * @param validatorFn The asynchronous validation function to run in order to validate
+   *                    the ping content.
+   *
+   * @returns A `Promise` resolved when the ping is collected and the validation function
+   *          is executed.
+   */
+  async testBeforeNextSubmit(validatorFn: ValidatorFunction): Promise<void> {
+    return new Promise((resolve) => {
+      this.testResolutionFunction = resolve;
+      this.testValidator = validatorFn;
+    });
+  }
 }
 
 export default PingType;