summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc9425.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc9425.txt')
-rw-r--r--doc/rfc/rfc9425.txt518
1 files changed, 518 insertions, 0 deletions
diff --git a/doc/rfc/rfc9425.txt b/doc/rfc/rfc9425.txt
new file mode 100644
index 0000000..0cf697d
--- /dev/null
+++ b/doc/rfc/rfc9425.txt
@@ -0,0 +1,518 @@
+
+
+
+
+Internet Engineering Task Force (IETF) R. Cordier, Ed.
+Request for Comments: 9425 Linagora Vietnam
+Category: Standards Track June 2023
+ISSN: 2070-1721
+
+
+ JSON Meta Application Protocol (JMAP) for Quotas
+
+Abstract
+
+ This document specifies a data model for handling quotas on accounts
+ with a server using the JSON Meta Application Protocol (JMAP).
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 7841.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ https://www.rfc-editor.org/info/rfc9425.
+
+Copyright Notice
+
+ Copyright (c) 2023 IETF Trust and the persons identified as the
+ document authors. All rights reserved.
+
+ This document is subject to BCP 78 and the IETF Trust's Legal
+ Provisions Relating to IETF Documents
+ (https://trustee.ietf.org/license-info) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with respect
+ to this document. Code Components extracted from this document must
+ include Revised BSD License text as described in Section 4.e of the
+ Trust Legal Provisions and are provided without warranty as described
+ in the Revised BSD License.
+
+Table of Contents
+
+ 1. Introduction
+ 1.1. Notational Conventions
+ 1.2. Terminology
+ 2. Addition to the Capabilities Object
+ 2.1. urn:ietf:params:jmap:quota
+ 3. Sub-types of the Quota Data Type
+ 3.1. Scope
+ 3.2. ResourceType
+ 4. Quota
+ 4.1. Properties of the Quota Object
+ 4.2. Quota/get
+ 4.3. Quota/changes
+ 4.4. Quota/query
+ 4.5. Quota/queryChanges
+ 5. Examples
+ 5.1. Fetching Quotas
+ 5.2. Requesting Latest Quota Changes
+ 6. Push
+ 7. IANA Considerations
+ 7.1. JMAP Capability Registration for "quota"
+ 7.2. JMAP Data Type Registration for "Quota"
+ 8. Security Considerations
+ 9. Normative References
+ Acknowledgements
+ Author's Address
+
+1. Introduction
+
+ The JSON Meta Application Protocol (JMAP) [RFC8620] is a generic
+ protocol for synchronizing data, such as mails, calendars, or
+ contacts between a client and a server. It is optimized for mobile
+ and web environments and aims to provide a consistent interface to
+ different data types.
+
+ This specification defines a data model for handling quotas over
+ JMAP, allowing a user to obtain details about a certain quota.
+
+ This specification does not address quota administration, which
+ should be handled by other means.
+
+1.1. Notational Conventions
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
+ "OPTIONAL" in this document are to be interpreted as described in
+ BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
+ capitals, as shown here.
+
+ Type signatures, examples, and property descriptions in this document
+ follow the conventions established in Section 1.1 of [RFC8620]. Data
+ types defined in the core specification are also used in this
+ document.
+
+1.2. Terminology
+
+ This document reuses the terminology from the core JMAP specification
+ established in Section 1.6 of [RFC8620].
+
+ The term "Quota" (when capitalized) is used to refer to the data type
+ defined in Section 4 and instance of that data type.
+
+2. Addition to the Capabilities Object
+
+ The capabilities object is returned as part of the JMAP Session
+ object; see [RFC8620], Section 2.
+
+ This document defines one additional capability URI.
+
+2.1. urn:ietf:params:jmap:quota
+
+ This represents support for the Quota data type and associated API
+ methods. Servers supporting this specification MUST add a property
+ called "urn:ietf:params:jmap:quota" to the capabilities object.
+
+ The value of this property is an empty object in both the JMAP
+ Session capabilities property and an account's accountCapabilities
+ property.
+
+3. Sub-types of the Quota Data Type
+
+ There are two fields within the Quota data type, which have an
+ enumerated set of possible values. These are:
+
+3.1. Scope
+
+ The Scope data type is used to represent the entities the quota
+ applies to. It is defined as a "String" with values from the
+ following set:
+
+ * account: The quota information applies to just the client's
+ account.
+
+ * domain: The quota information applies to all accounts sharing this
+ domain.
+
+ * global: The quota information applies to all accounts belonging to
+ the server.
+
+3.2. ResourceType
+
+ The ResourceType data type is used to act as a unit of measure for
+ the quota usage. It is defined as a "String" with values from the
+ following set:
+
+ * count: The quota is measured in a number of data type objects.
+ For example, a quota can have a limit of 50 "Mail" objects.
+
+ * octets: The quota is measured in size (in octets). For example, a
+ quota can have a limit of 25000 octets.
+
+4. Quota
+
+ 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.
+
+4.1. Properties of the Quota Object
+
+ The Quota object MUST contain the following fields:
+
+ * id: Id
+
+ The unique identifier for this object.
+
+ * resourceType: String
+
+ The resource type of the quota as defined in Section 3.2.
+
+ * used: UnsignedInt
+
+ The current usage of the defined quota, using the "resourceType"
+ defined as unit of measure. Computation of this value is handled
+ by the server.
+
+ * 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.
+
+ * scope: String
+
+ The "Scope" of this quota as defined in Section 3.1.
+
+ * name: String
+
+ The name of the quota. Useful for managing quotas and using
+ queries for searching.
+
+ * types: String[]
+
+ A list of all the type names as defined in the "JMAP Types Names"
+ registry (e.g., Email, Calendar, etc.) to which this quota
+ applies. This allows the quotas to be assigned to distinct or
+ shared data types.
+
+ The server MUST filter out any types for which the client did not
+ request the associated capability in the "using" section of the
+ request. Further, the server MUST NOT return Quota objects for
+ which there are no types recognized by the client.
+
+ The Quota object MAY contain the following fields:
+
+ * warnLimit: UnsignedInt|null
+
+ The warn limit set by this quota, 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 from null) and the "hardLimit".
+
+ * softLimit: UnsignedInt|null
+
+ The soft limit set by this quota, 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,
+ etc.) while still receiving incoming events (receiving emails,
+ receiving calendars events, etc.). If set, it SHOULD be higher
+ than the "warnLimit" (if present and different from null) but
+ lower than the "hardLimit".
+
+ * description: String|null
+
+ 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, and 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 or locale.
+
+ The following JMAP methods are supported.
+
+4.2. Quota/get
+
+ Standard "/get" method as described in [RFC8620], Section 5.1. The
+ _id_'s argument may be "null" to fetch all quotas of the account at
+ once, as demonstrated in Section 5.1.
+
+4.3. Quota/changes
+
+ Standard "/changes" method as described in [RFC8620], Section 5.2,
+ but with one extra argument in the response:
+
+ * updatedProperties: String[]|null
+
+ If only the "used" Quota property has changed since the old state,
+ this will be a list containing only that property. If the server
+ is unable to tell if only "used" has changed, it MUST be null.
+
+ Since "used" frequently changes, but other properties are generally
+ only changed rarely, the server can help the client optimize data
+ transfer by keeping track of changes to quota usage separate from
+ other state changes. The 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 to be changing frequently.
+
+ This method's usage is demonstrated in Section 5.2.
+
+4.4. 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 included or omitted:
+
+ * name: String
+
+ The Quota _name_ property contains the given string.
+
+ * scope: String
+
+ The Quota _scope_ property must match the given value exactly.
+
+ * resourceType: String
+
+ The Quota _resourceType_ property must match the given value
+ exactly.
+
+ * type: String
+
+ The Quota _types_ property contains the given value.
+
+ A Quota object matches the FilterCondition if, and only if, all the
+ given conditions match. If zero properties are specified, it is
+ automatically true for all objects.
+
+ The following Quota properties MUST be supported for sorting:
+
+ * name
+
+ * used
+
+4.5. Quota/queryChanges
+
+ This is a standard "/queryChanges" method as described in [RFC8620],
+ Section 5.6.
+
+5. Examples
+
+5.1. Fetching Quotas
+
+ Request fetching all quotas related to an account:
+
+ [[ "Quota/get", {
+ "accountId": "u33084183",
+ "ids": null
+ }, "0" ]]
+
+ With response:
+
+ [[ "Quota/get", {
+ "accountId": "u33084183",
+ "state": "78540",
+ "list": [{
+ "id": "2a06df0d-9865-4e74-a92f-74dcc814270e",
+ "resourceType": "count",
+ "used": 1056,
+ "warnLimit": 1600,
+ "softLimit": 1800,
+ "hardLimit": 2000,
+ "scope": "account",
+ "name": "bob@example.com",
+ "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.",
+ "types" : [ "Mail", "Calendar", "Contact" ]
+ }, {
+ "id": "3b06df0e-3761-4s74-a92f-74dcc963501x",
+ "resourceType": "octets",
+ ...
+ }, ...],
+ "notFound": []
+ }, "0" ]]
+
+5.2. Requesting Latest Quota Changes
+
+ Request fetching the changes for a specific quota:
+
+ [[ "Quota/changes", {
+ "accountId": "u33084183",
+ "sinceState": "78540",
+ "maxChanges": 20
+ }, "0" ],
+ [ "Quota/get", {
+ "accountId": "u33084183",
+ "#ids": {
+ "resultOf": "0",
+ "name": "Quota/changes",
+ "path": "/updated"
+ },
+ "#properties": {
+ "resultOf": "0",
+ "name": "Quota/changes",
+ "path": "/updatedProperties"
+ }
+ }, "1" ]]
+
+ With response:
+
+ [[ "Quota/changes", {
+ "accountId": "u33084183",
+ "oldState": "78540",
+ "newState": "78542",
+ "hasMoreChanges": false,
+ "updatedProperties": ["used"],
+ "created": [],
+ "updated": ["2a06df0d-9865-4e74-a92f-74dcc814270e"],
+ "destroyed": []
+ }, "0" ],
+ [ "Quota/get", {
+ "accountId": "u33084183",
+ "state": "10826",
+ "list": [{
+ "id": "2a06df0d-9865-4e74-a92f-74dcc814270e",
+ "used": 1246
+ }],
+ "notFound": []
+ }, "1" ]]
+
+6. Push
+
+ 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.
+
+7. IANA Considerations
+
+7.1. JMAP Capability Registration for "quota"
+
+ IANA has registered the "quota" JMAP Capability as follows:
+
+ Capability Name: urn:ietf:params:jmap:quota
+
+ Reference: RFC 9425
+
+ Intended Use: common
+
+ Change Controller: IETF
+
+ Security and Privacy Considerations: RFC 9425, Section 8
+
+7.2. JMAP Data Type Registration for "Quota"
+
+ IANA has registered the "Quota" Data Type as follows:
+
+ Type Name: Quota
+
+ Can Reference Blobs: No
+
+ Can Use for State Change: Yes
+
+ Capability: urn:ietf:params:jmap:quota
+
+ Reference: RFC 9425
+
+8. Security Considerations
+
+ All security considerations of JMAP [RFC8620] apply to this
+ specification.
+
+ Implementors should be careful to make sure the implementation of the
+ extension specified in this document does not violate the site's
+ security policy. The resource usage of other users is likely to be
+ considered confidential information and should not be divulged to
+ unauthorized persons.
+
+ As for any resource shared across users (for example, a quota with
+ the "domain" or "global" scope), a user that can consume the resource
+ can affect the resources available to the other users. For example,
+ a user could spam themselves with events and make the shared resource
+ hit the limit and unusable for others (implementors could mitigate
+ that with some rate-limiting 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, some users are part of a private
+ list belonging to the server, so they shouldn't know how many users
+ are in there. However, 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. In order to limit those attacks, quotas
+ with "domain" or "global" scope SHOULD only be visible to server
+ administrators and not to general users.
+
+9. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119,
+ DOI 10.17487/RFC2119, March 1997,
+ <https://www.rfc-editor.org/info/rfc2119>.
+
+ [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
+ 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
+ 2003, <https://www.rfc-editor.org/info/rfc3629>.
+
+ [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
+ 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
+ May 2017, <https://www.rfc-editor.org/info/rfc8174>.
+
+ [RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application
+ Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July
+ 2019, <https://www.rfc-editor.org/info/rfc8620>.
+
+ [RFC9007] Ouazana, R., Ed., "Handling Message Disposition
+ Notification with the JSON Meta Application Protocol
+ (JMAP)", RFC 9007, DOI 10.17487/RFC9007, March 2021,
+ <https://www.rfc-editor.org/info/rfc9007>.
+
+ [RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
+ Ed., "HTTP Semantics", STD 97, RFC 9110,
+ DOI 10.17487/RFC9110, June 2022,
+ <https://www.rfc-editor.org/info/rfc9110>.
+
+Acknowledgements
+
+ Thank you to Michael Bailly, who 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 an RFC after finalizing his own document: [RFC9007].
+
+ Thank you to Bron Gondwana, Neil Jenkins, Alexey Melnikov, Joris
+ Baum, and the people from the IETF JMAP working group in general, who
+ helped with extensive discussions, reviews, and feedback.
+
+ Thank you to the people in the IETF organization, who took the time
+ to read, understand, comment, and give great feedback in the last
+ rounds.
+
+Author's Address
+
+ René Cordier (editor)
+ Linagora Vietnam
+ 5 Dien Bien Phu
+ Hanoi
+ 10000
+ Vietnam
+ Email: rcordier@linagora.com
+ URI: https://linagora.vn