Allow to pass custom fetch for fetching pre-rendered errors (#13403)

* Allow to pass custom fetch for fetching pre-rendered errors

* Add changeset

* Update lockfile

* Update .changeset/big-hats-train.md

* Add JSDoc to the new param

* Commit suggested rephrase

* Change the suffix of the sentence

* Correct the test, it was using proper fetch signature, which is not actually what we need

* Add a more strict type to the error page path

* State explicitly that it's only 404 or 500

* Rephrase the JSdoc

* rename to `prerenderedErrorPageFetch`

* rename to `prerenderedErrorPageFetch`

* Update .changeset/big-hats-train.md

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

* update the changeset

* update tests

* Apply suggestions from code review

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

* Update .changeset/big-hats-train.md

Co-authored-by: Matt Kane <[email protected]>

---------

Co-authored-by: Matt Kane <[email protected]>
Co-authored-by: Emanuele Stoppa <[email protected]>
Co-authored-by: Sarah Rainsberger <[email protected]>

Author: 4 people

.changeset/big-hats-train.md

@@ -0,0 +1,29 @@
+---
+'astro': minor
+---
+
+Adds a new optional `prerenderedErrorPageFetch` option in the Adapter API to allow adapters to provide custom implementations for fetching prerendered error pages.
+
+Now, adapters can override the default `fetch()` behavior, for example when `fetch()` is unavailable or when you cannot call the server from itself.
+
+The following example provides a custom fetch for `500.html` and `404.html`, reading them from disk instead of performing an HTTP call:
+```js "prerenderedErrorPageFetch"
+return app.render(request, {
+  prerenderedErrorPageFetch: async (url: string): Promise<Response> => {
+    if (url.includes("/500")) {
+        const content = await fs.promises.readFile("500.html", "utf-8");
+        return new Response(content, {
+          status: 500,
+          headers: { "Content-Type": "text/html" },
+        });
+    }
+    const content = await fs.promises.readFile("404.html", "utf-8");
+      return new Response(content, {
+        status: 404,
+        headers: { "Content-Type": "text/html" },
+      });
+});
+```
+If no value is provided, Astro will fallback to its default behavior for fetching error pages.
+
+Read more about this feature in the [Adapter API reference](https://docs.astro.build/en/reference/adapter-reference/#prerenderederrorpagefetch).

packages/astro/src/core/app/index.ts

@@ -31,6 +31,15 @@ import { AppPipeline } from './pipeline.js';
 
 export { deserializeManifest } from './common.js';
 
+
+type ErrorPagePath = 
+  | `${string}/404`
+  | `${string}/500`
+  | `${string}/404/`
+  | `${string}/500/`
+  | `${string}404.html`
+  | `${string}500.html`;
+
 export interface RenderOptions {
 	/**
 	 * Whether to automatically add all cookies written by `Astro.cookie.set()` to the response headers.
@@ -55,6 +64,20 @@ export interface RenderOptions {
 	 */
 	locals?: object;
 
+	/**
+	 * A custom fetch function for retrieving prerendered pages - 404 or 500.
+	 *
+	 * If not provided, Astro will fallback to its default behavior for fetching error pages.
+	 *
+	 * When a dynamic route is matched but ultimately results in a 404, this function will be used
+	 * to fetch the prerendered 404 page if available. Similarly, it may be used to fetch a
+	 * prerendered 500 error page when necessary.
+	 *
+	 * @param {ErrorPagePath} url - The URL of the prerendered 404 or 500 error page to fetch.
+	 * @returns {Promise<Response>} A promise resolving to the prerendered response.
+	 */
+	prerenderedErrorPageFetch?: (url: ErrorPagePath) => Promise<Response>;
+
 	/**
 	 * **Advanced API**: you probably do not need to use this.
 	 *
@@ -77,6 +100,7 @@ export interface RenderErrorOptions {
 	 */
 	error?: unknown;
 	clientAddress: string | undefined;
+	prerenderedErrorPageFetch: (url: ErrorPagePath) => Promise<Response>;
 }
 
 export class App {
@@ -287,6 +311,7 @@ export class App {
 		let addCookieHeader: boolean | undefined;
 		const url = new URL(request.url);
 		const redirect = this.#redirectTrailingSlash(url.pathname);
+		const prerenderedErrorPageFetch = renderOptions?.prerenderedErrorPageFetch ?? fetch;
 
 		if (redirect !== url.pathname) {
 			const status = request.method === 'GET' ? 301 : 308;
@@ -323,7 +348,7 @@ export class App {
 			if (typeof locals !== 'object') {
 				const error = new AstroError(AstroErrorData.LocalsNotAnObject);
 				this.#logger.error(null, error.stack!);
-				return this.#renderError(request, { status: 500, error, clientAddress });
+				return this.#renderError(request, { status: 500, error, clientAddress, prerenderedErrorPageFetch: prerenderedErrorPageFetch, });
 			}
 		}
 		if (!routeData) {
@@ -342,7 +367,7 @@ export class App {
 		if (!routeData) {
 			this.#logger.debug('router', "Astro hasn't found routes that match " + request.url);
 			this.#logger.debug('router', "Here's the available routes:\n", this.#manifestData);
-			return this.#renderError(request, { locals, status: 404, clientAddress });
+			return this.#renderError(request, { locals, status: 404, clientAddress, prerenderedErrorPageFetch: prerenderedErrorPageFetch });
 		}
 		const pathname = this.#getPathnameFromRequest(request);
 		const defaultStatus = this.#getDefaultStatusCode(routeData, pathname);
@@ -366,7 +391,7 @@ export class App {
 			response = await renderContext.render(await mod.page());
 		} catch (err: any) {
 			this.#logger.error(null, err.stack || err.message || String(err));
-			return this.#renderError(request, { locals, status: 500, error: err, clientAddress });
+			return this.#renderError(request, { locals, status: 500, error: err, clientAddress, prerenderedErrorPageFetch: prerenderedErrorPageFetch });
 		} finally {
 			await session?.[PERSIST_SYMBOL]();
 		}
@@ -383,6 +408,7 @@ export class App {
 				// while undefined means there's no error
 				error: response.status === 500 ? null : undefined,
 				clientAddress,
+				prerenderedErrorPageFetch: prerenderedErrorPageFetch,
 			});
 		}
 
@@ -431,6 +457,7 @@ export class App {
 			skipMiddleware = false,
 			error,
 			clientAddress,
+			prerenderedErrorPageFetch,
 		}: RenderErrorOptions,
 	): Promise<Response> {
 		const errorRoutePath = `/${status}${this.#manifest.trailingSlash === 'always' ? '/' : ''}`;
@@ -444,7 +471,7 @@ export class App {
 					url,
 				);
 				if (statusURL.toString() !== request.url) {
-					const response = await fetch(statusURL.toString());
+					const response = await prerenderedErrorPageFetch(statusURL.toString() as ErrorPagePath);
 
 					// response for /404.html and 500.html is 200, which is not meaningful
 					// so we create an override
@@ -479,6 +506,7 @@ export class App {
 						response: originalResponse,
 						skipMiddleware: true,
 						clientAddress,
+						prerenderedErrorPageFetch,
 					});
 				}
 			} finally {

packages/astro/test/custom-fetch-error-pages.test.js

@@ -0,0 +1,92 @@
+import assert from 'node:assert/strict';
+import { before, describe, it, beforeEach } from 'node:test';
+import * as cheerio from 'cheerio';
+import testAdapter from './test-adapter.js';
+import { loadFixture } from './test-utils.js';
+
+describe('Custom Fetch for Error Pages', () => {
+  /** @type {import('./test-utils.js').Fixture} */
+  let fixture;
+  
+  before(async () => {
+    fixture = await loadFixture({
+      root: './fixtures/custom-fetch-error-pages/',
+      output: 'server',
+      adapter: testAdapter(),
+      build: { inlineStylesheets: 'never' },
+    });
+  });
+  
+  describe('Production', () => {
+    /** @type {import('./test-utils.js').App} */
+    let app;
+    
+    // Mock fetch calls for tracking
+    let fetchCalls = [];
+    const customFetch = async (url) => {
+      fetchCalls.push(url);
+      // Return a custom response to verify our fetch was used
+      return new Response('<html><body><h1>Custom Fetch Response</h1></body></html>', {
+        headers: {
+          'content-type': 'text/html',
+        },
+      });
+    };
+    
+    before(async () => {
+      await fixture.build({});
+      app = await fixture.loadTestAdapterApp();
+    });
+    
+    beforeEach(() => {
+      // Reset fetch calls before each test
+      fetchCalls = [];
+    });
+    
+    it('uses custom fetch implementation in case the server needs to get pre-rendered error 404 page when provided via preRenderedFetch', async () => {
+      const request = new Request('http://example.com/not-found');
+      const response = await app.render(request, { prerenderedErrorPageFetch: customFetch });
+      
+      // Verify the response comes from our custom fetch
+      assert.equal(response.status, 404);
+      
+      // Verify our custom fetch was called with the right URL
+      assert.equal(fetchCalls.length, 1);
+      assert.ok(fetchCalls[0].includes('/404'));
+
+      const html = await response.text();
+      const $ = cheerio.load(html);
+      assert.equal($('h1').text(), 'Custom Fetch Response');
+    });
+    
+    it('uses custom fetch implementation for 500 errors', async () => {
+      const request = new Request('http://example.com/causes-error');
+      const response = await app.render(request, { prerenderedErrorPageFetch: customFetch });
+      
+      // Verify the response comes from our custom fetch
+      assert.equal(response.status, 500);
+      
+      // Verify our custom fetch was called with the right URL
+      assert.equal(fetchCalls.length, 1);
+      assert.ok(fetchCalls[0].includes('/500'));
+      
+      const html = await response.text();
+      const $ = cheerio.load(html);
+      assert.equal($('h1').text(), 'Custom Fetch Response');
+    });
+    
+    it('falls back to global fetch when preRenderedFetch is not provided', async () => {
+      const request = new Request('http://example.com/not-found');
+      const response = await app.render(request);
+      
+      // Verify our custom fetch was NOT called
+      assert.equal(fetchCalls.length, 0);
+      
+      // Response should be the default 404 page
+      assert.equal(response.status, 404);
+      const html = await response.text();
+      const $ = cheerio.load(html);
+      assert.equal($('h1').text(), 'Example Domain'); // actual fetch requesting example.com and gets that.
+    });
+  });
+}); 

packages/astro/test/fixtures/custom-fetch-error-pages/astro.config.mjs

@@ -0,0 +1,5 @@
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  output: 'server',
+}); 

packages/astro/test/fixtures/custom-fetch-error-pages/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "custom-fetch-error-pages",
+  "version": "1.0.0",
+  "private": true,
+  "dependencies": {
+    "astro": "workspace:*"
+  }
+} 

packages/astro/test/fixtures/custom-fetch-error-pages/src/pages/404.astro

@@ -0,0 +1,9 @@
+---
+// This is the 404 page
+export const prerender = true;
+---
+<html>
+<body>
+  <h1>Something went horribly wrong!</h1>
+</body>
+</html> 

packages/astro/test/fixtures/custom-fetch-error-pages/src/pages/500.astro

@@ -0,0 +1,9 @@
+---
+// This is the 500 error page
+export const prerender = true;
+---
+<html>
+<body>
+  <h1>This is an error page</h1>
+</body>
+</html> 

packages/astro/test/fixtures/custom-fetch-error-pages/src/pages/[page].astro

@@ -0,0 +1,12 @@
+---
+const params = Astro.params;
+if (params.page && params.page.includes('not-found')) {
+    return new Response(null, { status: 404 });
+}
+---
+
+<html>
+<body>
+    <h1>{new Date()}</h1>
+</body>
+</html> 

packages/astro/test/fixtures/custom-fetch-error-pages/src/pages/causes-error.astro

@@ -0,0 +1,3 @@
+---
+throw new Error('Oops!');
+--- 

packages/astro/test/test-adapter.js

@@ -69,7 +69,7 @@ export default function ({
 													this.#manifest = manifest;
 												}
 
-												async render(request, { routeData, clientAddress, locals, addCookieHeader } = {}) {
+												async render(request, { routeData, clientAddress, locals, addCookieHeader, prerenderedErrorPageFetch } = {}) {
 													const url = new URL(request.url);
 													if(this.#manifest.assets.has(url.pathname)) {
 														const filePath = new URL('../../client/' + this.removeBase(url.pathname), import.meta.url);
@@ -82,7 +82,7 @@ export default function ({
 															? `request[Symbol.for('astro.clientAddress')] = clientAddress ?? '0.0.0.0';`
 															: ''
 													}
-													return super.render(request, { routeData, locals, addCookieHeader });
+													return super.render(request, { routeData, locals, addCookieHeader, prerenderedErrorPageFetch });
 												}
 											}