1Background 2========== 3 4WebExtensions run in a sandboxed environment much like regular web content. 5The purpose of extensions is to enhance the browser in a way that 6regular content cannot -- WebExtensions APIs bridge this gap by exposing 7browser features to extensions in a way preserves safety, reliability, 8and performance. 9The implementation of a WebExtension API runs with 10`chrome privileges <https://developer.mozilla.org/en-US/docs/Security/Firefox_Security_Basics_For_Developers>`_. 11Browser internals are accessed using 12`XPCOM <https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM>`_ 13or `ChromeOnly WebIDL features <https://developer.mozilla.org/en-US/docs/Mozilla/WebIDL_bindings#ChromeOnly>`_. 14 15The rest of this documentation covers how API implementations interact 16with the implementation of WebExtensions. 17To expose some browser feature to WebExtensions, the first step is 18to design the API. Some high-level principles for API design 19are documented on the Mozilla wiki: 20 21- `Vision for WebExtensions <https://wiki.mozilla.org/WebExtensions/Vision>`_ 22- `API Policies <https://wiki.mozilla.org/WebExtensions/policy>`_ 23- `Process for creating new APIs <https://wiki.mozilla.org/WebExtensions/NewAPIs>`_ 24 25Javascript APIs 26--------------- 27Many WebExtension APIs are accessed directly from extensions through 28Javascript. Functions are the most common type of object to expose, 29though some extensions expose properties of primitive Javascript types 30(e.g., constants). 31Regardless of the exact method by which something is exposed, 32there are a few important considerations when designing part of an API 33that is accessible from Javascript: 34 35- **Namespace**: 36 Everything provided to extensions is exposed as part of a global object 37 called ``browser``. For compatibility with Google Chrome, many of these 38 features are also exposed on a global object called ``chrome``. 39 Functions and other objects are not exposed directly as properties on 40 ``browser``, they are organized into *namespaces*, which appear as 41 properties on ``browser``. For example, the 42 `tabs API <https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/tabs>`_ 43 uses a namespace called ``tabs``, so all its functions and other 44 properties appear on the object ``browser.tabs``. 45 For a new API that provides features via Javascript, the usual practice 46 is to create a new namespace with a concise but descriptive name. 47 48- **Environments**: 49 There are several different types of Javascript environments in which 50 extension code can execute: extension pages, content scripts, proxy 51 scripts, and devtools pages. 52 Extension pages include the background page, popups, and content pages 53 accessed via |getURL|_. 54 When creating a new Javascript feature the designer must choose 55 in which of these environments the feature will be available. 56 Most Javascript features are available in extension pages, 57 other environments have limited sets of API features available. 58 59.. |getURL| replace:: ``browser.runtime.getURL()`` 60.. _getURL: https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/runtime/getURL 61 62- **Permissions**: 63 Many Javascript features are only present for extensions that 64 include an appropriate permission in the manifest. 65 The guidelines for when an API feature requires a permission are 66 described in (*citation needed*). 67 68The specific types of features that can be exposed via Javascript are: 69 70- **Functions**: 71 A function callable from Javascript is perhaps the most commonly 72 used feature in WebExtension APIs. 73 New API functions are asynchronous, returning a 74 `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_. Even functions that do not return a result 75 use Promises so that errors can be indicated asynchronously 76 via a rejected Promise as opposed to a synchronously thrown Error. 77 This is due to the fact that extensions run in a child process and 78 many API functions require communication with the main process. 79 If an API function that needs to communicate in this way returned a 80 synchronous result, then all Javascript execution in the child 81 process would need to be paused until a response from the main process 82 was received. Even if a function could be implemented synchronously 83 within a child process, the standard practice is to make it 84 asynchronous so as not to constrain the implementation of the underlying 85 browser feature and make it impossible to move functionality out of the 86 child process. 87 Another consequence of functions using inter-process communication is 88 that the parameters to a function and its return value must all be 89 simple data types that can be sent between processes using the 90 `structured clone algorithm <https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm>`_. 91 92- **Events**: 93 Events complement functions (which allow an extension to call into 94 an API) by allowing an event within the browser to invoke a callback 95 in the extension. 96 Any time an API requires an extension to pass a callback function that 97 gets invoked some arbitrary number of times, that API method should be 98 defined as an event. 99 100Manifest Keys 101------------- 102In addition to providing functionality via Javascript, WebExtension APIs 103can also take actions based on the contents of particular properties 104in an extension's manifest (or even just the presence of a particular 105property). 106Manifest entries are used for features in which an extension specifies 107some static information that is used when an extension is installed or 108when it starts up (i.e., before it has the chance to run any code to use 109a Javascript API). 110An API may handle a manifest key and implement Javscript functionality, 111see the 112`browser action <https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/browserAction>`_ 113API for an example. 114 115Other Considerations 116-------------------- 117In addition to the guidelines outlined above, 118there are some other considerations when designing and implementing 119a WebExtension API: 120 121- **Cleanup**: A badly written WebExtension should not be able to permanently 122 leak any resources. In particular, any action from an extension that 123 causes a resource to be allocated within the browser should be 124 automatically cleaned up when the extension is disabled or uninstalled. 125 This is described in more detail in the section on :ref:`lifecycle`. 126 127- **Performance**: A new WebExtension API should not add any new overhead 128 to the browser when the API is not used. That is, the implementation 129 of the API should not be loaded at all unless it is actively used by 130 an extension. In addition, initialization should be delayed when 131 possible -- extensions ared started relatively early in the browser 132 startup process so any unnecessary work done during extension startup 133 contributes directly to sluggish browser startup. 134 135