@ecopages/core 0.2.0-beta.4 → 0.2.0-beta.40

package/src/adapters/node/runtime-host.js

@@ -1,92 +1,99 @@
-import { createServer } from "node:http";
-import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
-import { appLogger } from "../../global/app-logger.js";
-import { resolveServeRuntimeOrigin } from "../shared/runtime-app-bootstrap.js";
-import { isNodeClientAbortError, NodeHttpRequestBridge } from "./http-request-bridge.js";
-class NodeRuntimeHost {
-  /**
-   * Creates a Node runtime host with injectable request bridging and server
-   * creation seams for tests and alternate hosts.
-   */
-  constructor(requestBridge, serverFactory = createServer) {
-    this.requestBridge = requestBridge;
-    this.serverFactory = serverFactory;
-  }
-  requestBridge;
-  serverFactory;
-  /**
-   * Starts the Node HTTP server and wires each request through the shared Web
-   * request pipeline.
-   *
-   * @remarks
-   * Client disconnects are treated as normal aborts and do not trigger adapter
-   * error logging or the runtime host's `onError` callback.
-   */
-  async start(options) {
-    const hostname = String(options.serveOptions.hostname ?? DEFAULT_ECOPAGES_HOSTNAME);
-    const port = Number(options.serveOptions.port ?? DEFAULT_ECOPAGES_PORT);
-    const runtimeOrigin = resolveServeRuntimeOrigin({ hostname, port });
-    const server = this.serverFactory(async (req, res) => {
-      try {
-        const webRequest = this.requestBridge.createWebRequest(req, runtimeOrigin);
-        const response = await options.handleRequest(webRequest);
-        await this.requestBridge.sendNodeResponse(res, response);
-      } catch (error) {
-        if (isNodeClientAbortError(error)) {
-          return;
-        }
-        appLogger.error("Node server adapter request failed", error);
-        res.statusCode = 500;
-        res.end("Internal Server Error");
-        await options.onError(error instanceof Error ? error : new Error(String(error)));
-      }
-    });
-    await new Promise((resolve) => {
-      server.listen(port, hostname, () => resolve());
-    });
-    return server;
-  }
-  /**
-   * Stops the Node HTTP server and, by default, force-closes any remaining open
-   * connections.
-   */
-  async stop(server, options) {
-    await new Promise((resolve, reject) => {
-      server.close((error) => {
-        if (error) {
-          reject(error);
-          return;
+import { createServer } from 'node:http';
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from '../../config/constants.js';
+import { appLogger } from '../../global/app-logger.js';
+import { resolveServeRuntimeOrigin } from '../shared/runtime/runtime-app-bootstrap.js';
+import { isNodeClientAbortError, NodeHttpRequestBridge } from './http-request-bridge.js';
+/**
+ * Node runtime host that binds the shared Web-request pipeline onto a concrete
+ * Node HTTP server.
+ *
+ * @remarks
+ * The host owns only transport concerns: creating the Node listener, converting
+ * requests through `NodeHttpRequestBridge`, and handling socket-level failures.
+ * Routing and rendering remain in the shared server adapter.
+ */
+export class NodeRuntimeHost {
+    requestBridge;
+    serverFactory;
+    /**
+     * Creates a Node runtime host with injectable request bridging and server
+     * creation seams for tests and alternate hosts.
+     */
+    constructor(requestBridge, serverFactory = createServer) {
+        this.requestBridge = requestBridge;
+        this.serverFactory = serverFactory;
+    }
+    /**
+     * Starts the Node HTTP server and wires each request through the shared Web
+     * request pipeline.
+     *
+     * @remarks
+     * Client disconnects are treated as normal aborts and do not trigger adapter
+     * error logging or the runtime host's `onError` callback.
+     */
+    async start(options) {
+        const hostname = String(options.serveOptions.hostname ?? DEFAULT_ECOPAGES_HOSTNAME);
+        const port = Number(options.serveOptions.port ?? DEFAULT_ECOPAGES_PORT);
+        const runtimeOrigin = resolveServeRuntimeOrigin({ hostname, port });
+        const server = this.serverFactory(async (req, res) => {
+            try {
+                const webRequest = this.requestBridge.createWebRequest(req, runtimeOrigin);
+                const response = await options.handleRequest(webRequest);
+                await this.requestBridge.sendNodeResponse(res, response);
+            }
+            catch (error) {
+                if (isNodeClientAbortError(error)) {
+                    return;
+                }
+                appLogger.error('Node server adapter request failed', error);
+                res.statusCode = 500;
+                res.end('Internal Server Error');
+                await options.onError(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+        await new Promise((resolve) => {
+            server.listen(port, hostname, () => resolve());
+        });
+        return server;
+    }
+    /**
+     * Stops the Node HTTP server and, by default, force-closes any remaining open
+     * connections.
+     */
+    async stop(server, options) {
+        await new Promise((resolve, reject) => {
+            server.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+            if (options?.force ?? true) {
+                server.closeAllConnections();
+            }
+        });
+    }
+    /**
+     * Resolves the public runtime origin from the bound Node listener.
+     *
+     * @remarks
+     * The host preserves the configured hostname rather than echoing the raw socket
+     * address because users care about the requested host contract, not the local
+     * bind interface that Node chose internally.
+     */
+    getOrigin(server, fallbackServeOptions) {
+        const address = server.address();
+        const fallbackHostname = fallbackServeOptions.hostname ?? DEFAULT_ECOPAGES_HOSTNAME;
+        if (address && typeof address === 'object') {
+            return resolveServeRuntimeOrigin({
+                hostname: fallbackHostname,
+                port: address.port,
+            });
         }
-        resolve();
-      });
-      if (options?.force ?? true) {
-        server.closeAllConnections();
-      }
-    });
-  }
-  /**
-   * Resolves the public runtime origin from the bound Node listener.
-   *
-   * @remarks
-   * The host preserves the configured hostname rather than echoing the raw socket
-   * address because users care about the requested host contract, not the local
-   * bind interface that Node chose internally.
-   */
-  getOrigin(server, fallbackServeOptions) {
-    const address = server.address();
-    const fallbackHostname = fallbackServeOptions.hostname ?? DEFAULT_ECOPAGES_HOSTNAME;
-    if (address && typeof address === "object") {
-      return resolveServeRuntimeOrigin({
-        hostname: fallbackHostname,
-        port: address.port
-      });
+        return resolveServeRuntimeOrigin({
+            hostname: fallbackHostname,
+            port: fallbackServeOptions.port,
+        });
     }
-    return resolveServeRuntimeOrigin({
-      hostname: fallbackHostname,
-      port: fallbackServeOptions.port
-    });
-  }
 }
-export {
-  NodeRuntimeHost
-};

package/src/adapters/node/server-adapter-dependencies.js

@@ -1,18 +1,19 @@
-import { WebSocketServer } from "ws";
-import { NodeClientBridge } from "./node-client-bridge.js";
-import { NodeHmrManager } from "./node-hmr-manager.js";
-class DefaultNodeServerDevRuntimeFactory {
-  create(options) {
-    const websocketServer = new WebSocketServer({ noServer: true });
-    const bridge = new NodeClientBridge();
-    const hmrManager = new NodeHmrManager({ appConfig: options.appConfig, bridge });
-    return {
-      websocketServer,
-      bridge,
-      hmrManager
-    };
-  }
+import { WebSocketServer } from 'ws';
+import { setAppDevClientBridge } from '../../dev/client-bridge-registry.js';
+import { setAppHmrManager } from '../../dev/hmr-manager-registry.js';
+import { NodeClientBridge } from './node-client-bridge.js';
+import { NodeHmrManager } from './node-hmr-manager.js';
+export class DefaultNodeServerDevRuntimeFactory {
+    create(options) {
+        const websocketServer = new WebSocketServer({ noServer: true });
+        const bridge = new NodeClientBridge();
+        const hmrManager = new NodeHmrManager({ appConfig: options.appConfig, bridge });
+        setAppDevClientBridge(options.appConfig, bridge);
+        setAppHmrManager(options.appConfig, hmrManager);
+        return {
+            websocketServer,
+            bridge,
+            hmrManager,
+        };
+    }
 }
-export {
-  DefaultNodeServerDevRuntimeFactory
-};

package/src/adapters/node/server-adapter.d.ts

@@ -1,10 +1,10 @@
 import { type Server as NodeHttpServer } from 'node:http';
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { ApiHandler, ErrorHandler, StaticRoute } from '../../types/public-types.js';
-import { SharedServerAdapter } from '../shared/server-adapter.js';
+import type { ApiHandler, ErrorHandler, StaticRoute, EcopagesWebSocketHandler } from '../../types/public-types.js';
+import { SharedServerAdapter } from '../shared/runtime/server-adapter.js';
 import type { ServerAdapterResult } from '../abstract/server-adapter.js';
 import { NodeHttpRequestBridge } from './http-request-bridge.js';
-import type { StaticPreviewHost } from '../shared/static-preview-host.js';
+import type { StaticPreviewHost } from '../shared/runtime/static-preview-host.js';
 import { type NodeServerDevRuntimeFactory } from './server-adapter-dependencies.js';
 export type NodeServerInstance = NodeHttpServer;
 export type NodeServeAdapterServerOptions = {
@@ -19,9 +19,13 @@ export interface NodeServerAdapterParams {
     apiHandlers?: ApiHandler[];
     staticRoutes?: StaticRoute[];
     errorHandler?: ErrorHandler;
+    websocketHandlers?: Map<string, EcopagesWebSocketHandler<any, any>>;
+    hostOwnsDevClient?: boolean;
     options?: {
         watch?: boolean;
     };
+    deferRuntimeAssetSetup?: boolean;
+    allowPortFallback?: boolean;
     previewHost?: StaticPreviewHost;
     requestBridge?: NodeHttpRequestBridge;
     devRuntimeFactory?: NodeServerDevRuntimeFactory;
@@ -29,6 +33,10 @@ export interface NodeServerAdapterParams {
 export interface NodeServerAdapterResult extends ServerAdapterResult {
     completeInitialization: (server: NodeServerInstance) => Promise<void>;
     handleRequest: (request: Request) => Promise<Response>;
+    attachUserWebSocketUpgrades: (server: NodeServerInstance, options?: {
+        passthroughUnmatched?: boolean;
+    }) => void;
+    dispose: () => Promise<void>;
 }
 /**
  * Node.js HTTP server adapter for the Ecopages runtime.
@@ -58,13 +66,46 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
     private errorHandler?;
     private bridge;
     private hmrManager;
+    private projectWatcher;
+    private adapterDisposed;
+    private readonly deferRuntimeAssetSetup;
+    private readonly allowPortFallback;
     private readonly previewHost;
     private readonly requestBridge;
     private readonly devRuntimeFactory;
-    private shouldInjectHmrScript;
-    private isHtmlResponse;
-    private maybeInjectHmrScript;
-    constructor(options: NodeServerAdapterParams);
+    /**
+     * Reference to the application-level WebSocket handlers map.
+     *
+     * @remarks
+     * This is a reference to the map owned by `AbstractApplicationAdapter`,
+     * passed in via the constructor. The Node adapter reads from it to wire
+     * WebSocket upgrades for user-registered patterns.
+     */
+    protected websocketHandlers: Map<string, EcopagesWebSocketHandler<any, any>>;
+    /**
+     * Wires user WebSocket routes onto a foreign Node HTTP server.
+     *
+     * Host integrations such as the Vite plugin call this so `app.websocket()`
+     * handlers work while HTTP is still served by the host dev server.
+     */
+    attachUserWebSocketUpgrades(server: NodeServerInstance, options?: {
+        passthroughUnmatched?: boolean;
+    }): void;
+    private wireUserWebSocketUpgrades;
+    /**
+     * @remarks
+     * `previewHost`, `requestBridge`, and `devRuntimeFactory` are optional on the
+     * public {@link NodeServerAdapterParams} so factory callers can omit them, but
+     * they are mandatory by the time the concrete adapter is constructed —
+     * {@link createNodeServerAdapter} fills in Node-specific defaults first. The
+     * constructor signature makes that invariant explicit instead of relying on
+     * non-null assertions.
+     */
+    constructor(options: NodeServerAdapterParams & {
+        previewHost: StaticPreviewHost;
+        requestBridge: NodeHttpRequestBridge;
+        devRuntimeFactory: NodeServerDevRuntimeFactory;
+    });
     /**
      * Prepares the adapter for use.
      *
@@ -79,27 +120,26 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
      *    processors during their `setup()` calls.
      */
     initialize(): Promise<void>;
-    private prepareRuntimePublicDir;
     getServerOptions(): NodeServeAdapterServerOptions;
     buildStatic(options?: {
         preview?: boolean;
-    }): Promise<void>;
-    private startBuildRuntimeServer;
-    private getListeningServerOrigin;
+        force?: boolean;
+    }): Promise<string | undefined>;
     /**
-     * Gracefully shuts down the ephemeral build runtime server.
-     *
-     * `closeAllConnections()` is called *before* `close()` because `server.close()`
-     * only stops accepting new connections — it waits for existing keep-alive
-     * connections to finish naturally, which can stall the build indefinitely.
-     * `closeAllConnections()` force-closes any lingering sockets immediately so
-     * the `close()` callback fires promptly.
-     *
-     * The `NodeClientBridge` heartbeat is also destroyed here so its `setInterval`
-     * does not prevent the Node.js process from exiting cleanly after the build.
+     * Serves an existing static export without running SSG. Used by e2e preview
+     * launchers after a shared prewarm build.
      */
-    private stopBuildRuntimeServer;
+    servePreviewOnly(): Promise<string | undefined>;
+    private startPreviewServer;
     createAdapter(): Promise<NodeServerAdapterResult>;
+    /**
+     * Releases dev-time resources owned by the adapter.
+     *
+     * @remarks
+     * Safe to call multiple times. Does not stop the bound HTTP server — callers
+     * should shut down transport through the runtime host before disposing.
+     */
+    dispose(): Promise<void>;
     /**
      * Handles a single incoming Web `Request` and returns a Web `Response`.
      *
@@ -123,7 +163,7 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
      * - Shared watcher bootstrapping listens for route-level file changes and
      *   refreshes the router and response handlers when pages are added or removed.
      *
-     * WebSocket upgrade requests that do not target `/_hmr` are rejected with an
+     * WebSocket upgrade requests that do not match a known path are rejected with an
      * immediate socket destroy to prevent unhandled upgrade leaks.
      */
     completeInitialization(server: NodeServerInstance): Promise<void>;