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