Bug 1440932 - Add some documentation and other small improvements to the policy engine. r=bytesized
authorFelipe Gomes <felipc@gmail.com>
Mon, 26 Feb 2018 15:42:27 -0300
changeset 405321 b82d04b3bd6f886d1be3d55474f955800c3ffb68
parent 405320 d35c034bf194e0cf88330157aa167a880c1e2b29
child 405322 5d7a2c906875e26e2e09f874af703775d7559349
push id60196
push userfelipc@gmail.com
push dateMon, 26 Feb 2018 18:57:52 +0000
treeherderautoland@5d7a2c906875 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersbytesized
bugs1440932
milestone60.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1440932 - Add some documentation and other small improvements to the policy engine. r=bytesized MozReview-Commit-ID: 5QeOmcx076r
browser/components/enterprisepolicies/EnterprisePolicies.js
browser/components/enterprisepolicies/Policies.jsm
--- a/browser/components/enterprisepolicies/EnterprisePolicies.js
+++ b/browser/components/enterprisepolicies/EnterprisePolicies.js
@@ -3,17 +3,16 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 ChromeUtils.import("resource://gre/modules/XPCOMUtils.jsm");
 ChromeUtils.import("resource://gre/modules/Services.jsm");
 ChromeUtils.import("resource://gre/modules/AppConstants.jsm");
 
 XPCOMUtils.defineLazyModuleGetters(this, {
   WindowsGPOParser: "resource:///modules/policies/WindowsGPOParser.jsm",
-  NetUtil: "resource://gre/modules/NetUtil.jsm",
   Policies: "resource:///modules/policies/Policies.jsm",
   PoliciesValidator: "resource:///modules/policies/PoliciesValidator.jsm",
 });
 
 // This is the file that will be searched for in the
 // ${InstallDir}/distribution folder.
 const POLICIES_FILENAME = "policies.json";
 
@@ -135,33 +134,47 @@ EnterprisePoliciesManager.prototype = {
       if (!parametersAreValid) {
         log.error(`Invalid parameters specified for ${policyName}.`);
         continue;
       }
 
       let policyImpl = Policies[policyName];
 
       for (let timing of Object.keys(this._callbacks)) {
-        let policyCallback = policyImpl["on" + timing];
+        let policyCallback = policyImpl[timing];
         if (policyCallback) {
           this._schedulePolicyCallback(
             timing,
-            policyCallback.bind(null,
+            policyCallback.bind(policyImpl,
                                 this, /* the EnterprisePoliciesManager */
                                 parsedParameters));
         }
       }
     }
   },
 
   _callbacks: {
-    BeforeAddons: [],
-    ProfileAfterChange: [],
-    BeforeUIStartup: [],
-    AllWindowsRestored: [],
+    // The earlist that a policy callback can run. This will
+    // happen right after the Policy Engine itself has started,
+    // and before the Add-ons Manager has started.
+    onBeforeAddons: [],
+
+    // This happens after all the initialization related to
+    // the profile has finished (prefs, places database, etc.).
+    onProfileAfterChange: [],
+
+    // Just before the first browser window gets created.
+    onBeforeUIStartup: [],
+
+    // Called after all windows from the last session have been
+    // restored (or the default window and homepage tab, if the
+    // session is not being restored).
+    // The content of the tabs themselves have not necessarily
+    // finished loading.
+    onAllWindowsRestored: [],
   },
 
   _schedulePolicyCallback(timing, callback) {
     this._callbacks[timing].push(callback);
   },
 
   _runPoliciesCallbacks(timing) {
     let callbacks = this._callbacks[timing];
@@ -211,32 +224,33 @@ EnterprisePoliciesManager.prototype = {
       this.observe(null, "sessionstore-windows-restored", null);
     });
   },
 
   // nsIObserver implementation
   observe: function BG_observe(subject, topic, data) {
     switch (topic) {
       case "policies-startup":
+        // Before the first set of policy callbacks runs, we must
+        // initialize the service.
         this._initialize();
-        this._runPoliciesCallbacks("BeforeAddons");
+
+        this._runPoliciesCallbacks("onBeforeAddons");
         break;
 
       case "profile-after-change":
-        // Before the first set of policy callbacks runs, we must
-        // initialize the service.
-        this._runPoliciesCallbacks("ProfileAfterChange");
+        this._runPoliciesCallbacks("onProfileAfterChange");
         break;
 
       case "final-ui-startup":
-        this._runPoliciesCallbacks("BeforeUIStartup");
+        this._runPoliciesCallbacks("onBeforeUIStartup");
         break;
 
       case "sessionstore-windows-restored":
-        this._runPoliciesCallbacks("AllWindowsRestored");
+        this._runPoliciesCallbacks("onAllWindowsRestored");
 
         // After the last set of policy callbacks ran, notify the test observer.
         Services.obs.notifyObservers(null,
                                      "EnterprisePolicies:AllPoliciesApplied");
         break;
 
       case "EnterprisePolicies:Restart":
         this._restart().then(null, Cu.reportError);
--- a/browser/components/enterprisepolicies/Policies.jsm
+++ b/browser/components/enterprisepolicies/Policies.jsm
@@ -27,16 +27,42 @@ XPCOMUtils.defineLazyGetter(this, "log",
     // messages during development. See LOG_LEVELS in Console.jsm for details.
     maxLogLevel: "error",
     maxLogLevelPref: PREF_LOGLEVEL,
   });
 });
 
 var EXPORTED_SYMBOLS = ["Policies"];
 
+/*
+ * ============================
+ * = POLICIES IMPLEMENTATIONS =
+ * ============================
+ *
+ * The Policies object below is where the implementation for each policy
+ * happens. An object for each policy should be defined, containing
+ * callback functions that will be called by the engine.
+ *
+ * See the _callbacks object in EnterprisePolicies.js for the list of
+ * possible callbacks and an explanation of each.
+ *
+ * Each callback will be called with two parameters:
+ * - manager
+ *   This is the EnterprisePoliciesManager singleton object from
+ *   EnterprisePolicies.js
+ *
+ * - param
+ *   The parameter defined for this policy in policies-schema.json.
+ *   It will be different for each policy. It could be a boolean,
+ *   a string, an array or a complex object. All parameters have
+ *   been validated according to the schema, and no unknown
+ *   properties will be present on them.
+ *
+ * The callbacks will be bound to their parent policy object.
+ */
 var Policies = {
   "BlockAboutAddons": {
     onBeforeUIStartup(manager, param) {
       if (param) {
         manager.disallowFeature("about:addons", true);
       }
     }
   },
@@ -201,16 +227,29 @@ var Policies = {
 /*
  * ====================
  * = HELPER FUNCTIONS =
  * ====================
  *
  * The functions below are helpers to be used by several policies.
  */
 
+/**
+ * setAndLockPref
+ *
+ * Sets the _default_ value of a pref, and locks it (meaning that
+ * the default value will always be returned, independent from what
+ * is stored as the user value).
+ * The value is only changed in memory, and not stored to disk.
+ *
+ * @param {string} prefName
+ *        The pref to be changed
+ * @param {boolean,number,string} prefValue
+ *        The value to set and lock
+ */
 function setAndLockPref(prefName, prefValue) {
   if (Services.prefs.prefIsLocked(prefName)) {
     Services.prefs.unlockPref(prefName);
   }
 
   let defaults = Services.prefs.getDefaultBranch("");
 
   switch (typeof(prefValue)) {
@@ -229,16 +268,29 @@ function setAndLockPref(prefName, prefVa
     case "string":
       defaults.setStringPref(prefName, prefValue);
       break;
   }
 
   Services.prefs.lockPref(prefName);
 }
 
+/**
+ * addAllowDenyPermissions
+ *
+ * Helper function to call the permissions manager (Services.perms.add)
+ * for two arrays of URLs.
+ *
+ * @param {string} permissionName
+ *        The name of the permission to change
+ * @param {array} allowList
+ *        The list of URLs to be set as ALLOW_ACTION for the chosen permission.
+ * @param {array} blockList
+ *        The list of URLs to be set as DENY_ACTION for the chosen permission.
+ */
 function addAllowDenyPermissions(permissionName, allowList, blockList) {
   allowList = allowList || [];
   blockList = blockList || [];
 
   for (let origin of allowList) {
     Services.perms.add(origin,
                        permissionName,
                        Ci.nsIPermissionManager.ALLOW_ACTION,