setMessages - Document args better?

[wolf...@gmail.com]

Under the messages specification, the spec says:

•   from: Emailer[]|null An array of name/email objects (see below) representing the parsed From header of the email, in the same order as they appear in the header. If the email  doesn’t have a From header, this is null. If the header exists but does not have any content, the response is an array of zero length.
•   to: Emailer[]|null An array of name/email objects (see below) representing the parsed To header of the email, in the same order as they appear in the header. If the email doesn’t have a To header, this is null. If the header exists but does not have any content, the response is an array of zero length.
• 
  
• So from/to are both arrays of hashes (speaking in Perl terms here).
  

Under setMessages - "Saving a Draft"

• from: Optional. Overrides a “From” in the headers.
• to: Optional. Overrides a “To” in the headers.

Since this doesn't specify a different data type, I expect these to both be arrays of hashes.

However it looks like from is actually just a hash, and to is still an array (at least as far as the JMAP Proxy is concerned).

It might be useful to update this section with the datatype of each arg?

Thanks,

-- Matthew Horsfall (alh)

[Neil Jenkins]

On Tue, 30 Aug 2016, at 12:11 PM, wolf...@gmail.com wrote:

• from: Optional. Overrides a “From” in the headers.
  
• to: Optional. Overrides a “To” in the headers.
  

Since this doesn't specify a different data type, I expect these to both be arrays of hashes.

The "headers" property has a datatype of String[ String ] –  it is a hash of the raw headers. The from/to properties are parsed versions of these headers. What the spec is saying here is that if you set both in a setMessages, the to/from property (serialised to RFC2822 format) will overwrite the value in the "headers" hash.

Neil.

[Matthew Horsfall (alh)]

On Mon, Aug 29, 2016 at 11:23 PM, Neil Jenkins <ne...@fastmail.com> wrote:
> The "headers" property has a datatype of String[ String ] – it is a hash of
> the raw headers. The from/to properties are parsed versions of these
> headers. What the spec is saying here is that if you set both in a
> setMessages, the to/from property (serialised to RFC2822 format) will
> overwrite the value in the "headers" hash.
>

That doesn't really clarify anything though does it?. Both "from" and
"to" are in the headers, but these are different data types on
setMessages. Putting the types of all arguments where they are
described in the spec could be really useful to readers/implementers.

-- Matthew Horsfall (alh)

[Neil Jenkins]

On Tue, 30 Aug 2016, at 10:56 PM, Matthew Horsfall (alh) wrote:

That doesn't really clarify anything though does it?. Both "from" and

"to" are in the headers, but these are different data types on setMessages.

These are two representations of the same data. The `headers` property on the Message object gives you the raw headers, e.g.

"headers": {

    "from": "Joe Bloggs <j...@example.com>",

    "to": "John Smith <jo...@example.com>, ja...@example.com"

}

As in the spec, it is of type String[ String ].

While the `from` and `to` (and `cc`/`bcc`) properties on the Message object give you parsed representations and are of type Emailer[]|null, e.g.

"from": [{

    "name": "Joe Bloggs",

    "email": "j...@example.com"

}],

"to": [{

    "name": "John Smith",

    "email": "jo...@example.com"

}, {

    "name": "",

    "email": "ja...@example.com"

}],

"cc": null

Now if you are setting rather than getting, we need to define what happens should a client both set a `from` or `to` property AND include a `from` or `to` field inside a `headers` property (even though it's unlikely a client would ever do this in practice, at least intentionally). The spec says in this case the `from`/`to` properties overwrite the version in the `headers` property.

Is that clearer?

Neil.

[Ricardo Signes]

* Neil Jenkins <ne...@fastmail.com> [2016-08-30T18:55:55]

> Now if you are setting rather than getting, we need to define what
> happens should a client both set a `from` or `to` property AND include a
> `from` or `to` field inside a `headers` property (even though it's
> unlikely a client would ever do this in practice, at least
> intentionally). The spec says in this case the `from`/`to` properties
> overwrite the version in the `headers` property.
>
> Is that clearer?

I think Matt has asked a different question than you answered.

* wolf...@gmail.com [2016-08-29T22:11:48]

> Under setMessages - "Saving a Draft"
>

> - *from*: Optional. Overrides a “From” in the *headers*.
> - *to*: Optional. Overrides a “To” in the *headers*.

> Since this doesn't specify a different data type, I expect these to both be
> arrays of hashes.
>
> However it looks like from is actually just a hash, and to is still an
> array (at least as far as the JMAP Proxy is concerned).

When given "from" and "to" to the "create" stanza of setMessages, one would
expect it to take the same datatypes that are returned by getMessages. That
is, you'd expect that you must pass `Emailer[]|null` for both from and to.

Matt said that "as far as the JMAP Proxy is concerned" the types are `Emailer`
for from, but `Emailer[]` for to. So he was saying, "If the args to
setMessages differ from getMessages, it should be documented."

I consulted the history of the spec and found this:

https://github.com/jmapio/jmap/commit/7b45eb3c2e4983d17a819775238a28746cc7dc01

The "from" attribute only became an array in February, and the JMAP Proxy has
not yet been updated to match the spec.

So: there's your answer, Matt. I leave it to you to file a GitHub Issue.

--
Ricardo Signes (rjbs)
Research & Development, IC Group

[Neil Jenkins]

Ah, right. I missed you were talking about the proxy, I thought this was a spec question. Yes, the proxy is currently a bit out of date with the latest spec. The Message datatype is definitely the same whether setting or getting!

Neil.

[Matthew Horsfall (alh)]

To me it was a spec question, I didn't realize the proxy was out of date :)

I think I'm good then.

Thanks!

-- Matthew Horsfall (alh)

[Matthew Horsfall (alh)]

On Tue, Aug 30, 2016 at 8:35 PM, Ricardo Signes <rj...@icgroup.com> wrote:
> I consulted the history of the spec and found this:
>
> https://github.com/jmapio/jmap/commit/7b45eb3c2e4983d17a819775238a28746cc7dc01
>
> The "from" attribute only became an array in February, and the JMAP Proxy has
> not yet been updated to match the spec.
>
> So: there's your answer, Matt. I leave it to you to file a GitHub Issue.

Thanks for clearing this up.

Filed: https://github.com/jmapio/jmap-perl/issues/38

-- Matthew Horsfall (alh)