Subject: [Stox] STOX Error Condition/Response code translation

From: "De Vries, Michael [USA]" <[email-masked]>
Date: Mon, 15 Jul 2013 16:36:17 +0000

Hello Everyone,

The draft-ietf-stox-core-00 document specifies mappings between XMPP error conditions and SIP response codes, but does not specify any requirements/recommendations for handling the SIP "Reason-Phrase" in the "Status-Line" header or the XMPP <text/> entry in the <error/> block.  According to the SIP and XMPP RFCs, the Reason-Phrase and <error/> block appear to effectively serve the same purpose in conveying additional error information intended for the human user, so a direct translation between the two (when present) seems reasonable to me.  

Additionally, this could potentially help to distinguish errors which are currently mapped down from many possibilities into a single entry, such as SIP response codes 413-423 (and others) all being mapped to the <bad-request/> XMPP Error Condition, assuming that the SIP responses provide a Reason-Phrase.  Additionally, it may even be possible to provide the additional distinguishing information in the XMPP <text/> block even if the SIP response does not contain a Reason-Phrase for direct translation.

For example:  Assume the XMPP-SIP gateway receives a SIP 415 response code (Unsupported Media Type) in response to some gateway-mediated action between an XMPP user and SIP user. As per the draft-ieftf-stox-core-00 document, this response code should be translated and sent to the XMPP user effectively as:

  <error type='modify'>
    <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>

If this 415 response contains a Reason-Phrase (though it does not appear to be mandated as per RFC3261), then the gateway could instead send to the XMPP user:

  <error type='modify'>
    <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <text xml:lang='en' xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>
      [ ... Reason-Phrase translated here ... ]
    </text>
  </error>

Additionally, if this 415 response does not contain a Reason-Phrase, then the gateway could send the following to the XMPP user as a means of distinguishing from other <bad-request/> errors:

  <error type='modify'>
    <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <text xml:lang='en' xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>
      Unsupported Media Type
    </text>
  </error>

Similarly, a 416 response (Unsupported URI Scheme) without a Reason-Phrase could be translated into:

  <error type='modify'>
    <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <text xml:lang='en' xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>
      Unsupported URI Scheme
    </text>
  </error>

thus distinguishing between the 415 and 416 responses for the XMPP human user, but effectively requiring some textual injection into the message stream by the gateway which would need to be specified in the document.  That said, as these fields are all optional and not related to actual SIP/XMPP application-level handling of messages, there is no reason that the XMPP-SIP gateway must perform such a translation, but I figured it might be worth exploring in this discussion group.

Thanks,
--Mike DeVries

---

From: Peter Saint-Andre <[email-masked]>
Date: Wed, 17 Jul 2013 21:23:21 -0600

Hi Mike, thank you very much for the feedback!

On 7/15/13 10:36 AM, De Vries, Michael [USA] wrote:
> Hello Everyone,
> 
> The draft-ietf-stox-core-00 document specifies mappings between XMPP
> error conditions and SIP response codes, but does not specify any
> requirements/recommendations for handling the SIP "Reason-Phrase" in
> the "Status-Line" header or the XMPP <text/> entry in the <error/>
> block.  According to the SIP and XMPP RFCs, the Reason-Phrase and
> <error/> block appear to effectively serve the same purpose in
> conveying additional error information intended for the human user,
> so a direct translation between the two (when present) seems
> reasonable to me.

RFC 3261 says (Section 7.2):

   The Status-Code is a 3-digit integer result code that indicates the
   outcome of an attempt to understand and satisfy a request.  The
   Reason-Phrase is intended to give a short textual description of the
   Status-Code.  The Status-Code is intended for use by automata,
   whereas the Reason-Phrase is intended for the human user.  A client
   is not required to examine or display the Reason-Phrase.

And RFC 6120 says (Section 8.3.2):

   The <text/> element is OPTIONAL.  If included, it is to be used only
   to provide descriptive or diagnostic information that supplements the
   meaning of a defined condition or application-specific condition.  It
   MUST NOT be interpreted programmatically by an application.  It
   SHOULD NOT be used as the error message presented to a human user,
   but MAY be shown in addition to the error message associated with the
   defined condition element (and, optionally, the application-specific
   condition element).

Despite the caveat about clients not directly copying the <text/>
element and using it as the error message shown to a user, I tend to
agree that they are mostly equivalent and can reasonably be mapped to
each other for interworking purposes.

> Additionally, this could potentially help to distinguish errors which
> are currently mapped down from many possibilities into a single
> entry, such as SIP response codes 413-423 (and others) all being
> mapped to the <bad-request/> XMPP Error Condition, assuming that the
> SIP responses provide a Reason-Phrase.  Additionally, it may even be
> possible to provide the additional distinguishing information in the
> XMPP <text/> block even if the SIP response does not contain a
> Reason-Phrase for direct translation.
> 
> For example:  Assume the XMPP-SIP gateway receives a SIP 415 response
> code (Unsupported Media Type) in response to some gateway-mediated
> action between an XMPP user and SIP user. As per the
> draft-ieftf-stox-core-00 document, this response code should be
> translated and sent to the XMPP user effectively as:
> 
> <error type='modify'> <bad-request
> xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> </error>
> 
> 
> If this 415 response contains a Reason-Phrase (though it does not
> appear to be mandated as per RFC3261), then the gateway could instead
> send to the XMPP user:
> 
> <error type='modify'> <bad-request
> xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> <text xml:lang='en'
> xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'> [ ... Reason-Phrase
> translated here ... ] </text> </error>
> 
> 
> Additionally, if this 415 response does not contain a Reason-Phrase,
> then the gateway could send the following to the XMPP user as a means
> of distinguishing from other <bad-request/> errors:
> 
> <error type='modify'> <bad-request
> xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> <text xml:lang='en'
> xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'> Unsupported Media Type 
> </text> </error>
> 
> 
> <error type='modify'> <bad-request
> xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> <text xml:lang='en'
> xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'> Unsupported URI Scheme 
> </text> </error>
> 
> 
> thus distinguishing between the 415 and 416 responses for the XMPP
> human user, but effectively requiring some textual injection into the
> message stream by the gateway which would need to be specified in the
> document.  That said, as these fields are all optional and not
> related to actual SIP/XMPP application-level handling of messages,
> there is no reason that the XMPP-SIP gateway must perform such a
> translation, but I figured it might be worth exploring in this
> discussion group.

IMHO your proposal is reasonable as suggested behavior, although I don't
think it rises to the level of a MUST or SHOULD requirement.

I will look into it further and propose some text on the list.

Peter

-- 
Peter Saint-Andre
https://stpeter.im/