@ecopages/core 0.2.0-alpha.1

package/src/adapters/bun/server-lifecycle.ts

@@ -0,0 +1,154 @@
+import path from 'node:path';
+import { getBunRuntime } from '../../utils/runtime.ts';
+import { RESOLVED_ASSETS_DIR } from '../../constants';
+import { defaultBuildAdapter } from '../../build/build-adapter.ts';
+import { appLogger } from '../../global/app-logger';
+import type { EcoPagesAppConfig } from '../../internal-types';
+import type { EcoBuildPlugin } from '../../build/build-types.ts';
+import { fileSystem } from '@ecopages/file-system';
+import { StaticSiteGenerator } from '../../static-site-generator/static-site-generator';
+import { ProjectWatcher } from '../../watchers/project-watcher';
+import type { ClientBridge } from './client-bridge';
+import type { HmrManager } from './hmr-manager';
+
+export interface WatcherCallbacks {
+	refreshRouterRoutesCallback: () => Promise<void>;
+}
+
+export interface ServerLifecycleParams {
+	appConfig: EcoPagesAppConfig;
+	runtimeOrigin: string;
+	hmrManager: HmrManager;
+	bridge: ClientBridge;
+}
+
+/**
+ * Handles server lifecycle: initialization, plugins, loaders, and file watching.
+ */
+export class ServerLifecycle {
+	private readonly appConfig: EcoPagesAppConfig;
+	private readonly hmrManager: HmrManager;
+	private readonly bridge: ClientBridge;
+	private readonly runtimeOrigin: string;
+	private staticSiteGenerator!: StaticSiteGenerator;
+
+	constructor({ appConfig, runtimeOrigin, hmrManager, bridge }: ServerLifecycleParams) {
+		this.appConfig = appConfig;
+		this.runtimeOrigin = runtimeOrigin;
+		this.hmrManager = hmrManager;
+		this.bridge = bridge;
+	}
+
+	/**
+	 * Initializes the server's core components.
+	 * @returns The static site generator instance for use by other components
+	 */
+	async initialize(): Promise<StaticSiteGenerator> {
+		this.staticSiteGenerator = new StaticSiteGenerator({ appConfig: this.appConfig });
+		await this.hmrManager.buildRuntime();
+
+		this.setupLoaders();
+		this.copyPublicDir();
+
+		return this.staticSiteGenerator;
+	}
+
+	/**
+	 * Sets up Bun loaders from config.
+	 * Note: This will be abstracted to a LoaderStrategy interface in #4 Runtime Abstraction.
+	 */
+	setupLoaders(): void {
+		const loaders = this.appConfig.loaders;
+		for (const loader of loaders.values()) {
+			defaultBuildAdapter.registerPlugin(loader);
+			getBunRuntime()?.plugin(loader as any);
+		}
+	}
+
+	/**
+	 * Copies public directory contents to dist root.
+	 * Static files are served from root (e.g., /favicon.ico, /robots.txt).
+	 */
+	copyPublicDir(): void {
+		try {
+			const srcPublicDir = path.join(this.appConfig.rootDir, this.appConfig.srcDir, this.appConfig.publicDir);
+
+			if (fileSystem.exists(srcPublicDir)) {
+				fileSystem.copyDir(srcPublicDir, path.join(this.appConfig.rootDir, this.appConfig.distDir));
+			}
+
+			fileSystem.ensureDir(path.join(this.appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
+		} catch (error) {
+			appLogger.error(
+				`Failed to copy public directory: ${error instanceof Error ? error.message : String(error)}`,
+			);
+			throw error;
+		}
+	}
+
+	/**
+	 * Initializes processors and integrations.
+	 * @param options.watch - Whether watch mode is enabled
+	 */
+	async initializePlugins(options?: { watch?: boolean }): Promise<EcoBuildPlugin[]> {
+		try {
+			const hmrEnabled = !!options?.watch;
+			this.hmrManager.setEnabled(hmrEnabled);
+
+			const processorBuildPlugins: EcoBuildPlugin[] = [];
+
+			const processorPromises = Array.from(this.appConfig.processors.values()).map(async (processor) => {
+				await processor.setup();
+				if (processor.plugins) {
+					for (const plugin of processor.plugins) {
+						defaultBuildAdapter.registerPlugin(plugin);
+						getBunRuntime()?.plugin(plugin as any);
+					}
+				}
+				if (processor.buildPlugins) {
+					processorBuildPlugins.push(...processor.buildPlugins);
+				}
+			});
+
+			const integrationPromises = this.appConfig.integrations.map(async (integration) => {
+				integration.setConfig(this.appConfig);
+				integration.setRuntimeOrigin(this.runtimeOrigin);
+				integration.setHmrManager(this.hmrManager);
+				await integration.setup();
+
+				for (const plugin of integration.plugins) {
+					defaultBuildAdapter.registerPlugin(plugin);
+					getBunRuntime()?.plugin(plugin as any);
+				}
+			});
+
+			await Promise.all([...processorPromises, ...integrationPromises]);
+
+			const loaderPlugins = Array.from(this.appConfig.loaders.values());
+			const allBuildPlugins = [...loaderPlugins, ...processorBuildPlugins];
+			this.hmrManager.setPlugins(allBuildPlugins);
+			return allBuildPlugins;
+		} catch (error) {
+			appLogger.error(`Failed to initialize plugins: ${error instanceof Error ? error.message : String(error)}`);
+			throw error;
+		}
+	}
+
+	/**
+	 * Starts file watching for HMR.
+	 */
+	async startWatching(callbacks: WatcherCallbacks): Promise<void> {
+		const watcherInstance = new ProjectWatcher({
+			config: this.appConfig,
+			refreshRouterRoutesCallback: callbacks.refreshRouterRoutesCallback,
+			hmrManager: this.hmrManager,
+			bridge: this.bridge,
+		});
+
+		await watcherInstance.createWatcherSubscription();
+	}
+
+	getStaticSiteGenerator(): StaticSiteGenerator {
+		return this.staticSiteGenerator;
+	}
+}

package/src/adapters/index.d.ts

@@ -0,0 +1,6 @@
+export { EcopagesApp, createApp } from './bun/create-app.js';
+export { defineApiHandler, defineGroupHandler } from './bun/define-api-handler.js';
+export { NodeServerAdapter, createNodeServerAdapter } from './node/server-adapter.js';
+export { EcopagesApp as NodeAdapterEcopagesApp, createNodeApp } from './node/create-app.js';
+export type { NodeServerAdapterParams, NodeServerAdapterResult } from './node/server-adapter.js';
+export type { EcopagesAppOptions as NodeEcopagesAppOptions } from './node/create-app.js';

package/src/adapters/index.js

@@ -0,0 +1,14 @@
+import { EcopagesApp, createApp } from "./bun/create-app.js";
+import { defineApiHandler, defineGroupHandler } from "./bun/define-api-handler.js";
+import { NodeServerAdapter, createNodeServerAdapter } from "./node/server-adapter.js";
+import { EcopagesApp as EcopagesApp2, createNodeApp } from "./node/create-app.js";
+export {
+  EcopagesApp,
+  EcopagesApp2 as NodeAdapterEcopagesApp,
+  NodeServerAdapter,
+  createApp,
+  createNodeApp,
+  createNodeServerAdapter,
+  defineApiHandler,
+  defineGroupHandler
+};

package/src/adapters/index.ts

@@ -0,0 +1,6 @@
+export { EcopagesApp, createApp } from './bun/create-app.ts';
+export { defineApiHandler, defineGroupHandler } from './bun/define-api-handler.ts';
+export { NodeServerAdapter, createNodeServerAdapter } from './node/server-adapter.ts';
+export { EcopagesApp as NodeAdapterEcopagesApp, createNodeApp } from './node/create-app.ts';
+export type { NodeServerAdapterParams, NodeServerAdapterResult } from './node/server-adapter.ts';
+export type { EcopagesAppOptions as NodeEcopagesAppOptions } from './node/create-app.ts';

package/src/adapters/node/create-app.d.ts

@@ -0,0 +1,21 @@
+import { type Server as NodeServerInstance } from 'node:http';
+import type { EcoPagesAppConfig } from '../../internal-types.js';
+import { type ApplicationAdapterOptions } from '../abstract/application-adapter.js';
+import { SharedApplicationAdapter } from '../shared/application-adapter.js';
+import { type NodeServerAdapterResult } from './server-adapter.js';
+export interface EcopagesAppOptions extends ApplicationAdapterOptions {
+    appConfig: EcoPagesAppConfig;
+    serverOptions?: Record<string, any>;
+}
+export declare class EcopagesApp extends SharedApplicationAdapter<EcopagesAppOptions, NodeServerInstance, Request> {
+    serverAdapter: NodeServerAdapterResult | undefined;
+    private server;
+    private runtimeOrigin;
+    stop(force?: boolean): Promise<void>;
+    protected initializeServerAdapter(): Promise<NodeServerAdapterResult>;
+    start(): Promise<NodeServerInstance | void>;
+    private createWebRequest;
+    private sendNodeResponse;
+    fetch(request: Request): Promise<Response>;
+}
+export declare function createNodeApp(options: EcopagesAppOptions): Promise<EcopagesApp>;

package/src/adapters/node/create-app.js

@@ -0,0 +1,143 @@
+import { createServer } from "node:http";
+import { Readable } from "node:stream";
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../constants.js";
+import { appLogger } from "../../global/app-logger.js";
+import {} from "../abstract/application-adapter.js";
+import { SharedApplicationAdapter } from "../shared/application-adapter.js";
+import { createNodeServerAdapter } from "./server-adapter.js";
+class EcopagesApp extends SharedApplicationAdapter {
+  serverAdapter;
+  server = null;
+  runtimeOrigin = "";
+  async stop(force = true) {
+    if (!this.server) {
+      return;
+    }
+    const activeServer = this.server;
+    this.server = null;
+    await new Promise((resolve, reject) => {
+      activeServer.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+      if (force) {
+        activeServer.closeAllConnections();
+      }
+    });
+  }
+  async initializeServerAdapter() {
+    const { dev } = this.cliArgs;
+    const { port: cliPort, hostname: cliHostname } = this.cliArgs;
+    const envPort = process.env.ECOPAGES_PORT;
+    const envHostname = process.env.ECOPAGES_HOSTNAME;
+    const preferredPort = cliPort ?? (envPort ? Number(envPort) : void 0) ?? DEFAULT_ECOPAGES_PORT;
+    const preferredHostname = cliHostname ?? envHostname ?? DEFAULT_ECOPAGES_HOSTNAME;
+    this.runtimeOrigin = `http://${preferredHostname}:${preferredPort}`;
+    return createNodeServerAdapter({
+      runtimeOrigin: this.runtimeOrigin,
+      appConfig: this.appConfig,
+      apiHandlers: this.apiHandlers,
+      staticRoutes: this.staticRoutes,
+      errorHandler: this.errorHandler,
+      options: { watch: dev },
+      serveOptions: {
+        port: preferredPort,
+        hostname: preferredHostname,
+        ...this.serverOptions
+      }
+    });
+  }
+  async start() {
+    if (!this.serverAdapter) {
+      this.serverAdapter = await this.initializeServerAdapter();
+    }
+    if (this.server) {
+      return this.server;
+    }
+    const { build, preview } = this.cliArgs;
+    if (build || preview) {
+      appLogger.debugTime("Building static pages");
+      await this.serverAdapter.buildStatic({ preview });
+      await this.stop(true);
+      appLogger.debugTimeEnd("Building static pages");
+      if (build) {
+        process.exit(0);
+      }
+      return;
+    }
+    const serveOptions = this.serverAdapter.getServerOptions();
+    const hostname = String(serveOptions.hostname ?? DEFAULT_ECOPAGES_HOSTNAME);
+    const port = Number(serveOptions.port ?? DEFAULT_ECOPAGES_PORT);
+    this.runtimeOrigin = `http://${hostname}:${port}`;
+    this.server = createServer(async (req, res) => {
+      try {
+        const webRequest = this.createWebRequest(req);
+        const response = await this.serverAdapter.handleRequest(webRequest);
+        await this.sendNodeResponse(res, response);
+      } catch (error) {
+        appLogger.error("Node server adapter request failed", error);
+        res.statusCode = 500;
+        res.end("Internal Server Error");
+      }
+    });
+    await new Promise((resolve) => {
+      this.server.listen(port, hostname, () => resolve());
+    });
+    await this.serverAdapter.completeInitialization(this.server);
+    appLogger.info(`Node server running at ${this.runtimeOrigin}`);
+    return this.server;
+  }
+  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") {
+      requestInit.body = Readable.toWeb(req);
+      requestInit.duplex = "half";
+    }
+    return new Request(url, requestInit);
+  }
+  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);
+  }
+  async fetch(request) {
+    if (!this.serverAdapter) {
+      this.serverAdapter = await this.initializeServerAdapter();
+    }
+    return this.serverAdapter.handleRequest(request);
+  }
+}
+async function createNodeApp(options) {
+  return new EcopagesApp(options);
+}
+export {
+  EcopagesApp,
+  createNodeApp
+};

package/src/adapters/node/create-app.ts

@@ -0,0 +1,179 @@
+import { createServer, type IncomingMessage, type Server as NodeServerInstance, type ServerResponse } from 'node:http';
+import { Readable } from 'node:stream';
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from '../../constants.ts';
+import { appLogger } from '../../global/app-logger.ts';
+import type { EcoPagesAppConfig } from '../../internal-types.ts';
+import type { StaticRoute } from '../../public-types.ts';
+import { type ApplicationAdapterOptions } from '../abstract/application-adapter.ts';
+import { SharedApplicationAdapter } from '../shared/application-adapter.ts';
+import { type NodeServerAdapterResult, createNodeServerAdapter } from './server-adapter.ts';
+
+export interface EcopagesAppOptions extends ApplicationAdapterOptions {
+	appConfig: EcoPagesAppConfig;
+	serverOptions?: Record<string, any>;
+}
+
+export class EcopagesApp extends SharedApplicationAdapter<EcopagesAppOptions, NodeServerInstance, Request> {
+	serverAdapter: NodeServerAdapterResult | undefined;
+	private server: NodeServerInstance | null = null;
+	private runtimeOrigin = '';
+
+	public async stop(force = true): Promise<void> {
+		if (!this.server) {
+			return;
+		}
+
+		const activeServer = this.server;
+		this.server = null;
+
+		await new Promise<void>((resolve, reject) => {
+			activeServer.close((error) => {
+				if (error) {
+					reject(error);
+					return;
+				}
+
+				resolve();
+			});
+
+			if (force) {
+				activeServer.closeAllConnections();
+			}
+		});
+	}
+
+	protected async initializeServerAdapter(): Promise<NodeServerAdapterResult> {
+		const { dev } = this.cliArgs;
+		const { port: cliPort, hostname: cliHostname } = this.cliArgs;
+
+		const envPort = process.env.ECOPAGES_PORT;
+		const envHostname = process.env.ECOPAGES_HOSTNAME;
+
+		const preferredPort = cliPort ?? (envPort ? Number(envPort) : undefined) ?? DEFAULT_ECOPAGES_PORT;
+		const preferredHostname = cliHostname ?? envHostname ?? DEFAULT_ECOPAGES_HOSTNAME;
+		this.runtimeOrigin = `http://${preferredHostname}:${preferredPort}`;
+
+		return createNodeServerAdapter({
+			runtimeOrigin: this.runtimeOrigin,
+			appConfig: this.appConfig,
+			apiHandlers: this.apiHandlers,
+			staticRoutes: this.staticRoutes as StaticRoute[],
+			errorHandler: this.errorHandler,
+			options: { watch: dev },
+			serveOptions: {
+				port: preferredPort,
+				hostname: preferredHostname,
+				...this.serverOptions,
+			},
+		});
+	}
+
+	public async start(): Promise<NodeServerInstance | void> {
+		if (!this.serverAdapter) {
+			this.serverAdapter = await this.initializeServerAdapter();
+		}
+
+		if (this.server) {
+			return this.server;
+		}
+
+		const { build, preview } = this.cliArgs;
+
+		if (build || preview) {
+			appLogger.debugTime('Building static pages');
+			await this.serverAdapter.buildStatic({ preview });
+			await this.stop(true);
+			appLogger.debugTimeEnd('Building static pages');
+
+			if (build) {
+				process.exit(0);
+			}
+			return;
+		}
+
+		const serveOptions = this.serverAdapter.getServerOptions();
+		const hostname = String(serveOptions.hostname ?? DEFAULT_ECOPAGES_HOSTNAME);
+		const port = Number(serveOptions.port ?? DEFAULT_ECOPAGES_PORT);
+		this.runtimeOrigin = `http://${hostname}:${port}`;
+
+		this.server = createServer(async (req, res) => {
+			try {
+				const webRequest = this.createWebRequest(req);
+				const response = await this.serverAdapter!.handleRequest(webRequest);
+				await this.sendNodeResponse(res, response);
+			} catch (error) {
+				appLogger.error('Node server adapter request failed', error as Error);
+				res.statusCode = 500;
+				res.end('Internal Server Error');
+			}
+		});
+
+		await new Promise<void>((resolve) => {
+			this.server!.listen(port, hostname, () => resolve());
+		});
+
+		await this.serverAdapter.completeInitialization(this.server);
+		appLogger.info(`Node server running at ${this.runtimeOrigin}`);
+
+		return this.server;
+	}
+
+	private createWebRequest(req: IncomingMessage): Request {
+		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 !== undefined) {
+				headers.set(key, value);
+			}
+		}
+
+		const method = (req.method ?? 'GET').toUpperCase();
+		const requestInit: RequestInit & { duplex?: 'half' } = {
+			method,
+			headers,
+		};
+
+		if (method !== 'GET' && method !== 'HEAD') {
+			requestInit.body = Readable.toWeb(req) as unknown as BodyInit;
+			requestInit.duplex = 'half';
+		}
+
+		return new Request(url, requestInit);
+	}
+
+	private async sendNodeResponse(res: ServerResponse, response: Response): Promise<void> {
+		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);
+	}
+
+	public async fetch(request: Request): Promise<Response> {
+		if (!this.serverAdapter) {
+			this.serverAdapter = await this.initializeServerAdapter();
+		}
+
+		return this.serverAdapter.handleRequest(request);
+	}
+}
+
+export async function createNodeApp(options: EcopagesAppOptions): Promise<EcopagesApp> {
+	return new EcopagesApp(options);
+}

package/src/adapters/node/index.d.ts

@@ -0,0 +1,4 @@
+export { NodeServerAdapter, createNodeServerAdapter } from './server-adapter.js';
+export { EcopagesApp, createNodeApp } from './create-app.js';
+export type { EcopagesAppOptions } from './create-app.js';
+export type { NodeServerAdapterParams, NodeServerAdapterResult, NodeServerInstance, NodeServeAdapterServerOptions, } from './server-adapter.js';

package/src/adapters/node/index.js

@@ -0,0 +1,8 @@
+import { NodeServerAdapter, createNodeServerAdapter } from "./server-adapter.js";
+import { EcopagesApp, createNodeApp } from "./create-app.js";
+export {
+  EcopagesApp,
+  NodeServerAdapter,
+  createNodeApp,
+  createNodeServerAdapter
+};

package/src/adapters/node/index.ts

@@ -0,0 +1,9 @@
+export { NodeServerAdapter, createNodeServerAdapter } from './server-adapter.ts';
+export { EcopagesApp, createNodeApp } from './create-app.ts';
+export type { EcopagesAppOptions } from './create-app.ts';
+export type {
+	NodeServerAdapterParams,
+	NodeServerAdapterResult,
+	NodeServerInstance,
+	NodeServeAdapterServerOptions,
+} from './server-adapter.ts';

package/src/adapters/node/node-client-bridge.d.ts

@@ -0,0 +1,26 @@
+import type { WebSocket } from 'ws';
+import type { ClientBridgeEvent, IClientBridge } from '../../public-types.js';
+export declare class NodeClientBridge implements IClientBridge {
+    private subscribers;
+    private heartbeatTimer;
+    constructor();
+    /**
+     * Pings all open subscribers and removes any that are no longer in OPEN state.
+     * This prevents a slow memory leak caused by zombie connections that never
+     * send a close event (e.g. abruptly killed browsers, orphaned tabs, network drops).
+     */
+    private sweep;
+    subscribe(ws: WebSocket): void;
+    unsubscribe(ws: WebSocket): void;
+    broadcast(event: ClientBridgeEvent): void;
+    reload(): void;
+    cssUpdate(path: string): void;
+    update(path: string): void;
+    error(message: string): void;
+    get subscriberCount(): number;
+    /**
+     * Stops the heartbeat timer and clears all subscribers.
+     * Call this when the dev server is shutting down.
+     */
+    destroy(): void;
+}

package/src/adapters/node/node-client-bridge.js

@@ -0,0 +1,66 @@
+const HEARTBEAT_INTERVAL_MS = 3e4;
+class NodeClientBridge {
+  subscribers = /* @__PURE__ */ new Set();
+  heartbeatTimer = null;
+  constructor() {
+    this.heartbeatTimer = setInterval(() => this.sweep(), HEARTBEAT_INTERVAL_MS);
+    this.heartbeatTimer.unref?.();
+  }
+  /**
+   * Pings all open subscribers and removes any that are no longer in OPEN state.
+   * This prevents a slow memory leak caused by zombie connections that never
+   * send a close event (e.g. abruptly killed browsers, orphaned tabs, network drops).
+   */
+  sweep() {
+    for (const ws of this.subscribers) {
+      if (ws.readyState !== 1) {
+        this.subscribers.delete(ws);
+        continue;
+      }
+      ws.ping();
+    }
+  }
+  subscribe(ws) {
+    this.subscribers.add(ws);
+  }
+  unsubscribe(ws) {
+    this.subscribers.delete(ws);
+  }
+  broadcast(event) {
+    const payload = JSON.stringify(event);
+    for (const ws of this.subscribers) {
+      if (ws.readyState === 1) {
+        ws.send(payload);
+      }
+    }
+  }
+  reload() {
+    this.broadcast({ type: "reload" });
+  }
+  cssUpdate(path) {
+    this.broadcast({ type: "css-update", path, timestamp: Date.now() });
+  }
+  update(path) {
+    this.broadcast({ type: "update", path, timestamp: Date.now() });
+  }
+  error(message) {
+    this.broadcast({ type: "error", message });
+  }
+  get subscriberCount() {
+    return this.subscribers.size;
+  }
+  /**
+   * Stops the heartbeat timer and clears all subscribers.
+   * Call this when the dev server is shutting down.
+   */
+  destroy() {
+    if (this.heartbeatTimer !== null) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    this.subscribers.clear();
+  }
+}
+export {
+  NodeClientBridge
+};