@angular/ssr 18.2.0-rc.0 → 19.0.0-next.0

package/esm2022/public_api.mjs

@@ -5,4 +5,5 @@
  * 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
  */
-export { CommonEngine, } from './src/common-engine';
+export { CommonEngine, } from './src/common-engine/common-engine';
+export { getRoutesFromAngularRouterConfig as ɵgetRoutesFromAngularRouterConfig } from './src/routes/ng-routes';

package/esm2022/src/app-engine.mjs

@@ -0,0 +1,106 @@
+/**
+ * @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 { Hooks } from './hooks';
+import { getPotentialLocaleIdFromUrl } from './i18n';
+import { getAngularAppEngineManifest } from './manifest';
+/**
+ * Angular server application engine.
+ * Manages Angular server applications (including localized ones), handles rendering requests,
+ * and optionally transforms index HTML before rendering.
+ */
+export class AngularAppEngine {
+    /**
+     * Hooks for extending or modifying the behavior of the server application.
+     * @internal This property is accessed by the Angular CLI when running the dev-server.
+     */
+    static hooks = new Hooks();
+    /**
+     * 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.
+     * @internal
+     */
+    get hooks() {
+        return AngularAppEngine.hooks;
+    }
+    /**
+     * Specifies if the application is operating in development mode.
+     * This property controls the activation of features intended for production, such as caching mechanisms.
+     * @internal
+     */
+    static isDevMode = false;
+    /**
+     * The manifest for the server application.
+     */
+    manifest = getAngularAppEngineManifest();
+    /**
+     * Map of locale strings to corresponding `AngularServerApp` instances.
+     * Each instance represents an Angular server application.
+     */
+    appsCache = new Map();
+    /**
+     * Renders an HTTP request using the appropriate Angular server application and returns a response.
+     *
+     * This method determines the entry point for the Angular server application based on the request URL,
+     * and caches the server application instances for reuse. If the application is in development mode,
+     * the cache is bypassed and a new instance is created for each request.
+     *
+     * 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
+     * corresponding to `https://www.example.com/page`.
+     *
+     * @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.
+     */
+    async render(request, requestContext) {
+        // Skip if the request looks like a file but not `/index.html`.
+        const url = new URL(request.url);
+        const entryPoint = this.getEntryPointFromUrl(url);
+        if (!entryPoint) {
+            return null;
+        }
+        const [locale, loadModule] = entryPoint;
+        let serverApp = this.appsCache.get(locale);
+        if (!serverApp) {
+            const { AngularServerApp } = await loadModule();
+            serverApp = new AngularServerApp({
+                isDevMode: AngularAppEngine.isDevMode,
+                hooks: this.hooks,
+            });
+            if (!AngularAppEngine.isDevMode) {
+                this.appsCache.set(locale, serverApp);
+            }
+        }
+        return serverApp.render(request, requestContext);
+    }
+    /**
+     * Retrieves the entry point path and locale for the Angular server application based on the provided URL.
+     *
+     * This method determines the appropriate entry point and locale for rendering the application by examining the URL.
+     * If there is only one entry point available, it is returned regardless of the URL.
+     * Otherwise, the method extracts a potential locale identifier from the URL and looks up the corresponding entry point.
+     *
+     * @param url - The URL used to derive the locale and determine the entry point.
+     * @returns An array containing:
+     * - The first element is the locale extracted from the URL.
+     * - The second element is a function that returns a promise resolving to an object with the `AngularServerApp` type.
+     *
+     * Returns `null` if no matching entry point is found for the extracted locale.
+     */
+    getEntryPointFromUrl(url) {
+        // Find bundle for locale
+        const { entryPoints, basePath } = this.manifest;
+        if (entryPoints.size === 1) {
+            return entryPoints.entries().next().value;
+        }
+        const potentialLocale = getPotentialLocaleIdFromUrl(url, basePath);
+        const entryPoint = entryPoints.get(potentialLocale);
+        return entryPoint ? [potentialLocale, entryPoint] : null;
+    }
+}

package/esm2022/src/app.mjs

@@ -0,0 +1,85 @@
+/**
+ * @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 { ServerAssets } from './assets';
+import { Hooks } from './hooks';
+import { getAngularAppManifest } from './manifest';
+import { ServerRenderContext, render } from './render';
+import { ServerRouter } from './routes/router';
+/**
+ * Represents a locale-specific Angular server application managed by the server application engine.
+ *
+ * The `AngularServerApp` class handles server-side rendering and asset management for a specific locale.
+ */
+export class AngularServerApp {
+    options;
+    /**
+     * The manifest associated with this server application.
+     * @internal
+     */
+    manifest = getAngularAppManifest();
+    /**
+     * 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.
+     * @internal
+     */
+    hooks;
+    /**
+     * Specifies if the server application is operating in development mode.
+     * This property controls the activation of features intended for production, such as caching mechanisms.
+     * @internal
+     */
+    isDevMode;
+    /**
+     * An instance of ServerAsset that handles server-side asset.
+     * @internal
+     */
+    assets = new ServerAssets(this.manifest);
+    /**
+     * The router instance used for route matching and handling.
+     */
+    router;
+    /**
+     * Creates a new `AngularServerApp` instance with the provided configuration options.
+     *
+     * @param options - The configuration options for the server application.
+     * - `isDevMode`: Flag indicating if the application is in development mode.
+     * - `hooks`: Optional hooks for customizing application behavior.
+     */
+    constructor(options) {
+        this.options = options;
+        this.isDevMode = options.isDevMode ?? false;
+        this.hooks = options.hooks ?? new Hooks();
+    }
+    /**
+     * Renders a response for the given HTTP request using the server application.
+     *
+     * This method processes the request and returns a response based on the specified rendering context.
+     *
+     * @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.
+     */
+    async render(request, requestContext, serverContext = ServerRenderContext.SSR) {
+        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;
+        }
+        const { redirectTo } = matchedRoute;
+        if (redirectTo !== undefined) {
+            // 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);
+        }
+        return render(this, request, serverContext, requestContext);
+    }
+}

package/esm2022/src/assets.mjs

@@ -0,0 +1,44 @@
+/**
+ * @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
+ */
+/**
+ * Manages server-side assets.
+ */
+export class ServerAssets {
+    manifest;
+    /**
+     * Creates an instance of ServerAsset.
+     *
+     * @param manifest - The manifest containing the server assets.
+     */
+    constructor(manifest) {
+        this.manifest = manifest;
+    }
+    /**
+     * 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.
+     */
+    async getServerAsset(path) {
+        const asset = this.manifest.assets[path];
+        if (!asset) {
+            throw new Error(`Server asset '${path}' does not exist.`);
+        }
+        return asset();
+    }
+    /**
+     * Retrieves and caches the content of 'index.server.html'.
+     *
+     * @returns A promise that resolves to the content of 'index.server.html'.
+     * @throws Error If there is an issue retrieving the asset.
+     */
+    getIndexServerHtml() {
+        return this.getServerAsset('index.server.html');
+    }
+}

package/esm2022/src/console.mjs

@@ -0,0 +1,34 @@
+/**
+ * @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 { ɵConsole } from '@angular/core';
+/**
+ * Custom implementation of the Angular Console service that filters out specific log messages.
+ *
+ * This class extends the internal Angular `ɵConsole` class to provide customized logging behavior.
+ * It overrides the `log` method to suppress logs that match certain predefined messages.
+ */
+export class Console extends ɵConsole {
+    /**
+     * A set of log messages that should be ignored and not printed to the console.
+     */
+    ignoredLogs = new Set(['Angular is running in development mode.']);
+    /**
+     * Logs a message to the console if it is not in the set of ignored messages.
+     *
+     * @param message - The message to log to the console.
+     *
+     * This method overrides the `log` method of the `ɵConsole` class. It checks if the
+     * message is in the `ignoredLogs` set. If it is not, it delegates the logging to
+     * the parent class's `log` method. Otherwise, the message is suppressed.
+     */
+    log(message) {
+        if (!this.ignoredLogs.has(message)) {
+            super.log(message);
+        }
+    }
+}

package/esm2022/src/hooks.mjs

@@ -0,0 +1,94 @@
+/**
+ * @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
+ */
+/**
+ * Manages a collection of hooks and provides methods to register and execute them.
+ * Hooks are functions that can be invoked with specific arguments to allow modifications or enhancements.
+ */
+export class Hooks {
+    /**
+     * A map of hook names to arrays of hook functions.
+     * Each hook name can have multiple associated functions, which are executed in sequence.
+     */
+    store = new Map();
+    /**
+     * Executes all hooks associated with the specified name, passing the given argument to each hook function.
+     * The hooks are invoked sequentially, and the argument may be modified by each hook.
+     *
+     * @template Hook - The type of the hook name. It should be one of the keys of `HooksMapping`.
+     * @param name - The name of the hook whose functions will be executed.
+     * @param context - The input value to be passed to each hook function. The value is mutated by each hook function.
+     * @returns A promise that resolves once all hook functions have been executed.
+     *
+     * @example
+     * ```typescript
+     * const hooks = new Hooks();
+     * hooks.on('html:transform:pre', async (ctx) => {
+     *   ctx.html = ctx.html.replace(/foo/g, 'bar');
+     *   return ctx.html;
+     * });
+     * const result = await hooks.run('html:transform:pre', { html: '<div>foo</div>' });
+     * console.log(result); // '<div>bar</div>'
+     * ```
+     * @internal
+     */
+    async run(name, context) {
+        const hooks = this.store.get(name);
+        switch (name) {
+            case 'html:transform:pre': {
+                if (!hooks) {
+                    return context.html;
+                }
+                const ctx = { ...context };
+                for (const hook of hooks) {
+                    ctx.html = await hook(ctx);
+                }
+                return ctx.html;
+            }
+            default:
+                throw new Error(`Running hook "${name}" is not supported.`);
+        }
+    }
+    /**
+     * Registers a new hook function under the specified hook name.
+     * This function should be a function that takes an argument of type `T` and returns a `string` or `Promise<string>`.
+     *
+     * @template Hook - The type of the hook name. It should be one of the keys of `HooksMapping`.
+     * @param name - The name of the hook under which the function will be registered.
+     * @param handler - A function to be executed when the hook is triggered. The handler will be called with an argument
+     *                  that may be modified by the hook functions.
+     *
+     * @remarks
+     * - If there are existing handlers registered under the given hook name, the new handler will be added to the list.
+     * - If no handlers are registered under the given hook name, a new list will be created with the handler as its first element.
+     *
+     * @example
+     * ```typescript
+     * hooks.on('html:transform:pre', async (ctx) => {
+     *   return ctx.html.replace(/foo/g, 'bar');
+     * });
+     * ```
+     */
+    on(name, handler) {
+        const hooks = this.store.get(name);
+        if (hooks) {
+            hooks.push(handler);
+        }
+        else {
+            this.store.set(name, [handler]);
+        }
+    }
+    /**
+     * Checks if there are any hooks registered under the specified name.
+     *
+     * @param name - The name of the hook to check.
+     * @returns `true` if there are hooks registered under the specified name, otherwise `false`.
+     */
+    has(name) {
+        return !!this.store.get(name)?.length;
+    }
+}

package/esm2022/src/i18n.mjs

@@ -0,0 +1,41 @@
+/**
+ * @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
+ */
+/**
+ * Extracts a potential locale ID from a given URL based on the specified base path.
+ *
+ * This function parses the URL to locate a potential locale identifier that immediately
+ * follows the base path segment in the URL's pathname. If the URL does not contain a valid
+ * locale ID, an empty string is returned.
+ *
+ * @param url - The full URL from which to extract the locale ID.
+ * @param basePath - The base path used as the reference point for extracting the locale ID.
+ * @returns The extracted locale ID if present, or an empty string if no valid locale ID is found.
+ *
+ * @example
+ * ```js
+ * const url = new URL('https://example.com/base/en/page');
+ * const basePath = '/base';
+ * const localeId = getPotentialLocaleIdFromUrl(url, basePath);
+ * console.log(localeId); // Output: 'en'
+ * ```
+ */
+export function getPotentialLocaleIdFromUrl(url, basePath) {
+    const { pathname } = url;
+    // Move forward of the base path section.
+    let start = basePath.length;
+    if (pathname[start] === '/') {
+        start++;
+    }
+    // Find the next forward slash.
+    let end = pathname.indexOf('/', start);
+    if (end === -1) {
+        end = pathname.length;
+    }
+    // Extract the potential locale id.
+    return pathname.slice(start, end);
+}

package/esm2022/src/manifest.mjs

@@ -0,0 +1,59 @@
+/**
+ * @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
+ */
+/**
+ * The Angular app manifest object.
+ * This is used internally to store the current Angular app manifest.
+ */
+let angularAppManifest;
+/**
+ * Sets the Angular app manifest.
+ *
+ * @param manifest - The manifest object to set for the Angular application.
+ */
+export function setAngularAppManifest(manifest) {
+    angularAppManifest = manifest;
+}
+/**
+ * Gets the Angular app manifest.
+ *
+ * @returns The Angular app manifest.
+ * @throws Will throw an error if the Angular app manifest is not set.
+ */
+export function getAngularAppManifest() {
+    if (!angularAppManifest) {
+        throw new Error('Angular app manifest is not set. ' +
+            `Please ensure you are using the '@angular/build:application' builder to build your server application.`);
+    }
+    return angularAppManifest;
+}
+/**
+ * The Angular app engine manifest object.
+ * This is used internally to store the current Angular app engine manifest.
+ */
+let angularAppEngineManifest;
+/**
+ * Sets the Angular app engine manifest.
+ *
+ * @param manifest - The engine manifest object to set.
+ */
+export function setAngularAppEngineManifest(manifest) {
+    angularAppEngineManifest = manifest;
+}
+/**
+ * Gets the Angular app engine manifest.
+ *
+ * @returns The Angular app engine manifest.
+ * @throws Will throw an error if the Angular app engine manifest is not set.
+ */
+export function getAngularAppEngineManifest() {
+    if (!angularAppEngineManifest) {
+        throw new Error('Angular app engine manifest is not set. ' +
+            `Please ensure you are using the '@angular/build:application' builder to build your server application.`);
+    }
+    return angularAppEngineManifest;
+}

package/esm2022/src/render.mjs

@@ -0,0 +1,74 @@
+/**
+ * @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 { ɵConsole, ɵresetCompiledComponents } from '@angular/core';
+import { ɵSERVER_CONTEXT as SERVER_CONTEXT } from '@angular/platform-server';
+import { Console } from './console';
+import { REQUEST, REQUEST_CONTEXT, RESPONSE_INIT } from './tokens';
+import { renderAngular } from './utils/ng';
+/**
+ * Enum representing the different contexts in which server rendering can occur.
+ */
+export var ServerRenderContext;
+(function (ServerRenderContext) {
+    ServerRenderContext["SSR"] = "ssr";
+    ServerRenderContext["SSG"] = "ssg";
+    ServerRenderContext["AppShell"] = "app-shell";
+})(ServerRenderContext || (ServerRenderContext = {}));
+/**
+ * Renders an Angular server application to produce a response for the given HTTP request.
+ * Supports server-side rendering (SSR), static site generation (SSG), or app shell rendering.
+ *
+ * @param app - The server application instance to render.
+ * @param request - The incoming HTTP request object.
+ * @param serverContext - Context specifying the rendering mode.
+ * @param requestContext - Optional additional context for the request, such as metadata.
+ * @returns A promise that resolves to a response object representing the rendered content.
+ */
+export async function render(app, request, serverContext, requestContext) {
+    const isSsrMode = serverContext === ServerRenderContext.SSR;
+    const responseInit = {};
+    const platformProviders = [
+        {
+            provide: SERVER_CONTEXT,
+            useValue: serverContext,
+        },
+    ];
+    if (isSsrMode) {
+        platformProviders.push({
+            provide: REQUEST,
+            useValue: request,
+        }, {
+            provide: REQUEST_CONTEXT,
+            useValue: requestContext,
+        }, {
+            provide: RESPONSE_INIT,
+            useValue: responseInit,
+        });
+    }
+    const { manifest, hooks, isDevMode } = app;
+    if (isDevMode) {
+        // Need to clean up GENERATED_COMP_IDS map in `@angular/core`.
+        // Otherwise an incorrect component ID generation collision detected warning will be displayed in development.
+        // See: https://github.com/angular/angular-cli/issues/25924
+        ɵresetCompiledComponents();
+        // An Angular Console Provider that does not print a set of predefined logs.
+        platformProviders.push({
+            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(),
+        });
+    }
+    let html = await app.assets.getIndexServerHtml();
+    // Skip extra microtask if there are no pre hooks.
+    if (hooks.has('html:transform:pre')) {
+        html = await hooks.run('html:transform:pre', { html });
+    }
+    return new Response(await renderAngular(html, manifest.bootstrap(), new URL(request.url), platformProviders), responseInit);
+}

package/esm2022/src/request.mjs

@@ -0,0 +1,63 @@
+/**
+ * @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
+ */
+/**
+ * Converts a Node.js `IncomingMessage` into a Web Standard `Request`.
+ *
+ * @param nodeRequest - The Node.js `IncomingMessage` object to convert.
+ * @returns A Web Standard `Request` object.
+ */
+export function createWebRequestFromNodeRequest(nodeRequest) {
+    const { headers, method = 'GET' } = nodeRequest;
+    const withBody = method !== 'GET' && method !== 'HEAD';
+    return new Request(createRequestUrl(nodeRequest), {
+        method,
+        headers: createRequestHeaders(headers),
+        body: withBody ? nodeRequest : undefined,
+        duplex: withBody ? 'half' : undefined,
+    });
+}
+/**
+ * Creates a `Headers` object from Node.js `IncomingHttpHeaders`.
+ *
+ * @param nodeHeaders - The Node.js `IncomingHttpHeaders` object to convert.
+ * @returns A `Headers` object containing the converted headers.
+ */
+function createRequestHeaders(nodeHeaders) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(nodeHeaders)) {
+        if (typeof value === 'string') {
+            headers.append(name, value);
+        }
+        else if (Array.isArray(value)) {
+            for (const item of value) {
+                headers.append(name, item);
+            }
+        }
+    }
+    return headers;
+}
+/**
+ * Creates a `URL` object from a Node.js `IncomingMessage`, taking into account the protocol, host, and port.
+ *
+ * @param nodeRequest - The Node.js `IncomingMessage` object to extract URL information from.
+ * @returns A `URL` object representing the request URL.
+ */
+function createRequestUrl(nodeRequest) {
+    const { headers, socket, url = '' } = nodeRequest;
+    const protocol = headers['x-forwarded-proto'] ?? ('encrypted' in socket && socket.encrypted ? 'https' : 'http');
+    const hostname = headers['x-forwarded-host'] ?? headers.host ?? headers[':authority'];
+    const port = headers['x-forwarded-port'] ?? socket.localPort;
+    if (Array.isArray(hostname)) {
+        throw new Error('host value cannot be an array.');
+    }
+    let hostnameWithPort = hostname;
+    if (port && !hostname?.includes(':')) {
+        hostnameWithPort += `:${port}`;
+    }
+    return new URL(url, `${protocol}://${hostnameWithPort}`);
+}

package/esm2022/src/response.mjs

@@ -0,0 +1,58 @@
+/**
+ * @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
+ */
+/**
+ * Streams a web-standard `Response` into a Node.js `ServerResponse`.
+ *
+ * @param source - The web-standard `Response` object to stream from.
+ * @param destination - The Node.js `ServerResponse` object to stream into.
+ * @returns A promise that resolves once the streaming operation is complete.
+ */
+export async function writeResponseToNodeResponse(source, destination) {
+    const { status, headers, body } = source;
+    destination.statusCode = status;
+    let cookieHeaderSet = false;
+    for (const [name, value] of headers.entries()) {
+        if (name === 'set-cookie') {
+            if (cookieHeaderSet) {
+                continue;
+            }
+            // Sets the 'set-cookie' header only once to ensure it is correctly applied.
+            // Concatenating 'set-cookie' values can lead to incorrect behavior, so we use a single value from `headers.getSetCookie()`.
+            destination.setHeader(name, headers.getSetCookie());
+            cookieHeaderSet = true;
+        }
+        else {
+            destination.setHeader(name, value);
+        }
+    }
+    if (!body) {
+        destination.end();
+        return;
+    }
+    try {
+        const reader = body.getReader();
+        destination.on('close', () => {
+            reader.cancel().catch((error) => {
+                // eslint-disable-next-line no-console
+                console.error(`An error occurred while writing the response body for: ${destination.req.url}.`, error);
+            });
+        });
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                destination.end();
+                break;
+            }
+            destination.write(value);
+        }
+    }
+    catch {
+        destination.end('Internal server error.');
+    }
+}