Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Integrate with the Permissions spec. #36

Merged
merged 6 commits into from
Oct 11, 2016
Merged

Integrate with the Permissions spec. #36

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
8cee49d
Integrate with the Permissions spec.
jyasskin Jul 21, 2016
7803cc1
Try a different enum-value dfn formatting.
jyasskin Jul 22, 2016
2ff9018
Put "Let |permission| be" at the beginning of its sentence.
jyasskin Jul 27, 2016
0c5c532
Formatting and wording tweaks from @annevk.
jyasskin Jul 27, 2016
0800e6d
Use "persistent-storage" directly instead of wrapping it into a descr…
jyasskin Aug 5, 2016
a9d477a
minor nits / date bump
annevk Oct 11, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 20 additions & 16 deletions storage.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ Promise.all([
]).then((persisted, permission) => {
if(!persisted && permission == "granted") {
navigator.storage.persist().then( /* … */ )
} else if(!persistent && permission == "default") {
} else if(!persistent && permission == "prompt") {
showPersistentStorageExplanation()
}
})
Expand Down Expand Up @@ -148,16 +148,26 @@ 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
on behalf of the user) has granted <dfn>permission</dfn>.
on behalf of the user) has granted permission to use the {{"persistent-storage"}} feature.

<p class="note">When granted to an <a>origin</a>, the persistence permission can be used to protect
storage from the user agent's clearing policies. The user agent cannot clear storage marked as
persistent without involvement from the <a>origin</a> or user. This makes it particularly useful for
resources the user needs to have available while offline or resources the user creates locally.

<p class="XXX">We will eventually integrate with the Permissions API, with the identifier
"<dfn export for=PermissionName type=enum-value><code>persistent-storage</code></dfn>", but since
that specification is not in great shape at the moment that has not happened yet.
The <dfn for="PermissionName" enum-value>"<code>persistent-storage</code>"</dfn>
<a>powerful feature</a>'s permission-related flags, algorithms, and types are defaulted, except for:

<dl>
<dt><a>permission state</a></dt>
<dd>{{"persistent-storage"}}'s <a>permission state</a> must have the same value for all
<a>environment settings objects</a> with a given <a>origin</a>.</dd>

<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>origin</a>’s <a>site storage unit</a>'s <a>box</a>'s
<a>mode</a> to "<code>best-effort</code>".</dd>
</dl>



Expand All @@ -177,7 +187,7 @@ room.

<p class=note>User agents are strongly encouraged to provide "popular" <a>origins</a> with a larger
<a>site storage quota</a>. Factors such as navigation frequency, recency of visits, bookmarking,
and <a>permission</a> for "<code>persistent-storage</code>" can be used as indications of
and <a href="#persistence">permission</a> for {{"persistent-storage"}} can be used as indications of
"popularity".


Expand Down Expand Up @@ -280,25 +290,18 @@ steps:
<ol>
<li><p>Let <var>origin</var> be <var>settingsObject</var>'s <a>origin</a>.

<li><p>Let <var>permission</var> be <a>permission</a> for <var>origin</var>.

<li>
<p>If <var>permission</var> is "<code title>prompt</code>", then determine through asking the
user or using heuristics whether <var>origin</var> is allowed to use persistent storage. If that
returns a positive answer, then set <var>permission</var> to "<code title>granted</code>". If
that returns a negative answer, then set <var>permission</var> to "<code title>denied</code>".
If that returns no answer, then do not alter <var>permission</var>.
<p>Let <var>permission</var> be the result of <a>requesting permission to use</a>
{{"persistent-storage"}}.

<p class="note">User agents are encouraged to not let the user answer this question twice for
the same <a>origin</a> around the same time and this algorithm is not equipped to handle such a
scenario.

<li><p>Set <a>permission</a> for <var>origin</var> to <var>permission</var>.

<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.

<li><p>If <var>persisted</var> is false and <var>permission</var> is "<code>granted</code>", then
<li><p>If <var>persisted</var> is false and <var>permission</var> is {{"granted"}}, then
set <var>persisted</var> to true and set <var>origin</var>'s <a>site storage unit</a>'s
<a>box</a>'s <a>mode</a> to "<code>persistent</code>".

Expand Down Expand Up @@ -350,6 +353,7 @@ Ben Turner,
Dale Harvey,
David Grogan,
Jake Archibald<!-- technically B.J. Archibald -->,
Jeffrey Yasskin,
Jonas Sicking,
Joshua Bell,
Kenji Baheux,
Expand Down
45 changes: 26 additions & 19 deletions storage.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@
<p data-fill-with="logo"><a class="logo" href="https://whatwg.org/"> <img alt="WHATWG" height="100" src="https://resources.whatwg.org/logo-storage.svg"> </a> </p>
<hgroup>
<h1 class="p-name no-ref" id="title">Storage</h1>
<h2 class="no-num no-toc no-ref heading settled" id="subtitle"><span class="content">Living Standard — Last Updated <time class="dt-updated" datetime="2016-09-30">30 September 2016</time></span></h2>
<h2 class="no-num no-toc no-ref heading settled" id="subtitle"><span class="content">Living Standard — Last Updated <time class="dt-updated" datetime="2016-10-11">11 October 2016</time></span></h2>
</hgroup>
<div data-fill-with="spec-metadata">
<dl>
Expand Down Expand Up @@ -157,7 +157,7 @@ <h2 class="heading settled" data-level="1" id="introduction"><span class="secno"
<span class="p">]</span><span class="p">)</span><span class="p">.</span>then<span class="p">(</span><span class="p">(</span>persisted<span class="p">,</span> permission<span class="p">)</span> <span class="o">=></span> <span class="p">{</span>
<span class="k">if</span><span class="p">(</span><span class="o">!</span>persisted <span class="o">&amp;&amp;</span> permission <span class="o">==</span> <span class="s2">"granted"</span><span class="p">)</span> <span class="p">{</span>
navigator<span class="p">.</span>storage<span class="p">.</span>persist<span class="p">(</span><span class="p">)</span><span class="p">.</span>then<span class="p">(</span> <span class="cm">/* … */</span> <span class="p">)</span>
<span class="p">}</span> <span class="k">else</span> <span class="k">if</span><span class="p">(</span><span class="o">!</span>persistent <span class="o">&amp;&amp;</span> permission <span class="o">==</span> <span class="s2">"default"</span><span class="p">)</span> <span class="p">{</span>
<span class="p">}</span> <span class="k">else</span> <span class="k">if</span><span class="p">(</span><span class="o">!</span>persistent <span class="o">&amp;&amp;</span> permission <span class="o">==</span> <span class="s2">"prompt"</span><span class="p">)</span> <span class="p">{</span>
showPersistentStorageExplanation<span class="p">(</span><span class="p">)</span>
<span class="p">}</span>
<span class="p">}</span><span class="p">)</span>
Expand Down Expand Up @@ -208,14 +208,18 @@ <h3 class="heading settled" data-level="3.1" id="boxes"><span class="secno">3.1.
must be cleared in its entirety.</p>
<h2 class="heading settled" data-level="4" id="persistence"><span class="secno">4. </span><span class="content">Persistence permission</span><a class="self-link" href="#persistence"></a></h2>
<p>A <a data-link-type="dfn" href="#box">box</a> can only be turned into a <a data-link-type="dfn" href="#persistent-box">persistent box</a> if the user (or user agent
on behalf of the user) has granted <dfn data-dfn-type="dfn" data-noexport="" id="permission">permission<a class="self-link" href="#permission"></a></dfn>.</p>
on behalf of the user) has granted permission to use the <code class="idl"><a data-link-type="idl" href="#dom-permissionname-persistent-storage">"persistent-storage"</a></code> feature.</p>
<p class="note" role="note">When granted to an <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/browsers.html#origin">origin</a>, the persistence permission can be used to protect
storage from the user agent’s clearing policies. The user agent cannot clear storage marked as
persistent without involvement from the <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/browsers.html#origin">origin</a> or user. This makes it particularly useful for
resources the user needs to have available while offline or resources the user creates locally. </p>
<p class="XXX">We will eventually integrate with the Permissions API, with the identifier
"<dfn data-dfn-for="PermissionName" data-dfn-type="dfn" data-export="" id="permissionname-persistent-storage" type="enum-value"><code>persistent-storage</code><a class="self-link" href="#permissionname-persistent-storage"></a></dfn>", but since
that specification is not in great shape at the moment that has not happened yet. </p>
<p>The <dfn class="idl-code" data-dfn-for="PermissionName" data-dfn-type="enum-value" data-export="" id="dom-permissionname-persistent-storage">"<code>persistent-storage</code>"<a class="self-link" href="#dom-permissionname-persistent-storage"></a></dfn> <a data-link-type="dfn" href="https://w3c.github.io/permissions/#powerful-feature">powerful feature</a>’s permission-related flags, algorithms, and types are defaulted, except for:</p>
<dl>
<dt><a data-link-type="dfn" href="https://w3c.github.io/permissions/#permission-state">permission state</a>
<dd><code class="idl"><a data-link-type="idl" href="#dom-permissionname-persistent-storage">"persistent-storage"</a></code>'s <a data-link-type="dfn" href="https://w3c.github.io/permissions/#permission-state">permission state</a> must have the same value for all <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/webappapis.html#environment-settings-object">environment settings objects</a> with a given <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/browsers.html#origin">origin</a>.
<dt><a data-link-type="dfn" href="https://w3c.github.io/permissions/#permission-revocation-algorithm">permission revocation algorithm</a>
<dd class="algorithm" data-algorithm="permission-revocation">If <code class="idl"><a data-link-type="idl" href="#dom-permissionname-persistent-storage">"persistent-storage"</a></code>'s <a data-link-type="dfn" href="https://w3c.github.io/permissions/#permission-state">permission state</a> is not <code class="idl"><a data-link-type="idl" href="https://w3c.github.io/permissions/#dom-permissionstate-granted">"granted"</a></code>, then set the current <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/browsers.html#origin">origin</a>’s <a data-link-type="dfn" href="#site-storage-unit">site storage unit</a>’s <a data-link-type="dfn" href="#box">box</a>’s <a data-link-type="dfn" href="#box-mode">mode</a> to "<code>best-effort</code>".
</dl>
<h2 class="heading settled" data-level="5" id="usage-and-quota"><span class="secno">5. </span><span class="content">Usage and quota</span><a class="self-link" href="#usage-and-quota"></a></h2>
<p>The <dfn data-dfn-type="dfn" data-export="" id="site-storage-usage">site storage usage<a class="self-link" href="#site-storage-usage"></a></dfn> of an <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/browsers.html#origin">origin</a> <var>origin</var> is a rough estimate
of the amount of bytes used in <var>origin</var>’s <a data-link-type="dfn" href="#site-storage-unit">site storage unit</a>.</p>
Expand All @@ -226,7 +230,7 @@ <h2 class="heading settled" data-level="5" id="usage-and-quota"><span class="sec
amount should be less than the total available storage space on the device to give users some wiggle
room.</p>
<p class="note" role="note">User agents are strongly encouraged to provide "popular" <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/browsers.html#origin">origins</a> with a larger <a data-link-type="dfn" href="#site-storage-quota">site storage quota</a>. Factors such as navigation frequency, recency of visits, bookmarking,
and <a data-link-type="dfn" href="#permission">permission</a> for "<code>persistent-storage</code>" can be used as indications of
and <a href="#persistence">permission</a> for <code class="idl"><a data-link-type="idl" href="#dom-permissionname-persistent-storage">"persistent-storage"</a></code> can be used as indications of
"popularity". </p>
<h2 class="heading settled" data-level="6" id="ui-guidelines"><span class="secno">6. </span><span class="content">User Interface Guidelines</span><a class="self-link" href="#ui-guidelines"></a></h2>
<p>User agents should not distinguish between network storage and <a data-link-type="dfn" href="#site-storage">site storage</a> in their user
Expand Down Expand Up @@ -300,22 +304,14 @@ <h2 class="heading settled" data-level="7" id="api"><span class="secno">7. </spa
<li>
<p>Let <var>origin</var> be <var>settingsObject</var>’s <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/browsers.html#origin">origin</a>. </p>
<li>
<p>Let <var>permission</var> be <a data-link-type="dfn" href="#permission">permission</a> for <var>origin</var>. </p>
<li>
<p>If <var>permission</var> is "<code title="">prompt</code>", then determine through asking the
user or using heuristics whether <var>origin</var> is allowed to use persistent storage. If that
returns a positive answer, then set <var>permission</var> to "<code title="">granted</code>". If
that returns a negative answer, then set <var>permission</var> to "<code title="">denied</code>".
If that returns no answer, then do not alter <var>permission</var>. </p>
<p>Let <var>permission</var> be the result of <a data-link-type="dfn" href="https://w3c.github.io/permissions/#request-permission-to-use">requesting permission to use</a> <code class="idl"><a data-link-type="idl" href="#dom-permissionname-persistent-storage">"persistent-storage"</a></code>. </p>
<p class="note" role="note">User agents are encouraged to not let the user answer this question twice for
the same <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/browsers.html#origin">origin</a> around the same time and this algorithm is not equipped to handle such a
scenario. </p>
<li>
<p>Set <a data-link-type="dfn" href="#permission">permission</a> for <var>origin</var> to <var>permission</var>. </p>
<li>
<p>Let <var>persisted</var> be true, if <var>origin</var>’s <a data-link-type="dfn" href="#site-storage-unit">site storage unit</a>’s <a data-link-type="dfn" href="#box">box</a> is a <a data-link-type="dfn" href="#persistent-box">persistent box</a>, and false otherwise. </p>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should keep this note I think.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

<li>
<p>If <var>persisted</var> is false and <var>permission</var> is "<code>granted</code>", then
<p>If <var>persisted</var> is false and <var>permission</var> is <code class="idl"><a data-link-type="idl" href="https://w3c.github.io/permissions/#dom-permissionstate-granted">"granted"</a></code>, then
set <var>persisted</var> to true and set <var>origin</var>’s <a data-link-type="dfn" href="#site-storage-unit">site storage unit</a>’s <a data-link-type="dfn" href="#box">box</a>’s <a data-link-type="dfn" href="#box-mode">mode</a> to "<code>persistent</code>". </p>
<li>
<p><a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/webappapis.html#queue-a-task">Queue a task</a> to resolve <var>promise</var> with <var>persisted</var>. </p>
Expand Down Expand Up @@ -359,6 +355,7 @@ <h2 class="no-num heading settled" id="acks"><span class="content">Acknowledgmen
Dale Harvey,
David Grogan,
Jake Archibald,
Jeffrey Yasskin,
Jonas Sicking,
Joshua Bell,
Kenji Baheux,
Expand Down Expand Up @@ -389,11 +386,10 @@ <h3 class="no-num no-ref heading settled" id="index-defined-here"><span class="c
<li><a href="#box-mode">mode</a><span>, in §3.1</span>
<li><a href="#navigatorstorage">NavigatorStorage</a><span>, in §7</span>
<li><a href="#non-persistent-box">non-persistent box</a><span>, in §3.1</span>
<li><a href="#permission">permission</a><span>, in §4</span>
<li><a href="#dom-storagemanager-persist">persist()</a><span>, in §7</span>
<li><a href="#dom-storagemanager-persisted">persisted()</a><span>, in §7</span>
<li><a href="#persistent-box">persistent box</a><span>, in §3.1</span>
<li><a href="#permissionname-persistent-storage">persistent-storage</a><span>, in §4</span>
<li><a href="#dom-permissionname-persistent-storage">"persistent-storage"</a><span>, in §4</span>
<li><a href="#dom-storageestimate-quota">quota</a><span>, in §7</span>
<li><a href="#schemeless-origin-group">schemeless origin group</a><span>, in §2</span>
<li><a href="#site-storage">site storage</a><span>, in §3</span>
Expand Down Expand Up @@ -425,6 +421,15 @@ <h3 class="no-num no-ref heading settled" id="index-defined-elsewhere"><span cla
<li><a href="https://html.spec.whatwg.org/multipage/webappapis.html#relevant-settings-object">relevant settings object</a>
<li><a href="https://html.spec.whatwg.org/multipage/browsers.html#concept-origin-tuple">tuple origin</a>
</ul>
<li>
<a data-link-type="biblio">[permissions]</a> defines the following terms:
<ul>
<li><a href="https://w3c.github.io/permissions/#dom-permissionstate-granted">"granted"</a>
<li><a href="https://w3c.github.io/permissions/#permission-revocation-algorithm">permission revocation algorithm</a>
<li><a href="https://w3c.github.io/permissions/#permission-state">permission state</a>
<li><a href="https://w3c.github.io/permissions/#powerful-feature">powerful feature</a>
<li><a href="https://w3c.github.io/permissions/#request-permission-to-use">requesting permission to use</a>
</ul>
<li>
<a data-link-type="biblio">[URL]</a> defines the following terms:
<ul>
Expand All @@ -445,6 +450,8 @@ <h3 class="no-num no-ref heading settled" id="normative"><span class="content">N
<dd>Anne van Kesteren. <a href="https://dom.spec.whatwg.org/">DOM Standard</a>. Living Standard. URL: <a href="https://dom.spec.whatwg.org/">https://dom.spec.whatwg.org/</a>
<dt id="biblio-html">[HTML]
<dd>Ian Hickson. <a href="https://html.spec.whatwg.org/multipage/">HTML Standard</a>. Living Standard. URL: <a href="https://html.spec.whatwg.org/multipage/">https://html.spec.whatwg.org/multipage/</a>
<dt id="biblio-permissions">[PERMISSIONS]
<dd>Mounir Lamouri; Marcos Caceres. <a href="https://w3c.github.io/permissions/">The Permissions API</a>. 7 April 2015. WD. URL: <a href="https://w3c.github.io/permissions/">https://w3c.github.io/permissions/</a>
<dt id="biblio-rfc2119">[RFC2119]
<dd>S. Bradner. <a href="https://tools.ietf.org/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a>. March 1997. Best Current Practice. URL: <a href="https://tools.ietf.org/html/rfc2119">https://tools.ietf.org/html/rfc2119</a>
<dt id="biblio-url">[URL]
Expand Down