Skip to content

Commit

Permalink
Editorial: group algorithms into own section
Browse files Browse the repository at this point in the history
  • Loading branch information
@marcoscaceres
marcoscaceres committed Feb 14, 2022
1 parent 5a804b9 commit acd1296
Showing 1 changed file with 175 additions and 170 deletions.
345 changes: 175 additions & 170 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -305,176 +305,6 @@ <h3>
</aside>
</section>
</section>
<section data-cite="permissions-policy">
<h3 id="reading-current-states">
Reading the current permission state
</h3>
<p>
To <dfn class="export" data-lt="getting the current permission state">get the current
permission state</dfn>, given a [=powerful feature/name=] |name| and an optional
[=environment settings object=] |settings|:
</p>
<ol class="algorithm">
<li>Let |descriptor:PermissionDescriptor| be a newly-created {{PermissionDescriptor}}
whose {{PermissionDescriptor/name}} is initialized with |name|.
</li>
<li>Return the [=permission state=] of |descriptor| and |settings|.
</li>
</ol>
<p>
A |descriptor|'s <dfn class="export" data-local-lt="state">permission state</dfn> for an
optional <a>environment settings object</a> |settings| is the result of the following
algorithm, which returns one of {{PermissionState/"granted"}},
{{PermissionState/"prompt"}}, or {{PermissionState/"denied"}}:
</p>
<ol class="algorithm">
<li>If |settings| wasn't passed, set it to the [=current settings object=].
</li>
<li>If |settings| is a <a>non-secure context</a>, return {{PermissionState/"denied"}}.
</li>
<li>If there exists a [=policy-controlled feature=] identified by |descriptor|'s
{{PermissionDescriptor/name}} and |settings| has an <a>associated `Document`</a> named
<var>document</var>, run the following step:
<ol class="algorithm">
<li>If <var>document</var> is not <a>allowed to use</a> the feature identified by
|descriptor|'s {{PermissionDescriptor/name}} return {{PermissionState/"denied"}}.
</li>
</ol>
</li>
<li>If there was a previous invocation of this algorithm with the same |descriptor| and
|settings|, returning |previousResult|, and the UA has not received <a>new information
about the user's intent</a> since that invocation, return |previousResult|.
</li>
<li>Return whichever of the following options most accurately reflects the user's intent
for the calling algorithm, taking into account any [=powerful feature/permission state
constraints=] for |descriptor|'s {{PermissionDescriptor/name}}:
<dl class="switch">
<dt>
succeed without prompting the user
</dt>
<dd>
{{PermissionState/"granted"}}
</dd>
<dt>
show the user a prompt to decide whether to succeed
</dt>
<dd>
{{PermissionState/"prompt"}}
</dd>
<dt>
fail without prompting the user
</dt>
<dd>
{{PermissionState/"denied"}}
</dd>
</dl>
</li>
</ol>
<aside class="issue" id="issue-current-entry-incumbent-or-relevant" data-number="278">
</aside>
<p>
As a shorthand, a {{PermissionName}} |name|'s <a>permission state</a> is the
<a>permission state</a> of a {{PermissionDescriptor}} with its
{{PermissionDescriptor/name}} member set to |name|.
</p>
</section>
<section>
<h3 id="requesting-more-permission">
Requesting permission to use a powerful feature
</h3>
<p class="note">
Spec authors, please note that algorithms in this section can wait for user input; so
they shouldn't be used from other algorithms running on the main thread.
</p>
<p>
To <dfn data-lt="request permission to use|requesting permission to use" class=
"export">request permission to use</dfn> a |descriptor|, the UA must perform the
following steps. This algorithm returns either {{PermissionState/"granted"}} or
{{PermissionState/"denied"}}.
</p>
<ol class="algorithm">
<li>Let <var>current state</var> be the |descriptor|'s <a>permission state</a>.
</li>
<li>If <var>current state</var> is not {{PermissionState/"prompt"}}, return <var>current
state</var> and abort these steps.
</li>
<li>Ask the user for <a>express permission</a> for the calling algorithm to use the
<a>powerful feature</a> described by |descriptor|.
</li>
<li>If the user grants permission, return {{PermissionState/"granted"}}; otherwise return
{{PermissionState/"denied"}}. The user's interaction may provide <a>new information about
the user's intent</a> for this [=global object/realm=] and other [=global object/realms=]
with the <a>same origin</a>.
<p class="note">
This is intentionally vague about the details of the permission UI and how the UA
infers user intent. UAs should be able to explore lots of UI within this framework.
</p>
</li>
</ol>
<p>
As a shorthand, <a>requesting permission to use</a> a {{PermissionName}} |name|, is the
same as <a>requesting permission to use</a> a {{PermissionDescriptor}} with its
{{PermissionDescriptor/name}} member set to |name|.
</p>
</section>
<section>
<h3>
Prompt the user to choose
</h3>
<p>
To <dfn data-lt="prompt the user to choose|prompting the user to choose" class=
"export">prompt the user to choose</dfn> one of several |options| associated with a
|descriptor|, the UA must perform the following steps. This algorithm returns either
{{PermissionState/"denied"}} or one of the options.
</p>
<ol class="algorithm">
<li>If |descriptor|'s <a>permission state</a> is {{PermissionState/"denied"}}, return
{{PermissionState/"denied"}} and abort these steps.
</li>
<li>If |descriptor|'s <a>permission state</a> is {{PermissionState/"granted"}}, the UA
may return one of |options| and abort these steps. If the UA returns without prompting,
then subsequent <a data-lt="prompt the user to choose">prompts for the user to choose</a>
from the same set of options with the same |descriptor| must return the same option,
unless the UA receives <a>new information about the user's intent</a>.
</li>
<li>Ask the user to choose one of the options or deny permission, and wait for them to
choose. If the calling algorithm specified extra information to include in the prompt,
include it.
</li>
<li>If the user chose an option, return it; otherwise return
{{PermissionState/"denied"}}. If the user's interaction indicates they intend this choice
to apply to other realms, then treat this this as <a>new information about the user's
intent</a> for other [=global object/realms=] with the <a>same origin</a>.
<p class="note">
This is intentionally vague about the details of the permission UI and how the UA
infers user intent. UAs should be able to explore lots of UI within this framework.
</p>
</li>
</ol>
<p>
As a shorthand, <a>prompting the user to choose</a> from options associated with a
{{PermissionName}} |name|, is the same as <a>prompting the user to choose</a> from those
options associated with a {{PermissionDescriptor}} with its {{PermissionDescriptor/name}}
member set to |name|.
</p>
</section>
<section>
<h3 id="reacting-to-revocation">
Reacting to users revoking permission
</h3>
<p>
When the UA learns that the user no longer intends to grant permission for a [=global
object/realm=] to use a <a>feature</a>, <dfn>react to the user revoking permission</dfn>
by:
</p>
<ol class="algorithm">
<li>
<a>Queue a task</a> on the Realm's [=Realm/settings object=]'s [=environment settings
object/responsible event loop=] to run that feature's [=powerful feature/permission
revocation algorithm=].
</li>
</ol>
</section>
</section>
<section>
<h2>
Expand Down Expand Up @@ -675,6 +505,181 @@ <h2>
of the above types and algorithms defaulted.
</p>
</section>
<section>
<h2>
Algorithms to interface with permissions
</h2>
<section data-cite="permissions-policy">
<h3 id="reading-current-states">
Reading the current permission state
</h3>
<p>
To <dfn class="export" data-lt="getting the current permission state">get the current
permission state</dfn>, given a [=powerful feature/name=] |name| and an optional
[=environment settings object=] |settings|:
</p>
<ol class="algorithm">
<li>Let |descriptor:PermissionDescriptor| be a newly-created {{PermissionDescriptor}}
whose {{PermissionDescriptor/name}} is initialized with |name|.
</li>
<li>Return the [=permission state=] of |descriptor| and |settings|.
</li>
</ol>
<p>
A |descriptor|'s <dfn class="export" data-local-lt="state">permission state</dfn> for an
optional <a>environment settings object</a> |settings| is the result of the following
algorithm, which returns one of {{PermissionState/"granted"}},
{{PermissionState/"prompt"}}, or {{PermissionState/"denied"}}:
</p>
<ol class="algorithm">
<li>If |settings| wasn't passed, set it to the [=current settings object=].
</li>
<li>If |settings| is a <a>non-secure context</a>, return {{PermissionState/"denied"}}.
</li>
<li>If there exists a [=policy-controlled feature=] identified by |descriptor|'s
{{PermissionDescriptor/name}} and |settings| has an <a>associated `Document`</a> named
<var>document</var>, run the following step:
<ol class="algorithm">
<li>If <var>document</var> is not <a>allowed to use</a> the feature identified by
|descriptor|'s {{PermissionDescriptor/name}} return {{PermissionState/"denied"}}.
</li>
</ol>
</li>
<li>If there was a previous invocation of this algorithm with the same |descriptor| and
|settings|, returning |previousResult|, and the UA has not received <a>new information
about the user's intent</a> since that invocation, return |previousResult|.
</li>
<li>Return whichever of the following options most accurately reflects the user's intent
for the calling algorithm, taking into account any [=powerful feature/permission state
constraints=] for |descriptor|'s {{PermissionDescriptor/name}}:
<dl class="switch">
<dt>
succeed without prompting the user
</dt>
<dd>
{{PermissionState/"granted"}}
</dd>
<dt>
show the user a prompt to decide whether to succeed
</dt>
<dd>
{{PermissionState/"prompt"}}
</dd>
<dt>
fail without prompting the user
</dt>
<dd>
{{PermissionState/"denied"}}
</dd>
</dl>
</li>
</ol>
<aside class="issue" id="issue-current-entry-incumbent-or-relevant" data-number="278">
</aside>
<p>
As a shorthand, a {{PermissionName}} |name|'s <a>permission state</a> is the
<a>permission state</a> of a {{PermissionDescriptor}} with its
{{PermissionDescriptor/name}} member set to |name|.
</p>
</section>
<section>
<h3 id="requesting-more-permission">
Requesting permission to use a powerful feature
</h3>
<p class="note">
Spec authors, please note that algorithms in this section can wait for user input; so
they shouldn't be used from other algorithms running on the main thread.
</p>
<p>
To <dfn data-lt="request permission to use|requesting permission to use" class=
"export">request permission to use</dfn> a |descriptor|, the UA must perform the
following steps. This algorithm returns either {{PermissionState/"granted"}} or
{{PermissionState/"denied"}}.
</p>
<ol class="algorithm">
<li>Let <var>current state</var> be the |descriptor|'s <a>permission state</a>.
</li>
<li>If <var>current state</var> is not {{PermissionState/"prompt"}}, return <var>current
state</var> and abort these steps.
</li>
<li>Ask the user for <a>express permission</a> for the calling algorithm to use the
<a>powerful feature</a> described by |descriptor|.
</li>
<li>If the user grants permission, return {{PermissionState/"granted"}}; otherwise return
{{PermissionState/"denied"}}. The user's interaction may provide <a>new information about
the user's intent</a> for this [=global object/realm=] and other [=global object/realms=]
with the <a>same origin</a>.
<p class="note">
This is intentionally vague about the details of the permission UI and how the UA
infers user intent. UAs should be able to explore lots of UI within this framework.
</p>
</li>
</ol>
<p>
As a shorthand, <a>requesting permission to use</a> a {{PermissionName}} |name|, is the
same as <a>requesting permission to use</a> a {{PermissionDescriptor}} with its
{{PermissionDescriptor/name}} member set to |name|.
</p>
</section>
<section>
<h3>
Prompt the user to choose
</h3>
<p>
To <dfn data-lt="prompt the user to choose|prompting the user to choose" class=
"export">prompt the user to choose</dfn> one of several |options| associated with a
|descriptor|, the UA must perform the following steps. This algorithm returns either
{{PermissionState/"denied"}} or one of the options.
</p>
<ol class="algorithm">
<li>If |descriptor|'s <a>permission state</a> is {{PermissionState/"denied"}}, return
{{PermissionState/"denied"}} and abort these steps.
</li>
<li>If |descriptor|'s <a>permission state</a> is {{PermissionState/"granted"}}, the UA
may return one of |options| and abort these steps. If the UA returns without prompting,
then subsequent <a data-lt="prompt the user to choose">prompts for the user to choose</a>
from the same set of options with the same |descriptor| must return the same option,
unless the UA receives <a>new information about the user's intent</a>.
</li>
<li>Ask the user to choose one of the options or deny permission, and wait for them to
choose. If the calling algorithm specified extra information to include in the prompt,
include it.
</li>
<li>If the user chose an option, return it; otherwise return
{{PermissionState/"denied"}}. If the user's interaction indicates they intend this choice
to apply to other realms, then treat this this as <a>new information about the user's
intent</a> for other [=global object/realms=] with the <a>same origin</a>.
<p class="note">
This is intentionally vague about the details of the permission UI and how the UA
infers user intent. UAs should be able to explore lots of UI within this framework.
</p>
</li>
</ol>
<p>
As a shorthand, <a>prompting the user to choose</a> from options associated with a
{{PermissionName}} |name|, is the same as <a>prompting the user to choose</a> from those
options associated with a {{PermissionDescriptor}} with its {{PermissionDescriptor/name}}
member set to |name|.
</p>
</section>
<section>
<h3 id="reacting-to-revocation">
Reacting to users revoking permission
</h3>
<p>
When the UA learns that the user no longer intends to grant permission for a [=global
object/realm=] to use a <a>feature</a>, <dfn>react to the user revoking permission</dfn>
by:
</p>
<ol class="algorithm">
<li>
<a>Queue a task</a> on the Realm's [=Realm/settings object=]'s [=environment settings
object/responsible event loop=] to run that feature's [=powerful feature/permission
revocation algorithm=].
</li>
</ol>
</section>
</section>
<section>
<h2>
Permissions API
Expand Down

0 comments on commit acd1296

Please sign in to comment.