@ecopages/core 0.2.0-alpha.23 → 0.2.0-alpha.24

package/src/adapters/create-app.ts

@@ -0,0 +1,91 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.ts';
+import { AbstractApplicationAdapter } from './abstract/application-adapter.ts';
+import type { ApiHandler } from '../types/public-types.ts';
+import type { ApplicationAdapterOptions } from './abstract/application-adapter.ts';
+import { SharedApplicationAdapter } from './shared/application-adapter.ts';
+
+export interface EcopagesAppOptions extends ApplicationAdapterOptions {
+	appConfig: EcoPagesAppConfig;
+	serverOptions?: Record<string, any>;
+}
+
+export type UniversalEcopagesApp = AbstractApplicationAdapter<EcopagesAppOptions, unknown, Request>;
+
+async function createRuntimeApp<WebSocketData = undefined>(options: EcopagesAppOptions): Promise<UniversalEcopagesApp> {
+	const bun = (globalThis as { Bun?: unknown }).Bun;
+
+	if (bun) {
+		const { createApp: createBunApp } = await import('./bun/create-app.ts');
+		return (await createBunApp<WebSocketData>(options)) as unknown as UniversalEcopagesApp;
+	}
+
+	const { createApp: createNodeApp } = await import('./node/create-app.ts');
+	return (await createNodeApp(options)) as unknown as UniversalEcopagesApp;
+}
+
+export async function createApp<WebSocketData = undefined>(options: EcopagesAppOptions): Promise<UniversalEcopagesApp> {
+	return createRuntimeApp<WebSocketData>(options);
+}
+
+export class EcopagesApp extends SharedApplicationAdapter<EcopagesAppOptions, unknown, Request> {
+	private readonly appOptions: EcopagesAppOptions;
+	private runtimeApp: UniversalEcopagesApp | null = null;
+	private runtimeAppPromise: Promise<UniversalEcopagesApp> | null = null;
+
+	constructor(options: EcopagesAppOptions) {
+		super(options);
+		this.appOptions = options;
+	}
+
+	private async getRuntimeApp(): Promise<UniversalEcopagesApp> {
+		if (this.runtimeApp) {
+			return this.runtimeApp;
+		}
+
+		if (!this.runtimeAppPromise) {
+			this.runtimeAppPromise = createRuntimeApp({
+				...this.appOptions,
+				clearOutput: false,
+			}).then((app) => {
+				for (const handler of this.apiHandlers) {
+					app.add(handler as ApiHandler<string, Request, any>);
+				}
+
+				for (const route of this.staticRoutes) {
+					app.static(route.path, route.loader);
+				}
+
+				if (this.errorHandler) {
+					app.onError(this.errorHandler);
+				}
+
+				this.runtimeApp = app;
+				return app;
+			});
+		}
+
+		return this.runtimeAppPromise;
+	}
+
+	protected async initializeServerAdapter(): Promise<UniversalEcopagesApp> {
+		return this.getRuntimeApp();
+	}
+
+	async start(): Promise<unknown> {
+		const runtimeApp = await this.getRuntimeApp();
+		return runtimeApp.start();
+	}
+
+	async fetch(request: Request): Promise<Response> {
+		const runtimeApp = await this.getRuntimeApp();
+		const candidate = runtimeApp as UniversalEcopagesApp & {
+			fetch?: (request: Request) => Promise<Response>;
+		};
+
+		if (!candidate.fetch) {
+			throw new Error('The selected runtime adapter does not expose fetch()');
+		}
+
+		return candidate.fetch(request);
+	}
+}

package/src/adapters/index.ts

@@ -0,0 +1,2 @@
+export { EcopagesApp, createApp } from './create-app.ts';
+export { defineApiHandler, defineGroupHandler, type GroupHandler } from './shared/define-api-handler.ts';

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

@@ -0,0 +1,53 @@
+import assert from 'node:assert/strict';
+import { afterEach, describe, it, vi } from 'vitest';
+import type { NodeServerAdapterParams, NodeServerAdapterResult } from './server-adapter.ts';
+import { NodeEcopagesApp } from './create-app.ts';
+
+class TestNodeEcopagesApp extends NodeEcopagesApp {
+	public capturedParams: NodeServerAdapterParams | undefined;
+
+	protected override async createServerAdapter(params: NodeServerAdapterParams): Promise<NodeServerAdapterResult> {
+		this.capturedParams = params;
+		return {
+			getServerOptions: () => params.serveOptions,
+			completeInitialization: async () => {},
+			handleRequest: async () => new Response(null, { status: 204 }),
+			buildStatic: async () => {},
+		};
+	}
+
+	public async initializeForTest(): Promise<void> {
+		await this.initializeServerAdapter();
+	}
+}
+
+afterEach(() => {
+	process.env.NODE_ENV = undefined;
+	process.env.ECOPAGES_INTERNAL_EMBEDDED_RUNTIME = undefined;
+	process.env.ECOPAGES_PORT = '';
+	process.env.ECOPAGES_HOSTNAME = '';
+	vi.restoreAllMocks();
+});
+
+describe('node embedded app bootstrap', () => {
+	it('keeps watch mode enabled for embedded development runtimes', async () => {
+		process.env.NODE_ENV = 'development';
+
+		const app = new TestNodeEcopagesApp({
+			appConfig: {
+				runtime: {},
+			} as any,
+			runtime: {
+				embedded: true,
+			},
+		});
+
+		await app.initializeForTest();
+
+		assert.equal(app.capturedParams?.options?.watch, true);
+		assert.deepEqual(app.capturedParams?.serveOptions, {
+			port: 3000,
+			hostname: 'localhost',
+		});
+	});
+});

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

@@ -0,0 +1,183 @@
+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 '../../config/constants.ts';
+import { appLogger } from '../../global/app-logger.ts';
+import type { StaticRoute } from '../../types/public-types.ts';
+import { SharedApplicationAdapter } from '../shared/application-adapter.ts';
+import type { EcopagesAppOptions } from '../create-app.ts';
+import { type NodeServerAdapterResult, createNodeServerAdapter } from './server-adapter.ts';
+
+export class NodeEcopagesApp extends SharedApplicationAdapter<EcopagesAppOptions, NodeServerInstance, Request> {
+	serverAdapter: NodeServerAdapterResult | undefined;
+	private server: NodeServerInstance | null = null;
+	private runtimeOrigin = '';
+
+	protected createServerAdapter(
+		params: Parameters<typeof createNodeServerAdapter>[0],
+	): Promise<NodeServerAdapterResult> {
+		return createNodeServerAdapter(params);
+	}
+
+	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 this.createServerAdapter({
+			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<NodeEcopagesApp> {
+	return new NodeEcopagesApp(options);
+}
+
+export async function createApp(options: EcopagesAppOptions): Promise<NodeEcopagesApp> {
+	return createNodeApp(options);
+}

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

@@ -0,0 +1,198 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { NodeClientBridge } from './node-client-bridge.ts';
+
+// ---------------------------------------------------------------------------
+// Minimal WebSocket mock — only the surface that NodeClientBridge touches
+// ---------------------------------------------------------------------------
+function createMockWs(readyState = 1 /* OPEN */) {
+	return {
+		readyState,
+		send: vi.fn(),
+		ping: vi.fn(),
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe('NodeClientBridge', () => {
+	let bridge: NodeClientBridge;
+
+	beforeEach(() => {
+		vi.useFakeTimers();
+		bridge = new NodeClientBridge();
+	});
+
+	afterEach(() => {
+		bridge.destroy();
+		vi.useRealTimers();
+	});
+
+	// ── subscribe / unsubscribe ─────────────────────────────────────────────
+
+	describe('subscribe / unsubscribe', () => {
+		it('increments subscriberCount when a socket is added', () => {
+			const ws = createMockWs();
+			bridge.subscribe(ws as never);
+			expect(bridge.subscriberCount).toBe(1);
+		});
+
+		it('decrements subscriberCount when a socket is removed', () => {
+			const ws = createMockWs();
+			bridge.subscribe(ws as never);
+			bridge.unsubscribe(ws as never);
+			expect(bridge.subscriberCount).toBe(0);
+		});
+
+		it('handles unsubscribing a socket that was never added', () => {
+			const ws = createMockWs();
+			expect(() => bridge.unsubscribe(ws as never)).not.toThrow();
+		});
+	});
+
+	// ── broadcast ──────────────────────────────────────────────────────────
+
+	describe('broadcast', () => {
+		it('sends the serialised event to all OPEN subscribers', () => {
+			const ws1 = createMockWs(1);
+			const ws2 = createMockWs(1);
+			bridge.subscribe(ws1 as never);
+			bridge.subscribe(ws2 as never);
+
+			bridge.broadcast({ type: 'reload' });
+
+			expect(ws1.send).toHaveBeenCalledWith(JSON.stringify({ type: 'reload' }));
+			expect(ws2.send).toHaveBeenCalledWith(JSON.stringify({ type: 'reload' }));
+		});
+
+		it('does NOT send to a socket that is not OPEN (readyState !== 1)', () => {
+			const closedWs = createMockWs(3 /* CLOSED */);
+			bridge.subscribe(closedWs as never);
+
+			bridge.broadcast({ type: 'reload' });
+
+			expect(closedWs.send).not.toHaveBeenCalled();
+		});
+	});
+
+	// ── convenience helpers ────────────────────────────────────────────────
+
+	describe('convenience broadcast helpers', () => {
+		it('reload() broadcasts a reload event', () => {
+			const ws = createMockWs();
+			bridge.subscribe(ws as never);
+
+			bridge.reload();
+
+			expect(ws.send).toHaveBeenCalledWith(JSON.stringify({ type: 'reload' }));
+		});
+
+		it('cssUpdate() broadcasts a css-update event with path and timestamp', () => {
+			const ws = createMockWs();
+			bridge.subscribe(ws as never);
+
+			bridge.cssUpdate('/styles/main.css');
+
+			const payload = JSON.parse((ws.send as ReturnType<typeof vi.fn>).mock.calls[0][0]);
+			expect(payload.type).toBe('css-update');
+			expect(payload.path).toBe('/styles/main.css');
+			expect(typeof payload.timestamp).toBe('number');
+		});
+
+		it('update() broadcasts an update event with path and timestamp', () => {
+			const ws = createMockWs();
+			bridge.subscribe(ws as never);
+
+			bridge.update('/pages/index.ts');
+
+			const payload = JSON.parse((ws.send as ReturnType<typeof vi.fn>).mock.calls[0][0]);
+			expect(payload.type).toBe('update');
+			expect(payload.path).toBe('/pages/index.ts');
+		});
+
+		it('error() broadcasts an error event with the message', () => {
+			const ws = createMockWs();
+			bridge.subscribe(ws as never);
+
+			bridge.error('build failed');
+
+			expect(ws.send).toHaveBeenCalledWith(JSON.stringify({ type: 'error', message: 'build failed' }));
+		});
+	});
+
+	// ── heartbeat sweep ────────────────────────────────────────────────────
+
+	describe('heartbeat sweep (every 30 s)', () => {
+		it('pings OPEN subscribers on each sweep', () => {
+			const ws = createMockWs(1);
+			bridge.subscribe(ws as never);
+
+			vi.advanceTimersByTime(30_000);
+
+			expect(ws.ping).toHaveBeenCalledTimes(1);
+		});
+
+		it('removes zombie sockets (non-OPEN) from the subscriber set', () => {
+			const liveWs = createMockWs(1 /* OPEN */);
+			const deadWs = createMockWs(3 /* CLOSED */);
+			bridge.subscribe(liveWs as never);
+			bridge.subscribe(deadWs as never);
+
+			expect(bridge.subscriberCount).toBe(2);
+
+			vi.advanceTimersByTime(30_000);
+
+			expect(bridge.subscriberCount).toBe(1);
+			expect(liveWs.ping).toHaveBeenCalledTimes(1);
+			expect(deadWs.ping).not.toHaveBeenCalled();
+		});
+
+		it('accumulates cleanup across multiple sweeps', () => {
+			const ws1 = createMockWs(1);
+			bridge.subscribe(ws1 as never);
+
+			// First sweep – still alive
+			vi.advanceTimersByTime(30_000);
+			expect(bridge.subscriberCount).toBe(1);
+
+			// Socket goes away
+			ws1.readyState = 3;
+
+			// Second sweep – removed
+			vi.advanceTimersByTime(30_000);
+			expect(bridge.subscriberCount).toBe(0);
+		});
+	});
+
+	// ── destroy ────────────────────────────────────────────────────────────
+
+	describe('destroy()', () => {
+		it('stops the heartbeat timer so no further pings are sent', () => {
+			const ws = createMockWs(1);
+			bridge.subscribe(ws as never);
+
+			bridge.destroy();
+
+			// Advancing time should NOT trigger any sweep
+			vi.advanceTimersByTime(30_000 * 5);
+
+			expect(ws.ping).not.toHaveBeenCalled();
+		});
+
+		it('clears all subscribers', () => {
+			bridge.subscribe(createMockWs() as never);
+			bridge.subscribe(createMockWs() as never);
+
+			bridge.destroy();
+
+			expect(bridge.subscriberCount).toBe(0);
+		});
+
+		it('is safe to call destroy() multiple times', () => {
+			expect(() => {
+				bridge.destroy();
+				bridge.destroy();
+			}).not.toThrow();
+		});
+	});
+});

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

@@ -0,0 +1,79 @@
+import type { WebSocket } from 'ws';
+import type { ClientBridgeEvent, IClientBridge } from '../../types/public-types.ts';
+
+const HEARTBEAT_INTERVAL_MS = 30_000;
+
+export class NodeClientBridge implements IClientBridge {
+	private subscribers = new Set<WebSocket>();
+	private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+
+	constructor() {
+		this.heartbeatTimer = setInterval(() => this.sweep(), HEARTBEAT_INTERVAL_MS);
+		/* Allow the process to exit even if the timer is still active */
+		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).
+	 */
+	private sweep(): void {
+		for (const ws of this.subscribers) {
+			if (ws.readyState !== 1 /* OPEN */) {
+				this.subscribers.delete(ws);
+				continue;
+			}
+			ws.ping();
+		}
+	}
+
+	subscribe(ws: WebSocket): void {
+		this.subscribers.add(ws);
+	}
+
+	unsubscribe(ws: WebSocket): void {
+		this.subscribers.delete(ws);
+	}
+
+	broadcast(event: ClientBridgeEvent): void {
+		const payload = JSON.stringify(event);
+		for (const ws of this.subscribers) {
+			if (ws.readyState === 1) {
+				ws.send(payload);
+			}
+		}
+	}
+
+	reload(): void {
+		this.broadcast({ type: 'reload' });
+	}
+
+	cssUpdate(path: string): void {
+		this.broadcast({ type: 'css-update', path, timestamp: Date.now() });
+	}
+
+	update(path: string): void {
+		this.broadcast({ type: 'update', path, timestamp: Date.now() });
+	}
+
+	error(message: string): void {
+		this.broadcast({ type: 'error', message });
+	}
+
+	get subscriberCount(): number {
+		return this.subscribers.size;
+	}
+
+	/**
+	 * Stops the heartbeat timer and clears all subscribers.
+	 * Call this when the dev server is shutting down.
+	 */
+	destroy(): void {
+		if (this.heartbeatTimer !== null) {
+			clearInterval(this.heartbeatTimer);
+			this.heartbeatTimer = null;
+		}
+		this.subscribers.clear();
+	}
+}