This is an automated email from the ASF dual-hosted git repository. rcordier pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/james-project.git
commit c297b6e7003c87a5fd3a35879dcde62f2e221398 Author: Rene Cordier <[email protected]> AuthorDate: Tue Jul 28 16:57:41 2020 +0700 JAMES-3099 Annotate JMAP RFC-8620 core specifications --- .../jmap-rfc-8621/doc/specs/spec/jmap/api.mdown | 26 ++++++++++++++ .../jmap-rfc-8621/doc/specs/spec/jmap/binary.mdown | 4 +++ .../jmap-rfc-8621/doc/specs/spec/jmap/intro.mdown | 8 +++++ .../doc/specs/spec/jmap/session.mdown | 40 ++++++++++++++++++++++ 4 files changed, 78 insertions(+) diff --git a/server/protocols/jmap-rfc-8621/doc/specs/spec/jmap/api.mdown b/server/protocols/jmap-rfc-8621/doc/specs/spec/jmap/api.mdown index 4a69f90..b902cc1 100644 --- a/server/protocols/jmap-rfc-8621/doc/specs/spec/jmap/api.mdown +++ b/server/protocols/jmap-rfc-8621/doc/specs/spec/jmap/api.mdown @@ -10,6 +10,10 @@ The request MUST be of type `application/json` and consist of a single JSON-enco ## The Invocation Data Type +<aside class="notice"> + Implemented +</aside> + Method calls and responses are represented by the **Invocation** data type. This is a tuple, represented as a JSON array containing three elements: 1. A `String` **name** of the method to call or of the response. @@ -20,6 +24,10 @@ Method calls and responses are represented by the **Invocation** data type. This ## The Request Object +<aside class="notice"> + Implemented +</aside> + A **Request** object has the following properties: - **using**: `String[]` @@ -59,6 +67,10 @@ Future specifications MAY add further properties to the Request object to extend ## The Response Object +<aside class="notice"> + Implemented +</aside> + A **Response** object has the following properties: - **methodResponses**: `Invocation[]` @@ -70,6 +82,9 @@ A **Response** object has the following properties: additional ones added for newly created records. - **sessionState**: `String` The current value of the "state" string on the Session object, as described in Section 2. Clients may use this to detect if this object has changed and needs to be refetched. + <aside class="warning"> + Not implemented + </aside> Unless otherwise specified, if the method call completed successfully, its response name is the same as the method name in the request. @@ -113,6 +128,10 @@ Finally, methods that make changes to the server state often act upon a number o ### Request-Level Errors +<aside class="notice"> + Implemented +</aside> + When an HTTP error response is returned to the client, the server SHOULD return a JSON "problem details" object as the response body, as per [@!RFC7807]. @@ -126,6 +145,9 @@ The following problem types are defined: - `urn:ietf:params:jmap:error:notRequest` The request parsed as JSON but did not match the type signature of the Request object. - `urn:ietf:params:jmap:error:limit` + <aside class="warning"> + Not implemented + </aside> The request was not processed as it would have exceeded one of the **request** limits defined on the capability object, such as maxSizeRequest, maxCallsInRequest, or maxConcurrentRequests. A "limit" property MUST also be @@ -397,6 +419,10 @@ Method calls within a single request MUST be executed in order. However, method # The Core/echo Method +<aside class="notice"> + Implemented +</aside> + The *Core/echo* method returns exactly the same arguments as it is given. It is useful for testing if you have a valid authenticated connection to a JMAP API endpoint. ## Example diff --git a/server/protocols/jmap-rfc-8621/doc/specs/spec/jmap/binary.mdown b/server/protocols/jmap-rfc-8621/doc/specs/spec/jmap/binary.mdown index 9574f08..fdbd130 100644 --- a/server/protocols/jmap-rfc-8621/doc/specs/spec/jmap/binary.mdown +++ b/server/protocols/jmap-rfc-8621/doc/specs/spec/jmap/binary.mdown @@ -1,5 +1,9 @@ # Binary Data +<aside class="warning"> + Not implemented yet +</aside> + Binary data is referenced by a *blobId* in JMAP and uploaded/downloaded separately to the core API. The blobId solely represents the raw bytes of data, not any associated metadata such as a file name or content type. Such metadata is stored alongside the blobId in the object referencing it. The data represented by a blobId is immutable. Any blobId that exists within an account may be used when creating/updating another object in that account. For example, an Email type may have a blobId that represents the object in Internet Message Format [@!RFC5322]. A client could create a new Email object with an attachment and use this blobId, in effect attaching the old message to the new one. Similarly, it could attach any existing attachment of an old message without having to download and upload it again. diff --git a/server/protocols/jmap-rfc-8621/doc/specs/spec/jmap/intro.mdown b/server/protocols/jmap-rfc-8621/doc/specs/spec/jmap/intro.mdown index 2ba63a8..8efde9c 100644 --- a/server/protocols/jmap-rfc-8621/doc/specs/spec/jmap/intro.mdown +++ b/server/protocols/jmap-rfc-8621/doc/specs/spec/jmap/intro.mdown @@ -45,6 +45,10 @@ signature. These have the following meanings: ## The Id Data Type +<aside class="notice"> + Implemented +</aside> + All record ids are assigned by the server and are immutable. Where `Id` is given as a data type, it means a `String` of at least 1 and a maximum of 255 octets in size, and it MUST only contain characters from the "URL and Filename Safe" base64 alphabet, as defined in Section 5 of [@!RFC4648], excluding the pad character (`=`). This means the allowed characters are the ASCII alphanumeric characters (`A-Za-z0-9`), hyphen (`-`), and underscore (`_`). @@ -67,6 +71,10 @@ alphabetical character. ## The Int and UnsignedInt Data Types +<aside class="notice"> + Implemented +</aside> + Where `Int` is given as a data type, it means an integer in the range -2^53+1 <= value <= 2^53-1, the safe range for integers stored in a floating-point double, represented as a JSON `Number`. Where `UnsignedInt` is given as a data type, it means an `Int` where the value MUST be in the range 0 <= value <= 2^53-1. diff --git a/server/protocols/jmap-rfc-8621/doc/specs/spec/jmap/session.mdown b/server/protocols/jmap-rfc-8621/doc/specs/spec/jmap/session.mdown index d813e0d..1ff1ba5 100644 --- a/server/protocols/jmap-rfc-8621/doc/specs/spec/jmap/session.mdown +++ b/server/protocols/jmap-rfc-8621/doc/specs/spec/jmap/session.mdown @@ -1,5 +1,9 @@ # The JMAP Session Resource +<aside class="notice"> + Implemented +</aside> + You need two things to connect to a JMAP server: 1. The URL for the JMAP Session resource. This may be requested directly from @@ -10,27 +14,54 @@ You need two things to connect to a JMAP server: A successful authenticated GET request to the JMAP Session resource MUST return a JSON-encoded **Session** object, giving details about the data and capabilities the server can provide to the client given those credentials. It has the following properties: - **capabilities**: `String[Object]` +<aside class="notice"> + Implemented +</aside> An object specifying the capabilities of this server. Each key is a URI for a capability supported by the server. The value for each of these keys is an object with further information about the server's capabilities in relation to that capability. The client MUST ignore any properties it does not understand. The capabilities object MUST include a property called `urn:ietf:params:jmap:core`. The value of this property is an object that MUST contain the following information on server capabilities (suggested minimum values for limits are supplied that allow clients to make efficient use of the network): + <aside class="notice"> + Implemented + </aside> - **maxSizeUpload**: `UnsignedInt` + <aside class="warning"> + Not enforced yet + </aside> The maximum file size, in octets, that the server will accept for a single file upload (for any purpose). Suggested minimum: 50,000,000. - **maxConcurrentUpload**: `UnsignedInt` + <aside class="warning"> + Not enforced yet + </aside> The maximum number of concurrent requests the server will accept to the upload endpoint. Suggested minimum: 4. - **maxSizeRequest**: `UnsignedInt` + <aside class="warning"> + Not enforced yet + </aside> The maximum size, in octets, that the server will accept for a single request to the API endpoint. Suggested minimum: 10,000,000. - **maxConcurrentRequests**: `UnsignedInt` + <aside class="warning"> + Not enforced yet + </aside> The maximum number of concurrent requests the server will accept to the API endpoint. Suggested minimum: 4. - **maxCallsInRequest**: `UnsignedInt` + <aside class="warning"> + Not enforced yet + </aside> The maximum number of method calls the server will accept in a single request to the API endpoint. Suggested minimum: 16. - **maxObjectsInGet**: `UnsignedInt` + <aside class="warning"> + Not enforced yet + </aside> The maximum number of objects that the client may request in a single `/get` type method call. Suggested minimum: 500. - **maxObjectsInSet**: `UnsignedInt` + <aside class="warning"> + Not enforced yet + </aside> The maximum number of objects the client may send to create, update, or destroy in a single `/set` type method call. This is the combined total, e.g., if the maximum is 10, you could not create 7 objects and destroy 6, as this would be 13 actions, which exceeds the limit. Suggested minimum: 500. - **collationAlgorithms**: `String[]` A list of identifiers for algorithms registered in the collation registry, as defined in [@!RFC4790], that the server supports for sorting when querying records. @@ -40,6 +71,9 @@ A successful authenticated GET request to the JMAP Session resource MUST return Servers MAY advertise vendor-specific JMAP extensions, as described in Section 1.8. To avoid conflict, an identifier for a vendor-specific extension MUST be a URL with a domain owned by the vendor. Clients MUST opt in to any capability it wishes to use (see Section 3.3). - **accounts**: `Id[Account]` +<aside class="notice"> + Implemented +</aside> A map of an **account id** to an Account object for each account (see Section 1.6.2) the user has access to. An **Account** object has the following properties: - **name**: `String` @@ -74,8 +108,14 @@ A successful authenticated GET request to the JMAP Session resource MUST return Errors", Section 3.6.2). - **primaryAccounts**: `String[Id]` +<aside class="notice"> + Implemented +</aside> A map of capability URIs (as found in *accountCapabilities*) to the account id that is considered to be the user's main or default account for data pertaining to that capability. If no account being returned belongs to the user, or in any other way there is no appropriate way to determine a default account, there MAY be no entry for a particular URI, even though that capability is supported by the server (and in the capabilities object). `urn:ietf:params:jmap:core` SHOULD NOT be present. - **username**: `String` +<aside class="notice"> + Implemented +</aside> The username associated with the given credentials, or the empty string if none. - **apiUrl**: `String` The URL to use for JMAP API requests. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
