@ecopages/core 0.2.0-beta.31 → 0.2.0-beta.32

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

@@ -1,191 +1,172 @@
-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);
+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';
+/**
+ * Handles static site generation.
+ */
+export 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;
     }
-    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
-      };
+    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;
     }
-    const srcPublicDir = path.join(
-      this.appConfig.rootDir,
-      this.appConfig.srcDir ?? "src",
-      this.appConfig.publicDir ?? "public"
-    );
-    if (fileSystem.exists(srcPublicDir)) {
-      fileSystem.copyDir(srcPublicDir, exportDir);
+    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');
+        }
     }
-    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");
+    /**
+     * 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:\n${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);
-        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 });
+        this.logger.info('Server entry file bundled successfully');
     }
-    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");
+    /**
+     * 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/runtime/static-preview-host.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,100 +1,109 @@
-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();
+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 = 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 }
-  );
+    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
-  });
+    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;
-  }
+    if (!handler.context) {
+        return undefined;
+    }
+    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));
-  });
+    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;
+/**
+ * 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 function attachNodeHttpWebSocketUpgrades(server, options) {
+    if (options.websocketHandlers.size === 0) {
+        return;
     }
-    const url = new URL(req.url ?? "/", options.runtimeOrigin);
-    const wsMatch = findWebSocketRoute(options.websocketHandlers, url.pathname);
-    if (!wsMatch) {
-      if (!options.passthroughUnmatched) {
-        socket.destroy();
-      }
-      return;
+    if (attachedUpgradeServers.has(server)) {
+        appLogger.warn('[WS] WebSocket upgrades already attached to this HTTP server; skipping duplicate attach.');
+        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");
-      });
+    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
-};