From 30c25bf6885fefea6094ec1815e066e4c6ada097 Mon Sep 17 00:00:00 2001
From: Alan Agius <alanagius@google.com>
Date: Mon, 26 Aug 2024 08:39:18 +0000
Subject: [PATCH] feat(@angular/ssr): export `AngularAppEngine` as public API

Added `AngularAppEngine` to the public API of `@angular/ssr`, allowing users to access it directly for enhanced server-side rendering functionality.
---
 goldens/public-api/angular/ssr/index.api.md | 11 ++++
 packages/angular/ssr/private_export.ts      |  2 +
 packages/angular/ssr/public_api.ts          |  6 ++
 packages/angular/ssr/src/app-engine.ts      | 62 +++++++++++++++++++--
 4 files changed, 77 insertions(+), 4 deletions(-)

diff --git a/goldens/public-api/angular/ssr/index.api.md b/goldens/public-api/angular/ssr/index.api.md
index 23d13774aba3..6d89972bde20 100644
--- a/goldens/public-api/angular/ssr/index.api.md
+++ b/goldens/public-api/angular/ssr/index.api.md
@@ -4,6 +4,17 @@
 
 ```ts
 
+// @public
+export interface AngularServerAppManager {
+    render(request: Request, requestContext?: unknown): Promise<Response | null>;
+}
+
+// @public
+export function destroyAngularAppEngine(): void;
+
+// @public
+export function getOrCreateAngularAppEngine(): AngularServerAppManager;
+
 // (No @packageDocumentation comment for this package)
 
 ```
diff --git a/packages/angular/ssr/private_export.ts b/packages/angular/ssr/private_export.ts
index 9772d2252afc..9c5573471467 100644
--- a/packages/angular/ssr/private_export.ts
+++ b/packages/angular/ssr/private_export.ts
@@ -17,4 +17,6 @@ export {
   setAngularAppEngineManifest as ɵsetAngularAppEngineManifest,
 } from './src/manifest';
 
+export { AngularAppEngine as ɵAngularAppEngine } from './src/app-engine';
+
 export { InlineCriticalCssProcessor as ɵInlineCriticalCssProcessor } from './src/utils/inline-critical-css';
diff --git a/packages/angular/ssr/public_api.ts b/packages/angular/ssr/public_api.ts
index e714ba0d0e44..71647188bc13 100644
--- a/packages/angular/ssr/public_api.ts
+++ b/packages/angular/ssr/public_api.ts
@@ -7,3 +7,9 @@
  */
 
 export * from './private_export';
+
+export {
+  type AngularServerAppManager,
+  getOrCreateAngularAppEngine,
+  destroyAngularAppEngine,
+} from './src/app-engine';
diff --git a/packages/angular/ssr/src/app-engine.ts b/packages/angular/ssr/src/app-engine.ts
index fa501c33510c..c76be807c223 100644
--- a/packages/angular/ssr/src/app-engine.ts
+++ b/packages/angular/ssr/src/app-engine.ts
@@ -10,20 +10,45 @@ import { Hooks } from './hooks';
 import { getPotentialLocaleIdFromUrl } from './i18n';
 import { EntryPointExports, getAngularAppEngineManifest } from './manifest';
 
+/**
+ * Angular server application engine.
+ * Manages Angular server applications (including localized ones) and handles rendering requests.
+
+ * @developerPreview
+ */
+export interface AngularServerAppManager {
+  /**
+   * Renders a response for the given HTTP request using the server application.
+   *
+   * This method processes the request, determines the appropriate route and rendering context,
+   * and returns an HTTP response.
+   *
+   * 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.
+   */
+  render(request: Request, 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 AngularAppEngine {
+export class AngularAppEngine implements AngularServerAppManager {
   /**
    * 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
    * provide extensibility points for the application lifecycle.
    *
-   * @internal
+   * @private
    */
-  static hooks = new Hooks();
+  static ɵhooks = new Hooks();
 
   /**
    * Provides access to the hooks for extending or modifying the server application's behavior.
@@ -32,7 +57,7 @@ export class AngularAppEngine {
    * @internal
    */
   get hooks(): Hooks {
-    return AngularAppEngine.hooks;
+    return AngularAppEngine.ɵhooks;
   }
 
   /**
@@ -92,3 +117,32 @@ export class AngularAppEngine {
     return entryPoints.get(potentialLocale);
   }
 }
+
+let angularAppEngine: AngularAppEngine | undefined;
+
+/**
+ * Retrieves an existing `AngularAppEngine` instance or creates a new one if none exists.
+ *
+ * This method ensures that only a single instance of `AngularAppEngine` is created and reused across
+ * the application lifecycle, providing efficient resource management. If the instance does not exist,
+ * it will be instantiated upon the first call.
+ *
+ * @developerPreview
+ * @returns The existing or newly created instance of `AngularAppEngine`.
+ */
+export function getOrCreateAngularAppEngine(): AngularServerAppManager {
+  return (angularAppEngine ??= new AngularAppEngine());
+}
+
+/**
+ * Destroys the current `AngularAppEngine` instance, releasing any associated resources.
+ *
+ * This method resets the reference to the `AngularAppEngine` instance to `undefined`, allowing
+ * a new instance to be created on the next call to `getOrCreateAngularAppEngine()`. It is typically
+ * used when reinitializing the server environment or refreshing the application state is necessary.
+ *
+ * @developerPreview
+ */
+export function destroyAngularAppEngine(): void {
+  angularAppEngine = undefined;
+}