Subject: [Jmap] draft-murchison-jmap-websocket as a JMAP working product

From: Barry Leiba <[email-masked]>
Date: Wed, 7 Nov 2018 14:20:54 +0700

In the JMAP session at IETF 103, we have just had no objections to
accepting the subject document.  Are there any objections here on the
mailing list?  Please voice objections by 16 November; if we hear
none, the chairs will approve draft-ietf-jmap-websocket-00 for
posting.

Barry

---

From: "Neil Jenkins" <[email-masked]>
Date: Fri, 23 Nov 2018 00:56:53 -0500

We also discussed the open issues at the JMAP session in IETF 103: 
 
>  o Should we allow push notifications over the WS connection? 
 
The consensus in the room was "yes", we should use the connection we already have. We would therefore need to: 
 * Add a tag to each JSON object sent through the socket so we know what it is. I would suggest an `@type` property with values of `"Request"` (sent by the client to the server), `"Response"` and `"StateChange"` (sent by the server for API responses and pushes respectively). (These are the names of the objects in the JMAP spec.) 
 
>  o Should we allow out of order processing of requests? 
 
Again the consensus was "yes"; you can use a single WebSocket connection as the equivalent to parallel HTTP API requests. This means we also need an `id` property on Request and Response objects so they can be correlated by the client.  
 
We probably also need to clarify that the core `maxConcurrentRequests` limit is applies to inflight requests over the WebSocket. We may need a new limit (exposed in the capability object) for establishing concurrent WebSocket connections (although a client shouldn't really need more than 1; that's the point)?
 
Ken, are you able to update the spec and we can publish a new version as a JMAP working group product? Thanks. 
 
Neil.

---

From: Ken Murchison <[email-masked]>
Date: Fri, 23 Nov 2018 07:38:42 -0500

On 11/23/18 12:56 AM, Neil Jenkins wrote:
> The consensus in the room was "yes", we should use the connection we 
> already have. We would therefore need to:
>
>   * Add a tag to each JSON object sent through the socket so we know
>     what it is. I would suggest an |@type| property with values of
>     |"Request"| (sent by the client to the server), |"Response"| and
>     |"StateChange"| (sent by the server for API responses and pushes
>     respectively). (These are the names of the objects in the JMAP spec.)
>

Se already have @type in the problem details object returned for a 
request level error.  Can't the client simply check the response object 
for "methodResponses" , or "changed", or "type"? Otherwise, perhaps 
"responseType".

> Again the consensus was "yes"; you can use a single WebSocket 
> connection as the equivalent to parallel HTTP API requests. This means 
> we also need an |id| property on Request and Response objects so they 
> can be correlated by the client.

Should we make this "requestId" to be a little more descriptive? Or 
perhaps steal "tag" from IMAP?

>
> We probably also need to clarify that the core |maxConcurrentRequests| 
> limit is applies to inflight requests over the WebSocket. We may need 
> a new limit (exposed in the capability object) for establishing 
> concurrent WebSocket connections (although a client shouldn't really 
> need more than 1; that's the point)?
>

Sure.

-- 
Ken Murchison
Cyrus Development Team
FastMail US LLC

---

From: Ken Murchison <[email-masked]>
Date: Fri, 23 Nov 2018 07:44:58 -0500

On 11/23/18 7:38 AM, Ken Murchison wrote:
>> connection as the equivalent to parallel HTTP API requests. This 
>> means we also need an |id| property on Request and Response objects 
>> so they can be correlated by the client.
>
>

Is "clientId" in the request not sufficient for correlation?

-- 
Ken Murchison
Cyrus Development Team
FastMail US LLC

---

From: Ken Murchison <[email-masked]>
Date: Fri, 23 Nov 2018 10:05:33 -0500

>     respectively). (These are the names of the objects in the JMAP spec.)

Do we push ALL notifications or do we allow the client to subscribe to 
notifications for certain object types?

-- 
Ken Murchison
Cyrus Development Team
FastMail US LLC

---

From: "Neil Jenkins" <[email-masked]>
Date: Fri, 30 Nov 2018 04:02:30 -0500

On Fri, 23 Nov 2018, at 11:38 PM, Ken Murchison wrote: 
> Se already have @type in the problem details object returned for a request level error. Can't the client simply check the response object for "methodResponses" , or "changed", or "type"? Otherwise, perhaps "responseType". 

There's a `type` property on the problem details object but not an `@type` property. This object would also need an `@type` property with a value probably of `"error"` (or maybe `"RequestError"` would be better actually). The client can then simply look at this property on the object it receives to know what type of object it is and how to dispatch it. That's simpler and cleaner than looking for certain properties which should be on one type of object but not another (which you could easily screw up in the future by adding an extra property with a common name). 
 
> Should we make this "requestId" to be a little more descriptive? Or perhaps steal "tag" from IMAP? 

We could, but in general with JMAP if a property is an id of the object it is on, that property is always just called "id". If it's a reference to an id of another object, then it gets prefixed with a description of what's being referenced. So I think `id` is probably more consistent on the `Request` object, but maybe name it `requestId` on the `Response` object to show that is what it is referencing. 
 
> Is "clientId" in the request not sufficient for correlation? 
 
Yes, except what if the Request object returns a `RequestError` problem details object (as discussed above)? We need to know which request generated the error, so I think need to have a matching `requestId` property on this object. 
 
> Do we push ALL notifications or do we allow the client to subscribe to notifications for certain object types? 
 
We should allow clients to choose what types they want push notifications for, like we do with the other two push mechanisms. I guess we define an API method to configure this that affects the push channel it's sent down. 
 
Neil.