blob: 644f3e2ac4c8da9e10016785fcdb3bf472a9c519 [file] [log] [blame] [view]
Charlie Reisb33534992020-06-26 05:28:171# Navigation Concepts
2
3This documentation covers a set of important topics to understand related to
4navigation. For a timeline of how a given navigation proceeds, see [Life of a
5Navigation](navigation.md).
6
7[TOC]
8
9
10## Same-Document and Cross-Document Navigations
11
12Chromium defines two types of navigations based on whether the navigation
13results in a new document or not. A _cross-document_ navigation is one that
14results in creating a new document to replace an existing document. This is
15the type of navigation that most users are familiar with. A _same-document_
16navigation does not create a new document, but rather keeps the same document
17and changes state associated with it. A same-document navigation does create a
18new session history entry, even though the same document remains active. This
19can be the result of one of the following cases:
20
21* Navigating to a fragment within an existing document (e.g.
22 `https://foo.com/1.html#fragment`).
23* A document calling the `history.pushState()` or `history.replaceState()` APIs.
Charlie Reisef219c82021-03-17 23:53:5924* A new document created via `document.open()`, which may change the URL to
25 match the document that initiated the call (possibly from another frame).
Charlie Reisb33534992020-06-26 05:28:1726* A session history navigation that stays in the same document, such as going
27 back/forward to an existing entry for the same document.
28
29
30## Browser-Initiated and Renderer-Initiated Navigations
31
32Chromium also defines two types of navigations based on which process started
33the navigation: _browser-initiated_ and _renderer-initiated_. This distinction
34is useful when making decisions about navigations, for example whether an
35ongoing navigation needs to be cancelled or not when a new navigation is
36starting. It is also used for some security decisions, such as whether to
37display the target URL of the navigation in the address bar or not.
38Browser-initiated navigations are more trustworthy, as they are usually in
39response to a user interaction with the UI of the browser. Renderer-initiated
40navigations originate in the renderer process, which may be under the control of
41an attacker. Note that some renderer-initiated navigations may be considered
42user-initiated, if they were performed with a [user
43activation](https://mustaqahmed.github.io/user-activation-v2/) (e.g., links),
44while others are not user-initiated (e.g., script navigations).
45
46
47## Last Committed, Pending, and Visible URLs
48
49Many features care about the URL or Origin of a given document, or about a
50pending navigation, or about what is showing in the address bar. These are all
51different concepts with different security implications, so be sure to use the
52correct value for your use case.
53
54See [Origin vs URL](security/origin-vs-url.md) when deciding whether to check
55the Origin or URL. In many cases that care about the security context, Origin
56should be preferred.
57
58The _last committed_ URL or Origin represents the document that is currently in
59the frame, regardless of what is showing in the address bar. This is almost
60always what should be used for feature-related state, unless a feature is
61explicitly tied to the address bar (e.g., padlock icon). See
62`RenderFrameHost::GetLastCommittedOrigin` (or URL) and
63`NavigationController::GetLastCommittedEntry`.
64
65The _pending_ URL exists when a main frame navigation has started but has not
66yet committed. This URL is only sometimes shown to the user in the address bar;
67see the description of visible URLs below. Features should rarely need to care
68about the pending URL, unless they are probing for a navigation they expect to
69have started. See `NavigationController::GetPendingEntry`.
70
71The _visible_ URL is what the address bar displays. This is carefully managed to
72show the main frame's last committed URL in most cases, and the pending URL in
73cases where it is safe and unlikely to be abused for a _URL spoof attack_ (where
74an attacker is able to display content as if it came from a victim URL). In
75general, the visible URL is:
76
77 * The pending URL for browser-initiated navigations like typed URLs or
78 bookmarks, excluding session history navigations.
79 * The last committed URL for renderer-initiated navigations, where an attacker
80 might have control over the contents of the document and the pending URL.
81 * A renderer-initiated navigation's URL is only visible while pending if it
82 opens in a new unmodified tab (so that an unhelpful `about:blank` URL is not
83 displayed), but only until another document tries to access the initial empty
84 document of the new tab. For example, an attacker window might open a new tab
85 to a slow victim URL, then inject content into the initial `about:blank`
86 document as if the slow URL had committed. If that occurs, the visible URL
87 reverts to `about:blank` to avoid a URL spoof scenario. Once the initial
88 navigation commits in the new tab, pending renderer-initiated navigation URLs
89 are no longer displayed.
90
91
92## Virtual URLs
93
94Virtual URLs are a way for features to change how certain URLs are displayed to
95the user (whether visible or committed). They are generally implemented using
96BrowserURLHandlers. Examples include:
97
98 * View Source URLs, where the `view-source:` prefix is not present in the
99 actual committed URL.
100 * DOM Distiller URLs, where the original URL is displayed to the user rather
101 than the more complex distiller URL.
102
103
104## Redirects
105
106Navigations can redirect to other URLs in two different ways.
107
108A _server redirect_ happens when the browser receives a 300-level HTTP response
109code before the document commits, telling it to request a different URL,
110possibly cross-origin. The new request will usually be an HTTP GET request,
111unless the redirect is triggered by a 307 or 308 response code, which preserves
112the original request method and body. Server redirects are managed by a single
113NavigationRequest. No document is committed to session history, but the original
114URL remains in the redirect chain.
115
116In contrast, a _client redirect_ happens after a document has committed, when
117the HTML in the document instructs the browser to request a new document (e.g.,
118via meta tags or JavaScript). Blink classifies the navigation as a client
119redirect based partly on how much time has passed. In this case, a session
120history item is created for the redirecting document, but it gets replaced when
121the actual destination document commits. A separate NavigationRequest is used
122for the second navigation.
123
124
125## Concurrent Navigations
126
127Many navigations can be in progress simultaneously. In general, every frame is
128considered independent and may have its own navigations(s), with each tracked by
129a NavigationRequest. Within a frame, it is possible to have multiple concurrent
130navigations:
131
132 * **A cross-document navigation waiting for its final response (at most one per
133 frame).** The NavigationRequest is owned by FrameTreeNode during this stage,
134 which can take several seconds. Some special case navigations do not use a
135 network request and skip this stage (e.g., `about:blank`, `about:srcdoc`,
136 MHTML).
137 * **A queue of cross-document navigations that are between "ready to commit"
138 and "commit," while the browser process waits for a commit acknowledgement
139 from the renderer process.** While rare, it is possible for multiple
140 navigations to be in this stage concurrently if the renderer process is slow.
141 The NavigationRequests are owned by the RenderFrameHost during this stage,
142 which is usually short-lived.
143 * **Same-document navigations.** These can be:
144 * Renderer-initiated (e.g., `pushState`, fragment link click). In this case,
145 the browser process creates and destroys a NavigationRequest in the same
146 task.
147 * Browser-initiated (e.g., omnibox fragment change). In this case, the
148 browser process creates a NavigationRequest owned by the RenderFrameHost
149 and immediately tells the renderer to commit.
150
151Note that the navigation code is not re-entrant. Callers must not start a new
152navigation while a call to `NavigateWithoutEntry` or
153`NavigateToExistingPendingEntry` is on the stack, to avoid a CHECK that guards
154against use-after-free for `pending_entry_`.
155
156
157## Rules for Canceling Navigations
158
159We generally do not want an abusive page to prevent the user from navigating
160away, such as by endlessly starting new navigations that interrupt or cancel the
161user's attempts. Generally, a new navigation will cancel an existing one in a
162frame, but we make the following exception: a renderer-initiated navigation is
163ignored iff there is an ongoing browser-initiated navigation and the new
164navigation lacks a user activation. (This is implemented in
165`Navigator::ShouldIgnoreIncomingRendererRequest`.)
166
167NavigationThrottles also have an ability to cancel navigations when desired by a
168feature. Keep in mind that it is problematic to simulate a redirect by canceling
169a navigation and starting a new one, since this may lose relevant context from
170the original navigation (e.g., ReloadType, CSP state, Sec-Fetch-Metadata state,
171redirect chain, etc), and it will lead to unexpected observer events and metrics
172(e.g., extra navigation starts, inflated numbers of canceled navigations, etc).
173Feature authors that want to simulate redirects may want to consider using a
174URLLoaderRequestInterceptor instead.
175
176
177## Error Pages
178
179There are several types of error pages that can be displayed when a navigation
180is not successful.
181
182The server can return a custom error page, such as a 400 or 500 level HTTP
183response code page. These pages are rendered much like a successful navigation
184to the site (and go into an appropriate process for that site), but the error
185code is available and `NavigationHandle::IsErrorPage()` is true.
186
187If the navigation fails to get a response from the server (e.g., the DNS lookup
188fails), then Chromium will display an error page. For main frames, this error
189page will be in a special error page process, not affiliated with any site or
190containing any untrustworthy content from the web. In these failed cases,
191NetErrorHelperCore may try to reload the URL at a later time (e.g., if a network
192connection comes back online), to load the document in an appropriate process.
193
194If instead the navigation is blocked (e.g., by an extension API or a
195NavigationThrottle), then Chromium will similarly display an error page in a
196special error page process. However, in blocked cases, Chromium will not attempt
197to reload the URL at a later time.
198
199
200## Interstitial Pages
201
202Interstitial pages are implemented as committed error pages. (Prior to
203[issue 448486](https://crbug.com/448486), they were implemented as overlays.)
204The original in-progress navigation is canceled when the interstitial is
205displayed, and Chromium repeats the navigation if the user chooses to proceed.
206
207Note that some interstitials can be shown after a page has committed (e.g., when
208a subresource load triggers a Safe Browsing error). In this case, Chromium
209navigates away from the original page to the interstitial page, with the intent
210of replacing the original NavigationEntry. However, the original NavigationEntry
211is preserved in `NavigationControllerImpl::entry_replaced_by_post_commit_error_`
212in case the user chooses to dismiss the interstitial and return to the original
213page.