<?xml version="1.0" encoding="utf-8"?> version='1.0' encoding='utf-8'?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd'
[
<!ENTITY rfc2119 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml'>
<!ENTITY rfc2818 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2818.xml'>
<!ENTITY rfc5246 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5246.xml'>
<!ENTITY rfc6455 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6455.xml'>
<!ENTITY rfc6570 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6570.xml'>
<!ENTITY rfc7230 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7230.xml'>
<!ENTITY rfc7235 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7235.xml'>
<!ENTITY rfc7525 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7525.xml'>
<!ENTITY rfc7540 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7540.xml'>
<!ENTITY rfc7692 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7692.xml'>
<!ENTITY rfc8174 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml'>
<!ENTITY rfc8441 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8441.xml'>
<!ENTITY rfc8446 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8446.xml'>
<!ENTITY rfc8620 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8620.xml'>
<!ENTITY rfc8621 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8621.xml'>
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc toc="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc tocdepth="3"?>
<?rfc strict="yes"?> "rfc2629-xhtml.ent">

<rfc xmlns:xi="http://www.w3.org/2001/XInclude" category="std" ipr='trust200902'
     docName='draft-ietf-jmap-websocket-07'>
     ipr="trust200902" docName="draft-ietf-jmap-websocket-07" obsoletes=""
     updates="" submissionType="IETF" xml:lang="en" tocInclude="true"
     symRefs="true" sortRefs="true" tocDepth="3" version="3" number="8887"
     consensus="true">
  <!-- xml2rfc v2v3 conversion 2.43.0 -->
  <front>
    <title abbrev="JMAP Over over WebSocket">
      A JSON Meta Application Protocol (JMAP) Subprotocol for WebSocket
    </title>
    <seriesInfo name="RFC" value="8887"/>
    <author initials="K." surname="Murchison" fullname="Kenneth Murchison">
      <organization abbrev="Fastmail">Fastmail US LLC</organization>
      <address>
        <postal>
          <street>1429 Walnut Street - Street, Suite 1201</street>
          <city>Philadelphia</city>
          <region>PA</region>
          <code>19102</code> <country>USA</country>
          <country>United States of America</country>
        </postal>
        <email>murch@fastmailteam.com</email>
        <uri>http://www.fastmail.com/</uri>
      </address>
    </author>
    <date /> month="August" year="2020"/>
    <area>ART</area>
    <workgroup>JMAP</workgroup>
    <keyword>jmap</keyword>
    <keyword>websocket</keyword>
    <abstract>
      <t>This document defines a binding for the JSON Meta Application
      Protocol (JMAP) over a WebSocket transport layer.  The WebSocket
      binding for JMAP provides higher performance than the current
      HTTP binding for JMAP.
      </t>
    </abstract>
<!--
    <note title="Open Issues">
      <t>
        <list style="symbols">
          <t>Still need to craft some text to discuss/address
          potential security risks of using WebSocket compression.</t>
        </list>
      </t>
    </note>
-->

  </front>
  <middle>
    <section title='Introduction'> numbered="true" toc="default">
      <name>Introduction</name>
      <t><xref target='RFC8620'>JMAP</xref> target="RFC8620" format="default">JMAP</xref>
      over <xref target='RFC7235'>HTTP</xref> target="RFC7235" format="default">HTTP</xref> requires that
      every JMAP API request be authenticated.
      Depending on the type of authentication used by
      the JMAP client and the configuration of the JMAP server,
      authentication could be an expensive operation both in time and
      resources.  In such circumstances, reauthenticating for every
      JMAP API request may harm performance.</t>
      <t>The <xref target='RFC6455'>WebSocket</xref> target="RFC6455" format="default">WebSocket</xref>
      binding for JMAP eliminates this performance
      hit by authenticating just the WebSocket handshake request and
      having those credentials remain in effect for the duration of
      the WebSocket connection.  This binding supports JMAP API
      requests and responses, with optional support for push
      notifications.</t>
      <t>Furthermore, the WebSocket binding for JMAP can optionally
      <xref target='RFC7692'>compress</xref> target="RFC7692" format="default">compress</xref> both JMAP API
      requests and responses.
      Although compression of HTTP responses is ubiquitous,
      compression of HTTP requests has very low, if any deployment, any, deployment
      and therefore isn&apos;t isn't a viable option for JMAP API requests
      over HTTP.</t>
    </section>
    <!-- Intro -->

    <section title='Conventions numbered="true" toc="default">
      <name>Conventions Used in This Document'>
      <t>The Document</name>
        <t>
    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
      NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED",
      "MAY", "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>",
    "<bcp14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL
    NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>",
    "<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",
    "<bcp14>MAY</bcp14>", and "OPTIONAL" "<bcp14>OPTIONAL</bcp14>" in this document are
    to be interpreted as
    described in BCP&nbsp;14 <xref target='RFC2119' /> target="RFC2119"/> <xref target='RFC8174' /> target="RFC8174"/>
    when, and only when, they appear in all capitals, as shown
      here.</t>

      <t>The same terminology is used in this here.
        </t>
	<t>This document as uses the terminology defined in the core JMAP specification.</t>
	specification <xref target="RFC8620"/>.</t>
    </section>
    <!-- Conventions -->

    <section anchor='discovery'
             title='Discovering anchor="discovery" numbered="true" toc="default">
      <name>Discovering Support for JMAP over WebSocket'> WebSocket</name>
      <t>The JMAP capabilities object is returned as part of the
      standard JMAP Session object (see Section 2 of
      <xref target='RFC8620' />). target="RFC8620" sectionFormat="of" section="2"/>).
      Servers supporting this specification MUST <bcp14>MUST</bcp14> add a property named
      "urn:ietf:params:jmap:websocket" to the capabilities object.
      The value of this property is an object which MUST that <bcp14>MUST</bcp14> contain the
      following information on server capabilities:

      <list style='symbols'>

      </t>
      <ul spacing="normal">
	<li>
	  <t>url: "String"
        <vspace blankLines="1"/>
        The  "String"</t>
          <t>The wss-URI (see Section 3 of <xref target='RFC6455' />) target="RFC6455" sectionFormat="of"
	  section="3"/>) to use for initiating a JMAP over WebSocket JMAP-over-WebSocket
	  handshake (the "WebSocket URL endpoint" colloquially).
        </t> colloquially).</t>
        </li>
	<li>
          <t>supportsPush: "Boolean"
        <vspace blankLines="1"/>
        This  "Boolean"</t>
          <t>This is true if the server supports push notifications over the
	  WebSocket, as described in <xref target='push' />.
        </t>
      </list>

      <figure>
	<preamble>
          Example:
        </preamble>

<artwork><![CDATA[ target="push"
	  format="default"/>.</t>
        </li>
      </ul>
      <t keepWithNext="true"> Example:</t>
<artwork name="" type="" align="left" alt=""><![CDATA[
"urn:ietf:params:jmap:websocket": {
  "url": "wss://server.example.com/jmap/ws/",
  "supportsPush": true
}
]]></artwork>
      </figure></t>
    </section>
    <!-- discovery -->

    <section anchor='jmap' title='JMAP Subprotocol'> anchor="jmap" numbered="true" toc="default">
      <name>JMAP Subprotocol</name>
      <t>The term WebSocket subprotocol refers to an application-level
      protocol layered on top of a WebSocket connection.  This
      document specifies the WebSocket JMAP subprotocol for carrying
      JMAP API requests, responses, and optional push notifications
      through a WebSocket connection.
      Binary data is handled per Section 6
      of <xref target='RFC8620' /> via target="RFC8620" sectionFormat="of"
      section="6"/> (via a separate HTTP connection or stream.</t> stream)
      or per a future extension to JMAP or this specification.</t>
      <section anchor='authentication' title='Authentication'> anchor="authentication" numbered="true" toc="default">
        <name>Authentication</name>
        <t>A JMAP WebSocket connection is authenticated by presenting
        a user&apos;s user's <xref target='RFC7235'>credentials target="RFC7235" format="default">credentials in the
        HTTP request</xref> that initiates the WebSocket handshake.
        See Section 8.2 of <xref target='RFC8620' /> target="RFC8620" sectionFormat="of" section="8.2"/> for
        recommendations regarding the selection of HTTP authentication
        schemes.</t>
      </section>
      <!-- authentication -->

      <section anchor='handshake' title='Handshake'> anchor="handshake" numbered="true" toc="default">
        <name>Handshake</name>
        <t>The JMAP WebSocket client and JMAP WebSocket server
        negotiate the use of the WebSocket JMAP subprotocol during
        the WebSocket handshake, either via a an HTTP/1.1 Upgrade request
        (see Section 4 of <xref target='RFC6455' />) target="RFC6455" sectionFormat="of" section="4"/>)
        or a an HTTP/2 Extended CONNECT request (see Section 5 of
        <xref target='RFC8441' />). target="RFC8441" sectionFormat="of" section="5"/>).
        The WebSocket JMAP subprotocol is also intended to run
        over future bindings of HTTP (e.g. (e.g., HTTP/3) provided that there
        is a defined mechanism for performing a WebSocket handshake
        over that binding.</t>
        <t>Regardless of the method used for the WebSocket handshake,
        the client MUST <bcp14>MUST</bcp14> first perform a TLS handshake on a
        JMAP <xref target='discovery'>WebSocket target="discovery" format="default">WebSocket URL endpoint</xref>
        having the "wss://" scheme (WebSocket over TLS) in
        accordance with the requirements of running the particular
        binding of HTTP over TLS (see <xref target='RFC2818' /> target="RFC2818" format="default"/>
        and Section 4.1 of <xref target='RFC6455' /> target="RFC6455" sectionFormat="of" section="4.1"/> for HTTP/1.1
        and Section 9.2 of <xref target='RFC7540' /> target="RFC7540" sectionFormat="of" section="9.2"/> for HTTP/2).
        If the TLS handshake fails, the client MUST <bcp14>MUST</bcp14> close the
        connection. Otherwise, the client MUST <bcp14>MUST</bcp14> make an
        <xref target='RFC7235'>authenticated</xref> target="RFC7235" format="default">authenticated HTTP request request</xref>
        on the encrypted connection, connection and MUST <bcp14>MUST</bcp14> include the value "jmap"
        in the list of protocols for the "Sec-WebSocket-Protocol"
        header field.</t>
        <t>The reply from the server MUST <bcp14>MUST</bcp14> also contain a
        corresponding "Sec-WebSocket-Protocol" header field with a
        value of "jmap" in order
        for a JMAP subprotocol connection to be established.</t>
        <t>Once the handshake has successfully completed, the
        WebSocket connection is established and can be used for JMAP
        API requests, responses, and optional push notifications.
        Other message types MUST NOT <bcp14>MUST NOT</bcp14> be transmitted over this
        connection.</t>
        <t>The credentials used for authenticating the HTTP request
        to initiate the handshake remain in effect for the duration
        of the WebSocket connection.  If the authentication
        credentials for the user expire, the server can either treat
        subsequent requests as if they are unauthenticated or close
        the WebSocket connection.
        In the latter case, the server MAY <bcp14>MAY</bcp14> send a Close frame with a
        status code of 1008 (Policy Violation) Violation), as defined in Section
        7.4.1 of
        <xref target='RFC6455' />.</t> target="RFC6455" sectionFormat="of" section="7.4.1"/>.</t>
      </section>
      <!-- handshake -->

      <section anchor='messages' title='WebSocket Messages'> anchor="messages" numbered="true" toc="default">
        <name>WebSocket Messages</name>
        <t>Data frame messages in the JMAP subprotocol MUST <bcp14>MUST</bcp14> be
        text frames and contain UTF-8 encoded data.  The messages MUST <bcp14>MUST</bcp14>
        be in the form of a single JMAP Request object (see Section
        3.3 of
        <xref target='RFC8620' />), target="RFC8620" sectionFormat="of" section="3.3"/>),
        JMAP WebSocketPushEnable object (see <xref target='pushenable' />), target="pushenable" format="default"/>),
        or JMAP WebSocketPushDisable object (see <xref target='pushdisable' />) target="pushdisable" format="default"/>)
        when sent from
        the client to the server, and MUST be in the form of a single JMAP
        Response object, JSON Problem Details object, or JMAP StateChange
        object (see Sections 3.4, 3.6.1, <xref target="RFC8620" section="3.4"
	sectionFormat="bare"/>, <xref target="RFC8620" section="3.6.1"
	sectionFormat="bare"/>, and 7.1 respectively <xref target="RFC8620" section="7.1"
	sectionFormat="bare"/> of <xref target='RFC8620' />) target="RFC8620" format="default"/>,
	respectively) when sent from the server to the client.</t>
        <t>Note that fragmented WebSocket messages (split over
        multiple text frames) MUST <bcp14>MUST</bcp14> be coalesced prior to parsing them
        as JSON objects.</t>
        <section anchor='invalid' title='Handling anchor="invalid" numbered="true" toc="default">
          <name>Handling Invalid Data'> Data</name>
          <t>If a client or server receives a binary frame, the endpoint
          can either ignore the frame or close the WebSocket connection.
          In the latter case, the endpoint MAY <bcp14>MAY</bcp14> send a Close frame with a
          status code of 1003 (Unsupported Data) Data), as defined in Section
          7.4.1 of
          <xref target='RFC6455' />.</t> target="RFC6455" sectionFormat="of" section="7.4.1"/>.</t>
          <t>If a client receives a message that is not in the form of
          either
          a JSON Problem Details object, a JMAP Response
          object, or a JMAP StateChange object, the client can either
          ignore the message or close the WebSocket connection.
          In the latter case, the endpoint MAY <bcp14>MAY</bcp14> send a Close frame with a
          status code of 1007 (Invalid frame payload data Data) data), as
          defined in Section 7.4.1 of <xref target='RFC6455' />.
          </t> target="RFC6455" sectionFormat="of"
	  section="7.4.1"/>.</t>
          <t>A server MUST <bcp14>MUST</bcp14> return an appropriate
          <xref target='errors'>JSON target="errors" format="default">JSON Problem Details object</xref>
          for any request-level errors
          (E.g.
          (e.g., an invalid JMAP object, an unsupported capability or
          method call, or exceeding a server request limit).</t>
        </section>
        <!-- invalid -->

        <section anchor='requests' title='JMAP Requests'> anchor="requests" numbered="true" toc="default">
          <name>JMAP Requests</name>
          <t>The specification extends the Request object with two
          additional arguments when used over a WebSocket:

          <list style='symbols'>
          </t>
	  <ul spacing="normal">
	    <li>
              <t>@type: "String"
            <vspace blankLines="1"/>
            This MUST  "String"</t>
              <t>This <bcp14>MUST</bcp14> be the string "Request".</t>
            </li>
	    <li>
              <t>id:  "String" (optional)
            <vspace blankLines="1"/>
            A (optional)</t>
              <t>A client-specified identifier for the request to be echoed
	      back in the response to this request.</t>
          </list></t>
            </li>
          </ul>

          <t>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.</t>
          <t>Additionally, the "maxConcurrentRequests" limit in the
          "capabilities" object (see Section 2 of <xref target='RFC8620' />) target="RFC8620" sectionFormat="of"
	  section="2"/>) also applies to requests made on
          the WebSocket connection.  When using the WebSocket JMAP
          subprotocol over a binding of HTTP that allows multiplexing
          of requests (e.g. (e.g., HTTP/2), this limit applies to the the sum
          of requests made on both the JMAP API endpoint and the
          WebSocket connection.</t>
        </section>
        <!-- requests -->

        <section anchor='responses' title='JMAP Responses'> anchor="responses" numbered="true" toc="default">
          <name>JMAP Responses</name>
          <t>The specification extends the Response object with two
          additional arguments when used over a WebSocket:

          <list style='symbols'>

          </t>
          <ul spacing="normal">
	    <li>
              <t>@type: "String"
            <vspace blankLines="1"/>
            This MUST  "String"</t>
              <t>This <bcp14>MUST</bcp14> be the string "Response".</t>
            </li>
	    <li>
              <t>requestId:  "String" (optional; MUST <bcp14>MUST</bcp14> be
	      returned if an
            id identifier is included in the request)
            <vspace blankLines="1"/>
            The request)</t>
              <t>The client-specified identifier in the corresponding
	      request.</t>
          </list></t>
            </li>
          </ul>
        </section>
        <!-- responses -->

        <section anchor='errors' title='JMAP anchor="errors" numbered="true" toc="default">
          <name>JMAP Request-Level Errors'> Errors</name>
          <t>The specification extends the Problem Details object
          for request-level errors (see Section 3.6.1 of <xref target='RFC8620' />) target="RFC8620"
	  sectionFormat="of" section="3.6.1"/>) with two additional arguments
	  when used over a WebSocket:

          <list style='symbols'> WebSocket:</t>
          <ul spacing="normal">
	    <li>
              <t>@type: "String"
            <vspace blankLines="1"/>
            This MUST  "String"</t>
              <t>This <bcp14>MUST</bcp14> be the string "RequestError".</t>
            </li>
	    <li>
              <t>requestId:  "String" (optional; MUST <bcp14>MUST</bcp14> be
	      returned if given in the request)
            <vspace blankLines="1"/>
            The request)</t>
              <t>The client-specified identifier in the corresponding
	      request.</t>
          </list></t>
            </li>
          </ul>
        </section>
        <!-- errors -->

        <section anchor='push' title='JMAP anchor="push" numbered="true" toc="default">
          <name>JMAP Push Notifications'>
          <t>JMAP over WebSocket Notifications</name>
          <t>JMAP-over-WebSocket servers that support push
          notifications on the WebSocket will advertise a
          "supportsPush" property with a value of true in
          the "urn:ietf:params:jmap:websocket" server capabilities
          object.</t>
          <section anchor='pushformat' title='Notification Format'> anchor="pushformat" numbered="true" toc="default">
            <name>Notification Format</name>
            <t>All push notifications take the form of a standard
            StateChange object (see Section 7.1 of <xref target='RFC8620' />).</t> target="RFC8620" sectionFormat="of"
	    section="7.1"/>).</t>
            <t>The specification extends the StateChange object with one
            additional argument when used over a WebSocket:

            <list style='symbols'>
            </t>
            <ul spacing="normal">
	      <li>
                <t>pushState:  "String" (optional)
              <vspace blankLines="1"/>
              A (optional)</t>
                <t>A (preferably short) string that encodes the entire server
		state visible to the user (not just the objects returned in
		this call).
              <vspace blankLines="1"/>
              The call).</t>
                <t>The purpose of the "pushState" token is to allow a client
		to immediately get any changes that occurred while is it was
		disconnected (see <xref target='pushenable'/>). target="pushenable"
		format="default"/>). If the server does not support
		"pushState" tokens, the client will have to issue a series of
		"/changes" requests (see Section 5.2 of <xref target='RFC8620' />) target="RFC8620"
		sectionFormat="of" section="5.2"/>) upon reconnection to
		update its state to match that of the server.</t>
            </list></t>
              </li>
            </ul>
          </section>
          <!-- format -->

          <section anchor='pushenable' title='Enabling Notifications'> anchor="pushenable" numbered="true" toc="default">
            <name>Enabling Notifications</name>
            <t>A client enables push notifications from the server for
            the current connection by
            sending a WebSocketPushEnable object to the server.  A
            WebSocketPushEnable object has the following properties:

            <list style='symbols'>

            </t>
            <ul spacing="normal">
	      <li>
                <t>@type: "String"
              <vspace blankLines="1"/>
              This MUST  "String"</t>
                <t>This <bcp14>MUST</bcp14> be the string
		"WebSocketPushEnable".</t>
	      </li>
	      <li>
                <t>dataTypes: "String[]|null"
              <vspace blankLines="1"/>
              A  "String[]|null"</t>
                <t>A list of data type names (e.g. "Mailbox", (e.g., "Mailbox" or "Email") that
		the client is interested in. A 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.</t>
              </li>
	      <li>
                <t>pushState:  "String" (optional)
              <vspace blankLines="1"/>
              The (optional)</t>
                <t>The last "pushState" token that the client received from
		the server. Upon receipt of a "pushState" token, the server
              SHOULD
		<bcp14>SHOULD</bcp14> immediately send all changes since that
		state token.</t>
            </list></t>
              </li>
            </ul>
          </section>
          <!-- enabling -->

          <section anchor='pushdisable' title='Disabling Notifications'> anchor="pushdisable" numbered="true" toc="default">
            <name>Disabling Notifications</name>
            <t>A client disables push notifications from the server
            for the current connection by
            sending a WebSocketPushDisable object to the server.  A
            WebSocketPushDisable object has the following property:

            <list style='symbols'>

            </t>
            <ul spacing="normal">
	      <li>
                <t>@type: "String"
              <vspace blankLines="1"/>
              This MUST  "String"</t>
                <t>This <bcp14>MUST</bcp14> be the string "WebSocketPushDisable".</t>
            </list></t>
              </li>
            </ul>
          </section>
          <!-- disabling -->

        </section>
        <!-- push -->

      </section>
      <!-- messages -->

      <section title='Examples'> numbered="true" toc="default">
        <name>Examples</name>
        <t>The following examples show WebSocket JMAP opening
        handshakes, a JMAP Core/echo request and response, and a
        subsequent closing handshake.
        The examples assume that the JMAP WebSocket URL endpoint has been
        advertised in the JMAP Session object as having a path of
        "/jmap/ws/" and that TLS negotiation has already succeeded.
        Note that folding of header fields is for editorial purposes
        only.</t>

	<figure>
	  <preamble>
        <t keepWithNext="true">
            WebSocket JMAP connection via HTTP/1.1 with push
            notifications for mail <xref target='RFC8621' /> target="RFC8621" format="default"/>
	    is enabled. This example assumes that the client has cached
	    pushState "aaa" from a previous connection.
          </preamble>

<artwork><![CDATA[
        </t>
<artwork name="" type="" align="left" alt=""><![CDATA[
[[ From Client ]]                [[ From Server ]]

GET /jmap/ws/ HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade
Authorization: Basic Zm9vOmJhcg==
Sec-WebSocket-Key:
  dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Protocol: jmap
Sec-WebSocket-Version: 13
Origin: https://www.example.com

                                 HTTP/1.1 101 Switching Protocols
                                 Upgrade: websocket
                                 Connection: Upgrade
                                 Sec-WebSocket-Accept:
                                   s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
                                 Sec-WebSocket-Protocol: jmap

[WebSocket connection established]

WS_DATA
{
  "@type": "WebSocketPushEnable",
  "dataTypes": [ "Mailbox", "Email" ],
  "pushState": "aaa"
}

                                 WS_DATA
                                 {
                                   "@type": "StateChange",
                                   "changed": {
                                     "a456": {
                                       "Mailbox": "d35ecb040aab"
                                     }
                                   },
                                   "pushState": "bbb"
                                 }

WS_DATA
{
  "@type": "Request",
  "id": "R1",
  "using": [ "urn:ietf:params:jmap:core" ],
  "methodCalls": [
    [
      "Core/echo", {
        "hello": true,
        "high": 5
      },
      "b3ff"
    ]
  ]
}

                                 WS_DATA
                                 {
                                   "@type": "Response",
                                   "requestId": "R1",
                                   "methodResponses": [
                                     [
                                       "Core/echo", {
                                         "hello": true,
                                         "high": 5
                                       },
                                       "b3ff"
                                     ]
                                   ]
                                 }

WS_DATA
The quick brown fox jumps
 over the lazy dog.

                                 WS_DATA
                                 {
                                   "@type": "RequestError",
                                   "requestId": null,
                                   "type":
                             "urn:ietf:params:jmap:error:notJSON",
                                   "status": 400,
                                   "detail":
                             "The request did not parse as I-JSON."
                                 }

[A new email is received]

                                 WS_DATA
                                 {
                                   "@type": "StateChange",
                                   "changed": {
                                     "a123": {
                                       "Email": "0af7a512ce70"
                                     }
                                   }
                                   "pushState": "ccc"
                                 }

WS_CLOSE

                                 WS_CLOSE

[WebSocket connection closed]
]]></artwork>
	</figure>

	<figure>
	  <preamble>
        <t keepWithNext="true">
            WebSocket JMAP connection on a an HTTP/2 stream which that also
            negotiates <xref target='RFC7692'>compression</xref>:
          </preamble>

<artwork><![CDATA[ target="RFC7692" format="default">compression</xref>:
        </t>
<artwork name="" type="" align="left" alt=""><![CDATA[
[[ From Client ]]                [[ From Server ]]

                                 SETTINGS
                                 SETTINGS_ENABLE_CONNECT_PROTOCOL = 1

HEADERS + END_HEADERS
:method = CONNECT
:protocol = websocket
:scheme = https
:path = /jmap/ws/
:authority = server.example.com
origin: https://example.com
authorization = Basic Zm9vOmJhcg==
sec-websocket-protocol = jmap
sec-websocket-version = 13
sec-websocket-extensions =
  permessage-deflate
origin = https://www.example.com

                                 HEADERS + END_HEADERS
                                 :status = 200
                                 sec-websocket-protocol = jmap
                                 sec-websocket-extensions =
                                   permessage-deflate

[WebSocket connection established]

DATA
WS_DATA
[compressed text]

                                 DATA
                                 WS_DATA
                                 [compressed text]

...

DATA + END_STREAM
WS_CLOSE

                                 DATA + END_STREAM
                                 WS_CLOSE

[WebSocket connection closed]
[HTTP/2 stream closed]
]]></artwork>
	</figure>
      </section>
      <!-- examples -->

    </section>
    <!-- jmap -->

    <section title='Security Considerations' anchor='security'> anchor="security" numbered="true" toc="default">
      <name>Security Considerations</name>
      <t>The security considerations for both WebSocket (see Section
      10 of <xref target='RFC6455' />)
      target="RFC6455" sectionFormat="of" section="10"/>) and JMAP (see Section 8 of <xref target='RFC8620' />)
      target="RFC8620" sectionFormat="of" section="8"/>) apply to the
      WebSocket JMAP subprotocol. Specific security considerations are
      described in subsections of
      this section.</t> below.</t>
      <section title='Connection numbered="true" toc="default">
        <name>Connection Confidentiality and Integrity'> Integrity</name>
        <t>To ensure the confidentiality and integrity of
        data sent and received via JMAP over WebSocket, the WebSocket
        connection MUST <bcp14>MUST</bcp14> use <xref target='RFC5246'>TLS target="RFC5246" format="default">TLS 1.2</xref>
        or later, following the recommendations in <xref
        target='RFC7525'>BCP target="RFC7525" format="default">BCP 195</xref>.
        Servers SHOULD <bcp14>SHOULD</bcp14> support <xref target='RFC8446'>TLS target="RFC8446" format="default">TLS 1.3</xref> or
        later.</t>
      </section>
      <section title='Non-Browser Clients'> numbered="true" toc="default">
        <name>Non-browser Clients</name>
        <t>JMAP over WebSocket can be used by clients both running
        inside and outside of a web browser.  As such, the security
        considerations in Sections 10.2 <xref target="RFC6455" section="10.2"
	sectionFormat="bare"/> and 10.1 <xref target="RFC6455" section="10.1"
	sectionFormat="bare"/> of <xref target='RFC6455' /> target="RFC6455" format="default"/>
	apply to those respective environments.</t>
      </section>
    </section>
    <!--
    <section title='Privacy Considerations' anchor='privacy'>
      <t>TODO</t>

    </section>
-->
    <section title='IANA Considerations' anchor='iana'> anchor="iana" numbered="true" toc="default">
      <name>IANA Considerations</name>
      <section title='Registration numbered="true" toc="default">
        <name>Registration of the WebSocket JMAP Subprotocol'>
        <t>This specification requests Subprotocol</name>
        <t>Per this specification, IANA to register has registered the WebSocket
        JMAP subprotocol under following in the
	"WebSocket Subprotocol Name"
        Registry with Name Registry" within the following data:

        <list style="hanging">
	  <t hangText="Subprotocol Identifier:">jmap</t>

	  <t hangText="Subprotocol "WebSocket Protocol
	Registries".

        </t>
        <dl newline="false" spacing="normal">
          <dt>Subprotocol Identifier:</dt>
          <dd>jmap</dd>
          <dt>Subprotocol Common Name:">
          WebSocket Name:</dt>
          <dd>WebSocket Transport for JMAP (JSON Meta Application Protocol)</t>

	  <t hangText="Subprotocol Definition:">RFCXXXX (this document)</t>
        </list></t>
	  Protocol)</dd>
          <dt>Subprotocol Definition:</dt>
          <dd>RFC 8887</dd>
        </dl>
      </section>
    </section>
    <!-- IANA -->
  </middle>
  <back>
    <references>
      <name>References</name>
      <references>
        <name>Normative References</name>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.2818.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.5246.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.6455.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7235.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7525.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7540.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7692.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8441.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8446.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8620.xml"/>
      </references>
      <references>
        <name>Informative References</name>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8621.xml"/>
      </references>
    </references>
    <section title='Acknowledgments'> numbered="false" toc="default">
      <name>Acknowledgments</name>
      <t>The author would like to thank the following individuals for
      contributing their ideas and support for writing this
      specification: Neil Jenkins, Robert Mueller, and Chris Newman.</t>
    </section>

  </middle>

  <back>
    <references title='Normative References'>
      &rfc2119;
      &rfc2818;
      &rfc5246;
      &rfc6455;
      &rfc7235;
      &rfc7525;
      &rfc7540;
      &rfc7692;
      &rfc8174;
      &rfc8441;
      &rfc8446;
      &rfc8620;

    </references>

    <references title='Informative References'>
      &rfc8621;
    </references>

    <section title="Change History (To be removed by RFC Editor before
                    publication)">
      <t>Changes since ietf-06:
      <list style='symbols'>
        <t>Removed open issue on security of WebSocket compression,
        per Alexey Melnikov.</t>
      </list>
      </t>

      <t>Changes since ietf-05:
      <list style='symbols'>
        <t>Renamed "webSocketUrl" to "url" and "supportsWebSocketPush"
        to "supportsPush", per Benjamin Schwartz.</t>
        <t>Added a security subsection with a nod to Sections 10.1 and
        10.2 of RFC6455, per Leif Johansson.</t>
        <t>Clarified "unsupported JMAP" vs "unsupported JSON", per
        Benjamin Kaduk.</t>
        <t>Refer to RFC 7525 as BCP 195, per Benjamin Kaduk.</t>
        <t>Several editorial improvements from Benjamin Kaduk.</t>
        <t>Several editorial improvements from Murray Kucherawy.</t>
      </list>
      </t>

       <t>Changes since ietf-04:
       <list style='symbols'>
         <t>Require the use of TLS for JMAP over WebSocket
         (per Alissa Cooper and others).</t>
         <t>Added a section explaining how to handle unsupported messages
         (per Bob Briscoe).</t>
         <t>Added a section specifically addressing authentication of
         the WebSocket (per Leif Johansson).</t>
         <t>Corrected references into specific sections of RFC 8620
         (per Martin Vigoureax).</t>
         <t>Made RFC 7692 a normative reference (per Barry Leiba).</t>
         <t>Clarified that the "maxConcurrentRequests" limit applies to
         the sum of all requests on the current connection (per
         Benjamin Kaduk).</t>
         <t>Clarified that the "pushState" token represents the entire
         server state visible to the user (per Banjamin Kaduk).</t>
         <t>Clarified that "WebSocketPushEnable/Disable" only
         effect the current connection (per Benjamin Kaduk).</t>
         <t>Several editorial improvements from Benjamin Kaduk.</t>
       </list>
       </t>

      <t>Changes since ietf-03:
      <list style='symbols'>
        <t>Updated JMAP Mail reference to RFC 8621.</t>
        <t>Specified that requestId MUST be present in a response if
        given in the request.</t>
      </list>
      </t>

      <t>Changes since ietf-02:
      <list style='symbols'>
        <t>Updated JMAP Core reference to RFC 8620.</t>
        <t>Added 'WebSocketPushDisable' object.</t>
        <t>Editorial and formatting changes.</t>
      </list>
      </t>

      <t>Changes since ietf-01:
      <list style='symbols'>
        <t>Changed 'wsURL' to 'webSocketUrl' and removed push query option.</t>
        <t>Added 'supportsWebSocketPush' capability.</t>
        <t>Added '@type' argument to Request object.</t>
        <t>Added 'WebSocketPushEnable' object.</t>
        <t>Added 'pushState' argument to StateChange object.</t>
        <t>Updated example.</t>
        <t>Minor Editorial changes.</t>
      </list>
      </t>

      <t>Changes since ietf-00:
      <list style='symbols'>
        <t>Added text describing advertisement of and selection of optional
        push notifications.</t>
        <t>Minor Editorial changes.</t>
      </list>
      </t>

      <t>Changes since murchison-02:
      <list style='symbols'>
        <t>Renamed as a JMAP WG document.</t>
        <t>Allow out of order processing.</t>
        <t>Allow push notifications.</t>
        <t>Modified examples.</t>
        <t>Add Security Considerations text.</t>
        <t>Minor Editorial changes.</t>
      </list>
      </t>

      <t>Changes since murchison-01:
      <list style='symbols'>
        <t>Updated WebSocket over HTTP/2 reference to RFC8144.</t>
      </list>
      </t>

      <t>Changes since murchison-00:
      <list style='symbols'>
        <t>Fleshed out section on discovery of support for JMAP over
        WebSocket.</t>
        <t>Allow JSON Problem Details objects to be returned by the
        server for toplevel errors.</t>
        <t>Mentioned the ability to compress JMAP API requests.</t>
        <t>Minor Editorial changes.</t>
      </list>
      </t> <contact fullname="Neil Jenkins"/>, <contact
      fullname="Robert Mueller"/>, and <contact fullname="Chris Newman"/>.</t>
    </section>
  </back>
</rfc>