Merge pull request #1713 from rosahbruno/1839955-architecture-doc-updates

Author: rosahbruno

.dictionary

@@ -75,3 +75,5 @@ uuid
 virtualenv
 webext
 webpack
+async
+queueing

ARCHITECTURE.md

@@ -39,12 +39,23 @@ When data is submitted, the Glean SDK is responsible for assembling the correct
 storage. Each metric can have different [lifetimes](https://mozilla.github.io/glean/book/user/metrics/adding-new-metrics.html#a-lifetime-example)
 and the SDK will manage its storage so that data does not remain in storage after it's lifetime is expired.
 
-The Glean SDK tries to do all of this is the least disruptive way possible to users. All of the
-SDKs tasks are queued and executed asynchronously. The APIs exposed by the Glean SDK will only do
+The Glean SDK tries to do all of this is the least disruptive way possible to users. There are two separate
+implementations for the SDK based on the platform: async (QT, node, web extensions) and sync (browser). The implementation
+is set inside of Glean itself and is not configurable by the user.
+
+### async (Web Extensions, QT, Node)
+
+All of the SDKs tasks are queued and executed asynchronously. The APIs exposed by the Glean SDK will only do
 the en-queuing of tasks, a quick synchronous operation. Internally, the Glean SDK will handle the
 queued tasks asynchronously, catching any errors thrown along the way so that Glean never
 crashes a users application.
 
+### sync (Browser)
+
+All of the SDKs tasks are executed synchronously, immediately as they are called. The APIs exposed by Glean
+are the same as the async implementation, but without queueing of any tasks. Errors will be caught without
+ever crashing the application.
+
 ## Code Map
 
 The Glean JavaScript SDK source code lives under the `glean/src` folder.
@@ -116,6 +127,13 @@ the `platform/` module contains implementations of identical interfaces in diffe
 This allows the pattern of only importing the necessary implementation of these modules on each platform.
 It also makes testing easier, because the exact same suite of tests can be run for each of the platform-specific implementations,
  thus guaranteeing that each module works exactly the same on all platforms.
+
+The storage module varies for each platform. The storage mechanism used by each platform is as follows:
+- `web` - [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)
+- `webext` - [`storage`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage)
+- `QT` - [`QtQuick.LocalStorage`](https://doc.qt.io/qt-6/qtquick-localstorage-qmlmodule.html)
+- `Node` - None, everything is stored in memory
+
 ### `plugins/`
 
 The `plugins/` folder contains the Glean.js' plugins code.
@@ -127,3 +145,15 @@ exposed through the `@mozilla/glean/plugins/*` entry point.
 
 This file is what gets executed when a user that has installed Glean through npm invokes the `glean`
 command. It serves as a wrapper to call `glean_parser` commands more easily from JavaScript projects.
+
+### `async`/`sync` files
+
+There are certain places where we need different implementations for internal services based on the
+platform. In these instances, the service will have its own folder with the following folder structure:
+
+```
+├── service/
+├──── async.ts
+├──── shared.ts # Shared base class defining all available methods AND any reusable helper functions
+└──── sync.ts
+```

docs/guides/adding_a_new_metric_type.md

@@ -106,6 +106,38 @@ This API's design should have been discussed and decided upon during the metric
 
 Still, metric type classes will always have at least one recording function and one testing function.
 
+The Glean file generation is very particular with which files get bundled. This means
+that the implementation for both `async` and `sync` metric recording exists in the same file. Each
+metric file will have a set of marks `/// <something> ///` to denote which type of function should
+live in that block. The common marks are: `SHARED`, `ASYNC`, `SYNC`, and `TESTING`.
+Each function that lives under `SHARED` needs to conditionally check if the current platform is
+synchronous.
+
+For example:
+
+```ts
+/// SHARED ///
+function set(value: string): void {
+  if (Context.isPlatformSync()) {
+    this.setSync(value);
+  } else {
+    this.setAsync(value);
+  }
+}
+
+/// ASYNC ///
+function setAsync(value: string): void {
+  Context.dispatcher.launch(async () => {
+    // Transform and record the metric.
+  });
+}
+
+/// SYNC ///
+function setSync(value: string): void {
+  // Transform and record the metric.
+}
+```
+
 > **Note** The `type` property on the `InternalMetricType` subclass is a constant. It will be used
 > to determine in which section of the ping the recorded metrics for this type should be placed.
 > It's value is the name of the section for this metric type on the ping payload.
@@ -116,6 +148,8 @@ Still, metric type classes will always have at least one recording function and
 
 _Functions that call Glean.js' database and store concrete values of a metric type._
 
+##### async
+
 Database calls are all asynchronous, but Glean.js' external API must **never** return promises.
 Therefore, Glean.js has an internal dispatcher. Asynchronous tasks are dispatched and the dispatcher
 will guarantee that they are executed in order without the user having to worry about
@@ -141,6 +175,25 @@ function set(value: string): void {
 }
 ```
 
+##### sync
+
+Database calls are synchronous and nothing is sent to the dispatcher. You do not need to wrap
+the call inside of any callback, you can call it directly. You do need to cast the `metricsDatabase`
+to its synchronous type when calling.
+
+```ts
+function set(value: string): void {
+  // !IMPORTANT! Always check whether or not metrics should be recorded before recording.
+  //
+  // Metrics must not be recorded in case: upload is disabled or the metric is expired.
+  if (!this.shouldRecord()) {
+    return;
+  }
+
+  (Glean.metricsDatabase as MetricsDatabaseSync).record(this, value);
+}
+```
+
 #### Testing functions
 
 _Functions that allow users to check what was recorded for the current metric type instance._