diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/overview/gecko.rst | 294 |
1 files changed, 294 insertions, 0 deletions
diff --git a/docs/overview/gecko.rst b/docs/overview/gecko.rst new file mode 100644 index 0000000000..eb28ab1f0e --- /dev/null +++ b/docs/overview/gecko.rst @@ -0,0 +1,294 @@ +Gecko +===== + +Gecko is Mozilla's rendering engine for the web. It is made up of HTML parsing and rendering, +networking, JavaScript, IPC, DOM, OS widget abstractions and much much more. It also includes some +UI components that are shared with applications built on top of Gecko such as Firefox for Desktop, +Firefox for Android, and Thunderbird. As well as rendering web pages Gecko is also responsible for +rendering the application's UI in some applications. + +Networking (necko) +------------------ + +The networking engine services requests for DNS queries as well as for content hosted on web servers +using either http, http/2 or http/3 protocols to retrieve it. Necko uses NSS +(`Network Security Services library <https://wiki.mozilla.org/NSS>`_) for its cryptographic uses +e.g. to perform secure requests using TLS. + +:ref:`Read more <Networking>` + +JavaScript (SpiderMonkey) +------------------------- + +The JavaScript engine is responsible for running JavaScript code both in content processes for +webpages as well as the JavaScript code that makes up the bulk of the UI in applications like +Firefox and Thunderbird. + +:ref:`Read more <SpiderMonkey>` + +JavaScript modules +################## + +SpiderMonkey supports a proprietary type of JavaScript modules that was developed before the +EcmaScript module standard and even before commonjs was popular. These modules define exports using +an EXPORTED_SYMBOLS array containing a list of symbol names to be exported. This kind of module is +being replaced with standard EcmaScript modules. + +XPCOM +----- + +XPCOM (Cross-Platform Component Object Model) is Mozilla's version of Microsoft's +`COM <https://en.wikipedia.org/wiki/Component_Object_Model>`_. + +XPCOM and :ref:`WebIDL <WebIDL>` are the primary ways for our frontend to communicate with the +underlying platform and to invoke methods that are implemented in native code. + +XPCOM performs the following critical functions: + +#. Allows creating software components with strictly defined + `interfaces <https://searchfox.org/mozilla-central/search?q=&path=.idl&case=false®exp=false>`_ + using :ref:`XPIDL <XPIDL>`. These components can be implemented in C++, JavaScript or Rust. They + can also be invoked and manipulated in any of those languages regardless of the underlying + implementation language. +#. Acts as a process-global registry of named components (there are singleton "services" as well as + factories for creating instances of components). +#. Allows components and services to implement multiple interfaces, and to be dynamically cast to + those interfaces using ``QueryInterface``. + +If that all sounds rather abstract, that's because it is. XPCOM is one of the oldest Mozilla +technologies that Firefox is still built on top of. XPCOM made a lot more sense in the late 90s when +Microsoft COM was still popular and the Mozilla codebase was also being developed as a general +application development platform for third-parties. There have been +`long-standing efforts <https://bugzilla.mozilla.org/show_bug.cgi?id=decom>`_ to move away from or +simplify XPCOM in places where its usefulness is questionable. + +.. mermaid:: + + sequenceDiagram + Caller->>Component Registry: Get service @mozilla.org/cookie-banner-service#59;1 + Component Registry->>nsCookieBannerService: new + nsCookieBannerService-->>Component Registry: return + Component Registry-->>Caller: return + Caller->>nsCookieBannerService: QueryInterface(nsICookieBannerService) + nsCookieBannerService-->>Caller: return + + +:ref:`Read more <XPCOM>` + +Process Separation / Fission / IPC / Actors +------------------------------------------- + +Firefox is a multi-process application. Over the lifetime of the main Firefox process, many other +sub processes can be started and stopped. A full catalogue of those different processes can be found +:ref:`here <Process Model>`. + +Firefox communicates between these processes (mostly) asynchronously using the native inter-process +communication mechanisms of the underlying platform. Those mechanisms and their details are hidden +under cross-platform abstractions like :ref:`IPDL <IPDL: Inter-Thread and Inter-Process Message Passing>` +(for native code) and :ref:`JSActors <JSActors>` (for frontend code). + +Firefox’s initial web content process separation (this was Project "Electrolysis", sometimes +shortened to “e10s”) shipped in 2016, and separated all web content into a single shared content +process. Not long after that, multiple content processes were enabled, and the web content of tabs +would be assigned to one of the created content processes using a round-robin scheme. In 2021, as +part of the mitigations for the `Spectre <https://en.wikipedia.org/wiki/Spectre_(security_vulnerability)>`_ +and `Meltdown <https://en.wikipedia.org/wiki/Meltdown_(security_vulnerability)>`_ processor +vulnerabilities, Firefox’s process model changed to enforce a model where each content process only +loads and executes instructions from a single site (this was Project “Fission”). You can read more +about the `underlying rationale and technical details about Project Fission <https://hacks.mozilla.org/2021/05/introducing-firefox-new-site-isolation-security-architecture/>`_. + +DOM + WebIDL +------------ + +The :ref:`DOM APIs <DOM>` implement the functionality of elements in webpages and UI that is +rendered by Gecko. + +:ref:`WebIDL <WebIDL>` is a standard specification for describing the interfaces to DOM objects. As +well as defining the interface for webpages Gecko also makes use of it for defining the interface to +various internal components. Like XPCOM, components that implement WebIDL interfaces can be called +from both C++ and JavaScript. + +Style System (CSS) +------------------ + +The style system is responsible for parsing the document's CSS and using that to resolve a value for +every CSS property on every element in the document. This determines many characteristics of how +each element will render (e.g. fonts, colors, size, layout model). + +:ref:`Read more <Layout & CSS>` + +Layout +------ + +The layout engine is responsible for taking the DOM and styles and generating and updating a frame +tree ready for presentation to the user. + +:ref:`Read more <Layout & CSS>` + +Graphics +-------- + +The graphics component is responsible for taking the frame tree generated by the layout engine +and presenting it on screen. + +:ref:`Read more <Graphics>` + +Localization (Fluent) +--------------------- + +At Mozilla, localizations are managed by locale communities around the world, who are responsible +for maintaining high quality linguistic and cultural adaptation of Mozilla software into over 100 +locales. + +The exact process of localization management differs from project to project, but in the case of +Gecko applications, the localization is primarily done via a web localization system called +`Pontoon <https://pontoon.mozilla.org/>`_ and stored in HG repositories under +`hg.mozilla.org/l10n-central <https://hg.mozilla.org/l10n-central/>`_. + +:ref:`Read more <Localization>` + +Profiles +-------- + +A user profile is where Gecko stores settings, caches and any other data that must persist after the +application exits. It is made up of two directories on disk. The root directory (often just called +the profile directory) is where settings are stored. The local directory is for caches or any other +data that is temporary and will be rebuilt with no perceived loss to the user should it be +unavailable. These two directories can just be the same directory on disk. In an enterprise +environment or other situation where a user often switches between computers the root directory is +intended to be in a location on the network accessible to all computers while the local directory +can be local to the computer. + +The profile service maintains a database of named user profiles that can be selected either from the +command line or through a basic user interface. Additionally command line arguments exist that will +run an application using any given directory for the user profile. + +Preferences +----------- + +The preferences service is a basic key value store for a user's settings. The keys are simple +strings and although are often considered to be hierarchical with parts separated by periods +internally everything is just held as flat lists. Preference values can be strings, integers or +boolean. + +:ref:`Read more <libpref>` + +Observer Service +---------------- + +The Observer Service (nsIObserverService) is a process-global XPCOM service that acts as a general +message bus implementing the `publish-subscribe pattern <https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern>`_. +Components implementing nsIObserver (or simple functions in JavaScript) can be registered with the +observer service to be notified when particular "topics" (topics are just developer-defined strings) +have occurred. This is particularly useful for creating a dependency between two components without +tightly coupling them. + +For example, suppose there is a mechanism that clears a user's browsing history from the disk and +memory. At the end of that process, it might tell the observer service to notify on a topic like +"browser-clear-history". An observer registered for that topic might use that signal to know to +clear some of its caches, which might also contain browsing history. + +Principals / Security model +--------------------------- + +Whenever Firefox on Desktop or Android fetches a resource from the web, Firefox performs a variety +of web security checks. Most prominently the `Same-origin Policy <https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy>`_ +to ensure web pages can not harm end users by performing malicious actions, like e.g. accessing the +local file system. All web related security checks within Firefox are evaluated based on the +security concept of a Principal, which slightly simplified represents an origin. More precisely, +Firefox captures the security context using one of the following four types of Principals: + +* Content-Principal, which reflects the Security Context of web content (origin). For example, when + visiting https://example.com a Content-Principal of https://example.com reflects the security + context of that origin and passes if scheme, host and port match. +* Null-Principal, which reflects a sandboxed (or least privilege) Security Context. For example, + when loading an iframe with a sandbox attribute Firefox internally generates a Null-Principal to + reflect that security context. A Null-Principal is only same-origin with itself. +* System-Principal, which reflects the security context of browser chrome-code and passes all + security checks. Important: Never use SystemPrincipal if the URI to be loaded can be influenced by + web content. +* Expanded-Principal, which is a list of principals to match the security needs for Content Scripts + in Firefox Extensions. + +Whenever Firefox starts to load a resource (e.g. script, css, image) then security relevant meta +information including `nsIPrincipal <https://searchfox.org/mozilla-central/source/caps/nsIPrincipal.idl>`_ +is attached to the `nsILoadInfo <https://searchfox.org/mozilla-central/source/netwerk/base/nsILoadInfo.idl>`_. +This load context providing object remains attached to the resource load ( +`nsIChannel <https://searchfox.org/mozilla-central/source/netwerk/base/nsIChannel.idl>`_) throughout +the entire loading life cycle of a resource and allows Firefox to provide the same security +guarantees even if the resource load encounters a server side redirect. + +Please find all the details about the Security Model of Firefox by reading the blog posts: +Understanding Web Security Checks in Firefox ( +`Part 1 <https://blog.mozilla.org/attack-and-defense/2020/06/10/understanding-web-security-checks-in-firefox-part-1/>`_ & +`Part 2 <https://blog.mozilla.org/attack-and-defense/2020/08/05/understanding-web-security-checks-in-firefox-part-2/>`_) +and `Enforcing Content Security By Default within Firefox <https://blog.mozilla.org/security/2016/11/10/enforcing-content-security-by-default-within-firefox/>`_. + +Chrome Protocol +--------------- + +The chrome protocol is an internal protocol used to reference files that ship as part of the +application. It is of the form ``chrome://<package>/<provider>/…`` where provider is one of content, +skin or locale. The majority of files referenced by the chrome protocol are stored in the omni.ja +files which are generated from :ref:`JAR manifest files <JAR Manifests>` at build time. +:ref:`Chrome manifest files <Chrome Registration>` are used to register where in the jar files +different packages are stored. + +Resource Protocol +----------------- + +The resource protocol is another internal protocol that can reference files that ship as part of the +application. Strictly speaking it is simply a mapped, all urls of the form ``resource://<package>/…`` +are mapped to ``<new-uri>/…``. The mappings are generally defined using the resource instruction in +:ref:`chrome manifest files <chrome_manifest_resource>` however can also be defined at runtime and +some hardcoded mappings. Common examples include: + +* ``resource://gre/…`` which references files in the gecko omni.ja file. +* ``resource://app/…``, often simplified as ``resource:///…`` which references files in the application + omni.ja file. + +About pages/protocol +-------------------- + +The ``about`` protocol allows for binding short human-readable urls to internal content to be +displayed in the content area. For the most part each about page is simply a simpler name for +content in the chrome or resource protocols. For example the page ``about:processes`` simply loads +``chrome://global/content/aboutProcesses.html``. About pages are registered in the +`global <https://searchfox.org/mozilla-central/source/docshell/base/nsAboutRedirector.cpp>`_ and +`desktop <https://searchfox.org/mozilla-central/source/browser/components/about/AboutRedirector.cpp>`_ +redirector components. + +Toolkit +------- + +Toolkit consists of components that can be shared across multiple applications built on top of +Gecko. For example, much of our WebExtensions API surfaces are implemented in toolkit, as several of +these APIs are shared between both Firefox, Firefox for Android, and in some cases Thunderbird. + +:ref:`Read more <Toolkit>` + +Linting / building / testing / developer workflow +------------------------------------------------- + +Set-up the build environment using the :ref:`contributor's quick reference <Firefox Contributors' Quick Reference>`. + +Make yourself aware of the :ref:`Linting set-up <Linting>`, in particular how to run +:ref:`linters and add hooks to automatically run the linters on commit <Running Linters Locally>`. +Additionally, make sure you set-up your editor with appropriate settings for linters. For VS Code, +these are set up automatically, as :ref:`per the documentation <Visual Studio Code>`. + +For front-end work, ESLint and Prettier are the linters you'll use the most, see the +:ref:`section on ESLint <ESLint>` for details of both of those, which also has +:ref:`an FAQ <eslint_common_issues>`. + +Details about :ref:`automated tests may be found here <Automated Testing>`. The most commonly used +tests are :ref:`XPCShell <XPCShell tests>` for testing backend components, +:ref:`Browser Chrome Tests <Browser chrome mochitests>` for testing the frontend UI and +:ref:`Web Platform Tests <web-platform-tests>` for testing web APIs. + +WebExtensions +-------------- + +The WebExtensions APIs allow extensions to interact with the rest of the browser. + +:ref:`Read more <WebExtensions API Development>` |