@ecopages/core 0.2.0-alpha.53 → 0.2.0-alpha.54

package/src/adapters/node/node-hmr-manager.ts

@@ -0,0 +1,72 @@
+import type { EcoPagesAppConfig, IClientBridge } from '../../types/internal-types.ts';
+import { appLogger } from '../../global/app-logger.ts';
+import {
+	InMemoryEntrypointDependencyGraph,
+	type EntrypointDependencyGraph,
+} from '../../services/runtime-state/entrypoint-dependency-graph.service.ts';
+import { SharedHmrManager } from '../shared/shared-hmr-manager.ts';
+
+export interface NodeHmrManagerParams {
+	appConfig: EcoPagesAppConfig;
+	bridge: IClientBridge;
+}
+
+/**
+ * Node development HMR manager.
+ *
+ * @remarks
+ * This manager owns three separate concerns:
+ * - runtime websocket event fanout
+ * - entrypoint registration and dedupe
+ * - strategy coordination for rebuilds and invalidation
+ *
+ * The strict page-entrypoint contract lives here: `registerEntrypoint()` is
+ * reserved for integration-owned page bundles, while generic script assets must
+ * go through `registerScriptEntrypoint()`.
+ */
+export class NodeHmrManager extends SharedHmrManager {
+	/**
+	 * Creates the Node HMR manager over the shared coordination pipeline.
+	 *
+	 * @remarks
+	 * Unlike Bun, Node keeps websocket subscription wiring in the server adapter,
+	 * so this manager only specializes the shared manager where runtime behavior
+	 * actually differs: dependency-graph storage, missing-file tolerance, and how
+	 * runtime bundle failures disable HMR.
+	 */
+	constructor({ appConfig, bridge }: NodeHmrManagerParams) {
+		super({ appConfig, bridge });
+	}
+
+	/**
+	 * Reuses the shared in-memory dependency graph when the app already has one and
+	 * otherwise creates the default Node development graph.
+	 */
+	protected override createEntrypointDependencyGraph(existingEntrypointDependencyGraph: EntrypointDependencyGraph) {
+		return existingEntrypointDependencyGraph instanceof InMemoryEntrypointDependencyGraph
+			? existingEntrypointDependencyGraph
+			: new InMemoryEntrypointDependencyGraph();
+	}
+
+	/**
+	 * Tells the shared HMR manager to ignore missing-file events during Node watch
+	 * mode.
+	 *
+	 * @remarks
+	 * Node file watching can briefly report remove-and-recreate sequences while a
+	 * file is being rewritten. Treating those transient gaps as fatal would disable
+	 * otherwise healthy development sessions.
+	 */
+	protected override shouldSkipMissingFileChange(_filePath: string): boolean {
+		return true;
+	}
+
+	/**
+	 * Disables HMR after a runtime bundle failure so the Node dev server can keep
+	 * serving requests without repeatedly emitting broken updates.
+	 */
+	protected override onRuntimeBundleFailure(error: unknown): void {
+		this.enabled = false;
+		appLogger.error('[HMR] Failed to build runtime script; continuing with HMR disabled.', error);
+	}
+}

package/src/adapters/node/runtime-host.test.ts

@@ -0,0 +1,49 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { appLogger } from '../../global/app-logger.ts';
+import { NodeClientAbortError } from './http-request-bridge.ts';
+import { NodeRuntimeHost } from './runtime-host.ts';
+
+describe('NodeRuntimeHost', () => {
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it('does not log or report client aborts raised while sending the response', async () => {
+		let requestHandler:
+			| ((req: unknown, res: { statusCode: number; end: ReturnType<typeof vi.fn> }) => Promise<void>)
+			| undefined;
+
+		const requestBridge = {
+			createWebRequest: vi.fn().mockReturnValue(new Request('http://localhost:3000')),
+			sendNodeResponse: vi.fn().mockRejectedValue(new NodeClientAbortError()),
+		};
+		const serverFactory = vi.fn().mockImplementation((handler) => {
+			requestHandler = handler;
+			return {
+				listen: (_port: number, _hostname: string, callback: () => void) => callback(),
+				close: (_callback: (error?: Error | null) => void) => undefined,
+				closeAllConnections: () => undefined,
+				address: () => ({ address: '127.0.0.1', port: 3000, family: 'IPv4' }),
+			};
+		});
+		const onError = vi.fn();
+		const loggerSpy = vi.spyOn(appLogger, 'error');
+		const host = new NodeRuntimeHost(requestBridge as never, serverFactory as never);
+
+		await host.start({
+			serveOptions: {
+				hostname: 'localhost',
+				port: 3000,
+			},
+			handleRequest: async () => new Response('ok'),
+			onError,
+		});
+
+		const res = { statusCode: 200, end: vi.fn() };
+		await requestHandler?.({ url: '/', method: 'GET', headers: {} }, res);
+
+		expect(loggerSpy).not.toHaveBeenCalled();
+		expect(res.end).not.toHaveBeenCalled();
+		expect(onError).not.toHaveBeenCalled();
+	});
+});

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

@@ -0,0 +1,113 @@
+import { createServer, type Server as NodeServerInstance } from 'node:http';
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from '../../config/constants.ts';
+import { appLogger } from '../../global/app-logger.ts';
+import { resolveServeRuntimeOrigin } from '../shared/runtime-app-bootstrap.ts';
+import type { RuntimeHost, RuntimeHostStartOptions } from '../shared/runtime-host.ts';
+import { isNodeClientAbortError, NodeHttpRequestBridge } from './http-request-bridge.ts';
+
+type NodeServerFactory = typeof createServer;
+
+/**
+ * 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 implements RuntimeHost<NodeServerInstance, { port?: number; hostname?: string }> {
+	/**
+	 * Creates a Node runtime host with injectable request bridging and server
+	 * creation seams for tests and alternate hosts.
+	 */
+	constructor(
+		private readonly requestBridge: NodeHttpRequestBridge,
+		private readonly serverFactory: NodeServerFactory = createServer,
+	) {}
+
+	/**
+	 * 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.
+	 */
+	public async start(
+		options: RuntimeHostStartOptions<{ port?: number; hostname?: string }>,
+	): Promise<NodeServerInstance> {
+		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 as Error);
+				res.statusCode = 500;
+				res.end('Internal Server Error');
+				await options.onError(error instanceof Error ? error : new Error(String(error)));
+			}
+		});
+
+		await new Promise<void>((resolve) => {
+			server.listen(port, hostname, () => resolve());
+		});
+
+		return server;
+	}
+
+	/**
+	 * Stops the Node HTTP server and, by default, force-closes any remaining open
+	 * connections.
+	 */
+	public async stop(server: NodeServerInstance, options?: { force?: boolean }): Promise<void> {
+		await new Promise<void>((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.
+	 */
+	public getOrigin(server: NodeServerInstance, fallbackServeOptions: { port?: number; hostname?: string }): string {
+		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,
+		});
+	}
+}

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

@@ -0,0 +1,28 @@
+import { WebSocketServer } from 'ws';
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import { NodeClientBridge } from './node-client-bridge.ts';
+import { NodeHmrManager } from './node-hmr-manager.ts';
+
+export interface NodeServerDevRuntime {
+	websocketServer: WebSocketServer;
+	bridge: NodeClientBridge;
+	hmrManager: NodeHmrManager;
+}
+
+export interface NodeServerDevRuntimeFactory {
+	create(options: { appConfig: EcoPagesAppConfig }): NodeServerDevRuntime;
+}
+
+export class DefaultNodeServerDevRuntimeFactory implements NodeServerDevRuntimeFactory {
+	public create(options: { appConfig: EcoPagesAppConfig }): NodeServerDevRuntime {
+		const websocketServer = new WebSocketServer({ noServer: true });
+		const bridge = new NodeClientBridge();
+		const hmrManager = new NodeHmrManager({ appConfig: options.appConfig, bridge });
+
+		return {
+			websocketServer,
+			bridge,
+			hmrManager,
+		};
+	}
+}

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

@@ -0,0 +1,84 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import type { NodeServerAdapterParams } from './server-adapter.ts';
+import { NodeServerAdapter } from './server-adapter.ts';
+import { NodeClientAbortError } from './http-request-bridge.ts';
+
+class TestNodeServerAdapter extends NodeServerAdapter {
+	public handleSharedRequestImpl?: () => Promise<Response>;
+
+	public setInitializedForTest(): void {
+		(this as unknown as { initialized: boolean }).initialized = true;
+	}
+
+	public setHmrManagerForTest(hmrManager: { isEnabled: () => boolean } | null): void {
+		(this as unknown as { hmrManager: { isEnabled: () => boolean } | null }).hmrManager = hmrManager;
+	}
+
+	public override async handleSharedRequest(): Promise<Response> {
+		if (this.handleSharedRequestImpl) {
+			return await this.handleSharedRequestImpl();
+		}
+
+		return new Response('<html><body><h1>Explicit route</h1></body></html>', {
+			headers: { 'Content-Type': 'text/html' },
+		});
+	}
+}
+
+function createAdapter(options?: Partial<NodeServerAdapterParams>) {
+	const appConfig = {
+		rootDir: '/tmp/app',
+		distDir: '.ecopages',
+		runtime: {},
+	} as unknown as EcoPagesAppConfig;
+
+	return new TestNodeServerAdapter({
+		appConfig,
+		runtimeOrigin: 'http://localhost:3000',
+		serveOptions: {},
+		options: { watch: true },
+		...options,
+	});
+}
+
+describe('NodeServerAdapter', () => {
+	beforeEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it('injects the HMR runtime into explicit HTML handler responses in watch mode', async () => {
+		const adapter = createAdapter();
+		adapter.setInitializedForTest();
+		adapter.setHmrManagerForTest({ isEnabled: () => true });
+
+		const response = await adapter.handleRequest(new Request('http://localhost:3000/explicit/team'));
+		const html = await response.text();
+
+		expect(html).toContain("import '/_hmr_runtime.js'");
+		expect(response.headers.get('Cache-Control')).toBe('no-store, must-revalidate');
+	});
+
+	it('does not inject the HMR runtime when watch mode is disabled', async () => {
+		const adapter = createAdapter({ options: { watch: false } });
+		adapter.setInitializedForTest();
+		adapter.setHmrManagerForTest({ isEnabled: () => true });
+
+		const response = await adapter.handleRequest(new Request('http://localhost:3000/explicit/team'));
+		const html = await response.text();
+
+		expect(html).not.toContain("import '/_hmr_runtime.js'");
+	});
+
+	it('returns 499 for normalized client aborts', async () => {
+		const adapter = createAdapter({ options: { watch: false } });
+		adapter.setInitializedForTest();
+		adapter.handleSharedRequestImpl = async () => {
+			throw new NodeClientAbortError();
+		};
+
+		const response = await adapter.handleRequest(new Request('http://localhost:3000/upload'));
+
+		expect(response.status).toBe(499);
+	});
+});