JMAP for Quotas

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 1 April 2023.¶

Copyright Notice

Copyright (c) 2022 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

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.¶

2. 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", {
  "accountId": "u33084183",
  "ids": null
}, "0" ]]

[[ "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" ]]

[[ "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" ]]

[[ "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" ]]

3. 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).¶

4. IANA Considerations

Author's Address