summaryrefslogtreecommitdiffstats
path: root/dom/docs/navigation
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--dom/docs/navigation/BrowsingContext.rst149
-rw-r--r--dom/docs/navigation/embedding.rst92
-rw-r--r--dom/docs/navigation/index.rst9
-rw-r--r--dom/docs/navigation/nav_replace.rst119
4 files changed, 369 insertions, 0 deletions
diff --git a/dom/docs/navigation/BrowsingContext.rst b/dom/docs/navigation/BrowsingContext.rst
new file mode 100644
index 0000000000..213b2fcce5
--- /dev/null
+++ b/dom/docs/navigation/BrowsingContext.rst
@@ -0,0 +1,149 @@
+BrowsingContext and WindowContext
+=================================
+
+The ``BrowsingContext`` is the Gecko representation of the spec-defined
+`Browsing Context`_ object.
+
+.. _Browsing Context: https://html.spec.whatwg.org/multipage/browsers.html#browsing-context
+
+
+The Browsing Context Tree
+-------------------------
+
+``BrowsingContext`` and ``WindowContext`` objects form a tree, corresponding
+to the tree of frame elements which was used to construct them.
+
+
+Example
+^^^^^^^
+
+Loading the HTML documents listed here, would end up creating a set of BrowsingContexts and WindowContexts forming the tree.
+
+.. code-block:: html
+
+ <!-- http://example.com/top.html -->
+ <iframe src="frame1.html"></iframe>
+ <iframe src="http://mozilla.org/"></iframe>
+
+ <!-- http://example.com/frame1.html -->
+ <iframe src="http://example.com/frame2.html"></iframe>
+
+ <!-- http://mozilla.org -->
+ <iframe></iframe>
+ <iframe></iframe>
+
+.. digraph:: browsingcontext
+
+ node [shape=rectangle]
+
+ "BC1" [label="BrowsingContext A"]
+ "BC2" [label="BrowsingContext B"]
+ "BC3" [label="BrowsingContext C"]
+ "BC4" [label="BrowsingContext D"]
+ "BC5" [label="BrowsingContext E"]
+ "BC6" [label="BrowsingContext F"]
+
+ "WC1" [label="WindowContext\n(http://example.com/top.html)"]
+ "WC2" [label="WindowContext\n(http://example.com/frame1.html)"]
+ "WC3" [label="WindowContext\n(http://mozilla.org)"]
+ "WC4" [label="WindowContext\n(http://example.com/frame2.html)"]
+ "WC5" [label="WindowContext\n(about:blank)"]
+ "WC6" [label="WindowContext\n(about:blank)"]
+
+ "BC1" -> "WC1";
+ "WC1" -> "BC2";
+ "WC1" -> "BC3";
+ "BC2" -> "WC2";
+ "BC3" -> "WC3";
+ "WC2" -> "BC4";
+ "BC4" -> "WC4";
+ "WC3" -> "BC5";
+ "BC5" -> "WC5";
+ "WC3" -> "BC6";
+ "BC6" -> "WC6";
+
+
+Synced Fields
+-------------
+
+WIP - In-progress documentation at `<https://wiki.mozilla.org/Project_Fission/BrowsingContext>`_.
+
+
+API Documentation
+-----------------
+
+.. cpp:class:: BrowsingContext
+
+ .. hlist::
+ :columns: 3
+
+ * `header (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/BrowsingContext.h>`_
+ * `source (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/BrowsingContext.cpp>`_
+ * `html spec <https://html.spec.whatwg.org/multipage/browsers.html#browsing-context>`_
+
+ This is a synced-context type. Instances of it will exist in every
+ "relevant" content process for the navigation.
+
+ Instances of :cpp:class:`BrowsingContext` created in the parent processes
+ will be :cpp:class:`CanonicalBrowsingContext`.
+
+ .. cpp:function:: WindowContext* GetParentWindowContext()
+
+ Get the parent ``WindowContext`` embedding this context, or ``nullptr``,
+ if this is the toplevel context.
+
+ .. cpp:function:: WindowContext* GetTopWindowContext()
+
+ Get the toplevel ``WindowContext`` embedding this context, or ``nullptr``
+ if this is the toplevel context.
+
+ This is equivalent to repeatedly calling ``GetParentWindowContext()``
+ until it returns nullptr.
+
+ .. cpp:function:: BrowsingContext* GetParent()
+
+ .. cpp:function:: BrowsingContext* Top()
+
+ .. cpp:function:: static already_AddRefed<BrowsingContext> Get(uint64_t aId)
+
+ Look up a specific ``BrowsingContext`` by it's unique ID. Callers should
+ check if the returned context has already been discarded using
+ ``IsDiscarded`` before using it.
+
+.. cpp:class:: CanonicalBrowsingContext : public BrowsingContext
+
+ .. hlist::
+ :columns: 3
+
+ * `header (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/CanonicalBrowsingContext.h>`_
+ * `source (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/CanonicalBrowsingContext.cpp>`_
+
+ When a :cpp:class:`BrowsingContext` is constructed in the parent process,
+ it is actually an instance of :cpp:class:`CanonicalBrowsingContext`.
+
+ Due to being in the parent process, more information about the context is
+ available from a ``CanonicalBrowsingContext``.
+
+.. cpp:class:: WindowContext
+
+ .. hlist::
+ :columns: 3
+
+ * `header (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/WindowContext.h>`_
+ * `source (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/WindowContext.cpp>`_
+
+.. cpp:class:: WindowGlobalParent : public WindowContext, public WindowGlobalActor, public PWindowGlobalParent
+
+ .. hlist::
+ :columns: 3
+
+ * `header (searchfox) <https://searchfox.org/mozilla-central/source/dom/ipc/WindowGlobalParent.h>`_
+ * `source (searchfox) <https://searchfox.org/mozilla-central/source/dom/ipc/WindowGlobalParent.cpp>`_
+
+.. cpp:class:: WindowGlobalChild : public WindowGlobalActor, public PWindowGlobalChild
+
+ .. hlist::
+ :columns: 3
+
+ * `header (searchfox) <https://searchfox.org/mozilla-central/source/dom/ipc/WindowGlobalChild.h>`_
+ * `source (searchfox) <https://searchfox.org/mozilla-central/source/dom/ipc/WindowGlobalChild.cpp>`_
diff --git a/dom/docs/navigation/embedding.rst b/dom/docs/navigation/embedding.rst
new file mode 100644
index 0000000000..a42aabc6f5
--- /dev/null
+++ b/dom/docs/navigation/embedding.rst
@@ -0,0 +1,92 @@
+Browsing Context Embedding
+==========================
+
+Embedder Element to nsDocShell
+------------------------------
+
+In order to render the contents of a ``BrowsingContext``, the embedding
+element needs to be able to communicate with the ``nsDocShell`` which is
+currently being used to host it's content. This is done in 3 different ways
+depending on which combination of processes is in-use.
+
+- *in-process*: The ``nsFrameLoader`` directly embeds the ``nsDocShell``.
+- *remote tab*: The parent process is the embedder, and uses a ``PBrowser``,
+ via a ``BrowserHost``. The ``BrowserChild`` actor holds the actual
+ ``nsDocShell`` alive.
+- *remote subframe*: A content process is the embedder, and uses a
+ ``PBrowserBridge``, via a ``BrowserBridgeHost`` to communicate with the
+ parent process. The parent process then uses a ``BrowserParent``, as in the
+ *remote tab* case, to communicate with the ``nsDocShell``.
+
+Diagram
+^^^^^^^
+
+.. digraph:: embedding
+
+ node [shape=rectangle]
+
+ subgraph cluster_choice {
+ color=transparent;
+ node [shape=none];
+
+ "In-Process";
+ "Remote Tab";
+ "Remote Subframe";
+ }
+
+ "nsFrameLoaderOwner" [label="nsFrameLoaderOwner\ne.g. <iframe>, <xul:browser>, <embed>"]
+
+ "nsFrameLoaderOwner" -> "nsFrameLoader";
+
+ "nsFrameLoader" -> "In-Process" [dir=none];
+ "nsFrameLoader" -> "Remote Tab" [dir=none];
+ "nsFrameLoader" -> "Remote Subframe" [dir=none];
+
+ "In-Process" -> "nsDocShell";
+ "Remote Tab" -> "BrowserHost";
+ "Remote Subframe" -> "BrowserBridgeHost";
+
+ "BrowserHost" -> "BrowserParent";
+ "BrowserParent" -> "BrowserChild" [label="PBrowser" style=dotted];
+ "BrowserChild" -> "nsDocShell";
+
+ "BrowserBridgeHost" -> "BrowserBridgeChild";
+ "BrowserBridgeChild" -> "BrowserBridgeParent" [label="PBrowserBridge", style=dotted];
+ "BrowserBridgeParent" -> "BrowserParent";
+
+nsDocShell to Document
+----------------------
+
+Embedding an individual document within a ``nsDocShell`` is done within the
+content process, which has that docshell.
+
+
+Diagram
+^^^^^^^
+
+This diagram shows the objects involved in a content process which is being
+used to host a given ``BrowsingContext``, along with rough relationships
+between them. Dotted lines represent a "current" relationship, whereas solid
+lines are a stronger lifetime relationship.
+
+.. graph:: document
+
+ node [shape=rectangle]
+
+ "BrowsingContext" -- "nsDocShell" [style=dotted];
+ "nsDocShell" -- "nsGlobalWindowOuter";
+ "nsGlobalWindowOuter" -- "nsGlobalWindowInner" [style=dotted];
+ "nsGlobalWindowInner" -- "Document" [style=dotted];
+
+ "nsDocShell" -- "nsDocumentViewer" [style=dotted];
+ "nsDocumentViewer" -- "Document";
+ "nsDocumentViewer" -- "PresShell";
+
+ "nsGlobalWindowInner" -- "WindowGlobalChild";
+ "BrowsingContext" -- "WindowContext" [style=dotted];
+ "WindowContext" -- "nsGlobalWindowInner";
+
+ subgraph cluster_synced {
+ label = "Synced Contexts";
+ "BrowsingContext" "WindowContext";
+ }
diff --git a/dom/docs/navigation/index.rst b/dom/docs/navigation/index.rst
new file mode 100644
index 0000000000..b322855eb6
--- /dev/null
+++ b/dom/docs/navigation/index.rst
@@ -0,0 +1,9 @@
+DOM Navigation
+==============
+
+.. toctree::
+ :maxdepth: 1
+
+ embedding
+ BrowsingContext
+ nav_replace
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.
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-24 16:21:17 +0000