Merge pull request jmapio#376 from Arsnael/jmap-quotas-11

Jmap quotas version 11
rjbs · Feb 2, 2023 · 33a0c17 · 33a0c17
2 parents 9f8e328 + cfef6d9
commit 33a0c17
Show file tree

Hide file tree

Showing 4 changed files with 44 additions and 28 deletions.
diff --git a/rfc/src/quotas.mdown b/rfc/src/quotas.mdown
@@ -2,17 +2,17 @@
     title = "JMAP for Quotas"
     abbrev = "JMAP Quotas"
     category = "std"
-    docName = "draft-ietf-jmap-quotas-10"
+    docName = "draft-ietf-jmap-quotas-11"
     ipr= "trust200902"
     area = "Applications"
     workgroup = "JMAP Working Group"
     keyword = ["JMAP", "JSON", "email", "quotas"]
 
-    date = 2022-11-30T00:00:00Z
+    date = 2023-01-31T00:00:00Z
 
     [seriesInfo]
     name="Internet-Draft"
-    value="draft-ietf-jmap-quotas-10"
+    value="draft-ietf-jmap-quotas-11"
     stream="IETF"
     status="standard"
 
@@ -34,13 +34,14 @@
 
 .# Abstract
 
-This document specifies a data model for handling quotas on accounts with a server using JMAP.
+This document specifies a data model for handling quotas on accounts with a server using the JSON Meta Application Protocol (JMAP).
 
 {mainmatter}
 
 {{spec/quotas/intro.mdown}}
 {{spec/quotas/quota.mdown}}
 {{spec/quotas/securityconsiderations.mdown}}
 {{spec/quotas/ianaconsiderations.mdown}}
+{{spec/quotas/acknowledgements.mdown}}
 
 {backmatter}
diff --git a/spec/quotas/acknowledgements.mdown b/spec/quotas/acknowledgements.mdown
@@ -0,0 +1,13 @@
+# Acknowledgements
+
+Thank you to Michael Bailly, that co-wrote the first draft version of this document, before deciding to turn to other matters.
+
+Thank you to Benoit Tellier for his constant help and support on writing this document.
+
+Thank you to Raphael Ouazana for sharing his own experience on how to write a RFC after finalizing his own document, the [@!RFC9007].
+
+Thank you to Bron Gondwana, Neil Jenkins, Alexei Melnikov, Joris Baum and the people from the IETF JMAP working group in general
+that helped with extensive discussions, reviews and feedbacks. 
+
+Thank you to the people in the IETF organization that took the time to read, understand, comment and give great feedbacks 
+in the last rounds.
diff --git a/spec/quotas/quota.mdown b/spec/quotas/quota.mdown
@@ -2,6 +2,8 @@
 
 The quota is an object that displays the limit set to an account usage. It then shows as well the current usage in regard to that limit.
 
+## Properties of the quota object
+
 The quota object MUST contain the following fields:
 
 * id: "Id"
@@ -17,7 +19,7 @@ The quota object MUST contain the following fields:
   The current usage of the defined quota, using the "resourceType" defined as unit of measure.
 Computation of this value is handled by the server.
 
-* limit: "UnsignedInt"
+* hardLimit: "UnsignedInt"
 
   The hard limit set by this quota, using the "resourceType" defined as unit of measure. Objects 
 in scope may not be created or updated if this limit is reached.
@@ -42,29 +44,29 @@ The quota object MAY contain the following fields:
 
   The warn limit set by this quota object, using the "resourceType" defined as unit of measure. 
 It can be used to send a warning to an entity about to reach the hard limit soon, but with no action taken yet. If set, it 
-SHOULD be lower than the "softLimit" (if present and different than null) and the "limit".
+SHOULD be lower than the "softLimit" (if present and different from null) and the "limit".
 
 * softLimit: "UnsignedInt|null" 
 
   The soft limit set by this quota object, using the "resourceType" defined as unit of measure.
 It can be used to still allow some operations, but refuse some others. What is allowed or not is up to the server. For example, it
 could be used for blocking outgoing events of an entity (sending emails, creating calendar events, ...) while still receiving
 incoming events (receiving emails, receiving calendars events, ...). If set, it SHOULD be higher than the "warnLimit" 
-(if present and different than null) but lower than the "limit".
+(if present and different from null) but lower than the "limit".
 
 * description: "String|null" 
 
-  Arbitrary free, human readable, description of this quota. It might be used to explain
-where the limit comes from and explain the entities and data types this quota applies to. The description MUST be 
+  Arbitrary free, human-readable, description of this quota. It might be used to explain
+where the different limits come from and explain the entities and data types this quota applies to. The description MUST be 
 encoded in UTF-8 [@!RFC3629] as described in [@!RFC8620] section 1.5, selected based on an Accept-Language header in the request
-(as defined in [RFC9110], Section 12.5.4) or out-of-band information about the user's language/locale.
+(as defined in [@!RFC9110], Section 12.5.4) or out-of-band information about the user's language/locale.
 
 The following JMAP methods are supported.
 
 ## Quota/get
 
 Standard "/get" method as described in [@!RFC8620] section 5.1. The *ids* argument may be "null" to fetch all Quotas of the account 
-at once, as demonstrated in this document at (#fetching-quotas).
+at once, as demonstrated in this document in (#fetching-quotas).
 
 ## Quota/changes
 
@@ -81,27 +83,27 @@ optimise data transfer by keeping track of changes to Quota usage separate from
 updatedProperties array may be used directly via a back-reference in a subsequent Quota/get call in the same request,
 so only these properties are returned if nothing else has changed.
 
-Servers MAY decide to add other properties to the list that they judge changing frequently.
+Servers MAY decide to add other properties to the list that they judge to be changing frequently.
 
 This method's usage is demonstrated in this document at (#requesting-latest-quota-changes).
 
 ## Quota/query
 
 This is a standard "/query" method as described in [@!RFC8620], Section 5.5.
 
-A **FilterCondition** object has the following properties, any of which may be omitted:
+A **FilterCondition** object has the following properties, any of which may be included or  omitted:
 
 * name: "String" 
 
   The Quota _name_ property contains the given string.
 
-* scopes: "Scope[]" 
+* scope: "Scope" 
 
-  The Quota _scope_ property must be in this list to match the condition.
+  The Quota _scope_ property must match the given value exactly.
 
-* resourceTypes: "ResourceType[]" 
+* resourceType: "ResourceType" 
 
-  The Quota _resourceType_ property must be in this list to match the condition.
+  The Quota _resourceType_ property must match the given value exactly.
 
 * dataTypes: "String[]" 
 
@@ -142,10 +144,10 @@ With response :
         "used": 1056,
         "warnLimit": 1600,
         "softLimit": 1800,
-        "limit": 2000,
+        "hardLimit": 2000,
         "scope": "account",
         "name": "bob@example.com",
-        "description": "Personal account usage",
+        "description": "Personal account usage. When the soft limit is reached, the user is not allowed to send mails or create contacts and calendar events anymore.",
         "dataTypes" : [ "Mail", "Calendar", "Contact" ]
       }, {
         "id": "3b06df0e-3761-4s74-a92f-74dcc963501x",
@@ -161,7 +163,7 @@ Request fetching the changes for a specific quota:
 
     [[ "Quota/changes", {
       "accountId": "u33084183",
-      "sinceState": "10824",
+      "sinceState": "78540",
       "maxChanges": 20
     }, "0" ],
     [ "Quota/get", {
@@ -182,8 +184,8 @@ With response:
 
     [[ "Quota/changes", {
       "accountId": "u33084183",
-      "oldState": "10824",
-      "newState": "10826",
+      "oldState": "78540",
+      "newState": "78542",
       "hasMoreChanges": false,
       "updatedProperties": ["used"],
       "created": [],
@@ -202,5 +204,5 @@ With response:
 
 # Push
 
-Servers MUST support the JMAP push mechanisms, as specified in [@!RFC8620] Section 7, to receive notifications when
-the state changes for the Quota type defined in this specification.
+Servers MUST support the JMAP push mechanisms, as specified in [@!RFC8620] Section 7, to allow clients to receive 
+notifications when the state changes for the Quota type defined in this specification.
diff --git a/spec/quotas/securityconsiderations.mdown b/spec/quotas/securityconsiderations.mdown
@@ -12,8 +12,8 @@ make the shared resource hit the limit and unusable for others (implementors cou
 implementation on the server).
 
 Also, revealing domain and global quota counts to all users may cause privacy leakage of other sensitive data, 
-or at least the existence of other sensitive data. For example, "user1" is part of a private list
-belonging to the server, so he shouldn't know how many users are in there. But by comparing the quota count
+or at least the existence of other sensitive data. For example, some users are part of a private list
+belonging to the server, so they shouldn't know how many users are in there. But by comparing the quota count
 before and after sending a message to the list, it could reveal the number of people of the list, as the 
-domain or global quota count would go up by the number of people subscribed. Likely to limit those attacks, quotas with 
-"domain" or "global" scope should only be visible to the administrators of the server and not all users.
+domain or global quota count would go up by the number of people subscribed. In order to limit those attacks, quotas with 
+"domain" or "global" scope SHOULD only be visible to server administrators and not to general users.