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:
```ts
const serverRoutes: ServerRoute[] = [
  {
    path: '/error',
    renderMode: RenderMode.SSR,
    status: 404,
    headers: {
      'Cache-Control': 'no-cache'
    }
  }
];
```

## Provide values for prerendering pages with dynamic routes:
```ts
const serverRoutes: ServerRoute[] = [
  {
    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:
```ts
const serverRoutes: ServerRoute[] = [
  {
    path: '/product/:id',
    renderMode: RenderMode.SSG,
    fallback: SSGFallback.SSR, // Can be SSR, CSR, or None
    async getPrerenderPaths() {
    }
  }
];
```

## Control rendering mode for individual routes:
```ts
const serverRoutes: ServerRoute[] = [
  {
    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,27 @@ 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 enum SSGFallback {
+    CSR = 1,
+    None = 2,
+    SSR = 0
+}
+
 // (No @packageDocumentation comment for this package)
 
 ```

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

@@ -0,0 +1,38 @@
+## API Report File for "@angular/devkit-repo"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+// @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;
+    getPrerenderPaths?: () => Promise<Record<string, string>[]>;
+    renderMode: RenderMode.SSG;
+}
+
+// @public
+export interface ServerRouteSSR extends ServerRouteCommon {
+    renderMode: RenderMode.SSR;
+}
+
+// (No @packageDocumentation comment for this package)
+
+```

packages/angular/ssr/BUILD.bazel

@@ -1,4 +1,4 @@
-load("@npm//@angular/build-tooling/bazel/api-golden:index.bzl", "api_golden_test_npm_package")
+load("@npm//@angular/build-tooling/bazel/api-golden:index.bzl", "api_golden_test", "api_golden_test_npm_package")
 load("@rules_pkg//:pkg.bzl", "pkg_tar")
 load("//tools:defaults.bzl", "ng_package", "ts_library")
 
@@ -67,3 +67,13 @@ api_golden_test_npm_package(
     golden_dir = "angular_cli/goldens/public-api/angular/ssr",
     npm_package = "angular_cli/packages/angular/ssr/npm_package",
 )
+
+api_golden_test(
+    name = "ssr_transitive_api",
+    data = [
+        ":ssr",
+        "//goldens:public-api",
+    ],
+    entry_point = "angular_cli/packages/angular/ssr/public_api_transitive.d.ts",
+    golden = "angular_cli/goldens/public-api/angular/ssr/index_transitive.api.md",
+)

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,10 @@ export {
   getOrCreateAngularAppEngine,
   destroyAngularAppEngine,
 } from './src/app-engine';
+
+export {
+  type SSGFallback,
+  type RenderMode,
+  type ServerRoute,
+  provideServerRoutesConfig,
+} from './src/routes/route-config';

packages/angular/ssr/public_api_transitive.ts

@@ -0,0 +1,19 @@
+/**
+ * @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
+ */
+
+// This file exports symbols that are not part of the public API but are
+// dependencies of public API symbols. Including them here ensures they
+// are tracked in the API golden file, preventing accidental breaking changes.
+
+export {
+  type ServerRouteAppShell,
+  type ServerRouteCSR,
+  type ServerRouteSSG,
+  type ServerRouteSSR,
+  type ServerRouteCommon,
+} 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.