GPII · klown · Jan 21, 2020 · Jan 21, 2020 · Jan 22, 2020 · Jan 22, 2020
diff --git a/documentation/Configs.md b/documentation/Configs.md
@@ -84,3 +84,18 @@ for the reset API and how to use it.
 **Purpose**: This config fetches default settings from a remote URL. The default URL is set to
 `https://raw.githubusercontent.com/GPII/universal/master/testData/defaultSettings/defaultSettings.win32.json5`
 in this config. See [Reset Computer](ResetComputer.md) for what are default settings.
+
+### Load Solutions from the Repository in Production Contexts
+
+**Config file**: [`%flowManager/configs/gpii.config.local.flowManager.loadSolutionsFromRepository.json5`](../gpii/node_modules/flowManager/configs/gpii.config.local.flowManager.loadSolutionsFromRepository.json5)
+
+**Purpose**: This add-on config is for use in production where the cloud based
+flow manager supports a valid `/revision` end point, and where the local
+flow manager loads solutions registries from both its local hard drive and from
+the source code repository.  See [SolutionsRegistryDataSource](SolutionsRegistryDataSource.md#local-flow-manager-solutions-registry-data-source)
+for more details.
+
+In addition, for development testing, the default is to assume there is no valid
+revision, and no request for the revision is made (see [GpiiRevisionRequester.js](../gpii/node_modules/flowManager/src/GpiiRevisionRequester.js)).
+This is done by setting the requester's `cloudURL` option to `null`.  This
+effectively stops the process of loading solutions from the repository.
diff --git a/documentation/FlowManager.md b/documentation/FlowManager.md
@@ -115,11 +115,19 @@ payload structure to start a matchMaking process.
  cloud based components of the GPII.
 * **route:** `/revision`
 * **method:** `GET`
-* **return:** A JSON document containing the revision:
+* **return:** On success, an http status code of 200 and a payload containing the revision, e.g.:
 
-```json
+```json5
+{"sha256": "2602bdf868aec49993d8780feec42d4e9f995e21"}
+```
+
+Otherwise, returns status code 404 and an error payload:
+
+```json5
 {
-    "sha256": "2602bdf868aec49993d8780feec42d4e9f995e21"
+    "isError": true,
+    "message": "Error retrieving full git revision: %reason",
+    "statusCode": 404
 }
 ```
 

diff --git a/documentation/SolutionsRegistryDataSource.md b/documentation/SolutionsRegistryDataSource.md
@@ -0,0 +1,134 @@
+# Solutions Registry Data Source
+
+The solutions registry data source provides a RESTful means of fetching
+solutions registries via the [FlowManager](FlowManager.md) in order to determine
+which solutions are available and appropriate for a user's preferences.  A
+solution is an application, such as the NVDA screen reader, or an operating
+system feature set using a control panel, such as the Windows high contrast
+theme.  Each solution entry in the registry declares a set of preferences that
+it supports and describes how to configure the solution, launch it, reset it,
+and stop it.
+
+The solutions are listed in `JSON` files called "solutions registries".  The
+structure of a solutions registry is documented in
+[SolutionsRegistryFormat](SolutionsRegistryFormat.md).  Since solutions are
+frequently specific to an operating system, or "platform", there are separate
+solution registries for each platform.  Examples of platforms are Windows,
+GNOME-Linux, MacOS, and Android.
+
+The SolutionsRegistryDataSource is a component that loads and caches
+solutions registries when the GPII starts up, and then serves solutions to the
+rest of the system upon request.  The flow manager coordinates retrieval of
+solutions, user preferences, device information, and so on, passing these to the
+[MatchMaker Framework](MatchMakerFramework.md) and [LifecycleManager](LifecycleManager.md).
+
+There are two initialization workflows with respect to solutions registries
+depending on whether the flow manager is running in the cloud or locally on the
+client device.  The Cloud Based Flow Manager uses a Solutions Registry Data
+Source implemented to run in that context, whereas the Local Flow Manager uses a
+Solutions Registry Data Source appropriate for running on client machines.
+These two scenarios are described in the following two sections.
+
+## Cloud Based Flow Manager Solutions Registry Data Source
+
+With respect to the Cloud Based Flow Manager, the solutions registries are
+included in the distribution of `gpii-universal` along with the other components
+of the GPII -- the flow manager, lifecycle manager and so on.  The Cloud Based
+FlowManager is a central service for GPII clients, and these clients run on a
+variety of platforms.  As such, the platform that the Cloud Based FlowManager is
+executing on is irrelevant in terms of providing solutions for the client.  When
+a request for a solutionsvregistry is made, the flow manager needs to have
+access to all platform solutions in order to respond with the solutions relevant
+to a particular client.
+
+Here, the SolutionsRegistryDataSource component loads the solutions
+registries from the local file system at system startup.  In this context,
+"local" refers to the file system associated with machine that the Cloud Based
+Flow Manager is running on.  The SolutionsRegistryDataSource is a
+subcomponent of the flow manager, and the sequence of operations and
+events that occur during its instantiation are:
+
+<ol>
+<li><code>loadSolutions.loadFromLocalDisk</code>,
+  <ul>
+  <li>The solutions registry files are loaded from the local file system,</li>
+  </ul>
+</li>
+<li><code>loadSolutions.solutionsLoaded</code>
+  <ul>
+  <li>Fires a <code>solutionsRegistryReady</code> event.</li>
+  </ul>
+</li>
+</ol>
+
+The `solutionsRegistryReady` informs the flow manager that its
+SolutionsRegistryDataSource is ready to provide solutions upon request.
+
+## Local Flow Manager Solutions Registry Data Source
+
+As in the case of the Cloud Based FlowManager, the solutions registries are
+included in the distribution of GPII for the client.  However, they are not
+updated as frequently as those in the cloud.  In particular, the solutions
+registry may be stale for the platform that the client is running on.  However,
+the registry associated with the latest version of the cloud based GPII is
+available in `gpii-universal`'s source code repository (github), and can be
+downloaded from there.  In this regard, the Cloud Based FlowManager provides a
+`/revision` end-point that responds with the full `SHA256` of the revision of
+the source associated with the latest solutions registries.
+
+The SolutionsRegistryDataSource associated with the Local FlowManager uses the
+following sequence of events and operations at startup:
+
+<ol>
+<li><code>loadSolutions.loadFromLocalDisk</code>,
+  <ul>
+  <li>The solutions registry files are loaded from the local file system,</li>
+  </ul>
+</li>
+<li><code>loadSolutions.getRevision</code>,
+  <ul>
+  <li>Make an http request of the Cloud Based FlowManager for the revision of
+      the source code of the GPII used by the cloud,
+  </li>
+  </ul>
+</li>
+<li><code>loadSolutions.loadFromRepository</code>,
+  <ul>
+  <li>Make an http request of the source code respository, passing:
+    <ul>
+    <li>the platform ID associated with the OS that the client is running on,
+        e.g. "darwin",
+    </li>
+    <li>the revision fetched at the previous step,</li>
+    </ul>
+  </li>
+  <li>The solutions registry corresponding to the platform and revision provided
+      is downloaded from the source code repository and overlays the one fetched
+      from the local file system at the first step.
+  </li>
+  </ul>
+</li>
+<li><code>loadSolutions.solutionsLoaded</code>
+  <ul>
+  <li>Fires a <code>solutionsRegistryReady</code> event</li>
+  </ul>
+</li>
+</ol>
+
+The above sequence is embeded within the Local FlowManager's `flowManagerReady`
+startup interlock such that all initialization is completed before the GPII
+client responds to user interactions.
+
+Note that both the `getRevision` and/or the `loadFromRepository` steps could
+fail.  In that case, the latest solutions registry for the client platform will
+not be downloaded and cached within the client.  When solutions for the client
+platform are requested, the SolutionsRegistryDataSource uses a fallback where
+the solutions loaded from the local file system during the first
+`loadFromLocalDisk` step are provided.
+
+Further note that the `getRevision` step feeds its result into the
+`loadFromRepository` step.  The revision is necessary to fetch the
+correct solutions registry from the repository. If a developer wants to avoid
+that, they can set the `cloudURL` of the `GpiiRevisionRequester` to `null`,
+effectively stopping the entire sequence.  No solutions registry will be
+downloaded from the repository in that case.
diff --git a/...dules/flowManager/configs/gpii.config.local.flowManager.loadSolutionsFromRepository.json5 b/...dules/flowManager/configs/gpii.config.local.flowManager.loadSolutionsFromRepository.json5
diff --git a/gpii/node_modules/flowManager/configs/gpii.flowManager.config.base.json5 b/gpii/node_modules/flowManager/configs/gpii.flowManager.config.base.json5
diff --git a/gpii/node_modules/flowManager/configs/gpii.flowManager.config.local.base.json5 b/gpii/node_modules/flowManager/configs/gpii.flowManager.config.local.base.json5
diff --git a/gpii/node_modules/flowManager/src/FlowManager.js b/gpii/node_modules/flowManager/src/FlowManager.js
@@ -42,9 +42,8 @@ require("gpii-user-errors");
 fluid.defaults("gpii.flowManager", {
     gradeNames: ["kettle.app"],
     components: {
-        // TODO: Make this use the solutions registry data source by default?
         solutionsRegistryDataSource: {
-            type: "kettle.dataSource",
+            type: "gpii.flowManager.solutionsRegistry.dataSource.cloudBased",
             options: {
                 termMap: {
                     "os": "%os",
@@ -154,9 +153,23 @@ fluid.defaults("gpii.flowManager.local", {
         "lifecycleManager.pspChannel.sessionBinder": {
             record: "gpii.pspChannel.sessionBinder",
             target: "{that lifecycleManager gpii.lifecycleManager.userSession}.options.gradeNames"
+        },
+        "solutionsRegistryDataSource.platformReporter": {
+            record: {
+                platformReporter: "{gpii.flowManager.local}.deviceReporter.platformReporter"
+            },
+            target: "{that solutionsRegistryDataSource}.options.components"
         }
     },
     components: {
+        solutionsRegistryDataSource: {
+            type: "gpii.flowManager.solutionsRegistry.dataSource.local",
+            options: {
+                events: {
+                    solutionsRegistryReady: "{gpii.flowManager.local}.events.solutionsRegistryReady"
+                }
+            }
+        },
         lifecycleManager: {
             type: "gpii.lifecycleManager",
             options: {
@@ -222,10 +235,12 @@ fluid.defaults("gpii.flowManager.local", {
         preferencesSavedSuccess: null,
         preferencesSavedError: null,
         noUserLoggedIn: null,
+        solutionsRegistryReady: null,
         getDefaultSettingsData: null,
         defaultSettingsDataLoaded: null,
         flowManagerReady: {
             events: {
+                "solutionsRegistryReady": "solutionsRegistryReady",
                 "defaultSettingsDataLoaded": "defaultSettingsDataLoaded",
                 "kettleReady": "{kettle.server}.events.onListen"
             }
@@ -242,7 +257,6 @@ fluid.defaults("gpii.flowManager.local", {
             funcName: "gpii.flowManager.local.mountWebSocketsSettingsHandler",
             args: ["{webSocketsSettingsHandlerComponent}"]
         },
-
         // Fire "getDefaultSettingsData" event to trigger promise transform chain that does:
         // 1. Read default settings from the reset to default file;
         // 2. Calculate defaultLifecycleInstructions and defaultSnapshot based on the default settings;

diff --git a/gpii/node_modules/flowManager/src/GpiiRevisionRequester.js b/gpii/node_modules/flowManager/src/GpiiRevisionRequester.js
@@ -0,0 +1,79 @@
+/*!
+GPII Full SHA Revision DataSource
+
+Copyright 2020 OCAD University
+
+Licensed under the New BSD license. You may not use this file except in
+compliance with this License.
+
+You may obtain a copy of the License at
+https://github.com/GPII/universal/blob/master/LICENSE.txt
+*/
+
+"use strict";
+
+var fluid = require("infusion"),
+    gpii = fluid.registerNamespace("gpii");
+
+require("kettle");
+
+fluid.registerNamespace("gpii.flowmanager.revisionRequester");
+
+fluid.defaults("gpii.flowmanager.revisionRequester", {
+    gradeNames: ["fluid.component"],
+
+    // Prepend CBFM host/port distributed down from, e.g., gpii.flowManager.config.untrusted
+    // For development tests where there is no valid /revision endpoint in the
+    // cloud, this is left as null.
+    cloudURL: null,
+    urlTemplate: "%cloudURL/revision",
+
+    // Compute url from CBFM base URL and template
+    revisionGetUrl: {
+        expander: {
+            funcName: "fluid.stringTemplate",
+            args: ["{that}.options.urlTemplate", {
+                cloudURL: "{that}.options.cloudURL"
+            }]
+        }
+    },
+    components: {
+        gpiiRevisionDataSource: {
+            type: "kettle.dataSource.URL",
+            options: {
+                url: "{revisionRequester}.options.revisionGetUrl"
+            }
+        }
+    },
+    invokers: {
+        getRevision: {
+            funcName: "gpii.flowmanager.revisionRequester.getRevision",
+            args: ["{that}"]
+        }
+    }
+});
+
+/**
+ * Retrieve the respository revision's full SHA256 from the cloud.
+ * @param {Component} that - An instance of gpii.flowManager.revisionRequester.
+ * @return {Promise} A promise whose resolved value is eiher the revision or, if
+ * there is an error, an object with an "isError: true" property.  The revision
+ * has the form { "sha256": "86a83d2f93a6f8f954a4fef618ca6aea1399c980" }.
+ */
+gpii.flowmanager.revisionRequester.getRevision = function (that) {
+    var togo = fluid.promise();
+    if (that.options.cloudURL !== null) {
+        var revisionPromise = that.gpiiRevisionDataSource.get();
+        revisionPromise.then(function (/*revision*/) {
+            fluid.promise.follow(revisionPromise, togo);
+        }, function (err) {
+            togo.resolve(err);
+        });
+    } else {
+        // If the url to the CBFM is null, assume this is running in a
+        // development testing enviroment or, generally, a scenario where
+        // requests for the revision are to be suppressed.
+        togo.resolve(null);
+    }
+    return togo;
+};
diff --git a/gpii/node_modules/flowManager/src/MatchMaking.js b/gpii/node_modules/flowManager/src/MatchMaking.js
@@ -96,25 +96,22 @@
     gpii.flowManager.getSolutions = function (solutionsRegistryDataSource, deviceContext, onSuccessEvent, onErrorEvent) {
         var promiseTogo = fluid.promise();
 
-        var os = fluid.get(deviceContext, "OS.id");
-        var promise = solutionsRegistryDataSource.get({});
-        promise.then(function (solutions) {
-            var solutionsRegistryEntries = gpii.matchMakerFramework.filterSolutions(solutions[os], deviceContext);
+        var promise = solutionsRegistryDataSource.get({os: fluid.get(deviceContext, "OS.id")});
+        promise.then(function (entries) {
+            var solutionsRegistryEntries = gpii.matchMakerFramework.filterSolutions(entries, deviceContext);
             fluid.log("Fetched filtered solutions registry entries: ", gpii.renderMegapayload({solutionsRegistryEntries: solutionsRegistryEntries}));
             promiseTogo.resolve({
-                solutionsRegistryEntries: solutionsRegistryEntries,
-                solutions: solutions
+                solutionsRegistryEntries: solutionsRegistryEntries
             });
             if (onSuccessEvent) {
-                onSuccessEvent.fire(solutionsRegistryEntries, solutions);
+                onSuccessEvent.fire(solutionsRegistryEntries);
             }
         }, function (error) {
             promiseTogo.reject(error);
             if (onErrorEvent) {
                 onErrorEvent.fire(error);
             }
         });
-
         return promiseTogo;
     };
 
@@ -187,8 +184,7 @@
                     gpiiKey: "{that}.gpiiKey",
                     preferences: "{arguments}.preferences.0",
                     deviceContext: "{arguments}.deviceContext.0",
-                    solutionsRegistryEntries: "{arguments}.solutions.0",
-                    fullSolutionsRegistry: "{arguments}.solutions.1"
+                    solutionsRegistryEntries: "{arguments}.solutions.0"
                 }]
             }
         },