[Telepathy] Spec meeting notes on Mail Notification interface

[Simon McVittie]

On Wed, 20 Jan 2010 at 15:09:17 -0500, Nicolas Dufresne wrote:
> Le mercredi 20 janvier 2010 à 18:57 +0000, Will Thompson a écrit :
> >         Subscribe()/Unsubscribe():
> >         • Needs rationale in the spec: we think this is because on
> >         some
> >            protocols you get push notification of “something has
> >         changed” and
> >            need to go and poll to find out what it is.
> 
> I agree this needs a rational. Subscribe/Unsubscribe should be used to
> trigger notification on some protocol (like google) and to reduce
> network and memory overhead if nobody is using it.

What happens if one client calls Subscribe() twice, then Unsubscribe() once?
Is it still subscribed or not? Must implementations track the unique name of
clients that have called Subscribe() to see if they crash?

Unless you can think of a compelling reason why not, I think the answer
should be as follows: The CM tracks a subscription count (like a refcount)
for each unique bus name that has called Subscribe(). When a client calls
Unsubscribe(), it releases one "reference". If a client exits, it releases
all of its "references".

The spec should say this explicitly. Another superficially appealing model
is that each client is either subscribed or not (so one call to Unsubscribe()
undoes the effect of any number of previous calls to Subscribe() - this is how
handle ownership currently works), but in practice that makes it harder to
implement clients.

> >         Maybe Mail should be aa{sv} rather than a{sv} and have the
> >         first part be
> >         the header, the rest the (optional) body parts, like on
> >         Messages. You
> >         could have a flag in the message body parts saying if it's a
> >         snippet.
> >         (We apparently already have one, it's called 'truncated'.)
> 
> I'm not sure I understand very well your idea for mail structure, could
> you elaborate a bit ?

You've invented a somewhat elaborate data structure to represent a message.
However, the Messages interface already has a similar data structure (which
can also deal with more complex messages). It may be worth representing a
mail in the same way as a Messages message, and just defining some extra
fields ("mail-from", "mail-cc", "mail-to", "mail-is-thread" etc.) and
forbidding some of the Messages fields from appearing in the MailNotification
interface where they don't make sense (like "message-sender").

> >         HTTP_Post_Data: are they guaranteed to be UTF-8 on the wire?
> >         If not,
> >         then they need to be ay not s. Are they percent-encoded or
> >         not?
> 
> I think it would be worth specifying that this is www-form data, so it's
> ASCII (a subset of UTF-8).

HTTP mostly deals in bytes, not characters.

Suppose the required POST data is a map where the keys are bytes 0x01 and 0x80,
and the values are equal to the keys. (Note that the byte 0x80 is meaningless
on its own in UTF-8 - the byte-string '\x80' is not valid UTF-8.)

I can see at least three reasonable ways to represent this (using dbus-python
notation):

signature 's':
    dbus.String('%01=%01&%80=%80')

signature 'a(ss)':
    dbus.Array([
        dbus.Struct(('%01', '%01'), signature='ss'),
        dbus.Struct(('%80', '%80'), signature='ss'),
    ], signature='(ss)')

signature 'a(ayay)':
    dbus.Array([
        dbus.Struct((dbus.ByteArray('\x01'), dbus.ByteArray('\x01'))),
        dbus.Struct((dbus.ByteArray('\x80'),dbus.ByteArray('\x80'))),
    ], signature='(ayay)')

You've chosen the second one. Why?

Do practical HTTP libraries/browsers support passing pre-encoded data to a POST
request, or would UIs, in practice, have to decode the s and a(ss) versions
and pass them to the library as byte arrays for re-encoding? (If UIs would have
to decode them, that's an argument in favour of a(ayay).)

> >         The flags' names aren't great. Perhaps:
> >         • Supports_Unread_Mail_Count
> >         • Supports_Unread_Mails
> >         • Emits_Mails_Received
> >         The flags' interdependencies are pretty hard to understand
> >         well. Needs
> >         some kind of truth table!
> 
> The original naming has the advantage that it uses the exact name of
> properties/method that is supported. 'has' vs 'supports' is quite the
> same to me, but english is not my first language, though 'has' is much
> shorter.

Be aware that in the Telepathy extensions to the D-Bus XML format, names that
are in Ugly_Case will generally be mapped to a different case convention for
bindings. Has_Prop_UnreadMails would become ..._HAS_PROP_UNREADMAILS in
telepathy-glib, whereas I think you actually want ..._HAS_PROP_UNREAD_MAILS,
or (as wjt suggests) ..._SUPPORTS_UNREAD_MAILS or ..._HAS_UNREAD_MAILS.

> Dependency are:
> * Has_Prop_UnreadMails implies Has_Prop_UnreadMailCount
> * Has_Prop_UnreadMails and Has_Signal_MailsReceived are exclusive

I see... so we probably can't just decompose this into two interfaces.
Am I right in saying that there are basically four "compliance levels", then?

* UnreadMailCount (can this happen? Is it useful to UIs?)
* MailsReceived only (you're told about new mail but can't see anything about
  old mail)
* MailsReceived and UnreadMailCount (you're told about new mail but can't
  see anything about old mail other than how many there were)
* UnreadMails and UnreadMailCount (full state-recovery for unread mail)

> >         
> >         General remark: the interface needs to be clearer about the
> >         different
> >         features of actual protocols, with more rationale.

I second this. Please explain what information GTalk, MSN and libpurple
actually give us, for instance in <tp:rationale> sections.

> >         Maybe we
> >         should
> >         consider splitting it into several interfaces? (Although there
> >         might be
> >         enough overlap not to need to... it's hard to tell without
> >         rationale in
> >         the spec.)
> 
> I think splitting the interface would also create some sort of
> confusion. The problem is not so simple because protocols usually
> disagree on what mail notification should be.

wjt's point is that if UIs have to look at the value of the capabilities
bitfield and decide between two different code paths, then this isn't
really one API at all, it's two APIs sharing an interface name, and it might
cause less confusion to represent it as such.

> We now have RequestInboxURL and RequestMailURL methods. Cookies has been
> discarded from interface since it would require some sort of system wide
> cookie manager in the Linux desktop.

That looks like an improvement, yes.

Regards,
    Simon