@angular/ssr 19.0.0-rc.0 → 19.0.0-rc.1

package/fesm2022/ssr.mjs

@@ -21,22 +21,31 @@ class ServerAssets {
     /**
      * Retrieves the content of a server-side asset using its path.
      *
-     * @param path - The path to the server asset.
-     * @returns A promise that resolves to the asset content as a string.
-     * @throws Error If the asset path is not found in the manifest, an error is thrown.
+     * @param path - The path to the server asset within the manifest.
+     * @returns The server asset associated with the provided path, as a `ServerAsset` object.
+     * @throws Error - Throws an error if the asset does not exist.
      */
-    async getServerAsset(path) {
+    getServerAsset(path) {
         const asset = this.manifest.assets.get(path);
         if (!asset) {
             throw new Error(`Server asset '${path}' does not exist.`);
         }
-        return asset();
+        return asset;
     }
     /**
-     * Retrieves and caches the content of 'index.server.html'.
+     * Checks if a specific server-side asset exists.
      *
-     * @returns A promise that resolves to the content of 'index.server.html'.
-     * @throws Error If there is an issue retrieving the asset.
+     * @param path - The path to the server asset.
+     * @returns A boolean indicating whether the asset exists.
+     */
+    hasServerAsset(path) {
+        return this.manifest.assets.has(path);
+    }
+    /**
+     * Retrieves the asset for 'index.server.html'.
+     *
+     * @returns The `ServerAsset` object for 'index.server.html'.
+     * @throws Error - Throws an error if 'index.server.html' does not exist.
      */
     getIndexServerHtml() {
         return this.getServerAsset('index.server.html');
@@ -300,6 +309,8 @@ function isNgModule(value) {
 
 /**
  * Different rendering modes for server routes.
+ * @see {@link provideServerRoutesConfig}
+ * @see {@link ServerRoute}
  * @developerPreview
  */
 var RenderMode;
@@ -316,7 +327,7 @@ var RenderMode;
 /**
  * Defines the fallback strategies for Static Site Generation (SSG) routes when a pre-rendered path is not available.
  * This is particularly relevant for routes with parameterized URLs where some paths might not be pre-rendered at build time.
- *
+ * @see {@link ServerRoutePrerenderWithParams}
  * @developerPreview
  */
 var PrerenderFallback;
@@ -347,9 +358,13 @@ const SERVER_ROUTES_CONFIG = new InjectionToken('SERVER_ROUTES_CONFIG');
  *
  * @param routes - An array of server routes to be provided.
  * @returns An `EnvironmentProviders` object that contains the server routes configuration.
+ * @see {@link ServerRoute}
  * @developerPreview
  */
 function provideServerRoutesConfig(routes) {
+    if (typeof ngServerMode === 'undefined' || !ngServerMode) {
+        throw new Error(`The 'provideServerRoutesConfig' function should not be invoked within the browser portion of the application.`);
+    }
     return makeEnvironmentProviders([
         {
             provide: SERVER_ROUTES_CONFIG,
@@ -578,6 +593,7 @@ async function* traverseRoutesConfig(options) {
                 matchedMetaData.presentInClientRouter = true;
             }
             const metadata = {
+                renderMode: RenderMode.Prerender,
                 ...matchedMetaData,
                 route: currentRoutePath,
             };
@@ -883,7 +899,7 @@ async function getRoutesFromAngularRouterConfig(bootstrap, document, url, invoke
  */
 async function extractRoutesAndCreateRouteTree(url, manifest = getAngularAppManifest(), invokeGetPrerenderParams = false, includePrerenderFallbackRoutes = true) {
     const routeTree = new RouteTree();
-    const document = await new ServerAssets(manifest).getIndexServerHtml();
+    const document = await new ServerAssets(manifest).getIndexServerHtml().text();
     const bootstrap = await manifest.bootstrap();
     const { baseHref, routes, errors } = await getRoutesFromAngularRouterConfig(bootstrap, document, url, invokeGetPrerenderParams, includePrerenderFallbackRoutes);
     for (const { route, ...metadata } of routes) {
@@ -1391,11 +1407,29 @@ const SERVER_CONTEXT_VALUE = {
  * The `AngularServerApp` class handles server-side rendering and asset management for a specific locale.
  */
 class AngularServerApp {
+    options;
     /**
-     * Hooks for extending or modifying the behavior of the server application.
-     * This instance can be used to attach custom functionality to various events in the server application lifecycle.
+     * Whether prerendered routes should be rendered on demand or served directly.
+     *
+     * @see {@link AngularServerAppOptions.allowStaticRouteRender} for more details.
      */
-    hooks = new Hooks();
+    allowStaticRouteRender;
+    /**
+     * Hooks for extending or modifying server behavior.
+     *
+     * @see {@link AngularServerAppOptions.hooks} for more details.
+     */
+    hooks;
+    /**
+     * Constructs an instance of `AngularServerApp`.
+     *
+     * @param options Optional configuration options for the server application.
+     */
+    constructor(options = {}) {
+        this.options = options;
+        this.allowStaticRouteRender = this.options.allowStaticRouteRender ?? false;
+        this.hooks = options.hooks ?? new Hooks();
+    }
     /**
      * The manifest associated with this server application.
      */
@@ -1425,71 +1459,86 @@ class AngularServerApp {
      */
     criticalCssLRUCache = new LRUCache(MAX_INLINE_CSS_CACHE_ENTRIES);
     /**
-     * Renders a response for the given HTTP request using the server application.
+     * Handles an incoming HTTP request by serving prerendered content, performing server-side rendering,
+     * or delivering a static file for client-side rendered routes based on the `RenderMode` setting.
      *
-     * This method processes the request and returns a response based on the specified rendering context.
+     * @param request - The HTTP request to handle.
+     * @param requestContext - Optional context for rendering, such as metadata associated with the request.
+     * @returns A promise that resolves to the resulting HTTP response object, or `null` if no matching Angular route is found.
      *
-     * @param request - The incoming HTTP request to be rendered.
-     * @param requestContext - Optional additional context for rendering, such as request metadata.
-     *
-     * @returns A promise that resolves to the HTTP response object resulting from the rendering, or null if no match is found.
+     * @remarks A request to `https://www.example.com/page/index.html` will serve or render the Angular route
+     * corresponding to `https://www.example.com/page`.
      */
-    render(request, requestContext) {
+    async handle(request, requestContext) {
+        const url = new URL(request.url);
+        this.router ??= await ServerRouter.from(this.manifest, url);
+        const matchedRoute = this.router.match(url);
+        if (!matchedRoute) {
+            // Not a known Angular route.
+            return null;
+        }
+        if (matchedRoute.renderMode === RenderMode.Prerender) {
+            const response = await this.handleServe(request, matchedRoute);
+            if (response) {
+                return response;
+            }
+        }
         return Promise.race([
-            this.createAbortPromise(request),
-            this.handleRendering(request, /** isSsrMode */ true, requestContext),
+            this.waitForRequestAbort(request),
+            this.handleRendering(request, matchedRoute, requestContext),
         ]);
     }
     /**
-     * Renders a page based on the provided URL via server-side rendering and returns the corresponding HTTP response.
-     * The rendering process can be interrupted by an abort signal, where the first resolved promise (either from the abort
-     * or the render process) will dictate the outcome.
+     * Handles serving a prerendered static asset if available for the matched route.
      *
-     * @param url - The full URL to be processed and rendered by the server.
-     * @param signal - (Optional) An `AbortSignal` object that allows for the cancellation of the rendering process.
-     * @returns A promise that resolves to the generated HTTP response object, or `null` if no matching route is found.
-     */
-    renderStatic(url, signal) {
-        const request = new Request(url, { signal });
-        return Promise.race([
-            this.createAbortPromise(request),
-            this.handleRendering(request, /** isSsrMode */ false),
-        ]);
-    }
-    /**
-     * Creates a promise that rejects when the request is aborted.
+     * This method only supports `GET` and `HEAD` requests.
      *
-     * @param request - The HTTP request to monitor for abortion.
-     * @returns A promise that never resolves but rejects with an `AbortError` if the request is aborted.
+     * @param request - The incoming HTTP request for serving a static page.
+     * @param matchedRoute - The metadata of the matched route for rendering.
+     * If not provided, the method attempts to find a matching route based on the request URL.
+     * @returns A promise that resolves to a `Response` object if the prerendered page is found, or `null`.
      */
-    createAbortPromise(request) {
-        return new Promise((_, reject) => {
-            request.signal.addEventListener('abort', () => {
-                const abortError = new Error(`Request for: ${request.url} was aborted.\n${request.signal.reason}`);
-                abortError.name = 'AbortError';
-                reject(abortError);
-            }, { once: true });
-        });
+    async handleServe(request, matchedRoute) {
+        const { headers, renderMode } = matchedRoute;
+        if (renderMode !== RenderMode.Prerender) {
+            return null;
+        }
+        const { url, method } = request;
+        if (method !== 'GET' && method !== 'HEAD') {
+            return null;
+        }
+        const { pathname } = stripIndexHtmlFromURL(new URL(request.url));
+        const assetPath = stripLeadingSlash(joinUrlParts(pathname, 'index.html'));
+        if (!this.assets.hasServerAsset(assetPath)) {
+            return null;
+        }
+        const { text, hash, size } = this.assets.getServerAsset(assetPath);
+        const etag = `"${hash}"`;
+        return request.headers.get('if-none-match') === etag
+            ? new Response(undefined, { status: 304, statusText: 'Not Modified' })
+            : new Response(await text(), {
+                headers: {
+                    'Content-Length': size.toString(),
+                    'ETag': etag,
+                    'Content-Type': 'text/html;charset=UTF-8',
+                    ...headers,
+                },
+            });
     }
     /**
      * Handles the server-side rendering process for the given HTTP request.
      * 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 matchedRoute - The metadata of the matched route for rendering.
+     * If not provided, the method attempts to find a matching route based on the request URL.
      * @param requestContext - Optional additional context for rendering, such as request metadata.
      *
      * @returns A promise that resolves to the rendered response, or null if no matching route is found.
      */
-    async handleRendering(request, isSsrMode, requestContext) {
-        const url = new URL(request.url);
-        this.router ??= await ServerRouter.from(this.manifest, url);
-        const matchedRoute = this.router.match(url);
-        if (!matchedRoute) {
-            // Not a known Angular route.
-            return null;
-        }
+    async handleRendering(request, matchedRoute, requestContext) {
         const { redirectTo, status } = matchedRoute;
+        const url = new URL(request.url);
         if (redirectTo !== undefined) {
             // Note: The status code is validated during route extraction.
             // 302 Found is used by default for redirections
@@ -1497,35 +1546,36 @@ class AngularServerApp {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             return Response.redirect(new URL(redirectTo, url), status ?? 302);
         }
-        const { renderMode = isSsrMode ? RenderMode.Server : RenderMode.Prerender, headers } = matchedRoute;
+        const { renderMode, headers } = matchedRoute;
+        if (!this.allowStaticRouteRender &&
+            (renderMode === RenderMode.Prerender || renderMode === RenderMode.AppShell)) {
+            return null;
+        }
         const platformProviders = [];
-        let responseInit;
-        if (isSsrMode) {
-            // Initialize the response with status and headers if available.
-            responseInit = {
-                status,
-                headers: new Headers({
-                    'Content-Type': 'text/html;charset=UTF-8',
-                    ...headers,
-                }),
-            };
-            if (renderMode === RenderMode.Server) {
-                // Configure platform providers for request and response only for SSR.
-                platformProviders.push({
-                    provide: REQUEST,
-                    useValue: request,
-                }, {
-                    provide: REQUEST_CONTEXT,
-                    useValue: requestContext,
-                }, {
-                    provide: RESPONSE_INIT,
-                    useValue: responseInit,
-                });
-            }
-            else if (renderMode === RenderMode.Client) {
-                // Serve the client-side rendered version if the route is configured for CSR.
-                return new Response(await this.assets.getServerAsset('index.csr.html'), responseInit);
-            }
+        // Initialize the response with status and headers if available.
+        const responseInit = {
+            status,
+            headers: new Headers({
+                'Content-Type': 'text/html;charset=UTF-8',
+                ...headers,
+            }),
+        };
+        if (renderMode === RenderMode.Server) {
+            // Configure platform providers for request and response only for SSR.
+            platformProviders.push({
+                provide: REQUEST,
+                useValue: request,
+            }, {
+                provide: REQUEST_CONTEXT,
+                useValue: requestContext,
+            }, {
+                provide: RESPONSE_INIT,
+                useValue: responseInit,
+            });
+        }
+        else if (renderMode === RenderMode.Client) {
+            // Serve the client-side rendered version if the route is configured for CSR.
+            return new Response(await this.assets.getServerAsset('index.csr.html').text(), responseInit);
         }
         const { manifest: { bootstrap, inlineCriticalCss, locale }, hooks, assets, } = this;
         if (locale !== undefined) {
@@ -1534,7 +1584,7 @@ class AngularServerApp {
                 useValue: locale,
             });
         }
-        let html = await assets.getIndexServerHtml();
+        let html = await assets.getIndexServerHtml().text();
         // Skip extra microtask if there are no pre hooks.
         if (hooks.has('html:transform:pre')) {
             html = await hooks.run('html:transform:pre', { html, url });
@@ -1545,16 +1595,16 @@ class AngularServerApp {
             // Optionally inline critical CSS.
             this.inlineCriticalCssProcessor ??= new InlineCriticalCssProcessor((path) => {
                 const fileName = path.split('/').pop() ?? path;
-                return this.assets.getServerAsset(fileName);
+                return this.assets.getServerAsset(fileName).text();
             });
             // TODO(alanagius): remove once Node.js version 18 is no longer supported.
-            if (isSsrMode && typeof crypto === 'undefined') {
+            if (renderMode === RenderMode.Server && typeof crypto === 'undefined') {
                 // eslint-disable-next-line no-console
                 console.error(`The global 'crypto' module is unavailable. ` +
                     `If you are running on Node.js, please ensure you are using version 20 or later, ` +
                     `which includes built-in support for the Web Crypto module.`);
             }
-            if (isSsrMode && typeof crypto !== 'undefined') {
+            if (renderMode === RenderMode.Server && typeof crypto !== 'undefined') {
                 // Only cache if we are running in SSR Mode.
                 const cacheKey = await sha256(html);
                 let htmlWithCriticalCss = this.criticalCssLRUCache.get(cacheKey);
@@ -1570,16 +1620,35 @@ class AngularServerApp {
         }
         return new Response(html, responseInit);
     }
+    /**
+     * Returns a promise that rejects if the request is aborted.
+     *
+     * @param request - The HTTP request object being monitored for abortion.
+     * @returns A promise that never resolves and rejects with an `AbortError`
+     * if the request is aborted.
+     */
+    waitForRequestAbort(request) {
+        return new Promise((_, reject) => {
+            request.signal.addEventListener('abort', () => {
+                const abortError = new Error(`Request for: ${request.url} was aborted.\n${request.signal.reason}`);
+                abortError.name = 'AbortError';
+                reject(abortError);
+            }, { once: true });
+        });
+    }
 }
 let angularServerApp;
 /**
  * Retrieves or creates an instance of `AngularServerApp`.
  * - If an instance of `AngularServerApp` already exists, it will return the existing one.
  * - If no instance exists, it will create a new one with the provided options.
+ *
+ * @param options Optional configuration options for the server application.
+ *
  * @returns The existing or newly created instance of `AngularServerApp`.
  */
-function getOrCreateAngularServerApp() {
-    return (angularServerApp ??= new AngularServerApp());
+function getOrCreateAngularServerApp(options) {
+    return (angularServerApp ??= new AngularServerApp(options));
 }
 /**
  * Destroys the existing `AngularServerApp` instance, releasing associated resources and resetting the
@@ -1640,12 +1709,21 @@ function getPotentialLocaleIdFromUrl(url, basePath) {
  * Manages Angular server applications (including localized ones), handles rendering requests,
  * and optionally transforms index HTML before rendering.
  *
- * @note This class should be instantiated once and used as a singleton across the server-side
+ * @remarks This class should be instantiated once and used as a singleton across the server-side
  * application to ensure consistent handling of rendering requests and resource management.
  *
  * @developerPreview
  */
 class AngularAppEngine {
+    /**
+     * A flag to enable or disable the rendering of prerendered routes.
+     *
+     * Typically used during development to avoid prerendering all routes ahead of time,
+     * allowing them to be rendered on the fly as requested.
+     *
+     * @private
+     */
+    static ɵallowStaticRouteRender = false;
     /**
      * Hooks for extending or modifying the behavior of the server application.
      * These hooks are used by the Angular CLI when running the development server and
@@ -1654,15 +1732,6 @@ class AngularAppEngine {
      * @private
      */
     static ɵhooks = /* #__PURE__*/ new Hooks();
-    /**
-     * Provides access to the hooks for extending or modifying the server application's behavior.
-     * This allows attaching custom functionality to various server application lifecycle events.
-     *
-     * @internal
-     */
-    get hooks() {
-        return AngularAppEngine.ɵhooks;
-    }
     /**
      * The manifest for the server application.
      */
@@ -1672,50 +1741,46 @@ class AngularAppEngine {
      */
     entryPointsCache = new Map();
     /**
-     * Renders a response for the given HTTP request using the server application.
+     * Handles an incoming HTTP request by serving prerendered content, performing server-side rendering,
+     * or delivering a static file for client-side rendered routes based on the `RenderMode` setting.
      *
-     * This method processes the request, determines the appropriate route and rendering context,
-     * and returns an HTTP response.
+     * @param request - The HTTP request to handle.
+     * @param requestContext - Optional context for rendering, such as metadata associated with the request.
+     * @returns A promise that resolves to the resulting HTTP response object, or `null` if no matching Angular route is found.
      *
-     * If the request URL appears to be for a file (excluding `/index.html`), the method returns `null`.
-     * A request to `https://www.example.com/page/index.html` will render the Angular route
+     * @remarks A request to `https://www.example.com/page/index.html` will serve or render the Angular route
      * corresponding to `https://www.example.com/page`.
+     */
+    async handle(request, requestContext) {
+        const serverApp = await this.getAngularServerAppForRequest(request);
+        return serverApp ? serverApp.handle(request, requestContext) : null;
+    }
+    /**
+     * 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 to be rendered.
-     * @param requestContext - Optional additional context for the request, such as metadata.
-     * @returns A promise that resolves to a Response object, or `null` if the request URL represents a file (e.g., `./logo.png`)
-     * rather than an application route.
+     * @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.
      */
-    async render(request, requestContext) {
+    async getAngularServerAppForRequest(request) {
         // Skip if the request looks like a file but not `/index.html`.
         const url = new URL(request.url);
         const entryPoint = await this.getEntryPointExportsForUrl(url);
         if (!entryPoint) {
             return null;
         }
-        const { ɵgetOrCreateAngularServerApp: getOrCreateAngularServerApp } = entryPoint;
         // Note: Using `instanceof` is not feasible here because `AngularServerApp` will
         // be located in separate bundles, making `instanceof` checks unreliable.
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
-        const serverApp = getOrCreateAngularServerApp();
-        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) {
-        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);
+        const ɵgetOrCreateAngularServerApp = entryPoint.ɵgetOrCreateAngularServerApp;
+        const serverApp = ɵgetOrCreateAngularServerApp({
+            allowStaticRouteRender: AngularAppEngine.ɵallowStaticRouteRender,
+            hooks: AngularAppEngine.ɵhooks,
+        });
+        return serverApp;
     }
     /**
      * Retrieves the exports for a specific entry point, caching the result.