Bug 1687644 - Implement the external API for consumers (#27)

Author: Beatriz Rizental

bin/qt-js-check.sh

@@ -19,7 +19,7 @@ xvfb-run python main.py &> qml.log &
 sleep 10
 
 if grep -q "Some Javascript error occured" "qml.log"; then
-  echo "Javascript errors in found in QML! See more logs below."
+  echo "Failed to initialize Glean in QML! See more logs below."
   cat qml.log
   exit 1
 fi

package.json

@@ -9,9 +9,9 @@
     "lint": "eslint . --ext .ts,.js,.json --max-warnings=0",
     "fix": "eslint . --ext .ts,.js,.json --fix",
     "build:webext": "webpack --config webpack.config.webext.js --mode production",
-    "dev:webext": "webpack --watch --config webpack.config.webext.js --mode development",
+    "dev:webext": "webpack --watch --config webpack.config.webext.js --mode development --devtool inline-source-map",
     "build:qt": "webpack --config webpack.config.qt.js --mode production",
-    "dev:qt": "webpack --watch --config webpack.config.qt.js --mode development",
+    "dev:qt": "webpack --watch --config webpack.config.qt.js --mode development  --devtool inline-source-map",
     "build:test-webext": "cd tests/utils/webext/sample/ && npm install && npm run build:xpi"
   },
   "repository": {

samples/qt-qml-app/main.qml

@@ -47,11 +47,11 @@ Rectangle {
   }
 
   Component.onCompleted: {
-      // Initialize Glean when the application starts.
-      try {
-        Glean.Glean.initialize("qt-qml-app", true);
-      } catch(err) {
-        console.error(`Some Javascript error occured.\n${err}`);
-      }
+    // Initialize Glean when the application starts.
+    Glean.Glean.initialize("qt-qml-app", true)
+      // Note: If you change this console messages you should change
+      // the console message verifications on `bin/qt-js-check.sh.
+      .then(() => console.log("Called Glean.initialize succesfully."))
+      .catch(err => console.error(`Some Javascript error occured.\n${err}`));
   }
 }

src/config.ts

@@ -11,7 +11,7 @@ interface Configuration {
   // The user visible version string fro the application running Glean.js.
   readonly appDisplayVersion?: string,
   // The server pings are sent to.
-  readonly serverEndpoint?: URL
+  readonly serverEndpoint?: string
 }
 
 export default Configuration;

src/glean.ts

@@ -7,7 +7,7 @@ import Configuration from "config";
 import MetricsDatabase from "metrics/database";
 import PingsDatabase from "pings/database";
 import PingUploader from "upload";
-import { isUndefined, sanitizeApplicationId } from "utils";
+import { isUndefined, sanitizeApplicationId, validateURL } from "utils";
 import { CoreMetrics } from "internal_metrics";
 import { Lifetime } from "metrics";
 import { DatetimeMetric } from "metrics/types/datetime";
@@ -33,7 +33,7 @@ class Glean {
   // The application ID (will be sanitized during initialization).
   private _applicationId?: string;
   // The server pings are sent to.
-  private _serverEndpoint?: URL;
+  private _serverEndpoint?: string;
   // Whether or not to record metrics.
   private _uploadEnabled?: boolean;
 
@@ -181,8 +181,11 @@ class Glean {
     }
     Glean.instance._applicationId = sanitizeApplicationId(applicationId);
 
-    Glean.instance._serverEndpoint = config
-      ? config.serverEndpoint : new URL(DEFAULT_TELEMETRY_ENDPOINT);
+    if (config && config.serverEndpoint && !validateURL(config.serverEndpoint)) {
+      throw new Error(`Unable to initialize Glean, serverEndpoint ${config.serverEndpoint} is an invalid URL.`);
+    }
+    Glean.instance._serverEndpoint = (config && config.serverEndpoint)
+      ? config.serverEndpoint : DEFAULT_TELEMETRY_ENDPOINT;
 
     if (uploadEnabled) {
       await Glean.onUploadEnabled();
@@ -232,7 +235,7 @@ class Glean {
     return Glean.instance._applicationId;
   }
 
-  static get serverEndpoint(): URL | undefined {
+  static get serverEndpoint(): string | undefined {
     if (!Glean.instance._initialized) {
       console.warn("Attempted to access the Glean.serverEndpoint before Glean was initialized.");
     }

src/index.ts

@@ -2,25 +2,81 @@
  * 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 Glean from "glean";
+import Configuration from "config";
+
+// Private Glean types to export.
+import PingType from "pings";
+import BooleanMetricType from "metrics/types/boolean";
+import CounterMetricType from "metrics/types/counter";
+import DatetimeMetricType from "metrics/types/datetime";
+import StringMetricType from "metrics/types/string";
+import UUIDMetricType from "metrics/types/uuid";
+
 export = {
   /**
-   * Initializes Glean.
+   * Initialize Glean. This method should only be called once, subsequent calls will be no-op.
+   *
+   * # Note
+   *
+   * Before this method is called Glean will not be able to upload pings or record metrics,
+   * all such operations will be no-op.
    *
-   * Before calling this function Glean.js won't submit any pings.
+   * This is _not_ the way glean-core deals with this. It will record tasks performed before init
+   * and flush them on init. We have a bug to figure out how to do that for Glean.js, Bug 1687491.
    *
-   * @param appId  Analogous to a Glean SDK application id.
-   * @param uploadEnabled Whether upload is enabled or not.
+   * @param applicationId The application ID (will be sanitized during initialization).
+   * @param uploadEnabled Determines whether telemetry is enabled.
+   *                      If disabled, all persisted metrics, events and queued pings (except
+   *                      first_run_date) are cleared.
+   * @param config Glean configuration options.
+   *
+   * @returns A promise that is resolved once initialize is completed.
    */
-  initialize(appId: string, uploadEnabled: boolean): void {
-    console.info(`Called Glean.initialize("${appId}", ${uploadEnabled})).`);
+  async initialize(
+    applicationId: string,
+    uploadEnabled: boolean,
+    config?: Configuration
+  ): Promise<void> {
+    await Glean.initialize(applicationId, uploadEnabled, config);
   },
 
   /**
-   * Enables / Disables upload.
+   * Sets whether upload is enabled or not.
+   *
+   * When uploading is disabled, metrics aren't recorded at all and no data is uploaded.
+   *
+   * When disabling, all pending metrics, events and queued pings are cleared.
    *
-   * @param flag Whether to disable or enable upload.
+   * When enabling, the core Glean metrics are recreated.
+   *
+   * If the value of this flag is not actually changed, this is a no-op.
+   *
+   * If Glean has not been initialized yet, this is also a no-op.
+   *
+   * @param flag When true, enable metric collection.
+   *
+   * @returns A promise that is resolved once setUploadEnabled is completed.
    */
-  setUploadEnabled(flag: boolean): void {
-    console.info(`Called Glean.setUploadEnabled(${flag})).`);
+  async setUploadEnabled(flag: boolean): Promise<void> {
+    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`
+      );
+      return;
+    }
+
+    await Glean.setUploadEnabled(flag);
+  },
+
+  _private: {
+    PingType,
+    BooleanMetricType,
+    CounterMetricType,
+    DatetimeMetricType,
+    StringMetricType,
+    UUIDMetricType
   }
 }

src/metrics/index.ts

@@ -147,6 +147,6 @@ export abstract class MetricType implements CommonMetricData {
    * @returns Whether or not this metric instance should be recorded.
    */
   shouldRecord(): boolean {
-    return (Glean.uploadEnabled && !this.disabled);
+    return (Glean.isUploadEnabled() && !this.disabled);
   }
 }

src/metrics/types/uuid.ts

@@ -9,6 +9,32 @@ import { Metric, MetricType, CommonMetricData } from "metrics";
 import { isString } from "utils";
 import Glean from "glean";
 
+/**
+ * Generates a UUIDv4.
+ *
+ * Will provide a fallback in case `crypto` is not available,
+ * which makes the "uuid" package generator not work.
+ *
+ * # Important
+ *
+ * This workaround is here for usage in Qt/QML environments, where `crypto` is not available.
+ * Bug 1688015 was opened to figure out a less hacky way to do this.
+ *
+ * @returns A randomly generated UUIDv4.
+ */
+function generateUUIDv4(): string {
+  if (typeof crypto !== "undefined") {
+    return UUIDv4();
+  } else {
+    // Copied from https://stackoverflow.com/a/2117523/261698
+    // and https://stackoverflow.com/questions/105034/how-to-create-guid-uuid
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, function(c) {
+      const r = Math.random() * 16 | 0, v = c == "x" ? r : (r & 0x3 | 0x8);
+      return v.toString(16);
+    });
+  }
+}
+
 export class UUIDMetric extends Metric<string, string> {
   constructor(v: unknown) {
     super(v);
@@ -54,7 +80,7 @@ class UUIDMetricType extends MetricType {
     }
 
     if (!value) {
-      value = UUIDv4();
+      value = generateUUIDv4();
     }
 
     let metric: UUIDMetric;
@@ -79,7 +105,7 @@ class UUIDMetricType extends MetricType {
       return;
     }
 
-    const value = UUIDv4();
+    const value = generateUUIDv4();
     await this.set(value);
 
     return value;

src/pings/index.ts

@@ -50,7 +50,7 @@ class PingType {
       return false;
     }
 
-    if (!Glean.uploadEnabled) {
+    if (!Glean.isUploadEnabled()) {
       console.info("Glean disabled: not submitting any pings.");
       return false;
     }

src/pings/maker.ts

@@ -7,7 +7,7 @@ import CounterMetricType, { CounterMetric } from "metrics/types/counter";
 import DatetimeMetricType, { DatetimeMetric } from "metrics/types/datetime";
 import { Lifetime } from "metrics";
 import TimeUnit from "metrics/time_unit";
-import { ClientInfo, PingInfo, PingHeaders, PingPayload } from "pings/database";
+import { ClientInfo, PingInfo, PingPayload } from "pings/database";
 import PingType from "pings";
 import Glean from "glean";
 
@@ -151,7 +151,7 @@ export async function buildClientInfoSection(ping: PingType): Promise<ClientInfo
  * @returns An object with the headers to include
  *          or `undefined` if there are no headers to include.
  */
-export async function getPingHeaders(): Promise<PingHeaders | undefined> {
+export async function getPingHeaders(): Promise<Record<string, string> | undefined> {
   // TODO: Returning nothing for now until Bug 1685718 is resolved.
   return;
 }