Request-level extensibility (top level object rather than array)

[brong]

From Chris Newman:

3.2. API structure

This model only allows extensibility by adding methods or altering
method parameters. There's no way to attach properties to the entire
API request. There are a number of potentially interesting
request-level properties such as "fail on error" (stop on first error)
or "transaction"/"atomic" (either perform all methods successfully or
none of them). If you made the top-level an object and the array of
methods a property of the top-level object, you'd get request-level
extensibility.

[cjnewman]

Questions:

1. How does the server respond if the client lists a capability the server doesn't recognize? (RFC5161 says the server MUST ignore unrecognized client capabilities)

2. Does the client need an ACK for capabilities the server does recognize (RFC 5161 has the ENABLED reply)? Or can the client assume any capability listed in server capabilities will always work in the using parameter?

3. Is it necessary to include using in every request, or is using "sticky" for the HTTP session? Is using optional for cases where it's implicit from the method call what extensions are being used?

4. Is there a size limit on the properties the server must ignore?

[brong]

On Wed, 22 Nov 2017, at 12:24, cjnewman wrote: Questions: 1. How does the server respond if the client lists a capability the server doesn't recognize? (RFC5161 says the server MUST ignore unrecognized client capabilities)

What the hell RFC5161. That's kinda silly: . ENABLE WIBBLE . OK Completed Yep, that's how Cyrus handles it. . ENABLE CONDSTORE * ENABLED CONDSTORE . OK Completed OK, so the difference is, you can only rely on having the extension if the server sends a: * ENABLED $FEATURE JMAP's capability request would be more like sieve require: require ["wibble"]; Unable to parse script: script errors: line 1: Unsupported feature(s) in "require": "wibble"

1. Does the client need an ACK for capabilities the server does recognize (RFC 5161 has the ENABLED reply)? Or can the client assume any capability listed in server capabilities will always work in the using parameter?

If they don't work, I assume the server would return an unsupportedFeature error for the entire request. That's a good point. I won't create a github for it just yet, but let's wait to see how Neil adds handling for unsupported capabilities being requested to the spec.

1. Is it necessary to include using in every request, or is using "sticky" for the HTTP session? Is using optional for cases where it's implicit from the method call what extensions are being used?

Include in every request was where we got to. There is no "HTTP session", and it's never implicit. Even the most basic request will need the boilerplate for this RFC.

1. Is there a size limit on the properties the server must ignore?

Yeah, good point - we probably should define both a maxlength for extension names, and a maximum number of extensions that can be used in a single request. If it turns out that most requests are using a large number of the same extensions (like the case with IMAP right now where if you had to opt in to uidplus and literal+ and list-ext and condstore and ... every time), then we'll probably release a JMAPbis which defines a profile which subsumes all the common extensions into a single require macro: require: ["jmap2019"] or whatever. Bron.

…

-- Bron Gondwana, CEO, FastMail Pty Ltd brong@fastmailteam.com

[cjnewman]

RFC 5161 is based on the assumption that most server capabilities can simply be used by the client if it sees them in the server capability list so there's normally no need for additional negotiation. I think there are only 3 IMAP extensions that recommend/require explicit client enable, so an IMAP client can simply have a fixed enable string it sends to all servers and it gets a list of the enabled features back -- that's simple to implement on both ends. It's a fine model for an interactive protocol.

The Sieve require model is appropriate for a non-interactive format (although I like the ihave Sieve extension in RFC5463).

An example of a bad negotiation model for an interactive protocol is Telnet option negotiation. Consider that the "how not to do it" guide (either side can request negotiation of an option and both sides must agree to use an option).

While I can live with your proposal, I think it would be more efficient to get closer to the 5161 model where the client only lists the capabilities that enable changes to server response syntax/semantics that are not implicit from the request structure.

[brong]

On Thu, 23 Nov 2017, at 06:46, cjnewman wrote: While I can live with your proposal, I think it would be more efficient to get closer to the 5161 model where the client only lists the capabilities that enable changes to server response syntax/semantics that are not implicit from the request structure.

I hate implicit, and I hate having to derive capabilities from guesses about the structure. I'm really strongly in favour of explicitly listing the extensions the request needs. Particularly since there's no real efficiency loss if your request fits inside a single packet. Bron.

…

-- Bron Gondwana, CEO, FastMail Pty Ltd brong@fastmailteam.com