XHRBatch API (DRAFT)

Goal

The goal of this API is to let data uploading/downloading can be performed without the APP staying in the memory during the transmission.

Status

Proposed API

interface nsIDOMNavigatorXHRBatch : EventTarget {
  readonly attribute long maxBatches;
  readonly attribute long numBatches;
  readonly attribute long numAllBatches;

  Promise getBatches();     // return submitted batches of the same origin.
  Promise getAllBatches();  // return all submitted batches, not strict by the same origin if with the permission
}

[Constructor(DOMString name, DOMString description)]
interface XHRBatch : EventTarget {
  readonly attribute DOMString origin;
  readonly attribute DOMString name;
  readonly attribute DOMString description;

  // states
  const unsigned short NOTSUBMITTED = 0;  // This batch is still not submitted.
  const unsigned short WAITING = 1;       // This batch is submitted, but not in a transmission.
  const unsigned short SENDING = 2;       // This batch is in a transmission.
  const unsigned short COMPLETED = 3;     // All requests in this batch are completed or failed.
  const unsigned short DROPPED = 4;       // This batch is already removed from the user agent.
  readonly attribute unsigned short state;

  Promise createXMLHttpRequest();
  /*
   * The batch is ready for a transmission and known by the user agent.
   * This function can be failed for running out resources of the user agent.
   * As so, drop the old batches to release the resources.  The state is transited
   * from NOTSUBMITTED to WAITING.
   */
  Promise submit();
  Promise start();  // Start the transmission.  The state is transited from WAITING to SENDING.
  /*
   * Stop the transmission.
   * The state is transited from SENDING to WAITING once all requests are stopped.
   * If |force| is true, all requests are stopped immediately, or it will wait
   * until completed or failed for requests in sending.
   */
  Promise stop(boolean force);
  Promise drop();   // remove the batch from the user agent.

  Promise getRequests();
}

partial interface XMLHttpRequest {
   readonly attribute XHRBatch batch;  // The batch this request belonging to.
   Promise<boolean> removeFromBatch(); // Remove this request from the batch belonged to.
}

Examples

List all batches owned by the App.

let batches_defer = navigator.XHRBatch.getBatches();
batches_defer.then(e => {
  for (let i in e.batches) {
    let batch = e.batches[i];
    console.log("Batch Name: " + batch.name);
    console.log("  Description: " + batch.description);
  }
});

Once the network is available, the system app start transmissions for all batches.

function onNetworkAvailable() {
  let allBatches_defer = navigator.XHRBatch.getAllBatches();
  allBatches_defer.then(e => {
    for (let i in e.batches) {
      let batch = e.batches[i];
      if (batch.state == navigator.XHRBatch.WAITING) {
        batch.start();
      }
    }
  });
}

Once one or more batches of the App are completed, the App would remove them from the user agent.

function onBatchCompleted() {
  let batches_defer = navigator.XHRBatch.getBatches();
  batches_defer.then(e => {
    for (let i in e.batches) {
      let batch = e.batches[i];
      if (batch.state != navigator.XHRBatch.COMPLETED)
        continue;
      batch.drop();

      batch.getRequests().then(e => {
        let error_count = 0;
        for (let i in e.requests) {
          let xhr = e.requests[i];
          if (xhr.status != 200) {
            error_count++;
          }
        }
        console.log("Batch " + e.batch.name + " is completed!");
        console.log("    " + error_count + " errors!");
      });
    }
  });
}

Proposers

Thinker Li

Resource Limitation

XHRBatch is limited resource of an App. Every App are allowed to have a limited number of submitted XHRBatch instances. The resources are released by calling |XHRBatch.drop()|.

Use Case

A user in camping taken videos and pictures with the attached camera and would like to share them with friends through the YouTube and Flickr. He launched the YouTube or Flickr App and take videos or pictures, writing down the title and description of his idea, and submitting them. The videos and pictures were queued. At his way home, he got WiFi access at a gas station, and he submitted the batches of YouTube and Flickr to send out the all videos and pictures during his camping through the transmission manager App. When the batches were sending, he could open E-Mail App to read and reply messages without running out the memory even he had very limited device RAM.