Quota

Proposing Quota management API for offline storage APIs

Note: now the proposal draft is moved to: https://dvcs.w3.org/hg/quota/raw-file/tip/Overview.html

Abstract

Today we have a lot of useful offline storage APIs (including proposing/obsolete ones), i.e. IndexedDB, FileSystem API, AppCache and SQL DB, but the storage allocation decision for the offline storage APIs has been a big unresolved pain among the UA. This proposal is to establish a clear protocol between apps, the UA and the user so that the UA can make an appropriate decision about how much it should allocate the storage and about whether the UA could delete the offline data at its discretion or not.

The proposal is:

1. introduce two different storage categories, temporary/evictable/transient and persistent/non-evictable.
   • The temporary storage can be viewed as '/tmp' space in the traditional filesystem, and can be used without explicit quota request but the data may get deleted at any time at the UA's discretion.
   • The persistent storage should never deleted by the UA without the user’s instruction, but should require up-front quota request to use, which may in turn require explicit user intervention.
2. introduce a new app-facing API to request or query quota/usage. The API includes two primary methods, one is to request more (persistent) storage quota and the other is to query the current quota and used amount.

The requested or granted quota should work in a unified way across different storage APIs, so that apps do not need to take care of storage space for each API.

API

 Window implements QuotaStorageEnvironment; 
 [NoInterfaceObject] 
 interface QuotaStorageEnvironment {
   readonly attribute StorageInfo storageInfo; 
 };

StorageInfo interface

 interface StorageInfo {
   const unsigned short TEMPORARY = 0; 
   const unsigned short PERSISTENT = 1; 
 
   // Queries the current quota and how much data is stored for the host. 
   void queryUsageAndQuota( 
       unsigned short storageType, 
       optional StorageInfoUsageCallback successCallback, 
       optional StorageInfoErrorCallback errorCallback); 
 
   // Requests a new quota.  Requesting a larger quota may require user's 
   // explicit permission via UI prompting / infobar. 
   void requestQuota(
       unsigned short storageType, 
       unsigned long long newQuotaInBytes, 
       optional StorageInfoQuotaCallback successCallback, 
       optional StorageInfoErrorCallback errorCallback); 
 }; 
 
 [NoInterfaceObject, Callback=FunctionOnly] 
 interface StorageInfoUsageCallback { 
   void handleEvent(unsigned long long currentUsageInBytes, 
                              unsigned long long currentQuotaInBytes); 
 }; 
 
 [NoInterfaceObject, Callback=FunctionOnly] 
 interface StorageInfoQuotaCallback { 
   void handleEvent(unsigned long long grantedQuotaInBytes); 
 }; 
 
 [NoInterfaceObject, Callback=FunctionOnly] 
 interface StorageInfoErrorCallback { 
   void handleEvent(DOMCoreException error); 
 }; 

Notes about TEMPORARY / PERSISTENT storageType const values: in general using string would be more preferable than enum, but for now we're proposing short const values to make it match with the type parameters of File API: Directories and System.

Example Code

The app can get the current quota and usage for the apps' origin by calling:

 storageInfo.queryUsageAndQuota(
   storageInfo.PERSISTENT,    // or TEMPORARY
   function (usage, quota) { log("Current usage/quota:" + usage + "/" + quota); },
   function (error) { log("Querying quota got error: " + error); });

The app can also request more quota by calling:

 storageInfo.requestQuota(
   storageInfo.PERSISTENT,
   requestingQuota,
   function (quota) { log("Requested " + requestingQuota + " => got " + quota); },
   function (error) { log("Requesting quota got error: " + error); });