@ecopages/core 0.2.0-alpha.1

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

@@ -0,0 +1,190 @@
+import { type Server as NodeHttpServer } from 'node:http';
+import type { EcoPagesAppConfig } from '../../internal-types.js';
+import type { ApiHandler, ErrorHandler, StaticRoute } from '../../public-types.js';
+import { SharedServerAdapter } from '../shared/server-adapter.js';
+import type { ServerAdapterResult } from '../abstract/server-adapter.js';
+export type NodeServerInstance = NodeHttpServer;
+export type NodeServeAdapterServerOptions = {
+    port?: number;
+    hostname?: string;
+    [key: string]: unknown;
+};
+export interface NodeServerAdapterParams {
+    appConfig: EcoPagesAppConfig;
+    runtimeOrigin: string;
+    serveOptions: NodeServeAdapterServerOptions;
+    apiHandlers?: ApiHandler[];
+    staticRoutes?: StaticRoute[];
+    errorHandler?: ErrorHandler;
+    options?: {
+        watch?: boolean;
+    };
+}
+export interface NodeServerAdapterResult extends ServerAdapterResult {
+    completeInitialization: (server: NodeServerInstance) => Promise<void>;
+    handleRequest: (request: Request) => Promise<Response>;
+}
+/**
+ * Node.js HTTP server adapter for the Ecopages runtime.
+ *
+ * `NodeServerAdapter` bridges the Node.js `http` module and the Ecopages
+ * `SharedServerAdapter` abstraction, translating between Node's
+ * `IncomingMessage`/`ServerResponse` API and the platform-agnostic Web
+ * `Request`/`Response` model.
+ *
+ * Lifecycle:
+ * 1. `createAdapter()` — calls `initialize()` and returns the public adapter result.
+ * 2. `completeInitialization(server)` — called once the HTTP server is listening.
+ *    Conditionally wires HMR, WebSocket upgrades, and the file watcher when
+ *    `options.watch` is `true`.
+ * 3. `handleRequest(request)` — delegates to `handleSharedRequest` for routing;
+ *    intercepts `ClientAbortError` to return 499 instead of 500.
+ * 4. `buildStatic()` — spins up an ephemeral runtime server, generates all static
+ *    pages against it, then tears it down.
+ *
+ * @see SharedServerAdapter for routing, caching and response handler logic.
+ */
+export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAdapterParams, NodeServerAdapterResult> {
+    private serverInstance;
+    private initialized;
+    private apiHandlers;
+    private staticRoutes;
+    private errorHandler?;
+    private previewServer;
+    private bridge;
+    private hmrManager;
+    private processorBuildPlugins;
+    constructor(options: NodeServerAdapterParams);
+    /**
+     * Prepares the adapter for use.
+     *
+     * Order is intentional:
+     * 1. **Loaders** are registered first so processors and integrations can
+     *    reference loader-provided file types in their own plugins.
+     * 2. **Public dir** is copied before any build so static assets are in `distDir`
+     *    before the first request arrives.
+     * 3. **Plugins** (processors, then integrations) are set up after the public dir
+     *    is in place so they can safely reference dist-relative paths.
+     * 4. **Router** is initialised last because it may depend on files written by
+     *    processors during their `setup()` calls.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Registers every configured file loader as a build plugin on the shared
+     * `defaultBuildAdapter`.
+     *
+     * Loaders are registered on the *shared* adapter (not on a per-build instance)
+     * because they must be available globally to both the SSR build and any dynamic
+     * transpile passes that happen outside of a top-level `build()` call (e.g. HMR
+     * incremental rebuilds).
+     */
+    private setupLoaders;
+    private copyPublicDir;
+    /**
+     * Sets up all configured processors and integrations in two distinct phases.
+     *
+     * **Phase 1 — Processors:**
+     * Each processor's `setup()` is called first. A processor may expose two
+     * plugin lists:
+     * - `plugins` — transform plugins used during SSR rendering (e.g. PostCSS).
+     * - `buildPlugins` — esbuild plugins used during the client bundle step.
+     * Both are registered on `defaultBuildAdapter` so later build calls pick them up.
+     *
+     * **Phase 2 — Integrations:**
+     * Integrations receive the fully-resolved app config, the runtime origin, and
+     * (if already initialised) the HMR manager before their own `setup()` is called.
+     * This ordering ensures integrations can query config values that processors
+     * may have mutated during phase 1.
+     */
+    private initializePlugins;
+    getServerOptions(): NodeServeAdapterServerOptions;
+    buildStatic(options?: {
+        preview?: boolean;
+    }): Promise<void>;
+    /**
+     * Converts a Node.js `IncomingMessage` into a Web API `Request`.
+     *
+     * Multi-value headers (e.g. `set-cookie`) are appended individually so no
+     * value is silently dropped.
+     *
+     * For methods that carry a body (`POST`, `PUT`, `PATCH`, …), the raw
+     * `IncomingMessage` stream is wrapped in a `ReadableStream` rather than
+     * cast directly to `BodyInit`. See the inline doc block inside the `if`
+     * branch for the rationale (client-abort handling).
+     *
+     * `duplex: 'half'` is required by the `fetch` spec when a streaming body is
+     * provided — without it Node.js 18+ throws a `TypeError`.
+     */
+    private createWebRequest;
+    /**
+     * Writes a Web `Response` back to a Node.js `ServerResponse`.
+     *
+     * The entire body is buffered via `arrayBuffer()` before writing. This is
+     * intentional for the current use-case (SSR pages and API routes), where
+     * responses are typically small and fully materialised. Streaming responses
+     * are not yet supported.
+     */
+    private sendNodeResponse;
+    /**
+     * Starts an ephemeral HTTP server used *only* during a static site generation
+     * run.
+     *
+     * Static generation works by having the `StaticSiteGenerator` issue real HTTP
+     * requests to a live server for each route, capturing the rendered HTML. This
+     * approach reuses the normal request pipeline (middleware, caching, API
+     * handlers) without any special-casing for the build path.
+     *
+     * The server is torn down immediately after generation completes via
+     * `stopBuildRuntimeServer`, so it never overlaps with the actual dev/prod server.
+     */
+    private startBuildRuntimeServer;
+    /**
+     * 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.
+     */
+    private stopBuildRuntimeServer;
+    createAdapter(): Promise<NodeServerAdapterResult>;
+    /**
+     * Handles a single incoming Web `Request` and returns a Web `Response`.
+     *
+     * Delegates to `handleSharedRequest` for all routing, caching, and response
+     * handler logic. The only Node-specific concern here is translating a
+     * `ClientAbortError` — which the body `ReadableStream` raises when the
+     * underlying socket closes early — into a 499 response so it does not
+     * incorrectly surface as a 500 in application logs.
+     */
+    handleRequest(_request: Request): Promise<Response>;
+    /**
+     * Called once the HTTP server is bound and listening.
+     *
+     * When `options.watch` is `true` this method wires the full HMR pipeline:
+     * - A `WebSocketServer` is attached to the existing HTTP server via the
+     *   `upgrade` event (no separate port needed).
+     * - `NodeClientBridge` tracks active WebSocket connections and handles
+     *   broadcast + heartbeat cleanup.
+     * - `NodeHmrManager` watches the filesystem and triggers incremental esbuild
+     *   rebuilds, notifying connected clients via the bridge.
+     * - `ProjectWatcher` 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
+     * immediate socket destroy to prevent unhandled upgrade leaks.
+     */
+    completeInitialization(_server: NodeServerInstance): Promise<void>;
+}
+/**
+ * Factory function that creates and fully initialises a `NodeServerAdapter`.
+ *
+ * `runtimeOrigin` is derived from `serveOptions` when not explicitly provided,
+ * so callers only need to set it when the server is behind a reverse proxy that
+ * changes the effective host or port.
+ */
+export declare function createNodeServerAdapter(params: NodeServerAdapterParams): Promise<NodeServerAdapterResult>;

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

@@ -0,0 +1,420 @@
+import { createServer } from "node:http";
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { RESOLVED_ASSETS_DIR } from "../../constants.js";
+import { defaultBuildAdapter } from "../../build/build-adapter.js";
+import { appLogger } from "../../global/app-logger.js";
+import { ProjectWatcher } from "../../watchers/project-watcher.js";
+import { NodeClientBridge } from "./node-client-bridge.js";
+import { NodeHmrManager } from "./node-hmr-manager.js";
+import { StaticSiteGenerator } from "../../static-site-generator/static-site-generator.js";
+import { SharedServerAdapter } from "../shared/server-adapter.js";
+import { ServerStaticBuilder } from "../shared/server-static-builder.js";
+import { NodeStaticContentServer } from "./static-content-server.js";
+class ClientAbortError extends Error {
+  constructor() {
+    super("Client closed the request");
+    this.name = "ClientAbortError";
+  }
+}
+class NodeServerAdapter extends SharedServerAdapter {
+  serverInstance = null;
+  initialized = false;
+  apiHandlers;
+  staticRoutes;
+  errorHandler;
+  previewServer = null;
+  bridge = null;
+  hmrManager = null;
+  processorBuildPlugins = [];
+  constructor(options) {
+    super(options);
+    this.apiHandlers = options.apiHandlers || [];
+    this.staticRoutes = options.staticRoutes || [];
+    this.errorHandler = options.errorHandler;
+  }
+  /**
+   * Prepares the adapter for use.
+   *
+   * Order is intentional:
+   * 1. **Loaders** are registered first so processors and integrations can
+   *    reference loader-provided file types in their own plugins.
+   * 2. **Public dir** is copied before any build so static assets are in `distDir`
+   *    before the first request arrives.
+   * 3. **Plugins** (processors, then integrations) are set up after the public dir
+   *    is in place so they can safely reference dist-relative paths.
+   * 4. **Router** is initialised last because it may depend on files written by
+   *    processors during their `setup()` calls.
+   */
+  async initialize() {
+    this.setupLoaders();
+    this.copyPublicDir();
+    await this.initializePlugins();
+    await this.initSharedRouter();
+    this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager ?? void 0);
+    this.staticSiteGenerator = new StaticSiteGenerator({ appConfig: this.appConfig });
+    this.staticBuilder = new ServerStaticBuilder({
+      appConfig: this.appConfig,
+      staticSiteGenerator: this.staticSiteGenerator,
+      serveOptions: this.serveOptions
+    });
+    this.initialized = true;
+  }
+  /**
+   * Registers every configured file loader as a build plugin on the shared
+   * `defaultBuildAdapter`.
+   *
+   * Loaders are registered on the *shared* adapter (not on a per-build instance)
+   * because they must be available globally to both the SSR build and any dynamic
+   * transpile passes that happen outside of a top-level `build()` call (e.g. HMR
+   * incremental rebuilds).
+   */
+  setupLoaders() {
+    for (const loader of this.appConfig.loaders.values()) {
+      defaultBuildAdapter.registerPlugin(loader);
+    }
+  }
+  copyPublicDir() {
+    const srcPublicDir = path.join(this.appConfig.rootDir, this.appConfig.srcDir, this.appConfig.publicDir);
+    if (fileSystem.exists(srcPublicDir)) {
+      fileSystem.copyDir(srcPublicDir, path.join(this.appConfig.rootDir, this.appConfig.distDir));
+    }
+    fileSystem.ensureDir(path.join(this.appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
+  }
+  /**
+   * Sets up all configured processors and integrations in two distinct phases.
+   *
+   * **Phase 1 — Processors:**
+   * Each processor's `setup()` is called first. A processor may expose two
+   * plugin lists:
+   * - `plugins` — transform plugins used during SSR rendering (e.g. PostCSS).
+   * - `buildPlugins` — esbuild plugins used during the client bundle step.
+   * Both are registered on `defaultBuildAdapter` so later build calls pick them up.
+   *
+   * **Phase 2 — Integrations:**
+   * Integrations receive the fully-resolved app config, the runtime origin, and
+   * (if already initialised) the HMR manager before their own `setup()` is called.
+   * This ordering ensures integrations can query config values that processors
+   * may have mutated during phase 1.
+   */
+  async initializePlugins() {
+    const processorBuildPlugins = [];
+    for (const processor of this.appConfig.processors.values()) {
+      await processor.setup();
+      if (processor.plugins) {
+        for (const plugin of processor.plugins) {
+          defaultBuildAdapter.registerPlugin(plugin);
+        }
+      }
+      if (processor.buildPlugins) {
+        processorBuildPlugins.push(...processor.buildPlugins);
+        for (const plugin of processor.buildPlugins) {
+          defaultBuildAdapter.registerPlugin(plugin);
+        }
+      }
+    }
+    for (const integration of this.appConfig.integrations) {
+      integration.setConfig(this.appConfig);
+      integration.setRuntimeOrigin(this.runtimeOrigin);
+      if (this.hmrManager) {
+        integration.setHmrManager(this.hmrManager);
+      }
+      await integration.setup();
+      for (const plugin of integration.plugins) {
+        defaultBuildAdapter.registerPlugin(plugin);
+      }
+    }
+    this.processorBuildPlugins = processorBuildPlugins;
+  }
+  getServerOptions() {
+    return {
+      ...this.serveOptions
+    };
+  }
+  async buildStatic(options) {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+    const buildServer = await this.startBuildRuntimeServer();
+    try {
+      await this.staticBuilder.build(
+        { preview: false },
+        {
+          router: this.router,
+          routeRendererFactory: this.routeRendererFactory,
+          staticRoutes: this.staticRoutes
+        }
+      );
+    } finally {
+      await this.stopBuildRuntimeServer(buildServer);
+    }
+    if (!options?.preview) {
+      return;
+    }
+    if (this.previewServer) {
+      await this.previewServer.stop();
+    }
+    this.previewServer = new NodeStaticContentServer({
+      appConfig: this.appConfig,
+      options: {
+        hostname: this.serveOptions.hostname,
+        port: Number(this.serveOptions.port || 3e3)
+      }
+    });
+    await this.previewServer.start();
+    const previewHostname = this.serveOptions.hostname || "localhost";
+    const previewPort = this.serveOptions.port || 3e3;
+    appLogger.info(`Preview running at http://${previewHostname}:${previewPort}`);
+  }
+  /**
+   * Converts a Node.js `IncomingMessage` into a Web API `Request`.
+   *
+   * Multi-value headers (e.g. `set-cookie`) are appended individually so no
+   * value is silently dropped.
+   *
+   * For methods that carry a body (`POST`, `PUT`, `PATCH`, …), the raw
+   * `IncomingMessage` stream is wrapped in a `ReadableStream` rather than
+   * cast directly to `BodyInit`. See the inline doc block inside the `if`
+   * branch for the rationale (client-abort handling).
+   *
+   * `duplex: 'half'` is required by the `fetch` spec when a streaming body is
+   * provided — without it Node.js 18+ throws a `TypeError`.
+   */
+  createWebRequest(req) {
+    const url = new URL(req.url ?? "/", this.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 ClientAbortError());
+          });
+          req.once("error", (err) => {
+            const isClientAbort = err.code === "ECONNRESET";
+            controller.error(isClientAbort ? new ClientAbortError() : err);
+          });
+        },
+        cancel() {
+          req.destroy();
+        }
+      });
+      requestInit.body = body;
+      requestInit.duplex = "half";
+    }
+    return new Request(url, requestInit);
+  }
+  /**
+   * Writes a Web `Response` back to a Node.js `ServerResponse`.
+   *
+   * The entire body is buffered via `arrayBuffer()` before writing. This is
+   * intentional for the current use-case (SSR pages and API routes), where
+   * responses are typically small and fully materialised. Streaming responses
+   * are not yet supported.
+   */
+  async sendNodeResponse(res, response) {
+    res.statusCode = response.status;
+    response.headers.forEach((value, key) => {
+      res.setHeader(key, value);
+    });
+    if (!response.body) {
+      res.end();
+      return;
+    }
+    const body = Buffer.from(await response.arrayBuffer());
+    res.end(body);
+  }
+  /**
+   * Starts an ephemeral HTTP server used *only* during a static site generation
+   * run.
+   *
+   * Static generation works by having the `StaticSiteGenerator` issue real HTTP
+   * requests to a live server for each route, capturing the rendered HTML. This
+   * approach reuses the normal request pipeline (middleware, caching, API
+   * handlers) without any special-casing for the build path.
+   *
+   * The server is torn down immediately after generation completes via
+   * `stopBuildRuntimeServer`, so it never overlaps with the actual dev/prod server.
+   */
+  async startBuildRuntimeServer() {
+    const hostname = String(this.serveOptions.hostname || "localhost");
+    const port = Number(this.serveOptions.port || 3e3);
+    const server = createServer(async (req, res) => {
+      try {
+        const webRequest = this.createWebRequest(req);
+        const response = await this.handleRequest(webRequest);
+        await this.sendNodeResponse(res, response);
+      } catch (error) {
+        appLogger.error("Node static build runtime request failed", error);
+        res.statusCode = 500;
+        res.end("Internal Server Error");
+      }
+    });
+    await new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(port, hostname, () => {
+        server.off("error", reject);
+        resolve();
+      });
+    });
+    this.serverInstance = server;
+    appLogger.info(`Server running at http://${hostname}:${port}`);
+    return server;
+  }
+  /**
+   * 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.
+   */
+  async stopBuildRuntimeServer(server) {
+    await new Promise((resolve, reject) => {
+      server.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+      server.closeAllConnections();
+    });
+    if (this.serverInstance === server) {
+      this.serverInstance = null;
+    }
+    this.bridge?.destroy();
+    this.bridge = null;
+  }
+  async createAdapter() {
+    await this.initialize();
+    return {
+      getServerOptions: this.getServerOptions.bind(this),
+      buildStatic: this.buildStatic.bind(this),
+      completeInitialization: this.completeInitialization.bind(this),
+      handleRequest: this.handleRequest.bind(this)
+    };
+  }
+  /**
+   * Handles a single incoming Web `Request` and returns a Web `Response`.
+   *
+   * Delegates to `handleSharedRequest` for all routing, caching, and response
+   * handler logic. The only Node-specific concern here is translating a
+   * `ClientAbortError` — which the body `ReadableStream` raises when the
+   * underlying socket closes early — into a 499 response so it does not
+   * incorrectly surface as a 500 in application logs.
+   */
+  async handleRequest(_request) {
+    if (!this.initialized) {
+      throw new Error("Node server adapter is not initialized. Call createAdapter() first.");
+    }
+    try {
+      return await this.handleSharedRequest(_request, {
+        apiHandlers: this.apiHandlers,
+        errorHandler: this.errorHandler,
+        serverInstance: this.serverInstance,
+        hmrManager: this.hmrManager
+      });
+    } catch (error) {
+      if (error instanceof ClientAbortError) {
+        return new Response(null, { status: 499 });
+      }
+      throw error;
+    }
+  }
+  /**
+   * Called once the HTTP server is bound and listening.
+   *
+   * When `options.watch` is `true` this method wires the full HMR pipeline:
+   * - A `WebSocketServer` is attached to the existing HTTP server via the
+   *   `upgrade` event (no separate port needed).
+   * - `NodeClientBridge` tracks active WebSocket connections and handles
+   *   broadcast + heartbeat cleanup.
+   * - `NodeHmrManager` watches the filesystem and triggers incremental esbuild
+   *   rebuilds, notifying connected clients via the bridge.
+   * - `ProjectWatcher` 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
+   * immediate socket destroy to prevent unhandled upgrade leaks.
+   */
+  async completeInitialization(_server) {
+    this.serverInstance = _server;
+    if (this.options?.watch) {
+      const { WebSocketServer } = await import("ws");
+      const wss = new WebSocketServer({ noServer: true });
+      this.bridge = new NodeClientBridge();
+      this.hmrManager = new NodeHmrManager({ appConfig: this.appConfig, bridge: this.bridge });
+      this.hmrManager.setEnabled(true);
+      await this.hmrManager.buildRuntime();
+      _server.on("upgrade", (req, socket, head) => {
+        const url = new URL(req.url ?? "/", this.runtimeOrigin);
+        if (url.pathname === "/_hmr") {
+          wss.handleUpgrade(req, socket, head, (ws) => {
+            this.bridge.subscribe(ws);
+            ws.on("close", () => this.bridge.unsubscribe(ws));
+            ws.on("error", (err) => appLogger.error("[HMR] WebSocket error:", err));
+          });
+        } else {
+          socket.destroy();
+        }
+      });
+      const loaderPlugins = Array.from(this.appConfig.loaders.values());
+      const hmrBuildPlugins = [...loaderPlugins, ...this.processorBuildPlugins];
+      this.hmrManager.setPlugins(hmrBuildPlugins);
+      for (const integration of this.appConfig.integrations) {
+        integration.setHmrManager(this.hmrManager);
+      }
+      this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager);
+      const watcher = new ProjectWatcher({
+        config: this.appConfig,
+        refreshRouterRoutesCallback: async () => {
+          await this.initSharedRouter();
+          this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager);
+        },
+        hmrManager: this.hmrManager,
+        bridge: this.bridge
+      });
+      await watcher.createWatcherSubscription();
+    }
+    appLogger.debug("Node server adapter initialization completed", {
+      apiHandlers: this.apiHandlers.length,
+      staticRoutes: this.staticRoutes.length,
+      hasErrorHandler: !!this.errorHandler,
+      hmrEnabled: !!this.hmrManager?.isEnabled()
+    });
+  }
+}
+async function createNodeServerAdapter(params) {
+  const runtimeOrigin = params.runtimeOrigin ?? `http://${params.serveOptions.hostname || "localhost"}:${params.serveOptions.port || 3e3}`;
+  const adapter = new NodeServerAdapter({
+    ...params,
+    runtimeOrigin
+  });
+  return adapter.createAdapter();
+}
+export {
+  NodeServerAdapter,
+  createNodeServerAdapter
+};