From 6c4307980711c8cc3b9bd273c0dfd72b35e8ec69 Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Wed, 20 May 2020 13:20:02 +0200 Subject: [PATCH 1/6] Add hooks for HTML "legacy-clone a browsing session storage shed" can be used by HTML to define creation of auxiliary browsing contexts, as part of https://github.com/whatwg/html/pull/5560. "obtain a storage key" can be used by APIs that share keying logic with storage, such as BroadcastChannel and shared workers. See https://github.com/whatwg/html/issues/3054. It's potentially also useful for Indexed DB as discussed in https://github.com/w3c/IndexedDB/pull/334. Closes #92. --- storage.bs | 75 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 58 insertions(+), 17 deletions(-) diff --git a/storage.bs b/storage.bs index 562ce28..42d1d4c 100644 --- a/storage.bs +++ b/storage.bs @@ -185,13 +185,30 @@ anticipated that some APIs will be applicable to both storage types going -

Storage sheds

+

Storage keys

A storage key is an origin. [[HTML]]

This is expected to change, see Client-Side Storage Partitioning. +

To obtain a storage key, given an environment settings object +environment, run these steps: + +

    +

  1. Let key be environment's + origin. + +

  2. If key is an opaque origin, then return failure. + +

  3. If the user has disabled storage, then return failure. + +

  4. Return key. +

+ + +

Storage sheds

+

A storage shed is a map of storage keys to storage shelves. It is initially empty. @@ -211,6 +228,28 @@ It is initially empty. browsing session. It is roughly analogous to top-level browsing context except that it cannot be replaced due to Cross-Origin-Opener-Policy or navigation. +

To legacy-clone a browsing session storage shed, given a browsing session +A and a browsing session B, run these steps: + +

    +
  1. +

    For each key → shelf of A's + storage shed: + +

      +

    1. Let newShelf be the result of running create a storage shelf with + "session". + +

    2. Set newShelf's bucket map["default"]'s + bottle map["sessionStorage"]'s map to a + clone of shelf's bucket map["default"]'s + bottle map["sessionStorage"]'s map. + +

    3. Set B's storage shed[key] to + newShelf. +

    +
+

Storage shelves

@@ -228,24 +267,14 @@ given a value when a storage shelf is type, run these steps:
    -

  1. Let key be environment's - origin. +

  2. Let key be the result of running obtain a storage key with + environment. -

  3. If key is an opaque origin, then return failure. +

  4. If key is failure, then return failure. -

  5. If the user has disabled storage, then return failure. - -

  6. -

    If shed[key] does not exist, then: - -

      -

    1. Let shelf be a new storage shelf. - -

    2. Set shelf's bucket map["default"] to the result of - create a storage bucket with type. - -

    3. Set shed[key] to shelf. -

    +

  7. If shed[key] does not exist, then set + shed[key] to the result of running create a storage shelf with + type.

  8. Return shed[key].

@@ -254,6 +283,18 @@ given a value when a storage shelf is environment, return the result of running obtain a storage shelf with the user agent's storage shed, environment, and "local". +

To create a storage shelf, given a storage type type, run these +steps: + +

    +

  1. Let shelf be a new storage shelf. + +

  2. Set shelf's bucket map["default"] to the result of running + create a storage bucket with type. + +

  3. Return shelf. +

+

Storage buckets

From 4bf2027817ce2228f554a9ec76f964dba3daa642 Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Fri, 29 May 2020 15:58:16 +0200 Subject: [PATCH 2/6] address running script; see #95 --- storage.bs | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/storage.bs b/storage.bs index 42d1d4c..8857211 100644 --- a/storage.bs +++ b/storage.bs @@ -477,22 +477,24 @@ evaluating quotas. -

User Interface Guidelines

+

User interface guidelines

User agents should not distinguish between network state and storage in their user interface. -Instead user agents should offer users the ability to remove all storage for each group of +Instead user agents should offer users the ability to clear all storage for each group of schemelessly same site origins. This ensures to some extent that network state cannot be used to revive storage. This also reduces the amount users need to know about the different ways in which websites can store data. +

User agents should not clear storage while script that is able to access the storage is running. +

Credentials should be separated as they contain data the user might not be able to revive, such as an autogenerated password. Permissions are best separated too to avoid inconveniencing the user. Credentials and permissions are also somewhat easier to understand and differentiate for users from network state and storage. -

Storage Pressure

+

Storage pressure

When the user agent notices it comes under storage pressure and it cannot free up sufficient space by clearing network state, session storage buckets, and local storage buckets From ec2d70b63c3caf14488bdf50d9422990479743ad Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Sat, 30 May 2020 11:53:22 +0200 Subject: [PATCH 3/6] rewrite a bit more --- storage.bs | 48 ++++++++++++++++++++++++++++++------------------ 1 file changed, 30 insertions(+), 18 deletions(-) diff --git a/storage.bs b/storage.bs index 8857211..d6bd5f5 100644 --- a/storage.bs +++ b/storage.bs @@ -298,9 +298,7 @@ steps:

Storage buckets

-

A storage bucket is a place for storage endpoints to store data. Whenever a -storage bucket is cleared by the user agent, it must be cleared in its entirety. - +

A storage bucket is a place for storage endpoints to store data.

A storage bucket has a bottle map of storage identifiers to storage bottles. @@ -477,30 +475,44 @@ evaluating quotas. -

User interface guidelines

+

Management

+ +

Whenever a storage bucket is cleared by the user agent, it must be cleared in its +entirety. User agents should avoid clearing storage bucket while script that is able to +access them is running, unless instructed otherwise by the user. + +

If removal of storage buckets leaves the encompassing storage shelf's +bucket map empty, then remove that +storage shelf and corresponding storage key from the encompassing +storage shed. + + +

Storage pressure

+ +

A user agent that comes under storage pressure should clear network state and +local storage buckets whose mode is +"best-effort", ideally prioritizing removal in a manner that least impacts the user. + +

If a user agent continues to be under storage pressure, then the user agent should inform the +user and offer a way to clear the remaining local storage buckets, i.e., those whose +mode is "persistent". + +

Session storage buckets must be cleared as browsing sessions are closed. + +

If the user agent allows revival of browsing sessions, then nothing can be cleared +until revival is no longer possible. + + +

User interface guidelines

User agents should not distinguish between network state and storage in their user interface. Instead user agents should offer users the ability to clear all storage for each group of schemelessly same site origins. This ensures to some extent that network state cannot be used to revive storage. This also reduces the amount users need to know about the different ways in which websites can store data. - - -

User agents should not clear storage while script that is able to access the storage is running.

Credentials should be separated as they contain data the user might not be able to revive, such as an autogenerated password. Permissions are best separated too to avoid inconveniencing the user. -Credentials and permissions are also somewhat easier to understand and differentiate for users from -network state and storage. - - -

Storage pressure

- -

When the user agent notices it comes under storage pressure and it cannot free up sufficient -space by clearing network state, session storage buckets, and local storage buckets -whose mode is "best-effort", then the user agent -should inform the user and offer a way to clear the remaining local storage buckets, i.e., -those whose mode is "persistent". From be6d567fe6c9754457a7c635cfa7fd2a92cf7a8c Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Thu, 4 Jun 2020 11:39:51 +0200 Subject: [PATCH 4/6] address review comments (except for the one I disagree with) --- storage.bs | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/storage.bs b/storage.bs index d6bd5f5..ee74afa 100644 --- a/storage.bs +++ b/storage.bs @@ -218,18 +218,13 @@ It is initially empty. storage shed. A user agent's storage shed holds all local storage data. -

A browsing session holds a storage shed, which is a -storage shed. A browsing session's storage shed holds all -session storage data. +

A browsing session holds a storage shed, which is +a storage shed. A browsing session's +storage shed holds all session storage data. -

See -whatwg/html issue #4782 and -whatwg/html issue #5350 for defining -browsing session. It is roughly analogous to top-level browsing context except that it cannot -be replaced due to Cross-Origin-Opener-Policy or navigation. - -

To legacy-clone a browsing session storage shed, given a browsing session -A and a browsing session B, run these steps: +

To legacy-clone a browsing session storage shed, given a +browsing session A and a browsing session B, run +these steps:

  1. @@ -250,6 +245,10 @@ be replaced due to Cross-Origin-Opener-Policy or navigation.
+

This is considered legacy as the benefits, if any, do not outweigh the +implementation complexity. And therefore it will not be used for session storage beyond the +above. +

Storage shelves

@@ -377,7 +376,7 @@ standard and standards using this standard can access the contents.

  • Assert: type is "session".

  • Set shed to environment's - browsing session's + browsing session's storage shed. @@ -497,10 +496,10 @@ access them is running, unless instructed otherwise by the user. user and offer a way to clear the remaining local storage buckets, i.e., those whose mode is "persistent". -

    Session storage buckets must be cleared as browsing sessions are closed. +

    Session storage buckets must be cleared as browsing sessions are closed. -

    If the user agent allows revival of browsing sessions, then nothing can be cleared -until revival is no longer possible. +

    If the user agent allows revival of browsing sessions, then nothing can +be cleared until revival is no longer possible.

    User interface guidelines

    From 5b61308ec6e43c58fbd9702612a7103570b9ef11 Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Thu, 4 Jun 2020 12:05:53 +0200 Subject: [PATCH 5/6] nit --- storage.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/storage.bs b/storage.bs index ee74afa..9503457 100644 --- a/storage.bs +++ b/storage.bs @@ -477,7 +477,7 @@ evaluating quotas.

    Management

    Whenever a storage bucket is cleared by the user agent, it must be cleared in its -entirety. User agents should avoid clearing storage bucket while script that is able to +entirety. User agents should avoid clearing storage buckets while script that is able to access them is running, unless instructed otherwise by the user.

    If removal of storage buckets leaves the encompassing storage shelf's From 329766e30b667e9f686f48315915c9664396d140 Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Fri, 5 Jun 2020 13:26:16 +0200 Subject: [PATCH 6/6] feedback + nits I found --- storage.bs | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/storage.bs b/storage.bs index 9503457..f57243b 100644 --- a/storage.bs +++ b/storage.bs @@ -84,8 +84,8 @@ function retrieveNextChunk(nextChunkInfo) {

    This specification depends on the Infra Standard. [[!INFRA]] -

    This specification uses terminology from the DOM, HTML, IDL, Permissions API, and URL Standards. -[[DOM]] [[HTML]] [[WEBIDL]] [[PERMISSIONS]] [[URL]] +

    This specification uses terminology from the HTML, IDL, and Permissions Standards. +[[!HTML]] [[!WEBIDL]] [[!PERMISSIONS]] @@ -187,9 +187,9 @@ anticipated that some APIs will be applicable to both storage types going

    Storage keys

    -

    A storage key is an origin. [[HTML]] +

    A storage key is an origin. [[!HTML]] -

    This is expected to change, see +

    This is expected to change; see Client-Side Storage Partitioning.

    To obtain a storage key, given an environment settings object @@ -246,8 +246,8 @@ these steps:

    This is considered legacy as the benefits, if any, do not outweigh the -implementation complexity. And therefore it will not be used for session storage beyond the -above. +implementation complexity. And therefore it will not be expanded or used outside of +HTML. [[HTML]]

    Storage shelves

    @@ -498,8 +498,9 @@ user and offer a way to clear the remaining local storage buckets, i.e.,

    Session storage buckets must be cleared as browsing sessions are closed. -

    If the user agent allows revival of browsing sessions, then nothing can -be cleared until revival is no longer possible. +

    If the user agent allows for revival of browsing sessions, e.g., +through reopening browsing sessions or continued use of them after restarting the user +agent, then clearing necessarily involves a more complex set of heuristics.

    User interface guidelines

    @@ -526,7 +527,7 @@ Navigator includes NavigatorStorage; WorkerNavigator includes NavigatorStorage; -

    Each environment settings object has an associated {{StorageManager}} object. [[HTML]] +

    Each environment settings object has an associated {{StorageManager}} object. [[!HTML]]

    The storage getter steps are to return this's relevant settings object's {{StorageManager}} object.