nav_replace.rst (5284B)
1 Objects Replaced by Navigations 2 =============================== 3 4 There are 3 major types of navigations, each of which can cause different 5 objects to be replaced. The general rules look something like this: 6 7 .. csv-table:: objects replaced or preserved across navigations 8 :header: "Class/Id", ":ref:`in-process navigations <in-process navigations>`", ":ref:`cross-process navigations <cross-process navigations>`", ":ref:`cross-group navigations <cross-group navigations>`" 9 10 "BrowserId [#bid]_", |preserve|, |preserve|, |preserve| 11 "BrowsingContextWebProgress", |preserve|, |preserve|, |preserve| 12 "BrowsingContextGroup", |preserve|, |preserve|, |replace| 13 "BrowsingContext", |preserve|, |preserve|, |replace| 14 "nsFrameLoader", |preserve|, |replace|, |replace| 15 "RemoteBrowser", |preserve|, |replace|, |replace| 16 "Browser{Parent,Child}", |preserve|, |replace|, |replace| 17 "nsDocShell", |preserve|, |replace|, |replace| 18 "nsGlobalWindowOuter", |preserve|, |replace|, |replace| 19 "nsGlobalWindowInner", "|replace| [#inner]_", |replace|, |replace| 20 "WindowContext", "|replace| [#inner]_", |replace|, |replace| 21 "WindowGlobal{Parent,Child}", "|replace| [#inner]_", |replace|, |replace| 22 "Document", "|replace|", |replace|, |replace| 23 24 25 .. |replace| replace:: ❌ replaced 26 .. |preserve| replace:: ✔️ preserved 27 28 .. [#bid] 29 30 The BrowserId is a unique ID on each ``BrowsingContext`` object, obtained 31 using ``GetBrowserId``, not a class. This ID will persist even when a 32 ``BrowsingContext`` is replaced (e.g. due to 33 ``Cross-Origin-Opener-Policy``). 34 35 .. [#inner] 36 37 When navigating from the initial ``about:blank`` document to a same-origin 38 document, the same ``nsGlobalWindowInner``, ``WindowContext`` and 39 ``WindowGlobal{Parent,Child}`` may be used. This initial ``about:blank`` 40 document is the one created when synchronously accessing a newly-created 41 pop-up window from ``window.open``, or a newly-created document in an 42 ``<iframe>``. 43 44 Types of Navigations 45 -------------------- 46 47 .. _in-process navigations: 48 49 in-process navigations 50 ^^^^^^^^^^^^^^^^^^^^^^ 51 52 An in-process navigation is the traditional type of navigation, and the most 53 common type of navigation when :ref:`Fission` is not enabled. 54 55 These navigations are used when no process switching or BrowsingContext 56 replacement is required, which includes most navigations with Fission 57 disabled, and most same site-origin navigations when Fission is enabled. 58 59 .. _cross-process navigations: 60 61 cross-process navigations 62 ^^^^^^^^^^^^^^^^^^^^^^^^^ 63 64 A cross-process navigation is used when a navigation requires a process 65 switch to occur, and no BrowsingContext replacement is required. This is a 66 common type of load when :ref:`Fission` is enabled, though it is also used 67 for navigations to and from special URLs like ``file://`` URIs when 68 Fission is disabled. 69 70 These process changes are triggered by ``DocumentLoadListener`` when it 71 determines that a process switch is required. See that class's documentation 72 for more details. 73 74 .. _cross-group navigations: 75 76 cross-group navigations 77 ^^^^^^^^^^^^^^^^^^^^^^^ 78 79 A cross-group navigation is used when the navigation's `response requires 80 a browsing context group switch 81 <https://html.spec.whatwg.org/multipage/origin.html#browsing-context-group-switches-due-to-cross-origin-opener-policy>`_. 82 83 These types of switches may or may not cause the process to change, but will 84 finish within a different ``BrowsingContextGroup`` than they started with. 85 Like :ref:`cross-process navigations`, these navigations are triggered using 86 the process switching logic in ``DocumentLoadListener``. 87 88 As the parent of a content browsing context cannot change due to a navigation, 89 only toplevel content browsing contexts can cross-group navigate. Navigations in 90 chrome browsing contexts [#chromebc]_ or content subframes only experience 91 either in-process or cross-process navigations. 92 93 As of the time of this writing, we currently trigger a cross-group navigation 94 in the following circumstances, though this may change in the future: 95 96 - If the `Cross-Origin-Opener-Policy 97 <https://html.spec.whatwg.org/multipage/origin.html#the-cross-origin-opener-policy-header>`_ 98 header is specified, and a mismatch is detected. 99 - When switching processes between the parent process, and a content process. 100 - When loading an extension document in a toplevel browsing context. 101 - When navigating away from a preloaded ``about:newtab`` document. 102 - When putting a ``BrowsingContext`` into BFCache for the session history 103 in-parent BFCache implementation. This will happen on most toplevel 104 navigations without opener relationships when the ``fission.bfcacheInParent`` 105 pref is enabled. 106 107 State which needs to be saved over cross-group navigations on 108 ``BrowsingContext`` instances is copied in the 109 ``CanonicalBrowsingContext::ReplacedBy`` method. 110 111 .. [#chromebc] 112 113 A chrome browsing context does **not** refer to pages with the system 114 principal loaded in the content area such as ``about:preferences``. 115 Chrome browsing contexts are generally used as the root context in a chrome 116 window, such where ``browser.xhtml`` is loaded for a browser window. 117 118 All chrome browsing contexts exclusively load in the parent process and 119 cannot process switch when navigating.