Merge remote-tracking branch 'origin/main' into next

6 files changed, 124 insertions, 2 deletions

diff --git a/packages/integrations/netlify/CHANGELOG.md b/packages/integrations/netlify/CHANGELOG.md
index a3ec39ce2..0d1e64302 100644
--- a/packages/integrations/netlify/CHANGELOG.md
+++ b/packages/integrations/netlify/CHANGELOG.md
@@ -106,6 +106,32 @@
   - astro@3.0.0-beta.0
   - @astrojs/underscore-redirects@0.3.0-beta.0
 
+## 2.6.0
+
+### Minor Changes
+
+- [#7975](https://github.com/withastro/astro/pull/7975) [`f974c95a2`](https://github.com/withastro/astro/commit/f974c95a27ccbf91adbc66f6f1433f4cf11be33e) Thanks [@lilnasy](https://github.com/lilnasy)! - If you are using Netlify's On-demand Builders, you can now specify how long your pages should remain cached. By default, all pages will be rendered on first visit and reused on every subsequent visit until a redeploy. To set a custom revalidation time, call the `runtime.setBuildersTtl()` local in either your frontmatter or middleware.
+
+  ```astro
+  ---
+  import Layout from '../components/Layout.astro';
+
+  if (import.meta.env.PROD) {
+    // revalidates every 45 seconds
+    Astro.locals.runtime.setBuildersTtl(45);
+  }
+  ---
+
+  <Layout title="Astro on Netlify">
+    {new Date(Date.now())}
+  </Layout>
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`1b8d30209`](https://github.com/withastro/astro/commit/1b8d3020990130dabfaaf753db73a32c6e0c896a), [`405913cdf`](https://github.com/withastro/astro/commit/405913cdf20b26407aa351c090f0a0859a4e6f54), [`87d4b1843`](https://github.com/withastro/astro/commit/87d4b18437c7565c48cad4bea81831c2a244ebb8), [`c23377caa`](https://github.com/withastro/astro/commit/c23377caafbc75deb91c33b9678c1b6868ad40ea), [`86bee2812`](https://github.com/withastro/astro/commit/86bee2812185df6e14025e5962a335f51853587b)]:
+  - astro@2.10.6
+
 ## 2.5.2
 
 ### Patch Changes
diff --git a/packages/integrations/netlify/README.md b/packages/integrations/netlify/README.md
index 91a0c41d8..8b652180b 100644
--- a/packages/integrations/netlify/README.md
+++ b/packages/integrations/netlify/README.md
@@ -144,6 +144,30 @@ Once you run `astro build` there will be a `dist/_redirects` file. Netlify will
 > **Note**
 > You can still include a `public/_redirects` file for manual redirects. Any redirects you specify in the redirects config are appended to the end of your own.
 
+### On-demand Builders
+
+[Netlify On-demand Builders](https://docs.netlify.com/configure-builds/on-demand-builders/) are serverless functions used to generate web content as needed that’s automatically cached on Netlify’s Edge CDN. You can enable these functions using the [`builders` configuration](#builders).
+
+By default, all pages will be rendered on first visit and the rendered result will be reused for every subsequent visit until you redeploy. To set a revalidation time, call the [`runtime.setBuildersTtl(ttl)` local](https://docs.astro.build/en/guides/middleware/#locals) with the duration (in seconds).
+
+The following example sets a revalidation time of 45, causing Netlify to store the rendered HTML for 45 seconds.
+
+```astro
+---
+import Layout from '../components/Layout.astro';
+
+if (import.meta.env.PROD) {
+  Astro.locals.runtime.setBuildersTtl(45);
+}
+---
+
+<Layout title="Astro on Netlify">
+  {new Date(Date.now())}
+</Layout>
+```
+
+It is important to note that On-demand Builders ignore query params when checking for cached pages. For example, if `example.com/?x=y` is cached, it will be served for `example.com/?a=b` (different query params) and `example.com/` (no query params) as well.
+
 ## Usage
 
 [Read the full deployment guide here.](https://docs.astro.build/en/guides/deploy/netlify/)
@@ -188,7 +212,7 @@ directory = "dist/functions"
 
 ### builders
 
-[Netlify On-demand Builders](https://docs.netlify.com/configure-builds/on-demand-builders/) are serverless functions used to build and cache page content on Netlify’s Edge CDN. You can enable these functions with the `builders` option:
+You can enable On-demand Builders using the `builders` option:
 
 ```js
 // astro.config.mjs
diff --git a/packages/integrations/netlify/builders-types.d.ts b/packages/integrations/netlify/builders-types.d.ts
new file mode 100644
index 000000000..7c778be4f
--- /dev/null
+++ b/packages/integrations/netlify/builders-types.d.ts
@@ -0,0 +1,9 @@
+interface NetlifyLocals {
+	runtime: {
+		/**
+		 * On-demand Builders support an optional time to live (TTL) pattern that allows you to set a fixed duration of time after which a cached builder response is invalidated. This allows you to force a refresh of a builder-generated response without a new deploy.
+		 * @param ttl time to live, in seconds
+		 */
+		setBuildersTtl(ttl: number): void;
+	};
+}
diff --git a/packages/integrations/netlify/src/netlify-functions.ts b/packages/integrations/netlify/src/netlify-functions.ts
index 3da0718b0..8c051d9f6 100644
--- a/packages/integrations/netlify/src/netlify-functions.ts
+++ b/packages/integrations/netlify/src/netlify-functions.ts
@@ -68,18 +68,32 @@ export const createExports = (manifest: SSRManifest, args: Args) => {
 			init.body =
 				typeof requestBody === 'string' ? Buffer.from(requestBody, encoding) : requestBody;
 		}
+
 		const request = new Request(rawUrl, init);
 
 		const routeData = app.match(request);
 		const ip = headers['x-nf-client-connection-ip'];
 		Reflect.set(request, clientAddressSymbol, ip);
-		let locals = {};
+
+		let locals: Record<string, unknown> = {};
+
 		if (request.headers.has(ASTRO_LOCALS_HEADER)) {
 			let localsAsString = request.headers.get(ASTRO_LOCALS_HEADER);
 			if (localsAsString) {
 				locals = JSON.parse(localsAsString);
 			}
 		}
+
+		let responseTtl = undefined;
+
+		locals.runtime = builders
+			? {
+					setBuildersTtl(ttl: number) {
+						responseTtl = ttl;
+					},
+			  }
+			: {};
+
 		const response: Response = await app.render(request, routeData, locals);
 		const responseHeaders = Object.fromEntries(response.headers.entries());
 
@@ -99,6 +113,7 @@ export const createExports = (manifest: SSRManifest, args: Args) => {
 			headers: responseHeaders,
 			body: responseBody,
 			isBase64Encoded: responseIsBase64Encoded,
+			ttl: responseTtl,
 		};
 
 		const cookies = response.headers.get('set-cookie');
diff --git a/packages/integrations/netlify/test/functions/builders.test.js b/packages/integrations/netlify/test/functions/builders.test.js
new file mode 100644
index 000000000..d47af92c0
--- /dev/null
+++ b/packages/integrations/netlify/test/functions/builders.test.js
@@ -0,0 +1,37 @@
+import { expect } from 'chai';
+import { loadFixture, testIntegration } from './test-utils.js';
+import netlifyAdapter from '../../dist/index.js';
+
+describe('Builders', () => {
+	/** @type {import('../../../astro/test/test-utils').Fixture} */
+	let fixture;
+
+	before(async () => {
+		fixture = await loadFixture({
+			root: new URL('./fixtures/builders/', import.meta.url).toString(),
+			output: 'server',
+			adapter: netlifyAdapter({
+				dist: new URL('./fixtures/builders/dist/', import.meta.url),
+				builders: true,
+			}),
+			site: `http://example.com`,
+			integrations: [testIntegration()],
+		});
+		await fixture.build();
+	});
+
+	it('A route can set builders ttl', async () => {
+		const entryURL = new URL(
+			'./fixtures/builders/.netlify/functions-internal/entry.mjs',
+			import.meta.url
+		);
+		const { handler } = await import(entryURL);
+		const resp = await handler({
+			httpMethod: 'GET',
+			headers: {},
+			rawUrl: 'http://example.com/',
+			isBase64Encoded: false,
+		});
+		expect(resp.ttl).to.equal(45);
+	});
+});
diff --git a/packages/integrations/netlify/test/functions/fixtures/builders/src/pages/index.astro b/packages/integrations/netlify/test/functions/fixtures/builders/src/pages/index.astro
new file mode 100644
index 000000000..ab8853785
--- /dev/null
+++ b/packages/integrations/netlify/test/functions/fixtures/builders/src/pages/index.astro
@@ -0,0 +1,11 @@
+---
+Astro.locals.runtime.setBuildersTtl(45)
+---
+<html>
+    <head>
+        <title>Astro on Netlify</title>
+    </head>
+    <body>
+        <h1>{new Date(Date.now())}</h1>
+    </body>
+</html>