Document how resp is affected by raising HTTPError/HTTPStatus

[vytas7]

As pointed out by @onecrayon on Gitter, at the time of writing, it is not very clear what happens with data attributes/headers/cookies already set on resp in the case an instance of HTTPError or HTTPStatus is raised.

The correct answer for the 3.x series is that resp.data, .text, .media, etc are reset, but headers and cookies persist unless they are overwritten by headers passed into HTTPError.

Another undocumented surprise is that passing Set-Cookie in headers will bubble up an unhandled falcon.errors.HeaderNotSupported to the app server.

See also: #1752.

[vytas7]

TBD: do we need any code changes here, or is clearly documenting the current behaviour good enough?

[onecrayon]

Clear documentation would be sufficient for my needs, personally, but mainly because I still want to send cookies along with redirects. I could also see an argument for the redirects using a completely new response, though, because it’s two lines to explicitly send a redirect while maintaining the response otherwise (set the status, set the header).

[CaselIT]

If we were to implement #1752 also for http status/error it would be feasible to add an attribute to them called override_request that means "discard everything in request and use things only from this object".

The default would be False to keep the current behaviour