1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
content / public / browser / preloading.h [blame]
// Copyright 2022 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef CONTENT_PUBLIC_BROWSER_PRELOADING_H_
#define CONTENT_PUBLIC_BROWSER_PRELOADING_H_
#include <cstdint>
#include <string_view>
#include "content/common/content_export.h"
namespace content {
// If you change any of the following enums or static variables, please follow
// the process in go/preloading-dashboard-updates to update the mapping
// reflected in dashboard, or if you are not a Googler, please file an FYI bug
// on https://crbug.new with component Internals>Preload.
// Defines the different types of preloading speedup techniques. Preloading is a
// holistic term to define all the speculative operations the browser does for
// loading content before a page navigates to make navigation faster.
//
// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused.
//
// LINT.IfChange
enum class PreloadingType {
// No PreloadingType is present. This may include other preloading operations
// which will be added later to PreloadingType as we expand.
kUnspecified = 0,
// Establishes a connection (including potential TLS handshake) with an
// origin.
kPreconnect = 2,
// Prefetch operation comes after Preresolve and Preconnect. Chrome spends a
// significant amount time idle, waiting for the main frame HTML fetch. The
// prefetch preloading operation fetches the HTML before the user starts
// navigating in order to load the page much faster.
kPrefetch = 3,
// This speedup technique comes with the most impact and overhead. We preload
// and render a page before the user navigates to it. This will make the next
// page navigation nearly instant as we would activate a fully prepared
// RenderFrameHost. Both resources are fetched and JS is executed.
kPrerender = 4,
// Like prerendering, it fetches resources in advance; but unlike prerendering
// it does not execute JavaScript or render any part of the page in advance.
// NoState prefetch only supports the GET HTTP method and doesn't cache
// resources with the no-store cache-control header.
kNoStatePrefetch = 5,
// Link-Preview loads a page with prerendering infrastructures in a dedicated
// mini tab so that users can take a look at the content before visiting it.
// TODO(b:291867362): This is not used by the current implementation,
// but might be reused in the future.
kLinkPreview = 6,
};
// LINT.ThenChange()
// Defines various triggering mechanisms which triggers different preloading
// operations mentioned in preloading.h. The integer portion is used for UKM
// logging, and the string portion is used to dynamically compose UMA histogram
// names. Embedders are allowed to define more predictors.
class CONTENT_EXPORT PreloadingPredictor {
public:
constexpr PreloadingPredictor(int64_t ukm_value, std::string_view name)
: ukm_value_(ukm_value), name_(name) {}
int64_t ukm_value() const { return ukm_value_; }
std::string_view name() const { return name_; }
constexpr bool operator==(const PreloadingPredictor& other) const {
// There's no need to compare name_ since every PreloadingPredictor has a
// distinct ukm_value_.
return other.ukm_value_ == ukm_value_;
}
constexpr std::strong_ordering operator<=>(
const PreloadingPredictor& other) const {
// There's no need to compare name_ since every PreloadingPredictor has a
// distinct ukm_value_.
return other.ukm_value_ <=> ukm_value_;
}
private:
int64_t ukm_value_;
std::string_view name_;
};
// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused.
//
// Advance numbering by +1 when adding a new element.
//
// To add additional predictors in content-internals and embedders, wrap the
// new `PreloadingPredictor` in the corresponding namespaces:
// - `content_preloading_predictor` for content-internals;
// - `chrome_preloading_predictor` for Chrome.
//
// See `content/browser/preloading/preloading.h` and
// `chrome/browser/preloading/chrome_preloading.h` for examples.
//
// Please limit content-public `PreloadingPredictor` between 0 to 49
// (inclusive) as 50 and beyond are reserved for content-internal and embedders.
// Both the value and the name should be unique across all the namespaces.
//
// The embedder `PreloadingPredictor` definitions should start at 100 (see
// `chrome/browser/preloading/chrome_preloading.h` for example).
//
// LINT.IfChange
namespace preloading_predictor {
// No PreloadingTrigger is present. This may include the small percentage of
// usages of browser triggers, link-rel, OptimizationGuideService e.t.c which
// will be added later as a separate elements.
static constexpr PreloadingPredictor kUnspecified(0, "Unspecified");
// Preloading is triggered by OnPointerDown event heuristics.
static constexpr PreloadingPredictor kUrlPointerDownOnAnchor(
1,
"UrlPointerDownOnAnchor");
// Preloading is triggered by OnPointerHover event heuristics.
static constexpr PreloadingPredictor kUrlPointerHoverOnAnchor(
2,
"UrlPointerHoverOnAnchor");
// Preloading was triggered by embedding a keyword for the rel attribute of
// the <link> HTML element to hint to browsers that the user might need it for
// next navigation.
static constexpr PreloadingPredictor kLinkRel(3, "LinkRel");
// When overscroll that could trigger a back navigation starts.
static constexpr PreloadingPredictor kBackGestureNavigation(
4,
"BackGestureNavigation");
// Preloading heuristics ML model.
static constexpr PreloadingPredictor kPreloadingHeuristicsMLModel(
5,
"PreloadingHeuristicsMLModel");
// Preloading is triggered by a deterministic viewport-based heuristic.
static constexpr PreloadingPredictor kViewportHeuristic(6, "ViewportHeuristic");
} // namespace preloading_predictor
// LINT.ThenChange()
// Defines if a preloading operation is eligible for a given preloading
// trigger.
//
// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused.
//
// LINT.IfChange
enum class PreloadingEligibility {
// Preloading operation is not defined for a particular preloading trigger
// prediction.
kUnspecified = 0,
// Preloading operation is eligible and is triggered for a preloading
// predictor.
kEligible = 1,
// Preloading operation could be ineligible if it is not triggered
// because some precondition was not satisfied. Preloading here could
// be ineligible due to various reasons subjective to the preloading
// operation like the following.
// These values are used in both //chrome and //content after integration with
// various preloading features.
// Preloading operation was ineligible because preloading was disabled.
kPreloadingDisabled = 2,
// Preloading operation was ineligible because it was triggered from the
// background or a hidden page.
kHidden = 3,
// Preloading operation was ineligible because it was invoked for cross origin
// navigation while preloading was restricted to same-origin navigations.
// (It's plausible that some preloading mechanisms in the future could work
// for cross-origin navigations as well.)
kCrossOrigin = 4,
// Preloading was ineligible due to low memory restrictions.
kLowMemory = 5,
// Preloading was ineligible as running JavaScript was disabled for the URL.
kJavascriptDisabled = 6,
// Preloading was ineligible because the Data Saver setting was enabled.
kDataSaverEnabled = 7,
// Preloading was ineligible because it was triggered from a page that has an
// effective url.
kHasEffectiveUrl = 8,
// Preloading was ineligible because only single renderer process is only
// allowed.
kSingleProcess = 9,
// Preloading was ineligible for link-rel:next URLs.
kLinkRelNext = 10,
// Preloading was ineligible due to the page having third party cookies.
kThirdPartyCookies = 11,
// Preloading was ineligible due to being called before we reached the time
// limit to invoke one more preloading operation.
kPreloadingInvokedWithinTimelimit = 12,
// Preloading was ineligible because we can't create a new renderer process
// for exceeding the renderer processes limit.
kRendererProcessLimitExceeded = 13,
// Preloading was ineligible because the Battery Saver setting was enabled.
kBatterySaverEnabled = 14,
// Preloading was ineligible because it is not supported for WebContents.
kPreloadingUnsupportedByWebContents = 15,
// Preloading was ineligible because it was triggered under memory pressure.
kMemoryPressure = 16,
// Preloading was ineligible because some DevTools client temporarily
// disabled.
kPreloadingDisabledByDevTools = 17,
// Preloading was ineligible because some triggers only allows https.
kHttpsOnly = 18,
// Preloading was ineligible for non-http(s).
kHttpOrHttpsOnly = 19,
// Preloading was ineligible because the network is too slow.
kSlowNetwork = 20,
// Preloading was ineligible because the V8 optimizer was disabled by the site
// settings. It's known that prerendering a page that has the COOP crashes
// when the V8 optimizer is disabled. See https://crbug.com/40076091 for
// details.
kV8OptimizerDisabled = 21,
// See corresponding values in PrefetchStatus for documentation.
kUserHasCookies = 55,
kUserHasServiceWorker = 56,
// This is similar to `kHttpsOnly`, but separately defined here to keep
// existing metrics values, for cases corresponding to
// `PrefetchStatus::kPrefetchIneligibleSchemeIsNotHttps`.
kSchemeIsNotHttps = 57,
kNonDefaultStoragePartition = 59,
kRetryAfter = 77,
kPrefetchProxyNotAvailable = 78,
kHostIsNonUnique = 86,
kExistingProxy = 88,
// OBSOLETE: kBrowserContextOffTheRecord = 89,
kSameSiteCrossOriginPrefetchRequiredProxy = 96,
// This constant is used to define the value beyond which embedders can add
// more enums.
kPreloadingEligibilityContentEnd = 100,
// This is another range reserved for content internal values, namely
// `PrerenderBackNavigationEligibility`. Embedders may add more values
// beyond this range.
kPreloadingEligibilityContentStart2 = 200,
kPreloadingEligibilityContentEnd2 = 250,
};
// LINT.ThenChange()
// The outcome of the holdback check. This is not part of eligibility status to
// clarify that this check needs to happen after we are done verifying the
// eligibility of a preloading attempt. In general, eligibility checks can be
// reordered, but the holdback check always needs to come after verifying that
// the preloading attempt was eligible.
//
// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused.
//
// LINT.IfChange
enum class PreloadingHoldbackStatus {
// The preloading holdback status has not been set yet. This should only
// happen when the preloading attempt was not eligible.
kUnspecified = 0,
// The preload was eligible to be triggered and was not disabled via a field
// trial holdback. Given enough time, the preload will trigger.
kAllowed = 1,
// The preload was eligible to be triggered but was disabled via a field
// trial holdback. This is useful for measuring the impact of preloading.
kHoldback = 2,
};
// LINT.ThenChange()
// Defines the post-triggering outcome once the preloading operation is
// triggered.
//
// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused. Please update
// "PreloadingTriggeringOutcome" in `tools/metrics/histograms/enums.xml` when
// new enums are added.
//
// LINT.IfChange
enum class PreloadingTriggeringOutcome {
// The outcome is kUnspecified for attempts that were not triggered due to
// various ineligibility reasons or due to a field trial holdback.
kUnspecified = 0,
// For attempts that we wanted to trigger, but for which we already had an
// equivalent attempt (same preloading operation and same URL/target) in
// progress.
kDuplicate = 2,
// Preloading was triggered and did not fail, but did not complete in time
// before the user navigated away (or the browser was shut down).
kRunning = 3,
// Preloading triggered and is ready to be used for the next navigation. This
// doesn't mean preloading attempt was actually used.
kReady = 4,
// Preloading was triggered, completed successfully and was used for the next
// navigation.
kSuccess = 5,
// Preloading was triggered but encountered an error and failed.
kFailure = 6,
// Some preloading features don't provide a way to keep track of the
// progression of the preloading attempt. In those cases, we just log
// kTriggeredButOutcomeUnknown, meaning that preloading was triggered but we
// don't know if it was successful.
kTriggeredButOutcomeUnknown = 7,
// A preloading feature (e.g., prefetch) completed successfully and was
// upgraded to Prerender. For PreloadingType::kPrefetch this is different from
// kSuccess reason which only tracks when the navigation directly uses the
// Prefetch. Please note that this doesn't ensure Prerender was successful.
kTriggeredButUpgradedToPrerender = 8,
// Preloading was triggered but was pending for starting its initial
// navigation.
kTriggeredButPending = 9,
// Used for triggers that do not perform a preloading operation. This may be
// used for a trigger which we're evaluating the accuracy of before actually
// having it preload.
kNoOp = 10,
// Required by UMA histogram macro.
kMaxValue = kNoOp,
};
// LINT.ThenChange()
// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused.
//
// LINT.IfChange
enum class PreloadingFailureReason {
// The failure reason is unspecified if the triggering outcome is not
// kFailure.
kUnspecified = 0,
// This constant is used to define the value from which specifying preloading
// types can add more enums beyond this value. We mask it by 100 to avoid
// usage of the same numbers for logging. The semantics of values beyond 100
// can vary by preloading type (for example 101 might mean "the page was
// destroyed" for prerender, but "the user already had cookies for a
// cross-origin prefetch"
// for prefetch).
//
// Values between kPreloadingFailureReasonCommonEnd (included) and
// kPreloadingFailureReasonContentEnd (excluded) are reserved for enums
// defined in //content.
kPreloadingFailureReasonCommonEnd = 100,
// Values beyond this value are for failure reasons defined by the embedder.
// The semantics of those values can vary by preloading type (1000 can mean
// "limit exceeded" for preconnect but "cancelled" for prerender).
kPreloadingFailureReasonContentEnd = 1000,
};
// LINT.ThenChange()
// Types of URL match:
// Exact match: the URLs are matching exactly.
// NoVarySearch match: No-Vary-Search header allows for inexact match by
// ignoring some query parameters, or the order of query parameters present
// in URLs.
// Custom match: custom URL matching provided by a url matching predicate.
enum class UrlMatchType { kExact, kNoVarySearch, kURLPredicateMatch };
} // namespace content
#endif // CONTENT_PUBLIC_BROWSER_PRELOADING_H_