falconry / falcon

The no-magic web data plane API and microservices framework for Python developers, with a focus on reliability, correctness, and performance at scale.
https://falcon.readthedocs.io/en/stable/
Apache License 2.0
9.53k stars 944 forks source link

Document how resp is affected by raising `HTTPError`/`HTTPStatus` #2221

Open vytas7 opened 7 months ago

vytas7 commented 7 months ago

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 commented 7 months ago

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

onecrayon commented 7 months ago

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 commented 7 months ago

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