[sipcore] Reason as a parameter rather than an escaped header

["Worley, Dale R (Dale)" <[e-mail]>]

First, I don't like the term "an escaped header".  The escaping
process is not central, what is central is that the "header" (per 3261
BNF terminology) is "added to" or "inserted into" the URI.

From: Paul Kyzivat [[e-mail]]
> On 11/7/2010 6:39 PM, Mary Barnes wrote:
> > I think there is still some confusion here - the Reason is NOT a URI
> > parameter. It is a SIP header field that is escaped in the URI for
> > compactness.
> 
> I don't think there is any real confusion. Its just that the terminology
> is awkward. We have parameters to headers, and we have headers that are
> parameters to URIs.

The BNF in RFC 3261 calls these things "headers":

    SIP-URI          =  "sip:" [ userinfo ] hostport
			uri-parameters [ headers ]
    headers         =  "?" header *( "&" header )
    header          =  hname "=" hvalue

In our organization, we call them "header parameters", contrasted to
"URI parameters" ("uri-parameters" per 3261) and "field parameters"
(which has no proper name in 3261, but its syntax is "generic-param").
These phrases are used in the prose of 3261 with these meanings
(usually).

> > In earlier versions, we had a separate parameter in the
> > SIP History-Info header for Reason, but Rohan suggested to just escape
> > the existing Reason header in the URI so as not to redefine Reason
> > parameters.
> 
> I even remember him making that suggestion. Too bad he isn't around so
> we can wring his neck. I thought it was a hack at the time, but didn't
> then realize how much trouble it would cause.

Certainly, doing so is conceptually incorrect, as the reason is a
property of the request-URI that was used, not a portion of that
request-URI.  Fortunately, no operational failure can result, as the
request-URI of a request cannot contain header parameters.

But it looks like we need to continue this hack for compatibility.  So let us:
- publicly state this is a hack
- not repeat the mistake in other cases

> > The Reason header is intended to tag the Reason why the hi-targeted-to
> > URI was retargeted and thus it goes with the "old" hi-entry versus the
> > "new" one.
> 
> Just stating it that was exposes the problem.
> The intent of the Reason header is specified in RFC3326.
> Any use that isn't consistent with that is an abuse.
> Its intended to indicate why a *request* is being sent.

Yes, but it quickly mutated into a carrier in responses to provide
additional information as to why the response was generated.
Consider:

   draft-jesske-dispatch-reason-in-responses-02

   Abstract

   Although the use of the Reason header field in responses is
   considered in RFC3326, doing so is not specified for any existing
   response code.  Nonetheless, the Reason header field has been widely
   used in responses to carry Q.850 reason codes for failure responses
   to INVITEs that have been gatewayed to PSTN systems.  This document
   specifies and formally permits the use of the Reason header field in
   SIP responses to carry Q.850 reason codes for this and other
   purposes.

> > Also, note that we cannot change this now even if it were the right
> > thing to do due to backwards compatibility.
> 
> So then we allow it continue to metastasize, e.g. by defining new Reason
> values that aren't ever expected to be used in requests, and that
> wouldn't make any sense if they were?

That seems likely.  It's probably a good thing.  It's a bit sketchy to use
the same header to describe why a request was generated and also why
a response was generated, but it's not going to cause confusion.

Dale