Capture.js

/**
 * GPII snapshot Handler
 *
 * Copyright 2014 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"]
        },
        "onSolutionsForCurrentDevice.getSolutionsPromise": {
            funcName: "gpii.flowManager.getSolutionsPromise",
            args: [ "{flowManager}.solutionsRegistryDataSource", "{arguments}.0"],
            priority: "after:getDeviceContextPromise"
        },
        "onSolutionsForCurrentDevice.solutionsRegistryEntriesToPromise": {
            funcName: "fluid.toPromise",
            args: ["{arguments}.0.solutionsRegistryEntries"],
            priority: "after:getSolutionsPromise"
        },
        // Begin declaration of Promise Chain for onCaptureSettingsForCurrentDevice
        "onCaptureSettingsForCurrentDevice.getInstalledSolutionsForCurrentDevice": {
            func: "{that}.getInstalledSolutionsForCurrentDevice"
        },
        "onCaptureSettingsForCurrentDevice.captureSystemSettings": {
            func: "{that}.captureSystemSettings",
            args: ["{arguments}.0", "{arguments}.1"],
            priority: "after:getInstalledSolutionsForCurrentDevice"
        },
        "onCaptureSettingsForCurrentDevice.formatRawCapturedSettings": {
            func: "gpii.flowManager.formatRawCapturedSettings",
            args: ["{arguments}.0"],
            priority: "after:captureSystemSettings"
        }
    },
    invokers: {
        getInstalledSolutionsForCurrentDevice: {
            funcName: "gpii.flowManager.getInstalledSolutionsForCurrentDevice",
            args: ["{that}"]
        },
        getSystemSettingsCapture: {
            funcName: "gpii.flowManager.getSystemSettingsCapture",
            args: ["{that}.events.onCaptureSettingsForCurrentDevice", "{arguments}.0"] // options
        },
        captureSystemSettings: {
            funcName: "gpii.flowManager.captureSystemSettings",
            args: ["{lifecycleManager}.read", "{arguments}.0", "{arguments}.1"] // solutionsRegistryEntries, options
        }
    }
});

gpii.flowManager.getInstalledSolutionsForCurrentDevice = function (that) {
    return fluid.promise.fireTransformEvent(that.events.onSolutionsForCurrentDevice);
};

/**
 * 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 {Event} onCaptureSettingsForCurrentDevice - The transforming promise chain
 * @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.
 */
gpii.flowManager.getSystemSettingsCapture = function (onCaptureSettingsForCurrentDevice, options) {
    return fluid.promise.fireTransformEvent(onCaptureSettingsForCurrentDevice,
        {}, options);
};

/**
 * This function invokers a settings handler to fetch settings, but wraps the processing and reports
 * back any failures in an `isError: true` json block.
 *
 * @param {Function} invokeSettingsHandlerGet - The get function from the appropriate settings handler.
 * @param {String} solutionID - The dotted solution id, ex `com.freedomscientific.jaws`
 * @param {Object} handlerSpec - TODO, exactly how much of the solutions entry block is this?
 * @return {Object} The returned settings, or an error block with debugging information.
 */
gpii.flowManager.capture.safeHandlerGet = function (invokeSettingsHandlerGet, solutionID, handlerSpec) {
    var promiseTogo = fluid.promise();
    try {
        invokeSettingsHandlerGet(solutionID, handlerSpec).then(function (data) {
            promiseTogo.resolve(data);
        }, function (err) {
            promiseTogo.resolve({
                solutionId: solutionID,
                handlerSpec: handlerSpec,
                isError: true,
                message: "Capture Workflow Error: Settings Handler Promise Rejection",
                err: err
            });
        });
    }
    catch (err) {
        promiseTogo.resolve({
            solutionId: solutionID,
            handlerSpec: handlerSpec,
            isError: true,
            message: "Capture Workflow Error: Unexpected Error in operating settings handler.",
            err: err
        });
    }
    return promiseTogo;
};

/**
 * 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.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.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(item[0].settings, function (value, settingId) {
                togo[key][settingId] = value;
            });
        });
    });
    return togo;
};