Adding upstream version 1:115.7.0.upstream/1%115.7.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 119 insertions, 0 deletions

diff --git a/dom/docs/navigation/nav_replace.rst b/dom/docs/navigation/nav_replace.rst
new file mode 100644
index 0000000000..6e2c710e28
--- /dev/null
+++ b/dom/docs/navigation/nav_replace.rst
@@ -0,0 +1,119 @@
+Objects Replaced by Navigations
+===============================
+
+There are 3 major types of navigations, each of which can cause different
+objects to be replaced. The general rules look something like this:
+
+.. csv-table:: objects replaced or preserved across navigations
+   :header: "Class/Id", ":ref:`in-process navigations <in-process navigations>`", ":ref:`cross-process navigations <cross-process navigations>`", ":ref:`cross-group navigations <cross-group navigations>`"
+
+   "BrowserId [#bid]_", |preserve|, |preserve|, |preserve|
+   "BrowsingContextWebProgress", |preserve|, |preserve|, |preserve|
+   "BrowsingContextGroup", |preserve|, |preserve|, |replace|
+   "BrowsingContext", |preserve|, |preserve|, |replace|
+   "nsFrameLoader", |preserve|, |replace|, |replace|
+   "RemoteBrowser", |preserve|, |replace|, |replace|
+   "Browser{Parent,Child}", |preserve|, |replace|, |replace|
+   "nsDocShell", |preserve|, |replace|, |replace|
+   "nsGlobalWindowOuter", |preserve|, |replace|, |replace|
+   "nsGlobalWindowInner", "|replace| [#inner]_", |replace|, |replace|
+   "WindowContext", "|replace| [#inner]_", |replace|, |replace|
+   "WindowGlobal{Parent,Child}", "|replace| [#inner]_", |replace|, |replace|
+   "Document", "|replace|", |replace|, |replace|
+
+
+.. |replace| replace:: ❌ replaced
+.. |preserve| replace:: ✔️ preserved
+
+.. [#bid]
+
+   The BrowserId is a unique ID on each ``BrowsingContext`` object, obtained
+   using ``GetBrowserId``, not a class. This ID will persist even when a
+   ``BrowsingContext`` is replaced (e.g. due to
+   ``Cross-Origin-Opener-Policy``).
+
+.. [#inner]
+
+   When navigating from the initial ``about:blank`` document to a same-origin
+   document, the same ``nsGlobalWindowInner``, ``WindowContext`` and
+   ``WindowGlobal{Parent,Child}`` may be used. This initial ``about:blank``
+   document is the one created when synchronously accessing a newly-created
+   pop-up window from ``window.open``, or a newly-created document in an
+   ``<iframe>``.
+
+Types of Navigations
+--------------------
+
+.. _in-process navigations:
+
+in-process navigations
+^^^^^^^^^^^^^^^^^^^^^^
+
+An in-process navigation is the traditional type of navigation, and the most
+common type of navigation when :ref:`Fission` is not enabled.
+
+These navigations are used when no process switching or BrowsingContext
+replacement is required, which includes most navigations with Fission
+disabled, and most same site-origin navigations when Fission is enabled.
+
+.. _cross-process navigations:
+
+cross-process navigations
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A cross-process navigation is used when a navigation requires a process
+switch to occur, and no BrowsingContext replacement is required. This is a
+common type of load when :ref:`Fission` is enabled, though it is also used
+for navigations to and from special URLs like ``file://`` URIs when
+Fission is disabled.
+
+These process changes are triggered by ``DocumentLoadListener`` when it
+determines that a process switch is required. See that class's documentation
+for more details.
+
+.. _cross-group navigations:
+
+cross-group navigations
+^^^^^^^^^^^^^^^^^^^^^^^
+
+A cross-group navigation is used when the navigation's `response requires
+a browsing context group switch
+<https://html.spec.whatwg.org/multipage/origin.html#browsing-context-group-switches-due-to-cross-origin-opener-policy>`_.
+
+These types of switches may or may not cause the process to change, but will
+finish within a different ``BrowsingContextGroup`` than they started with.
+Like :ref:`cross-process navigations`, these navigations are triggered using
+the process switching logic in ``DocumentLoadListener``.
+
+As the parent of a content browsing context cannot change due to a navigation,
+only toplevel content browsing contexts can cross-group navigate. Navigations in
+chrome browsing contexts [#chromebc]_ or content subframes only experience
+either in-process or cross-process navigations.
+
+As of the time of this writing, we currently trigger a cross-group navigation
+in the following circumstances, though this may change in the future:
+
+- If the `Cross-Origin-Opener-Policy
+  <https://html.spec.whatwg.org/multipage/origin.html#the-cross-origin-opener-policy-header>`_
+  header is specified, and a mismatch is detected.
+- When switching processes between the parent process, and a content process.
+- When loading an extension document in a toplevel browsing context.
+- When navigating away from a preloaded ``about:newtab`` document.
+- When putting a ``BrowsingContext`` into BFCache for the session history
+  in-parent BFCache implementation. This will happen on most toplevel
+  navigations without opener relationships when the ``fission.bfcacheInParent``
+  pref is enabled.
+
+State which needs to be saved over cross-group navigations on
+``BrowsingContext`` instances is copied in the
+``CanonicalBrowsingContext::ReplacedBy`` method.
+
+.. [#chromebc]
+
+   A chrome browsing context does **not** refer to pages with the system
+   principal loaded in the content area such as ``about:preferences``.
+   Chrome browsing contexts are generally used as the root context in a chrome
+   window, such where ``browser.xhtml`` is loaded for a browser window.
+
+   All chrome browsing contexts exclusively load in the parent process and
+   cannot process switch when navigating.