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/>.

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.