Ad-hoc command error cases - Standards

4 Apr 2025

Hi!

While adding tests for XEP-0133: Service Administration to the XMPP Interop
Testing project, we ran into trouble. Specifically, it is unclear to me how
an ad-hoc command failure is to be represented.

Two XEPs are relevant:

   - XEP-0050: Ad-Hoc Commands
   - XEP-0133: Service Administration

I don't think either is exactly clear in the definition of non-success
scenarios.

XEP-0050 Section 3.6 "Commands Successful/Failed" defines:

...
  The status of command execution signals only if the
command is executing,
 has been completed, or been canceled. If completed, the "status" attribute
 does not specify if it completed successfully or not. If a command
 completes but fails, the responder MUST include at least one <note
 type='error'/> with the <command status='completed'/> it
returns. 

I do not believe that XEP-0050 specifies what the IQ type is (result or
error) when a command execution is completed with a failure.

XEP-0050 Section 4.4 "Possible Errors" defines command execution errors.
All of the descriptions listed relate to conditions where the responding
entity is prevented from starting to execute the command: it doesn't
understand the action, the requesting entity doesn't have permissions to
execute the command, and so on.

In example 23, it is shown that these type of errors are used in an IQ
type=error.

XEP-0133 is less clear. Where errors are referenced in the descriptions of
each command ("Unless an error occurs ...") they also seem to refer to
scenario's where a command execution cannot start. To me, that's in line
with XEP-0050. However, section 5 "Error Handling" specifies conditions
that seem to are detected both _before_ but also _after_ execution of the
command has started. Examples of that latter are:

   - <conflict/> The command cannot be completed because of a data or
   system conflict (e.g., a user already exists with that username).
   - No entity is allowed to perform the command (e.g., retrieve the CEO's
   roster).

To me, these two are examples of what should be responded to with a
<command status='completed'><note
type='error'/></command>.

The XEP(s) would benefit from having more explicit definitions with regards
to these cases.

Firstly, lets specify explicitly in XEP-0050 if a command of which the
execution completed with an error is to be represented by an IQ stanza of
type 'result' or 'error'. The XEP to me suggests 'result', but I
don't
think this is sufficiently clear from the text. For what it's worth, the
implementations that I've seen (Openfire, Smack and Prosody), seem to use
'result'.

Secondly, Section 5 of XEP-0133 arguably contradicts XEP-0050 - or at least
adds confusion more than clarification. What added value does this section
have over the error handling that is specified in XEP-0050? Perhaps
referring to XEP-0133 is a good alternative to the existence of Section 5
in XEP-0133.

Thirdly, the XEPs should have an example of a command that is
completed-with-failure. The illustrative power of that would be very
welcome.

I would value your feedback on this.

Kind regards,

  Guus