W3C

Quota Management API

W3C Working Draft 03 July 2012

This version:
http://www.w3.org/TR/2012/WD-quota-api-20120703/
Latest published version:
http://www.w3.org/TR/quota-api/
Latest editor's draft:
http://dvcs.w3.org/hg/quota/raw-file/tip/Overview.html
Editor:
Kinuko Yasuda, Google

Abstract

This specification defines an API to manage usage and availability of local storage resources, and defines a means by which a user agent (UA) may grant Web applications permission to use more local space, temporarily or persistently, via various different storage APIs.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document was published by the Web Applications (WebApps) Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-webapps@w3.org (subscribe, archives). All feedback is welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

2. Introduction

This section is non-normative.

Today we have a variety of storage APIs that can store inherently complex or large data in order to satisfy offline data requirements of Web applications. Examples of these APIs include: Application Cache [OFFLINE-WEBAPPS], File API: Directories and System (File System API) [FILE-SYSTEM], Indexed Database [INDEXEDDB] and Web SQL Database [WEBSQL].

These APIs may require larger local space than the conventional cookie storage or Web Storage [WEBSTORAGE], but they do not provide a means by which a Web application can query and manage how much data is currently stored and how much more can be stored.

This specification defines an API to query and manage usage and availability of a user's local storage. The storage space granted by the API is intended to be shared by different storage APIs, therefore a user and UA only need to manage single upper limit for all storage per logical application unit, e.g. per origin or per browser (which is implementation specific).

3. Storage Types

3.1 Temporary vs Persistent

This section is non-normative.

A Web application can request temporary or persistent local storage space depending on its purpose.

Temporary type of storage is especially useful if an application wants to cache data locally to improve its performance, but can fall back to fetching or recreating the same data at a data loss.

Conversely, persistent type of storage is useful if an application wants to store critical offline data that is necessary to be functional, or wants to manage local data amount and lifetime on its own policy rather than relying on the UA's default eviction policy for temporary storage.

3.2 Examples

Suppose there is a photo editing application. This application manages user photo data using Indexed Database [INDEXEDDB], stores photo images using Filesystem API [FILE-SYSTEM] and optinally utilizes Application Cache [OFFLINE-WEBAPPS] to make it work offline.

The application needs to query how much data it can store in the temporary storage to determine its initial cache size.

// Query current usage and availability in Temporary storage:
navigator.temporaryStorage.queryUsageAndQuota(
  function (usage, quota) {
    // Continue to initialize local cache using the obtained
    // usage and quota (availability) information.
    initializeCache(usage, quota);
  },
  function (error) { log("Got error: ", error); });

Similarly, the application needs to request additional persistent storage to support offline mode when it is enabled by the user.

function onError(error) {
  // Handle an error.
  log("Got error: ", error);
}

function setUpOfflineMode(availableSpace) {
  // ...
}

// A function which is to be called when 'offline-mode' is enabled.
function onOfflineEnabled(amountOfSpaceNeeded) {
  // First check how much we can use in the Persistent storage.
  navigator.persistentStorage.queryUsageAndQuota(
    function (usage, quota) {
      var availableSpace = quota - usage;
      if (availableSpace >= amountOfSpaceNeeded) {
        // We're fine; just continue to set up offline mode.
        setUpOfflineMode(availableSpace);
        return;
      }
      var requestingQuota = amountOfSpaceNeeded + usage;
      navigator.persistentStorage.requestQuota(
          requestingQuota,
          function (grantedQuota) {
            setUpOfflineMode(grantedQuota - usage);
          },
          onError);
    },
    onError);
}

4. Quota Management API

4.1 StorageQuota interface

The StorageQuota interface provides means to query and request storage usage and quota information. The API provided by the interface is asynchronous since querying or allocating space in a user's local storage may require blocking I/O operations, e.g. examining the local disk status or making changes in a local database.

interface StorageQuota {
    void queryUsageAndQuota (in StorageUsageCallback successCallback, in optional StorageErrorCallback errorCallback);
    void requestQuota (in unsigned long long newQuotaInBytes, in optional StorageQuotaCallback successCallback, in optional StorageErrorCallback errorCallback);
};

4.1.1 Methods

queryUsageAndQuota

Queries the current usage (how much data is stored) and quota available for the requesting application. Either one of successCallback or errorCallback is called to indicate the request is successfully handled or not.

ParameterTypeNullableOptionalDescription
successCallbackStorageUsageCallback
errorCallbackStorageErrorCallback
No exceptions.
Return type: void
requestQuota

Requests a new quota for the requesting application. It is not guaranteed that the requested amount of space is granted just by calling this API. Calling this API may trigger user prompting to request explicit user permission to proceed. Either one of successCallback or errorCallback is called to indicate the request is successfully handled or not. successCallback may return a smaller amount of quota than requested.

ParameterTypeNullableOptionalDescription
newQuotaInBytesunsigned long long
successCallbackStorageQuotaCallback
errorCallbackStorageErrorCallback
No exceptions.
Return type: void

This interface is defined after the storage model defined in File System API [FILE-SYSTEM], and therefore uses the terminology and interface model similar to the API, e.g. employing Callback model rather than Event model.

4.1.2 Restrictions

The space queried and granted by StorageQuota must have the following properties:

  • The space granted for persistent type should not be deleted by the UA, other than in a response to a removal API call, without explicit authorization from the user.
  • The space granted for temporary type may be deleted by the UA at its discretion, without application or user intervention due to local resource shortage or for other reasons.
  • When the UA deletes the data in temporary storage, the UA should avoid partial or incomplete deletion which could leave the application in an unrecoverable inconsistent state.

4.2 StorageUsageCallback callback

This callback is used to return usage and quota information.

callback StorageUsageCallback = void (in unsigned long long currentUsageInBytes, in unsigned long long currentQuotaInBytes);

Used to supply the current usage and quota information in bytes.

currentUsageInBytes indicates the total amount of data stored in the storage of the requested storage type. Depending on the UA's usage tracking system the returned value may differ from the exact real-time usage of the user's physical local storage.

currentQuotaInBytes indicates the current upper limit of the storage space that is exposed to and can be used by the requesting application.

4.3 StorageQuotaCallback callback

This callback is used to return a new quota information granted by a UA.

callback StorageQuotaCallback = void (in unsigned long long grantedQuotaInBytes);

4.4 StorageErrorCallback callback

This interface is the callback used to indicate an error has occured.

callback StorageErrorCallback = void (in DOMError error);

There was an error with the request. Details are provided by the error parameter.

4.5 Accessing StorageQuota

All instances of Navigator type are defined to also implement StorageQuotaEnvironment interface.

[NoInterfaceObject]
interface StorageQuotaEnvironment {
    readonly attribute StorageQuota persistentStorage;
    readonly attribute StorageQuota temporaryStorage;
};

4.5.1 Attributes

persistentStorage of type StorageQuota, readonly
This attribute provides applications a means to access Quota Management API for temporary storage type.
No exceptions.
temporaryStorage of type StorageQuota, readonly
This attribute provides applications a means to access Quota Management API for persistent storage type.
No exceptions.

5. Quota handling in storage API

This section is non-normative.

Storage APIs except for Web Storage, i.e. Application Cache, File System API, Indexed Database and Web SQL Database, should respect the quota management API and must have following properties:

A. Acknowledgements

Many thanks to Robin Berjon for making our lives so much easier with his cool tool.

B. References

B.1 Normative references

[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt

B.2 Informative references

[DOM4]
Anne van Kesteren; Aryeh Gregor; Ms2ger. DOM4. 5 January 2012. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2012/WD-dom-20120105/
[FILE-SYSTEM]
Eric Uhrhane. File API: Directories and System. 17 March 2012. W3C Editor's Draft. (Work in progress.) URL: http://dev.w3.org/2009/dap/file-system/file-dir-sys.html
[INDEXEDDB]
Nikunj Mehta; Jonas Sicking; Eliot Graff; Andrei Popescu; Jeremy Orlow. Indexed Datbase API. 6 December 2011. W3C Editor's Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-IndexedDB-20111206
[OFFLINE-WEBAPPS]
Ian Hickson; Anne van Kesteren. Offline Web Applications. 30 May 2008. W3C Note. URL: http://www.w3.org/TR/2008/NOTE-offline-webapps-20080530
[WEBSQL]
Ian Hickson. Web SQL Database. 18 November 2010. W3C Working Group Note. URL: http://www.w3.org/TR/2010/NOTE-webdatabase-20101118
[WEBSTORAGE]
Ian Hickson. Web Storage. 10 September 2009. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2009/WD-webstorage-20090910/