Keep the response headers of prerendered pages, and write them to a headers file by jnadaud · Pull Request #6 · bakslashHQ/static-site-bundle

jnadaud · 2026-10-21T12:38:51Z

Closes #2.

Built along the lines of your answer on the issue.

What changes

RenderedPage gains array $headers = [], holding every header of the response the page was rendered from, keyed by lowercase name as HeaderBag::all() gives them. Nothing is filtered there, so listeners can read X-Robots-Tag, Link or anything else. Redirect stubs carry none.
RenderedPage::withContent() returns a copy with other content, keeping the format and the headers. MinifyListener uses it, so minification no longer drops them, and so does the README's RewriteLinks example.
headers_file (default null) registers a listener that collects the headers on PageRenderedEvent and writes the file on GenerationFinishedEvent, from $event->uris. Only pages actually written get a rule. The listener runs at -512, after the minifier and user listeners.
- Filtering on write: a fixed list of headers that describe the page is written: CSP (and report-only), HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy, the three Cross-Origin-*, X-Robots-Tag and Link. Set-Cookie, Cache-Control, Vary, Date, ETag and the like never are. The list isn't configurable, as you suggested.
- Rule limit: the headers every page sends with the same value go into one /* rule, and a page only gets a rule of its own for what differs. A header whose value differs between pages is never put in /*, so no ! detaching or value joining is involved.
- Partial runs: the rules live between two comment markers. A --route/--path run reads the pages already listed there, updates its own, and lays everything out again, so /* stays right for the whole site. A page covered by /* alone is listed as a comment, so it isn't forgotten. Everything outside the markers (hand-written rules) is kept verbatim.
- Paths are the ones the host serves: base path included, <path>/ under clean_urls, and <path>.<format> for other formats. A value containing a line break is dropped, so it cannot forge another rule. A headers_file escaping the output (..) is rejected.
Docs: the headers in the Caddy and nginx examples; a "Security headers" section covering the file, the 100-rule layout, the GitHub Pages limits, and the two points below; the option in the configuration reference; CHANGELOG under "Unreleased".
- Nonce-based CSP: it is frozen at build time, so use hashes.
- Debug kernels: FrameworkBundle adds X-Robots-Tag: noindex when kernel.debug is on, so generating with --allow-debug writes it. The functional test caught this one.

Backward compatibility

Additive: existing new RenderedPage($content, $format) calls keep working, and nothing is written unless headers_file is set.

Tests

19 new tests:

renderer: all headers kept, redirects carry none;
minify listener: headers kept;
headers file:
- shared /* rule and per-path differences;
- differing values stay per path;
- filtering;
- served paths, including clean URLs and base path;
- partial run with hand-written rules kept;
- a /*-only page surviving a partial run;
- injected line breaks;
- nothing written when nothing was;
an end-to-end run with a real kernel, plus the configuration check.

composer test -- --fail-on-deprecation, composer stan and composer cs pass on PHP 8.5 with the highest dependencies, and the suite passes on PHP 8.3 with the lowest (Symfony 7.4, PHPUnit 12).

One choice to check with you: Link and X-Robots-Tag are in the written list, since they describe the page too. Happy to drop either if you'd rather leave them to a listener.

…eaders file RenderedPage keeps every header of the response it was rendered from, and withContent() carries them through listeners (minification included). With headers_file set, the headers that describe a page (CSP, HSTS, X-Robots-Tag, Link, ...) are written in the _headers format of Cloudflare Pages and Netlify: what all pages share in one /* rule, per-path rules only for what differs, and a filtered run merges with the pages already listed. Closes bakslashHQ#2

mtarld

I think we can make this simpler, mostly by dropping the merge on filtered runs I asked for in #2 (see inline). Plus, the /* rule turns out to be fragile on a real site: a redirect or a removed route is enough to lose it, and to go past the 100 rules on a large site.
Link and X-Robots-Tag in the written list are fine to me.

mtarld · 2026-10-21T15:43:02Z

+- `RenderedPage::$headers` keeps every header of the response a page was rendered from;
+  `RenderedPage::withContent()` returns a copy with other content, keeping the format and
+  the headers, and the minification listener uses it (#2).
+- `headers_file` writes the headers that describe each page (`Content-Security-Policy`,
+  `Strict-Transport-Security`, ...) in the `_headers` format of Cloudflare Pages and Netlify:
+  shared headers in one `/*` rule, merged with the existing file on filtered runs (#2).


Suggested change

- `RenderedPage::$headers` keeps every header of the response a page was rendered from;

`RenderedPage::withContent()` returns a copy with other content, keeping the format and

the headers, and the minification listener uses it (#2).

- `headers_file` writes the headers that describe each page (`Content-Security-Policy`,

`Strict-Transport-Security`, ...) in the `_headers` format of Cloudflare Pages and Netlify:

shared headers in one `/*` rule, merged with the existing file on filtered runs (#2).

- Keep the response headers of a rendered page in `RenderedPage::$headers`, and add

`RenderedPage::withContent()` (#2).

- Add a `headers_file` option, writing the page headers in the `_headers` format of

Cloudflare Pages and Netlify (#2).

mtarld · 2026-10-21T15:43:34Z

+    /**
+     * A copy carrying other content, keeping the format and the headers: what a listener
+     * transforming the markup should return.
+     */


Not needed.

mtarld · 2026-10-21T15:44:18Z

 Git integration's output directory at it. `_redirects` and `_headers` files placed in the
 output are honoured.

+### Security headers


I think this section can be way shorter: the config, the file example and the nonce note are enough IMO. The GitHub Pages paragraph is off topic, and the X-Robots-Tag note is expected when using --allow-debug.

mtarld · 2026-10-21T15:45:10Z

+                ->scalarNode('headers_file')
+                    ->info('Write the headers that describe each page (Content-Security-Policy, Strict-Transport-Security, ...) to this file of the output, in the "_headers" format of Cloudflare Pages and Netlify (e.g. "_headers"). Disabled when null.')
+                    ->defaultNull()
+                    ->validate()
+                        ->ifTrue(static fn (mixed $value): bool => \is_string($value) && ('' === trim($value, '/') || str_contains($value, '..')))
+                        ->thenInvalid('The headers file must be a path inside the output, got %s.')
+                    ->end()
+                ->end()


Suggested change

->scalarNode('headers_file')

->info('Write the headers that describe each page (Content-Security-Policy, Strict-Transport-Security, ...) to this file of the output, in the "_headers" format of Cloudflare Pages and Netlify (e.g. "_headers"). Disabled when null.')

->defaultNull()

->validate()

->ifTrue(static fn (mixed $value): bool => \is_string($value) && ('' === trim($value, '/') || str_contains($value, '..')))

->thenInvalid('The headers file must be a path inside the output, got %s.')

->end()

->end()

->scalarNode('headers_file')

->info('Write the headers that describe each page to this file of the output, in the "_headers" format of Cloudflare Pages and Netlify (e.g. "_headers"). Disabled when null.')

->defaultNull()

->end()

Flysystem's WhitespacePathNormalizer already throws PathTraversalDetected on .. and strips the leading / (same for the ltrim() below), so I think we can drop this validation and testRejectsAHeadersFileOutsideTheOutput. Plus, str_contains($value, '..') rejects foo..bar.

mtarld · 2026-10-21T15:46:46Z

+                ltrim($file, '/'),
+                $cleanUrls,
+            ])
+            ->addTag('kernel.event_listener', ['event' => PageRenderedEvent::class, 'method' => 'onPageRendered', 'priority' => -512])


The changes of a user listener registered below -512 are missed. What about decorating bakslash_static_site.dumper instead? dump() gets the final page, and the decorator only has to record it when the inner dumper doesn't throw, so no need to filter on $event->uris anymore.

mtarld · 2026-10-21T15:51:30Z

+    /**
+     * The URL the host serves the written file at: what its rules match against.
+     */
+    private function servedPath(string $uri, string $format): string


This duplicates the match of FlysystemDumper::dump(), so both will diverge at the first change. What about computing the written path in a single place, and deriving the served URL from it? It would fix /page.html as well, as Cloudflare Pages serves it at /page.

mtarld · 2026-10-21T15:52:13Z

+            default => $uri.'.'.$format,
+        };
+
+        return $this->siteContext->basePath().$path;


I'm not sure about the base path. Pages are written at the root of the output, so a host serving it (behind a proxy stripping /docs or not) receives /blog, never /docs/blog. And if the output is a subdirectory of a larger deployment, the _headers file is ignored, as it must be at the root.
Am I missing a case where the prefix matches?

mtarld · 2026-10-21T15:53:02Z

            ?? 'html';

-        return new RenderedPage($content, $format);
+        return new RenderedPage($content, $format, $this->headers($response));


Suggested change

return new RenderedPage($content, $format, $this->headers($response));

return new RenderedPage($content, $format, $response->headers->all());

null values end up as '' in written(), which already skips them, so headers() can go. The @param of RenderedPage::$headers then has to be list<string|null>, as HeaderBag::all() returns.

mtarld · 2026-10-21T15:53:35Z

+
+    public function testWritesTheHeadersOfThePagesToTheHeadersFile(): void
+    {
+        $kernel = $this->kernel = new HeadersFileKernel('test', true);


What about booting the kernel with debug: false? The test would then check what a real build writes, without the X-Robots-Tag coming from the debug mode.

mtarld · 2026-10-21T15:59:10Z

+     *
+     * @return list<string>
+     */
+    private static function layout(array $pages): array


AFAIK Cloudflare silently ignores the rules past the 100th, and nothing tells it here (150 pages with a different Link give 151 rules). Should we at least log a warning, or even throw?

jnadaud marked this pull request as ready for review October 21, 2026 12:43

jnadaud mentioned this pull request Oct 21, 2026

Response headers (CSP, HSTS, …) are dropped when a page is prerendered #2

Open

mtarld requested changes Oct 21, 2026

View reviewed changes

Navigation Menu

Repository navigation

Keep the response headers of prerendered pages, and write them to a headers file - #6

Keep the response headers of prerendered pages, and write them to a headers file#6
jnadaud wants to merge 1 commit into
bakslashHQ:mainfrom
jnadaud:keep-response-headers

jnadaud commented Oct 21, 2026

Uh oh!

mtarld left a comment

Uh oh!

mtarld Oct 21, 2026

Uh oh!

mtarld Oct 21, 2026

Uh oh!

mtarld Oct 21, 2026

Uh oh!

mtarld Oct 21, 2026

Uh oh!

mtarld Oct 21, 2026

Uh oh!

mtarld Oct 21, 2026

Uh oh!

mtarld Oct 21, 2026

Uh oh!

mtarld Oct 21, 2026

Uh oh!

mtarld Oct 21, 2026

Uh oh!

mtarld Oct 21, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	return new RenderedPage($content, $format, $this->headers($response));
	return new RenderedPage($content, $format, $response->headers->all());

Conversation

jnadaud commented Oct 21, 2026

Uh oh!

mtarld left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants