feat(@angular/ssr): introduce AngularNodeAppEngine API for Node.js integration

Expose a variant of `AngularAppEngine` tailored for Node.js. These additions streamline the process by minimizing boilerplate code and eliminate the need for users to call `createWebRequestFromNodeRequest` before invoking the render method.

Author: alan-agius4

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

@@ -6,10 +6,16 @@
 
 import { ApplicationRef } from '@angular/core';
 import type { IncomingMessage } from 'node:http';
+import type { IncomingMessage as IncomingMessage_2 } from 'http';
 import type { ServerResponse } from 'node:http';
 import { StaticProvider } from '@angular/core';
 import { Type } from '@angular/core';
 
+// @public
+export interface AngularNodeServerAppManager {
+    render(request: Request | IncomingMessage_2, requestContext?: unknown): Promise<Response | null>;
+}
+
 // @public
 export class CommonEngine {
     constructor(options?: CommonEngineOptions | undefined);
@@ -40,6 +46,12 @@ export interface CommonEngineRenderOptions {
 // @public
 export function createWebRequestFromNodeRequest(nodeRequest: IncomingMessage): Request;
 
+// @public
+export function destroyAngularNodeAppEngine(): void;
+
+// @public
+export function getOrCreateAngularNodeAppEngine(): AngularNodeServerAppManager;
+
 // @public
 export function writeResponseToNodeResponse(source: Response, destination: ServerResponse): Promise<void>;
 

packages/angular/ssr/node/public_api.ts

@@ -12,5 +12,11 @@ export {
   type CommonEngineOptions,
 } from './src/common-engine/common-engine';
 
+export {
+  type AngularNodeServerAppManager,
+  destroyAngularNodeAppEngine,
+  getOrCreateAngularNodeAppEngine,
+} from './src/app-engine';
+
 export { writeResponseToNodeResponse } from './src/response';
 export { createWebRequestFromNodeRequest } from './src/request';

packages/angular/ssr/node/src/app-engine.ts

@@ -0,0 +1,95 @@
+/**
+ * @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 { ɵAngularAppEngine as AngularAppEngine } from '@angular/ssr';
+import type { IncomingMessage } from 'http';
+import { createWebRequestFromNodeRequest } from './request';
+
+/**
+ * Angular server application engine.
+ * Manages Angular server applications (including localized ones) and handles rendering requests.
+
+ * @developerPreview
+ */
+export interface AngularNodeServerAppManager {
+  /**
+   * Renders an HTTP response based on the incoming request using the Angular server application.
+   *
+   * The method processes the incoming request, determines the appropriate route, and prepares the
+   * rendering context to generate a response. If the request URL corresponds to a static file (excluding `/index.html`),
+   * the method returns `null`.
+   *
+   * Example: A request to `https://www.example.com/page/index.html` will render the Angular route
+   * associated with `https://www.example.com/page`.
+   *
+   * @param request - The incoming HTTP request object to be rendered. It can be a `Request` or `IncomingMessage` object.
+   * @param requestContext - Optional additional context for the request, such as metadata or custom settings.
+   * @returns A promise that resolves to a `Response` object, or `null` if the request URL is for a static file
+   * (e.g., `./logo.png`) rather than an application route.
+   */
+  render(request: Request | IncomingMessage, requestContext?: unknown): Promise<Response | null>;
+}
+
+/**
+ * Angular server application engine.
+ * Manages Angular server applications (including localized ones), handles rendering requests,
+ * and optionally transforms index HTML before rendering.
+ */
+export class AngularNodeAppEngine extends AngularAppEngine implements AngularNodeServerAppManager {
+  /**
+   * Renders an HTTP response based on the incoming request using the Angular server application.
+   *
+   * The method processes the incoming request, determines the appropriate route, and prepares the
+   * rendering context to generate a response. If the request URL corresponds to a static file (excluding `/index.html`),
+   * the method returns `null`.
+   *
+   * Example: A request to `https://www.example.com/page/index.html` will render the Angular route
+   * associated with `https://www.example.com/page`.
+   *
+   * @param request - The incoming HTTP request object to be rendered. It can be a `Request` or `IncomingMessage` object.
+   * @param requestContext - Optional additional context for the request, such as metadata or custom settings.
+   * @returns A promise that resolves to a `Response` object, or `null` if the request URL is for a static file
+   * (e.g., `./logo.png`) rather than an application route.
+   */
+  override render(
+    request: Request | IncomingMessage,
+    requestContext?: unknown,
+  ): Promise<Response | null> {
+    const webReq = request instanceof Request ? request : createWebRequestFromNodeRequest(request);
+
+    return super.render(webReq, requestContext);
+  }
+}
+
+let angularNodeAppEngine: AngularNodeAppEngine | undefined;
+
+/**
+ * Retrieves the existing `AngularNodeAppEngine` instance or creates a new one if it doesn't exist.
+ *
+ * This method ensures that a single instance of `AngularNodeAppEngine` is used throughout the application's lifecycle,
+ * promoting efficient resource management. If an instance does not exist, it will be instantiated upon the first call.
+ *
+ * @developerPreview
+ * @returns The existing or newly created instance of `AngularNodeAppEngine`.
+ */
+export function getOrCreateAngularNodeAppEngine(): AngularNodeServerAppManager {
+  return (angularNodeAppEngine ??= new AngularNodeAppEngine());
+}
+
+/**
+ * Destroys the current `AngularNodeAppEngine` instance and releases any associated resources.
+ *
+ * This method resets the reference to the `AngularNodeAppEngine` instance to `undefined`, allowing for the creation
+ * of a new instance on subsequent calls to `getOrCreateAngularNodeAppEngine()`. This is typically used when
+ * reinitializing the server environment or refreshing the application state.
+ *
+ * @developerPreview
+ */
+export function destroyAngularNodeAppEngine(): void {
+  angularNodeAppEngine = undefined;
+}