@ecopages/core 0.2.0-alpha.26 → 0.2.0-alpha.27

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

@@ -1,162 +0,0 @@
-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 { 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;
-    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>;
-    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;
-    private getListeningServerOrigin;
-    /**
-     * 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.
-     * - 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
-     * 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

@@ -1,368 +0,0 @@
-import { createServer } from "node:http";
-import { appLogger } from "../../global/app-logger.js";
-import { NodeClientBridge } from "./node-client-bridge.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 {
-  bindSharedRuntimeHmrManager,
-  initializeSharedRuntimePlugins,
-  installSharedRuntimeBuildExecutor,
-  prepareSharedRuntimePublicDir,
-  startSharedProjectWatching
-} from "../shared/runtime-bootstrap.js";
-import { NodeStaticContentServer } from "./static-content-server.js";
-import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.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;
-  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() {
-    installSharedRuntimeBuildExecutor(this.appConfig, {
-      development: this.options?.watch === true
-    });
-    prepareSharedRuntimePublicDir(this.appConfig);
-    await initializeSharedRuntimePlugins({
-      appConfig: this.appConfig,
-      runtimeOrigin: this.runtimeOrigin,
-      hmrManager: this.hmrManager ?? void 0
-    });
-    await this.initializeSharedRouteHandling({
-      staticRoutes: this.staticRoutes,
-      hmrManager: this.hmrManager ?? void 0
-    });
-    this.staticSiteGenerator = new StaticSiteGenerator({ appConfig: this.appConfig });
-    this.staticBuilder = new ServerStaticBuilder({
-      appConfig: this.appConfig,
-      staticSiteGenerator: this.staticSiteGenerator,
-      serveOptions: this.serveOptions,
-      apiHandlers: this.apiHandlers
-    });
-    this.initialized = true;
-  }
-  getServerOptions() {
-    return {
-      ...this.serveOptions
-    };
-  }
-  async buildStatic(options) {
-    if (!this.initialized) {
-      await this.initialize();
-    }
-    const buildServer = await this.startBuildRuntimeServer();
-    const buildRuntimeOrigin = this.getListeningServerOrigin(buildServer);
-    try {
-      await this.staticBuilder.build(
-        { preview: false, baseUrl: buildRuntimeOrigin },
-        {
-          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 || DEFAULT_ECOPAGES_PORT)
-      }
-    });
-    await this.previewServer.start();
-    const previewHostname = this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME;
-    const previewPort = this.serveOptions.port || DEFAULT_ECOPAGES_PORT;
-    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 || DEFAULT_ECOPAGES_HOSTNAME);
-    const port = 0;
-    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 ${this.getListeningServerOrigin(server)}`);
-    return server;
-  }
-  getListeningServerOrigin(server) {
-    const address = server.address();
-    const hostname = String(this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME);
-    if (!address || typeof address === "string") {
-      throw new Error("Build runtime server did not expose a numeric listening port");
-    }
-    return `http://${hostname}:${address.port}`;
-  }
-  /**
-   * 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.
-   * - 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
-   * immediate socket destroy to prevent unhandled upgrade leaks.
-   */
-  async completeInitialization(server) {
-    this.serverInstance = server;
-    if (this.options?.watch) {
-      const { NodeHmrManager } = await import("./node-hmr-manager.js");
-      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();
-        }
-      });
-      bindSharedRuntimeHmrManager(this.appConfig, this.hmrManager);
-      this.configureSharedResponseHandlers(this.staticRoutes, this.hmrManager);
-      await startSharedProjectWatching({
-        appConfig: this.appConfig,
-        refreshRouterRoutesCallback: this.createSharedWatchRefreshCallback({
-          staticRoutes: this.staticRoutes,
-          hmrManager: this.hmrManager
-        }),
-        hmrManager: this.hmrManager,
-        bridge: this.bridge
-      });
-    }
-    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 || DEFAULT_ECOPAGES_HOSTNAME}:${params.serveOptions.port || DEFAULT_ECOPAGES_PORT}`;
-  const adapter = new NodeServerAdapter({
-    ...params,
-    runtimeOrigin
-  });
-  return adapter.createAdapter();
-}
-export {
-  NodeServerAdapter,
-  createNodeServerAdapter
-};

package/src/adapters/node/static-content-server.d.ts

@@ -1,60 +0,0 @@
-import { type Server as NodeHttpServer } from 'node:http';
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-type NodeStaticContentServerOptions = {
-    hostname?: string;
-    port?: number;
-};
-/**
- * Serves prebuilt static Ecopages output through Node's HTTP server.
- *
- * @remarks
- * This server is used by the Node preview/build path once the app has already
- * emitted its static output. It intentionally stays small: path sanitization,
- * content-type selection, optional gzip serving, and 404 handling.
- */
-export declare class NodeStaticContentServer {
-    private readonly appConfig;
-    private readonly options;
-    private server;
-    /**
-     * Creates the Node static-content server for one built app output directory.
-     */
-    constructor({ appConfig, options }: {
-        appConfig: EcoPagesAppConfig;
-        options?: NodeStaticContentServerOptions;
-    });
-    /**
-     * Returns whether the given content type should be served from a pre-gzipped
-     * companion file when available.
-     */
-    private shouldServeGzip;
-    /**
-     * Normalizes a request pathname and rejects directory traversal attempts.
-     */
-    private sanitizePath;
-    /**
-     * Writes one HTTP response with the provided headers and optional body.
-     */
-    private sendResponse;
-    /**
-     * Serves the generated 404 page when present, or a plain-text fallback.
-     */
-    private sendNotFoundPage;
-    /**
-     * Serves one concrete file path, honoring gzip and HEAD semantics.
-     */
-    private serveFile;
-    /**
-     * Handles one incoming Node HTTP request against the built static output tree.
-     */
-    private handleRequest;
-    /**
-     * Starts the static preview server.
-     */
-    start(): Promise<NodeHttpServer>;
-    /**
-     * Stops the static preview server and optionally closes active connections.
-     */
-    stop(force?: boolean): Promise<void>;
-}
-export {};