feat(cloudflare): add experimental support for static headers #13959

Johannes-Andersen · 2025-06-17T20:19:19Z

Changes

This is my first ever change to astro. So I am not sure this is the correct way. Therefore a more thorough review may be required.

The PR aims to implement the experimental CSP policy to the cloudflare adapter.

Mainly copied work from: de82ef2

Testing

Added tests. Existing tests should still pass.

Validate CF docs if output matches.

Example output:

/has-header
  cdn-cache-control: public, max-age=3600
  Content-Security-Policy: script-src 'self' 'sha256-BF0290pkb3jxQsE7z00xR8Imp8X34FLC88L0lkMnrGw=' 'sha256-QzWFZi+FLIx23tnm9SBU4aEgx4x8DsuASP07mfqol/c=' 'sha256-0chmwFk0zaA528yFfGV7J9ppIpdfTPPULncDF3WG7Zs=' 'sha256-eIXWvAmxkr251LJZkjniEK5LcPF3NkapbJepohwYRIc=' 'sha256-Q2BPg90ZMplYY+FSdApNErhpWafg2hcRRbndmvxuL/Q=' 'sha256-0oe0j1+KVmVYcHm1N1/3tGTf3Yhpnd6heIyJsO4LZS0=' 'sha256-Yfb49Tdgb3WWkhZG+Levy7SSbIwvHj9bEqvunWdMcuU='; style-src 'self' 'sha256-2sYicASgHviyvFSsZfd8xuNIhA0b8XasqB2neZePwjs=';

/parent/*/page
  Content-Security-Policy: script-src 'self' 'sha256-BF0290pkb3jxQsE7z00xR8Imp8X34FLC88L0lkMnrGw=' 'sha256-QzWFZi+FLIx23tnm9SBU4aEgx4x8DsuASP07mfqol/c=' 'sha256-0chmwFk0zaA528yFfGV7J9ppIpdfTPPULncDF3WG7Zs=' 'sha256-eIXWvAmxkr251LJZkjniEK5LcPF3NkapbJepohwYRIc=' 'sha256-Q2BPg90ZMplYY+FSdApNErhpWafg2hcRRbndmvxuL/Q=' 'sha256-0oe0j1+KVmVYcHm1N1/3tGTf3Yhpnd6heIyJsO4LZS0=' 'sha256-ByjyHeCbp9JwIvEz5gjdoP7siW4JyclCitgVszsv3/A='; style-src 'self' 'sha256-2sYicASgHviyvFSsZfd8xuNIhA0b8XasqB2neZePwjs=';

/
  Content-Security-Policy: script-src 'self' 'sha256-BF0290pkb3jxQsE7z00xR8Imp8X34FLC88L0lkMnrGw=' 'sha256-QzWFZi+FLIx23tnm9SBU4aEgx4x8DsuASP07mfqol/c=' 'sha256-0chmwFk0zaA528yFfGV7J9ppIpdfTPPULncDF3WG7Zs=' 'sha256-eIXWvAmxkr251LJZkjniEK5LcPF3NkapbJepohwYRIc=' 'sha256-Q2BPg90ZMplYY+FSdApNErhpWafg2hcRRbndmvxuL/Q=' 'sha256-0oe0j1+KVmVYcHm1N1/3tGTf3Yhpnd6heIyJsO4LZS0=' 'sha256-v10nX5cSfrpnBaKOp54plCw0M1DSmiPyeQyg//eGOnA='; style-src 'self' 'sha256-2sYicASgHviyvFSsZfd8xuNIhA0b8XasqB2neZePwjs=';

/*
  Content-Security-Policy: script-src 'self' 'sha256-BF0290pkb3jxQsE7z00xR8Imp8X34FLC88L0lkMnrGw=' 'sha256-QzWFZi+FLIx23tnm9SBU4aEgx4x8DsuASP07mfqol/c=' 'sha256-0chmwFk0zaA528yFfGV7J9ppIpdfTPPULncDF3WG7Zs=' 'sha256-eIXWvAmxkr251LJZkjniEK5LcPF3NkapbJepohwYRIc=' 'sha256-Q2BPg90ZMplYY+FSdApNErhpWafg2hcRRbndmvxuL/Q=' 'sha256-0oe0j1+KVmVYcHm1N1/3tGTf3Yhpnd6heIyJsO4LZS0=' 'sha256-84Lsggi8q1VFTLi2blghehwqNiFOYysZSnNhkaidDMk='; style-src 'self' 'sha256-2sYicASgHviyvFSsZfd8xuNIhA0b8XasqB2neZePwjs=';

Docs

Docs needs to be added, todo based on feedback.

changeset-bot · 2025-06-17T20:19:24Z

🦋 Changeset detected

Latest commit: a9ba349

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

ascorbic

Thanks for this. I'm going to ask @ematipico for a review as he's the one who's working on this feature, but it looks good from my perspective.

ematipico

Thank you @Johannes-Andersen for your first contribution! I left some comments. I spotted some bugs, and asked a few questions.

One important thing that we have to address is to add use cases. Let me know if there's something that isn't clear.

packages/integrations/cloudflare/src/utils/generate-headers-file.ts

ematipico · 2025-06-18T10:47:42Z

packages/integrations/cloudflare/src/utils/generate-headers-file.ts

+		for (const line of raw.split(/\r?\n/)) {
+			if (!line.trim()) continue;
+			if (!/^\s/.test(line)) {
+				currentPattern = line.trim();
+				headersByPattern.set(currentPattern, headersByPattern.get(currentPattern) || {});
+			} else {
+				const [name, ...rest] = line.trim().split(':');
+				headersByPattern.get(currentPattern)![name.trim()] = rest.join(':').trim();
+			}
+		}


This is the first time that this adapter is in charge of _headers, which means that Astro owns its contents every time it is generated. In fact, its relative is loaded from outDir, instead of publicDir.

If the assumption is correct, it means that we don't need to read its contents, because they are generated anew at every build.

EDIT: I see that the tests use the public directory, which means that the code needs to be updated to use publicDir configuration. Also, I am fine to have this behaviour different from Netlify, at the end, it's up to the adapter how to use the feature. We need to make sure to:

update the documentation of the adapter, and explain that when experimentalStaticHeaders is enabled, Astro will update public/_headers

add more tests

As I understand it, right now a user could create a _headers file in public and it would work. We want to be able to not break these sites, so it makes sense to update the file in outDir (merging the user headers with the added ones) and leave the one in public untouched.

Yeah that makes sense!

ematipico · 2025-06-18T10:50:38Z

packages/integrations/cloudflare/src/utils/generate-headers-file.ts

+			const csp = heads.get('Content-Security-Policy');
+			if (!csp) continue;
+
+			const pattern = segmentsToCfSyntax(route.segments, config);


Out of curiosity, is there a reason why you didn't use createHostRouteDefinition like we do in Netlify?

astro/packages/integrations/netlify/src/index.ts

Line 146 in 304df34

const definition = createHostedRouteDefinition(route, config);

The logic behind it has already been used for the _redirects file in Cloudflare, which means that it's battle-tested, and it provides all the information to create the correct Unix-like paths.

ematipico · 2025-06-18T11:00:40Z

packages/integrations/cloudflare/test/fixtures/static-headers/public/_headers

+/has-header
+  cdn-cache-control: public, max-age=3600


Now that the adapter reads this file and updates it, we need to ensure that we join routes correctly. Which means that if this file specifies a route e.g. /server-island with some headers, and Astro emits the CSP header for this very route, the final file should contain both headers.

Can we add few more tests that cover more Astro routes:

static routes e.g. src/pages/server-island.astro

dynamic routes e.g. src/pages/posts/[slug].astro

catch all route e.g. src/pages/blog/[...catchAll].astro

And have few routes in _headers that match some of those routes and make sure they all have all headers merged.

/server-island cdn-cache-control: public, max-age=3600 /posts/intro cdn-cache-control: public, max-age=3600 /blog/hello-word cdn-cache-control: public, max-age=3600

I agree, I would add some more built-in routes to the tests

@alexanderniebuhr I tried adding more. Would love to hear what more routes you would like tested :D

Johannes-Andersen · 2025-06-18T14:49:38Z

Thank you @Johannes-Andersen for your first contribution! I left some comments. I spotted some bugs, and asked a few questions.

One important thing that we have to address is to add use cases. Let me know if there's something that isn't clear.

Thanks for the review! The feedback you left makes sense! I'll have a go at fixing them tomorrow. A bit busy today ☺️

ematipico

Thank you for addressing my comments! I tried to merge main again, because some tests were failing and I don't know why

ematipico · 2025-06-29T04:09:55Z

@Johannes-Andersen we are in the process of changing the payload, so we're holding off merging the PR. However, in the meantime, can you please address the CI failures?

ematipico · 2025-07-01T08:56:04Z

@Johannes-Andersen heads-up that this PR #13972 is going to change how we generate the static headers for the page

alexanderniebuhr · 2025-07-01T18:36:51Z

I will also review this tomorrow :)

packages/integrations/cloudflare/src/index.ts

alexanderniebuhr · 2025-07-02T05:40:29Z

packages/integrations/cloudflare/src/utils/generate-headers-file.ts

+	const output =
+		[...headersByPattern]
+			.map(([pattern, headers]) =>
+				[pattern, ...Object.entries(headers).map(([k, v]) => `  ${k}: ${v}`)].join('\n'),
+			)
+			.join('\n\n') + '\n';


Don't we have a shared util from astro for this?

Be aware that this PR #13972 will change headersByPattern, so we will probably have to update this code.

Nonetheless, we have @astrojs/underscore-redirects that might provide something we can use here, but you should look into it

Yeah I was thinking about printAsRedirects from @astrojs/underscore-redirects, but I'm not sure if the syntax is 100% equal

alexanderniebuhr · 2025-07-02T05:41:23Z

packages/integrations/cloudflare/src/utils/generate-headers-file.ts

+async function loadExistingHeaders(publicUrl: URL): Promise<Map<string, Record<string, string>>> {
+	try {
+		const text = await readFile(publicUrl, 'utf-8');
+		return text
+			.split(/\r?\n/)
+			.filter(Boolean)
+			.reduce(
+				(map, line) => {
+					if (!line.startsWith(' ')) {
+						map.current = line.trim();
+						map.store.set(map.current, map.store.get(map.current) ?? {});
+					} else {
+						const [key, ...rest] = line.trim().split(':');
+						map.store.get(map.current)![key.trim()] = rest.join(':').trim();
+					}
+					return map;
+				},
+				{ current: '', store: new Map<string, Record<string, string>>() },
+			).store;
+	} catch {
+		return new Map();
+	}
+}


Good for now, but in the long term I think we should also have this shared from astro, I feel like this could also apply to other providers not just Cloudflare. WDYT @ematipico?

I'm not sure we can. Each adapter (i.e., hosting platform) has its own configuration file, with its own syntax. For example, with Netlify we use their config.json file. With the Node.js adapter, we created a custom JSON file with a different structure

Interesting, I thought the _headers file is a common syntax, than disregard my comment.

I think the _headers file is a kinda-common syntax. I think it's generally supported in the same places that support _redirects, so there is a good argument for adding support in that package. We don't use it on Netlify now, as we use their new framework API. On Netlify at least, the _headers file is now mainly created by users rather than auto-generated by frameworks.

sarah11918

Just fixing a quick changeset nit!

.changeset/eight-regions-tease.md

Co-authored-by: Sarah Rainsberger <[email protected]>

sarah11918 · 2025-07-02T11:08:37Z

For docs, noting that an accompanying docs PR should add experimentalStaticHeaders as an option in this section of the Cloudflare adapter guide (https://docs.astro.build/en/guides/integrations-guide/cloudflare/#options)

(By the time this merges, there should already be something similar written for the Node, Netlify, and Vercel adapters, so you can basically copy from them.)

florian-lefebvre · 2025-09-16T14:17:21Z

@Johannes-Andersen Hi! Are you still interested in this PR?

Johannes-Andersen · 2025-09-17T07:51:07Z

@Johannes-Andersen Hi! Are you still interested in this PR?

Got a bit much happening in life and at work at the moment 😅
So while I still would like to finish this up, I currently do not have the capacity

florian-lefebvre · 2025-09-17T08:03:44Z

No problem, thanks for opening the PR in the first place!

feat(cloudflare): add experimental support for static headers

b84628e

github-actions bot added the pkg: integration Related to any renderer integration (scope) label Jun 17, 2025

fix: nitpicks

314b14d

ascorbic approved these changes Jun 18, 2025

View reviewed changes

ascorbic requested a review from ematipico June 18, 2025 08:25

ematipico requested changes Jun 18, 2025

View reviewed changes

Johannes-Andersen and others added 2 commits June 19, 2025 22:32

Merge branch 'main' into feat/cloudflareStaticHeaders

45bbfba

fix: address code review comments

0667f93

Johannes-Andersen force-pushed the feat/cloudflareStaticHeaders branch from c5a5ff8 to 0667f93 Compare June 19, 2025 21:45

Johannes-Andersen and others added 2 commits June 23, 2025 10:49

Merge branch 'main' into feat/cloudflareStaticHeaders

fa3259e

Merge branch 'main' into feat/cloudflareStaticHeaders

8c44d35

ematipico approved these changes Jun 23, 2025

View reviewed changes

Johannes-Andersen added 2 commits June 24, 2025 09:14

Merge branch 'main' into feat/cloudflareStaticHeaders

0ffa508

Merge branch 'main' into feat/cloudflareStaticHeaders

c4964f3

alexanderniebuhr self-requested a review July 1, 2025 18:36

alexanderniebuhr reviewed Jul 2, 2025

View reviewed changes

packages/integrations/cloudflare/src/index.ts Show resolved Hide resolved

alexanderniebuhr reviewed Jul 2, 2025

View reviewed changes

Johannes-Andersen and others added 3 commits July 2, 2025 10:38

Merge branch 'main' into feat/cloudflareStaticHeaders

faa63df

docs: move worker before pages docs

e6552a9

chore: attempt to fix tests

3fdcd82

sarah11918 reviewed Jul 2, 2025

View reviewed changes

.changeset/eight-regions-tease.md Outdated Show resolved Hide resolved

Update .changeset/eight-regions-tease.md

a9ba349

Co-authored-by: Sarah Rainsberger <[email protected]>

Johannes-Andersen closed this Sep 17, 2025

Uh oh!

feat(cloudflare): add experimental support for static headers #13959

feat(cloudflare): add experimental support for static headers #13959

Uh oh!

Conversation

Johannes-Andersen commented Jun 17, 2025

Changes

Testing

Docs

Uh oh!

changeset-bot bot commented Jun 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

ascorbic left a comment

Choose a reason for hiding this comment

Uh oh!

ematipico left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

ematipico Jun 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Johannes-Andersen commented Jun 18, 2025

Uh oh!

ematipico left a comment

Choose a reason for hiding this comment

Uh oh!

ematipico commented Jun 29, 2025

Uh oh!

ematipico commented Jul 1, 2025

Uh oh!

alexanderniebuhr commented Jul 1, 2025

Uh oh!

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!

alexanderniebuhr Jul 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sarah11918 commented Jul 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

florian-lefebvre commented Sep 16, 2025

Uh oh!

Johannes-Andersen commented Sep 17, 2025

Uh oh!

florian-lefebvre commented Sep 17, 2025

Uh oh!

Reviewers

changeset-bot bot commented Jun 17, 2025 •

edited

Loading

ematipico Jun 18, 2025 •

edited

Loading

alexanderniebuhr Jul 2, 2025 •

edited

Loading

sarah11918 commented Jul 2, 2025 •

edited

Loading