Skip to content

Commit

Permalink
Rename boxes to buckets
Browse files Browse the repository at this point in the history
This avoids needlessly conflicting with the CSS box model.

Fixes whatwg#51.
  • Loading branch information
annevk authored Nov 11, 2017
1 parent d68e2a8 commit 0ecf0dd
Showing 1 changed file with 25 additions and 22 deletions.
47 changes: 25 additions & 22 deletions storage.bs
Original file line number Diff line number Diff line change
Expand Up @@ -30,15 +30,15 @@ Over the years the web has grown various APIs that can be used for storage, e.g.
these APIs by defining:

<ul class=brief>
<li>A box, the primitive these APIs store their data in
<li>A way of making that box persistent
<li>A bucket, the primitive these APIs store their data in
<li>A way of making that bucket persistent
<li>A way of getting usage and quota estimates for an <a for=/>origin</a>
</ul>

<p>Traditionally, as the user runs out of storage space on their device, the data stored with these
APIs gets lost without the user being able to intervene. However, persistent boxes cannot be cleared
without consent by the user. This thus brings data guarantees users have enjoyed on native platforms
to the web.
APIs gets lost without the user being able to intervene. However, persistent buckets cannot be
cleared without consent by the user. This thus brings data guarantees users have enjoyed on native
platforms to the web.

<div class="example" id=example-3a7051a8>
<p>A simple way to make storage persistent is through invoking the {{persist()}} method. It
Expand Down Expand Up @@ -129,24 +129,26 @@ This specification primarily concerns itself with <dfn export id=site-storage>si
<dfn export id=site-storage-unit>site storage units</dfn>.

Each <a for=/>origin</a> has an associated <a>site storage unit</a>. A <a>site storage unit</a>
contains a single <dfn export id=box>box</dfn>. [[HTML]]
contains a single <dfn export id=bucket oldids=box>bucket</dfn>. [[HTML]]


<h3 id=boxes>Boxes</h3>
<h3 id=buckets oldids=boxes>Buckets</h3>

A <a>box</a> has <dfn export for=box>mode</dfn> which is either "<code title>best-effort</code>" or
"<code title>persistent</code>". A <dfn export>persistent box</dfn> is a <a>box</a> whose
<a>mode</a> is "<code title>persistent</code>". A <dfn export>non-persistent box</dfn> is a
<a>box</a> whose <a>mode</a> is <em>not</em> "<code title>persistent</code>".
A <a>bucket</a> has <dfn export for=bucket oldids=box-mode>mode</dfn> which is either
"<code title>best-effort</code>" or "<code title>persistent</code>". A
<dfn export oldids=persistent-box>persistent bucket</dfn> is a <a>bucket</a> whose
<a for=bucket>mode</a> is "<code title>persistent</code>". A
<dfn export oldids=non-persistent-box>non-persistent bucket</dfn> is a <a>bucket</a> whose
<a for=bucket>mode</a> is <em>not</em> "<code title>persistent</code>".

A box is considered to be an atomic unit. Whenever a <a>box</a> is cleared by the user agent, it
must be cleared in its entirety.
A bucket is considered to be an atomic unit. Whenever a <a>bucket</a> is cleared by the user agent,
it must be cleared in its entirety.



<h2 id=persistence>Persistence permission</h2>

A <a>box</a> can only be turned into a <a>persistent box</a> if the user (or user agent
A <a>bucket</a> can only be turned into a <a>persistent bucket</a> if the user (or user agent
on behalf of the user) has granted permission to use the {{"persistent-storage"}} feature.

<p class="note">When granted to an <a for=/>origin</a>, the persistence permission can be used to
Expand All @@ -165,8 +167,8 @@ The <dfn for="PermissionName" enum-value>"<code>persistent-storage</code>"</dfn>

<dt><a>permission revocation algorithm</a></dt>
<dd algorithm="permission-revocation">If {{"persistent-storage"}}'s <a>permission state</a> is not
{{"granted"}}, then set the current <a for=/>origin</a>’s <a>site storage unit</a>'s <a>box</a>'s
<a>mode</a> to "<code>best-effort</code>".</dd>
{{"granted"}}, then set the current <a for=/>origin</a>’s <a>site storage unit</a>'s
<a>bucket</a>'s <a for=bucket>mode</a> to "<code>best-effort</code>".</dd>
</dl>


Expand Down Expand Up @@ -211,8 +213,8 @@ somewhat easier to understand and differentiate for users from network storage a
<h3 id=storage-pressure>Storage Pressure</h3>

When the user agent notices it comes under storage pressure and it cannot free up sufficient space
by clearing network storage and <a>non-persistent boxes</a> within <a>site storage</a>, then the
user agent should alert the user and offer a way to clear <a>persistent boxes</a>.
by clearing network storage and <a>non-persistent buckets</a> within <a>site storage</a>, then the
user agent should alert the user and offer a way to clear <a>persistent buckets</a>.



Expand Down Expand Up @@ -268,8 +270,8 @@ these steps:

<ol>
<li>
<p>Let <var>persisted</var> be true if <var>origin</var>'s <a>site storage unit</a>'s <a>box</a>
is a <a>persistent box</a>, and false otherwise.
<p>Let <var>persisted</var> be true if <var>origin</var>'s <a>site storage unit</a>'s
<a>bucket</a> is a <a>persistent bucket</a>, and false otherwise.

<p class=note>It will be false when there's an internal error.

Expand Down Expand Up @@ -305,15 +307,15 @@ steps:

<li>
<p>Let <var>persisted</var> be true, if <var>origin</var>'s <a>site storage unit</a>'s
<a>box</a> is a <a>persistent box</a>, and false otherwise.
<a>bucket</a> is a <a>persistent bucket</a>, and false otherwise.

<p class=note>It will be false when there's an internal error.

<li>
<p>If <var>persisted</var> is false and <var>permission</var> is {{"granted"}}, then:

<ol>
<li><p>Set <var>origin</var>'s <a>site storage unit</a>'s <a>box</a>'s <a>mode</a> to
<li><p>Set <var>origin</var>'s <a>site storage unit</a>'s <a>bucket</a>'s <a>mode</a> to
"<code>persistent</code>".

<li><p>If there was no internal error, then set <var>persisted</var> to true.
Expand Down Expand Up @@ -375,6 +377,7 @@ Ben Kelly,
Ben Turner,
Dale Harvey,
David Grogan,
fantasai,
Jake Archibald<!-- technically B.J. Archibald -->,
Jeffrey Yasskin,
Jonas Sicking,
Expand Down

0 comments on commit 0ecf0dd

Please sign in to comment.