diff --git a/docs/patterns/streaming.rst b/docs/patterns/streaming.rst index ff356310..fc2f1739 100644 --- a/docs/patterns/streaming.rst +++ b/docs/patterns/streaming.rst @@ -8,6 +8,21 @@ roundtrip to the filesystem? The answer is by using generators and direct responses. +HTTP Response Behavior +---------------------- + +**Headers cannot be changed after the streaming response starts.** + +When using streaming, it's important to be aware of the order than an HTTP +response is sent. All headers must be sent first, then the body. More headers +cannot be sent after the body has begun. Therefore, you must make sure all +headers are set before starting the response, outside the generator. + +In particular, if the generator will access ``session``, be sure to do so in the +view as well so that the ``Vary: cookie`` header will be set. Do not modify the +session in the generator, as the ``Set-Cookie`` header will already be sent. + + Basic Usage ----------- diff --git a/docs/templating.rst b/docs/templating.rst index 9fa8dcdb..ed4a52ee 100644 --- a/docs/templating.rst +++ b/docs/templating.rst @@ -251,5 +251,11 @@ functions to make this easier to use. return stream_template("timeline.html") These functions automatically apply the -:func:`~flask.stream_with_context` wrapper if a request is active, so -that it remains available in the template. +:func:`~flask.stream_with_context` wrapper if a request is active, so that +:data:`.request`, :data:`.session`, and :data:`.g` remain available in the +template. + +More headers cannot be sent after the body has begun. Therefore, you must +make sure all headers are set before starting the response. In particular, +if the template will access ``session``, be sure to do so in the view as +well so that the ``Vary: cookie`` header will be set. diff --git a/src/flask/helpers.py b/src/flask/helpers.py index 8befe719..fb7f6eba 100644 --- a/src/flask/helpers.py +++ b/src/flask/helpers.py @@ -68,6 +68,18 @@ def stream_with_context( available, even though at the point the generator runs the request context will typically have ended. + .. warning:: + + Due to the following caveat, it is often safer to pass the data you + need as arguments to the generator, rather than relying on the context + objects. + + More headers cannot be sent after the body has begun. Therefore, you must + make sure all headers are set before starting the response. In particular, + if the generator will access ``session``, be sure to do so in the view as + well so that the ``Vary: cookie`` header will be set. Do not modify the + session in the generator, as the ``Set-Cookie`` header will already be sent. + Use it as a decorator on a generator function: .. code-block:: python