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

package/src/adapters/node/create-app.js

@@ -0,0 +1,92 @@
+import { appLogger } from "../../global/app-logger.js";
+import { SharedApplicationAdapter } from "../shared/application-adapter.js";
+import { resolveRuntimeBinding } from "../shared/runtime-app-bootstrap.js";
+import { createNodeServerAdapter } from "./server-adapter.js";
+import { NodeHttpRequestBridge } from "./http-request-bridge.js";
+import { NodeRuntimeHost } from "./runtime-host.js";
+class NodeEcopagesApp extends SharedApplicationAdapter {
+  serverAdapter;
+  server = null;
+  runtimeOrigin = "";
+  runtimeHost;
+  constructor(options, dependencies) {
+    super(options);
+    this.runtimeHost = dependencies.runtimeHost;
+  }
+  createServerAdapter(params) {
+    return createNodeServerAdapter(params);
+  }
+  async stop(force = true) {
+    if (!this.server) {
+      return;
+    }
+    const activeServer = this.server;
+    this.server = null;
+    await this.runtimeHost.stop(activeServer, { force });
+  }
+  async initializeServerAdapter() {
+    const binding = resolveRuntimeBinding({
+      cliArgs: this.cliArgs,
+      serverOptions: this.serverOptions
+    });
+    this.runtimeOrigin = binding.runtimeOrigin;
+    return this.createServerAdapter({
+      runtimeOrigin: this.runtimeOrigin,
+      appConfig: this.appConfig,
+      apiHandlers: this.apiHandlers,
+      staticRoutes: this.staticRoutes,
+      errorHandler: this.errorHandler,
+      options: { watch: binding.watch },
+      serveOptions: binding.serveOptions
+    });
+  }
+  async start() {
+    if (!this.serverAdapter) {
+      this.serverAdapter = await this.initializeServerAdapter();
+    }
+    if (this.server) {
+      return this.server;
+    }
+    const { build, preview } = this.cliArgs;
+    if (build || preview) {
+      appLogger.debugTime("Building static pages");
+      await this.serverAdapter.buildStatic({ preview });
+      await this.stop(true);
+      appLogger.debugTimeEnd("Building static pages");
+      if (build) {
+        process.exit(0);
+      }
+      return;
+    }
+    const serveOptions = this.serverAdapter.getServerOptions();
+    this.server = await this.runtimeHost.start({
+      serveOptions,
+      handleRequest: async (request) => await this.serverAdapter.handleRequest(request),
+      onError: async () => {
+      }
+    });
+    this.runtimeOrigin = this.runtimeHost.getOrigin(this.server, serveOptions);
+    await this.serverAdapter.completeInitialization(this.server);
+    appLogger.info(`Node server running at ${this.runtimeOrigin}`);
+    return this.server;
+  }
+  async fetch(request) {
+    if (!this.serverAdapter) {
+      this.serverAdapter = await this.initializeServerAdapter();
+    }
+    return this.serverAdapter.handleRequest(request);
+  }
+}
+async function createNodeApp(options) {
+  return new NodeEcopagesApp(options, {
+    runtimeHost: new NodeRuntimeHost(new NodeHttpRequestBridge())
+  });
+}
+async function createApp(options) {
+  return createNodeApp(options);
+}
+export {
+  NodeEcopagesApp,
+  createApp,
+  createNodeApp
+};

package/src/adapters/node/http-request-bridge.d.ts

@@ -0,0 +1,57 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/**
+ * 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 declare class NodeClientAbortError extends Error {
+    /**
+     * Creates the canonical Node transport abort error used across request-body
+     * reads and response-body writes.
+     */
+    constructor();
+}
+/**
+ * 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 declare function isNodeClientAbortError(error: unknown): error is NodeClientAbortError;
+/**
+ * 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 declare 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: IncomingMessage, runtimeOrigin: string): Request;
+    /**
+     * 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`.
+     */
+    sendNodeResponse(res: ServerResponse, response: Response): Promise<void>;
+}

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

@@ -0,0 +1,118 @@
+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";
+  }
+}
+function isNodeClientDisconnectCode(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;
+}
+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();
+    }
+  }
+  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);
+        }
+        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();
+        }
+      });
+      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 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.d.ts

@@ -0,0 +1,26 @@
+import type { WebSocket } from 'ws';
+import type { ClientBridgeEvent, IClientBridge } from '../../types/public-types.js';
+export declare class NodeClientBridge implements IClientBridge {
+    private subscribers;
+    private heartbeatTimer;
+    constructor();
+    /**
+     * 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).
+     */
+    private sweep;
+    subscribe(ws: WebSocket): void;
+    unsubscribe(ws: WebSocket): void;
+    broadcast(event: ClientBridgeEvent): void;
+    reload(): void;
+    cssUpdate(path: string): void;
+    update(path: string): void;
+    error(message: string): void;
+    get subscriberCount(): number;
+    /**
+     * Stops the heartbeat timer and clears all subscribers.
+     * Call this when the dev server is shutting down.
+     */
+    destroy(): void;
+}

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

@@ -0,0 +1,66 @@
+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) {
+        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);
+      }
+    }
+  }
+  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();
+  }
+}
+export {
+  NodeClientBridge
+};

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

@@ -0,0 +1,52 @@
+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';
+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 declare 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);
+    /**
+     * Reuses the shared in-memory dependency graph when the app already has one and
+     * otherwise creates the default Node development graph.
+     */
+    protected createEntrypointDependencyGraph(existingEntrypointDependencyGraph: EntrypointDependencyGraph): 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 shouldSkipMissingFileChange(_filePath: string): boolean;
+    /**
+     * Disables HMR after a runtime bundle failure so the Node dev server can keep
+     * serving requests without repeatedly emitting broken updates.
+     */
+    protected onRuntimeBundleFailure(error: unknown): void;
+}

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

@@ -0,0 +1,49 @@
+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 }) {
+    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

@@ -0,0 +1,57 @@
+import { createServer, type Server as NodeServerInstance } from 'node:http';
+import type { RuntimeHost, RuntimeHostStartOptions } from '../shared/runtime-host.js';
+import { NodeHttpRequestBridge } from './http-request-bridge.js';
+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 declare class NodeRuntimeHost implements RuntimeHost<NodeServerInstance, {
+    port?: number;
+    hostname?: string;
+}> {
+    private readonly requestBridge;
+    private readonly serverFactory;
+    /**
+     * Creates a Node runtime host with injectable request bridging and server
+     * creation seams for tests and alternate hosts.
+     */
+    constructor(requestBridge: NodeHttpRequestBridge, serverFactory?: NodeServerFactory);
+    /**
+     * 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.
+     */
+    start(options: RuntimeHostStartOptions<{
+        port?: number;
+        hostname?: string;
+    }>): Promise<NodeServerInstance>;
+    /**
+     * Stops the Node HTTP server and, by default, force-closes any remaining open
+     * connections.
+     */
+    stop(server: NodeServerInstance, options?: {
+        force?: boolean;
+    }): Promise<void>;
+    /**
+     * 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: NodeServerInstance, fallbackServeOptions: {
+        port?: number;
+        hostname?: string;
+    }): string;
+}
+export {};

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

@@ -0,0 +1,92 @@
+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;
+        }
+        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
+    });
+  }
+}
+export {
+  NodeRuntimeHost
+};

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

@@ -0,0 +1,19 @@
+import { WebSocketServer } from 'ws';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import { NodeClientBridge } from './node-client-bridge.js';
+import { NodeHmrManager } from './node-hmr-manager.js';
+export interface NodeServerDevRuntime {
+    websocketServer: WebSocketServer;
+    bridge: NodeClientBridge;
+    hmrManager: NodeHmrManager;
+}
+export interface NodeServerDevRuntimeFactory {
+    create(options: {
+        appConfig: EcoPagesAppConfig;
+    }): NodeServerDevRuntime;
+}
+export declare class DefaultNodeServerDevRuntimeFactory implements NodeServerDevRuntimeFactory {
+    create(options: {
+        appConfig: EcoPagesAppConfig;
+    }): NodeServerDevRuntime;
+}

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

@@ -0,0 +1,18 @@
+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
+    };
+  }
+}
+export {
+  DefaultNodeServerDevRuntimeFactory
+};