docs/overview/gecko.rst

   1 Gecko
   2 =====
   3
   4 Gecko is Mozilla's rendering engine for the web. It is made up of HTML parsing and rendering,
   5 networking, JavaScript, IPC, DOM, OS widget abstractions and much much more. It also includes some
   6 UI components that are shared with applications built on top of Gecko such as Firefox for Desktop,
   7 Firefox for Android, and Thunderbird. As well as rendering web pages Gecko is also responsible for
   8 rendering the application's UI in some applications.
   9
  10 Networking (necko)
  11 ------------------
  12
  13 The networking engine services requests for DNS queries as well as for content hosted on web servers
  14 using either http, http/2 or http/3 protocols to retrieve it. Necko uses NSS
  15 (`Network Security Services library <https://wiki.mozilla.org/NSS>`_) for its cryptographic uses
  16 e.g. to perform secure requests using TLS.
  17
  18 :ref:`Read more <Networking>`
  19
  20 JavaScript (SpiderMonkey)
  21 -------------------------
  22
  23 The JavaScript engine is responsible for running JavaScript code both in content processes for
  24 webpages as well as the JavaScript code that makes up the bulk of the UI in applications like
  25 Firefox and Thunderbird.
  26
  27 :ref:`Read more <SpiderMonkey>`
  28
  29 JavaScript modules
  30 ##################
  31
  32 SpiderMonkey supports a proprietary type of JavaScript modules that was developed before the
  33 EcmaScript module standard and even before commonjs was popular. These modules define exports using
  34 an EXPORTED_SYMBOLS array containing a list of symbol names to be exported. This kind of module is
  35 being replaced with standard EcmaScript modules.
  36
  37 XPCOM
  38 -----
  39
  40 XPCOM (Cross-Platform Component Object Model) is Mozilla's version of Microsoft's
  41 `COM <https://en.wikipedia.org/wiki/Component_Object_Model>`_.
  42
  43 XPCOM and :ref:`WebIDL <WebIDL>` are the primary ways for our frontend to communicate with the
  44 underlying platform and to invoke methods that are implemented in native code.
  45
  46 XPCOM performs the following critical functions:
  47
  48 #. Allows creating software components with strictly defined
  49    `interfaces <https://searchfox.org/mozilla-central/search?q=&path=.idl&case=false&regexp=false>`_
  50    using :ref:`XPIDL <XPIDL>`. These components can be implemented in C++, JavaScript or Rust. They
  51    can also be invoked and manipulated in any of those languages regardless of the underlying
  52    implementation language.
  53 #. Acts as a process-global registry of named components (there are singleton "services" as well as
  54    factories for creating instances of components).
  55 #. Allows components and services to implement multiple interfaces, and to be dynamically cast to
  56    those interfaces using ``QueryInterface``.
  57
  58 If that all sounds rather abstract, that's because it is. XPCOM is one of the oldest Mozilla
  59 technologies that Firefox is still built on top of. XPCOM made a lot more sense in the late 90s when
  60 Microsoft COM was still popular and the Mozilla codebase was also being developed as a general
  61 application development platform for third-parties. There have been
  62 `long-standing efforts <https://bugzilla.mozilla.org/show_bug.cgi?id=decom>`_ to move away from or
  63 simplify XPCOM in places where its usefulness is questionable.
  64
  65 .. mermaid::
  66
  67      sequenceDiagram
  68          Caller->>Component Registry: Get service @mozilla.org/cookie-banner-service#59;1
  69          Component Registry->>nsCookieBannerService: new
  70          nsCookieBannerService-->>Component Registry: return
  71          Component Registry-->>Caller: return
  72          Caller->>nsCookieBannerService: QueryInterface(nsICookieBannerService)
  73          nsCookieBannerService-->>Caller: return
  74
  75
  76 :ref:`Read more <XPCOM>`
  77
  78 Process Separation / Fission / IPC / Actors
  79 -------------------------------------------
  80
  81 Firefox is a multi-process application. Over the lifetime of the main Firefox process, many other
  82 sub processes can be started and stopped. A full catalogue of those different processes can be found
  83 :ref:`here <Process Model>`.
  84
  85 Firefox communicates between these processes (mostly) asynchronously using the native inter-process
  86 communication mechanisms of the underlying platform. Those mechanisms and their details are hidden
  87 under cross-platform abstractions like :ref:`IPDL <IPDL: Inter-Thread and Inter-Process Message Passing>`
  88 (for native code) and :ref:`JSActors <JSActors>` (for frontend code).
  89
  90 Firefox’s initial web content process separation (this was Project "Electrolysis", sometimes
  91 shortened to “e10s”) shipped in 2016, and separated all web content into a single shared content
  92 process. Not long after that, multiple content processes were enabled, and the web content of tabs
  93 would be assigned to one of the created content processes using a round-robin scheme. In 2021, as
  94 part of the mitigations for the `Spectre <https://en.wikipedia.org/wiki/Spectre_(security_vulnerability)>`_
  95 and `Meltdown <https://en.wikipedia.org/wiki/Meltdown_(security_vulnerability)>`_ processor
  96 vulnerabilities, Firefox’s process model changed to enforce a model where each content process only
  97 loads and executes instructions from a single site (this was Project “Fission”). You can read more
  98 about the `underlying rationale and technical details about Project Fission <https://hacks.mozilla.org/2021/05/introducing-firefox-new-site-isolation-security-architecture/>`_.
  99
 100 DOM + WebIDL
 101 ------------
 102
 103 The :ref:`DOM APIs <DOM>` implement the functionality of elements in webpages and UI that is
 104 rendered by Gecko.
 105
 106 :ref:`WebIDL <WebIDL>` is a standard specification for describing the interfaces to DOM objects. As
 107 well as defining the interface for webpages Gecko also makes use of it for defining the interface to
 108 various internal components. Like XPCOM, components that implement WebIDL interfaces can be called
 109 from both C++ and JavaScript.
 110
 111 Style System (CSS)
 112 ------------------
 113
 114 The style system is responsible for parsing the document's CSS and using that to resolve a value for
 115 every CSS property on every element in the document.  This determines many characteristics of how
 116 each element will render (e.g. fonts, colors, size, layout model).
 117
 118 :ref:`Read more <Layout & CSS>`
 119
 120 Layout
 121 ------
 122
 123 The layout engine is responsible for taking the DOM and styles and generating and updating a frame
 124 tree ready for presentation to the user.
 125
 126 :ref:`Read more <Layout & CSS>`
 127
 128 Graphics
 129 --------
 130
 131 The graphics component is responsible for taking the frame tree generated by the layout engine
 132 and presenting it on screen.
 133
 134 :ref:`Read more <Graphics>`
 135
 136 Localization (Fluent)
 137 ---------------------
 138
 139 At Mozilla, localizations are managed by locale communities around the world, who are responsible
 140 for maintaining high quality linguistic and cultural adaptation of Mozilla software into over 100
 141 locales.
 142
 143 The exact process of localization management differs from project to project, but in the case of
 144 Gecko applications, the localization is primarily done via a web localization system called
 145 `Pontoon <https://pontoon.mozilla.org/>`_ and stored in HG repositories under
 146 `hg.mozilla.org/l10n-central <https://hg.mozilla.org/l10n-central/>`_.
 147
 148 :ref:`Read more <Localization>`
 149
 150 Profiles
 151 --------
 152
 153 A user profile is where Gecko stores settings, caches and any other data that must persist after the
 154 application exits. It is made up of two directories on disk. The root directory (often just called
 155 the profile directory) is where settings are stored. The local directory is for caches or any other
 156 data that is temporary and will be rebuilt with no perceived loss to the user should it be
 157 unavailable. These two directories can just be the same directory on disk. In an enterprise
 158 environment or other situation where a user often switches between computers the root directory is
 159 intended to be in a location on the network accessible to all computers while the local directory
 160 can be local to the computer.
 161
 162 The profile service maintains a database of named user profiles that can be selected either from the
 163 command line or through a basic user interface. Additionally command line arguments exist that will
 164 run an application using any given directory for the user profile.
 165
 166 Preferences
 167 -----------
 168
 169 The preferences service is a basic key value store for a user's settings. The keys are simple
 170 strings and although are often considered to be hierarchical with parts separated by periods
 171 internally everything is just held as flat lists. Preference values can be strings, integers or
 172 boolean.
 173
 174 :ref:`Read more <libpref>`
 175
 176 Observer Service
 177 ----------------
 178
 179 The Observer Service (nsIObserverService) is a process-global XPCOM service that acts as a general
 180 message bus implementing the `publish-subscribe pattern <https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern>`_.
 181 Components implementing nsIObserver (or simple functions in JavaScript) can be registered with the
 182 observer service to be notified when particular "topics" (topics are just developer-defined strings)
 183 have occurred. This is particularly useful for creating a dependency between two components without
 184 tightly coupling them.
 185
 186 For example, suppose there is a mechanism that clears a user's browsing history from the disk and
 187 memory. At the end of that process, it might tell the observer service to notify on a topic like
 188 "browser-clear-history". An observer registered for that topic might use that signal to know to
 189 clear some of its caches, which might also contain browsing history.
 190
 191 Principals / Security model
 192 ---------------------------
 193
 194 Whenever Firefox on Desktop or Android fetches a resource from the web, Firefox performs a variety
 195 of web security checks. Most prominently the `Same-origin Policy <https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy>`_
 196 to ensure web pages can not harm end users by performing malicious actions, like e.g. accessing the
 197 local file system. All web related security checks within Firefox are evaluated based on the
 198 security concept of a Principal, which slightly simplified represents an origin. More precisely,
 199 Firefox captures the security context using one of the following four types of Principals:
 200
 201 * Content-Principal, which reflects the Security Context of web content (origin). For example, when
 202   visiting https://example.com a Content-Principal of https://example.com reflects the security
 203   context of that origin and passes if scheme, host and port match.
 204 * Null-Principal, which reflects a sandboxed (or least privilege) Security Context. For example,
 205   when loading an iframe with a sandbox attribute Firefox internally generates a Null-Principal to
 206   reflect that security context. A Null-Principal is only same-origin with itself.
 207 * System-Principal, which reflects the security context of browser chrome-code and passes all
 208   security checks. Important: Never use SystemPrincipal if the URI to be loaded can be influenced by
 209   web content.
 210 * Expanded-Principal, which is a list of principals to match the security needs for Content Scripts
 211   in Firefox Extensions.
 212
 213 Whenever Firefox starts to load a resource (e.g. script, css, image) then security relevant meta
 214 information including `nsIPrincipal <https://searchfox.org/mozilla-central/source/caps/nsIPrincipal.idl>`_
 215 is attached to the `nsILoadInfo <https://searchfox.org/mozilla-central/source/netwerk/base/nsILoadInfo.idl>`_.
 216 This load context providing object remains attached to the resource load (
 217 `nsIChannel <https://searchfox.org/mozilla-central/source/netwerk/base/nsIChannel.idl>`_) throughout
 218 the entire loading life cycle of a resource and allows Firefox to provide the same security
 219 guarantees even if the resource load encounters a server side redirect.
 220
 221 Please find all the details about the Security Model of Firefox by reading the blog posts:
 222 Understanding Web Security Checks in Firefox (
 223 `Part 1 <https://blog.mozilla.org/attack-and-defense/2020/06/10/understanding-web-security-checks-in-firefox-part-1/>`_ &
 224 `Part 2 <https://blog.mozilla.org/attack-and-defense/2020/08/05/understanding-web-security-checks-in-firefox-part-2/>`_)
 225 and `Enforcing Content Security By Default within Firefox <https://blog.mozilla.org/security/2016/11/10/enforcing-content-security-by-default-within-firefox/>`_.
 226
 227 Chrome Protocol
 228 ---------------
 229
 230 The chrome protocol is an internal protocol used to reference files that ship as part of the
 231 application. It is of the form ``chrome://<package>/<provider>/…`` where provider is one of content,
 232 skin or locale. The majority of files referenced by the chrome protocol are stored in the omni.ja
 233 files which are generated from :ref:`JAR manifest files <JAR Manifests>` at build time.
 234 :ref:`Chrome manifest files <Chrome Registration>` are used to register where in the jar files
 235 different packages are stored.
 236
 237 Resource Protocol
 238 -----------------
 239
 240 The resource protocol is another internal protocol that can reference files that ship as part of the
 241 application. Strictly speaking it is simply a mapped, all urls of the form ``resource://<package>/…``
 242 are mapped to ``<new-uri>/…``. The mappings are generally defined using the resource instruction in
 243 :ref:`chrome manifest files <chrome_manifest_resource>` however can also be defined at runtime and
 244 some hardcoded mappings. Common examples include:
 245
 246 * ``resource://gre/…`` which references files in the gecko omni.ja file.
 247 * ``resource://app/…``, often simplified as ``resource:///…`` which references files in the application
 248   omni.ja file.
 249
 250 About pages/protocol
 251 --------------------
 252
 253 The ``about`` protocol allows for binding short human-readable urls to internal content to be
 254 displayed in the content area. For the most part each about page is simply a simpler name for
 255 content in the chrome or resource protocols. For example the page ``about:processes`` simply loads
 256 ``chrome://global/content/aboutProcesses.html``. About pages are registered in the
 257 `global <https://searchfox.org/mozilla-central/source/docshell/base/nsAboutRedirector.cpp>`_ and
 258 `desktop <https://searchfox.org/mozilla-central/source/browser/components/about/AboutRedirector.cpp>`_
 259 redirector components.
 260
 261 Toolkit
 262 -------
 263
 264 Toolkit consists of components that can be shared across multiple applications built on top of
 265 Gecko. For example, much of our WebExtensions API surfaces are implemented in toolkit, as several of
 266 these APIs are shared between both Firefox, Firefox for Android, and in some cases Thunderbird.
 267
 268 :ref:`Read more <Toolkit>`
 269
 270 Linting / building / testing / developer workflow
 271 -------------------------------------------------
 272
 273 Set-up the build environment using the :ref:`contributor's quick reference <Firefox Contributors' Quick Reference>`.
 274
 275 Make yourself aware of the :ref:`Linting set-up <Linting>`, in particular how to run
 276 :ref:`linters and add hooks to automatically run the linters on commit <Running Linters Locally>`.
 277 Additionally, make sure you set-up your editor with appropriate settings for linters. For VS Code,
 278 these are set up automatically, as :ref:`per the documentation <Visual Studio Code>`.
 279
 280 For front-end work, ESLint and Prettier are the linters you'll use the most, see the
 281 :ref:`section on ESLint <ESLint>` for details of both of those, which also has
 282 :ref:`an FAQ <eslint_common_issues>`.
 283
 284 Details about :ref:`automated tests may be found here <Automated Testing>`. The most commonly used
 285 tests are :ref:`XPCShell <XPCShell tests>` for testing backend components,
 286 :ref:`Browser Chrome Tests <Browser chrome mochitests>` for testing the frontend UI and
 287 :ref:`Web Platform Tests <web-platform-tests>` for testing web APIs.
 288
 289 WebExtensions
 290 --------------
 291
 292 The WebExtensions APIs allow extensions to interact with the rest of the browser.
 293
 294 :ref:`Read more <WebExtensions API Development>`