draft-ietf-jmap-websocket-03.txt   draft-ietf-jmap-websocket-04.txt 
JMAP K. Murchison JMAP K. Murchison
Internet-Draft Fastmail Internet-Draft Fastmail
Intended status: Standards Track July 22, 2019 Intended status: Standards Track November 17, 2019
Expires: January 23, 2020 Expires: May 20, 2020
A JSON Meta Application Protocol (JMAP) Subprotocol for WebSocket A JSON Meta Application Protocol (JMAP) Subprotocol for WebSocket
draft-ietf-jmap-websocket-03 draft-ietf-jmap-websocket-04
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.
Status of This Memo Status of This Memo
skipping to change at page 1, line 33 skipping to change at page 1, line 33
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 January 23, 2020. This Internet-Draft will expire on May 20, 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 25 skipping to change at page 2, line 25
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 . . . . . . . . . . . . . . . . . . . . . . . . 7 4.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 7
5. Security Considerations . . . . . . . . . . . . . . . . . . . 11 5. Security Considerations . . . . . . . . . . . . . . . . . . . 11
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
6.1. Registration of the WebSocket JMAP Subprotocol . . . . . 11 6.1. Registration of the WebSocket JMAP Subprotocol . . . . . 11
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 11
8.1. Normative References . . . . . . . . . . . . . . . . . . 11 8.1. Normative References . . . . . . . . . . . . . . . . . . 11
8.2. Informative References . . . . . . . . . . . . . . . . . 12 8.2. Informative References . . . . . . . . . . . . . . . . . 12
8.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Appendix A. Change History (To be removed by RFC Editor before Appendix A. Change History (To be removed by RFC Editor before
publication) . . . . . . . . . . . . . . . . . . . . 12 publication) . . . . . . . . . . . . . . . . . . . . 12
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13
1. Introduction 1. Introduction
JMAP [RFC8620] over HTTP [RFC7235] requires that every JMAP API JMAP [RFC8620] over HTTP [RFC7235] requires that every JMAP API
request be authenticated. Depending on the type of authentication request be authenticated. Depending on the type of authentication
used by the JMAP client and the configuration of the JMAP server, used by the JMAP client and the configuration of the JMAP server,
authentication could be an expensive operation both in time and authentication could be an expensive operation both in time and
skipping to change at page 3, line 9 skipping to change at page 3, line 9
Furthermore, the WebSocket binding for JMAP can optionally compress Furthermore, the WebSocket binding for JMAP can optionally compress
[RFC7692] both JMAP API requests and responses. Although compression [RFC7692] both JMAP API requests and responses. Although compression
of HTTP responses is ubiquitous, compression of HTTP requests has of HTTP responses is ubiquitous, compression of HTTP requests has
very low, if any deployment, and therefore isn't a viable option for very low, if any deployment, and therefore isn't a viable option for
JMAP API requests over HTTP. JMAP API requests over HTTP.
2. Conventions Used in This Document 2. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in
14 [1] [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
The same terminology is used in this document as in the core JMAP The same terminology is used in this document as in the core JMAP
specification. specification.
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 [RFC8620]). Servers supporting this Session object (see Section 2 of [RFC8620]). Servers supporting this
specification MUST add a property named specification MUST add a property named
skipping to change at page 5, line 25 skipping to change at page 5, line 25
requests over the WebSocket. 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:
o @type: "String" o @type: "String"
This MUST be the string "Response". This MUST be the string "Response".
o requestId: "String" (optional; only returned if given in the o requestId: "String" (optional; MUST be returned if given in the
request) request)
The client-specified identifier in the corresponding request. The client-specified identifier in the corresponding request.
4.2.3. JMAP Request-level Errors 4.2.3. JMAP Request-level Errors
This specification adds two extra arguments to the Problem Details This specification adds two extra arguments to the Problem Details
object: object:
o @type: "String" o @type: "String"
This MUST be the string "RequestError". This MUST be the string "RequestError".
o requestId: "String" (optional; only returned if given in the o requestId: "String" (optional; MUST be returned if given in the
request) request)
The client-specified identifier in the corresponding request. The client-specified identifier in the corresponding 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 "supportsWebSocketPush" property with a WebSocket will advertise a "supportsWebSocketPush" property with a
value of true in the server capabilities object. value of true in the server capabilities object.
skipping to change at page 7, line 14 skipping to change at page 7, line 14
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 "webSocketUrl" has been advertised The examples assume that the JMAP "webSocketUrl" has been advertised
in the JMAP Session object as "/jmap/ws/". 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 for WebSocket JMAP connection via HTTP/1.1 with push notifications for
mail [I-D.ietf-jmap-mail] enabled: mail [RFC8621] enabled:
[[ From Client ]] [[ From Server ]] [[ From Client ]] [[ From Server ]]
GET /jmap/ws/ 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==
skipping to change at page 12, line 15 skipping to change at page 12, line 15
[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>.
[RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application [RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application
Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July
2019, <https://www.rfc-editor.org/info/rfc8620>. 2019, <https://www.rfc-editor.org/info/rfc8620>.
8.2. Informative References 8.2. Informative References
[I-D.ietf-jmap-mail]
Jenkins, N. and C. Newman, "JMAP (JSON Meta Application
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 [RFC8621] Jenkins, N. and C. Newman, "The JSON Meta Application
Protocol (JMAP) for Mail", RFC 8621, DOI 10.17487/RFC8621,
[1] https://tools.ietf.org/html/bcp14 August 2019, <https://www.rfc-editor.org/info/rfc8621>.
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-03:
o Updated JMAP Mail reference to RFC 8621.
o Specified that requestId MUST be present in a response if given in
the request.
Changes since ietf-02: Changes since ietf-02:
o Updated JMAP Core reference to RFC 8620. o Updated JMAP Core reference to RFC 8620.
o Added 'WebSocketPushDisable' object. o Added 'WebSocketPushDisable' object.
o Editorial and formatting changes. o Editorial and formatting changes.
Changes since ietf-01: Changes since ietf-01:
 End of changes. 11 change blocks. 
18 lines changed or deleted 19 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/