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:

```ts
const serverRoutes: ServerRoute[] = [
  {
    path: '/error',
    renderMode: RenderMode.Server,
    status: 404,
    headers: {
      'Cache-Control': 'no-cache'
    }
  }
];
```

```ts
const serverRoutes: ServerRoute[] = [
  {
    path: '/product/:id',
    renderMode: RenderMode.Prerender,
    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' }]
    }
  }
];
```

```ts
const serverRoutes: ServerRoute[] = [
  {
    path: '/product/:id',
    renderMode: RenderMode.Prerender,
    fallback: PrerenderFallback.Server, // Can be Server, Client, or None
    async getPrerenderPaths() {
    }
  }
];
```

```ts
const serverRoutes: ServerRoute[] = [
  {
    path: '/product/:id',
    renderMode: RenderMode.Server,
  },
  {
    path: '/error',
    renderMode: RenderMode.Client,
  },
  {
    path: '/**',
    renderMode: RenderMode.Prerender,
  },
];
```

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,13 +4,36 @@
 
 ```ts
 
+import { EnvironmentProviders } from '@angular/core';
+
 // @public
 export class AngularAppEngine {
-    getHeaders(request: Request): ReadonlyMap<string, string>;
+    getPrerenderHeaders(request: Request): ReadonlyMap<string, string>;
     render(request: Request, requestContext?: unknown): Promise<Response | null>;
     static ɵhooks: Hooks;
 }
 
+// @public
+export enum PrerenderFallback {
+    Client = 1,
+    None = 2,
+    Server = 0
+}
+
+// @public
+export function provideServerRoutesConfig(routes: ServerRoute[]): EnvironmentProviders;
+
+// @public
+export enum RenderMode {
+    AppShell = 0,
+    Client = 2,
+    Prerender = 3,
+    Server = 1
+}
+
+// @public
+export type ServerRoute = ServerRouteAppShell | ServerRouteClient | ServerRoutePrerender | ServerRoutePrerenderWithParams | ServerRouteServer;
+
 // (No @packageDocumentation comment for this package)
 
 ```

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

@@ -0,0 +1,43 @@
+## 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 ServerRouteClient extends ServerRouteCommon {
+    renderMode: RenderMode.Client;
+}
+
+// @public
+export interface ServerRouteCommon {
+    headers?: Record<string, string>;
+    path: string;
+    status?: number;
+}
+
+// @public
+export interface ServerRoutePrerender extends Omit<ServerRouteCommon, 'status'> {
+    fallback?: never;
+    renderMode: RenderMode.Prerender;
+}
+
+// @public
+export interface ServerRoutePrerenderWithParams extends Omit<ServerRoutePrerender, 'fallback'> {
+    fallback?: PrerenderFallback;
+    getPrerenderParams: () => Promise<Record<string, string>[]>;
+}
+
+// @public
+export interface ServerRouteServer extends ServerRouteCommon {
+    renderMode: RenderMode.Server;
+}
+
+// (No @packageDocumentation comment for this package)
+
+```

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

@@ -12,7 +12,7 @@ import { Type } from '@angular/core';
 
 // @public
 export class AngularNodeAppEngine {
-    getHeaders(request: IncomingMessage): ReadonlyMap<string, string>;
+    getPrerenderHeaders(request: IncomingMessage): ReadonlyMap<string, string>;
     render(request: IncomingMessage, requestContext?: unknown): Promise<Response | null>;
 }
 

packages/angular/build/src/builders/application/tests/options/app-shell_spec.ts

@@ -116,7 +116,8 @@ describeBuilder(buildApplication, APPLICATION_BUILDER_INFO, (harness) => {
       harness.expectFile('dist/browser/main.js').toExist();
       const indexFileContent = harness.expectFile('dist/browser/index.html').content;
       indexFileContent.toContain('app-shell works!');
-      indexFileContent.toContain('ng-server-context="app-shell"');
+      // TODO(alanagius): enable once integration of routes in complete.
+      // indexFileContent.toContain('ng-server-context="app-shell"');
     });
 
     it('critical CSS is inlined', async () => {

packages/angular/build/src/tools/esbuild/application-code-bundle.ts

@@ -325,7 +325,6 @@ export function createServerMainCodeBundleOptions(
 
           // Add @angular/ssr exports
           `export {
-            ɵServerRenderContext,
             ɵdestroyAngularServerApp,
             ɵextractRoutesAndCreateRouteTree,
             ɵgetOrCreateAngularServerApp,

packages/angular/build/src/utils/server-rendering/load-esm-from-memory.ts

@@ -7,11 +7,7 @@
  */
 
 import type { ApplicationRef, Type } from '@angular/core';
-import type {
-  ɵServerRenderContext,
-  ɵextractRoutesAndCreateRouteTree,
-  ɵgetOrCreateAngularServerApp,
-} from '@angular/ssr';
+import type { ɵextractRoutesAndCreateRouteTree, ɵgetOrCreateAngularServerApp } from '@angular/ssr';
 import { assertIsError } from '../error';
 import { loadEsmModule } from '../load-esm';
 
@@ -20,7 +16,6 @@ import { loadEsmModule } from '../load-esm';
  */
 interface MainServerBundleExports {
   default: (() => Promise<ApplicationRef>) | Type<unknown>;
-  ɵServerRenderContext: typeof ɵServerRenderContext;
   ɵextractRoutesAndCreateRouteTree: typeof ɵextractRoutesAndCreateRouteTree;
   ɵgetOrCreateAngularServerApp: typeof ɵgetOrCreateAngularServerApp;
 }

packages/angular/build/src/utils/server-rendering/prerender.ts

@@ -210,12 +210,13 @@ async function renderPages(
         route.slice(baseHrefWithLeadingSlash.length - 1),
       );
 
-      const isAppShellRoute = appShellRoute === routeWithoutBaseHref;
-      const render: Promise<string | null> = renderWorker.run({ url: route, isAppShellRoute });
+      const render: Promise<string | null> = renderWorker.run({ url: route });
       const renderResult: Promise<void> = render
         .then((content) => {
           if (content !== null) {
             const outPath = posix.join(removeLeadingSlash(routeWithoutBaseHref), 'index.html');
+            const isAppShellRoute = appShellRoute === routeWithoutBaseHref;
+
             output[outPath] = { content, appShellRoute: isAppShellRoute };
           }
         })

packages/angular/build/src/utils/server-rendering/render-worker.ts

@@ -16,24 +16,18 @@ export interface RenderWorkerData extends ESMInMemoryFileLoaderWorkerData {
 
 export interface RenderOptions {
   url: string;
-  isAppShellRoute: boolean;
 }
 
 /**
  * Renders each route in routes and writes them to <outputPath>/<route>/index.html.
  */
-async function renderPage({ url, isAppShellRoute }: RenderOptions): Promise<string | null> {
-  const {
-    ɵgetOrCreateAngularServerApp: getOrCreateAngularServerApp,
-    ɵServerRenderContext: ServerRenderContext,
-  } = await loadEsmModuleFromMemory('./main.server.mjs');
+async function renderPage({ url }: RenderOptions): Promise<string | null> {
+  const { ɵgetOrCreateAngularServerApp: getOrCreateAngularServerApp } =
+    await loadEsmModuleFromMemory('./main.server.mjs');
   const angularServerApp = getOrCreateAngularServerApp();
-  const response = await angularServerApp.render(
-    new Request(new URL(url, 'http://local-angular-prerender'), {
-      signal: AbortSignal.timeout(30_000),
-    }),
-    undefined,
-    isAppShellRoute ? ServerRenderContext.AppShell : ServerRenderContext.SSG,
+  const response = await angularServerApp.renderStatic(
+    new URL(url, 'http://local-angular-prerender'),
+    AbortSignal.timeout(30_000),
   );
 
   return response ? response.text() : null;

packages/angular/build/src/utils/server-rendering/routes-extractor-worker.ts

@@ -26,6 +26,8 @@ async function extractRoutes(): Promise<RoutersExtractorWorkerResult> {
 
   const routeTree = await extractRoutesAndCreateRouteTree(
     new URL('http://local-angular-prerender/'),
+    /** manifest */ undefined,
+    /** invokeGetPrerenderParams */ true,
   );
 
   return routeTree.toObject();

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",
+)