Re: [lemonade] Expert Review: annotatemore (like WGLC)

[Dan Karp <dkarp@xxxxxxxxxx>]

> http://www.ietf.org/internet-drafts/draft-daboo-imap-annotatemore-11.txt

Comments interspersed btween snippets of the draft:

   Changes from -10 to -11:
   7.   Added match type and collation identifier to the LIST-EXTENDED
        selection option.
   8.   Made support for IMAP-I18N a requirement.

   Text comparisons may be done as part of the GETMETADATA or LIST-
   EXTENDED commands.  As a result, support for the COMPARATOR
   [I-D.ietf-imapext-i18n] extension is REQUIRED.

GETMETADATA doesn't actually do text comparisons, right?  The BNF
doesn't seem to tie in the "matchtype" or "collation" productions.

But more to the point, I believe that the intention was that METADATA
should be a simple, baseline extenstion that will be required by a wide
range of other extensions.  If that's the case, *PLEASE* reconsider the
wisdom of adding the LT, LE, GT, and GE matchers (and thus the
COMPARATOR requirement) to this draft.  It doesn't apear to be core
functionality for METADATA, and since COMPARATOR appears nontrivial to
implement this may not only prevent server authors from implementing
METADATA but also keep us from impelenting any future extension that
requires METADATA.


   A user can only set and retrieve private or shared annotations on a
   mailbox which exists and is returned to them via a LIST or LSUB
   command, irrespective of whether they have read or write access to
   the actual message content of the mailbox.  If the client attempts to
   set or retrieve annotations on other mailboxes, the server MUST
   respond with a NO response.

I can understand the logic behind requiring LIST/LSUB access for reading
public mailbox annotations and for setting private annotations.  But
that seems to be a very low bar for setting public mailbox annotations.
Adding a new ACL permission for setting annotations would make this
extension more complex and would also introduce a dependency on the ACL
extension, but perhaps requiring [READ-WRITE] access to the mailbox
might be reasonable?


   The new SETMETADATA command and the METADATA response each have a
   mailbox name argument, indicating that the annotations being referred
   to are attached to the specified mailbox.  An empty string can be
   used for the mailbox name to signify server annotations.

What rights are required to set public and private annotations on the
server?


   This command sets the specified list of entries by adding or
   replacing the specified attributes with the values provided, on the
   specified existing mailboxes.  Clients can use NIL for values of
   attributes it wants to remove from entries.  The server MAY return a
   METADATA response containing the updated annotation data.

In this case, the server may return a METADATA response that doesn't
contain the updated annotation data or a LIST response that does,
correct?


   This extension adds the GETMETADATA command.  This allows clients to
   retrieve server annotations.  Mailbox annotations are retrieved via
   the extended LIST command described in the next section.

   This extension adds the SETMETADATA command.  This allows clients to
   set annotations.

It's a little incongruous that GETMETADATA is used only to retrieve
server annotations, but SETMETADATA can be used to set both server and
mailbox annotations.  I understand that the mailbox-level function of
GETMETADATA has been passed to the LIST-EXTENDED feature, but generally
it's clearer when a GETFOO and SETFOO pair cover the same target space.


   If the METADATA extension is present, support for shared annotations
   is REQUIRED, whilst support for private annotations is OPTIONAL.
   This recognizes the fact that support for private annotations may
   introduce significantly more complexity to a server in terms of
   tracking ownership of the annotations, how quota is determined for
   users based on their own annotations etc.  Clients that support the
   METADATA extension MUST handle both shared and private annotations.

Is there a mechanism for informing clients that a server does not
support private annotations?  Or is a client expected to determine this
from METADATA NOPRIVATE response codes on a SETMETADATA NO response?

If the latter is the case, won't client implementations end up allowing
users one attempt to set private annotations and only then inform them
that the functionality is not supported by the server?  (This would
probably occur once per IMAP session...)


   If the server is unable to set an annotation because the size of its
   value is too large, the server MUST return a tagged NO response with
   a "[METADATA TOOBIG]" response code.

Likewise, is there a mechanism for a server to tell its clients the
maximum annotation length it supports?  Or is it up to the client to
determine this from METADATA TOOBIG error code responses?


   Entry and attribute names are case-sensitive.

   Entry and attribute names MUST NOT contain asterisk ("*") or percent
   ("%") characters and MUST NOT contain non-ASCII characters or the NUL
   octet.  Invalid entry or attribute names result in a BAD response in
   any IMAP commands where they are used.

   Use of control or punctuation characters in entry and attribute names
   is strongly discouraged.

It's probably cleaner in the long run to use the BNF to explicitly
specify a limited set of permitted characters for entry and attribute
names.  Constraining them to something like "atom" plus the delimiters
is probably not a bad idea.

Given that these names are already constrained to ASCII, I'd favor
eliminating the case-sensitivity requirement.  It differs from other
IMAP commands and extensions' general consistent overall case-
insensitivity (e.g. RFC 3501 keywords).


   value
      A string or binary data representing the value of the annotation.
      To delete an annotation, the client can store "NIL" into the
      value.  The content represented by the string is determined by the
      Content-Type used to register the entry (see Section 6.1 for entry
      registration templates).  Where applicable, the registered
      Content-Type MUST include a charset parameter.  Text values SHOULD
      use the utf-8 [RFC3629] character set.

Is there any reason not to mandate UTF-8 for text values?  We seem to be
moving towards standardizing on UTF-8 in IMAP, and this seems a good
opportunity to draw a line.


   /sort
      Defines the default sort criteria [I-D.ietf-imapext-sort] to use
      when first displaying the mailbox contents to the user, or NIL if
      sorting is not required.  Note that the presence of this attribute
      does not imply that the server supports the IMAP SORT
      [I-D.ietf-imapext-sort] extension - servers can choose to support
      or not support SORT independently of this extension.  In the
      absence of the SORT extension, clients can choose to interpret
      this entry as suggesting a client-side sort ordering of the
      corresponding mailbox.

   /thread
      Defines the default thread criteria [I-D.ietf-imapext-sort] to use
      when first displaying the mailbox contents to the user, or NIL if
      threading is not required.  If both sort and thread are not NIL,
      then threading should take precedence over sorting.  Note that the
      presence of this attribute does not imply that the server supports
      the IMAP THREAD [I-D.ietf-imapext-sort] extension - servers can
      choose to support or not support THREAD independently of this
      extension.  In the absence of the THREAD extension, clients can
      choose to interpret this entry as a client-side thread ordering of
      the corresponding mailbox.

These registered annotations are odd ducks.  They seem most appropriate
as private annotations on a mailbox, but in practice they may be
confusing to the end user because sorting and threading preferences are
often client-specific, not user-specific.

For instance, a user may prefer to read their mail nonthreaded on the
desktop, but on a mobile device they may want to make use of the reduced
visual footprint of a threaded display.  Likewise, more likely than not
a user won't expect their sort preferences to automatically be
transferred between their devices and clients.


   Mailboxes or the server as a whole may have zero or more annotations
   associated with them.  An annotation contains a uniquely named entry
   with a set of uniquely named attributes, each of which has a value.
   Annotations can be added to mailboxes when a mailbox name is provided
   as the first argument to the new command, or to the server as a whole
   when the empty string is provided as the first argument to the new
   command.

Just a nitpick here, but you should probably refer to SETMETADATA
command by name since (a) it hasn't been introduced at this point in the
document and (b) there is more than one new command added by the draft.


   Each annotation is an entry that has a hierarchical name, with each
   component of the name separated by a slash ("/").  An entry name MUST
   NOT contain two consecutive "/" characters and MUST NOT end with a
   "/" character.

   Each entry is made up of a set of attributes.  Each attribute has a
   hierarchical name, with each component of the name separated by a
   period (".").  An attribute name MUST NOT contain two consecutive "."
   characters and MUST NOT end with a "." character.

My last comment is personal preference: I fear that this may be a bit of
overkill for folder annotation.  I understand the need for this type of
flexible syntax for ACAP's purposes, but the use cases for IMAP appear
significantly more limited in scope.  In accordance with the KISS
philosophy, is there any chance I might be able to convince everyone to
consider shedding a layer of hierarchy here?