From 8d9ae4df8b512bbaf325760e6e2c601789403cfb Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Wed, 20 Sep 2017 16:07:06 -0700 Subject: [PATCH] Remove permissions.request() and permissions.revoke(). They've moved to incubations in https://github.com/jyasskin/permissions-request and https://github.com/jyasskin/permissions-revoke. This fixes #46 and fixes #83. --- index.bs | 156 +++++++------------------------------------------------ 1 file changed, 20 insertions(+), 136 deletions(-) diff --git a/index.bs b/index.bs index 1fb22dd..3230aed 100644 --- a/index.bs +++ b/index.bs @@ -77,24 +77,28 @@ spec: webidl

This section is non-normative.

- This document specifies a model and an API to query and request permissions - to powerful features on the Web platform. Web APIs have different ways to - deal with permissions. The [[notifications]] API allows developers to - request a permission and check the permission status explicitly. - Others expose the status to web pages when they try to use the API, - like the [[geolocation-API]] which fails if the permission was not - granted without allowing the developer to check beforehand. + This document specifies a model for permissions to use powerful features on + the Web platform and an API to query the current permission state of those + features.

- The Permissions API provides tools for developers to control when permission - prompts are shown and to relinquish permissions that are no longer needed. + Current Web APIs have different ways to deal with permissions. For example, + the [[notifications]] API allows developers to request a permission and + check the permission status explicitly. Others expose the status to web + pages when they try to use the API, like the [[geolocation-API]] which fails + if the permission was not granted without allowing the developer to check + beforehand. +

+

+ The {{Permissions/query()}} function provides a tool for developers to + control when permission prompts are shown.

The solution described in this document is meant to be extensible, but isn't - meant to be applicable to all the current and future permissions - available in the web platform. Working Groups that are creating specifications - whose permission model doesn't fit in the model described in this document - should contact the editors by + expected to be applicable to all the current and future permissions + available in the web platform. Working Groups that are creating + specifications whose permission model doesn't fit in the model described in + this document should contact the editors by filing an issue.

@@ -510,10 +514,6 @@ spec: webidl [Exposed=(Window,Worker)] interface Permissions { Promise<PermissionStatus> query(object permissionDesc); - - Promise<PermissionStatus> request(object permissionDesc); - - Promise<PermissionStatus> revoke(object permissionDesc); };

@@ -554,76 +554,6 @@ spec: webidl recommend the use of {{Promise}}.all(). An example can be found in the Examples section. - -

- When the request(permissionDesc) method - is invoked, the user agent MUST run the following algorithm, passing the - parameter permissionDesc: -

-
    -
  1. Let |rootDesc| be the object |permissionDesc| refers to, converted to - an IDL value of type {{PermissionDescriptor}}. If this throws an - exception, return a promise rejected with that exception and abort - these steps. -
    2. -
  2. Let |typedDescriptor| be the object |permissionDesc| refers to, - converted to an IDL value of - |rootDesc|.{{PermissionDescriptor/name}}'s permission - descriptor type. If this throws an exception, return a promise - rejected with that exception and abort these steps. -
    3. -
  3. Let promise be a newly-created {{Promise}}. -
    4. -
  4. Return promise and continue the following steps - asynchronously. -
    5. -
  5. Run the steps to create a PermissionStatus for - typedDescriptor, and let status be the result. -
    6. -
  6. - Run the permission request algorithm of the feature named - |typedDescriptor|.name with typedDescriptor and - status as arguments. -
    7. -
  7. - If the previous step threw an exception, reject |promise| with that - exception. -
    8. -
  8. Otherwise resolve promise with status. -
    9. -
- -

- When the revoke(|permissionDesc|) method - is invoked, - the UA must return a new promise |promise| and run the following - steps in parallel: -

-
    -
  1. Let |rootDesc| be the object |permissionDesc| refers to, converted to - an IDL value of type {{PermissionDescriptor}}. If this throws an - exception, return a promise rejected with that exception and abort - these steps. -
    2. -
  2. Let |typedDescriptor| be the object |permissionDesc| refers to, - converted to an IDL value of - |rootDesc|.{{PermissionDescriptor/name}}'s permission - descriptor type. If this throws an exception, return a promise - rejected with that exception and abort these steps. -
    3. -
  3. The UA now has new - information that the user intends to revoke permission to use the - feature described by |typedDescriptor|. -
    4. -
  4. - If any tasks run due to , wait for - them to finish. -
    5. -
  5. - Resolve |promise| with the result of query(|permissionDesc|). -
    6. -

@@ -640,36 +570,6 @@ spec: webidl permission state. -

- The boolean permission request algorithm, given a - {{PermissionDescriptor}} permissionDesc and a - {{PermissionStatus}} status, runs the following steps: -

-
    -
  1. - Run the boolean permission query algorithm on |permissionDesc| and - |status|. -
    2. -
  2. - If |status|.state is not {{"prompt"}}, abort these steps. -
    3. -
  3. - Request permission to use |permissionDesc|. -
    4. -
  4. - Run the boolean permission query algorithm again on - |permissionDesc| and |status|. - -

    - On browsers that don't store permissions persistently within an - environment settings object, this will always return - {{"prompt"}}, but still show the user an unnecessary prompt. That may - mean that no permissions should use the boolean permission request - algorithm, since it can never return an appropriate - object-capability. -

    -
    5. -

@@ -781,35 +681,19 @@ spec: webidl Takes an instance of the permission descriptor type and a new or existing instance of the permission result type, and updates the permission result type instance with the query result. Used by - {{Permissions}}' {{Permissions/query()}} method and the PermissionStatus update steps. If unspecified, this defaults to the boolean permission query algorithm. -
- A permission request algorithm -
-
- Takes an instance of the permission descriptor type and a - newly-created instance of the permission result type. Uses the - algorithms in to show the user - any necessary prompt to try to increase permissions, and updates the - instance permission result type to match. May throw an exception if - the request can fail exceptionally. (Merely being denied permission is not - exceptional.) Used by {{Permissions}}' {{Permissions/request()}} method. - If unspecified, this defaults to the boolean permission request - algorithm. -
A permission revocation algorithm
Takes no arguments. Updates any other parts of the implementation that need to be kept in sync with changes in the results of permission - states or extra permission data. Run by {{Permissions}}' - {{Permissions/revoke()}} method and run when the UA receives new - information about the user's intent. If unspecified, this defaults to - doing nothing. + states or extra permission data. Run by [[#reacting-to-revocation]]. + If unspecified, this defaults to doing nothing.