@ecopages/core 0.2.0-beta.9 → 0.2.0-rc.1

package/src/adapters/node/http-request-bridge.js

@@ -1,118 +1,159 @@
-import { Readable } from "node:stream";
-import { pipeline } from "node:stream/promises";
-class NodeClientAbortError extends Error {
-  /**
-   * Creates the canonical Node transport abort error used across request-body
-   * reads and response-body writes.
-   */
-  constructor() {
-    super("Client closed the request");
-    this.name = "ClientAbortError";
-  }
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+/**
+ * Signals that the remote client closed the HTTP exchange before the Node
+ * adapter finished reading or writing the body.
+ *
+ * @remarks
+ * This error represents a transport-level disconnect, not an application
+ * failure. Higher layers may safely suppress logging for this error when the
+ * client socket is already gone and no meaningful response can still be sent.
+ */
+export class NodeClientAbortError extends Error {
+    /**
+     * Creates the canonical Node transport abort error used across request-body
+     * reads and response-body writes.
+     */
+    constructor() {
+        super('Client closed the request');
+        this.name = 'ClientAbortError';
+    }
 }
+/**
+ * Returns whether a Node stream error code corresponds to a normal client-side
+ * disconnect rather than a server fault.
+ *
+ * @remarks
+ * The allowlist is intentionally narrow. Only socket and stream shutdown codes
+ * that are expected after browser aborts or navigation churn are treated as
+ * suppressible client disconnects.
+ */
 function isNodeClientDisconnectCode(code) {
-  return [
-    "ECONNRESET",
-    "EPIPE",
-    "ERR_STREAM_DESTROYED",
-    "ERR_STREAM_PREMATURE_CLOSE",
-    "ERR_STREAM_UNABLE_TO_PIPE"
-  ].includes(code ?? "");
+    return [
+        'ECONNRESET',
+        'EPIPE',
+        'ERR_STREAM_DESTROYED',
+        'ERR_STREAM_PREMATURE_CLOSE',
+        'ERR_STREAM_UNABLE_TO_PIPE',
+    ].includes(code ?? '');
 }
-function isNodeClientAbortError(error) {
-  return error instanceof NodeClientAbortError;
+/**
+ * Type guard for the canonical client-abort error used by the Node adapter.
+ *
+ * @remarks
+ * Runtime hosts use this guard before logging so only explicitly classified
+ * client disconnects are muted. All other failures continue through the normal
+ * error-reporting path.
+ */
+export function isNodeClientAbortError(error) {
+    return error instanceof NodeClientAbortError;
 }
+/**
+ * Normalizes low-level Node socket and stream shutdown errors into the shared
+ * `NodeClientAbortError` abstraction used by the adapter stack.
+ *
+ * @remarks
+ * This normalization exists at the transport boundary because Node exposes
+ * several host-specific error codes for the same underlying event: the client
+ * disappeared before the response stream finished. Converting them here keeps
+ * the rest of the adapter stack independent from those Node-specific details.
+ */
 function toNodeClientAbortError(error) {
-  if (error instanceof NodeClientAbortError) {
-    return error;
-  }
-  if (typeof error === "object" && error !== null && "code" in error) {
-    const code = typeof error.code === "string" ? error.code : void 0;
-    if (isNodeClientDisconnectCode(code)) {
-      return new NodeClientAbortError();
+    if (error instanceof NodeClientAbortError) {
+        return error;
     }
-  }
-  return null;
-}
-class NodeHttpRequestBridge {
-  /**
-   * Converts one incoming Node request into the Web `Request` shape consumed by
-   * the shared server adapter.
-   *
-   * @remarks
-   * Non-GET/HEAD requests retain streaming semantics via a `ReadableStream` so
-   * large request bodies do not need to be buffered before route handling begins.
-   */
-  createWebRequest(req, runtimeOrigin) {
-    const url = new URL(req.url ?? "/", runtimeOrigin);
-    const headers = new Headers();
-    for (const [key, value] of Object.entries(req.headers)) {
-      if (Array.isArray(value)) {
-        for (const item of value) {
-          headers.append(key, item);
+    if (typeof error === 'object' && error !== null && 'code' in error) {
+        const code = typeof error.code === 'string' ? error.code : undefined;
+        if (isNodeClientDisconnectCode(code)) {
+            return new NodeClientAbortError();
         }
-        continue;
-      }
-      if (value !== void 0) {
-        headers.set(key, value);
-      }
     }
-    const method = (req.method ?? "GET").toUpperCase();
-    const requestInit = {
-      method,
-      headers
-    };
-    if (method !== "GET" && method !== "HEAD") {
-      const body = new ReadableStream({
-        start(controller) {
-          req.on("data", (chunk) => controller.enqueue(chunk));
-          req.once("end", () => controller.close());
-          req.once("aborted", () => {
-            controller.error(new NodeClientAbortError());
-          });
-          req.once("error", (err) => {
-            const isClientAbort = err.code === "ECONNRESET";
-            controller.error(isClientAbort ? new NodeClientAbortError() : err);
-          });
-        },
-        cancel() {
-          req.destroy();
+    return null;
+}
+/**
+ * Bridges Node's `IncomingMessage` / `ServerResponse` pair to the Web
+ * `Request` / `Response` contract used by the shared routing pipeline.
+ *
+ * @remarks
+ * This class is the Node transport boundary. It owns the translation of request
+ * headers and bodies into Web primitives and the reverse translation of Web
+ * responses back onto Node streams, including client-abort normalization.
+ */
+export class NodeHttpRequestBridge {
+    /**
+     * Converts one incoming Node request into the Web `Request` shape consumed by
+     * the shared server adapter.
+     *
+     * @remarks
+     * Non-GET/HEAD requests retain streaming semantics via a `ReadableStream` so
+     * large request bodies do not need to be buffered before route handling begins.
+     */
+    createWebRequest(req, runtimeOrigin) {
+        const url = new URL(req.url ?? '/', runtimeOrigin);
+        const headers = new Headers();
+        for (const [key, value] of Object.entries(req.headers)) {
+            if (Array.isArray(value)) {
+                for (const item of value) {
+                    headers.append(key, item);
+                }
+                continue;
+            }
+            if (value !== undefined) {
+                headers.set(key, value);
+            }
         }
-      });
-      requestInit.body = body;
-      requestInit.duplex = "half";
-    }
-    return new Request(url, requestInit);
-  }
-  /**
-   * Sends a Web `Response` through Node's `ServerResponse` without buffering the
-   * full body in memory first.
-   *
-   * @remarks
-   * Streaming responses matter for large payloads and long-lived transports such
-   * as server-sent events. The bridge therefore forwards the `ReadableStream`
-   * directly into the Node writable response instead of materializing an
-   * intermediate `ArrayBuffer`.
-   */
-  async sendNodeResponse(res, response) {
-    res.statusCode = response.status;
-    response.headers.forEach((value, key) => {
-      res.setHeader(key, value);
-    });
-    if (!response.body) {
-      res.end();
-      return;
+        const method = (req.method ?? 'GET').toUpperCase();
+        const requestInit = {
+            method,
+            headers,
+        };
+        if (method !== 'GET' && method !== 'HEAD') {
+            const body = new ReadableStream({
+                start(controller) {
+                    req.on('data', (chunk) => controller.enqueue(chunk));
+                    req.once('end', () => controller.close());
+                    req.once('aborted', () => {
+                        controller.error(new NodeClientAbortError());
+                    });
+                    req.once('error', (err) => {
+                        const isClientAbort = err.code === 'ECONNRESET';
+                        controller.error(isClientAbort ? new NodeClientAbortError() : err);
+                    });
+                },
+                cancel() {
+                    req.destroy();
+                },
+            });
+            requestInit.body = body;
+            requestInit.duplex = 'half';
+        }
+        return new Request(url, requestInit);
     }
-    const responseBody = response.body;
-    try {
-      await pipeline(Readable.fromWeb(responseBody), res);
-    } catch (error) {
-      throw toNodeClientAbortError(error) ?? error;
+    /**
+     * Sends a Web `Response` through Node's `ServerResponse` without buffering the
+     * full body in memory first.
+     *
+     * @remarks
+     * Streaming responses matter for large payloads and long-lived transports such
+     * as server-sent events. The bridge therefore forwards the `ReadableStream`
+     * directly into the Node writable response instead of materializing an
+     * intermediate `ArrayBuffer`.
+     */
+    async sendNodeResponse(res, response) {
+        res.statusCode = response.status;
+        response.headers.forEach((value, key) => {
+            res.setHeader(key, value);
+        });
+        if (!response.body) {
+            res.end();
+            return;
+        }
+        const responseBody = response.body;
+        try {
+            await pipeline(Readable.fromWeb(responseBody), res);
+        }
+        catch (error) {
+            throw toNodeClientAbortError(error) ?? error;
+        }
     }
-  }
 }
-export {
-  NodeClientAbortError,
-  NodeHttpRequestBridge,
-  isNodeClientAbortError
-};

package/src/adapters/node/node-client-bridge.js

@@ -1,69 +1,67 @@
-const HEARTBEAT_INTERVAL_MS = 3e4;
-class NodeClientBridge {
-  subscribers = /* @__PURE__ */ new Set();
-  heartbeatTimer = null;
-  constructor() {
-    this.heartbeatTimer = setInterval(() => this.sweep(), HEARTBEAT_INTERVAL_MS);
-    this.heartbeatTimer.unref?.();
-  }
-  /**
-   * Pings all open subscribers and removes any that are no longer in OPEN state.
-   * This prevents a slow memory leak caused by zombie connections that never
-   * send a close event (e.g. abruptly killed browsers, orphaned tabs, network drops).
-   */
-  sweep() {
-    for (const ws of this.subscribers) {
-      if (ws.readyState !== 1) {
+const HEARTBEAT_INTERVAL_MS = 30_000;
+export class NodeClientBridge {
+    subscribers = new Set();
+    heartbeatTimer = null;
+    constructor() {
+        this.heartbeatTimer = setInterval(() => this.sweep(), HEARTBEAT_INTERVAL_MS);
+        /* Allow the process to exit even if the timer is still active */
+        this.heartbeatTimer.unref?.();
+    }
+    /**
+     * Pings all open subscribers and removes any that are no longer in OPEN state.
+     * This prevents a slow memory leak caused by zombie connections that never
+     * send a close event (e.g. abruptly killed browsers, orphaned tabs, network drops).
+     */
+    sweep() {
+        for (const ws of this.subscribers) {
+            if (ws.readyState !== 1 /* OPEN */) {
+                this.subscribers.delete(ws);
+                continue;
+            }
+            ws.ping();
+        }
+    }
+    subscribe(ws) {
+        this.subscribers.add(ws);
+    }
+    unsubscribe(ws) {
         this.subscribers.delete(ws);
-        continue;
-      }
-      ws.ping();
     }
-  }
-  subscribe(ws) {
-    this.subscribers.add(ws);
-  }
-  unsubscribe(ws) {
-    this.subscribers.delete(ws);
-  }
-  broadcast(event) {
-    const payload = JSON.stringify(event);
-    for (const ws of this.subscribers) {
-      if (ws.readyState === 1) {
-        ws.send(payload);
-      }
+    broadcast(event) {
+        const payload = JSON.stringify(event);
+        for (const ws of this.subscribers) {
+            if (ws.readyState === 1) {
+                ws.send(payload);
+            }
+        }
+    }
+    reload() {
+        this.broadcast({ type: 'reload' });
+    }
+    cssUpdate(path) {
+        this.broadcast({ type: 'css-update', path, timestamp: Date.now() });
+    }
+    update(path) {
+        this.broadcast({ type: 'update', path, timestamp: Date.now() });
+    }
+    error(message) {
+        this.broadcast({ type: 'error', message });
+    }
+    get subscriberCount() {
+        return this.subscribers.size;
+    }
+    /**
+     * Stops the heartbeat timer and clears all subscribers.
+     * Call this when the dev server is shutting down.
+     */
+    destroy() {
+        if (this.heartbeatTimer !== null) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        this.subscribers.clear();
     }
-  }
-  reload() {
-    this.broadcast({ type: "reload" });
-  }
-  cssUpdate(path) {
-    this.broadcast({ type: "css-update", path, timestamp: Date.now() });
-  }
-  update(path) {
-    this.broadcast({ type: "update", path, timestamp: Date.now() });
-  }
-  error(message) {
-    this.broadcast({ type: "error", message });
-  }
-  get subscriberCount() {
-    return this.subscribers.size;
-  }
-  /**
-   * Stops the heartbeat timer and clears all subscribers.
-   * Call this when the dev server is shutting down.
-   */
-  destroy() {
-    if (this.heartbeatTimer !== null) {
-      clearInterval(this.heartbeatTimer);
-      this.heartbeatTimer = null;
+    [Symbol.dispose]() {
+        this.destroy();
     }
-    this.subscribers.clear();
-  }
-  [Symbol.dispose]() {
-    this.destroy();
-  }
 }
-export {
-  NodeClientBridge
-};

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

@@ -1,10 +1,9 @@
 import type { EcoPagesAppConfig, IClientBridge } from '../../types/internal-types.js';
 import { InMemoryEntrypointDependencyGraph, type EntrypointDependencyGraph } from '../../services/runtime-state/entrypoint-dependency-graph.service.js';
-import { SharedHmrManager } from '../shared/shared-hmr-manager.js';
+import { SharedHmrManager } from '../shared/hmr/shared-hmr-manager.js';
 export interface NodeHmrManagerParams {
     appConfig: EcoPagesAppConfig;
     bridge: IClientBridge;
-    registrationTimeoutMs?: number;
 }
 /**
  * Node development HMR manager.
@@ -29,7 +28,7 @@ export declare class NodeHmrManager extends SharedHmrManager {
      * actually differs: dependency-graph storage, missing-file tolerance, and how
      * runtime bundle failures disable HMR.
      */
-    constructor({ appConfig, bridge, registrationTimeoutMs }: NodeHmrManagerParams);
+    constructor({ appConfig, bridge }: NodeHmrManagerParams);
     /**
      * Reuses the shared in-memory dependency graph when the app already has one and
      * otherwise creates the default Node development graph.

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

@@ -1,49 +1,59 @@
-import { appLogger } from "../../global/app-logger.js";
-import {
-  InMemoryEntrypointDependencyGraph
-} from "../../services/runtime-state/entrypoint-dependency-graph.service.js";
-import { SharedHmrManager } from "../shared/shared-hmr-manager.js";
-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, registrationTimeoutMs }) {
-    super({ appConfig, bridge, registrationTimeoutMs });
-  }
-  /**
-   * Reuses the shared in-memory dependency graph when the app already has one and
-   * otherwise creates the default Node development graph.
-   */
-  createEntrypointDependencyGraph(existingEntrypointDependencyGraph) {
-    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.
-   */
-  shouldSkipMissingFileChange(_filePath) {
-    return true;
-  }
-  /**
-   * Disables HMR after a runtime bundle failure so the Node dev server can keep
-   * serving requests without repeatedly emitting broken updates.
-   */
-  onRuntimeBundleFailure(error) {
-    this.enabled = false;
-    appLogger.error("[HMR] Failed to build runtime script; continuing with HMR disabled.", error);
-  }
+import { appLogger } from '../../global/app-logger.js';
+import { InMemoryEntrypointDependencyGraph, } from '../../services/runtime-state/entrypoint-dependency-graph.service.js';
+import { SharedHmrManager } from '../shared/hmr/shared-hmr-manager.js';
+/**
+ * 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 }) {
+        super({ appConfig, bridge });
+    }
+    /**
+     * Reuses the shared in-memory dependency graph when the app already has one and
+     * otherwise creates the default Node development graph.
+     */
+    createEntrypointDependencyGraph(existingEntrypointDependencyGraph) {
+        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.
+     */
+    shouldSkipMissingFileChange(_filePath) {
+        return true;
+    }
+    /**
+     * Disables HMR after a runtime bundle failure so the Node dev server can keep
+     * serving requests without repeatedly emitting broken updates.
+     */
+    onRuntimeBundleFailure(error) {
+        this.enabled = false;
+        appLogger.error('[HMR] Failed to build runtime script; continuing with HMR disabled.', error);
+    }
 }
-export {
-  NodeHmrManager
-};

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

@@ -1,5 +1,5 @@
 import { createServer, type Server as NodeServerInstance } from 'node:http';
-import type { RuntimeHost, RuntimeHostStartOptions } from '../shared/runtime-host.js';
+import type { RuntimeHost, RuntimeHostStartOptions } from '../shared/runtime/runtime-host.js';
 import { NodeHttpRequestBridge } from './http-request-bridge.js';
 type NodeServerFactory = typeof createServer;
 /**