Storage Buckets API

[SecureContext]
interface mixin NavigatorStorageBuckets {
  [SameObject] readonly attribute StorageBucketManager storageBuckets;
};
Navigator includes NavigatorStorageBuckets;
WorkerNavigator includes NavigatorStorageBuckets;

[Exposed=(Window,Worker),
 SecureContext]
interface StorageBucketManager {
    Promise<StorageBucket> open(DOMString name, optional StorageBucketOptions options = {});
    Promise<sequence<DOMString>> keys();
    Promise<undefined> delete(DOMString name);
};

dictionary StorageBucketOptions {
  boolean persisted = false;
  unsigned long long quota;
  DOMHighResTimeStamp expires;
};

The open(name, options) method steps are:

1. Let environment be this's relevant settings object.

2. Let shelf be the result of running obtain a local storage shelf given environment.

3. If shelf is failure, then return a promise rejected with a TypeError.

4. If the result of validate a bucket name with name is failure, then return a promise rejected with a TypeError.

5. Let p be a new promise.

6. Enqueue the following steps to storage bucket manager:

   1. Let r be the result of running open a bucket with shelf, name, and options.

   2. If r is failure, then queue a storage task to reject p with a TypeError.

   3. Otherwise, queue a storage task to resolve p with r.

7. Return p.

To open a bucket for a shelf given a bucket name and optional options, run the following steps:

1. Let expires be undefined.

2. If options["expires"] exists, then:

   1. Set expires to options["expires"].

   2. If expires milliseconds after the Unix epoch is before the relevant settings object's current wall time, then return failure.

3. Let quota be undefined.

4. If options["quota"] exists, then:

   1. Set quota to options["quota"].

   2. If quota is less than or equal to zero, then return failure.

5. Let persisted be false.

6. If options["persisted"] is true, then:

   1. Let permission be the result of requesting permission to use "persistent-storage".

   2. If permission is "granted", then set persisted to true.

7. Let bucket be the result of running get or expire a bucket with shelf and name.

8. If bucket is null, then:

   1. Set bucket to a new storage bucket with name name.

   2. Set bucket’s quota value to quota.

   3. Set shelf’s bucket map[name] to bucket.

9. If persisted is true, set bucket’s bucket mode to "persistent".

10. Set bucket’s expiration to expires milliseconds after the Unix epoch.

11. Let storageBucket be a new StorageBucket.

12. Set storageBucket’s storage bucket to bucket.

13. Return storageBucket.

To validate a bucket name given string name, run the following steps:

1. If name contains any code point that is not ASCII lower alpha, ASCII digit, U+005F (_), or U+002D(-), then return failure.

2. If name code point length is 0 or exceeds 64, then return failure.

3. If name begins with U+005F (_) or U+002D(-), then return failure.

4. Return.

The delete(name) method steps are:

1. Let environment be this's relevant settings object.

2. Let shelf be the result of running obtain a local storage shelf given environment.

3. If shelf is failure, then return a promise rejected with a TypeError.

4. Let p be a new promise.

5. If the result of validate a bucket name with name is failure, then reject p with an InvalidCharacterError.

6. Otherwise, enqueue the following steps to storage bucket manager:

   1. Run remove a bucket with shelf and name.

   2. Queue a storage task to resolve p.

7. Return p.

To remove a bucket on a shelf given a bucket name, run the following steps:

1. Let bucket be shelf’s bucket map[name] if exists. Otherwise return.

2. Remove key name in shelf’s bucket map.

3. Set bucket’s removed to true.

4. Return.

[IndexedDB-3] needs to define how deletion occurs when data is evicted by quota.

[FS] needs to define how deletion occurs for Bucket File System when data is evicted by quota.

[Service-Workers] needs to define how deletion occurs for CacheStorage and Service Workers when data is evicted by quota.

The keys() method steps are:

1. Let shelf be the result of running obtain a local storage shelf.

2. If shelf is failure, then return a promise rejected with a TypeError.

3. Let p be a new promise.

4. Let keys be a new list.

5. Enqueue the following steps to storage bucket manager:

   1. For each key in shelf’s bucket map, run the following steps:

      1. Let bucket be the result of running get or expire a bucket with shelf and key.

      2. If bucket is non-null, append key to keys.

   2. Queue a storage task to resolve p with keys.

6. Return p.

[Exposed=(Window,Worker),
 SecureContext]
interface StorageBucket {
  readonly attribute DOMString name;

  [Exposed=Window] Promise<boolean> persist();
  Promise<boolean> persisted();

  Promise<StorageEstimate> estimate();

  Promise<undefined> setExpires(DOMHighResTimeStamp expires);
  Promise<DOMHighResTimeStamp?> expires();

  [SameObject] readonly attribute IDBFactory indexedDB;

  [SameObject] readonly attribute CacheStorage caches;

  Promise<FileSystemDirectoryHandle> getDirectory();
};

The persist() method steps are:

1. Let bucket be this's storage bucket.

2. Let environment be this's relevant settings object.

3. Let p be a new promise.

4. Run the following steps in parallel:

   1. If bucket’s removed flag is true, then queue a storage task to reject p with an InvalidStateError.

   2. Let persisted be true if bucket’s bucket mode is "persistent".

   3. Otherwise,

      1. Let permission be the result of getting the current permission state with "persistent-storage" and environment.

      2. If permission is "granted", then set bucket’s bucket mode to "persistent" and set persisted to true.

      3. Otherwise, set persisted to false.

   4. Queue a storage task to resolve p with persisted.

5. Return p.

The persisted() method steps are:

1. Let p be a new promise.

2. Let bucket be this's storage bucket.

3. Otherwise, run these steps in parallel:

   1. If bucket’s removed flag is true, then queue a storage task to reject p with an InvalidStateError.

   2. Let persistent be true if bucket’s bucket mode is "persistent", otherwise false.

   3. Queue a storage task to resolve p with persistent.

4. Return p.

The estimate() method steps are:

1. Let environment be this's relevant settings object.

2. Let shelf be the result of running obtain a local storage shelf with environment.

3. If shelf is failure, then return a promise rejected with a TypeError.

4. Let bucket be this's storage bucket.

5. If bucket’s removed flag is true, then return a promise rejected with an InvalidStateError.

6. Let p be a new promise.

7. Otherwise, run the following steps in parallel:

   1. Let quota be storage quota for shelf.

   2. Set quota to bucket’s quota value if it is non-null.

   3. Let usage be storage usage for bucket.

   4. Let dictionary be a new StorageEstimate dictionary whose usage member is usage and quota member is quota.

   5. Queue a storage task to resolve p with dictionary.

8. Return p.

The setExpires(expires) method steps are:

1. Let p be a new promise.

2. Let bucket be this's storage bucket.

3. Otherwise, run these steps in parallel:

   1. If bucket’s removed flag is true, then queue a storage task to reject p with an InvalidStateError.

   2. Otherwise, set bucket’s expiration time to expires milliseconds after the Unix epoch.

   3. Queue a storage task to resolve p.

4. Return p.

The expires() method steps are:

1. Let p be a new promise.

2. Let bucket be this's storage bucket.

3. Otherwise, run these steps in parallel:

   1. If bucket’s removed flag is true, then queue a storage task to reject p with an InvalidStateError.

   2. Otherwise, let expiration be bucket’s expiration time.

   3. Queue a storage task to resolve p with expiration.

4. Return p.

A StorageBucket has an IDBFactory object, initially null. The indexedDB getter steps are:

1. If this's indexedDB is null, run the following steps:

   1. Let bucket be this's storage bucket.

   2. Let bottle map be the result of obtain a local storage bottle map with bucket and "indexedDB".

   3. Let indexedDB be an IDBFactory object.

   4. Set the storage bottle map for indexedDB to bottle map.

   5. Set this's indexedDB to indexedDB.

2. Return this's indexedDB.

A StorageBucket has a CacheStorage object, initially null. The caches getter steps are:

1. If this's caches is null, run the following steps:

   1. Let bucket be this's storage bucket.

   2. Let bottle map be the result of obtain a local storage bottle map with bucket and "cacheStorage".

   3. Let cacheStorage be a CacheStorage object.

   4. Set the relevant name to cache map for cacheStorage to bottle map.

   5. Set this's caches to cacheStorage.

2. Return this's caches.

The getDirectory() steps are:

1. Let map be the result of obtain a local storage bottle map with this's storage bucket and "fileSystem".

2. Return the result of getDirectory with map.

To parse a Clear-Site-Data header with buckets, execute the following steps:

1. For each type in header, execute the following steps:

   1. If type does not start with "storage:", abort these steps.

   2. Let bucket name be the code unit substring from 8 to end of type.

   3. If the result of validate a bucket name with bucket name is failure, then abort these steps.

   4. Append a tuple consisting of ("storage-bucket", bucket name) to types

To clear data with buckets given a bucket name, execute the following steps:

1. Let environment be this's relevant settings object.

2. Let shelf be the result of running obtain a local storage shelf given environment.

3. If shelf is failure, then throw a TypeError and abort these steps.

4. For each type in types, execute the following steps:

   1. If type is not a tuple or type[0] is not "storage-bucket", abort these steps.

   2. Let bucket be shelf’s bucket map[bucket name] if one exists. Otherwise abort these steps

   3. Remove bucket.