From 1bebea88d0caae1f971a66130becc7003785e11b Mon Sep 17 00:00:00 2001 From: Patrick Meenan Date: Fri, 16 Dec 2022 11:58:58 -0500 Subject: [PATCH] Updated the proposal to reflect the landing of changes in fetch --- EXPLAINER.md | 34 ++++++--------- index.bs | 116 +++++++++++---------------------------------------- 2 files changed, 37 insertions(+), 113 deletions(-) diff --git a/EXPLAINER.md b/EXPLAINER.md index 4668a44..2066d6d 100644 --- a/EXPLAINER.md +++ b/EXPLAINER.md @@ -6,16 +6,12 @@ Browsers may also use this heuristic resource priority to delay sending certain requests in order to avoid bandwidth contention of these resources with more critical ones. -Currently web developers have very little control over the heuristic -priority of loaded resources, other than speeding up their discovery -using ``. Browsers make many assumptions on the priority of resources based on the resource's type (AKA its request destination), and based on its location in the containing document. -This document will detail use cases and an API/markup sketch that will -provide developers with the control to indicate a resource's -relative priority to the browser for the browser to use when making +This document will detail use cases and show how developers can indicate a +resource's relative priority to the browser for the browser to use when making loading prioritization decisions. It is important to note that changing the priority of one resource usually @@ -25,11 +21,9 @@ user experience but correctly tagging a few resources that the browser would otherwise not load optimally can have a huge benefit. ### Adoption path -Markup based signal should be added in a way such that non-supporting -browsers will simply ignore them and load all resources, potentially not -in the intended priority and dependency. Script based signaling APIs -should be created in a way that non-supporting browsers simply ignore -the signals. +The markup signals and script APIs are backward-compatible in that +non-supporting browsers will simply ignore them and load all resources as they +normally would without the additional hints. ## Out of scope * Anything besides an initial priority signal for the loading of the @@ -40,27 +34,23 @@ the signals. ## Solution -We propose to address the above use-cases using the following concepts: +Priority Hints addresses the above use-cases using the following concepts: -* We will define a new standard `fetchpriority` attribute to signal to the browser the relative priority of a resource. +* A `fetchpriority` attribute to signal to the browser the relative priority of a resource. * The `fetchpriority` attribute may be used with elements including link, img, script and iframe. This keyword hints to the browser the relative fetch priority a developer intends for a resource to have. Consider it an upgrade/downgrade mechanism for hinting at resource priority. -* The `fetchpriority` attribute will have three states that will map to current browser priorities: +* The `fetchpriority` attribute will has three states that will influence the current browser priorities: - * `high` - The developer considers the resource as being important relative to other resources of the same type. - * `low` - The developer considers the resource as being less important relative to other resources of the same type. + * `high` - The developer considers the resource as being important relative to the default priority for resources of the same type. + * `low` - The developer considers the resource as being less important relative to the default priority for resources of the same type. * `auto` - The developer does not indicate a preference and defers to the browser's default heuristics. This also serves as the default value if the attribute is not specified. -* Developers would annotate resource-requesting tags such as img, script and link using the `fetchpriority` attribute as a hint of the preferred priority with which the resource should be fetched. - -* Developers would be able to specify that certain resources are more or less important than others using this attribute. It would act as a hint of the intended priority rather than an instruction to the browser. - * With the `fetchpriority` attribute, the browser should make an effort to respect the developer's preference for the priority of a resource when fetching it. Note that this is intentionally weak language, allowing for a browser to apply its own preferences for resource priority or heuristics if deemed important. * Priority Hints compliment existing browser loading primitives such as preload. Preload is a mandatory fetch for a resource that is necessary for the current navigation. Priority Hints can hint that a resource's priority should be lower or higher than its default, and can also be used to provide more granular prioritization to preloads. -* The JavaScript fetch() API will expose the priority hint as a `priority` property of the Request using the same `high`, `low` and `auto` values as the HTML `fetchpriority` attribute. +* The JavaScript fetch() API exposes the priority hint as a [`priority` property of RequestInit](https://fetch.spec.whatwg.org/#dom-requestinit-priority) using the same `high`, `low` and `auto` values as the HTML `fetchpriority` attribute. This is how we conceptually think about different resource types under the hood in browsers today. It may translate well to user-space where different types of content share similar properties. @@ -120,4 +110,4 @@ function autocomplete() { ``` ## Further reading -For a more complete overview of the Priority Hints proposal, please see the [draft specification](https://wicg.github.io/priority-hints/). +For a more complete overview of Priority Hints, please see the [specification](https://wicg.github.io/priority-hints/). diff --git a/index.bs b/index.bs index c3463e6..dc3aebd 100644 --- a/index.bs +++ b/index.bs @@ -55,24 +55,11 @@ urlPrefix: https://html.spec.whatwg.org/multipage/iframe-embed-object.html; spec urlPrefix: https://html.spec.whatwg.org/multipage/indices.html; spec: HTML; type: dfn; url: #elements-3; text: List of elements; urlPrefix: https://fetch.spec.whatwg.org; spec: FETCH; - type: dfn; url: #concept-request; text: fetch request; - type: dfn; url: #concept-request; text: request; - type: dfn; url: #concept-request-url; text: request URL; type:dfn; text:destination - type:interface; text:request - type: dfn; url: #concept-fetch; text: fetch; 
 {
-    "PRELOAD": {
-        "authors": [
-            "Ilya Grigorik", "Yoav Weiss"
-        ],
-        "href": "https://w3c.github.io/preload/",
-        "publisher": "W3C",
-        "title": "Preload"
-    },
     "RFC5988": {
         "authors": [
             "Mark Nottingham"
@@ -90,8 +77,8 @@ urlPrefix: https://fetch.spec.whatwg.org; spec: FETCH;
       This specification describes a browser API enabling developers to signal the priority of each resource they need to download.
       It introduces the
       fetchpriority attribute that may be used with HTML elements such as
-      <{img}>, <{link}>, <{script}> and <{iframe}> and the priority attribute
-      on the {{Request|RequestInfo}} of [[fetch#fetch-method|fetch]]. 
+      <{img}>, <{link}>, <{script}> and <{iframe}> and the {{RequestInit/priority}} attribute
+      on the {{Request|RequestInit}} of [[fetch#fetch-method|fetch]]. 
     

   
   

@@ -109,11 +96,10 @@ urlPrefix: https://fetch.spec.whatwg.org; spec: FETCH;
       to their heuristic priority. Browsers might also use this heuristic resource priority to delay sending certain requests
       in order to avoid bandwidth contention of these resources with more critical ones.

 
-    
Currently web developers have very little control over the heuristic priority of loaded resources, other than speeding
-      up their discovery using <link rel=preload>([[PRELOAD|Preload]]). Browsers mostly determine a request's priority based on the
+    
Browsers mostly determine a request's priority based on the
       request's destination, and location in the containing document if applicable.

 
-    
This document details use cases and modifications to [[FETCH|Fetch]] and [[HTML|HTML]] markup that will provide developers
+    
This document details use cases and modifications to [[FETCH|Fetch]] and [[HTML|HTML]] markup that provide developers
       control to indicate a resource's relative priority to the browser, enabling the browser to act on those indications to influence
       the request's overall priority in ways described in the Effects of Priority Hints section.
     

@@ -134,14 +120,16 @@ urlPrefix: https://fetch.spec.whatwg.org; spec: FETCH;
       a developer intends for a resource to have.

 
     
    
-      
  • The fetchpriority attribute will have three states:
+      
  • The fetchpriority attribute has three states:
         
      
           
    • 
-            high - The developer considers the resource as being important relative to other resources of the
+            high - The developer considers the resource as being
+            important relative to the default priority for resources of the
             same type.
           
      • 
           
    • 
-            low - The developer considers the resource as being less important relative to other resources of
+            low - The developer considers the resource as being
+            less important relative to the default priority for resources of
             the same type.
           
      • 
           
    • 
@@ -183,71 +171,17 @@ urlPrefix: https://fetch.spec.whatwg.org; spec: FETCH;
       
       
         high
-        Signal a high-priority fetch relative to other resources of the same type.
+        Signal a high-priority fetch relative to the default priority for resources of the same type.
       
         low
-        Signal a low-priority fetch relative to other resources of the same type.
+        Signal a low-priority fetch relative to the default priority for resources of the same type.
       
         auto
-        Signal automatic determination of fetch priority relative to other resources of the same type.
+        Signal automatic determination of fetch priority.
     
 
     
      Fetch Integration
      
-    This section will be removed once the [[FETCH|Fetch]] specification has been modified.
-    
        
-      
      1. 
-        
        We extend the [=request=] definition:
        
-        
        
-        A [=request=] has an associated
-        priority, which is
-        "high",
-        "low" or
-        "auto".
-        Unless stated otherwise it is "auto".
-        
        
-
-      
      2. We extend the {{Request}} interface as follows:
-        
        -        partial interface Request {
-          readonly attribute FetchPriority priority;
-        };
-
-        partial dictionary RequestInit {
-          FetchPriority priority;
-        };
-        
        
-
-      
      3. We add the following to the "For web developers (non-normative)"" note in the
-        [[fetch#request-class|Request class]] constructor:
        
-        
        
-        
        {{RequestInit/priority}}
-        
        A string to set request's {{Request/priority}}.
-        
        
-
-      
      4. We add to step 12 of the new Request
-        constructor steps:
        
-        
        
-        
        priority
-        
        request's priority.
-        
        
-
-      
      5. We rename references to {{Request}}'s opaque priority to
-        internalpriority:
        
-        
          
-        
        1. A request has an associated internalpriority (null or a user-agent-defined object). Unless otherwise stated it is null.
-        
        2. We replace step 12 of new Request constructor steps with :
          
-        
          
-        
          internalpriority
-        
          request's internalpriority.
-        
          
-        
        
-
-      
      6. We modify step 14 in the process of [=fetch=] to read:
        
-        
        If request's internalpriority is null, then use
-        request's priority, initiator and
-        destination appropriately in setting request's
-        internalpriority to a user-agent-defined object.
        
-    
      
+    
      The {{RequestInit/priority}} attribute is documented in the [[FETCH|Fetch]] specification.
      
 
     
      HTML Integration
      
     This section will be removed once the [[HTML|HTML]] specification has been modified.
@@ -295,11 +229,11 @@ urlPrefix: https://fetch.spec.whatwg.org; spec: FETCH;
           content attribute, limited to only known values.
      
       
    • We add a step to [=update the image data|Updating the image data=] before fetching the
           image:
      
-        
      Set request's {{Request/priority}} to the current state of the element's
+        
      Set request's priority to the current state of the element's
           fetchpriority attribute.
      
       
    • We add a step to [=Reacting to environment changes=] when setting the image request's
           image data, before the request is fetched:
      
-        
      Set request's {{Request/priority}} to the current state of the element's
+        
      Set request's priority to the current state of the element's
           fetchpriority attribute.
      
       
    • We modify the [=List of elements=] to include the 
         fetchpriority attribute on the <{img}> element.
@@ -330,11 +264,11 @@ urlPrefix: https://fetch.spec.whatwg.org; spec: FETCH;

  • We extend [=create a link element request=] of [=Fetching and processing a resource from a link element=] by adding a step before returning the request:

    -

    Set request's {{Request/priority}} to the current state of +

    Set request's priority to the current state of el's fetchpriority content attribute.

  • We extend the [=fetch and process the linked resource=] algorithm of [=modulepreload=] links by adding a step before setting the render-blocking state:

    -

    Let {{Request/priority}} be the current state of the element's +

    Let priority be the current state of the element's fetchpriority attribute.

  • We modify the [=List of elements=] to include the fetchpriority attribute on the <{link}> element. @@ -369,12 +303,12 @@ urlPrefix: https://fetch.spec.whatwg.org; spec: FETCH; include the fetchpriority attribute.

  • We extend the [=Script fetch options=] struct:

    fetchpriority - The - {{Request/priority}} for the initial [=fetch=].

    + priority for the initial [=fetch=].

  • We extend [=default classic script fetch options=] to include "auto" as the default value for fetchpriority.
  • We extend [=set up the classic script request=] to set request's - {{Request/priority}} to option's + priority to option's fetchpriority

  • We insert a step before step 24 of [=prepare a script=]:

    Let fetchpriority be the current state of the element's fetchpriority is fetchpriority.

  • We extend [=set up the module script request=] to set request's - {{Request/priority}} to option's + priority to option's fetchpriority
  • We modify the [=List of elements=] to include the fetchpriority attribute on the <{script}> @@ -412,7 +346,7 @@ urlPrefix: https://fetch.spec.whatwg.org; spec: FETCH; content attribute, limited to only known values.

  • We modify step 5 (the resource creation step) of [=shared attribute processing steps for iframe and frame elements=] to include:

    -

    ...and whose {{Request/priority}} is the current state of element's +

    ...and whose priority is the current state of element's fetchpriority content attribute

  • We modify the [=List of elements=] to include the fetchpriority attribute on the <{iframe}> @@ -599,13 +533,13 @@ urlPrefix: https://fetch.spec.whatwg.org; spec: FETCH;

    As above examples illustrate, fetchpriority can be specified via declarative markup, Link HTTP header ([[RFC5988|RFC5988]]), - or scheduled via JavaScript.

    + or scheduled via JavaScript.

    Adoption path

    -

    Markup-based signals should be added in a way such that non-supporting browsers will simply ignore them and load all - resources, potentially not with the intended priority and dependency. Script-based signaling APIs should be created - in a way that non-supporting browsers simply ignore the signals.

    +

    The markup signals and script APIs are backward-compatible in that + non-supporting browsers will simply ignore them and load all resources as they + normally would without the additional hints.

    Out of scope