feat(@angular/ssr): add defineNodeNextHandler utility

Introduced the `defineNodeNextHandler` utility to expose middleware functions from the `server.ts` entry point for use with Vite.
This provides flexibility in integrating different server frameworks, including Express, Hono, and Fastify, with Angular SSR.

Examples:

**Express**
```
export default defineNodeNextHandler(app);
```

**Hono**
```
export default defineNodeNextHandler(async (req, res, next) => {
  try {
    const webRes = await app.fetch(createWebRequestFromNodeRequest(req));
    if (webRes) {
      await writeResponseToNodeResponse(webRes, res);
    } else {
      next();
    }
  } catch (error) {
    next(error);
  }
});
```

**Fastify**
```ts
export default defineNodeNextHandler(async (req, res) => {
  await app.ready();
  app.server.emit('request', req, res);
});
```

Author: alan-agius4

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

@@ -46,6 +46,9 @@ export interface CommonEngineRenderOptions {
 // @public
 export function createWebRequestFromNodeRequest(nodeRequest: IncomingMessage): Request;
 
+// @public
+export function defineNodeNextHandler<T = NextHandleFunction>(handler: T): T;
+
 // @public
 export function isMainModule(url: string): boolean;
 

packages/angular/ssr/node/public_api.ts

@@ -14,6 +14,7 @@ export {
 
 export { AngularNodeAppEngine } from './src/app-engine';
 
+export { defineNodeNextHandler } from './src/handler';
 export { writeResponseToNodeResponse } from './src/response';
 export { createWebRequestFromNodeRequest } from './src/request';
 export { isMainModule } from './src/module';

packages/angular/ssr/node/src/handler.ts

@@ -0,0 +1,75 @@
+/**
+ * @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 type { IncomingMessage, ServerResponse } from 'node:http';
+
+/**
+ * Represents a middleware function for handling HTTP requests in a Node.js environment.
+ *
+ * @param req - The incoming HTTP request object.
+ * @param res - The outgoing HTTP response object.
+ * @param next - A callback function that signals the completion of the middleware or forwards the error if provided.
+ *
+ * @returns A Promise that resolves to void or simply void. The handler can be asynchronous.
+ */
+type NextHandleFunction = (
+  req: IncomingMessage,
+  res: ServerResponse,
+  next: (err?: unknown) => void,
+) => Promise<void> | void;
+
+/**
+ * Attaches metadata to the handler function to mark it as a special handler for Node.js environments.
+ *
+ * @typeParam T - The type of the handler function, which defaults to `NextHandleFunction`.
+ * @param handler - The handler function to be defined and annotated.
+ * @returns The same handler function passed as an argument, with metadata attached.
+ *
+ * @example
+ * Usage in an Express application:
+ * ```ts
+ * const app = express();
+ * export default defineNodeNextHandler(app);
+ * ```
+ *
+ * @example
+ * Usage in a Hono application:
+ * ```ts
+ * const app = new Hono();
+ * export default defineNodeNextHandler(async (req, res, next) => {
+ *   try {
+ *     const webRes = await app.fetch(createWebRequestFromNodeRequest(req));
+ *     if (webRes) {
+ *       await writeResponseToNodeResponse(webRes, res);
+ *     } else {
+ *       next();
+ *     }
+ *   } catch (error) {
+ *     next(error);
+ *   }
+ * }));
+ * ```
+ *
+ * @example
+ * Usage in a Fastify application:
+ * ```ts
+ * const app = Fastify();
+ * export default defineNodeNextHandler(async (req, res) => {
+ *   await app.ready();
+ *   app.server.emit('request', req, res);
+ *   res.send('Hello from Fastify with Node Next Handler!');
+ * }));
+ * ```
+ * @developerPreview
+ */
+export function defineNodeNextHandler<T = NextHandleFunction>(handler: T): T {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (handler as any)['__ng_node_next_handler__'] = true;
+
+  return handler;
+}