Skip to content

Commit 0ce01bb

Browse files
domenicdomenic
committed
Rebase on top of HTML
whatwg/html#11426 upstreams most of the speculation rules specification to HTML. Remove the upstreamed portions, and add references to the PR and PR preview.
1 parent 90ccea6 commit 0ce01bb

File tree

4 files changed

+167
-1032
lines changed

4 files changed

+167
-1032
lines changed

‎index.html‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,19 @@
33
<h1>WICG/nav-speculation</h1>
44
<p>This document has been split for easier reading.</p>
55
<dl>
6+
<dt><a href="https://whatpr.org/html/11426/speculative-loading.html">HTML Standard PR Preview: Speculative Loading</a></dt>
7+
<dd>Some of this specification is being upstreamed to the HTML Standard: see <a href="https://github.com/whatwg/html/pull/11426">whatwg/html#11426</a> and <a href="https://github.com/whatwg/html/issues/11123">whatwg/html#11123</a>.</dd>
8+
69
<dt><a href="prefetch.html">Prefetch</a></dt>
7-
<dd>Extensions to WHATWG Fetch for prefetching with partitioning in mind.</dd>
10+
<dd>The navigational prefetching algorithms.</dd>
811

912
<dt><a href="prerendering.html">Prerendering Revamped</a></dt>
10-
<dd>This document contains a collection of specification patches for well-specified prerendering.</dd>
13+
<dd>The navigational prerendering algorithms.</dd>
1114

1215
<dt><a href="speculation-rules.html">Speculation Rules</a></dt>
13-
<dd>A flexible syntax for defining what outgoing links can be prepared speculatively before navigation.</dd>
16+
<dd>Extensions to speculation rules to support navigational prerendering.</dd>
1417

15-
<dt><a href="no-vary-search.html">No-Vary-Search</a></dt>
18+
<dt><a href="https://httpwg.org/http-extensions/draft-ietf-httpbis-no-vary-search.html">IETF HTTPWG: No-Vary-Search</a></dt>
1619
<dd>A proposed HTTP header for changing how a URL's search component impacts cache hits.</dd>
1720
</dl>
1821
<script>

‎prefetch.bs‎

Lines changed: 37 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@ Repository: WICG/nav-speculation
77
URL: https://wicg.github.io/nav-speculation/prefetch.html
88
Level: 1
99
Editor: Jeremy Roman, Google https://www.google.com/, jbroman@chromium.org
10-
Abstract: Extensions to WHATWG Fetch for prefetching with partitioning in mind.
10+
Editor: Domenic Denicola, Google https://www.google.com/, d@domenic.me
11+
Abstract: A specification for navigational prefetching
1112
Markup Shorthands: css no, markdown yes
1213
Assume Explicit For: yes
1314
Complain About: accidental-2119 yes, missing-example-ids yes
@@ -108,6 +109,22 @@ spec: html; urlPrefix: https://html.spec.whatwg.org/multipage/
108109
text: process early hint headers; url: process-early-hint-headers
109110
urlPrefix: structured-data.html
110111
text: StructuredSerializeForStorage; url: structuredserializeforstorage
112+
spec: HTML; urlPrefix: https://whatpr.org/html/11426/speculative-loading.html#
113+
type: dfn
114+
text: cross-origin prefetch IP anonymization policy; url: cross-origin-prefetch-ip-anonymization-policy
115+
text: prefetch candidate; url: prefetch-candidate
116+
text: prefetch IP anonymization policy; url: prefetch-ip-anonymization-policy
117+
text: prerender candidate; url: prerender-candidate
118+
text: speculation rule tag; url: speculation-rule-tag
119+
text: speculative load candidate; url: speculative-load-candidate
120+
for: cross-origin prefetch IP anonymization policy
121+
text: origin; url: copiap-origin
122+
for: prefetch candidate
123+
text: anonymization policy; url: sl-candidate-anonymization-policy
124+
for: speculative load candidate
125+
text: URL; url: sl-candidate-url
126+
type: http-header
127+
text: Sec-Speculation-Tags; url: sec-speculation-tags
111128
spec: fetch; urlPrefix: https://fetch.spec.whatwg.org/
112129
type: dfn
113130
text: network partition key; url: network-partition-key
@@ -188,12 +205,12 @@ A <dfn>redirect chain</dfn> is a [=list=] of [=exchange records=].
188205
Each {{Document}} has <dfn export for="Document">prefetch records</dfn>, which is a [=list=] of [=prefetch records=].
189206

190207
A <dfn export>prefetch record</dfn> is a [=struct=] with the following [=struct/items=]:
191-
* <dfn export for="prefetch record">tags</dfn>, an [=ordered set=] of [=speculation rules tags=]
208+
* <dfn export for="prefetch record">tags</dfn>, an [=ordered set=] of [=speculation rule tags=]
192209
* <dfn export for="prefetch record">URL</dfn>, a [=URL=]
193210
* <dfn export for="prefetch record">anonymization policy</dfn>, a [=prefetch IP anonymization policy=]
194211
* <dfn export for="prefetch record">referrer policy</dfn>, a [=referrer policy=]
195212
* <dfn export for="prefetch record">No-Vary-Search hint</dfn>, a [=URL search variance=]
196-
* <dfn export for="prefetch record">label</dfn>, a [=string=]
213+
* <dfn export for="prefetch record">source</dfn>, a [=string=]
197214

198215
<div class="note">This is intended for use by a specification or [=implementation-defined=] feature to identify which prefetches it created. It might also associate other data with this struct.</div>
199216
* <dfn export for="prefetch record">prerendering traversable</dfn>, a [=prerendering traversable=], "`to be created`", or null (null by default)
@@ -309,6 +326,17 @@ The user agent may [=prefetch record/cancel and discard=] records from the [=Doc
309326
<p class="note">The reasoning for setting the cutoff time *after* waiting for a prefetch record to finish is to allow for flexibility in selecting a prefetch to serve the navigation while still guaranteeing falling back to a non-prefetched navigation in the case of repeated prefetch failures. We allow blocking on prefetch attempts which started before we see an attempt fail, but we don't block on subsequent attempts. Notably, this approach: does not finalize the set of prefetches to block on at the start of the navigation; allows a prefetch which started and completed after the navigation started to serve the navigation; avoids the use of a fixed timeout, which would be arbitrary and detrimental to the use of prefetch with slower servers; and blocks on, at most, two nearly-consecutive prefetches before falling back to a conventional navigation.</p>
310327
</div>
311328

329+
<div algorithm>
330+
A [=prefetch record=] |prefetchRecord| is <dfn export for="prefetch record">still being speculated</dfn>, given a list of [=speculative load candidates=] |candidates|, if the following steps return true:
331+
332+
1. [=list/For each=] |candidate| of |candidates|:
333+
1. If |prefetchRecord| does not [=prefetch record/match a URL=] given |candidate|'s [=speculative load candidate/URL=], then [=iteration/continue=].
334+
1. If |candidate| is a [=prefetch candidate=] and |prefetchRecord|'s [=prefetch record/anonymization policy=] does not equal |candidate|'s [=prefetch candidate/anonymization policy=], then [=iteration/continue=].
335+
1. If |candidate| is a [=prerender candidate=] and |prefetchRecord|'s [=prefetch record/prerendering traversable=] is null, then [=iteration/continue=].
336+
1. Return true.
337+
1. Return false.
338+
</div>
339+
312340
<div algorithm="has a matching prefetch record">
313341
A {{Document}} |document| <dfn export>has a matching prefetch record</dfn> given a [=prefetch record=] |recordUnderConsideration| and an optional boolean <dfn for="has a matching prefetch record" export>|checkPrerender|</dfn> (default false) if the following algorithm returns true:
314342

@@ -335,25 +363,7 @@ The user agent may [=prefetch record/cancel and discard=] records from the [=Doc
335363

336364
1. Return false.
337365

338-
<div class="note" id="note-require-equivalent-nvs">
339-
<p>The requirement that the No-Vary-Search values be equivalent is somewhat strict. It means that some cases which could theoretically be treated as matching, are not treated as such, and thus redundant prefetches could happen.
340-
341-
<p>However, allowing more lenient matching makes the check no longer an equivalence relation, and thus prohibits implementation strategies based on normalized URL keys. For this reason, we require equivalent No-Vary-Search values. This is in line with the best practices for server operators demanded in [[NO-VARY-SEARCH#section-6]].
342-
343-
<p>In practice, we do not expect this to cause redundant prefetches, since server operators and the corresponding speculation rules-writing web developers will follow best practices and use static No-Vary-Search values.
344-
</div>
345-
346-
<div class="example" id="example-non-matching-nvs">
347-
<p>Consider three [=prefetch records=]:
348-
349-
* |A| has a [=prefetch record/URL=] of `https://example.com?a=1&b=1` and a [=prefetch record/No-Vary-Search hint=] parsed from `params=("a")`.
350-
* |B| has a [=prefetch record/URL=] of `https://example.com?a=2&b=1` and a [=prefetch record/No-Vary-Search hint=] parsed from `params=("b")`.
351-
* |C| has a [=prefetch record/URL=] of `https://example.com?a=2&b=2` and a [=prefetch record/No-Vary-Search hint=] parsed from `params=("a")`.
352-
353-
<p>With the current definition of [=has a matching prefetch record=], none of these records match each other.
354-
355-
<p>A definition which did not require equivalent No-Vary-Search values could consider |A| and |B| to match (using |A|'s [=prefetch record/No-Vary-Search hint=]), and |B| and |C| to match (using |B|'s [=prefetch record/No-Vary-Search hint=]). But it could not consider |A| and |C| to match, so it would not be transitive, and thus not an equivalence relation.
356-
</div>
366+
<p class="note">See the discussion [:No-Vary-Search:] comparison <a href="https://whatpr.org/html/11426/document-lifecycle.html#note-sl-candidate-redundant-with-nvs-strictness">in the HTML Standard</a>.</p>
357367
</div>
358368

359369
<div algorithm>
@@ -444,10 +454,6 @@ The user agent may [=prefetch record/cancel and discard=] records from the [=Doc
444454
:: "`navigational-prefetch`"
445455
</div>
446456

447-
A <dfn export>prefetch IP anonymization policy</dfn> is either null or a [=cross-origin prefetch IP anonymization policy=].
448-
449-
A <dfn export>cross-origin prefetch IP anonymization policy</dfn> has an <dfn export for="cross-origin prefetch IP anonymization policy">origin</dfn>, which is an [=origin=].
450-
451457
<div algorithm>
452458
A [=prefetch IP anonymization policy=] |policy| <dfn for="prefetch IP anonymization policy">requires anonymity</dfn> for [=request=] |request| if the following steps return true:
453459

@@ -819,7 +825,7 @@ Modify <a abstract-op spec="CLEAR-SITE-DATA">clear site data for response</a>'s
819825
The <dfn>list of sufficiently strict speculative navigation referrer policies</dfn> is a list containing the following: "", "`strict-origin-when-cross-origin`", "`strict-origin`", "`same-origin`", "`no-referrer`".
820826

821827
<div algorithm>
822-
To <dfn export>prefetch</dfn> given a {{Document}} |document| and a [=prefetch record=] |prefetchRecord|, perform the following steps.
828+
To <dfn export>start a referrer-initiated navigational prefetch</dfn> given a {{Document}} |document| and a [=prefetch record=] |prefetchRecord|, perform the following steps.
823829

824830
1. [=Assert=]: |document|'s [=node navigable=] is a [=top-level traversable=].
825831

@@ -944,7 +950,7 @@ The following parameters are defined for the `prefetch` token:
944950
<div class="note">
945951
A future specification might define assign more specific meaning to non-boolean values. For now, they are treated the same as true. Implementations are advised not to emit such values.
946952

947-
This specification conforms to this advice; the [=prefetch=] algorithm does not emit non-boolean values.
953+
This specification conforms to this advice; the [=start a referrer-initiated navigational prefetch=] algorithm does not emit non-boolean values.
948954
</div>
949955

950956
* A parameter whose key is "<dfn for="Sec-Purpose prefetch">`prerender`</dfn>".
@@ -954,23 +960,13 @@ The following parameters are defined for the `prefetch` token:
954960
<div class="note">
955961
A future specification might define assign more specific meaning to non-boolean values. For now, they are treated the same as true. Implementations are advised not to emit such values.
956962

957-
This specification conforms to this advice; the [=prefetch=] algorithm does not emit non-boolean values.
963+
This specification conforms to this advice; the [=start a referrer-initiated navigational prefetch=] algorithm does not emit non-boolean values.
958964
</div>
959965

960-
<h2 id="sec-speculation-tags-header">The `Sec-Speculation-Tags` HTTP request header</h2>
961-
962-
The \`<code><dfn http-header>Sec-Speculation-Tags</dfn></code>\` HTTP request header specifies the web developer-provided tags associated with the speculative navigation request. It can also be used to distinguish speculative navigation requests from other speculative requests, since [:Sec-Purpose:] can be sent by both categories of request.
963-
964-
The header field is an [[RFC9651]] Structured Header whose value must be a [=structured header/List=]. The list can contain either [=structured header/Token=] or [=structured header/String=] values. String values represent developer-provided tags, whereas token values represent predefined tags. As of now, the only predefined tag is `null`, which indicates a speculative navigation request with no developer-defined tag.
965-
966966
<h2 id="security-considerations">Security considerations</h2>
967967

968-
See <a href="speculation-rules.html#security-considerations">Security considerations (Speculation Rules)</a>.
969-
970-
For the integration of this spec with No-Vary-Search, see <a href="https://httpwg.org/http-extensions/draft-ietf-httpbis-no-vary-search.html#name-security-considerations">No-Vary-Search Security considerations</a>.
968+
See <a href="https://whatpr.org/html/11426/speculative-loading.html#speculative-loading-security">the HTML Standard</a>.
971969

972970
<h2 id="privacy-considerations">Privacy considerations</h2>
973971

974-
See <a href="speculation-rules.html#privacy-considerations">Privacy considerations (Speculation Rules)</a>.
975-
976-
For the integration of this spec with No-Vary-Search, see <a href="https://httpwg.org/http-extensions/draft-ietf-httpbis-no-vary-search.html#name-privacy-considerations">No-Vary-Search Privacy considerations</a>.
972+
See <a href="https://whatpr.org/html/11426/speculative-loading.html#speculative-loading-privacy">the HTML Standard</a>.

‎prerendering.bs‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,7 @@ spec: nav-speculation; urlPrefix: prefetch.html
9494
text: wait for a matching prefetch record; url: wait-for-a-matching-prefetch-record
9595
text: has a matching prefetch record
9696
for: prefetch record
97+
text: source
9798
text: prerendering traversable
9899
text: prerendering target navigable name hint
99100
for: has a matching prefetch record
@@ -255,7 +256,7 @@ Every {{Document}} has an <dfn for="Document">activation start time</dfn>, which
255256

256257
1. Set |prerenderingTraversable|'s [=navigable/loading mode=] to "`prerender`".
257258

258-
1. Let |prefetchRecord| be a new [=prefetch record=] whose [=prefetch record/URL=] is |startingURL|, [=prefetch record/anonymization policy=] is null, [=prefetch record/referrer policy=] is the empty string, [=prefetch record/No-Vary-Search hint=] is the [=default URL search variance=], [=prefetch record/label=] is "`browser UI`", and [=prefetch record/prerendering traversable=] is |prerenderingTraversable|.
259+
1. Let |prefetchRecord| be a new [=prefetch record=] whose [=prefetch record/URL=] is |startingURL|, [=prefetch record/anonymization policy=] is null, [=prefetch record/referrer policy=] is the empty string, [=prefetch record/No-Vary-Search hint=] is the [=default URL search variance=], [=prefetch record/source=] is "`browser UI`", and [=prefetch record/prerendering traversable=] is |prerenderingTraversable|.
259260

260261
1. [=Prefetch=] given |prerenderingTraversable|'s [=navigable/active document=] and |prefetchRecord|.
261262

@@ -281,7 +282,7 @@ Every {{Document}} has an <dfn for="Document">activation start time</dfn>, which
281282
</div>
282283

283284
<div>
284-
To <dfn export>start referrer-initiated prerendering</dfn> given a {{Document}} |referrerDoc| and a [=prefetch record=] |prefetchRecord|:
285+
To <dfn export>start a referrer-initiated navigational prerender</dfn> given a {{Document}} |referrerDoc| and a [=prefetch record=] |prefetchRecord|:
285286

286287
1. [=Assert=]: |prefetchRecord|'s [=prefetch record/URL=]'s [=url/scheme=] is an [=HTTP(S) scheme=].
287288

@@ -1064,15 +1065,15 @@ More complicated cases:
10641065

10651066
<h2 id="security-considerations">Security considerations</h2>
10661067

1067-
See <a href="speculation-rules.html#security-considerations">Security considerations (Speculation Rules)</a>.
1068+
See <a href="https://whatpr.org/html/11426/speculative-loading.html#speculative-loading-security">the HTML Standard</a>.
10681069

10691070
For the integration of this spec with No-Vary-Search, see <a href="https://httpwg.org/http-extensions/draft-ietf-httpbis-no-vary-search.html#name-security-considerations">No-Vary-Search Security considerations</a>.
10701071

10711072
<p class="issue">Add security considerations that are specific to prerendering. See <a href="https://github.com/WICG/nav-speculation/issues/319">issue #319</a>.</p>
10721073

10731074
<h2 id="privacy-considerations">Privacy considerations</h2>
10741075

1075-
See <a href="speculation-rules.html#privacy-considerations">Privacy considerations (Speculation Rules)</a>.
1076+
See <a href="https://whatpr.org/html/11426/speculative-loading.html#speculative-loading-privacy">the HTML Standard</a>.
10761077

10771078
For the integration of this spec with No-Vary-Search, see <a href="https://httpwg.org/http-extensions/draft-ietf-httpbis-no-vary-search.html#name-privacy-considerations">No-Vary-Search Privacy considerations</a>.
10781079

0 commit comments

Comments
 (0)