Allow omitting optional parameters for Extensions API functions

chrome/renderer/resources/extensions/schema_generated_bindings.js

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // This script contains privileged chrome extension related javascript APIs.
 // It is loaded by pages whose URL has the chrome-extension protocol.
 
 var chrome = chrome || {};
 (function() {
   native function GetChromeHidden();
@@ skipping 13 matching lines @@
   var internalAPIs = {};
   chromeHidden.internalAPIs = internalAPIs;
 
   function forEach(dict, f) {
     for (key in dict) {
       if (dict.hasOwnProperty(key))
         f(key, dict[key]);
     }
   }
 
+  // Generate all possible signatures for a given API function schema.

[not at google - send to devlin, 2012/02/24 03:59:56]

i think these methods can be grouped with the other ones after the
chromeHidden.validator thing.

[Matt Tytel, 2012/02/29 04:36:37]

Done.

+  function getSignatures(paramList) {
+    if (paramList.length === 0)
+      return [[]];
+
+    var signatures = [];
+    var remaining = getSignatures(paramList.slice(1));
+    for (var i = 0; i < remaining.length; i++)
+      signatures.push([paramList[0]].concat(remaining[i]))
+
+    if (paramList[0].optional)
+      return signatures.concat(remaining);
+    return signatures;
+  };
+
+  // Return true if arguments match a given signature's schema.
+  function argumentsMatchSignature(args, paramList) {
+    if (args.length != paramList.length)
+      return false;
+
+    for (var i = 0; i < paramList.length; i++) {
+      if (!chromeHidden.schemaValidator.isValidSchemaType(
+          chromeHidden.JSONSchemaValidator.getType(args[i]), paramList[i]))
+        return false;
+    }
+    return true;
+  };
+
+  // Finds the function signature for the given arguments.
+  function resolveSignature(args, paramList) {
+    var candidateSignatures = getSignatures(paramList);
+    for (var i = 0; i < candidateSignatures.length; i++) {
+      if (argumentsMatchSignature(args, candidateSignatures[i]))
+        return candidateSignatures[i];
+    }
+    return null;
+  };
+
+  // Validates that a given schema for an API function is not ambiguous.
+  function isParameterSchemaAmbiguous(parameterSchema) {
+    var signaturesAmbiguous = function(signature1, signature2) {
+      if (signature1.length != signature2.length)
+        return false;
+
+      for (var i = 0; i < signature1.length; i++) {
+        if (!chromeHidden.schemaValidator.checkSchemaOverlap(signature1[i],
+            signature2[i]))
+          return false;
+      }
+      return true;
+    };
+
+    var signatures = getSignatures(parameterSchema);
+    for (var i = 0; i < signatures.length; i++) {
+      for (var j = i + 1; j < signatures.length; j++) {
+        if (signaturesAmbiguous(signatures[i], signatures[j]))
+          return true;
+      }
+    }
+    return false;
+  };
+
   // Validate arguments.
-  chromeHidden.validationTypes = [];
-  chromeHidden.validate = function(args, schemas) {
-    if (args.length > schemas.length)
+  chromeHidden.schemaValidator = new chromeHidden.JSONSchemaValidator();
+  chromeHidden.validate = function(args, paramList) {
+    if (args.length > paramList.length)
       throw new Error("Too many arguments.");
 
-    for (var i = 0; i < schemas.length; i++) {
+    for (var i = 0; i < paramList.length; i++) {
       if (i in args && args[i] !== null && args[i] !== undefined) {
-        var validator = new chromeHidden.JSONSchemaValidator();
-        validator.addTypes(chromeHidden.validationTypes);
-        validator.validate(args[i], schemas[i]);
-        if (validator.errors.length == 0)
+        chromeHidden.schemaValidator.resetErrors();
+        chromeHidden.schemaValidator.validate(args[i], paramList[i]);
+        if (chromeHidden.schemaValidator.errors.length == 0)
           continue;
 
         var message = "Invalid value for argument " + (i + 1) + ". ";
-        for (var i = 0, err; err = validator.errors[i]; i++) {
+        for (var i = 0; i < chromeHidden.schemaValidator.length; i++) {
+          var err = chromeHidden.schemaValidator.errors[i];
           if (err.path) {
             message += "Property '" + err.path + "': ";
           }
           message += err.message;
           message = message.substring(0, message.length - 1);
           message += ", ";
         }
         message = message.substring(0, message.length - 2);
         message += ".";
 
         throw new Error(message);
-      } else if (!schemas[i].optional) {
+      } else if (!paramList[i].optional) {
         throw new Error("Parameter " + (i + 1) + " is required.");
       }
     }
   };
 
+  // Returns a string representing the defined signature of the API function.
+  // Example return value for chrome.windows.getCurrent:
+  // "windows.getCurrent(optional object populate, function callback)"
+  function getParameterSignatureString(name, paramList) {
+    var getSchemaTypeString = function(schema) {
+      var schemaTypes =
+          chromeHidden.schemaValidator.getAllTypesForSchema(schema);
+      var typeName = schemaTypes.join(" or ") + " " + schema.name;
+      if (schema.optional)
+        return "optional " + typeName;
+      return typeName;
+    };
+
+    var typeNames = paramList.map(getSchemaTypeString);
+    return name + "(" + typeNames.join(", ") + ")";
+  };
+
+  // Returns a string representing a call to an API function.
+  // Example return value for call: chrome.windows.get(1, callback) is:
+  // "windows.get(int, function)"
+  function getArgumentSignatureString(name, args) {
+    var typeNames = args.map(chromeHidden.JSONSchemaValidator.getType);
+    return name + "(" + typeNames.join(", ") + ")";
+  };
+
+  // Finds the correct signature for the given arguments, then validates the
+  // arguments against that signature. Returns a 'normalized' arguments list
+  // where nulls are inserted where optional parameters were omitted.
+  chromeHidden.updateArgumentsValidate = function(args, funDef) {
+    var paramList = funDef.definition.parameters;
+    var resolvedSignature = resolveSignature(args, paramList);
+    if (!resolvedSignature)
+      throw new Error("Invocation of form " +
+          getArgumentSignatureString(funDef.name, args) +
+          " doesn't match definition " +
+          getParameterSignatureString(funDef.name, paramList));
+    chromeHidden.validate(args, resolvedSignature);
+
+    var normalizedArgs = [];
+    var ai = 0;
+    for (var si = 0; si < paramList.length; si++) {
+      if (paramList[si] === resolvedSignature[ai])
+        normalizedArgs.push(args[ai++]);
+      else
+        normalizedArgs.push(null);
+    }
+    return normalizedArgs;
+  };
+
   // Callback handling.
   var requests = [];
   chromeHidden.handleResponse = function(requestId, name,
                                          success, response, error) {
     try {
       var request = requests[requestId];
       if (success) {
         delete chrome.extension.lastError;
       } else {
         if (!error) {
@@ skipping 307 matching lines @@
 
       // See comment on internalAPIs at the top.
       var mod = apiDef.internal ? internalAPIs : chrome;
 
       var namespaces = apiDef.namespace.split('.');
       for (var index = 0, name; name = namespaces[index]; index++) {
         mod[name] = mod[name] || {};
         mod = mod[name];
       }
 
-      // Add types to global validationTypes
+      // Add types to global schemaValidator
       if (apiDef.types) {
         apiDef.types.forEach(function(t) {
           if (!isSchemaNodeSupported(t, platform, manifestVersion))
             return;
 
-          chromeHidden.validationTypes.push(t);
+          chromeHidden.schemaValidator.addTypes(t);
           if (t.type == 'object' && customTypes[t.id]) {
             customTypes[t.id].prototype.setSchema(t);
           }
         });
       }
 
       // Returns whether access to the content of a schema should be denied,
       // based on the presence of "unprivileged" and whether this is an
       // extension process (versus e.g. a content script).
       function isSchemaAccessAllowed(itemSchema) {
@@ skipping 22 matching lines @@
           if (!isSchemaNodeSupported(functionDef, platform, manifestVersion))
             return;
           if (!isSchemaAccessAllowed(functionDef)) {
             addUnprivilegedAccessGetter(mod, functionDef.name);
             return;
           }
 
           var apiFunction = {};
           apiFunction.definition = functionDef;
           apiFunction.name = apiDef.namespace + "." + functionDef.name;
+
+          // Validate API for ambiguity only in DEBUG mode.
+          // TODO(aa): It would be best to run this in a unit test, but in order
+          // to do that we would need to better factor this code so that it
+          // didn't depend on so much v8::Extension machinery.
+          if (chromeHidden.validateAPI &&
+              isParameterSchemaAmbiguous(apiFunction.definition.parameters))
+            throw new Error(apiFunction.name + " is ambiguous");
+
           apiFunctions.register(apiFunction.name, apiFunction);
-
           mod[functionDef.name] = (function() {
-            var args = arguments;
+            var args = Array.prototype.slice.call(arguments);
             if (this.updateArgumentsPreValidate)
               args = this.updateArgumentsPreValidate.apply(this, args);
-            chromeHidden.validate(args, this.definition.parameters);
+
+            args = chromeHidden.updateArgumentsValidate(args, this);
             if (this.updateArgumentsPostValidate)
               args = this.updateArgumentsPostValidate.apply(this, args);
 
             var retval;
             if (this.handleRequest) {
               retval = this.handleRequest.apply(this, args);
             } else {
               retval = sendRequest(this.name, args,
                                    this.definition.parameters,
                                    {customCallback: this.customCallback});
@@ skipping 116 matching lines @@
     // See http://crbug.com/100242
     if (chrome.webstorePrivate) {
       chrome.webstorePrivate.beginInstallWithManifest2 =
           chrome.webstorePrivate.beginInstallWithManifest3;
     }
 
     if (chrome.test)
       chrome.test.getApiDefinitions = GetExtensionAPIDefinition;
   });
 })();