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