@ecopages/core 0.2.0-beta.4 → 0.2.0-beta.40

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,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';
+/**
+ * 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;
+    }
+    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:\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);
+        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');
+        }
+    }
+}

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,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 = 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 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));
+    });
+}
+/**
+ * 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;
+    }
+    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');
+            });
+        });
+    });
+}

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,62 @@
+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);
+    }
+}
+/**
+ * @remarks
+ * Bun and Node adapters previously duplicated outgoing-message dispatch and
+ * stream forwarding; this is the shared implementation both transports delegate to.
+ */
+export 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),
+    };
+}
+export function toWebSocketCloseInfo(code, reason) {
+    return {
+        code,
+        reason,
+        wasClean: code === 1000 || code === 1001,
+    };
+}
+export function invokeWebSocketHandlerHook(kind, hookName, result) {
+    if (result instanceof Promise) {
+        result.catch((error) => {
+            appLogger.error(`[WS:${kind}] ${hookName} failed:`, error);
+        });
+    }
+}