GPII-228 Capture Settings Backend (Snapshotter 2018)

gpii/node_modules/flowManager/src/Capture.js

@@ -0,0 +1,200 @@
+/**
+ * GPII Capture Component
+ *
+ * Copyright 2020 Raising the Floor - International
+ *
+ * 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/LICENSE.txt
+ */
+"use strict";
+
+var fluid = require("infusion"),
+    gpii = fluid.registerNamespace("gpii");
+
+fluid.defaults("gpii.flowManager.capture", {
+    gradeNames: ["fluid.component"],
+    events: {
+        // Pseudoevents for transforming promise chains to fetch the solutions on the current device
+        // and capture the settings for the device.
+        onSolutionsForCurrentDevice: null,
+        onCaptureSettingsForCurrentDevice: null
+    },
+    listeners: {
+        // Begin declaration of Promise Chain for onSolutionsForCurrentDevice
+        "onSolutionsForCurrentDevice.getDeviceContextPromise": {
+            funcName: "gpii.lifecycleManager.getDeviceContextPromise",
+            args: ["{flowManager}.deviceReporter"],
+            priority: "first"
+        },
+        "onSolutionsForCurrentDevice.getSolutions": {
+            funcName: "gpii.flowManager.getSolutions",
+            args: [ "{flowManager}.solutionsRegistryDataSource", "{arguments}.0"],
+            priority: "after:getDeviceContextPromise"
+        },
+        "onSolutionsForCurrentDevice.solutionsRegistryEntriesToPromise": {
+            funcName: "fluid.toPromise",
+            args: ["{arguments}.0.solutionsRegistryEntries"],
+            priority: "after:getSolutions"
+        },
+        // Begin declaration of Promise Chain for onCaptureSettingsForCurrentDevice
+        "onCaptureSettingsForCurrentDevice.getInstalledSolutionsForCurrentDevice": {
+            func: "{that}.getInstalledSolutionsForCurrentDevice",
+            priority: "first"
+        },
+        "onCaptureSettingsForCurrentDevice.captureSystemSettings": {
+            funcName: "gpii.flowManager.capture.captureSystemSettings",
+            args: ["{lifecycleManager}.read", "{arguments}.0", "{arguments}.1"], // solutionsRegistryEntries, options
+            priority: "after:getInstalledSolutionsForCurrentDevice"
+        },
+        "onCaptureSettingsForCurrentDevice.formatRawCapturedSettings": {
+            func: "gpii.flowManager.capture.formatRawCapturedSettings",
+            args: ["{arguments}.0"],
+            priority: "after:captureSystemSettings"
+        }
+    },
+    invokers: {
+        getInstalledSolutionsForCurrentDevice: {
+            funcName: "fluid.promise.fireTransformEvent",
+            args: ["{that}.events.onSolutionsForCurrentDevice"]
+        },
+        getSystemSettingsCapture: {
+            funcName: "fluid.promise.fireTransformEvent",
+            args: ["{that}.events.onCaptureSettingsForCurrentDevice", null, "{arguments}.0"] // options
+        }
+    }
+});
+
+/**
+ * Invoker `{gpii.flowManager.capture}.getInstalledSolutionsForCurrentDevice`
+ *
+ * @method
+ * @name {gpii.flowManager.capture}.getInstalledSolutionsForCurrentDevice
+ *
+ * This invoker method will return the solution registry entries, in their usual json format,
+ * that are available on the current device.
+ *
+ * @return {Promise} A promise resolved with an object of solutions registry entries available on the
+ * current device. As with the solutions registry itself, these are keyed by the solution ID.
+ */
+
+/**
+ * Invoker `{gpii.flowManager.capture}.getSystemSettingsCapture`
+ *
+ * @method
+ * @name {gpii.flowManager.capture}.getSystemSettingsCapture
+ *
+ * This main API entry point for capturing settings from a system or computer. This captures
+ * the actual settings on the device, so it assumed to be running in a local untrusted flow
+ * manager.
+ *
+ * @param {Object} options - Options for this chain.
+ * @param {Array} options.solutionsList - An array of solution IDs to filter by when
+ * retreiving settings. If this option is not included, all available settings will be
+ * returned. ex: `["com.microsoft.windows.mouseSettings", "com.freedomscientific.jaws"]`.
+ * @return {Promise} A promise resolved with the payload of captured system settings.
+ */
+
+/**
+ * Runs through all the solutions currently available on the system, pulls the current
+ * setting for each supportedSetting and returns them in an object. Primary use case
+ * is for backing Capture tools that would allow a user to set up their GPII profile
+ * starting with the current settings for their applications on the local machine.
+ *
+ * @param {Function|gpii.lifecycleManager.read} readSettingsFunc - lifecycleManager.read (or suitable implementation),
+ * that takes solution registry entries, reads their current values on the device, and returns a promise resolved to
+ * them.
+ * @param {Object} solutions - Solutions registry entries for solutions available on the current machine.
+ * @param {Object} options - Extra options for processing.
+ * @param {Array} options.solutionsList - If provided, only solutions in this list of `solutionsID`s will
+ * be captured. Example:
+ *
+ * '''json
+ * ["com.microsoft.windows.cursors", "com.freedomscientific.jaws"]
+ * '''
+ * @return {fluid.promise} Returns a promise resolving with the entire system settings capture.
+ */
+gpii.flowManager.capture.captureSystemSettings = function (readSettingsFunc, solutions, options) {
+    var solutionsToFetch = fluid.copy(solutions);
+    if (options.solutionsList) {
+        fluid.remove_if(solutionsToFetch, function (solution, solutionID) {
+            return !options.solutionsList.includes(solutionID);
+        });
+    }
+
+    return readSettingsFunc(solutionsToFetch);
+};
+
+/**
+ * The raw return payload from the capture promise sequence looks like:
+ * '''json
+ *       [
+ *           {
+ *               "fakemag1": [
+ *                   {
+ *                       "settings": {
+ *                           "magnification": 2
+ *                       }
+ *                   }
+ *               ]
+ *           },
+ *           {
+ *               "fakemag1": [
+ *                   {
+ *                       "settings": {
+ *                           "invert": true
+ *                       }
+ *                   }
+ *               ]
+ *           },
+ *           {
+ *               "fakemag2": [
+ *                   {
+ *                       "settings": {
+ *                           "magnification": 2,
+ *                           "invert": true
+ *                       }
+ *                   }
+ *               ]
+ *           }
+ *       ]
+ * '''
+ *
+ * and we want:
+ * '''json
+ *       {
+ *           "fakemag1": {
+ *               "magnification": 2,
+ *               "invert": true
+ *           },
+ *           "fakemag2": {
+ *               "magnification": 2,
+ *               "invert": true
+ *           }
+ *       }
+ * '''
+ *
+ * @param {Object} data - The raw captured data.
+ * @return {Object} Returns a new payload with collapsed data, and multiple settings handler
+ * results for the same solution merged together.
+ */
+gpii.flowManager.capture.formatRawCapturedSettings = function (data) {
+    var togo = {};
+    fluid.each(data, function (sequenceItem) {
+        if (sequenceItem.isError) {
+            fluid.log("Error capturing settings for: ", sequenceItem);
+            return;
+        }
+        fluid.each(sequenceItem, function (item, key) {
+            if (!togo[key]) {
+                togo[key] = {};
+            }
+            fluid.each(fluid.get(item, [0, "settings"]), function (value, settingId) {
+                togo[key][settingId] = value;
+            });
+        });
+    });
+    return togo;
+};

gpii/node_modules/flowManager/src/FlowManager.js

@@ -28,6 +28,7 @@ require("./DefaultSettingsLoader.js");
 require("./PSPChannel.js");
 require("./SettingsDataSource.js");
 require("./UntrustedFlowManager.js");
+require("./Capture.js");
 
 require("preferencesServer");
 require("lifecycleManager");
@@ -179,6 +180,9 @@ fluid.defaults("gpii.flowManager.local", {
         eventLog: {
             type: "gpii.eventLog"
         },
+        capture: {
+            type: "gpii.flowManager.capture"
+        },
         userListeners: {
             type: "gpii.userListeners"
         },

gpii/node_modules/flowManager/src/MatchMaking.js

@@ -77,28 +77,45 @@
         });
     };
 
-    /*
-     * Asynchronous function which makes a get call to the solutions registry (1st parameter) to
+    /**
+     * Asynchronous/Promise returning function which makes a get call to the solutions registry (1st parameter) to
      * retrieve the solutions registry matching what is passed in the `device` parameter.
      * This is appended to the matchmaker payload (mmpayload) parameter, which in turn is passed
      * as parameter in the event fired.
      *
-     * @solutionsRegistryDataSource (Object) - a solutions registry data source
-     * @deviceContext (Object) - output from a device reporter. Used to filter solutions registry entries
-     * @event (Object) - Event to be fired when the solutionsRegistry entry has been retrieved
-     * @onError (Object) - Event to be fired when an error occurs
+     * This function can be used with either (or both) asyncronously with an `event` and `onError` handlers
+     * passed in, or with the returned `fluid.promise`.
      *
-     * @return (undefined) - function is asynchronous and doesn't return anything. Instead the event
-     *      is fired with the modified mmpayload.
+     * @param {Object} solutionsRegistryDataSource - a solutions registry data source
+     * @param {Object} deviceContext - output from a device reporter. Used to filter solutions registry entries
+     * @param {Object} onSuccessEvent - Optional: Event to be fired when the solutionsRegistry entry has been retrieved
+     * @param {Object} onErrorEvent - Optional: Event to be fired when an error occurs
+     * @return {fluid.promise} - Returns a promise resolving with the mmpayload. Optionally if provided, the events
+     *      are also fired with the modified mmpayload.
      */
-    gpii.flowManager.getSolutions = function (solutionsRegistryDataSource, deviceContext, event, onError) {
+    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);
             fluid.log("Fetched filtered solutions registry entries: ", gpii.renderMegapayload({solutionsRegistryEntries: solutionsRegistryEntries}));
-            event.fire(solutionsRegistryEntries, solutions);
-        }, onError.fire);
+            promiseTogo.resolve({
+                solutionsRegistryEntries: solutionsRegistryEntries,
+                solutions: solutions
+            });
+            if (onSuccessEvent) {
+                onSuccessEvent.fire(solutionsRegistryEntries, solutions);
+            }
+        }, function (error) {
+            promiseTogo.reject(error);
+            if (onErrorEvent) {
+                onErrorEvent.fire(error);
+            }
+        });
+
+        return promiseTogo;
     };
 
     // initialPayload contains fields