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($String.substr(t.id, 0, schema.namespace.length) ==
 293                              schema.namespace);
 294           // Note: + 1 because it ends in a '.', e.g., 'fooApi.Type'.
 295           var id = $String.substr(t.id, 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 = $Object.hasOwnProperty(enumValue, 'name') ?
 302                 enumValue.name : enumValue;
 303             if (enumValue) {  // Avoid setting any empty enums.
 304               // Make all properties in ALL_CAPS_STYLE.
 305               // Replace myEnum-Foo with my_Enum-Foo:
 306               var propertyName =
 307                   $String.replace(enumValue, /([a-z])([A-Z])/g, '$1_$2');
 308               // Replace my_Enum-Foo with my_Enum_Foo:
 309               propertyName = $String.replace(propertyName, /\W/g, '_');
 310               // Uppercase (replace my_Enum_Foo with MY_ENUM_FOO):
 311               propertyName = $String.toUpperCase(propertyName);
 312               mod[id][propertyName] = enumValue;
 313             }
 314           });
 315         }
 316       }, this);
 317     }
 318
 319     // TODO(cduvall): Take out when all APIs have been converted to features.
 320     // Returns whether access to the content of a schema should be denied,
 321     // based on the presence of "unprivileged" and whether this is an
 322     // extension process (versus e.g. a content script).
 323     function isSchemaAccessAllowed(itemSchema) {
 324       return (contextType == 'BLESSED_EXTENSION') ||
 325              schema.unprivileged ||
 326              itemSchema.unprivileged;
 327     };
 328
 329     // Setup Functions.
 330     if (schema.functions) {
 331       $Array.forEach(schema.functions, function(functionDef) {
 332         if (functionDef.name in mod) {
 333           throw new Error('Function ' + functionDef.name +
 334                           ' already defined in ' + schema.namespace);
 335         }
 336
 337         if (!isSchemaNodeSupported(functionDef, platform, manifestVersion)) {
 338           this.apiFunctions_.registerUnavailable(functionDef.name);
 339           return;
 340         }
 341
 342         var apiFunction = {};
 343         apiFunction.definition = functionDef;
 344         apiFunction.name = schema.namespace + '.' + functionDef.name;
 345
 346         if (!GetAvailability(apiFunction.name).is_available ||
 347             (checkUnprivileged && !isSchemaAccessAllowed(functionDef))) {
 348           this.apiFunctions_.registerUnavailable(functionDef.name);
 349           return;
 350         }
 351
 352         // TODO(aa): It would be best to run this in a unit test, but in order
 353         // to do that we would need to better factor this code so that it
 354         // doesn't depend on so much v8::Extension machinery.
 355         if (logging.DCHECK_IS_ON() &&
 356             schemaUtils.isFunctionSignatureAmbiguous(apiFunction.definition)) {
 357           throw new Error(
 358               apiFunction.name + ' has ambiguous optional arguments. ' +
 359               'To implement custom disambiguation logic, add ' +
 360               '"allowAmbiguousOptionalArguments" to the function\'s schema.');
 361         }
 362
 363         this.apiFunctions_.register(functionDef.name, apiFunction);
 364
 365         mod[functionDef.name] = $Function.bind(function() {
 366           var args = $Array.slice(arguments);
 367           if (this.updateArgumentsPreValidate)
 368             args = $Function.apply(this.updateArgumentsPreValidate, this, args);
 369
 370           args = schemaUtils.normalizeArgumentsAndValidate(args, this);
 371           if (this.updateArgumentsPostValidate) {
 372             args = $Function.apply(this.updateArgumentsPostValidate,
 373                                    this,
 374                                    args);
 375           }
 376
 377           sendRequestHandler.clearCalledSendRequest();
 378
 379           var retval;
 380           if (this.handleRequest) {
 381             retval = $Function.apply(this.handleRequest, this, args);
 382           } else {
 383             var optArgs = {
 384               customCallback: this.customCallback
 385             };
 386             retval = sendRequest(this.name, args,
 387                                  this.definition.parameters,
 388                                  optArgs);
 389           }
 390           sendRequestHandler.clearCalledSendRequest();
 391
 392           // Validate return value if in sanity check mode.
 393           if (logging.DCHECK_IS_ON() && this.definition.returns)
 394             schemaUtils.validate([retval], [this.definition.returns]);
 395           return retval;
 396         }, apiFunction);
 397       }, this);
 398     }
 399
 400     // Setup Events
 401     if (schema.events) {
 402       $Array.forEach(schema.events, function(eventDef) {
 403         if (eventDef.name in mod) {
 404           throw new Error('Event ' + eventDef.name +
 405                           ' already defined in ' + schema.namespace);
 406         }
 407         if (!isSchemaNodeSupported(eventDef, platform, manifestVersion))
 408           return;
 409
 410         var eventName = schema.namespace + "." + eventDef.name;
 411         if (!GetAvailability(eventName).is_available ||
 412             (checkUnprivileged && !isSchemaAccessAllowed(eventDef))) {
 413           return;
 414         }
 415
 416         var options = eventDef.options || {};
 417         if (eventDef.filters && eventDef.filters.length > 0)
 418           options.supportsFilters = true;
 419
 420         var parameters = eventDef.parameters;
 421         if (this.customEvent_) {
 422           mod[eventDef.name] = new this.customEvent_(
 423               eventName, parameters, eventDef.extraParameters, options);
 424         } else {
 425           mod[eventDef.name] = new Event(eventName, parameters, options);
 426         }
 427       }, this);
 428     }
 429
 430     function addProperties(m, parentDef) {
 431       var properties = parentDef.properties;
 432       if (!properties)
 433         return;
 434
 435       forEach(properties, function(propertyName, propertyDef) {
 436         if (propertyName in m)
 437           return;  // TODO(kalman): be strict like functions/events somehow.
 438         if (!isSchemaNodeSupported(propertyDef, platform, manifestVersion))
 439           return;
 440         if (!GetAvailability(schema.namespace + "." +
 441               propertyName).is_available ||
 442             (checkUnprivileged && !isSchemaAccessAllowed(propertyDef))) {
 443           return;
 444         }
 445
 446         var value = propertyDef.value;
 447         if (value) {
 448           // Values may just have raw types as defined in the JSON, such
 449           // as "WINDOW_ID_NONE": { "value": -1 }. We handle this here.
 450           // TODO(kalman): enforce that things with a "value" property can't
 451           // define their own types.
 452           var type = propertyDef.type || typeof(value);
 453           if (type === 'integer' || type === 'number') {
 454             value = parseInt(value);
 455           } else if (type === 'boolean') {
 456             value = value === 'true';
 457           } else if (propertyDef['$ref']) {
 458             var ref = propertyDef['$ref'];
 459             var type = utils.loadTypeSchema(propertyDef['$ref'], schema);
 460             logging.CHECK(type, 'Schema for $ref type ' + ref + ' not found');
 461             var constructor = createCustomType(type);
 462             var args = value;
 463             // For an object propertyDef, |value| is an array of constructor
 464             // arguments, but we want to pass the arguments directly (i.e.
 465             // not as an array), so we have to fake calling |new| on the
 466             // constructor.
 467             value = { __proto__: constructor.prototype };
 468             $Function.apply(constructor, value, args);
 469             // Recursively add properties.
 470             addProperties(value, propertyDef);
 471           } else if (type === 'object') {
 472             // Recursively add properties.
 473             addProperties(value, propertyDef);
 474           } else if (type !== 'string') {
 475             throw new Error('NOT IMPLEMENTED (extension_api.json error): ' +
 476                 'Cannot parse values for type "' + type + '"');
 477           }
 478           m[propertyName] = value;
 479         }
 480       });
 481     };
 482
 483     addProperties(mod, schema);
 484
 485     // This generate() call is considered successful if any functions,
 486     // properties, or events were created.
 487     var success = ($Object.keys(mod).length > 0);
 488
 489     // Special case: webViewRequest is a vacuous API which just copies its
 490     // implementation from declarativeWebRequest.
 491     //
 492     // TODO(kalman): This would be unnecessary if we did these checks after the
 493     // hooks (i.e. this.runHooks_(mod)). The reason we don't is to be very
 494     // conservative with running any JS which might actually be for an API
 495     // which isn't available, but this is probably overly cautious given the
 496     // C++ is only giving us APIs which are available. FIXME.
 497     if (schema.namespace == 'webViewRequest') {
 498       success = true;
 499     }
 500
 501     // Special case: runtime.lastError is only occasionally set, so
 502     // specifically check its availability.
 503     if (schema.namespace == 'runtime' &&
 504         GetAvailability('runtime.lastError').is_available) {
 505       success = true;
 506     }
 507
 508     if (!success) {
 509       var availability = GetAvailability(schema.namespace);
 510       // If an API was available it should have been successfully generated.
 511       logging.DCHECK(!availability.is_available,
 512                      schema.namespace + ' was available but not generated');
 513       console.error('chrome.' + schema.namespace + ' is not available: ' +
 514                     availability.message);
 515       return;
 516     }
 517
 518     this.runHooks_(mod);
 519     return mod;
 520   }
 521 };
 522
 523 exports.Binding = Binding;