refine streaming response headers and docs

Author: michalsn

system/HTTP/ResponseTrait.php

@@ -394,7 +394,7 @@ public function send()
      * need it avoids the cost of constructing a 1000+ line service on every
      * request.
      */
-    private function shouldFinalizeCsp(): bool
+    protected function shouldFinalizeCsp(): bool
     {
         // Developer already touched CSP through getCSP(); respect it.
         if ($this->CSP !== null) {

system/HTTP/SSEResponse.php

@@ -124,12 +124,22 @@ protected function prepareStreamHeaders(): void
         $this->setContentType('text/event-stream', 'UTF-8');
         $this->removeHeader('Cache-Control');
         $this->setHeader('Cache-Control', 'no-cache');
-        $this->setHeader('Content-Encoding', 'identity');
         $this->setHeader('X-Accel-Buffering', 'no');
 
         // Connection: keep-alive is only valid for HTTP/1.x
         if (version_compare($this->getProtocolVersion(), '2.0', '<')) {
             $this->setHeader('Connection', 'keep-alive');
         }
     }
+
+    /**
+     * {@inheritDoc}
+     *
+     * CSP is not finalized for SSE responses, as Content Security
+     * Policy does not apply to event streams.
+     */
+    protected function shouldFinalizeCsp(): bool
+    {
+        return false;
+    }
 }

system/HTTP/StreamResponse.php

@@ -123,7 +123,13 @@ public function send()
 
         $this->prepareStreamHeaders();
 
-        // Intentionally skip CSP finalize: the body is streamed, not buffered HTML.
+        // Give CSP a chance to build its headers. Nonce placeholders cannot be
+        // replaced in a streamed body; call getCSP()->getScriptNonce() or
+        // getStyleNonce() before returning the response instead.
+        if ($this->shouldFinalizeCsp()) {
+            $this->getCSP()->finalize($this);
+        }
+
         $this->sendHeaders();
         $this->sendCookies();
 
@@ -141,10 +147,6 @@ protected function prepareStreamHeaders(): void
         if (! $this->hasHeader('X-Accel-Buffering')) {
             $this->setHeader('X-Accel-Buffering', 'no');
         }
-
-        if (! $this->hasHeader('Content-Encoding')) {
-            $this->setHeader('Content-Encoding', 'identity');
-        }
     }
 
     /**

tests/system/HTTP/StreamResponseSendTest.php

@@ -14,6 +14,7 @@
 namespace CodeIgniter\HTTP;
 
 use CodeIgniter\Test\CIUnitTestCase;
+use Config\App;
 use Generator;
 use PHPUnit\Framework\Attributes\Group;
 use PHPUnit\Framework\Attributes\PreserveGlobalState;
@@ -44,7 +45,7 @@ public function testSendEmitsHeadersCookiesAndStream(): void
 
         $this->assertSame('Hello World', $output);
         $this->assertHeaderEmitted('X-Accel-Buffering: no');
-        $this->assertHeaderEmitted('Content-Encoding: identity');
+        $this->assertHeaderNotEmitted('Content-Encoding:');
         $this->assertHeaderEmitted('Set-Cookie: foo=bar;');
     }
 
@@ -121,4 +122,50 @@ public function testSendEmitsCustomStatusCode(): void
 
         $this->assertSame(202, http_response_code());
     }
+
+    /**
+     * This test does not test that CSP is handled properly -
+     * it makes sure that sending gives CSP a chance to do its thing.
+     */
+    #[PreserveGlobalState(false)]
+    #[RunInSeparateProcess]
+    #[WithoutErrorHandler]
+    public function testSendEmitsCspHeaderWhenEnabled(): void
+    {
+        $this->resetFactories();
+        $this->resetServices();
+
+        config(App::class)->CSPEnabled = true;
+
+        $response = new StreamResponse(static function (): void {
+        });
+        $response->pretend(false);
+
+        ob_start();
+        $response->send();
+        ob_end_clean();
+
+        $this->assertHeaderEmitted('Content-Security-Policy:');
+    }
+
+    #[PreserveGlobalState(false)]
+    #[RunInSeparateProcess]
+    #[WithoutErrorHandler]
+    public function testSendSkipsCspHeaderForSSE(): void
+    {
+        $this->resetFactories();
+        $this->resetServices();
+
+        config(App::class)->CSPEnabled = true;
+
+        $response = new SSEResponse(static function (): void {
+        });
+        $response->pretend(false);
+
+        ob_start();
+        $response->send();
+        ob_end_clean();
+
+        $this->assertHeaderNotEmitted('Content-Security-Policy:');
+    }
 }

user_guide_src/source/outgoing/response.rst

@@ -252,7 +252,12 @@ The callback receives the ``StreamResponse`` instance. ``StreamResponse::write()
 returns ``false`` once the client has disconnected, so you can stop producing
 output early. By default, every ``write()`` flushes output to the client
 immediately. When writing many small chunks, pass ``false`` as the second
-argument and call ``StreamResponse::flush()`` at intervals instead.
+argument and call ``StreamResponse::flush()`` at intervals instead - the
+example above flushes once per batch.
+
+The callback is not limited to ``write()``: you may also write directly to
+``php://output`` (for example, with ``fputcsv()`` for CSV exports), calling
+``flush()`` and ``StreamResponse::isClientConnected()`` yourself.
 
 Alternatively, you may pass an iterable of string chunks (such as a generator),
 and each chunk is written and flushed in order:
@@ -264,16 +269,25 @@ Headers and Status Code
 
 Set the content type, status code, and any custom headers **before** returning
 the response - anything set inside the callback will be too late. Unless you
-have already set them, ``StreamResponse`` applies ``X-Accel-Buffering: no`` and
-``Content-Encoding: identity`` to discourage intermediaries from buffering or
-compressing the stream.
+have already set it, ``StreamResponse`` applies ``X-Accel-Buffering: no`` to
+discourage intermediaries from buffering the stream. PHP's zlib output
+compression is turned off automatically, but if your web server or CDN
+compresses responses (e.g., nginx ``gzip`` or Apache ``mod_deflate``), configure
+it to skip your streaming endpoints - compression can delay chunk delivery.
 
 The response is streamed: output buffering is disabled, the PHP time limit is
 removed, and the session is closed to avoid blocking other requests. After
 filters still run and may set headers, but they must not rely on the response
 body. View rendering and decorators are not applied - stream your output in
 the callback.
 
+If :doc:`Content Security Policy </outgoing/csp>` is enabled, the
+``Content-Security-Policy`` header is sent as usual. However, nonce
+placeholders cannot be replaced in a streamed body. When streaming HTML that
+needs a nonce, call ``$this->response->getCSP()->getScriptNonce()`` (or
+``getStyleNonce()``) **before** returning the response and embed the returned
+value in your output yourself.
+
 ``StreamResponse`` does not set a ``Content-Length`` header by default, since
 the body length is typically unknown in advance. Without it, clients cannot
 display download progress or resume interrupted transfers. If you do know the
@@ -369,9 +383,9 @@ Production Considerations
 Some server stacks and CDNs buffer or compress responses (e.g., Apache with
 ``mod_deflate``), which can break real-time SSE delivery.
 ``SSEResponse`` disables PHP output buffering, turns off zlib output
-compression, and sets ``Content-Encoding: identity`` and ``X-Accel-Buffering: no``.
-However, intermediaries may still buffer or compress, so configure your web server
-or CDN to disable buffering/compression for SSE endpoints.
+compression, and sets ``X-Accel-Buffering: no``. However, intermediaries may
+still buffer or compress, so configure your web server or CDN to disable
+buffering/compression for SSE endpoints.
 
 Example: Product-Oriented Use Case
 ----------------------------------

user_guide_src/source/outgoing/response/039.php

@@ -2,13 +2,24 @@
 
 use CodeIgniter\HTTP\StreamResponse;
 
-return $this->response->stream(static function (StreamResponse $stream) {
-    $stream->write("id,email\n");
+return $this->response
+    ->stream(static function (StreamResponse $stream) {
+        $userModel = model('UserModel');
+        $offset    = 0;
 
-    foreach (model('UserModel')->findAll() as $user) {
-        // write() returns false when the client disconnects
-        if (! $stream->write("{$user->id},{$user->email}\n")) {
-            break;
+        // Fetch rows in batches to keep memory usage low
+        while ($users = $userModel->findAll(500, $offset)) {
+            foreach ($users as $user) {
+                // write() returns false once the client has disconnected
+                if (! $stream->write(json_encode($user) . "\n", false)) {
+                    return;
+                }
+            }
+
+            // Push the whole batch to the client at once
+            $stream->flush();
+
+            $offset += 500;
         }
-    }
-});
+    })
+    ->setContentType('application/x-ndjson');

user_guide_src/source/outgoing/response/041.php

@@ -1,11 +1,18 @@
 <?php
 
+use CodeIgniter\Exceptions\PageNotFoundException;
 use CodeIgniter\HTTP\StreamResponse;
 
-$stream = $this->response->stream(static function (StreamResponse $stream) {
-    // Forward the upstream file chunk by chunk, without buffering it in memory
-    $source = fopen('https://storage.internal/reports/annual.pdf', 'rb');
+// Open and validate the upstream source before creating the response,
+// so a failure can still produce a proper error page
+$source = @fopen('https://storage.internal/reports/annual.pdf', 'rb');
+
+if ($source === false) {
+    throw PageNotFoundException::forPageNotFound();
+}
 
+$stream = $this->response->stream(static function (StreamResponse $stream) use ($source) {
+    // Forward the upstream file chunk by chunk, without buffering it in memory
     try {
         while (! feof($source)) {
             $chunk = fread($source, 1_048_576);