fix(@angular/ssr): enable serving of prerendered pages in the App Engine

alan-agius4 · alan-agius4 · commit d0402ac57b56 · 2024-10-29T14:19:59.000Z
This commit implements the capability for the App Engine to serve prerendered pages directly. Previously, we relied on frameworks like Express for this functionality, which resulted in inconsistent redirects for the root path (`/`).

**Note:** This change applies only when using the new SSR APIs. When using the `CommonEngine`, a 3rd party static serve middleware is still required.
diff --git a/packages/angular/build/src/builders/application/execute-post-bundle.ts b/packages/angular/build/src/builders/application/execute-post-bundle.ts
@@ -175,13 +175,15 @@ export async function executePostBundleSteps(
       switch (metadata.renderMode) {
         case RouteRenderMode.Prerender:
         case /* Legacy building mode */ undefined: {
-          if (!metadata.redirectTo || outputMode === OutputMode.Static) {
+          if (!metadata.redirectTo) {
+            serializableRouteTreeNodeForManifest.push(metadata);
             prerenderedRoutes[metadata.route] = { headers: metadata.headers };
           }
           break;
         }
         case RouteRenderMode.Server:
         case RouteRenderMode.Client:
+        case RouteRenderMode.AppShell:
           serializableRouteTreeNodeForManifest.push(metadata);
 
           break;
diff --git a/packages/angular/build/src/utils/server-rendering/manifest.ts b/packages/angular/build/src/utils/server-rendering/manifest.ts
@@ -135,11 +135,7 @@ export function generateAngularServerAppManifest(
 ): string {
   const serverAssetsContent: string[] = [];
   for (const file of [...additionalHtmlOutputFiles.values(), ...outputFiles]) {
-    if (
-      file.path === INDEX_HTML_SERVER ||
-      file.path === INDEX_HTML_CSR ||
-      (inlineCriticalCss && file.path.endsWith('.css'))
-    ) {
+    if (file.path.endsWith('.html') || (inlineCriticalCss && file.path.endsWith('.css'))) {
       serverAssetsContent.push(`['${file.path}', async () => \`${escapeUnsafeChars(file.text)}\`]`);
     }
   }
diff --git a/packages/angular/ssr/node/src/app-engine.ts b/packages/angular/ssr/node/src/app-engine.ts
@@ -43,30 +43,40 @@ export class AngularNodeAppEngine {
   }
 
   /**
-   * Retrieves HTTP headers for a request associated with statically generated (SSG) pages,
-   * based on the URL pathname.
+   * Serves a prerendered page for a given request.
    *
-   * @param request - The incoming request object.
-   * @returns A `Map` containing the HTTP headers as key-value pairs.
-   * @note This function should be used exclusively for retrieving headers of SSG pages.
-   * @example
-   * ```typescript
-   * const angularAppEngine = new AngularNodeAppEngine();
+   * This method examines the incoming request to determine if it corresponds to a known prerendered page.
+   * If a matching page is found, it returns a `Response` object containing the page content; otherwise, it returns `null`.
    *
-   * app.use(express.static('dist/browser', {
-   *   setHeaders: (res, path) => {
-   *     // Retrieve headers for the current request
-   *     const headers = angularAppEngine.getPrerenderHeaders(res.req);
+   * @param request - The incoming HTTP request for a prerendered page.
+   * @returns A promise that resolves to a `Response` object containing the prerendered page content, or `null`
+   * if no matching page is found.
+   */
+  servePrerendered(request: IncomingMessage): Promise<Response | null> {
+    return this.angularAppEngine.servePrerendered(createWebRequestFromNodeRequest(request));
+  }
+
+  /**
+   * Handles incoming HTTP requests by serving prerendered content or rendering the page.
    *
-   *     // Apply the retrieved headers to the response
-   *     for (const [key, value] of headers) {
-   *       res.setHeader(key, value);
-   *     }
-   *   }
-     }));
-  * ```
-  */
-  getPrerenderHeaders(request: IncomingMessage): ReadonlyMap<string, string> {
-    return this.angularAppEngine.getPrerenderHeaders(createWebRequestFromNodeRequest(request));
+   * This method first attempts to serve a prerendered page. If the prerendered page is not available,
+   * it falls back to rendering the requested page using server-side rendering. The function returns
+   * a promise that resolves to the appropriate HTTP response.
+   *
+   * @param request - The incoming HTTP request for a prerendered page.
+   * @param requestContext - Optional additional context for rendering, such as request metadata.
+   * @returns A promise that resolves to the HTTP response object resulting from the request handling,
+   * or null if no matching content is found.
+   */
+  async serveOrRender(
+    request: IncomingMessage,
+    requestContext?: unknown,
+  ): Promise<Response | null> {
+    const webRequest = createWebRequestFromNodeRequest(request);
+
+    return (
+      (await this.angularAppEngine.servePrerendered(webRequest)) ??
+      (await this.angularAppEngine.render(webRequest, requestContext))
+    );
   }
 }
diff --git a/packages/angular/ssr/src/app-engine.ts b/packages/angular/ssr/src/app-engine.ts
@@ -68,6 +68,63 @@ export class AngularAppEngine {
    * rather than an application route.
    */
   async render(request: Request, requestContext?: unknown): Promise<Response | null> {
+    const serverApp = await this.getAngularServerAppForRequest(request);
+
+    return serverApp ? serverApp.render(request, requestContext) : null;
+  }
+
+  /**
+   * Serves a prerendered page for a given request.
+   *
+   * This method examines the incoming request to determine if it corresponds to a known prerendered page.
+   * If a matching page is found, it returns a `Response` object containing the page content; otherwise, it returns `null`.
+   *
+   * @param request - The incoming HTTP request object to be rendered.
+   * @returns A promise that resolves to a `Response` object containing the prerendered page content, or `null`
+   * if no matching page is found.
+   **/
+  async servePrerendered(request: Request): Promise<Response | null> {
+    const serverApp = await this.getAngularServerAppForRequest(request);
+
+    return serverApp ? serverApp.servePrerendered(request) : null;
+  }
+
+  /**
+   * Handles incoming HTTP requests by serving prerendered content or rendering the page.
+   *
+   * This method first attempts to serve a prerendered page. If the prerendered page is not available,
+   * it falls back to rendering the requested page using server-side rendering. The function returns
+   * a promise that resolves to the appropriate HTTP response.
+   *
+   * @param request - The incoming HTTP request to be processed.
+   * @param requestContext - Optional additional context for rendering, such as request metadata.
+   * @returns A promise that resolves to the HTTP response object resulting from the request handling,
+   * or null if no matching content is found.
+   */
+  async serveOrRender(request: Request, requestContext?: unknown): Promise<Response | null> {
+    const serverApp = await this.getAngularServerAppForRequest(request);
+    if (!serverApp) {
+      return null;
+    }
+
+    return (
+      (await serverApp.servePrerendered(request)) ??
+      (await serverApp.render(request, requestContext))
+    );
+  }
+
+  /**
+   * Retrieves the Angular server application instance for a given request.
+   *
+   * This method checks if the request URL corresponds to an Angular application entry point.
+   * If so, it initializes or retrieves an instance of the Angular server application for that entry point.
+   * Requests that resemble file requests (except for `/index.html`) are skipped.
+   *
+   * @param request - The incoming HTTP request object.
+   * @returns A promise that resolves to an `AngularServerApp` instance if a valid entry point is found,
+   * or `null` if no entry point matches the request URL.
+   */
+  private async getAngularServerAppForRequest(request: Request): Promise<AngularServerApp | null> {
     // Skip if the request looks like a file but not `/index.html`.
     const url = new URL(request.url);
     const entryPoint = await this.getEntryPointExportsForUrl(url);
@@ -82,26 +139,7 @@ export class AngularAppEngine {
     const serverApp = getOrCreateAngularServerApp() as AngularServerApp;
     serverApp.hooks = this.hooks;
 
-    return serverApp.render(request, requestContext);
-  }
-
-  /**
-   * Retrieves HTTP headers for a request associated with statically generated (SSG) pages,
-   * based on the URL pathname.
-   *
-   * @param request - The incoming request object.
-   * @returns A `Map` containing the HTTP headers as key-value pairs.
-   * @note This function should be used exclusively for retrieving headers of SSG pages.
-   */
-  getPrerenderHeaders(request: Request): ReadonlyMap<string, string> {
-    if (this.manifest.staticPathsHeaders.size === 0) {
-      return new Map();
-    }
-
-    const { pathname } = stripIndexHtmlFromURL(new URL(request.url));
-    const headers = this.manifest.staticPathsHeaders.get(stripTrailingSlash(pathname));
-
-    return new Map(headers);
+    return serverApp;
   }
 
   /**
diff --git a/packages/angular/ssr/src/app.ts b/packages/angular/ssr/src/app.ts
@@ -17,6 +17,7 @@ import { sha256 } from './utils/crypto';
 import { InlineCriticalCssProcessor } from './utils/inline-critical-css';
 import { LRUCache } from './utils/lru-cache';
 import { AngularBootstrap, renderAngular } from './utils/ng';
+import { joinUrlParts, stripIndexHtmlFromURL, stripLeadingSlash } from './utils/url';
 
 /**
  * Maximum number of critical CSS entries the cache can store.
@@ -124,6 +125,66 @@ export class AngularServerApp {
     ]);
   }
 
+  /**
+   * Serves a static, prerendered page for the incoming request if available.
+   *
+   * This method attempts to match the incoming request URL with a prerendered route in the application.
+   * If the route is found and is configured for prerendering, the corresponding static asset is retrieved
+   * and returned as a `Response` object with the appropriate HTTP headers.
+   *
+   * @param request - The incoming HTTP request for a potential static page.
+   * @returns A promise that resolves to a `Response` object containing the prerendered page content
+   * if available, or `null` if the request does not match a prerendered route or asset.
+   */
+  async servePrerendered(request: Request): Promise<Response | null> {
+    const url = stripIndexHtmlFromURL(new URL(request.url));
+    this.router ??= await ServerRouter.from(this.manifest, url);
+
+    const matchedRoute = this.router.match(new URL(request.url));
+    if (!matchedRoute) {
+      return null;
+    }
+
+    const { headers, renderMode } = matchedRoute;
+    if (renderMode !== RenderMode.Prerender) {
+      return null;
+    }
+
+    const assetPath = stripLeadingSlash(joinUrlParts(url.pathname, 'index.html'));
+    if (!this.assets.hasServerAsset(assetPath)) {
+      return null;
+    }
+
+    // TODO(alanagius): handle etags
+
+    const content = await this.assets.getServerAsset(assetPath);
+
+    return new Response(content, {
+      headers: {
+        'Content-Type': 'text/html;charset=UTF-8',
+        // 30 days in seconds
+        'Cache-Control': `max-age=${30 * 24 * 60 * 60}`,
+        ...headers,
+      },
+    });
+  }
+
+  /**
+   * Handles incoming HTTP requests by serving prerendered content or rendering the page.
+   *
+   * This method first attempts to serve a prerendered page. If the prerendered page is not available,
+   * it falls back to rendering the requested page using server-side rendering. The function returns
+   * a promise that resolves to the appropriate HTTP response.
+   *
+   * @param request - The incoming HTTP request to be processed.
+   * @param requestContext - Optional additional context for rendering, such as request metadata.
+   * @returns A promise that resolves to the HTTP response object resulting from the request handling,
+   * or null if no matching content is found.
+   */
+  async serveOrRender(request: Request, requestContext?: unknown): Promise<Response | null> {
+    return (await this.servePrerendered(request)) ?? (await this.render(request, requestContext));
+  }
+
   /**
    * Creates a promise that rejects when the request is aborted.
    *
diff --git a/packages/angular/ssr/src/assets.ts b/packages/angular/ssr/src/assets.ts
@@ -35,6 +35,16 @@ export class ServerAssets {
     return asset();
   }
 
+  /**
+   * Checks if a specific server-side asset exists.
+   *
+   * @param path - The path to the server asset.
+   * @returns A boolean indicating whether the asset exists.
+   */
+  hasServerAsset(path: string): boolean {
+    return this.manifest.assets.has(path);
+  }
+
   /**
    * Retrieves and caches the content of 'index.server.html'.
    *
diff --git a/packages/angular/ssr/src/manifest.ts b/packages/angular/ssr/src/manifest.ts
@@ -43,19 +43,6 @@ export interface AngularAppEngineManifest {
    * This is used to determine the root path of the application.
    */
   readonly basePath: string;
-
-  /**
-   * A map that associates static paths with their corresponding HTTP headers.
-   * Each entry in the map consists of:
-   * - `key`: The static path as a string.
-   * - `value`: An array of tuples, where each tuple contains:
-   *   - `headerName`: The name of the HTTP header.
-   *   - `headerValue`: The value of the HTTP header.
-   */
-  readonly staticPathsHeaders: ReadonlyMap<
-    string,
-    readonly [headerName: string, headerValue: string][]
-  >;
 }
 
 /**
diff --git a/packages/angular/ssr/test/app-engine_spec.ts b/packages/angular/ssr/test/app-engine_spec.ts
@@ -53,15 +53,6 @@ describe('AngularAppEngine', () => {
           ]),
         ),
         basePath: '',
-        staticPathsHeaders: new Map([
-          [
-            '/about',
-            [
-              ['Cache-Control', 'no-cache'],
-              ['X-Some-Header', 'value'],
-            ],
-          ],
-        ]),
       });
 
       appEngine = new AngularAppEngine();
@@ -104,32 +95,6 @@ describe('AngularAppEngine', () => {
         expect(response).toBeNull();
       });
     });
-
-    describe('getPrerenderHeaders', () => {
-      it('should return headers for a known path without index.html', () => {
-        const request = new Request('https://example.com/about');
-        const headers = appEngine.getPrerenderHeaders(request);
-        expect(Object.fromEntries(headers.entries())).toEqual({
-          'Cache-Control': 'no-cache',
-          'X-Some-Header': 'value',
-        });
-      });
-
-      it('should return headers for a known path with index.html', () => {
-        const request = new Request('https://example.com/about/index.html');
-        const headers = appEngine.getPrerenderHeaders(request);
-        expect(Object.fromEntries(headers.entries())).toEqual({
-          'Cache-Control': 'no-cache',
-          'X-Some-Header': 'value',
-        });
-      });
-
-      it('should return no headers for unknown paths', () => {
-        const request = new Request('https://example.com/unknown/path');
-        const headers = appEngine.getPrerenderHeaders(request);
-        expect(headers).toHaveSize(0);
-      });
-    });
   });
 
   describe('Non-localized app', () => {
@@ -161,7 +126,6 @@ describe('AngularAppEngine', () => {
           ],
         ]),
         basePath: '',
-        staticPathsHeaders: new Map(),
       });
 
       appEngine = new AngularAppEngine();
diff --git a/packages/angular/ssr/test/app_spec.ts b/packages/angular/ssr/test/app_spec.ts
diff --git a/packages/angular/ssr/test/testing-utils.ts b/packages/angular/ssr/test/testing-utils.ts
diff --git a/packages/schematics/angular/ssr/files/application-builder/server.ts.template b/packages/schematics/angular/ssr/files/application-builder/server.ts.template

Original file line number	Diff line number	Diff line change
`@@ -135,11 +135,7 @@ export function generateAngularServerAppManifest(`
`135`	`135`	`): string {`
`136`	`136`	`const serverAssetsContent: string[] = [];`
`137`	`137`	`for (const file of [...additionalHtmlOutputFiles.values(), ...outputFiles]) {`
`138`		`- if (`
`139`		`- file.path === INDEX_HTML_SERVER \|\|`
`140`		`- file.path === INDEX_HTML_CSR \|\|`
`141`		`- (inlineCriticalCss && file.path.endsWith('.css'))`
`142`		`- ) {`
	`138`	`+ if (file.path.endsWith('.html') \|\| (inlineCriticalCss && file.path.endsWith('.css'))) {`
`143`	`139`	serverAssetsContent.push(`['${file.path}', async () => \`${escapeUnsafeChars(file.text)}\`]`);
`144`	`140`	`}`
`145`	`141`	`}`