extensions/renderer/resources/binding.js

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 var Event = require('event_bindings').Event;
   6 var forEach = require('utils').forEach;
   7 var GetAvailability = requireNative('v8_context').GetAvailability;
   8 var exceptionHandler = require('uncaught_exception_handler');
   9 var lastError = require('lastError');
  10 var logActivity = requireNative('activityLogger');
  11 var logging = requireNative('logging');
  12 var process = requireNative('process');
  13 var schemaRegistry = requireNative('schema_registry');
  14 var schemaUtils = require('schemaUtils');
  15 var utils = require('utils');
  16 var sendRequestHandler = require('sendRequest');
  17
  18 var contextType = process.GetContextType();
  19 var extensionId = process.GetExtensionId();
  20 var manifestVersion = process.GetManifestVersion();
  21 var sendRequest = sendRequestHandler.sendRequest;
  22
  23 // Stores the name and definition of each API function, with methods to
  24 // modify their behaviour (such as a custom way to handle requests to the
  25 // API, a custom callback, etc).
  26 function APIFunctions(namespace) {
  27   this.apiFunctions_ = {};
  28   this.unavailableApiFunctions_ = {};
  29   this.namespace = namespace;
  30 }
  31
  32 APIFunctions.prototype.register = function(apiName, apiFunction) {
  33   this.apiFunctions_[apiName] = apiFunction;
  34 };
  35
  36 // Registers a function as existing but not available, meaning that calls to
  37 // the set* methods that reference this function should be ignored rather
  38 // than throwing Errors.
  39 APIFunctions.prototype.registerUnavailable = function(apiName) {
  40   this.unavailableApiFunctions_[apiName] = apiName;
  41 };
  42
  43 APIFunctions.prototype.setHook_ =
  44     function(apiName, propertyName, customizedFunction) {
  45   if ($Object.hasOwnProperty(this.unavailableApiFunctions_, apiName))
  46     return;
  47   if (!$Object.hasOwnProperty(this.apiFunctions_, apiName))
  48     throw new Error('Tried to set hook for unknown API "' + apiName + '"');
  49   this.apiFunctions_[apiName][propertyName] = customizedFunction;
  50 };
  51
  52 APIFunctions.prototype.setHandleRequest =
  53     function(apiName, customizedFunction) {
  54   var prefix = this.namespace;
  55   return this.setHook_(apiName, 'handleRequest',
  56     function() {
  57       var ret = $Function.apply(customizedFunction, this, arguments);
  58       // Logs API calls to the Activity Log if it doesn't go through an
  59       // ExtensionFunction.
  60       if (!sendRequestHandler.getCalledSendRequest())
  61         logActivity.LogAPICall(extensionId, prefix + "." + apiName,
  62             $Array.slice(arguments));
  63       return ret;
  64     });
  65 };
  66
  67 APIFunctions.prototype.setHandleRequestWithPromise =
  68     function(apiName, customizedFunction) {
  69   var prefix = this.namespace;
  70   return this.setHook_(apiName, 'handleRequest', function() {
  71       var name = prefix + '.' + apiName;
  72       logActivity.LogAPICall(extensionId, name, $Array.slice(arguments));
  73       var stack = exceptionHandler.getExtensionStackTrace();
  74       var callback = arguments[arguments.length - 1];
  75       var args = $Array.slice(arguments, 0, arguments.length - 1);
  76       var keepAlivePromise = requireAsync('keep_alive').then(function(module) {
  77         return module.createKeepAlive();
  78       });
  79       $Function.apply(customizedFunction, this, args).then(function(result) {
  80         if (callback) {
  81           sendRequestHandler.safeCallbackApply(name, {'stack': stack}, callback,
  82                                                [result]);
  83         }
  84       }).catch(function(error) {
  85         if (callback) {
  86           var message = exceptionHandler.safeErrorToString(error, true);
  87           lastError.run(name, message, stack, callback);
  88         }
  89       }).then(function() {
  90         keepAlivePromise.then(function(keepAlive) {
  91           keepAlive.close();
  92         });
  93       });
  94     });
  95 };
  96
  97 APIFunctions.prototype.setUpdateArgumentsPostValidate =
  98     function(apiName, customizedFunction) {
  99   return this.setHook_(
 100     apiName, 'updateArgumentsPostValidate', customizedFunction);
 101 };
 102
 103 APIFunctions.prototype.setUpdateArgumentsPreValidate =
 104     function(apiName, customizedFunction) {
 105   return this.setHook_(
 106     apiName, 'updateArgumentsPreValidate', customizedFunction);
 107 };
 108
 109 APIFunctions.prototype.setCustomCallback =
 110     function(apiName, customizedFunction) {
 111   return this.setHook_(apiName, 'customCallback', customizedFunction);
 112 };
 113
 114 function CustomBindingsObject() {
 115 }
 116
 117 CustomBindingsObject.prototype.setSchema = function(schema) {
 118   // The functions in the schema are in list form, so we move them into a
 119   // dictionary for easier access.
 120   var self = this;
 121   self.functionSchemas = {};
 122   $Array.forEach(schema.functions, function(f) {
 123     self.functionSchemas[f.name] = {
 124       name: f.name,
 125       definition: f
 126     }
 127   });
 128 };
 129
 130 // Get the platform from navigator.appVersion.
 131 function getPlatform() {
 132   var platforms = [
 133     [/CrOS Touch/, "chromeos touch"],
 134     [/CrOS/, "chromeos"],
 135     [/Linux/, "linux"],
 136     [/Mac/, "mac"],
 137     [/Win/, "win"],
 138   ];
 139
 140   for (var i = 0; i < platforms.length; i++) {
 141     if ($RegExp.test(platforms[i][0], navigator.appVersion)) {
 142       return platforms[i][1];
 143     }
 144   }
 145   return "unknown";
 146 }
 147
 148 function isPlatformSupported(schemaNode, platform) {
 149   return !schemaNode.platforms ||
 150       $Array.indexOf(schemaNode.platforms, platform) > -1;
 151 }
 152
 153 function isManifestVersionSupported(schemaNode, manifestVersion) {
 154   return !schemaNode.maximumManifestVersion ||
 155       manifestVersion <= schemaNode.maximumManifestVersion;
 156 }
 157
 158 function isSchemaNodeSupported(schemaNode, platform, manifestVersion) {
 159   return isPlatformSupported(schemaNode, platform) &&
 160       isManifestVersionSupported(schemaNode, manifestVersion);
 161 }
 162
 163 function createCustomType(type) {
 164   var jsModuleName = type.js_module;
 165   logging.CHECK(jsModuleName, 'Custom type ' + type.id +
 166                 ' has no "js_module" property.');
 167   var jsModule = require(jsModuleName);
 168   logging.CHECK(jsModule, 'No module ' + jsModuleName + ' found for ' +
 169                 type.id + '.');
 170   var customType = jsModule[jsModuleName];
 171   logging.CHECK(customType, jsModuleName + ' must export itself.');
 172   customType.prototype = new CustomBindingsObject();
 173   customType.prototype.setSchema(type);
 174   return customType;
 175 }
 176
 177 var platform = getPlatform();
 178
 179 function Binding(schema) {
 180   this.schema_ = schema;
 181   this.apiFunctions_ = new APIFunctions(schema.namespace);
 182   this.customEvent_ = null;
 183   this.customHooks_ = [];
 184 };
 185
 186 Binding.create = function(apiName) {
 187   return new Binding(schemaRegistry.GetSchema(apiName));
 188 };
 189
 190 Binding.prototype = {
 191   // The API through which the ${api_name}_custom_bindings.js files customize
 192   // their API bindings beyond what can be generated.
 193   //
 194   // There are 2 types of customizations available: those which are required in
 195   // order to do the schema generation (registerCustomEvent and
 196   // registerCustomType), and those which can only run after the bindings have
 197   // been generated (registerCustomHook).
 198
 199   // Registers a custom event type for the API identified by |namespace|.
 200   // |event| is the event's constructor.
 201   registerCustomEvent: function(event) {
 202     this.customEvent_ = event;
 203   },
 204
 205   // Registers a function |hook| to run after the schema for all APIs has been
 206   // generated.  The hook is passed as its first argument an "API" object to
 207   // interact with, and second the current extension ID. See where
 208   // |customHooks| is used.
 209   registerCustomHook: function(fn) {
 210     $Array.push(this.customHooks_, fn);
 211   },
 212
 213   // TODO(kalman/cduvall): Refactor this so |runHooks_| is not needed.
 214   runHooks_: function(api) {
 215     $Array.forEach(this.customHooks_, function(hook) {
 216       if (!isSchemaNodeSupported(this.schema_, platform, manifestVersion))
 217         return;
 218
 219       if (!hook)
 220         return;
 221
 222       hook({
 223         apiFunctions: this.apiFunctions_,
 224         schema: this.schema_,
 225         compiledApi: api
 226       }, extensionId, contextType);
 227     }, this);
 228   },
 229
 230   // Generates the bindings from |this.schema_| and integrates any custom
 231   // bindings that might be present.
 232   generate: function() {
 233     var schema = this.schema_;
 234
 235     function shouldCheckUnprivileged() {
 236       var shouldCheck = 'unprivileged' in schema;
 237       if (shouldCheck)
 238         return shouldCheck;
 239
 240       $Array.forEach(['functions', 'events'], function(type) {
 241         if ($Object.hasOwnProperty(schema, type)) {
 242           $Array.forEach(schema[type], function(node) {
 243             if ('unprivileged' in node)
 244               shouldCheck = true;
 245           });
 246         }
 247       });
 248       if (shouldCheck)
 249         return shouldCheck;
 250
 251       for (var property in schema.properties) {
 252         if ($Object.hasOwnProperty(schema, property) &&
 253             'unprivileged' in schema.properties[property]) {
 254           shouldCheck = true;
 255           break;
 256         }
 257       }
 258       return shouldCheck;
 259     }
 260     var checkUnprivileged = shouldCheckUnprivileged();
 261
 262     // TODO(kalman/cduvall): Make GetAvailability handle this, then delete the
 263     // supporting code.
 264     if (!isSchemaNodeSupported(schema, platform, manifestVersion)) {
 265       console.error('chrome.' + schema.namespace + ' is not supported on ' +
 266                     'this platform or manifest version');
 267       return undefined;
 268     }
 269
 270     var mod = {};
 271
 272     var namespaces = $String.split(schema.namespace, '.');
 273     for (var index = 0, name; name = namespaces[index]; index++) {
 274       mod[name] = mod[name] || {};
 275       mod = mod[name];
 276     }
 277
 278     if (schema.types) {
 279       $Array.forEach(schema.types, function(t) {
 280         if (!isSchemaNodeSupported(t, platform, manifestVersion))
 281           return;
 282
 283         // Add types to global schemaValidator; the types we depend on from
 284         // other namespaces will be added as needed.
 285         schemaUtils.schemaValidator.addTypes(t);
 286
 287         // Generate symbols for enums.
 288         var enumValues = t['enum'];
 289         if (enumValues) {
 290           // Type IDs are qualified with the namespace during compilation,
 291           // unfortunately, so remove it here.
 292           logging.DCHECK(
 293               t.id.substr(0, schema.namespace.length) == schema.namespace);
 294           // Note: + 1 because it ends in a '.', e.g., 'fooApi.Type'.
 295           var id = t.id.substr(schema.namespace.length + 1);
 296           mod[id] = {};
 297           $Array.forEach(enumValues, function(enumValue) {
 298             // Note: enums can be declared either as a list of strings
 299             // ['foo', 'bar'] or as a list of objects
 300             // [{'name': 'foo'}, {'name': 'bar'}].
 301             enumValue =
 302                 enumValue.hasOwnProperty('name') ? enumValue.name : enumValue;
 303             if (enumValue)  // Avoid setting any empty enums.
 304               mod[id][enumValue] = enumValue;
 305           });
 306         }
 307       }, this);
 308     }
 309
 310     // TODO(cduvall): Take out when all APIs have been converted to features.
 311     // Returns whether access to the content of a schema should be denied,
 312     // based on the presence of "unprivileged" and whether this is an
 313     // extension process (versus e.g. a content script).
 314     function isSchemaAccessAllowed(itemSchema) {
 315       return (contextType == 'BLESSED_EXTENSION') ||
 316              schema.unprivileged ||
 317              itemSchema.unprivileged;
 318     };
 319
 320     // Setup Functions.
 321     if (schema.functions) {
 322       $Array.forEach(schema.functions, function(functionDef) {
 323         if (functionDef.name in mod) {
 324           throw new Error('Function ' + functionDef.name +
 325                           ' already defined in ' + schema.namespace);
 326         }
 327
 328         if (!isSchemaNodeSupported(functionDef, platform, manifestVersion)) {
 329           this.apiFunctions_.registerUnavailable(functionDef.name);
 330           return;
 331         }
 332
 333         var apiFunction = {};
 334         apiFunction.definition = functionDef;
 335         apiFunction.name = schema.namespace + '.' + functionDef.name;
 336
 337         if (!GetAvailability(apiFunction.name).is_available ||
 338             (checkUnprivileged && !isSchemaAccessAllowed(functionDef))) {
 339           this.apiFunctions_.registerUnavailable(functionDef.name);
 340           return;
 341         }
 342
 343         // TODO(aa): It would be best to run this in a unit test, but in order
 344         // to do that we would need to better factor this code so that it
 345         // doesn't depend on so much v8::Extension machinery.
 346         if (logging.DCHECK_IS_ON() &&
 347             schemaUtils.isFunctionSignatureAmbiguous(apiFunction.definition)) {
 348           throw new Error(
 349               apiFunction.name + ' has ambiguous optional arguments. ' +
 350               'To implement custom disambiguation logic, add ' +
 351               '"allowAmbiguousOptionalArguments" to the function\'s schema.');
 352         }
 353
 354         this.apiFunctions_.register(functionDef.name, apiFunction);
 355
 356         mod[functionDef.name] = $Function.bind(function() {
 357           var args = $Array.slice(arguments);
 358           if (this.updateArgumentsPreValidate)
 359             args = $Function.apply(this.updateArgumentsPreValidate, this, args);
 360
 361           args = schemaUtils.normalizeArgumentsAndValidate(args, this);
 362           if (this.updateArgumentsPostValidate) {
 363             args = $Function.apply(this.updateArgumentsPostValidate,
 364                                    this,
 365                                    args);
 366           }
 367
 368           sendRequestHandler.clearCalledSendRequest();
 369
 370           var retval;
 371           if (this.handleRequest) {
 372             retval = $Function.apply(this.handleRequest, this, args);
 373           } else {
 374             var optArgs = {
 375               customCallback: this.customCallback
 376             };
 377             retval = sendRequest(this.name, args,
 378                                  this.definition.parameters,
 379                                  optArgs);
 380           }
 381           sendRequestHandler.clearCalledSendRequest();
 382
 383           // Validate return value if in sanity check mode.
 384           if (logging.DCHECK_IS_ON() && this.definition.returns)
 385             schemaUtils.validate([retval], [this.definition.returns]);
 386           return retval;
 387         }, apiFunction);
 388       }, this);
 389     }
 390
 391     // Setup Events
 392     if (schema.events) {
 393       $Array.forEach(schema.events, function(eventDef) {
 394         if (eventDef.name in mod) {
 395           throw new Error('Event ' + eventDef.name +
 396                           ' already defined in ' + schema.namespace);
 397         }
 398         if (!isSchemaNodeSupported(eventDef, platform, manifestVersion))
 399           return;
 400
 401         var eventName = schema.namespace + "." + eventDef.name;
 402         if (!GetAvailability(eventName).is_available ||
 403             (checkUnprivileged && !isSchemaAccessAllowed(eventDef))) {
 404           return;
 405         }
 406
 407         var options = eventDef.options || {};
 408         if (eventDef.filters && eventDef.filters.length > 0)
 409           options.supportsFilters = true;
 410
 411         var parameters = eventDef.parameters;
 412         if (this.customEvent_) {
 413           mod[eventDef.name] = new this.customEvent_(
 414               eventName, parameters, eventDef.extraParameters, options);
 415         } else {
 416           mod[eventDef.name] = new Event(eventName, parameters, options);
 417         }
 418       }, this);
 419     }
 420
 421     function addProperties(m, parentDef) {
 422       var properties = parentDef.properties;
 423       if (!properties)
 424         return;
 425
 426       forEach(properties, function(propertyName, propertyDef) {
 427         if (propertyName in m)
 428           return;  // TODO(kalman): be strict like functions/events somehow.
 429         if (!isSchemaNodeSupported(propertyDef, platform, manifestVersion))
 430           return;
 431         if (!GetAvailability(schema.namespace + "." +
 432               propertyName).is_available ||
 433             (checkUnprivileged && !isSchemaAccessAllowed(propertyDef))) {
 434           return;
 435         }
 436
 437         var value = propertyDef.value;
 438         if (value) {
 439           // Values may just have raw types as defined in the JSON, such
 440           // as "WINDOW_ID_NONE": { "value": -1 }. We handle this here.
 441           // TODO(kalman): enforce that things with a "value" property can't
 442           // define their own types.
 443           var type = propertyDef.type || typeof(value);
 444           if (type === 'integer' || type === 'number') {
 445             value = parseInt(value);
 446           } else if (type === 'boolean') {
 447             value = value === 'true';
 448           } else if (propertyDef['$ref']) {
 449             var ref = propertyDef['$ref'];
 450             var type = utils.loadTypeSchema(propertyDef['$ref'], schema);
 451             logging.CHECK(type, 'Schema for $ref type ' + ref + ' not found');
 452             var constructor = createCustomType(type);
 453             var args = value;
 454             // For an object propertyDef, |value| is an array of constructor
 455             // arguments, but we want to pass the arguments directly (i.e.
 456             // not as an array), so we have to fake calling |new| on the
 457             // constructor.
 458             value = { __proto__: constructor.prototype };
 459             $Function.apply(constructor, value, args);
 460             // Recursively add properties.
 461             addProperties(value, propertyDef);
 462           } else if (type === 'object') {
 463             // Recursively add properties.
 464             addProperties(value, propertyDef);
 465           } else if (type !== 'string') {
 466             throw new Error('NOT IMPLEMENTED (extension_api.json error): ' +
 467                 'Cannot parse values for type "' + type + '"');
 468           }
 469           m[propertyName] = value;
 470         }
 471       });
 472     };
 473
 474     addProperties(mod, schema);
 475
 476     // This generate() call is considered successful if any functions,
 477     // properties, or events were created.
 478     var success = ($Object.keys(mod).length > 0);
 479
 480     // Special case: webViewRequest is a vacuous API which just copies its
 481     // implementation from declarativeWebRequest.
 482     //
 483     // TODO(kalman): This would be unnecessary if we did these checks after the
 484     // hooks (i.e. this.runHooks_(mod)). The reason we don't is to be very
 485     // conservative with running any JS which might actually be for an API
 486     // which isn't available, but this is probably overly cautious given the
 487     // C++ is only giving us APIs which are available. FIXME.
 488     if (schema.namespace == 'webViewRequest') {
 489       success = true;
 490     }
 491
 492     // Special case: runtime.lastError is only occasionally set, so
 493     // specifically check its availability.
 494     if (schema.namespace == 'runtime' &&
 495         GetAvailability('runtime.lastError').is_available) {
 496       success = true;
 497     }
 498
 499     if (!success) {
 500       var availability = GetAvailability(schema.namespace);
 501       // If an API was available it should have been successfully generated.
 502       logging.DCHECK(!availability.is_available,
 503                      schema.namespace + ' was available but not generated');
 504       console.error('chrome.' + schema.namespace + ' is not available: ' +
 505                     availability.message);
 506       return;
 507     }
 508
 509     this.runHooks_(mod);
 510     return mod;
 511   }
 512 };
 513
 514 exports.Binding = Binding;