@ecopages/core 0.2.0-beta.3 → 0.2.0-beta.30

package/src/adapters/shared/{server-static-builder.d.ts → runtime/server-static-builder.d.ts}

@@ -1,11 +1,12 @@
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { ApiHandler, StaticRoute } from '../../types/public-types.js';
-import type { RouteRegistry } from '../../router/server/route-registry.js';
-import type { StaticSiteGenerator } from '../../static-site-generator/static-site-generator.js';
-import type { StaticGenerationRendererResolver } from '../../route-renderer/route-renderer.js';
+import type { EcoPagesAppConfig, IHmrManager } from '../../../types/internal-types.js';
+import type { EcoBuildPlugin } from '../../../build/contracts/build-types.js';
+import type { StaticRoute } from '../../../types/public-types.js';
+import type { RouteRegistry } from '../../../router/server/route-registry.js';
+import type { StaticSiteGenerator } from '../../../static-site-generator/static-site-generator.js';
+import type { StaticGenerationRendererResolver } from '../../../route-renderer/route-renderer.js';
 export interface StaticBuildOptions {
-    preview?: boolean;
     baseUrl?: string;
+    force?: boolean;
 }
 export interface ServeOptions {
     hostname?: string;
@@ -15,10 +16,17 @@ export interface ServerStaticBuilderParams {
     appConfig: EcoPagesAppConfig;
     staticSiteGenerator: StaticSiteGenerator;
     serveOptions: ServeOptions;
-    apiHandlers?: ApiHandler[];
+    runtimeOrigin: string;
+    /**
+     * Whether the app requires a server entry bundle for production use.
+     * When `true`, the build step bundles the server entry file for `ecopages start`.
+     * Defaults to `false` (static-only build, no server needed).
+     */
+    needsServerBundle?: boolean;
     logger?: ServerStaticBuilderLogger;
-    previewServerFactory?: ServerStaticPreviewServerFactory;
     entryFile?: string;
+    hmrManager?: IHmrManager;
+    onRuntimePlugin?: (plugin: EcoBuildPlugin) => void;
 }
 /**
  * Minimal logger dependency used by the static builder.
@@ -26,53 +34,38 @@ export interface ServerStaticBuilderParams {
 export interface ServerStaticBuilderLogger {
     warn(message: string, detail?: string): unknown;
     info(message: string): unknown;
+    debug(message: string): unknown;
     error(message: string): unknown;
 }
 /**
- * Preview server factory dependency used when static preview mode is enabled.
- */
-export interface ServerStaticPreviewServerFactory {
-    createServer(args: {
-        appConfig: EcoPagesAppConfig;
-        options: {
-            port: number;
-        };
-    }): {
-        server?: {
-            port?: number;
-        } | null;
-    };
-}
-/**
- * Handles static site generation and previews.
+ * Handles static site generation.
  */
 export declare class ServerStaticBuilder {
     private readonly appConfig;
     private readonly staticSiteGenerator;
     private readonly serveOptions;
-    private readonly apiHandlers;
+    private readonly runtimeOrigin;
+    private readonly needsServerBundle;
     private readonly logger;
-    private readonly previewServerFactory;
     private readonly entryFile;
-    constructor({ appConfig, staticSiteGenerator, serveOptions, apiHandlers, logger, previewServerFactory, entryFile, }: ServerStaticBuilderParams);
-    private warnApiHandlersUnavailableInStaticMode;
+    private readonly hmrManager?;
+    private readonly onRuntimePlugin?;
+    constructor({ appConfig, staticSiteGenerator, serveOptions, runtimeOrigin, needsServerBundle, logger, entryFile, hmrManager, onRuntimePlugin, }: ServerStaticBuilderParams);
     private prepareExportDirectory;
     private refreshRuntimeAssets;
     /**
      * Bundles the server entry file for production use.
      *
      * @remarks
-     * When the project has API endpoints, the entry file must be bundled
-     * into a single JS file so the production server can start without
-     * on-the-fly TypeScript transpilation. The bundle is output to
-     * `dist/{SERVER_BUNDLE_DIR}/{SERVER_BUNDLE_FILENAME}` and used by
-     * `ecopages start` in production.
+     * Only invoked when the app requires a runtime server (API handlers,
+     * websocket handlers, etc.). Static-only apps skip this step entirely.
+     * Incremental builds may skip Rolldown when the `.eco/.server-entry`
+     * cache is still valid.
      *
      * Package imports remain external so native addons and runtime-owned
      * dependencies continue to load through the app's installed
      * `node_modules` tree. Only the app entry graph is bundled.
      *
-     * Skips silently when no API endpoints are registered (static-only site).
      * Throws if the build adapter is unavailable, is owned by a host
      * runtime, or bundling fails.
      *
@@ -81,7 +74,6 @@ export declare class ServerStaticBuilder {
     private bundleServerEntry;
     /**
      * Generates a static build of the site for deployment.
-     * @param options.preview - If true, starts a preview server after build
      * @param dependencies.router - The initialized router
      * @param dependencies.routeRendererFactory - The route renderer factory
      * @param dependencies.staticRoutes - Explicit static routes registered via app.static()

package/src/adapters/shared/runtime/server-static-builder.js

@@ -0,0 +1,191 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../../config/constants.js";
+import { appLogger } from "../../../global/app-logger.js";
+import { build, getAppBuildAdapter, setupAppRuntimePlugins } from "../../../build/build-adapter.js";
+import { createServerBuildRequest } from "../../../build/runtime/build-request-policy.js";
+import { requireBuildRuntime } from "../../../build/runtime/build-runtime.js";
+import { attachHmrToIntegrations } from "./runtime-server-lifecycle.js";
+import {
+  getServerBundleOutputPaths,
+  lookupServerEntryBuildCache,
+  recordServerEntryBuildCache,
+  writeServerBundleDeployManifest
+} from "../../../build/cache/server-entry-build-cache.js";
+import {
+  clearProductionBuildCaches,
+  shouldResetStaticExportDirectory
+} from "../../../static-site-generator/static-build-invalidation.js";
+import { resolveEntryFile, SERVER_BUNDLE_FILENAME } from "../../../utils/resolve-entry-file.js";
+class ServerStaticBuilder {
+  appConfig;
+  staticSiteGenerator;
+  serveOptions;
+  runtimeOrigin;
+  needsServerBundle;
+  logger;
+  entryFile;
+  hmrManager;
+  onRuntimePlugin;
+  constructor({
+    appConfig,
+    staticSiteGenerator,
+    serveOptions,
+    runtimeOrigin,
+    needsServerBundle,
+    logger,
+    entryFile,
+    hmrManager,
+    onRuntimePlugin
+  }) {
+    this.appConfig = appConfig;
+    this.staticSiteGenerator = staticSiteGenerator;
+    this.serveOptions = serveOptions;
+    this.runtimeOrigin = runtimeOrigin;
+    this.needsServerBundle = needsServerBundle ?? false;
+    this.logger = logger ?? appLogger;
+    this.entryFile = resolveEntryFile({ entryFile });
+    this.hmrManager = hmrManager;
+    this.onRuntimePlugin = onRuntimePlugin;
+  }
+  prepareExportDirectory(force) {
+    if (force) {
+      clearProductionBuildCaches(this.appConfig);
+    }
+    const exportDir = this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, this.appConfig.distDir);
+    const shouldCleanDist = shouldResetStaticExportDirectory(this.appConfig, force);
+    fileSystem.ensureDir(exportDir, shouldCleanDist);
+    if (shouldCleanDist) {
+      this.appConfig.runtime = {
+        ...this.appConfig.runtime ?? {},
+        runtimeAssetsPrepared: false
+      };
+    }
+    const srcPublicDir = path.join(
+      this.appConfig.rootDir,
+      this.appConfig.srcDir ?? "src",
+      this.appConfig.publicDir ?? "public"
+    );
+    if (fileSystem.exists(srcPublicDir)) {
+      fileSystem.copyDir(srcPublicDir, exportDir);
+    }
+    return !shouldCleanDist;
+  }
+  async refreshRuntimeAssets() {
+    appLogger.debugTime("refreshRuntimeAssets");
+    try {
+      await setupAppRuntimePlugins({
+        appConfig: this.appConfig,
+        runtimeOrigin: this.runtimeOrigin,
+        onRuntimePlugin: this.onRuntimePlugin
+      });
+      if (this.hmrManager?.isEnabled()) {
+        attachHmrToIntegrations(this.appConfig, this.hmrManager);
+      }
+    } finally {
+      appLogger.debugTimeEnd("refreshRuntimeAssets");
+    }
+  }
+  /**
+   * Bundles the server entry file for production use.
+   *
+   * @remarks
+   * Only invoked when the app requires a runtime server (API handlers,
+   * websocket handlers, etc.). Static-only apps skip this step entirely.
+   * Incremental builds may skip Rolldown when the `.eco/.server-entry`
+   * cache is still valid.
+   *
+   * Package imports remain external so native addons and runtime-owned
+   * dependencies continue to load through the app's installed
+   * `node_modules` tree. Only the app entry graph is bundled.
+   *
+   * Throws if the build adapter is unavailable, is owned by a host
+   * runtime, or bundling fails.
+   *
+   * @throws If the build adapter is unavailable, is host-owned, or bundling fails.
+   */
+  async bundleServerEntry(options) {
+    const buildAdapter = getAppBuildAdapter(this.appConfig);
+    if (buildAdapter.ownership === "vite-host") {
+      throw new Error(
+        'Cannot bundle the server entry file: build ownership is "vite-host". The host runtime is expected to produce its own server bundle.'
+      );
+    }
+    const entryPath = path.isAbsolute(this.entryFile) ? this.entryFile : path.join(this.appConfig.rootDir, this.entryFile);
+    if (!fileSystem.exists(entryPath)) {
+      throw new Error(
+        `Cannot bundle server entry: file "${this.entryFile}" not found in "${this.appConfig.rootDir}".`
+      );
+    }
+    const { serverOutdir, serverEntryPath } = getServerBundleOutputPaths(this.appConfig);
+    const cached = lookupServerEntryBuildCache({
+      appConfig: this.appConfig,
+      entryPath,
+      force: options?.force
+    });
+    if (cached) {
+      const hasBundle = cached.outputPaths.some(
+        (outputPath) => path.resolve(outputPath) === path.resolve(serverEntryPath) && fileSystem.exists(outputPath)
+      );
+      if (hasBundle) {
+        this.logger.info("Reusing cached server entry bundle");
+        writeServerBundleDeployManifest(this.appConfig, serverEntryPath);
+        return;
+      }
+    }
+    this.logger.info("Bundling server entry file...");
+    const buildOptions = createServerBuildRequest(this.appConfig, {
+      profile: "server-entry",
+      entrypoints: [entryPath],
+      outdir: serverOutdir,
+      naming: SERVER_BUNDLE_FILENAME,
+      sourcemap: "hidden"
+    });
+    const result = await build(buildOptions, requireBuildRuntime(this.appConfig).getProfile("server-entry"));
+    if (!result.success) {
+      const errorMessages = result.logs.map((log) => log.message).join("\n");
+      throw new Error(`Failed to bundle server entry file:
+${errorMessages}`);
+    }
+    const outputPaths = result.outputs.length > 0 ? result.outputs.map((output) => output.path) : fileSystem.exists(serverEntryPath) ? [serverEntryPath] : [];
+    recordServerEntryBuildCache({
+      appConfig: this.appConfig,
+      entryPath,
+      buildResult: result,
+      outputPaths
+    });
+    writeServerBundleDeployManifest(this.appConfig, serverEntryPath);
+    this.logger.info("Server entry file bundled successfully");
+  }
+  /**
+   * Generates a static build of the site for deployment.
+   * @param dependencies.router - The initialized router
+   * @param dependencies.routeRendererFactory - The route renderer factory
+   * @param dependencies.staticRoutes - Explicit static routes registered via app.static()
+   */
+  async build(options, dependencies) {
+    const { baseUrl: explicitBaseUrl, force = false } = options ?? {};
+    const baseUrl = explicitBaseUrl ?? `http://${this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME}:${this.serveOptions.port || DEFAULT_ECOPAGES_PORT}`;
+    const preserveExportDirectory = this.prepareExportDirectory(force);
+    await this.refreshRuntimeAssets();
+    if (this.needsServerBundle) {
+      await this.bundleServerEntry({ force });
+    }
+    await this.staticSiteGenerator.run({
+      router: dependencies.router,
+      baseUrl,
+      routeRendererFactory: dependencies.routeRendererFactory,
+      staticRoutes: dependencies.staticRoutes,
+      force,
+      preserveExportDirectory
+    });
+    if (process.env.ECOPAGES_BENCH === "1" && process.env.ECOPAGES_BENCH_VERBOSE !== "1") {
+      this.logger.debug("Build completed");
+    } else {
+      this.logger.info("Build completed");
+    }
+  }
+}
+export {
+  ServerStaticBuilder
+};

package/src/adapters/shared/{static-preview-host.d.ts → runtime/static-preview-host.d.ts}

@@ -1,4 +1,4 @@
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
 export interface StaticPreviewHost {
     start(options: StaticPreviewHostStartOptions): Promise<number | null>;
     stop(force?: boolean): Promise<void>;
@@ -7,4 +7,9 @@ export interface StaticPreviewHostStartOptions {
     appConfig: EcoPagesAppConfig;
     hostname: string;
     port: number;
+    /**
+     * When true, bind to the next available port if the preferred one is busy.
+     * Should remain false when the port was explicitly configured.
+     */
+    allowPortFallback?: boolean;
 }

package/src/adapters/shared/ws/node-http-websocket-upgrades.d.ts

@@ -0,0 +1,21 @@
+import type { Duplex } from 'node:stream';
+import type { Server as NodeHttpServer, IncomingMessage } from 'node:http';
+import type { EcopagesWebSocketHandler } from '../../../types/public-types.js';
+export type NodeHttpWebSocketUpgradePreflight = (req: IncomingMessage, socket: Duplex, head: Buffer) => boolean;
+export type AttachNodeHttpWebSocketUpgradesOptions = {
+    runtimeOrigin: string;
+    websocketHandlers: Map<string, EcopagesWebSocketHandler<any, any>>;
+    /**
+     * When true, unmatched upgrade requests are left for other listeners (e.g.
+     * Vite HMR). When false, unmatched upgrades are destroyed immediately.
+     */
+    passthroughUnmatched?: boolean;
+    preflight?: NodeHttpWebSocketUpgradePreflight;
+};
+/**
+ * Wires Ecopages user WebSocket routes onto a Node HTTP server's `upgrade` event.
+ *
+ * Used by the Node adapter in standalone mode and by host integrations such as
+ * the Vite plugin that embed Ecopages behind a foreign HTTP server.
+ */
+export declare function attachNodeHttpWebSocketUpgrades(server: NodeHttpServer, options: AttachNodeHttpWebSocketUpgradesOptions): void;

package/src/adapters/shared/ws/node-http-websocket-upgrades.js

@@ -0,0 +1,100 @@
+import { WebSocketServer } from "ws";
+import { appLogger } from "../../../global/app-logger.js";
+import { findWebSocketRoute } from "../../abstract/ws-pattern-matcher.js";
+import { createEcopagesSocket, invokeWebSocketHandlerHook, toWebSocketCloseInfo } from "./websocket-lifecycle.js";
+const attachedUpgradeServers = /* @__PURE__ */ new WeakSet();
+function adaptNodeWebSocket(ws, kind, params, search, context) {
+  return createEcopagesSocket(
+    {
+      send: (data) => ws.send(data),
+      close: (code, reason) => ws.close(code, reason)
+    },
+    { kind, params, search, context }
+  );
+}
+function toUpgradeRequest(runtimeOrigin, req) {
+  const upgradeUrl = new URL(req.url ?? "/", runtimeOrigin);
+  return new Request(upgradeUrl, {
+    method: req.method,
+    headers: req.headers
+  });
+}
+async function resolveNodeContext(request, handler, kind, params, search) {
+  if (!handler.context) {
+    return void 0;
+  }
+  try {
+    return await handler.context({ request, kind, params, search });
+  } catch (error) {
+    appLogger.error(`[WS:${kind}] context() failed; closing connection.`, error);
+    throw error;
+  }
+}
+async function setupNodeWebSocketConnection(ws, wsMatch, req, runtimeOrigin, search) {
+  const handler = wsMatch.handler;
+  const baseRequest = toUpgradeRequest(runtimeOrigin, req);
+  let context;
+  try {
+    context = await resolveNodeContext(baseRequest, handler, wsMatch.kind, wsMatch.params, search);
+  } catch {
+    ws.close(1011, "context initialization failed");
+    return;
+  }
+  const socket = adaptNodeWebSocket(ws, wsMatch.kind, wsMatch.params, search, context);
+  try {
+    await handler.onConnect?.(socket);
+  } catch (error) {
+    appLogger.error(`[WS:${wsMatch.kind}] onConnect failed:`, error);
+    ws.close(1011, "onConnect failed");
+    return;
+  }
+  ws.on("message", (msg, isBinary) => {
+    const message = isBinary ? {
+      kind: "binary",
+      data: msg instanceof ArrayBuffer ? new Uint8Array(msg) : Array.isArray(msg) ? new Uint8Array(Buffer.concat(msg)) : new Uint8Array(msg)
+    } : { kind: "text", text: msg.toString() };
+    invokeWebSocketHandlerHook(wsMatch.kind, "onMessage", handler.onMessage?.(socket, message));
+  });
+  ws.on("close", (code, reason) => {
+    const event = toWebSocketCloseInfo(code, reason.toString());
+    invokeWebSocketHandlerHook(wsMatch.kind, "onClose", handler.onClose?.(socket, event));
+  });
+  ws.on("error", (err) => {
+    appLogger.error(`[WS:${wsMatch.kind}] error:`, err);
+    invokeWebSocketHandlerHook(wsMatch.kind, "onError", handler.onError?.(socket, err));
+  });
+}
+function attachNodeHttpWebSocketUpgrades(server, options) {
+  if (options.websocketHandlers.size === 0) {
+    return;
+  }
+  if (attachedUpgradeServers.has(server)) {
+    appLogger.warn("[WS] WebSocket upgrades already attached to this HTTP server; skipping duplicate attach.");
+    return;
+  }
+  attachedUpgradeServers.add(server);
+  const userWss = new WebSocketServer({ noServer: true });
+  server.on("upgrade", (req, socket, head) => {
+    if (options.preflight?.(req, socket, head)) {
+      return;
+    }
+    const url = new URL(req.url ?? "/", options.runtimeOrigin);
+    const wsMatch = findWebSocketRoute(options.websocketHandlers, url.pathname);
+    if (!wsMatch) {
+      if (!options.passthroughUnmatched) {
+        socket.destroy();
+      }
+      return;
+    }
+    userWss.handleUpgrade(req, socket, head, (ws) => {
+      const search = Object.fromEntries(url.searchParams.entries());
+      void setupNodeWebSocketConnection(ws, wsMatch, req, options.runtimeOrigin, search).catch((error) => {
+        appLogger.error(`[WS:${wsMatch.kind}] unexpected error:`, error);
+        ws.close(1011, "internal error");
+      });
+    });
+  });
+}
+export {
+  attachNodeHttpWebSocketUpgrades
+};

package/src/adapters/shared/ws/websocket-lifecycle.d.ts

@@ -0,0 +1,24 @@
+import type { EcopagesSocket, WebSocketCloseInfo } from '../../../types/public-types.js';
+/**
+ * @remarks
+ * Bun and Node expose different raw socket types but share the same
+ * {@link OutgoingWebSocketMessage} contract. Adapters supply only `send`/`close`;
+ * {@link createEcopagesSocket} owns message normalization and stream forwarding.
+ */
+export interface WebSocketSendTransport {
+    send(data: string | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+}
+/**
+ * @remarks
+ * Bun and Node adapters previously duplicated outgoing-message dispatch and
+ * stream forwarding; this is the shared implementation both transports delegate to.
+ */
+export declare function createEcopagesSocket<TContext, TParams extends Record<string, string>>(transport: WebSocketSendTransport, meta: {
+    kind: string;
+    params: TParams;
+    search: Record<string, string>;
+    context: TContext;
+}): EcopagesSocket<TContext, TParams>;
+export declare function toWebSocketCloseInfo(code: number, reason: string): WebSocketCloseInfo;
+export declare function invokeWebSocketHandlerHook(kind: string, hookName: string, result: void | Promise<void>): void;

package/src/adapters/shared/ws/websocket-lifecycle.js

@@ -0,0 +1,55 @@
+import { appLogger } from "../../../global/app-logger.js";
+function sendOutgoingMessage(transport, message) {
+  if (typeof message === "string") {
+    transport.send(message);
+  } else if (message instanceof Blob) {
+    void message.arrayBuffer().then((buffer) => transport.send(new Uint8Array(buffer)));
+  } else if (message instanceof ArrayBuffer) {
+    transport.send(new Uint8Array(message));
+  } else if (ArrayBuffer.isView(message)) {
+    transport.send(new Uint8Array(message.buffer, message.byteOffset, message.byteLength));
+  } else {
+    transport.send(message);
+  }
+}
+function createEcopagesSocket(transport, meta) {
+  return {
+    kind: meta.kind,
+    params: meta.params,
+    search: meta.search,
+    context: meta.context,
+    send: (message) => sendOutgoingMessage(transport, message),
+    sendStream: async (stream) => {
+      const reader = stream.getReader();
+      try {
+        while (true) {
+          const { value, done } = await reader.read();
+          if (done) break;
+          if (value) transport.send(value);
+        }
+      } finally {
+        reader.releaseLock();
+      }
+    },
+    close: (code, reason) => transport.close(code, reason)
+  };
+}
+function toWebSocketCloseInfo(code, reason) {
+  return {
+    code,
+    reason,
+    wasClean: code === 1e3 || code === 1001
+  };
+}
+function invokeWebSocketHandlerHook(kind, hookName, result) {
+  if (result instanceof Promise) {
+    result.catch((error) => {
+      appLogger.error(`[WS:${kind}] ${hookName} failed:`, error);
+    });
+  }
+}
+export {
+  createEcopagesSocket,
+  invokeWebSocketHandlerHook,
+  toWebSocketCloseInfo
+};