< draft-ietf-jmap-websocket-01.txt   draft-ietf-jmap-websocket-02.txt >
JMAP K. Murchison JMAP K. Murchison
Internet-Draft FastMail Internet-Draft Fastmail
Intended status: Standards Track March 10, 2019 Intended status: Standards Track July 5, 2019
Expires: September 11, 2019 Expires: January 6, 2020
A JSON Meta Application Protocol (JMAP) Subprotocol for WebSocket A JSON Meta Application Protocol (JMAP) Subprotocol for WebSocket
draft-ietf-jmap-websocket-01 draft-ietf-jmap-websocket-02
Abstract Abstract
This document defines a binding for the JSON Meta Application This document defines a binding for the JSON Meta Application
Protocol (JMAP) over a WebSocket transport layer. The WebSocket Protocol (JMAP) over a WebSocket transport layer. The WebSocket
binding for JMAP provides higher performance than the current HTTP binding for JMAP provides higher performance than the current HTTP
binding for JMAP. binding for JMAP.
Open Issues
o Should push over WebSocket make use of the EventSource Last-Event-
ID request header field (or a similar facility; e.g., as an extra
query parameter)? And if so, where would the server state token
be returned to the user? As a new property in the StateChange
object?
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 11, 2019. This Internet-Draft will expire on January 6, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 20 skipping to change at page 2, line 13
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Conventions Used in This Document . . . . . . . . . . . . . . 3 2. Conventions Used in This Document . . . . . . . . . . . . . . 3
3. Discovering Support for JMAP over WebSocket . . . . . . . . . 3 3. Discovering Support for JMAP over WebSocket . . . . . . . . . 3
4. JMAP Subprotocol . . . . . . . . . . . . . . . . . . . . . . 3 4. JMAP Subprotocol . . . . . . . . . . . . . . . . . . . . . . 3
4.1. Handshake . . . . . . . . . . . . . . . . . . . . . . . . 4 4.1. Handshake . . . . . . . . . . . . . . . . . . . . . . . . 4
4.2. WebSocket Messages . . . . . . . . . . . . . . . . . . . 4 4.2. WebSocket Messages . . . . . . . . . . . . . . . . . . . 4
4.2.1. JMAP Requests . . . . . . . . . . . . . . . . . . . . 5 4.2.1. JMAP Requests . . . . . . . . . . . . . . . . . . . . 4
4.2.2. JMAP Responses . . . . . . . . . . . . . . . . . . . 5 4.2.2. JMAP Responses . . . . . . . . . . . . . . . . . . . 5
4.2.3. JMAP Request-level Errors . . . . . . . . . . . . . . 5 4.2.3. JMAP Request-level Errors . . . . . . . . . . . . . . 5
4.2.4. JMAP Push Notifications . . . . . . . . . . . . . . . 5 4.2.4. JMAP Push Notifications . . . . . . . . . . . . . . . 5
4.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 6 4.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 6
5. Security Considerations . . . . . . . . . . . . . . . . . . . 10 5. Security Considerations . . . . . . . . . . . . . . . . . . . 10
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
6.1. Registration of the WebSocket JMAP Subprotocol . . . . . 10 6.1. Registration of the WebSocket JMAP Subprotocol . . . . . 10
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 10 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 10
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 10
8.1. Normative References . . . . . . . . . . . . . . . . . . 10 8.1. Normative References . . . . . . . . . . . . . . . . . . 10
skipping to change at page 3, line 31 skipping to change at page 3, line 25
3. Discovering Support for JMAP over WebSocket 3. Discovering Support for JMAP over WebSocket
The JMAP capabilities object is returned as part of the standard JMAP The JMAP capabilities object is returned as part of the standard JMAP
Session object (see Section 2 of [I-D.ietf-jmap-core]). Servers Session object (see Section 2 of [I-D.ietf-jmap-core]). Servers
supporting this specification MUST add a property named supporting this specification MUST add a property named
"urn:ietf:params:jmap:websocket" to the capabilities object. The "urn:ietf:params:jmap:websocket" to the capabilities object. The
value of this property is an object which MUST contain the following value of this property is an object which MUST contain the following
information on server capabilities: information on server capabilities:
wsUrl: "String" The URL to use for initiating a JMAP over WebSocket webSocketUrl: "String" The URL to use for initiating a JMAP over
handshake. WebSocket handshake.
Server support for push notifications over the WebSocket is OPTIONAL. supportsWebSocketPush: "Boolean" This is "true" if the server
A server advertises that it supports push notifications by returning supports push notifications over the WebSocket, as described in
the "wsURL" property in URI Template [RFC6570] (level 3) format Section 4.2.4.
containing the variable "{?types}". The use of this variable is
described in Section 4.2.4.
Example: Example:
"urn:ietf:params:jmap:websocket": { "urn:ietf:params:jmap:websocket": {
"wsUrl": "/jmap/ws/{?types}" "webSocketUrl": "/jmap/ws/",
"supportsWebSocketPush": true
} }
4. JMAP Subprotocol 4. JMAP Subprotocol
The term WebSocket subprotocol refers to an application-level The term WebSocket subprotocol refers to an application-level
protocol layered on top of a WebSocket connection. This document protocol layered on top of a WebSocket connection. This document
specifies the WebSocket JMAP subprotocol for carrying JMAP API specifies the WebSocket JMAP subprotocol for carrying JMAP API
requests, responses, and optional push notifications through a requests, responses, and optional push notifications through a
WebSocket connection. Binary data MUST NOT be uploaded or downloaded WebSocket connection. Binary data MUST NOT be uploaded or downloaded
through a WebSocket JMAP connection. Binary data is handled per through a WebSocket JMAP connection. Binary data is handled per
skipping to change at page 4, line 16 skipping to change at page 4, line 13
stream. stream.
4.1. Handshake 4.1. Handshake
The JMAP WebSocket client and JMAP WebSocket server negotiate the use The JMAP WebSocket client and JMAP WebSocket server negotiate the use
of the WebSocket JMAP subprotocol during the WebSocket handshake, of the WebSocket JMAP subprotocol during the WebSocket handshake,
either via a HTTP/1.1 Upgrade request (see Section 1.3 of [RFC6455]) either via a HTTP/1.1 Upgrade request (see Section 1.3 of [RFC6455])
or a HTTP/2 Extended CONNECT request (see Section 5 of [RFC8441]). or a HTTP/2 Extended CONNECT request (see Section 5 of [RFC8441]).
Regardless of the method used for the WebSocket handshake, the client Regardless of the method used for the WebSocket handshake, the client
MUST make an authenticated [RFC7235] HTTP request on the JMAP "wsURL" MUST make an authenticated [RFC7235] HTTP request on the JMAP
(Section 3), and the client MUST include the value 'jmap' in the list "webSocketUrl" (Section 3), and the client MUST include the value
of protocols for the 'Sec-WebSocket-Protocol' header field. The 'jmap' in the list of protocols for the 'Sec-WebSocket-Protocol'
reply from the server MUST also contain 'jmap' in its corresponding header field. The reply from the server MUST also contain 'jmap' in
'Sec-WebSocket-Protocol' header field in order for a JMAP subprotocol its corresponding 'Sec-WebSocket-Protocol' header field in order for
connection to be established. a JMAP subprotocol connection to be established.
If a client receives a handshake response that does not include If a client receives a handshake response that does not include
'jmap' in the 'Sec-WebSocket-Protocol' header, then a JMAP 'jmap' in the 'Sec-WebSocket-Protocol' header, then a JMAP
subprotocol WebSocket connection was not established and the client subprotocol WebSocket connection was not established and the client
MUST close the WebSocket connection. MUST close the WebSocket connection.
Once the handshake has successfully completed, the WebSocket Once the handshake has successfully completed, the WebSocket
connection is established and can be used for JMAP API requests, connection is established and can be used for JMAP API requests,
responses, and optional push notifications. Other message types MUST responses, and optional push notifications. Other message types MUST
NOT be transmitted over this connection. NOT be transmitted over this connection.
The credentials used for authenticating the HTTP request to initiate The credentials used for authenticating the HTTP request to initiate
the handshake remain in effect for the duration of the WebSocket the handshake remain in effect for the duration of the WebSocket
connection. connection.
4.2. WebSocket Messages 4.2. WebSocket Messages
Data frame messages in the JMAP subprotocol MUST be of the text type Data frame messages in the JMAP subprotocol MUST be of the text type
and contain UTF-8 encoded data. The messages MUST be in the form of and contain UTF-8 encoded data. The messages MUST be in the form of
a single JMAP Request object (see Section 3.2 of a single JMAP Request object (see Section 3.2 of
[I-D.ietf-jmap-core]) when sent from the client to the server, and in [I-D.ietf-jmap-core]) or JMAP WebSocketPushEnable object (see
the form of a single JMAP Response object, JSON Problem Details Section 4.2.4) when sent from the client to the server, and in the
object, or JMAP StateChange object (see Sections 3.3, 3.5.1, and 7.1 form of a single JMAP Response object, JSON Problem Details object,
or JMAP StateChange object (see Sections 3.3, 3.5.1, and 7.1
respectively of [I-D.ietf-jmap-core]) when sent from the server to respectively of [I-D.ietf-jmap-core]) when sent from the server to
the client. the client.
4.2.1. JMAP Requests 4.2.1. JMAP Requests
JMAP over WebSocket allows out of order processing of requests, This specification adds two extra arguments to the Request object:
thereby requiring a mechanism for the client to correlate requests
and responses. To this end, this specification adds one extra @type: "String" This MUST be the string "Request".
argument to the request object:
id: "String" (default: ) A client-specified identifier for the id: "String" (default: ) A client-specified identifier for the
request. request.
JMAP over WebSocket allows the server to process requests out of
order. The client-specified identifier is used as a mechanism for
the client to correlate requests and responses.
Additionally, the "maxConcurrentRequests" field in the "capabilities" Additionally, the "maxConcurrentRequests" field in the "capabilities"
object (see Section 2 of [I-D.ietf-jmap-core]) limits the number of object (see Section 2 of [I-D.ietf-jmap-core]) limits the number of
inflight requests over the WebSocket. inflight requests over the WebSocket.
4.2.2. JMAP Responses 4.2.2. JMAP Responses
This specification adds two extra arguments to the Response object: This specification adds two extra arguments to the Response object:
@type: "String" This MUST be the string "Response". @type: "String" This MUST be the string "Response".
skipping to change at page 5, line 43 skipping to change at page 5, line 40
@type: "String" This MUST be the string "RequestError". @type: "String" This MUST be the string "RequestError".
requestId: "String|null" The client-specified identifier in the requestId: "String|null" The client-specified identifier in the
corresponding request. If "null", no identifier was provided in corresponding request. If "null", no identifier was provided in
the request. the request.
4.2.4. JMAP Push Notifications 4.2.4. JMAP Push Notifications
JMAP over WebSocket servers that support push notifications on the JMAP over WebSocket servers that support push notifications on the
WebSocket will advertise a "wsURL" property in URI Template [RFC6570] WebSocket will advertise a "supportsWebSocketPush" property with a
(level 3) format containing the variable "{?types}". value of "true" in the server capabilities object.
A client enables push notifications on the server as part of the A client enables push notifications from the server by sending a
authenticated HTTP request that initiates the WebSocket handshake by WebSocketPushEnable object to the server. A WebSocketPushEnable
substituting the appropriate variables: object has the following properties:
types: This MUST be either: @type: "String" This MUST be the string "WebSocketPushEnable".
* A comma-separated list of type names, e.g. "Email,Mailbox" dataTypes: "String[]|null" A list of data type names (e.g.
[I-D.ietf-jmap-core]. The server MUST only push changes for "Mailbox", "Email") that the client is interested in. A
the types in this list. StateChange notification will only be sent if the data for one of
these types changes. Other types are omitted from the TypeState
object. If "null", changes will be pushed for all supported data
types.
* The single character: "*". Changes to all types are pushed. pushState: "String" Optional. The last "pushState" token that the
client received from the server. Upon receipt of a "pushState"
token, the server SHOULD immediately send all changes since that
state token.
All push notifications take the form of a standard StateChange object All push notifications take the form of a standard StateChange object
(see Section 7.1 of [I-D.ietf-jmap-core]). (see Section 7.1 of [I-D.ietf-jmap-core]).
This specification adds one extra argument to the StateChange object:
pushState: "String" Optional. A (preferably short) string
representing the state on the server for ALL of the data types in
the account (not just the objects returned in this call).
4.3. Examples 4.3. Examples
The following examples show WebSocket JMAP opening handshakes, a JMAP The following examples show WebSocket JMAP opening handshakes, a JMAP
Core/echo request and response, and a subsequent closing handshake. Core/echo request and response, and a subsequent closing handshake.
The examples assume that the JMAP "wsURL" has been advertised in the The examples assume that the JMAP "webSocketUrl" has been advertised
JMAP Session object as "/jmap/ws/{?types}". Note that folding of in the JMAP Session object as "/jmap/ws/". Note that folding of
header fields is for editorial purposes only. header fields is for editorial purposes only.
WebSocket JMAP connection via HTTP/1.1 with push notifications WebSocket JMAP connection via HTTP/1.1 with push notifications
enabled: enabled:
[[ From Client ]] [[ From Server ]] [[ From Client ]] [[ From Server ]]
GET /jmap/ws/?types=Email,Mailbox HTTP/1.1 GET /jmap/ws/ HTTP/1.1
Host: server.example.com Host: server.example.com
Upgrade: websocket Upgrade: websocket
Connection: Upgrade Connection: Upgrade
Authorization: Basic Zm9vOmJhcg== Authorization: Basic Zm9vOmJhcg==
Sec-WebSocket-Key: Sec-WebSocket-Key:
dGhlIHNhbXBsZSBub25jZQ== dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Protocol: jmap Sec-WebSocket-Protocol: jmap
Sec-WebSocket-Version: 13 Sec-WebSocket-Version: 13
Origin: http://www.example.com Origin: http://www.example.com
skipping to change at page 6, line 49 skipping to change at page 7, line 9
Upgrade: websocket Upgrade: websocket
Connection: Upgrade Connection: Upgrade
Sec-WebSocket-Accept: Sec-WebSocket-Accept:
s3pPLMBiTxaQ9kYGzzhZRbK+xOo= s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Protocol: jmap Sec-WebSocket-Protocol: jmap
[WebSocket connection established] [WebSocket connection established]
WS_DATA WS_DATA
{ {
"@type": "WebSocketPushEnable",
"dataTypes": [ "Mailbox", "Email" ],
"pushState": "aaa"
}
WS_DATA
{
"@type": "StateChange",
"changed": {
"a456": {
"Email": "d35ecb040aab"
}
},
"pushState": "bbb"
}
WS_DATA
{
"@type": "Request",
"id": "R1", "id": "R1",
"using": [ "urn:ietf:params:jmap:core" ], "using": [ "urn:ietf:params:jmap:core" ],
"methodCalls": [ "methodCalls": [
[ [
"Core/echo", { "Core/echo", {
"hello": true, "hello": true,
"high": 5 "high": 5
}, },
"b3ff" "b3ff"
] ]
skipping to change at page 7, line 48 skipping to change at page 8, line 28
"status": 400, "status": 400,
"detail": "detail":
"The request did not parse as I-JSON." "The request did not parse as I-JSON."
} }
WS_DATA WS_DATA
{ {
"@type": "StateChange", "@type": "StateChange",
"changed": { "changed": {
"a123": { "a123": {
"Mailbox": "0af7a512ce70", "Mailbox": "0af7a512ce70"
} }
} }
"pushState": "ccc"
} }
WS_CLOSE WS_CLOSE
WS_CLOSE WS_CLOSE
[WebSocket connection closed] [WebSocket connection closed]
WebSocket JMAP connection on a HTTP/2 stream which also negotiates WebSocket JMAP connection on a HTTP/2 stream which also negotiates
compression [RFC7692]: compression [RFC7692]:
skipping to change at page 10, line 38 skipping to change at page 10, line 38
The author would like to thank the following individuals for The author would like to thank the following individuals for
contributing their ideas and support for writing this specification: contributing their ideas and support for writing this specification:
Neil Jenkins, Robert Mueller, and Chris Newman. Neil Jenkins, Robert Mueller, and Chris Newman.
8. References 8. References
8.1. Normative References 8.1. Normative References
[I-D.ietf-jmap-core] [I-D.ietf-jmap-core]
Jenkins, N. and C. Newman, "JSON Meta Application Jenkins, N. and C. Newman, "JSON Meta Application
Protocol", draft-ietf-jmap-core-14 (work in progress), Protocol", draft-ietf-jmap-core-17 (work in progress),
January 2019. March 2019.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol",
RFC 6455, DOI 10.17487/RFC6455, December 2011, RFC 6455, DOI 10.17487/RFC6455, December 2011,
<https://www.rfc-editor.org/info/rfc6455>. <https://www.rfc-editor.org/info/rfc6455>.
[RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
and D. Orchard, "URI Template", RFC 6570,
DOI 10.17487/RFC6570, March 2012,
<https://www.rfc-editor.org/info/rfc6570>.
[RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Authentication", RFC 7235, Protocol (HTTP/1.1): Authentication", RFC 7235,
DOI 10.17487/RFC7235, June 2014, DOI 10.17487/RFC7235, June 2014,
<https://www.rfc-editor.org/info/rfc7235>. <https://www.rfc-editor.org/info/rfc7235>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8441] McManus, P., "Bootstrapping WebSockets with HTTP/2", [RFC8441] McManus, P., "Bootstrapping WebSockets with HTTP/2",
RFC 8441, DOI 10.17487/RFC8441, September 2018, RFC 8441, DOI 10.17487/RFC8441, September 2018,
<https://www.rfc-editor.org/info/rfc8441>. <https://www.rfc-editor.org/info/rfc8441>.
8.2. Informative References 8.2. Informative References
[I-D.ietf-jmap-mail] [I-D.ietf-jmap-mail]
Jenkins, N. and C. Newman, "JMAP for Mail", draft-ietf- Jenkins, N. and C. Newman, "JMAP (JSON Meta Application
jmap-mail-15 (work in progress), February 2019. Protocol) for Mail", draft-ietf-jmap-mail-16 (work in
progress), March 2019.
[RFC7692] Yoshino, T., "Compression Extensions for WebSocket", [RFC7692] Yoshino, T., "Compression Extensions for WebSocket",
RFC 7692, DOI 10.17487/RFC7692, December 2015, RFC 7692, DOI 10.17487/RFC7692, December 2015,
<https://www.rfc-editor.org/info/rfc7692>. <https://www.rfc-editor.org/info/rfc7692>.
8.3. URIs 8.3. URIs
[1] https://tools.ietf.org/html/bcp14 [1] https://tools.ietf.org/html/bcp14
Appendix A. Change History (To be removed by RFC Editor before Appendix A. Change History (To be removed by RFC Editor before
publication) publication)
Changes since ietf-01:
o Changed 'wsURL' to 'webSocketUrl' and removed push query option.
o Added 'supportsWebSocketPush' capability.
o Added '@type' argument to Request object.
o Added 'WebSocketPushEnable' object.
o Added 'pushState' argument to StateChange object.
o Updated example.
o Minor Editorial changes.
Changes since ietf-00: Changes since ietf-00:
o Added text describing advertisement of and selection of optional o Added text describing advertisement of and selection of optional
push notifications. push notifications.
o Minor Editorial changes. o Minor Editorial changes.
Changes since murchison-02: Changes since murchison-02:
o Renamed as a JMAP WG document. o Renamed as a JMAP WG document.
skipping to change at page 12, line 32 skipping to change at page 12, line 43
o Allow JSON Problem Details objects to be returned by the server o Allow JSON Problem Details objects to be returned by the server
for toplevel errors. for toplevel errors.
o Mentioned the ability to compress JMAP API requests. o Mentioned the ability to compress JMAP API requests.
o Minor Editorial changes. o Minor Editorial changes.
Author's Address Author's Address
Kenneth Murchison Kenneth Murchison
FastMail US LLC Fastmail US LLC
1429 Walnut Street - Suite 1201 1429 Walnut Street - Suite 1201
Philadelphia, PA 19102 Philadelphia, PA 19102
USA USA
Email: murch@fastmailteam.com Email: murch@fastmailteam.com
URI: http://www.fastmail.com/ URI: http://www.fastmail.com/
 End of changes. 28 change blocks. 
59 lines changed or deleted 98 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/