Background Fetch

To queue a bgfetch task on an optional eventLoop (an event loop , defaulting to the caller’s this 's relevant settings object 's responsible event loop ) with steps (steps), queue a task on eventLoop using the background fetch task source to run steps .

To perform a background fetch for bgFetch (a background fetch ), run these steps:

1. Let swRegistration be bgFetch ’s service worker registration .

2. Let settledFetches be 0.

3. Let immediateFailure be false.

4. Let failureReason be the empty string.

5. For each record in bgFetch ’s records , run these steps in parallel :

   1. Complete a record for bgFetch and record .

   2. Let result be record ’s response data 's result .

   3. If failureReason is not the empty string:

      1. Assert: result is not "redundant" .

      2. Set failureReason to result .

   4. Increment settledFetches by 1.

   5. If result is "download-total-exceeded" , then set immediateFailure to true.

6. Wait for settledFetches to be bgFetch ’s records 's size , or immediateFailure to be true.

7. If immediateFailure is true, set bgFetch ’s abort all flag .

   Note: The complete a record algorithm listens to this flag and terminates the fetch when set.

8. Enqueue the following steps to swRegistration ’s active background fetches edit queue :

   1. Let activeBgFetches be swRegistration ’s active background fetches .

   2. Let id be bgFetch ’s id .

   3. If activeBgFetches contains background fetch bgFetch , then remove activeBgFetches [ id ].

   4. Otherwise, set failureReason to "aborted" .

      Note: This handles a race condition where abort() was successfully called but one of the fetches failed at the same time. If we’ve returned true from abort() , this ensures we fire the related abort event.

   5. If failureReason is not the empty string, then:

      1. Set bgFetch ’s result to "failure" .

      2. Set bgFetch ’s failure reason to failureReason .

   6. Otherwise, set bgFetch ’s result to "success" .

   7. Update background fetch instances for bgFetch .

   8. Let eventName be the empty string.

   9. Let eventConstructor be null.

   10. If failureReason is "aborted" , then:

       1. Set eventName to " backgroundfetchabort ".

       2. Set eventConstructor to BackgroundFetchEvent .

   11. Otherwise, if failureReason is not the empty string, then:

       1. Set eventName to " backgroundfetchfail ".

       2. Set eventConstructor to BackgroundFetchUpdateUIEvent .

   12. Otherwise:

       1. Set eventName to " backgroundfetchsuccess ".

       2. Set eventConstructor to BackgroundFetchUpdateUIEvent .

   13. Fire a functional event named eventName using eventConstructor on swRegistration with the following properties:

       registration

       The result of getting a BackgroundFetchRegistration instance for bgFetch in the event object’s relevant Realm .

       Then run these steps with dispatchedEvent in parallel :

       1. Wait until dispatchedEvent is not active .

          ServiceWorker/1348 .

       2. Unset bgFetch ’s records available flag .

       3. Update background fetch instances for bgFetch .

To complete a record for bgFetch (a background fetch ) and record (a background fetch record ), run these steps:

1. Let responseData be record ’s response data .

2. Let downloadTotal be bgFetch ’s download total if it is not 0, otherwise infinity.

3. Wait for bgFetch ’s paused flag to be unset.

4. Let request be a copy of record ’s request .

   Note: At this point the request is entirely held in storage, even if it started as a stream.

5. Set request ’s keepalive to true.

6. Set request ’s service-workers mode to " none ".

7. Let rangeStart be the length of responseData ’s bytes .

8. If rangeStart is not 0, then add a range header to request with rangeStart .

   Note: If the rangeStart is 0, a normal request is made. This allows the initial request to make use of content encoding, since Accept-Encoding: identity is added to requests with a range header.

9. Let fetchAttemptComplete be false.

10. Let lastTransmittedSize be 0.

11. Fetch request .

    The remainder of this step uses fetch "callbacks" which currently queue tasks. This isn’t desirable or possible here, so let’s pretend that tasks aren’t queued. ( issue )

    To process request body for request , run these steps:

    1. Let transmittedSize be request ’s body 's transmitted bytes .

    2. Increment bgFetch ’s uploaded by transmittedSize minus lastTransmittedSize .

    3. Set lastTransmittedSize to transmittedSize .

    4. Update background fetch instances for bgFetch .

    To process response for response , run these steps:

    1. If response is a network error , then:

       1. If the resource is temporarily unavailable and request ’s method is ` GET `, then wait until the resource is not temporarily unavailable , then set fetchAttemptComplete to true and abort these steps.

          Note: If request ’s method is not ` GET `, reissuing the request may have unwanted side effects. If a standard method to resume requests becomes available, it’ll be adopted here.

       2. If response is an aborted network error , then set responseData ’s result to "aborted" , otherwise "fetch-error" .

       3. Set fetchAttemptComplete to true, and abort these steps.

    2. If response ’s status is 206 , then:

       1. If validate a partial response for rangeStart , response , and responseData ’s response returns invalid, then:

          1. Set responseData ’s result to "fetch-error" .

          2. Set fetchAttemptComplete to true.

          3. Terminate the ongoing fetch, and abort these steps.

    3. Otherwise:

       1. Set responseData ’s result to "redundant" .

       2. Set responseData to a new background fetch response .

       3. Set record ’s response data to responseData .

          Note: The create record objects algorithm may hold a reference to the previous background fetch response .

       4. Update background fetch instances for bgFetch .

    4. If rangeStart is 0 or response ’s status is not 206 , then set responseData ’s response to a copy of response except for its body .

    5. Let stream be the response body 's stream .

    6. Whenever one or more bytes are transmitted from stream , let bytes be the transmitted bytes and run these steps:

       1. If bgFetch ’s stored body bytes total plus the size of bytes is greater than downloadTotal , then:

          1. Cancel stream .

          2. Set responseData ’s result to "download-total-exceeded" , fetchAttemptComplete to true, and abort these steps.

       2. Append bytes to responseData ’s bytes .

       3. If the previous step fails due to exceeding a quota limit, set responseData ’s result to "quota-exceeded" , fetchAttemptComplete to true, and abort these steps.

       4. Update background fetch instances for bgFetch .

    7. If at any point the bytes transmission for stream is done normally, then:

       1. If response ’s status is 206 , then:

          1. Let firstBytePos , lastBytePos , and completeLength be the result of extracting content-range values from response .

          2. If completeLength is not null, and equal to the length of responseData ’s bytes , set responseData ’s result to "success" .

             Note: Although we ask for the whole resource, or the remainder of the resource, the server may not have returned the remainder, in which case we need to make an additional request.

       2. Otherwise, if response ’s status is not an ok status , set responseData ’s result to "bad-status" .

       3. Otherwise, set responseData ’s result to "success" .

       4. Set fetchAttemptComplete to true.

    8. If at any point stream becomes errored , then:

       1. If the resource is temporarily unavailable and request ’s method is ` GET `, then wait until the resource is not temporarily unavailable , then set fetchAttemptComplete to true.

       2. Otherwise, set responseData ’s result to "fetch-error" and fetchAttemptComplete to true.

12. Let result be the empty string.

13. Run these steps, but abort when bgFetch ’s paused flag or abort all flag is set:

    1. Wait for fetchAttemptComplete to be true.

    2. Set result to responseData ’s result .

14. If aborted , then:

    1. If bgFetch ’s paused flag is set, then assert request ’s method is ` GET `.

    2. If bgFetch ’s abort all flag is set, then set responseData ’s result to "aborted" .

    3. Set result to responseData ’s result .

       Note: The result is stored now, as terminating the fetch may change the result.

    4. Terminate the ongoing fetch.

15. If result is the empty string, then complete a record for bgFetch and record .

To update background fetch instances for bgFetch (a background fetch ), enqueue the following steps to bgFetch ’s update handling queue :

1. Let downloaded be bgFetch ’s stored body bytes total .

2. Let uploaded be bgFetch ’s uploaded .

3. Let result be bgFetch ’s result .

4. Let failureReason be bgFetch ’s failure reason .

5. Let recordsAvailable be true if bgFetch ’s records available flag is set, otherwise false.

6. For each environment settings object env whose origin is equal to bgFetch ’s service worker registration 's scope URL 's origin , queue a bgfetch task on env ’s responsible event loop to run these steps:

   1. Let bgFetchRegistration be the instance of BackgroundFetchRegistration within the relevant realm whose background fetch is equal to bgFetch , or null if none exists.

      Note: There will be at most one per environment, due to the get a BackgroundFetchRegistration instance algorithm.

   2. If bgFetchRegistration is null, then abort these steps.

   3. If recordsAvailable is false and bgFetchRegistration ’s records available flag is set, then unset bgFetchRegistration ’s records available flag .

   4. If bgFetchRegistration ’s result is not the empty string, then abort these steps.

      Note: This prevents progress being reported after the background fetch has settled. This is possible when the operation has aborted, but some fetches haven’t yet terminated.

   5. If all of the following are true:

      • bgFetchRegistration ’s downloaded is equal to downloaded .

      • bgFetchRegistration ’s uploaded is equal to uploaded .

      • bgFetchRegistration ’s result is equal to result .

      • bgFetchRegistration ’s failure reason is equal to failureReason .

      Then abort these steps.

   6. Set bgFetchRegistration ’s downloaded to downloaded .

   7. Set bgFetchRegistration ’s uploaded to uploaded .

   8. Set bgFetchRegistration ’s result to result .

   9. Set bgFetchRegistration ’s failure reason to failureReason .

   10. Fire an event named " progress " at bgFetchRegistration .

   I need to debounce this similar to how mouse move events debounce.

To fire a background fetch click event for a bgFetch (a background fetch ), fire a functional event named " backgroundfetchclick " using BackgroundFetchEvent on bgFetch ’s service worker registration with the following properties:

registration

The result of getting a BackgroundFetchRegistration instance for bgFetch in the event object’s relevant Realm .

To get a BackgroundFetchRegistration instance for a bgFetch (a background fetch ) in realm (a Realm ), run these steps:

1. Let instancesMap be the BackgroundFetchRegistration instances of the only instance of BackgroundFetchManager within this realm .

2. If instancesMap [ bgFetch ] exists , then return instancesMap [ bgFetch ].

3. Let instance be a new BackgroundFetchRegistration in realm , with its background fetch set to bgFetch .

4. Set instancesMap [ bgFetch ] to instance .

5. Return instance .

To validate a partial response for an expectedRangeStart (a number), a partialResponse (a response ), and an optional previousResponse (a response or null, null unless otherwise specified), run these steps:

1. Assert: partialResponse ’s status is 206 .

2. Let responseFirstBytePos , responseLastBytePos , and responseCompleteLength be the result of extracting content-range values from partialResponse . If this fails, then return invalid.

3. If responseFirstBytePos does not equal expectedRangeStart , then return invalid.

4. If previousResponse is not null, then:

   1. For headerName of « ` ETag `, ` Last-Modified ` »:

      1. If previousResponse ’s header list contains headerName and the combined value of headerName in previousResponse ’s header list does not equal the combined value of headerName in partialResponse ’s header list , then return invalid.

   2. If previousResponse ’s status is 206 , then:

      1. Let previousResponseFirstBytePos , previousResponseLastBytePos , and previousResponseCompleteLength be the result of extracting content-range values from previousResponse . If this fails, then return invalid.

      2. If previousResponseCompleteLength is not null, and responseCompleteLength does not equal previousResponseCompleteLength , then return invalid.

5. Return valid.

To extract content-range values from a response (a response ), run these steps:

1. If response ’s header list does not contain ` Content-Range `, then return failure.

2. Let contentRangeValue be the value of the first header whose name is a byte-case-insensitive match for ` Content-Range ` in response ’s header list .

3. If parsing contentRangeValue per single byte content-range fails, then return failure.

4. Let firstBytePos be the portion of contentRangeValue named first-byte-pos when parsed as single byte content-range , parsed as an integer.

5. Let lastBytePos be the portion of contentRangeValue named last-byte-pos when parsed as single byte content-range , parsed as an integer.

6. Let completeLength be the portion of contentRangeValue named complete-length when parsed as single byte content-range .

7. If completeLength is "*" , then set completeLength to null, otherwise set completeLength to completeLength parsed as an integer.

8. Return firstBytePos , lastBytePos , and completeLength .

Parsing as an integer infra/189 .

To create record objects from records (a list of background fetch records ) in realm (a Realm ), run these steps:

All platform objects must be created in realm .

1. Let recordObjects be a new list .

2. For each record of records :

   1. Let responseData be record ’s response data .

   2. Let recordObject be a new BackgroundFetchRecord .

   3. Set recordObject ’s responseReady to a new promise .

   4. Let requestObject be a new Request object with the following set:

      Request

      A copy of record ’s request , including its body .

      Headers

      A new Headers object associated with this Request 's request 's header list .

   5. Set recordObject ’s request to requestObject .

   6. Let transmittedBytes be 0.

   7. Let stream be a new ReadableStream .

   8. Set up stream given a pull action that returns a new promise promise and runs these steps in parallel :

      1. Wait for the length of responseData ’s bytes to be greater than transmittedBytes , or responseData ’s result not to be the empty string.

      2. Let bytes be null.

      3. If the length of responseData ’s bytes is greater than transmittedBytes and responseData may be exposed , then:

         1. Set bytes to a user agent determined slice of responseData ’s bytes , starting from an offset of transmittedBytes .

            Note: This allows the user agent to stream the resource from storage at an appropriate rate.

         2. Increment transmittedBytes by bytes ’ length .

      4. Queue a task in stream ’s relevant settings object 's responsible event loop using the networking task source to run these steps:

         1. If bytes is not null, then:

            1. Let array be a new Uint8Array wrapping a new ArrayBuffer of bytes .

            2. Enqueue array into stream .

         2. If responseData may be exposed , responseData ’s result is not the empty string, and transmittedBytes is the length of responseData ’s bytes , then close stream .

         3. Otherwise, if responseData ’s result is "aborted" , then error stream with an AbortError DOMException .

         4. Otherwise, if responseData may not be exposed , then error stream with a TypeError .

         5. Resolve promise .

   9. Run these steps in parallel :

      1. Wait for responseData ’s response to not be not-null.

      2. If responseData may be exposed , then:

         1. Let response be a copy of responseData ’s response .

         2. Delete ` Content-Range ` from response ’s header list .

         3. Delete ` Content-Length ` from response ’s header list .

         4. Let body be a new body with stream set to stream .

         5. Set response ’s body to body .

         6. Queue a task in recordObject ’s relevant settings object 's responsible event loop using the networking task source to run these steps:

            1. Let responseObject be a new Response object with the following set:

               Response

               response .

               Headers

               A new Headers object associated with this Response 's response 's header list .

            2. Resolve recordObject ’s responseReady with responseObject .

      3. Otherwise, if responseData ’s result is "aborted" , then reject recordObject ’s responseReady with an AbortError DOMException .

      4. Otherwise, reject recordObject ’s responseReady with a TypeError .

   10. Append recordObject to recordObjects .

3. Return recordObjects .

To determine whether a map (a map ) contains background fetch bgFetch (a background fetch ), run these steps:

1. Let id be bgFetch ’s id .

2. If map [ id ] does not exist , then return false.

3. If map [ id ] does not equal bgFetch , then return false.

4. Return true.

To determine whether a map (a map ) does not contain background fetch bgFetch (a background fetch ), run these steps:

1. If map contains background fetch bgFetch , then return false.

2. Return true.

"bytes=" first-byte-pos "-" last-byte-pos "/" complete-length
first-byte-pos = 1*DIGIT
last-byte-pos  = 1*DIGIT
complete-length
=
(
1*DIGIT
/
"*"
)

partial interface ServiceWorkerGlobalScope {
  attribute EventHandler onbackgroundfetchsuccess;
  attribute EventHandler onbackgroundfetchfail;
  attribute EventHandler onbackgroundfetchabort;
  attribute EventHandler onbackgroundfetchclick;
};

partial interface ServiceWorkerRegistration {
  readonly attribute BackgroundFetchManager backgroundFetch;
};

[Exposed=(Window,Worker)]
interface BackgroundFetchManager {
  Promise<BackgroundFetchRegistration> fetch(DOMString id, (RequestInfo or sequence<RequestInfo>) requests, optional BackgroundFetchOptions options = {});
  Promise<BackgroundFetchRegistration?> get(DOMString id);
  Promise<sequence<DOMString>> getIds();
};
dictionary BackgroundFetchUIOptions {
  sequence<ImageResource> icons;
  DOMString title;
};
dictionary BackgroundFetchOptions : BackgroundFetchUIOptions {
  unsigned long long downloadTotal = 0;
};

[Exposed=(Window,Worker)]
interface BackgroundFetchRegistration : EventTarget {
  readonly attribute DOMString id;
  readonly attribute unsigned long long uploadTotal;
  readonly attribute unsigned long long uploaded;
  readonly attribute unsigned long long downloadTotal;
  readonly attribute unsigned long long downloaded;
  readonly attribute BackgroundFetchResult result;
  readonly attribute BackgroundFetchFailureReason failureReason;
  readonly attribute boolean recordsAvailable;
  attribute EventHandler onprogress;
  Promise<boolean> abort();
  Promise<BackgroundFetchRecord> match(RequestInfo request, optional CacheQueryOptions options = {});
  Promise<sequence<BackgroundFetchRecord>> matchAll(optional RequestInfo request, optional CacheQueryOptions options = {});
};
enum BackgroundFetchResult { "", "success", "failure" };
enum BackgroundFetchFailureReason {
  // The background fetch has not completed yet, or was successful.
  "",
  // The operation was aborted by the user, or abort() was called.
  "aborted",
  // A response had a not-ok-status.
  "bad-status",
  // A fetch failed for other reasons, e.g. CORS, MIX, an invalid partial response,
  // or a general network failure for a fetch that cannot be retried.
  "fetch-error",
  // Storage quota was reached during the operation.
  "quota-exceeded",
  // The provided downloadTotal was exceeded.
  "download-total-exceeded"
};

[Exposed=(Window,Worker)]
interface BackgroundFetchRecord {
  readonly attribute Request request;
  readonly attribute Promise<Response> responseReady;
};

[Exposed=ServiceWorker]
interface BackgroundFetchEvent : ExtendableEvent {
  constructor(DOMString type, BackgroundFetchEventInit init);
  readonly attribute BackgroundFetchRegistration registration;
};
dictionary BackgroundFetchEventInit : ExtendableEventInit {
  required BackgroundFetchRegistration registration;
};

[Exposed=ServiceWorker]
interface BackgroundFetchUpdateUIEvent : BackgroundFetchEvent {
  constructor(DOMString type, BackgroundFetchEventInit init);
  Promise<undefined> updateUI(optional BackgroundFetchUIOptions options = {});
};

Method	URI Template
POST	/session/{session id}/backgroundfetch/{ id }/click

The background fetch click extension command simulates the user activating the display of a background fetch . The remote end steps are:

1. If the current top-level browsing context is no longer open , then return a WebDriver error with WebDriver error code no such window .

2. Let pageURL be the current top-level browsing context 's active document 's URL .

3. Let swRegistration be the matching service worker registration for pageURL .

4. If swRegistration is null, then return a WebDriver error with status 400 and JSON error code " invalid service worker state ".

5. Let bgFetch be the newest background fetch with an id of url variable id and a service worker registration of swRegistration , or null if none exists.

6. If bgFetch is null, then return a WebDriver error with status 404 and JSON error code " background fetch not found ".

7. Fire a background fetch click event for bgFetch .

8. Return WebDriver success .