Prefetch

1. Let cookieData be an empty list.

2. If the user agent is not configured to block cookies for request, then set cookieData be the result of gathering cookie data for request’s URL in the cookie store associated with request.

3. Let authenticationEntry be null.

4. If there’s an authentication entry for request and request’s current URL does not include credentials, then set authenticationEntry to that authentication entry.

5. Append a new exchange record whose request is a copy of request, response is null, cookie data is cookieData, and authentication entry is authenticationEntry to redirectChain.

1. Assert: redirectChain is not empty.

2. Assert: redirectChain’s last element’s request is the same as request and its response is null.

3. Set redirectChain’s last element’s response to response.

1. For each exchangeRecord of redirectChain:

   1. Let request be exchangeRecord’s request.

   2. Let cookieData be an empty list.

   3. If the user agent is not configured to block cookies for request, then set cookieData to the result of gathering cookie data for request’s URL in the cookie store associated with request.

   4. If cookieData is not identical to exchangeRecord’s cookie data, then user agents must return true. User agents may also return true if a modification to the cookies applicable to request has occurred in some other way (even though the cookie data may ultimately be identical).

      This gives freedom to use a slightly coarser algorithm, such as monitoring whether the cookies for the URL have been modified at all, or storing a hash, timestamp or revision number instead of the full cookie data.

   5. Let authenticationEntry be null.

   6. If there’s an authentication entry for request and request’s current URL does not include credentials, then set authenticationEntry to that authentication entry.

   7. If authenticationEntry is not identical to exchangeRecord’s authentication entry, then user agents must return true. User agents may also return true if a modification to the authentication entries applicable to request has occurred in some other way.

      This provides similar implementation freedom to that described above for cookies.

2. Return false.

1. Assert: prefetchRecord is in document’s prefetch records.

2. Assert: prefetchRecord’s state is not "canceled".

3. Set prefetchRecord’s state to "canceled".

4. Abort prefetchRecord’s fetch controller. This will cause any ongoing fetch to be canceled and yield a network error.

5. Remove prefetchRecord from document’s prefetch records.

1. Assert: document is fully active.

2. Let currentTime be the current high resolution time for the relevant global object of document.

3. Let expiryTime be currentTime + 300000 (i.e., five minutes).

4. Remove all elements of document’s prefetch records which have the same URL as prefetchRecord and whose state equals "completed".

5. Set prefetchRecord’s state to "completed" and expiry time to expiryTime.

1. Assert: document is fully active.

2. Let currentTime be the current high resolution time for the relevant global object of document.

3. For each record of document’s prefetch records:

   1. If record’s URL is not equal to url, then continue.

   2. If record’s state is not "completed", then continue.

   3. If record’s sandboxing flag set is empty and sandboxFlags is not empty, then continue.

      Strictly speaking, it would still be possible for this to be valid if sandbox flags have been added to the container since prefetch but those flags would not cause an error due to cross origin opener policy. This is expected to be rare and so isn’t handled.

   4. Remove record from document’s prefetch records.

   5. If record’s expiry time is less than currentTime, return null.

   6. If record’s redirect chain has updated credentials, return null.

   7. Return record.

4. Return null.

It’s not obvious, but this doesn’t actually require that the prefetch have received the complete body, just the response headers. In particular, a navigation to a prefetched response might nonetheless not load instantaneously.

It might be possible to use cache response headers to determine when a response can be used multiple times, but given the short lifetime of the prefetch buffer it’s unclear whether this is worthwhile.

1. Let responseOrigin be null.

2. Let responseCOOP be null.

3. Let coopEnforcementResult be the result of creating a cross-origin opener policy enforcement result for navigation given navigable’s active document and documentState’s initiator origin.

4. Let finalSandboxFlags be an empty sandboxing flag set.

5. Let responsePolicyContainer be null.

6. Let urlList be an empty list.

7. For each exchangeRecord in record’s redirect chain:

   1. Let response be exchangeRecord’s response.

   2. Append response’s URL to urlList.

   3. Set responsePolicyContainer to the result of creating a policy container from a fetch response given response and request’s reserved client.

   4. Set finalSandboxFlags to the union of targetSnapshotParams’s sandboxing flags and responsePolicyContainer’s CSP list's CSP-derived sandboxing flags.

   5. Set responseOrigin to the result of determining the origin given response’s URL, finalSandboxFlags, documentState’s initiator origin, and null.

   6. If navigable is a top-level traversable, then:

      1. Set responseCOOP to the result of obtaining a cross-origin opener policy given response and request’s reserved client.

      2. Assert: If finalSandboxFlags is not empty, then responseCOOP’s value is "unsafe-none".

         This is guaranteed since the sandboxing flags of the document cannot change to become non-empty since this was prefetched, and the check was not done for a different window. If this changes, this will need to be able to handle failure of this check.

      3. Set coopEnforcementResult to the result of enforcing a response’s cross-origin opener policy given navigable’s active browsing context, response’s URL, responseOrigin, responseCOOP, coopEnforcementResult, and exchangeRecord’s request's referrer.

8. Set request’s URL list to urlList.

9. Let resultPolicyContainer be the result of determining navigation params policy container given record’s response's URL, documentState’s history policy container, sourceSnapshotParams’s source policy container, null, and responsePolicyContainer.

10. Return a new navigation params, with:

    id

    navigationId

    request

    request

    response

    record’s response

    origin

    responseOrigin

    policy container

    resultPolicyContainer

    final sandboxing flag set

    finalSandboxFlags

    cross-origin opener policy

    responseCOOP

    COOP enforcement result

    coopEnforcementResult

    reserved environment

    request’s reserved client

    navigable

    navigable

    navigation timing type

    navTimingType

    fetch controller

    record’s fetch controller

    commit early hints

    null

    delivery type

    "navigational-prefetch"

    This implies that early hints delivered for prefetched documents won’t be processed. This could be revised in the future if it is common for there to be useful resource hints which are not repeated in the main response headers. Since prefetches aren’t currently served until the response headers arrive, early hints would not be processed any earlier than ordinary response headers. It might be possible for a future specification to allow early hints found during prefetching to be used in some way.

1. If policy is a cross-origin prefetch IP anonymization policy:

   1. If request’s URL's origin is the same as policy’s origin, then return false.

   2. Return true.

2. Assert: policy is null.

3. Return false.

To create a reserved client given a navigable navigable, a URL url and an opaque origin or null isolationOrigin:

1. Let topLevelCreationURL be url.

2. Let topLevelOrigin be null.

3. If isolationOrigin is not null, then:

   1. Set topLevelCreationURL to about:blank.

   2. Set topLevelOrigin to isolationOrigin.

4. Otherwise, if navigable is not a top-level traversable, then:

   1. Let parentEnvironment be navigable’s parent's active document's relevant settings object.

   2. Set topLevelCreationURL to parentEnvironment’s top-level creation URL.

   3. Set topLevelOrigin to parentEnvironment’s top-level origin.

5. Return a new environment whose id is a unique opaque string, target browsing context is navigable’s active browsing context, creation URL is url, top-level creation URL is topLevelCreationURL, and top-level origin is topLevelOrigin.

To create a cross-origin opener policy enforcement result for navigation given a Document activeDocument and an origin initiatorOrigin, return a new cross-origin opener policy enforcement result with

url

activeDocument’s URL

origin

activeDocument’s origin

cross-origin opener policy

activeDocument’s cross-origin opener policy

current context is navigation source

true if activeDocument’s origin is same origin with initiatorOrigin; otherwise false

To create a navigation request given a session history entry entry, an environment settings object fetchClient, a navigable container or null container, and a boolean hasTransientActivation, perform the following steps.

1. Let documentResource be entry’s document state's resource.

2. Let request be a new request, with

   url

   entry’s URL

   policy container

   entry’s document state's history policy container

   client

   fetchClient

   destination

   "document"

   credentials mode

   "include"

   use-URL-credentials flag

   set

   redirect mode

   "manual"

   mode

   "navigate"

   referrer

   entry’s document state's request referrer

   referrer policy

   entry’s document state's request referrer policy

3. If documentResource is a POST resource, then:

   1. Set request’s method to `POST`.

   2. Set request’s body to documentResource’s request body.

   3. Set `Content-Type` to documentResource’s request content-type in request’s header list.

4. If entry’s document state's reload pending is true, then set request’s reload-navigation flag.

5. Otherwise, if entry’s document state's ever populated is true, then set request’s history-navigation flag.

6. If hasTransientActivation is true, then set request’s user-activation to true.

7. If container is non-null:

   1. If container has a browsing context scope origin, then set request’s origin to that browsing context scope origin.

   2. Set request’s destination and initiator type to container’s local name.

8. Return request.

1. Otherwise, if both of the following are true:

   • entry’s URL's scheme is a fetch scheme; and

   • documentResource is null, or allowPOST is true and documentResource’s request body is not failure

   then:

   1. Let request be the result of creating a navigation request given entry, sourceSnapshotParams’s fetch client, navigable’s container, and sourceSnapshotParams’s has transient activation.

   2. Set request’s replaces client id to navigable’s active document's relevant settings object's id.

   3. Let prefetchRecord be the result of finding a matching prefetch record given navigable’s active document, entry’s URL, and targetSnapshotParams’s sandboxing flags.

   4. If documentResource is null and prefetchRecord is not null:

      1. Set navigationParams to the result of creating navigation params from a prefetch record given navigable, entry’s document state, navigationId, navTimingType, request, prefetchRecord, targetSnapshotParams, and sourceSnapshotParams.

      2. Copy prefetch cookies given prefetchRecord’s isolated partition key and navigationParams’s reserved environment.

         This copy is complete before continuing, in the sense that subresource fetches, document.cookie, etc. can observe the cookies. If the prefetch never reached a cross-site URL, there will be no cookies to copy.

   5. Otherwise:

      1. Let coopEnforcementResult be the result of creating a cross-origin opener policy enforcement result for navigation given navigable’s active document and entry’s document state's initiator origin.

      2. Set navigationParams to the result of creating navigation params by fetching given request, entry, coopEnforcementResult, navigable, sourceSnapshotParams, targetSnapshotParams, cspNavigationType, navigationId, and navTimingType.

To create navigation params by fetching given a request request, a session history entry entry, a cross-origin opener policy enforcement result coopEnforcementResult, a navigable navigable, a source snapshot params sourceSnapshotParams, a target snapshot params targetSnapshotParams, a string cspNavigationType, a navigation ID or null navigationId, a NavigationTimingType navTimingType, and an optional prefetch record prefetchRecord, perform the following steps.

1. Assert: this is running in parallel.

2. Assert: request’s URL is entry’s URL.

3. Assert: request’s mode is "navigate".

4. Assert: request’s redirect mode is "manual".

5. Assert: request’s reserved client is null.

6. Let response be null.

7. Let responseOrigin be null.

8. Let fetchController be null.

9. Let finalSandboxFlags be an empty sandboxing flag set.

10. Let responsePolicyContainer be null.

11. Let responseCOOP be a new cross-origin opener policy.

12. Let locationURL be null.

13. Let currentURL be request’s current URL.

14. Let commitEarlyHints be null.

15. Let isolationOrigin be null.

16. If prefetchRecord was given:

    1. Let isolationSite be prefetchRecord’s isolated partition key[0].

    2. Assert: isolationSite is an opaque origin.

    3. Set isolationOrigin to isolationSite.

17. While true:

    1. If request’s reserved client is not null and currentURL’s origin is not the same as request’s reserved client's creation URL's origin, then:

       1. Run the environment discarding steps for request’s reserved client.

       2. Set request’s reserved client to null.

       3. Set commitEarlyHints to null.

    2. If request’s reserved client is null, then set request’s reserved client to the result of creating a reserved client given navigable, currentURL and isolationOrigin.

    3. If the result of should navigation request of type be blocked by Content Security Policy? given request and cspNavigationType is "Blocked", then set response to a network error and break. [CSP]

    4. If prefetchRecord was given, then:

       1. Let purpose be a List containing the Token prefetch.

       2. If prefetchRecord’s anonymization policy requires anonymity for request, then:

          1. Add a parameter whose key is "anonymous-client-ip" and whose value is true to the prefetch token in purpose.

          2. The user agent must use a connection which anonymizes the client IP address (e.g., using a proxy) when fetching request, or set response to a network error and break.

             At the moment, how IP anonymization is achieved is handwaved. This will probably be done in an implementation-defined manner using some kind of proxy or relay. Ideally this would be plumbed down to obtain a connection, and possibly even the mechanism could be further standardized.

       3. Set a structured field value given (`Sec-Purpose`, purpose) in request’s header list.

          Implementations might also send vendor-specific headers, like Chromium’s `Purpose`/`prefetch`, Mozilla’s `X-moz`/`prefetch`, and WebKit’s `X-Purpose`/`preview`, for compatibility with existing server software. Over time we hope implementers and server software authors will adopt this common header.

       4. If request’s current URL is not potentially trustworthy, then set response to a network error and break.

          This is intended to both reduce the likelihood of prefetch traffic being visible to an on-path attacker, and to encourage the use of cryptographic schemes over public networks.

       5. Let proposedPartitionKey be the result of determining the network partition key given request’s reserved client.

       6. If proposedPartitionKey is not equal to prefetchRecord’s source partition key and request’s referrer policy is not in the list of sufficiently strict speculative navigation referrer policies, then set response to a network error and break.

          In practice, this means that cross-site prefetches will abandon rather than expose more information about the referrer URL than the origin.

       7. If request cannot be fetched given prefetchRecord’s anonymization policy for an implementation-defined reason, then set response to a network error and break.

          This explicitly acknowledges that implementations might have additional restrictions. For instance, anonymized traffic might not be possible to some hosts, such as those that are not publicly routable and those that have traffic advice declining private prefetch traffic.

       8. Append request to prefetchRecord’s redirect chain.

    5. Set response to null.

    6. If fetchController is null, then set fetchController to the result of fetching request, with processEarlyHintsResponse set to processEarlyHintsResponse as defined below, processResponse set to processResponse as defined below, and useParallelQueue set to true.

       Let processEarlyHintsResponse be the following algorithm given a response earlyResponse:

       1. If prefetchRecord was given and commitEarlyHints is null, then set commitEarlyHints to the result of processing early hint headers given earlyResponse and request’s reserved client.

       Let processResponse be the following algorithm given a response fetchedResponse:

       1. Set response to fetchedResponse.

    7. Otherwise, process the next manual redirect for fetchController.

    8. Wait until either response is non-null, or navigable’s ongoing navigation changes to no longer equal navigationId.

       If the latter condition occurs, then abort fetchController, and return. Otherwise, proceed onward. This aborts prefetches the moment a navigation starts, which might not be desirable.

    9. If request’s body is null, then set entry’s document state's resource to null.

    10. Set responsePolicyContainer to the result of creating a policy container from a fetch response given response and request’s reserved client.

    11. Set finalSandboxFlags to the union of targetSnapshotParams’s sandboxing flags and responsePolicyContainer’s CSP list's CSP-derived sandboxing flags.

    12. Set responseOrigin to the result of determining the origin given response’s URL, finalSandboxFlags, entry’s document state's initiator origin, and null.

    13. If navigable is a top-level traversable, then:

        1. Set responseCOOP to the result of obtaining a cross-origin opener policy given response and request’s reserved client.

        2. If prefetchRecord was given, then set responseCOOP’s reporting endpoint and report-only reporting endpoint to null. This allows COOP violation reports to be suppressed until the prefetch is used.

        3. Set coopEnforcementResult to the result of enforcing a response’s cross-origin opener policy given navigable’s active browsing context, request’s URL, responseOrigin, responseCOOP, coopEnforcementResult, and request’s referrer.

        4. If finalSandboxFlags is not empty and responseCOOP’s value is not "unsafe-none", then set response to an appropriate network error and break.

    14. If response is not a network error, navigable is a child navigable, and the result of performing a cross-origin resource policy check with navigable’s container document's origin, navigable’s container document's relevant settings object, request’s destination, response, and true is blocked, then set response to a network error and break.

    15. If prefetchRecord was given, then:

        1. Update the response for its redirect chain given request and response.

        2. Let hypotheticalEnvironment be the result of creating a reserved client given navigable, currentURL, and null.

        3. Let hypotheticalPartitionKey be the result of determining the network partition key given hypotheticalEnvironment.

        4. Let hasConflictingCredentials be true if hypotheticalPartitionKey is not equal to prefetchRecord’s source partition key and there are credentials associated with currentURL and hypotheticalPartitionKey, and false otherwise.

        5. If hasConflictingCredentials is true:

           1. Let loadingModes be the result of getting the supported loading modes for response.

           2. If loadingModes does not contain `uncredentialed-prefetch` then set prefetchRecord’s has conflicting credentials to true.

              This does not immediately abort the prefetch or stop following redirects, because doing so might reveal whether or not the user has stored state outside the current partition, before the user navigates. Instead, the prefetch continues as though there were no conflicting credentials, except that the prefetch cannot actually be used. User agents might wish to report a warning to the console or otherwise inform authors that this has happened.

    16. Set locationURL to response’s location URL given currentURL’s fragment.

    17. If locationURL is failure or null, then break.

    18. Assert: locationURL is a URL.

    19. Set entry’s serialized state to StructuredSerializeForStorage(null).

    20. Let oldDocState be entry’s document state.

    21. Set entry’s document state to a new document state, with:

        history policy container

        a clone of oldDocState’s history policy container

        request referrer

        oldDocState’s request referrer

        request referrer policy

        oldDocState’s request referrer policy

        origin

        oldDocState’s origin

        resource

        oldDocState’s resource

        ever populated

        oldDocState’s ever populated

        navigable target name

        oldDocState’s navigable target name

    22. If locationURL’s scheme is not an HTTP(S) scheme, then:

        1. Set entry’s document state's resource to null.

        2. Break.

    23. Set currentURL to locationURL.

    24. Set entry’s URL to currentURL.

18. If locationURL is a URL whose scheme is not a fetch scheme, then return a new non-fetch scheme navigation params, with:

    initiator origin

    request’s current URL's origin

19. If any of the following are true:

    • response is a network error;

    • locationURL is failure; or

    • locationURL is a URL whose scheme is a fetch scheme

    then return null.

20. Let resultPolicyContainer be the result of determining navigation params policy container given response’s URL, entry’s document state's history policy container, sourceSnapshotParams’s source policy container, null, and responsePolicyContainer.

21. Return a new navigation params, with:

    id

    navigationId

    request

    request

    response

    response

    origin

    responseOrigin

    policy container

    resultPolicyContainer

    final sandboxing flag set

    finalSandboxFlags

    cross-origin opener policy

    responseCOOP

    COOP enforcement result

    coopEnforcementResult

    reserved environment

    request’s reserved client

    navigable

    navigable

    navigation timing type

    navTimingType

    fetch controller

    fetchController

    commit early hints

    commitEarlyHints

1. Let sourceSnapshotParams be the result of snapshotting source snapshot params given document.

2. Let targetSnapshotParams be the result of snapshotting target snapshot params given document’s node navigable.

3. Set prefetchRecord’s source partition key to the result of determining the network partition key given document’s relevant settings object.

4. Assert: prefetchRecord’s URL's scheme is an HTTP(S) scheme.

5. Append prefetchRecord to document’s prefetch records

6. Set prefetchRecord’s sandboxing flag set to the result of determining the creation sandboxing flags for document’s browsing context given document’s node navigable's container.

7. Let referrerPolicy be prefetchRecord’s referrer policy if prefetchRecord’s referrer policy is not the empty string, and document’s policy container's referrer policy otherwise.

8. Let documentState be a new document state with

   request referrer policy

   referrerPolicy

   initiator origin

   document’s origin

9. Let entry be a new session history entry with

   URL

   prefetchRecord’s URL

   document state

   documentState

10. Let request be the result of creating a navigation request given entry, document’s relevant settings object, document’s node navigable's container, and false.

11. Let coopEnforcementResult be the result of creating a cross-origin opener policy enforcement result for navigation given document and document’s origin.

12. Let global be document’s relevant global object.

13. In parallel:

    1. Let navigationParams be the result of creating navigation params by fetching given request, entry, coopEnforcementResult, document’s node navigable, sourceSnapshotParams, targetSnapshotParams, "other", null (navigationId), "navigate", and prefetchRecord prefetchRecord.

    2. If navigationParams’s response does not support prefetch, then set navigationParams to null.

    3. If prefetchRecord has conflicting credentials, then set navigationParams to null.

       This means that if any cross-partition origin along the redirect chain had credentials (and did not override this behavior using `Supports-Loading-Mode`), the prefetch is discarded. This reduces the chance of the user observing a logged-out page when they are logged in.

    4. Queue a global task on the networking task source, given global, to:

       1. If navigationParams is not a navigation params, then cancel and discard prefetchRecord given document and abort these steps.

       2. Assert: navigationParams’s response is the response of prefetchRecord’s redirect chain's last element.

       3. Complete prefetchRecord given document.

1. Let status be response’s status.

2. Assert: status is not a redirect status.

3. If status is not an ok status, then return false.

   In particular, this means that error responses aren’t stored and will be retried when a navigation occurs. This increases the likelihood of navigations succeeding if the error was transient or due to the request being for prefetch. It also gives server software a simple way to refuse to handle requests which carry a `Sec-Purpose` request header indicating prefetch.

4. Return true.

1. Let isolatedCookieStore be the cookie store associated with isolatedPartitionKey.

2. For each cookie cookie in isolatedCookieStore.

   1. Remove cookie from isolatedCookieStore.

   2. A user agent may ignore a cookie in its entirety. If so, continue.

      This is consistent with [COOKIES] expressly permitting this when receiving a cookie.

   3. Let topLevelSite be null.

   4. If environment’s target browsing context is a top-level browsing context:

      1. Set topLevelSite to the result of obtaining a site given tuple origin ("https", cookie’s domain, null, null).

         The use of the "https" scheme and null port here is arbitrary because cookies are visible across schemes and ports, in contrast to the usual same origin policy. The user agent’s choice of associated cookie store, therefore, cannot be sensitive to either.
      When performing a prefetch in a top-level browsing context, the request (including all redirects) is preparing for a top-level navigation. environment’s top-level site changes as redirects are followed, and since a redirect might be cross-site, environment’s top-level site might have changed since a given cookie was received. However, since the navigation is top-level, the origin delivering the cookie would have been the top-level site at the time. Since the cookie’s domain has to be same-site with an origin delivering it, the cookie’s domain can be used to determine the correct top-level site.

   5. Otherwise:

      1. Let topLevelOrigin be environment’s top-level origin.

      2. If topLevelOrigin is null, then set topLevelOrigin to environment’s top-level creation URL's origin.

      3. Assert: topLevelOrigin is an origin.

      4. Set topLevelSite be the result of obtaining a site given topLevelOrigin.

      When performing a prefetch in a child navigable, the top-level site is determined by the top-level traversable that contains it. Since that doesn’t change as redirects are followed, environment can be used to establish the top-level site.

   6. Let secondKey be null or an implementation-defined value.

      secondKey is expected to match the value it would have had if this response had been processed as part of an ordinary navigation in environment’s target browsing context.

   7. Let destinationPartitionKey be (topLevelSite, secondKey).

   8. Let cookieStore be the cookie store associated with destinationPartitionKey.

   9. Let newCookie be a copy of cookie.

   10. Set newCookie’s creation-time and last-access-time to the current date and time.

   11. If cookieStore contains a cookie existingCookie with the same name, domain and path as the newly created cookie:

       1. Set the creation-time of newCookie to existingCookie’s creation-time.

       2. Remove existingCookie from cookieStore.

   12. Insert newCookie into cookieStore.

       This remove-and-insert pattern is consistent with what happens when receiving a cookie.

1. Let cookieList be the set of cookies from cookieStore that meet all of the following requirements:

   • one of the following applies:

     • the cookie’s host-only flag is true and url’s canonicalized host is identical to the cookie’s domain

     • the cookie’s host-only flag is false and url’s canonicalized host domain-matches the cookie’s domain

   • url’s path path-matches the cookie’s path

   • if the cookie’s secure-only-flag is true, then url’s scheme is "https"

2. Sort cookieList lexicographically by name, and by value if names are equal.

   Since both are octet sequences, Unicode collation rules do not apply.

3. Let cookieData be an empty list.

4. For each cookie in cookieList:

   1. Append (cookie’s name, cookie’s value) to cookieData.

5. Return cookieData.