feat(@angular/ssr): Add getHeaders Method to AngularAppEngine and AngularNodeAppEngine for handling pages static headers

This commit introduces a new `getHeaders` method to the `AngularAppEngine` and `AngularNodeAppEngine` classes, designed to facilitate the retrieval of HTTP headers based on URL pathnames for statically generated (SSG) pages.

```typescript
const angularAppEngine = new AngularNodeAppEngine();

app.use(express.static('dist/browser', {
  setHeaders: (res, path) => {
    // Retrieve headers for the current request
    const headers = angularAppEngine.getHeaders(res.req);

    // Apply the retrieved headers to the response
    for (const { key, value } of headers) {
      res.setHeader(key, value);
    }
  }
}));
```

In this example, the `getHeaders` method is used within an Express application to dynamically set HTTP headers for static files. This ensures that appropriate headers are applied based on the specific request, enhancing the handling of SSG pages.

Author: alan-agius4

goldens/public-api/angular/ssr/index.api.md

@@ -6,6 +6,7 @@
 
 // @public
 export interface AngularServerAppManager {
+    getHeaders(request: Request): Readonly<Map<string, string>>;
     render(request: Request, requestContext?: unknown): Promise<Response | null>;
 }
 

goldens/public-api/angular/ssr/node/index.api.md

@@ -6,14 +6,14 @@
 
 import { ApplicationRef } from '@angular/core';
 import type { IncomingMessage } from 'node:http';
-import type { IncomingMessage as IncomingMessage_2 } from 'http';
 import type { ServerResponse } from 'node:http';
 import { StaticProvider } from '@angular/core';
 import { Type } from '@angular/core';
 
 // @public
 export interface AngularNodeServerAppManager {
-    render(request: Request | IncomingMessage_2, requestContext?: unknown): Promise<Response | null>;
+    getHeaders(request: IncomingMessage): Readonly<Map<string, string>>;
+    render(request: IncomingMessage, requestContext?: unknown): Promise<Response | null>;
 }
 
 // @public

packages/angular/ssr/node/src/app-engine.ts

@@ -6,8 +6,8 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import { ɵAngularAppEngine as AngularAppEngine } from '@angular/ssr';
-import type { IncomingMessage } from 'http';
+import { destroyAngularAppEngine, getOrCreateAngularAppEngine } from '@angular/ssr';
+import type { IncomingMessage } from 'node:http';
 import { createWebRequestFromNodeRequest } from './request';
 
 /**
@@ -27,42 +27,54 @@ export interface AngularNodeServerAppManager {
    * Example: A request to `https://www.example.com/page/index.html` will render the Angular route
    * associated with `https://www.example.com/page`.
    *
-   * @param request - The incoming HTTP request object to be rendered. It can be a `Request` or `IncomingMessage` object.
+   * @param request - The incoming HTTP request object to be rendered.
    * @param requestContext - Optional additional context for the request, such as metadata or custom settings.
    * @returns A promise that resolves to a `Response` object, or `null` if the request URL is for a static file
    * (e.g., `./logo.png`) rather than an application route.
    */
-  render(request: Request | IncomingMessage, requestContext?: unknown): Promise<Response | null>;
+  render(request: IncomingMessage, requestContext?: unknown): Promise<Response | null>;
+
+  /**
+   * 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.
+   * @example
+   * ```typescript
+   * const angularAppEngine = getOrCreateAngularNodeAppEngine();
+   *
+   * app.use(express.static('dist/browser', {
+   *   setHeaders: (res, path) => {
+   *     // Retrieve headers for the current request
+   *     const headers = angularAppEngine.getHeaders(res.req);
+   *
+   *     // Apply the retrieved headers to the response
+   *     for (const { key, value } of headers) {
+   *       res.setHeader(key, value);
+   *     }
+   *   }
+     }));
+  * ```
+  */
+  getHeaders(request: IncomingMessage): Readonly<Map<string, string>>;
 }
 
 /**
  * Angular server application engine.
  * Manages Angular server applications (including localized ones), handles rendering requests,
  * and optionally transforms index HTML before rendering.
  */
-export class AngularNodeAppEngine extends AngularAppEngine implements AngularNodeServerAppManager {
-  /**
-   * Renders an HTTP response based on the incoming request using the Angular server application.
-   *
-   * The method processes the incoming request, determines the appropriate route, and prepares the
-   * rendering context to generate a response. If the request URL corresponds to a static file (excluding `/index.html`),
-   * the method returns `null`.
-   *
-   * Example: A request to `https://www.example.com/page/index.html` will render the Angular route
-   * associated with `https://www.example.com/page`.
-   *
-   * @param request - The incoming HTTP request object to be rendered. It can be a `Request` or `IncomingMessage` object.
-   * @param requestContext - Optional additional context for the request, such as metadata or custom settings.
-   * @returns A promise that resolves to a `Response` object, or `null` if the request URL is for a static file
-   * (e.g., `./logo.png`) rather than an application route.
-   */
-  override render(
-    request: Request | IncomingMessage,
-    requestContext?: unknown,
-  ): Promise<Response | null> {
-    const webReq = request instanceof Request ? request : createWebRequestFromNodeRequest(request);
+class AngularNodeAppEngine implements AngularNodeServerAppManager {
+  private readonly angularAppEngine = getOrCreateAngularAppEngine();
+
+  render(request: IncomingMessage, requestContext?: unknown): Promise<Response | null> {
+    return this.angularAppEngine.render(createWebRequestFromNodeRequest(request), requestContext);
+  }
 
-    return super.render(webReq, requestContext);
+  getHeaders(request: IncomingMessage): Readonly<Map<string, string>> {
+    return this.angularAppEngine.getHeaders(createWebRequestFromNodeRequest(request));
   }
 }
 
@@ -92,4 +104,5 @@ export function getOrCreateAngularNodeAppEngine(): AngularNodeServerAppManager {
  */
 export function destroyAngularNodeAppEngine(): void {
   angularNodeAppEngine = undefined;
+  destroyAngularAppEngine();
 }

packages/angular/ssr/src/app-engine.ts

@@ -10,6 +10,7 @@ import type { AngularServerApp } from './app';
 import { Hooks } from './hooks';
 import { getPotentialLocaleIdFromUrl } from './i18n';
 import { EntryPointExports, getAngularAppEngineManifest } from './manifest';
+import { stripIndexHtmlFromURL } from './utils/url';
 
 /**
  * Angular server application engine.
@@ -34,12 +35,24 @@ export interface AngularServerAppManager {
    * rather than an application route.
    */
   render(request: Request, requestContext?: unknown): Promise<Response | null>;
+
+  /**
+   * 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.
+   */
+  getHeaders(request: Request): Readonly<Map<string, string>>;
 }
 
 /**
  * Angular server application engine.
  * Manages Angular server applications (including localized ones), handles rendering requests,
  * and optionally transforms index HTML before rendering.
+ *
+ * @developerPreview
  */
 export class AngularAppEngine implements AngularServerAppManager {
   /**
@@ -120,6 +133,25 @@ export class AngularAppEngine implements AngularServerAppManager {
 
     return entryPoints.get(potentialLocale);
   }
+
+  /**
+   * 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.
+   */
+  getHeaders(request: Request): Readonly<Map<string, string>> {
+    if (this.manifest.staticPathsHeaders.size === 0) {
+      return new Map();
+    }
+
+    const { pathname } = stripIndexHtmlFromURL(new URL(request.url));
+    const headers = this.manifest.staticPathsHeaders.get(pathname);
+
+    return new Map(headers);
+  }
 }
 
 let angularAppEngine: AngularAppEngine | undefined;

packages/angular/ssr/src/manifest.ts

@@ -43,6 +43,18 @@ 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: Readonly<
+    Map<string, readonly [headerName: string, headerValue: string][]>
+  >;
 }
 
 /**

packages/angular/ssr/src/routes/route-config.ts

@@ -0,0 +1,146 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import { EnvironmentProviders, InjectionToken, makeEnvironmentProviders } from '@angular/core';
+
+/**
+ * Different rendering modes for server routes.
+ * @developerPreview
+ */
+export enum RenderMode {
+  /** AppShell rendering mode, typically used for pre-rendered shells of the application. */
+  AppShell,
+
+  /** Server-Side Rendering (SSR) mode, where content is rendered on the server for each request. */
+  SSR,
+
+  /** Client-Side Rendering (CSR) mode, where content is rendered on the client side in the browser. */
+  CSR,
+
+  /** Static Site Generation (SSG) mode, where content is pre-rendered at build time and served as static files. */
+  SSG,
+}
+
+/**
+ * Fallback strategies for Static Site Generation (SSG) routes.
+ * @developerPreview
+ */
+export enum SSGFallback {
+  /** Use Server-Side Rendering (SSR) as the fallback for this route. */
+  SSR,
+
+  /** Use Client-Side Rendering (CSR) as the fallback for this route. */
+  CSR,
+
+  /** No fallback; Angular will not handle the response if the path is not pre-rendered. */
+  None,
+}
+
+/**
+ * Common interface for server routes, providing shared properties.
+ */
+export interface ServerRouteCommon {
+  /** The path associated with this route. */
+  path: string;
+
+  /** Optional additional headers to include in the response for this route. */
+  headers?: Record<string, string>;
+
+  /** Optional status code to return for this route. */
+  status?: number;
+}
+
+/**
+ * A server route that uses AppShell rendering mode.
+ */
+export interface ServerRouteAppShell extends Omit<ServerRouteCommon, 'headers' | 'status'> {
+  /** Specifies that the route uses AppShell rendering mode. */
+  renderMode: RenderMode.AppShell;
+}
+
+/**
+ * A server route that uses Client-Side Rendering (CSR) mode.
+ */
+export interface ServerRouteCSR extends ServerRouteCommon {
+  /** Specifies that the route uses Client-Side Rendering (CSR) mode. */
+  renderMode: RenderMode.CSR;
+}
+
+/**
+ * A server route that uses Static Site Generation (SSG) mode.
+ */
+export interface ServerRouteSSG extends Omit<ServerRouteCommon, 'status'> {
+  /** Specifies that the route uses Static Site Generation (SSG) mode. */
+  renderMode: RenderMode.SSG;
+
+  /**
+   * Optional fallback strategy to use if the SSG path is not pre-rendered.
+   * Defaults to `SSGFallback.SSR` if not provided.
+   */
+  fallback?: SSGFallback;
+  /**
+   * A function that returns a Promise resolving to an array of objects, each representing a route path with URL parameters.
+   * This function runs in the injector context, allowing access to Angular services and dependencies.
+   *
+   * @returns A Promise resolving to an array where each element is an object with string keys (representing URL parameter names)
+   * and string values (representing the corresponding values for those parameters in the route path).
+   *
+   * @example
+   * ```typescript
+   * export const serverRouteConfig: ServerRoutes[] = [
+   *   {
+   *     path: '/product/:id',
+   *     remderMode: RenderMode.SSG,
+   *     async getPrerenderPaths() {
+   *       const productService = inject(ProductService);
+   *       const ids = await productService.getIds(); // Assuming this returns ['1', '2', '3']
+   *
+   *       return ids.map(id => ({ id })); // Generates paths like: [{ id: '1' }, { id: '2' }, { id: '3' }]
+   *     },
+   *   },
+   * ];
+   * ```
+   */
+  getPrerenderPaths?: () => Promise<Record<string, string>[]>;
+}
+
+/**
+ * A server route that uses Server-Side Rendering (SSR) mode.
+ */
+export interface ServerRouteSSR extends ServerRouteCommon {
+  /** Specifies that the route uses Server-Side Rendering (SSR) mode. */
+  renderMode: RenderMode.SSR;
+}
+
+/**
+ * Server route configuration.
+ * @developerPreview
+ */
+export type ServerRoute = ServerRouteAppShell | ServerRouteCSR | ServerRouteSSG | ServerRouteSSR;
+
+/**
+ * Token for providing the server routes configuration.
+ * @internal
+ */
+export const SERVER_ROUTES_CONFIG = new InjectionToken<ServerRoute[]>('SERVER_ROUTES_CONFIG');
+
+/**
+ * Configures the necessary providers for server routes configuration.
+ *
+ * @param routes - An array of server routes to be provided.
+ * @returns An `EnvironmentProviders` object that contains the server routes configuration.
+ * @developerPreview
+ */
+export function provideServerRoutesConfig(routes: ServerRoute[]): EnvironmentProviders {
+  return makeEnvironmentProviders([
+    {
+      provide: SERVER_ROUTES_CONFIG,
+      useValue: routes,
+    },
+  ]);
+}

packages/angular/ssr/test/app-engine_spec.ts

@@ -47,45 +47,82 @@ describe('AngularAppEngine', () => {
           ]),
         ),
         basePath: '',
+        staticPathsHeaders: new Map([
+          [
+            '/about',
+            [
+              ['Cache-Control', 'no-cache'],
+              ['X-Some-Header', 'value'],
+            ],
+          ],
+        ]),
       });
 
       appEngine = new AngularAppEngine();
     });
 
-    it('should return null for requests to unknown pages', async () => {
-      const request = new Request('https://example.com/unknown/page');
-      const response = await appEngine.render(request);
-      expect(response).toBeNull();
-    });
+    describe('render', () => {
+      it('should return null for requests to unknown pages', async () => {
+        const request = new Request('https://example.com/unknown/page');
+        const response = await appEngine.render(request);
+        expect(response).toBeNull();
+      });
 
-    it('should return null for requests with unknown locales', async () => {
-      const request = new Request('https://example.com/es/home');
-      const response = await appEngine.render(request);
-      expect(response).toBeNull();
-    });
+      it('should return null for requests with unknown locales', async () => {
+        const request = new Request('https://example.com/es/home');
+        const response = await appEngine.render(request);
+        expect(response).toBeNull();
+      });
 
-    it('should return a rendered page with correct locale', async () => {
-      const request = new Request('https://example.com/it/home');
-      const response = await appEngine.render(request);
-      expect(await response?.text()).toContain('Home works IT');
-    });
+      it('should return a rendered page with correct locale', async () => {
+        const request = new Request('https://example.com/it/home');
+        const response = await appEngine.render(request);
+        expect(await response?.text()).toContain('Home works IT');
+      });
 
-    it('should correctly render the content when the URL ends with "index.html" with correct locale', async () => {
-      const request = new Request('https://example.com/it/home/index.html');
-      const response = await appEngine.render(request);
-      expect(await response?.text()).toContain('Home works IT');
-    });
+      it('should correctly render the content when the URL ends with "index.html" with correct locale', async () => {
+        const request = new Request('https://example.com/it/home/index.html');
+        const response = await appEngine.render(request);
+        expect(await response?.text()).toContain('Home works IT');
+      });
 
-    it('should return null for requests to unknown pages in a locale', async () => {
-      const request = new Request('https://example.com/it/unknown/page');
-      const response = await appEngine.render(request);
-      expect(response).toBeNull();
+      it('should return null for requests to unknown pages in a locale', async () => {
+        const request = new Request('https://example.com/it/unknown/page');
+        const response = await appEngine.render(request);
+        expect(response).toBeNull();
+      });
+
+      it('should return null for requests to file-like resources in a locale', async () => {
+        const request = new Request('https://example.com/it/logo.png');
+        const response = await appEngine.render(request);
+        expect(response).toBeNull();
+      });
     });
 
-    it('should return null for requests to file-like resources in a locale', async () => {
-      const request = new Request('https://example.com/it/logo.png');
-      const response = await appEngine.render(request);
-      expect(response).toBeNull();
+    describe('getHeaders', () => {
+      it('should return headers for a known path without index.html', () => {
+        const request = new Request('https://example.com/about');
+        const headers = appEngine.getHeaders(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.getHeaders(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.getHeaders(request);
+        expect(headers).toHaveSize(0);
+      });
     });
   });
 
@@ -115,6 +152,7 @@ describe('AngularAppEngine', () => {
           ],
         ]),
         basePath: '',
+        staticPathsHeaders: new Map(),
       });
 
       appEngine = new AngularAppEngine();