feat(@angular/ssr): add server routing configuration API

This commit introduces a new server routing configuration API, as discussed in RFC angular/angular#56785. The new API provides several enhancements:

## Add headers and status code to individual pages:
```js
{
  path: '/error',
  renderMode: RenderMode.SSR,
  status: 404,
  headers: {
    'Cache-Control': 'no-cache'
  }
}
```

## Provide values for prerendering pages with dynamic routes:
```js
{
  path: '/product/:id',
  renderMode: RenderMode.SSG,
  async getPrerenderPaths() {
    const dataService = inject(ProductService);
    const ids = await dataService.getIds(); // Assuming this returns ['1', '2', '3']
    return ids.map(id => ({ id })); // Generates paths like: [{ id: '1' }, { id: '2' }, { id: '3' }]
  }
}
```

## Specify fallback behavior for SSG routes with parameterized paths:
```js
{
  path: '/product/:id',
  renderMode: RenderMode.SSG,
  fallback: SSGFallback.SSR, // Can be SSR, CSR, or None
  async getPrerenderPaths() {
  }
}
```

## Control rendering mode for individual routes:
```js
{
  path: '/product/:id',
  renderMode: RenderMode.SSR
},
{
  path: '/error',
  renderMode: RenderMode.CSR
},
{
  path: '/**',
  renderMode: RenderMode.SSG
}
```

These additions aim to provide greater flexibility and control over server-side rendering configurations and prerendering behaviors.

Author: alan-agius4

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

@@ -4,6 +4,8 @@
 
 ```ts
 
+import { EnvironmentProviders } from '@angular/core';
+
 // @public
 export interface AngularServerAppManager {
     render(request: Request, requestContext?: unknown): Promise<Response | null>;
@@ -15,6 +17,56 @@ export function destroyAngularAppEngine(): void;
 // @public
 export function getOrCreateAngularAppEngine(): AngularServerAppManager;
 
+// @public
+export function provideServerRoutesConfig(routes: ServerRoute[]): EnvironmentProviders;
+
+// @public
+export enum RenderMode {
+    AppShell = 0,
+    CSR = 2,
+    SSG = 3,
+    SSR = 1
+}
+
+// @public
+export type ServerRoute = ServerRouteAppShell | ServerRouteCSR | ServerRouteSSG | ServerRouteSSR;
+
+// @public
+export interface ServerRouteAppShell extends Omit<ServerRouteCommon, 'headers' | 'status'> {
+    renderMode: RenderMode.AppShell;
+}
+
+// @public
+export interface ServerRouteCommon {
+    headers?: Record<string, string>;
+    path: string;
+    status?: number;
+}
+
+// @public
+export interface ServerRouteCSR extends ServerRouteCommon {
+    renderMode: RenderMode.CSR;
+}
+
+// @public
+export interface ServerRouteSSG extends Omit<ServerRouteCommon, 'status'> {
+    fallback?: SSGFallback;
+    getPrenderPaths?: () => Promise<Record<string, string>[]>;
+    renderMode: RenderMode.SSG;
+}
+
+// @public
+export interface ServerRouteSSR extends ServerRouteCommon {
+    renderMode: RenderMode.SSR;
+}
+
+// @public
+export enum SSGFallback {
+    CSR = 1,
+    None = 2,
+    SSR = 0
+}
+
 // (No @packageDocumentation comment for this package)
 
 ```

packages/angular/ssr/private_export.ts

@@ -12,7 +12,6 @@ export {
   extractRoutesAndCreateRouteTree as ɵextractRoutesAndCreateRouteTree,
 } from './src/routes/ng-routes';
 export {
-  ServerRenderContext as ɵServerRenderContext,
   getOrCreateAngularServerApp as ɵgetOrCreateAngularServerApp,
   destroyAngularServerApp as ɵdestroyAngularServerApp,
 } from './src/app';

packages/angular/ssr/public_api.ts

@@ -13,3 +13,15 @@ export {
   getOrCreateAngularAppEngine,
   destroyAngularAppEngine,
 } from './src/app-engine';
+
+export {
+  type SSGFallback,
+  type RenderMode,
+  type ServerRoute,
+  type ServerRouteAppShell,
+  type ServerRouteCSR,
+  type ServerRouteSSG,
+  type ServerRouteSSR,
+  type ServerRouteCommon,
+  provideServerRoutesConfig,
+} from './src/routes/route-config';

packages/angular/ssr/src/app.ts

@@ -6,25 +6,34 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import { StaticProvider, ɵConsole, ɵresetCompiledComponents } from '@angular/core';
-import { ɵSERVER_CONTEXT as SERVER_CONTEXT } from '@angular/platform-server';
+import { StaticProvider, ɵresetCompiledComponents } from '@angular/core';
 import { ServerAssets } from './assets';
-import { Console } from './console';
 import { Hooks } from './hooks';
 import { getAngularAppManifest } from './manifest';
+import { RenderMode } from './routes/route-config';
 import { ServerRouter } from './routes/router';
 import { REQUEST, REQUEST_CONTEXT, RESPONSE_INIT } from './tokens';
 import { InlineCriticalCssProcessor } from './utils/inline-critical-css';
 import { renderAngular } from './utils/ng';
 
 /**
- * Enum representing the different contexts in which server rendering can occur.
+ * A mapping of `RenderMode` enum values to corresponding string representations.
+ *
+ * This record is used to map each `RenderMode` to a specific string value that represents
+ * the server context. The string values are used internally to differentiate
+ * between various rendering strategies when processing routes.
+ *
+ * - `RenderMode.SSG` maps to `'ssg'` (Static Site Generation).
+ * - `RenderMode.SSR` maps to `'ssr'` (Server-Side Rendering).
+ * - `RenderMode.AppShell` maps to `'app-shell'` (pre-rendered application shell).
+ * - `RenderMode.CSR` maps to an empty string `''` (Client-Side Rendering, no server context needed).
  */
-export enum ServerRenderContext {
-  SSR = 'ssr',
-  SSG = 'ssg',
-  AppShell = 'app-shell',
-}
+const SERVER_CONTEXT_VALUE: Record<RenderMode, string> = {
+  [RenderMode.SSG]: 'ssg',
+  [RenderMode.SSR]: 'ssr',
+  [RenderMode.AppShell]: 'app-shell',
+  [RenderMode.CSR]: '',
+};
 
 /**
  * Represents a locale-specific Angular server application managed by the server application engine.
@@ -65,18 +74,31 @@ export class AngularServerApp {
    *
    * @param request - The incoming HTTP request to be rendered.
    * @param requestContext - Optional additional context for rendering, such as request metadata.
-   * @param serverContext - The rendering context.
    *
    * @returns A promise that resolves to the HTTP response object resulting from the rendering, or null if no match is found.
    */
-  render(
-    request: Request,
-    requestContext?: unknown,
-    serverContext: ServerRenderContext = ServerRenderContext.SSR,
-  ): Promise<Response | null> {
+  render(request: Request, requestContext?: unknown): Promise<Response | null> {
     return Promise.race([
       this.createAbortPromise(request),
-      this.handleRendering(request, requestContext, serverContext),
+      this.handleRendering(request, /** isSsrMode */ true, requestContext),
+    ]);
+  }
+
+  /**
+   * Renders a response for the given URL using the server application.
+   *
+   * This method processes the request based on the provided URL and returns a response by performing server-side rendering.
+   * The rendering process can be aborted, with the first completed promise (either the abort or the render) determining the result.
+   *
+   * @param url - The URL of the page url. This object contains the full URL to be processed and rendered by the server.
+   * @returns A promise that resolves to the HTTP response object generated from the rendering, or `null` if no matching route is found.
+   */
+  renderStatic(url: URL): Promise<Response | null> {
+    const request = new Request(url);
+
+    return Promise.race([
+      this.createAbortPromise(request),
+      this.handleRendering(request, /** isSsrMode */ false),
     ]);
   }
 
@@ -107,15 +129,15 @@ export class AngularServerApp {
    * This method matches the request URL to a route and performs rendering if a matching route is found.
    *
    * @param request - The incoming HTTP request to be processed.
+   * @param isSsrMode - A boolean indicating whether the rendering is performed in server-side rendering (SSR) mode.
    * @param requestContext - Optional additional context for rendering, such as request metadata.
-   * @param serverContext - The rendering context. Defaults to server-side rendering (SSR).
    *
    * @returns A promise that resolves to the rendered response, or null if no matching route is found.
    */
   private async handleRendering(
     request: Request,
+    isSsrMode: boolean,
     requestContext?: unknown,
-    serverContext: ServerRenderContext = ServerRenderContext.SSR,
   ): Promise<Response | null> {
     const url = new URL(request.url);
     this.router ??= await ServerRouter.from(this.manifest, url);
@@ -126,32 +148,32 @@ export class AngularServerApp {
       return null;
     }
 
-    const { redirectTo } = matchedRoute;
+    const { redirectTo, status } = matchedRoute;
     if (redirectTo !== undefined) {
+      // Note: The status code is validated during route extraction.
       // 302 Found is used by default for redirections
       // See: https://developer.mozilla.org/en-US/docs/Web/API/Response/redirect_static#status
-      return Response.redirect(new URL(redirectTo, url), 302);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      return Response.redirect(new URL(redirectTo, url), (status as any) ?? 302);
     }
 
-    const platformProviders: StaticProvider[] = [
-      {
-        provide: SERVER_CONTEXT,
-        useValue: serverContext,
-      },
-      {
-        // An Angular Console Provider that does not print a set of predefined logs.
-        provide: ɵConsole,
-        // Using `useClass` would necessitate decorating `Console` with `@Injectable`,
-        // which would require switching from `ts_library` to `ng_module`. This change
-        // would also necessitate various patches of `@angular/bazel` to support ESM.
-        useFactory: () => new Console(),
-      },
-    ];
-
-    const isSsrMode = serverContext === ServerRenderContext.SSR;
-    const responseInit: ResponseInit = {};
+    const { renderMode = isSsrMode ? RenderMode.SSR : RenderMode.SSG, headers } = matchedRoute;
+
+    const platformProviders: StaticProvider[] = [];
+    let responseInit: ResponseInit | undefined;
 
     if (isSsrMode) {
+      // Initialize the response with status and headers if available.
+      responseInit = {
+        status,
+        headers: headers ? new Headers(headers) : undefined,
+      };
+
+      if (renderMode === RenderMode.CSR) {
+        // Serve the client-side rendered version if the route is configured for CSR.
+        return new Response(await this.assets.getServerAsset('index.csr.html'), responseInit);
+      }
+
       platformProviders.push(
         {
           provide: REQUEST,
@@ -183,7 +205,13 @@ export class AngularServerApp {
       html = await hooks.run('html:transform:pre', { html });
     }
 
-    html = await renderAngular(html, manifest.bootstrap(), new URL(request.url), platformProviders);
+    html = await renderAngular(
+      html,
+      manifest.bootstrap(),
+      new URL(request.url),
+      platformProviders,
+      SERVER_CONTEXT_VALUE[renderMode],
+    );
 
     if (manifest.inlineCriticalCss) {
       // Optionally inline critical CSS.