Create plugin and event infra and define afterPingCollection event

Author: brizental

glean/src/core/config.ts

@@ -3,6 +3,7 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 import { DEFAULT_TELEMETRY_ENDPOINT } from "./constants";
+import Plugin from "../plugins";
 import { validateURL } from "./utils";
 
 /**
@@ -25,6 +26,8 @@ export interface ConfigurationInterface {
   readonly serverEndpoint?: string,
   // Debug configuration.
   debug?: DebugOptions,
+  // Optional list of plugins to instrument the current Glean instance.
+  plugins?: Plugin[],
 }
 
 export class Configuration implements ConfigurationInterface {
@@ -36,7 +39,7 @@ export class Configuration implements ConfigurationInterface {
   readonly serverEndpoint: string;
   // Debug configuration.
   debug?: DebugOptions;
- 
+
   constructor(config?: ConfigurationInterface) {
     this.appBuild = config?.appBuild;
     this.appDisplayVersion = config?.appDisplayVersion;

glean/src/core/events/index.ts

@@ -0,0 +1,79 @@
+/* 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 http://mozilla.org/MPL/2.0/. */
+
+import CoreEvents from "../../../dist/webext/types/core/events";
+import Plugin from "../../plugins";
+
+import { PingPayload } from "../pings/database";
+import { JSONObject } from "../utils";
+
+export class CoreEvent<
+   // An array of arguments that the event will provide as context to the plugin action.
+   Context extends unknown[] = unknown[],
+   // The expected type of the action result. To be returned by the plugin.
+   Result extends unknown = unknown
+ > {
+   // The plugin to be triggered eveytime this even occurs.
+   private plugin?: Plugin<CoreEvent<Context, Result>>;
+
+   constructor(readonly name: string) {}
+
+   /**
+    * Registers a plugin that listens to this event.
+    *
+    * @param plugin The plugin to register.
+    */
+   registerPlugin(plugin: Plugin<CoreEvent<Context, Result>>): void {
+     if (this.plugin) {
+       console.error(
+         `Attempted to register plugin '${plugin.name}', which listens to the event '${plugin.event}'.`,
+         `That event is already watched by plugin '${this.plugin.name}'`,
+         `Plugin '${plugin.name}' will be ignored.`
+       );
+       return;
+     }
+ 
+     this.plugin = plugin;
+   }
+ 
+   /**
+    * Deregisters the currently registered plugin.
+    *
+    * If no plugin is currently registered this is a no-op.
+    */
+   deregisterPlugin(): void {
+     this.plugin = undefined;
+   }
+
+   /**
+    * Triggers this event.
+    *
+    * Will execute the action of the registered plugin, if there is any.
+    *
+    * @param args The arguments to be passed as context to the registered plugin.
+    *
+    * @returns The result from the plugin execution.
+    */
+   trigger(...args: Context): Result | void {
+     if (this.plugin) {
+       return this.plugin.action(...args);
+     }
+   }
+}
+
+/**
+ * Glean internal events.
+ */
+const CoreEvents: {
+  afterPingCollection: CoreEvent<[PingPayload], Promise<JSONObject>>,
+  [unused: string]: CoreEvent
+} = {
+  // Event that is triggered immediatelly after a ping is collect and before it is recorded.
+  //
+  //  - Context: The `PingPayload` of the recently collected ping.
+  //  - Result: The modified payload as a JSON object.
+  afterPingCollection: new CoreEvent<[PingPayload], Promise<JSONObject>>("afterPingCollection")
+};
+
+export default CoreEvents;

glean/src/core/events/utils.ts

@@ -0,0 +1,42 @@
+/* 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 http://mozilla.org/MPL/2.0/. */
+
+import CoreEvents, { CoreEvent } from "./index";
+import Plugin from "../../plugins";
+
+/**
+ * Registers a plugin to the desired Glean event.
+ *
+ * If the plugin is attempting to listen to an unknown event it will be ignored.
+ *
+ * @param plugin The plugin to register.
+ */
+export function registerPluginToEvent<E extends CoreEvent>(plugin: Plugin<E>): void {
+  const eventName = plugin.event;
+  if (eventName in CoreEvents) {
+    const event = CoreEvents[eventName];
+    event.registerPlugin(plugin);
+    return;
+  }
+
+  console.error(
+    `Attempted to register plugin '${plugin.name}', which listens to the event '${plugin.event}'.`,
+    "That is not a valid Glean event. Ignoring"
+  );
+}
+
+/**
+ * **Test-only API**
+ *
+ * Deregister plugins registered to all Glean events.
+ */
+export function testResetEvents(): void {
+  for (const event in CoreEvents) {
+    CoreEvents[event].deregisterPlugin();
+  }
+}
+
+
+
+

glean/src/core/glean.ts

@@ -15,6 +15,7 @@ import UUIDMetricType from "./metrics/types/uuid";
 import DatetimeMetricType, { DatetimeMetric } from "./metrics/types/datetime";
 import Dispatcher from "./dispatcher";
 import CorePings from "./internal_pings";
+import { registerPluginToEvent, testResetEvents } from "./events/utils";
 
 import Platform from "../platform/index";
 import TestPlatform from "../platform/test";
@@ -50,7 +51,7 @@ class Glean {
     metrics: MetricsDatabase,
     events: EventsDatabase,
     pings: PingsDatabase
-  }
+  };
 
   private constructor() {
     if (!isUndefined(Glean._instance)) {
@@ -231,6 +232,12 @@ class Glean {
     // The configuration constructor will throw in case config has any incorrect prop.
     const correctConfig = new Configuration(config);
 
+    if (config?.plugins) {
+      for (const plugin of config.plugins) {
+        registerPluginToEvent(plugin);
+      }
+    }
+
     // Initialize the dispatcher and execute init before any other enqueued task.
     //
     // Note: We decide to execute the above tasks outside of the dispatcher task,
@@ -374,9 +381,9 @@ class Glean {
     Glean.dispatcher.launch(async () => {
       if (!Glean.initialized) {
         console.error(
-          `Changing upload enabled before Glean is initialized is not supported.
-        Pass the correct state into \`Glean.initialize\`.
-        See documentation at https://mozilla.github.io/glean/book/user/general-api.html#initializing-the-glean-sdk`
+          "Changing upload enabled before Glean is initialized is not supported.\n",
+          "Pass the correct state into `Glean.initialize\n`.",
+          "See documentation at https://mozilla.github.io/glean/book/user/general-api.html#initializing-the-glean-sdk`"
         );
         return;
       }
@@ -464,6 +471,9 @@ class Glean {
     // Get back to an uninitialized state.
     Glean.instance._initialized = false;
 
+    // Deregiter all plugins
+    testResetEvents();
+
     // Clear the dispatcher queue and return the dispatcher back to an uninitialized state.
     await Glean.dispatcher.testUninitialize();
 

glean/src/core/pings/database.ts

@@ -42,10 +42,9 @@ export interface PingPayload extends JSONObject {
   metrics?: MetricsPayload,
   events?: JSONArray,
 }
-
 export interface PingInternalRepresentation extends JSONObject {
   path: string,
-  payload: PingPayload,
+  payload: JSONObject,
   headers?: Record<string, string>
 }
 
@@ -117,7 +116,7 @@ class PingsDatabase {
   async recordPing(
     path: string,
     identifier: string,
-    payload: PingPayload,
+    payload: JSONObject,
     headers?: Record<string, string>
   ): Promise<void> {
     const ping: PingInternalRepresentation = {

glean/src/core/pings/maker.ts

@@ -10,6 +10,8 @@ import TimeUnit from "../metrics/time_unit";
 import { ClientInfo, PingInfo, PingPayload } from "../pings/database";
 import PingType from "../pings";
 import Glean from "../glean";
+import CoreEvents from "../events";
+import { JSONObject } from "../utils";
 
 // The moment the current Glean.js session started.
 const GLEAN_START_TIME = new Date();
@@ -206,27 +208,35 @@ function makePath(identifier: string, ping: PingType): string {
 /**
  * Collects and stores a ping on the pings database.
  *
+ * This function will trigger the `AfterPingCollection` event.
+ * This event is triggered **after** logging the ping, which happens if `logPings` is set.
+ * We will log the payload before it suffers any change by plugins instrumenting this event.
+ *
  * @param identifier The pings UUID identifier.
  * @param ping The ping to submit.
  * @param reason An optional reason code to include in the ping.
  *
  * @returns A promise that is resolved once collection and storing is done.
  */
 export async function collectAndStorePing(identifier: string, ping: PingType, reason?: string): Promise<void> {
-  const payload = await collectPing(ping, reason);
-  if (!payload) {
+  const collectedPayload = await collectPing(ping, reason);
+  if (!collectedPayload) {
     return;
   }
 
   if (Glean.logPings) {
-    console.info(JSON.stringify(payload, null, 2));
+    console.info(JSON.stringify(collectedPayload, null, 2));
   }
 
   const headers = getPingHeaders();
+
+  const modifiedPayload = await CoreEvents.afterPingCollection.trigger(collectedPayload);
+  const finalPayload = modifiedPayload ? modifiedPayload : collectedPayload;
+
   return Glean.pingsDatabase.recordPing(
     makePath(identifier, ping),
     identifier,
-    payload,
+    finalPayload,
     headers
   );
 }

glean/src/plugins/encryption/index.ts

@@ -0,0 +1,29 @@
+/* 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 http://mozilla.org/MPL/2.0/. */
+
+import CompactEncrypt from "jose/jwe/compact/encrypt";
+import parseJwk from "jose/jwk/parse";
+import { JWK } from "jose/types";
+
+import Plugin from "../index";
+import { PingPayload } from "../../core/pings/database";
+import { JSONObject } from "../../core/utils";
+import CoreEvents from "../../core/events";
+
+class PingEncryptionPlugin extends Plugin<typeof CoreEvents["afterPingCollection"]> {
+  constructor(readonly jwk: JWK) {
+    super(CoreEvents["afterPingCollection"].name, "pingEncryptionPlugin");
+  }
+
+  async action(payload: PingPayload): Promise<JSONObject> {
+    const key = await parseJwk(this.jwk);
+    const encoder = new TextEncoder();
+    const encodedPayload = await new CompactEncrypt(encoder.encode(JSON.stringify(payload)))
+      .setProtectedHeader({ kid: this.jwk.kid })
+      .encrypt(key);
+    return { payload: encodedPayload };
+  }
+}
+
+export default PingEncryptionPlugin;

glean/src/plugins/index.ts

@@ -0,0 +1,39 @@
+/* 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 http://mozilla.org/MPL/2.0/. */
+
+import { CoreEvent } from "../core/events";
+
+// Helper type that extracts the type of the Context from a generic CoreEvent.
+export type EventContext<Context> = Context extends CoreEvent<infer InnerContext, unknown>
+ ? InnerContext
+ : undefined[];
+
+// Helper type that extracts the type of the Result from a generic CoreEvent.
+export type EventResult<Result> = Result extends CoreEvent<unknown[], infer InnerResult>
+ ? InnerResult
+ : void;
+
+/**
+ * Plugins can listen to events that happen during Glean's lifecycle.
+ *
+ * Every Glean plugin must extend this class.
+ */
+abstract class Plugin<E extends CoreEvent = CoreEvent> {
+  /**
+   * Instantiates the Glean plugin.
+   *
+   * @param event The name of the even this plugin instruments.
+   * @param name The name of this plugin.
+   */
+  constructor(readonly event: string, readonly name: string) {}
+
+ /**
+  * An action that will be triggered everytime the instrumented event occurs.
+  *
+  * @param args The arguments that are expected to be passed by this event.
+  */
+ abstract action(...args: EventContext<E>): EventResult<E>;
+}
+
+export default Plugin;

glean/tests/core/glean.spec.ts

@@ -6,13 +6,26 @@ import assert from "assert";
 import sinon from "sinon";
 
 import { CLIENT_INFO_STORAGE, DELETION_REQUEST_PING_NAME, KNOWN_CLIENT_ID } from "../../src/core/constants";
+import CoreEvents from "../../src/core/events";
 import Glean from "../../src/core/glean";
 import { Lifetime } from "../../src/core/metrics";
 import StringMetricType from "../../src/core/metrics/types/string";
 import PingType from "../../src/core/pings";
+import { JSONObject } from "../../src/core/utils";
 import TestPlatform from "../../src/platform/qt";
+import Plugin from "../../src/plugins";
 
 const GLOBAL_APPLICATION_ID = "org.mozilla.glean.test.app";
+class MockPlugin extends Plugin<typeof CoreEvents["afterPingCollection"]> {
+  constructor() {
+    super(CoreEvents["afterPingCollection"].name, "mockPlugin");
+  }
+
+  action(): Promise<JSONObject> {
+    return Promise.resolve({});
+  }
+}
+
 const sandbox = sinon.createSandbox();
 
 describe("Glean", function() {
@@ -164,6 +177,26 @@ describe("Glean", function() {
     }
   });
 
+  it("initialization registers plugins when provided", async function() {
+    await Glean.testUninitialize();
+
+    const mockPlugin = new MockPlugin();
+    await Glean.testInitialize(GLOBAL_APPLICATION_ID, true, {
+      // We need to ignore TypeScript here,
+      // otherwise it will error since mockEvent is not listed as a Glean event in core/events.ts
+      //
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      plugins: [ mockPlugin ]
+    });
+
+    assert.deepStrictEqual(CoreEvents["afterPingCollection"]["plugin"], mockPlugin);
+
+    await Glean.testUninitialize();
+    await Glean.testInitialize(GLOBAL_APPLICATION_ID, true);
+    assert.strictEqual(CoreEvents["afterPingCollection"]["plugin"], undefined);
+  });
+
   it("disabling upload should disable metrics recording", async function() {
     const pings = ["aPing", "twoPing", "threePing"];
     const metric = new StringMetricType({