You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@james.apache.org by bt...@apache.org on 2022/10/17 02:55:21 UTC
[james-project] 02/04: JAMES-3830 Add rfc jmap quotas doc from the IETF spec
This is an automated email from the ASF dual-hosted git repository.
btellier pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git
commit 90867f5c5294efef34d0d8758a17c4c5d071aff3
Author: Rene Cordier <rc...@linagora.com>
AuthorDate: Mon Oct 10 16:16:41 2022 +0700
JAMES-3830 Add rfc jmap quotas doc from the IETF spec
---
.../jmap-rfc-8621/doc/specs/rfc/src/quotas.mdown | 46 ++++++
.../doc/specs/spec/quotas/ianaconsiderations.mdown | 15 ++
.../doc/specs/spec/quotas/intro.mdown | 68 +++++++++
.../doc/specs/spec/quotas/quota.mdown | 157 +++++++++++++++++++++
.../specs/spec/quotas/securityconsiderations.mdown | 12 ++
5 files changed, 298 insertions(+)
diff --git a/server/protocols/jmap-rfc-8621/doc/specs/rfc/src/quotas.mdown b/server/protocols/jmap-rfc-8621/doc/specs/rfc/src/quotas.mdown
new file mode 100644
index 0000000000..b81822e358
--- /dev/null
+++ b/server/protocols/jmap-rfc-8621/doc/specs/rfc/src/quotas.mdown
@@ -0,0 +1,46 @@
+%%%
+ title = "JMAP for Quotas"
+ abbrev = "JMAP Quotas"
+ category = "std"
+ docName = "draft-ietf-jmap-quotas-06"
+ ipr= "trust200902"
+ area = "Applications"
+ workgroup = "JMAP"
+ keyword = ["JMAP", "JSON", "email", "quotas"]
+
+ date = 2022-09-28T00:00:00Z
+
+ [seriesInfo]
+ name="Internet-Draft"
+ value="draft-ietf-jmap-quotas-06"
+ stream="IETF"
+ status="standard"
+
+ [[author]]
+ initials="R.C."
+ surname="Cordier"
+ fullname="René Cordier"
+ role="editor"
+ organization = "Linagora Vietnam"
+ [author.address]
+ email = "rcordier@linagora.com"
+ uri = "https://linagora.vn"
+ [author.address.postal]
+ street = "5 Dien Bien Phu"
+ city = "Hanoi"
+ code = "10000"
+ country = "Vietnam"
+%%%
+
+.# Abstract
+
+This document specifies a data model for handling quotas on accounts with a server using JMAP.
+
+{mainmatter}
+
+{{spec/quotas/intro.mdown}}
+{{spec/quotas/quota.mdown}}
+{{spec/quotas/securityconsiderations.mdown}}
+{{spec/quotas/ianaconsiderations.mdown}}
+
+{backmatter}
diff --git a/server/protocols/jmap-rfc-8621/doc/specs/spec/quotas/ianaconsiderations.mdown b/server/protocols/jmap-rfc-8621/doc/specs/spec/quotas/ianaconsiderations.mdown
new file mode 100644
index 0000000000..56da643610
--- /dev/null
+++ b/server/protocols/jmap-rfc-8621/doc/specs/spec/quotas/ianaconsiderations.mdown
@@ -0,0 +1,15 @@
+# IANA Considerations
+
+## JMAP Capability Registration for "quota"
+
+IANA will register the "quota" JMAP Capability as follows:
+
+Capability Name: `urn:ietf:params:jmap:quota`
+
+Specification document: this document
+
+Intended use: common
+
+Change Controller: IETF
+
+Security and privacy considerations: this document, section 4.
\ No newline at end of file
diff --git a/server/protocols/jmap-rfc-8621/doc/specs/spec/quotas/intro.mdown b/server/protocols/jmap-rfc-8621/doc/specs/spec/quotas/intro.mdown
new file mode 100644
index 0000000000..f2f15598e2
--- /dev/null
+++ b/server/protocols/jmap-rfc-8621/doc/specs/spec/quotas/intro.mdown
@@ -0,0 +1,68 @@
+# Introduction
+
+JMAP ([@!RFC8620] – JSON Meta Application Protocol) is a generic protocol for synchronising data, such as mails,
+calendars or contacts, between a client and a server. It is optimised 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 you to read and explain quota information.
+
+This specification does not address quota administration, which should be handled by other means.
+
+## 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.
+
+Servers MUST support all properties specified for the new data types defined in this document.
+
+## Terminology
+
+The same terminology is used in this document as in the core JMAP specification.
+
+The term Quota (with that specific capitalization) is used to refer to the data type defined in this document and instance of that data type.
+
+## 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.
+
+### 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.
+
+## Data types
+
+In addition to the standard JSON data types, a couple of additional data types are common to the definition of Quota objects and properties.
+
+### Scope
+
+The **Scope** is a `String` from an enumeration defined list of values, handled by the server.
+
+It explains the entities this value applies to. Values for the **Scope** are:
+
+* `account`: Applies for this account
+* `domain`: All accounts of this domain share this part of the quota
+* `global`: All accounts of this server share this part of the quota
+
+### ResourceType
+
+The **ResourceType** is a `String` from an enumeration defined list of values, handled by the server.
+
+A resource type is like an unit of measure for the quota usage. Values for the **ResourceType** are:
+
+* `count`: The quota is measured in 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`.
+
+## 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.
diff --git a/server/protocols/jmap-rfc-8621/doc/specs/spec/quotas/quota.mdown b/server/protocols/jmap-rfc-8621/doc/specs/spec/quotas/quota.mdown
new file mode 100644
index 0000000000..122de14c7c
--- /dev/null
+++ b/server/protocols/jmap-rfc-8621/doc/specs/spec/quotas/quota.mdown
@@ -0,0 +1,157 @@
+# Quota
+
+The quota is an object that displays the limit set to an account usage as well as the current usage in regard to that limit.
+
+The quota object MUST contain the following fields:
+
+* **id**: `Id` The unique identifier for this object. It should respect the JMAP ID datatype defined in section 1.2 of [@!RFC8620]
+
+* **resourceType**: `ResourceType` The resource type of the quota.
+
+* **used**: `UnsignedInt` The current usage of the defined quota. Computation of this value is handled by the server.
+
+* **limit**: `UnsignedInt` The hard limit set by this quota. Objects in scope may not be created or updated if we reach this limit. It should be higher than the `warnLimit` and the `softLimit`.
+
+* **scope**: `Scope` The `Scope` of this quota.
+
+* **name**: `String` The name of the quota object. Useful for managing quotas and use queries for searching.
+
+* **datatypes**: `String[]` A list of all the data types values that are applying to this quota. This allows to assign
+quotas to separated or shared data types. This MAY include data types the client does not recognise. Clients MUST
+ignore any unknown data type in the list.
+
+The quota object MAY contain the following field:
+
+* **warnLimit**: `UnsignedInt|null` The warn limit set by this quota object. 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` and the `limit`.
+
+* **softLimit**: `UnsignedInt|null` The soft limit set by this quota object. It can be used to still allow some operations,
+but refusing 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` but lower than the `limit`.
+
+* **description**: `String|null` Arbitrary free, human readable, description of this quota. Might be used to explain
+where the limit comes from and explain the entities and data types this quota applies to.
+
+## Quota/get
+
+Standard “/get” method as described in [@!RFC8620] section 5.1. The ids argument may be `null` to fetch all at once.
+
+## Quota/changes
+
+Standard “/changes” method as described in [@!RFC8620] section 5.2 but with one extra argument to the response:
+
+* **updatedProperties**: `String[]|null` If only the “used” Quota properties has changed since the old state, this
+will be the list of properties that may have changed. If the server is unable to tell if only "used" has changed, it
+MUST just be null.
+
+Since "used" frequently changes but other properties are generally only changed rarely, the server can help the client
+optimise 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 changing frequently.
+
+## 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:
+
+* **name**: `String` The Quota _name_ property contains the given string.
+* **scopes**: `Scope[]` The Quota _scope_ property must be in this list to match the condition.
+* **resourceTypes**: `ResourceType[]` The Quota _resourceType_ property must be in this list to match the condition.
+* **datatypes**: `String[]` The Quota _datatypes_ property must contain the elements in this list to match the condition.
+
+A Quota object matches the FilterCondition if and only if all of 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**
+
+## Quota/queryChanges
+
+This is a standard “/queryChanges” method as described in [@!RFC8620], Section 5.6.
+
+## Examples
+
+### 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,
+ "limit": 2000,
+ "scope": "account",
+ "name": "bob@example.com",
+ "description": "Personal account usage",
+ "datatypes" : [ "Mail", "Calendar", "Contact" ]
+ }, {
+ "id": "3b06df0e-3761-4s74-a92f-74dcc963501x",
+ "resourceType": "octets",
+ ...
+ }, ...],
+ "notFound": []
+ }, "0" ]]
+
+### Requesting latest quota changes
+
+Request fetching the changes for a specific quota:
+
+ [[ "Quota/changes", {
+ "accountId": "u33084183",
+ "sinceState": "10824",
+ "maxChanges": 20,
+ "updatedProperties": ["used"]
+ }, "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": "10824",
+ "newState": "10826",
+ "hasMoreChanges": false,
+ "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" ]]
diff --git a/server/protocols/jmap-rfc-8621/doc/specs/spec/quotas/securityconsiderations.mdown b/server/protocols/jmap-rfc-8621/doc/specs/spec/quotas/securityconsiderations.mdown
new file mode 100644
index 0000000000..e9830d4eba
--- /dev/null
+++ b/server/protocols/jmap-rfc-8621/doc/specs/spec/quotas/securityconsiderations.mdown
@@ -0,0 +1,12 @@
+# Security considerations
+
+All security considerations of JMAP ([@!RFC8620]) apply to this specification.
+
+Implementors should be careful to make sure the implementation of that extension 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 himself 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).
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org