Skip to content
This repository has been archived by the owner on Sep 18, 2024. It is now read-only.

Explainer edits + initial spec. #1

Merged
merged 5 commits into from
Aug 22, 2024
Merged

Explainer edits + initial spec. #1

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
51e14e1
Explainer edits + initial spec.
alexnj Aug 21, 2024
56c0a2e
Review changes
alexnj Aug 21, 2024
79c143f
Update specification plan section.
alexnj Aug 21, 2024
ac969b9
Review changes
alexnj Aug 22, 2024
f985091
Crosslink method for [get a structured field value]
alexnj Aug 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
184 changes: 53 additions & 131 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,177 +1,99 @@
# Explainer for the TODO API
# `Prefer-No-Speculative-Parsing` explainer

**Instructions for the explainer author: Search for "todo" in this repository and update all the
instances as appropriate. For the instances in `index.bs`, update the repository name, but you can
leave the rest until you start the specification. Then delete the TODOs and this block of text.**

This proposal is an early design sketch by [TODO: team] to describe the problem below and solicit
feedback on the proposed solution. It has not been approved to ship in Chrome.

TODO: Fill in the whole explainer template below using https://tag.w3.org/explainers/ as a
reference. Look for [brackets].

## Proponents

- [Proponent team 1]
- [Proponent team 2]
- [etc.]
The `Prefer-No-Speculative-Parsing` HTTP response header allows a developer to request the user agent to not use the default speculative parsing behavior.

## Participate
- https://github.com/explainers-by-googlers/[your-repository-name]/issues
- [Discussion forum]
- https://github.com/explainers-by-googlers/prefer-no-speculative-parsing/issues

## Table of Contents [if the explainer is longer than one printed page]
## Table of Contents

<!-- Update this table of contents by running `npx doctoc README.md` -->
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Introduction](#introduction)
- [Goals](#goals)
- [Non-goals](#non-goals)
- [User research](#user-research)
- [Use cases](#use-cases)
- [Use case 1](#use-case-1)
- [Use case 2](#use-case-2)
- [[Potential Solution]](#potential-solution)
- [How this solution would solve the use cases](#how-this-solution-would-solve-the-use-cases)
- [Use case 1](#use-case-1-1)
- [Use case 2](#use-case-2-1)
- [Detailed design discussion](#detailed-design-discussion)
- [[Tricky design choice #1]](#tricky-design-choice-1)
- [[Tricky design choice 2]](#tricky-design-choice-2)
- [Considered alternatives](#considered-alternatives)
- [[Alternative 1]](#alternative-1)
- [[Alternative 2]](#alternative-2)
- [Stakeholder Feedback / Opposition](#stakeholder-feedback--opposition)
- [References & acknowledgements](#references--acknowledgements)
- [`Prefer-No-Speculative-Parsing` explainer](#prefer-no-speculative-parsing-explainer)
- [Participate](#participate)
- [Table of Contents](#table-of-contents)
- [Introduction](#introduction)
- [Example](#example)
- [Goals](#goals)
- [Non-goals](#non-goals)
- [User research](#user-research)
- [Specification plan](#specification-plan)
- [Considered alternatives](#considered-alternatives)
- [A `<meta>` tag version](#a-meta-tag-version)
- [Use of `Content-Security-Policy` meta tag as a work-around](#use-of-content-security-policy-meta-tag-as-a-work-around)
- [References \& acknowledgements](#references--acknowledgements)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Introduction

[The "executive summary" or "abstract".
Explain in a few sentences what the goals of the project are,
and a brief overview of how the solution works.
This should be no more than 1-2 paragraphs.]

## Goals

[What is the **end-user need** which this project aims to address? Make this section short, and
elaborate in the Use cases section.]

## Non-goals

[If there are "adjacent" goals which may appear to be in scope but aren't,
enumerate them here. This section may be fleshed out as your design progresses and you encounter necessary technical and other trade-offs.]

## User research

[If any user research has been conducted to inform your design choices,
discuss the process and findings. User research should be more common than it is.]

## Use cases

[Describe in detail what problems end-users are facing, which this project is trying to solve. A
common mistake in this section is to take a web developer's or server operator's perspective, which
makes reviewers worry that the proposal will violate [RFC 8890, The Internet is for End
Users](https://www.rfc-editor.org/rfc/rfc8890).]

### Use case 1

### Use case 2
User Agents have implemented [speculative parsing of HTML](https://html.spec.whatwg.org/multipage/parsing.html#speculative-html-parsing) to speculatively fetch resources that are present in the HTML markup, to speed up page loading. For the vast majority of pages on the Web that have resources declared in the HTML markup, the optimization is beneficial and the cost paid in determining such resources is a sound tradeoff. However, the following scenarios might result in a sub-optimal performance tradeoff vs. the explicit time spent parsing HTML for determining sub resources to fetch:

<!-- In your initial explainer, you shouldn't be attached or appear attached to any of the potential
solutions you describe below this. -->
* Pages that do not have any resources declared in the HTML.
* Large HTML pages with minimal or no resource loads that could explicitly control preloading resources via other preload mechanisms available.
* Pages that have privacy concerns around resource loads during the speculative fetch phase.

## [Potential Solution]
This proposal introduces a hint response header `Prefer-No-Speculative-Parsing` to explicitly state to the User Agent that it may choose to optimize out the time spent in such sub resource determination.

[For each related element of the proposed solution - be it an additional JS method, a new object, a new element, a new concept etc., create a section which briefly describes it.]
## Example

```js
// Provide example code - not IDL - demonstrating the design of the feature.
A document can request that the default speculative parsing behavior is not used, by using the `Prefer-No-Speculative-Parsing` HTTP header. This header is a HTTP [structured field](https://httpwg.org/http-extensions/draft-ietf-httpbis-header-structure.html) whose value must be Boolean.

// If this API can be used on its own to address a user need,
// link it back to one of the scenarios in the goals section.

// If you need to show how to get the feature set up
// (initialized, or using permissions, etc.), include that too.
```http
HTTP/1.1 200 OK
Content-Type: text/html
...
Prefer-No-Speculative-Parsing: ?1
...
```

[Where necessary, provide links to longer explanations of the relevant pre-existing concepts and API.
If there is no suitable external documentation, you might like to provide supplementary information as an appendix in this document, and provide an internal link where appropriate.]
The presence of the header, with the structured headers boolean "true" value `?1`, indicates that resulting document’s [active speculative HTML parser](https://html.spec.whatwg.org/multipage/parsing.html#active-speculative-html-parser) may be explicitly set to `null`. Note that this header indicates only a preference from the Document on how the speculative HTML parser may behave, which the user agent may eventually choose to ignore. In terms of observable effects, this means that any fetches originating from speculative HTML parser may be avoided and any time spent in speculative parsing may be reduced. Resources that were being fetched as part of a speculative fetch, will then be fetched as part of the normal document parsing. Behind the scenes, this preference can allow user agents to skip the time spent in speculative parsing, and deallocate any implementation specific resources corresponding to speculative parsing for additional efficiency.

[If this is already specced, link to the relevant section of the spec.]

[If spec work is in progress, link to the PR or draft of the spec.]

[If you have more potential solutions in mind, add ## Potential Solution 2, 3, etc. sections.]

### How this solution would solve the use cases

[If there are a suite of interacting APIs, show how they work together to solve the use cases described.]

#### Use case 1
## Goals

[Description of the end-user scenario]
* Allow well informed web developers to assist User Agents to optimize loading sequence better, resulting in a more performant scenario.
* Allow opting-in per HTTP response, creating a very targeted signal that reduces misuse.
* Allow User Agents to determine if they should heed to the hint, preventing any binding contracts that prevent future optimization of the speculating parser and prefetch implementation.

```js
// Sample code demonstrating how to use these APIs to address that scenario.
```
## Non-goals

#### Use case 2
* Generalize the header to signal more than the intended hint.
* Allow explicit control of the speculative parsing or preloading scanning mechanism — it’s better this is designed as a hint that a response is supplied with, on which the UA may choose to vary its usage of speculative parsing on.

[etc.]
## User research

## Detailed design discussion
An Origin Trial was conducted in Chrome from M125 to M130 that allowed participants to disable the default speculative prefetch behavior of the user agent. More information about the Origin Trial can be found on the [Chrome Platform Status page for the Skip Preload Scanning Feature](https://chromestatus.com/feature/5190976638550016) and the [explainer document](https://docs.google.com/document/d/1wiaTL5TeONTZamycMVMjo76nMcbhHNYznQy7I_zCVRY/edit).
alexnj marked this conversation as resolved.
Show resolved Hide resolved

### [Tricky design choice #1]
Additional comments and usecases from the community were received on the [tracker issue](https://issues.chromium.org/issues/330802493) that influenced the design of this header.

[Talk through the tradeoffs in coming to the specific design point you want to make.]
Participants observed improved performance on pages that do not have external
resource fetches by reducing the time spent towards speculative parsing.

```js
// Illustrated with example code.
```
## Specification plan

[This may be an open question,
in which case you should link to any active discussion threads.]
The specification for this feature in itself consists of two parts.

### [Tricky design choice 2]
One part is header parsing, which relies on the [Structured Headers](https://httpwg.org/http-extensions/draft-ietf-httpbis-header-structure.html) specification to do the work. The other is altering behavior of the [active HTML speculative parser](https://html.spec.whatwg.org/multipage/parsing.html#active-speculative-html-parser), which would be done by modifying the HTML Standard's [Speculative HTML parsing](https://html.spec.whatwg.org/multipage/parsing.html#speculative-html-parsing).

[etc.]
Please see the associated [spec proposal](https://explainers-by-googlers.github.io/prefer-no-speculative-parsing) for more information.

## Considered alternatives

[This should include as many alternatives as you can,
from high level architectural decisions down to alternative naming choices.]

### [Alternative 1]

[Describe an alternative which was considered,
and why you decided against it.]

### [Alternative 2]
### A `<meta>` tag version

[etc.]
While a `meta` header is in some cases easier for web developers to add to their page than a header, it would make the behavior of such a directive unpredictable. It will also add further complexity in determining how such a directive would work given the placement and timing of itself against resources specified in the HTML. This option has been considered and rejected.
alexnj marked this conversation as resolved.
Show resolved Hide resolved

## Stakeholder Feedback / Opposition
### Use of `Content-Security-Policy` meta tag as a work-around

[Implementors and other stakeholders may already have publicly stated positions on this work. If you can, list them here with links to evidence as appropriate.]

- [Implementor A] : Positive
- [Stakeholder B] : No signals
- [Implementor C] : Negative

[If appropriate, explain the reasons given by other implementors for their concerns.]
Some user agents may choose to disable active speculative HTML parser partly or completely on encountering a CSP meta tag. A more direct hint from the page is a more precise signal vs. overloading of the CSP header for implicit disabling of active speculative HTML parser.

## References & acknowledgements

[Your design will change and be informed by many people; acknowledge them in an ongoing way! It helps build community and, as we only get by through the contributions of many, is only fair.]

[Unless you have a specific reason not to, these should be in alphabetical order.]

Many thanks for valuable feedback and advice from:

- [Person 1]
- [Person 2]
- [etc.]
- Domenic Denicola
- Yoav Weiss
44 changes: 31 additions & 13 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
<pre class='metadata'>
Title: The TODO API
Shortname: todo
Title: Prefer-No-Speculative-Parsing
Shortname: Prefer-No-Speculative-Parsing
Level: None
Status: w3c/UD
Repository: explainers-by-googlers/todo-your-repo-name
URL: https://explainers-by-googlers.github.io/todo-your-repo-name
Editor: TODO: Your Name, Google https://google.com, TODO@google.com
Abstract: TODO: A short description of your spec, one or two sentences.
Repository: explainers-by-googlers/prefer-no-speculative-parsing
URL: https://explainers-by-googlers.github.io/prefer-no-speculative-parsing
Editor: Alex N. Jose, Google LLC https://google.com, alexnj@google.com
Abstract: The `Prefer-No-Speculative-Parsing` HTTP response header allows a developer to request the user agent to not use the default speculative behavior.
Markup Shorthands: markdown yes, css no
Complain About: accidental-2119 yes, missing-example-ids yes
Assume Explicit For: yes
Expand All @@ -17,12 +17,30 @@ Include MDN Panels: if possible
Include Can I Use Panels: yes
</pre>

Introduction {#intro}
=====================
# Introduction # {#introduction}

For now, see the [explainer]([REPOSITORYURL]).
*This section is non-normative.*

See [https://garykac.github.io/procspec/](https://garykac.github.io/procspec/),
[https://dlaliberte.github.io/bikeshed-intro/index.html](https://dlaliberte.github.io/bikeshed-intro/index.html),
and [https://speced.github.io/bikeshed/](https://speced.github.io/bikeshed/) to get started on your
specificaton.
A document can request the user agent that the default speculative parsing behavior is not used, by using the `Prefer-No-Speculative-Parsing` HTTP header. This header is a HTTP structured field whose value must be Boolean.
alexnj marked this conversation as resolved.
Show resolved Hide resolved

The consequence of using this header is that the resulting Document's [active speculative HTML parser](https://html.spec.whatwg.org/multipage/parsing.html#active-speculative-html-parser) may be set to `null`. This header indicates only a preference from the Document on how the speculative HTML parser may behave, which the user agent may choose to ignore. In terms of observable effects, this means that any fetches originating from speculative HTML parser may be avoided and any time spent in speculative parsing may be reduced. Resources that were being fetched as part of a speculative fetch, will then be fetched as part of the normal document parsing. Behind the scenes, this preference can allow user agents to skip the time spent in speculative parsing, and deallocate any implementation specific resources corresponding to speculative parsing for additional efficiency.
alexnj marked this conversation as resolved.
Show resolved Hide resolved
alexnj marked this conversation as resolved.
Show resolved Hide resolved

# Modifications to HTML's Speculative HTML parsing # {#modifications-html-speculative-parsing}

1. Modify [[HTML#speculative-html-parsing]] to add the following line:

1. Each {{Document}} has a <dfn for="Document">prefer no speculative HTML parsing</dfn> boolean. It is initially `false`.
alexnj marked this conversation as resolved.
Show resolved Hide resolved

1. Rewrite step 1 of [start the speculative HTML parser](https://html.spec.whatwg.org/#start-the-speculative-html-parser) to:

1. Optionally, return. The user agent may especially wish to return if <var ignore>parser</var>'s {{Document}}'s [=Document/prefer no speculative HTML parsing=] is `true`, as that indicates the {{Document}} prefers to opt out of speculative HTML parsing.

# Modifications to Document creation # {#modifications-document-creation}

1. Modify [create and initialize a Document object](https://html.spec.whatwg.org/#initialise-the-document-object) under [[HTML#shared-document-creation-infrastructure]] section by inserting the following steps between the current step 9 and 10:
alexnj marked this conversation as resolved.
Show resolved Hide resolved

1. Let |preferNoSpeculativeHTMLParsingHeader| be the result of [getting a structured field value](https://fetch.spec.whatwg.org/#concept-header-list-get-structured-header) given `Prefer-No-Speculative-Parsing` from <var ignore>navigationParams</var>'s [response](https://html.spec.whatwg.org/#navigation-params-response)'s [header list](https://fetch.spec.whatwg.org/#concept-response-header-list).
alexnj marked this conversation as resolved.
Show resolved Hide resolved

1. Let |preferNoSpeculativeHTMLParsing| be `true` if |preferNoSpeculativeHTMLParsingHeader| is not `null` and |preferNoSpeculativeHTMLParsingHeader| is the [boolean](https://httpwg.org/specs/rfc8941.html#boolean) `true`; otherwise `false`.
alexnj marked this conversation as resolved.
Show resolved Hide resolved

1. Modify the current step 10 to set <var ignore>document</var>'s [=Document/prefer no speculative HTML parsing=] to |preferNoSpeculativeHTMLParsing|.