Rayo complete reason changes

README.md

It is proposed that the <success/> element, indicating that a component completed successfully, be replaced by a set of more descriptively named elements, such as <initial-timeout/>, <end-of-file/>, etc. These allow the client to correlate the actual completion reason with what are potentially a large set of possible triggers from the original command. For example, setting both max-time and interrupt-on on an Output results in an ambiguous <success/> reason. In the case of Input, <success/> will be renamed <match/>.

Further, it is concerning that node ordering is still being relied upon for disambiguating children of <complete/>. Currently, the Record component may submit a complete event like this:

<presence to='[email protected]/1' from='[email protected]/fgh4590'>
  <complete xmlns='urn:xmpp:rayo:ext:1'>
    <success xmlns='urn:xmpp:rayo:record:complete:1'/>
    <recording xmlns='urn:xmpp:rayo:record:complete:1' 
         uri="file:/tmp/rayo7451601434771683422.mp3"
         duration="34000"
         size="23450"/>
  </complete>
</presence>

If a Rayo server were to instead spit out this event:

<presence to='[email protected]/1' from='[email protected]/fgh4590'>
  <complete xmlns='urn:xmpp:rayo:ext:1'>
    <recording xmlns='urn:xmpp:rayo:record:complete:1' 
         uri="file:/tmp/rayo7451601434771683422.mp3"
         duration="34000"
         size="23450"/>
    <success xmlns='urn:xmpp:rayo:record:complete:1'/>
  </complete>
</presence>

merry hell would break loose in clients. I strongly believe it is unacceptable to rely on the order of sibling nodes to provide any semantic value. Unfortunately, we currently have no other way of disambiguating a completion reason from any other child element. There are a few possible solutions to this:

1. Make the reason an attribute of <complete/>, and force any further meta-data to be included as children. [PREFERRED]
2. Mandate that the ONLY allowed child of <complete/> be the reason for completion, and any meta-data (such as recordings) be nested within the reason element.
3. Introduce a generic <reason/> element with a child such as <timeout/>.

A couple of comments on this proposal.

With regards to the reason names. What I liked about success (doing devils advocate here) is that it is a very understandable reason. Success is always good. On the other hand, all the other reasons meant failure, which is also quite understandable. So simply question is, if new reasons are introduced, how do I know if they are a success or a failure? Do I need to know the spec? Example, I am a developer and I get <end-of-file/>. Right. Is that good or bad?

With regards to 2.1. With that solution the schema becomes a bit weird. I mean, a complete element would have many unrelated child elements.
I like 2.2 more.

As far as grouping reason names into success/failure goes, the options are either to enumerate them in the spec, or have generic <success type="terminator"/>, <failure type="hangup"/>, etc. That also solves the problem of knowing which is the reason element.

Comments about the second part noted, and I'm on the fence.

On Reason Names: the distinction between success/failure is simple. Anything other than <error/> is success. A "no match" is a perfectly valid and common use case. My vote is to enumerate the reasons in the spec and have clients surface the various reason however they like.

On element order: I honestly don;t see what the big deal is. XML / Schema was designed to explicitly support ordered elements (i.e. sequence) and every XML client I've ever seem offeres a method for iterating over child elements in document order. If we absolutely have to change it, my vote is for options #2 (i.e. single reason element).

I agree that ordered elements is not a big deal. From a server implementation perspective, it matters little how the event is formatted so go with whatever makes client implementation easy and doesn't mess up the schema.