@ecopages/core 0.2.0-alpha.26 → 0.2.0-alpha.27

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

@@ -0,0 +1,232 @@
+/**
+ * This file contains the implementation of the Bun application adapter for EcoPages.
+ * It extends the AbstractApplicationAdapter class and provides methods for handling
+ * HTTP requests, initializing the server adapter, and starting the Bun application server.
+ * The adapter is designed to work with the Bun runtime and provides a way to create
+ * EcoPages applications using Bun's features.
+ *
+ * @module EcopagesApp
+ */
+
+import type { Server } from 'bun';
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from '../../config/constants.ts';
+import { StaticContentServer } from '../../dev/sc-server.ts';
+import { appLogger } from '../../global/app-logger.ts';
+import { getBunRuntime } from '../../utils/runtime.ts';
+import type { ApiHandlerContext, RouteGroupBuilder } from '../../types/public-types.ts';
+import { SharedApplicationAdapter } from '../shared/application-adapter.ts';
+import type { EcopagesAppOptions } from '../create-app.ts';
+import { type BunServerAdapterResult, createBunServerAdapter } from './server-adapter.ts';
+
+/**
+ * Bun-specific route group builder that properly infers route params from path patterns.
+ * When you define a route like `/posts/:slug`, the handler context will have
+ * `ctx.params.slug` typed as `string`.
+ *
+ * @typeParam WebSocketData - WebSocket data type for the server
+ * @typeParam TContext - Extended context type from middleware (e.g., `{ user: User }`)
+ */
+export type BunRouteGroupBuilder<
+	WebSocketData = undefined,
+	TContext extends ApiHandlerContext<Request, Server<WebSocketData>> = ApiHandlerContext<
+		Request,
+		Server<WebSocketData>
+	>,
+> = RouteGroupBuilder<Request, Server<WebSocketData>, TContext>;
+
+/**
+ * Bun-specific application adapter implementation
+ * This class extends the {@link AbstractApplicationAdapter}
+ * and provides methods for handling HTTP requests and managing the server.
+ */
+
+export class BunEcopagesApp<WebSocketData = undefined> extends SharedApplicationAdapter<
+	EcopagesAppOptions,
+	Server<WebSocketData>,
+	Request
+> {
+	serverAdapter: BunServerAdapterResult | undefined;
+	private server: Server<WebSocketData> | null = null;
+
+	private async startStaticPreviewServer(port: number, hostname: string): Promise<void> {
+		await new Promise((resolve) => setTimeout(resolve, 100));
+
+		for (let attempt = 0; attempt < 20; attempt += 1) {
+			try {
+				const previewServer = StaticContentServer.createServer({
+					appConfig: this.appConfig,
+					options: { port },
+				});
+
+				if (previewServer.server?.port) {
+					appLogger.info(`Preview running at http://${hostname}:${previewServer.server.port}`);
+					return;
+				}
+
+				break;
+			} catch (error) {
+				const errorMessage = error instanceof Error ? error.message : String(error);
+				const errorCode =
+					typeof error === 'object' && error !== null && 'code' in error
+						? String((error as { code?: unknown }).code)
+						: undefined;
+				const isPortReleaseRace = errorCode === 'EADDRINUSE' || errorMessage.includes('EADDRINUSE');
+
+				if (!isPortReleaseRace || attempt === 19) {
+					throw error;
+				}
+
+				await new Promise((resolve) => setTimeout(resolve, 100));
+			}
+		}
+
+		appLogger.error('Failed to start preview server');
+	}
+
+	public async fetch(request: Request): Promise<Response> {
+		if (!this.serverAdapter) {
+			this.serverAdapter = await this.initializeServerAdapter();
+		}
+
+		await this.serverAdapter.completeInitialization(this.server);
+		return this.serverAdapter.handleRequest(request);
+	}
+
+	/**
+	 * Complete the initialization of the server adapter by processing dynamic routes
+	 * @param server The Bun server instance
+	 */
+	public async completeInitialization(server: Server<WebSocketData>): Promise<void> {
+		if (!this.serverAdapter) {
+			throw new Error('Server adapter not initialized. Call start() first.');
+		}
+
+		await this.serverAdapter.completeInitialization(server);
+	}
+
+	/**
+	 * Initialize the Bun server adapter
+	 */
+	protected async initializeServerAdapter(): Promise<BunServerAdapterResult> {
+		const { dev } = this.cliArgs;
+		const { port: cliPort, hostname: cliHostname } = this.cliArgs;
+
+		const envPort = process.env.ECOPAGES_PORT ? process.env.ECOPAGES_PORT : undefined;
+		const envHostname = process.env.ECOPAGES_HOSTNAME;
+
+		const preferredPort = cliPort ?? envPort ?? DEFAULT_ECOPAGES_PORT;
+		const preferredHostname = cliHostname ?? envHostname ?? DEFAULT_ECOPAGES_HOSTNAME;
+
+		appLogger.debug('initializeServerAdapter', {
+			dev,
+			cliPort,
+			cliHostname,
+			envPort,
+			envHostname,
+			preferredPort,
+			preferredHostname,
+			composedUrl: `http://${preferredHostname}:${preferredPort}`,
+		});
+
+		return await createBunServerAdapter({
+			runtimeOrigin: `http://${preferredHostname}:${preferredPort}`,
+			appConfig: this.appConfig,
+			apiHandlers: this.apiHandlers,
+			staticRoutes: this.staticRoutes,
+			errorHandler: this.errorHandler,
+			options: { watch: dev },
+			serveOptions: {
+				port: preferredPort,
+				hostname: preferredHostname,
+				...this.serverOptions,
+			},
+		});
+	}
+
+	/**
+	 * Start the Bun application server
+	 * @param options Optional settings
+	 * @param options.autoCompleteInitialization Whether to automatically complete initialization with dynamic routes after server start (defaults to true)
+	 */
+	public async start(): Promise<Server<WebSocketData> | void> {
+		if (!this.serverAdapter) {
+			this.serverAdapter = await this.initializeServerAdapter();
+		}
+
+		const { dev, preview, build } = this.cliArgs;
+		const requiresFetchRuntime = this.appConfig.integrations.some(
+			(integration) => integration.staticBuildStep === 'fetch',
+		);
+		const canBuildWithoutRuntimeServer = (build || preview) && !requiresFetchRuntime;
+
+		if (canBuildWithoutRuntimeServer) {
+			appLogger.debugTime('Building static pages');
+			await this.serverAdapter.buildStatic({ preview });
+			appLogger.debugTimeEnd('Building static pages');
+
+			if (build) {
+				process.exit(0);
+			}
+
+			return;
+		}
+
+		const enableHmr = dev || (!preview && !build);
+		const serverOptions = this.serverAdapter.getServerOptions({ enableHmr });
+		const configuredHostname = String(serverOptions.hostname ?? DEFAULT_ECOPAGES_HOSTNAME);
+		const configuredPort = Number(serverOptions.port ?? DEFAULT_ECOPAGES_PORT);
+		const runtimeServerOptions =
+			(preview || build) && requiresFetchRuntime
+				? {
+						...serverOptions,
+						port: 0,
+					}
+				: serverOptions;
+
+		const bun = getBunRuntime();
+		if (!bun) {
+			throw new Error('Bun runtime is required for the Bun adapter');
+		}
+
+		const bunServer = bun.serve(runtimeServerOptions as Bun.Serve.Options<WebSocketData>);
+		this.server = bunServer as Server<WebSocketData>;
+
+		await this.serverAdapter.completeInitialization(this.server).catch((error: Error) => {
+			appLogger.error(`Failed to complete initialization: ${error}`);
+		});
+
+		if (!this.server) {
+			throw new Error('Server failed to start');
+		}
+		appLogger.info(`Server running at http://${this.server.hostname}:${this.server.port}`);
+
+		if (build || preview) {
+			appLogger.debugTime('Building static pages');
+			await this.serverAdapter.buildStatic({ preview: false });
+			this.server.stop(true);
+
+			if (preview) {
+				const previewHostname = configuredHostname;
+				const previewPort = configuredPort;
+				await this.startStaticPreviewServer(previewPort, previewHostname);
+			}
+
+			appLogger.debugTimeEnd('Building static pages');
+
+			if (build) {
+				process.exit(0);
+			}
+		}
+
+		return this.server;
+	}
+}
+
+/**
+ * Factory function to create a Bun application
+ */
+export async function createApp<WebSocketData = undefined>(
+	options: EcopagesAppOptions,
+): Promise<BunEcopagesApp<WebSocketData>> {
+	return new BunEcopagesApp(options);
+}

package/src/adapters/bun/hmr-manager.test.ts

@@ -0,0 +1,265 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, test, vi } from 'vitest';
+import { ConfigBuilder } from '../../config/config-builder.ts';
+import { resolveInternalExecutionDir, resolveInternalWorkDir } from '../../utils/resolve-work-dir.ts';
+import { HmrManager } from './hmr-manager.ts';
+
+const tempRoots: string[] = [];
+
+function createTempRoot(prefix: string): string {
+	const root = fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-`));
+	tempRoots.push(root);
+	return root;
+}
+
+afterEach(() => {
+	for (const root of tempRoots.splice(0)) {
+		fs.rmSync(root, { recursive: true, force: true });
+	}
+	vi.restoreAllMocks();
+});
+
+test('HmrManager shares one in-flight entrypoint registration across concurrent callers', async () => {
+	const rootDir = createTempRoot('ecopages-bun-hmr-register');
+	const srcDir = path.join(rootDir, 'src');
+	const pagesDir = path.join(srcDir, 'pages');
+	fs.mkdirSync(pagesDir, { recursive: true });
+
+	const entrypointPath = path.join(pagesDir, 'react-lab.tsx');
+	fs.writeFileSync(entrypointPath, 'export default function Page() { return null; }', 'utf8');
+
+	const config = await new ConfigBuilder().setRootDir(rootDir).build();
+	const manager = new HmrManager({
+		appConfig: config,
+		bridge: {
+			subscriberCount: 0,
+			broadcast: () => {},
+			subscribe: () => {},
+			unsubscribe: () => {},
+		} as any,
+	});
+
+	const relativePathJs = path
+		.relative(config.absolutePaths.srcDir, entrypointPath)
+		.replace(/\.(tsx?|jsx?|mdx?)$/, '.js');
+	const encodedPathJs = relativePathJs.replace(/\[([^\]]+)\]/g, '_$1_');
+	const outputPath = path.join(resolveInternalWorkDir(config), 'assets', '_hmr', encodedPathJs);
+
+	const handleFileChange = vi.spyOn(manager, 'handleFileChange').mockImplementation(async () => {
+		await new Promise((resolve) => setTimeout(resolve, 25));
+		fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+		fs.writeFileSync(outputPath, 'export default 1;', 'utf8');
+	});
+
+	const [firstUrl, secondUrl] = await Promise.all([
+		manager.registerEntrypoint(entrypointPath),
+		manager.registerEntrypoint(entrypointPath),
+	]);
+
+	assert.equal(firstUrl, '/assets/_hmr/pages/react-lab.js');
+	assert.equal(secondUrl, '/assets/_hmr/pages/react-lab.js');
+	assert.equal(handleFileChange.mock.calls.length, 1);
+	assert.equal(fs.existsSync(outputPath), true);
+
+	manager.stop();
+});
+
+test('HmrManager clears timed-out entrypoint registrations so later requests can retry', async () => {
+	const rootDir = createTempRoot('ecopages-bun-hmr-timeout-register');
+	const srcDir = path.join(rootDir, 'src');
+	const pagesDir = path.join(srcDir, 'pages');
+	fs.mkdirSync(pagesDir, { recursive: true });
+
+	const entrypointPath = path.join(pagesDir, 'stuck-page.tsx');
+	fs.writeFileSync(entrypointPath, 'export default function Page() { return null; }', 'utf8');
+
+	const config = await new ConfigBuilder().setRootDir(rootDir).build();
+	const manager = new HmrManager({
+		appConfig: config,
+		bridge: {
+			subscriberCount: 0,
+			broadcast: () => {},
+			subscribe: () => {},
+			unsubscribe: () => {},
+		} as any,
+	});
+
+	const previousNodeEnv = process.env.NODE_ENV;
+	process.env.NODE_ENV = 'development';
+
+	const handleFileChange = vi.spyOn(manager, 'handleFileChange').mockImplementation(async () => {
+		await new Promise(() => undefined);
+	});
+
+	try {
+		await assert.rejects(() => manager.registerEntrypoint(entrypointPath), /Timed out registering entrypoint/);
+
+		const registrations = (manager as unknown as { entrypointRegistrations: Map<string, Promise<string>> })
+			.entrypointRegistrations;
+		const watchedFiles = manager.getWatchedFiles();
+		assert.equal(registrations.size, 0);
+		assert.equal(watchedFiles.has(entrypointPath), false);
+
+		handleFileChange.mockImplementationOnce(async () => {
+			const relativePathJs = path
+				.relative(config.absolutePaths.srcDir, entrypointPath)
+				.replace(/\.(tsx?|jsx?|mdx?)$/, '.js');
+			const encodedPathJs = relativePathJs.replace(/\[([^\]]+)\]/g, '_$1_');
+			const outputPath = path.join(resolveInternalWorkDir(config), 'assets', '_hmr', encodedPathJs);
+			fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+			fs.writeFileSync(outputPath, 'export default 2;', 'utf8');
+		});
+
+		const retriedUrl = await manager.registerEntrypoint(entrypointPath);
+		assert.equal(retriedUrl, '/assets/_hmr/pages/stuck-page.js');
+		assert.equal(watchedFiles.get(entrypointPath), retriedUrl);
+	} finally {
+		process.env.NODE_ENV = previousNodeEnv;
+		manager.stop();
+	}
+});
+
+test('HmrManager fails strict entrypoint registration when the owning integration emits no output', async () => {
+	const rootDir = createTempRoot('ecopages-bun-hmr-strict-fail');
+	const srcDir = path.join(rootDir, 'src');
+	const pagesDir = path.join(srcDir, 'pages');
+	fs.mkdirSync(pagesDir, { recursive: true });
+
+	const entrypointPath = path.join(pagesDir, 'react-content.mdx');
+	fs.writeFileSync(entrypointPath, '# Hello', 'utf8');
+
+	const config = await new ConfigBuilder().setRootDir(rootDir).build();
+	const manager = new HmrManager({
+		appConfig: config,
+		bridge: {
+			subscriberCount: 0,
+			broadcast: () => {},
+			subscribe: () => {},
+			unsubscribe: () => {},
+		} as any,
+	});
+
+	vi.spyOn(manager, 'handleFileChange').mockImplementation(async () => {});
+
+	await assert.rejects(() => manager.registerEntrypoint(entrypointPath), /Integration failed to emit entrypoint/);
+	assert.equal(manager.getWatchedFiles().has(path.resolve(entrypointPath)), false);
+
+	manager.stop();
+});
+
+test('HmrManager uses the generic build path for script entrypoints when no strategy emits output', async () => {
+	const rootDir = createTempRoot('ecopages-bun-hmr-script-fallback');
+	const srcDir = path.join(rootDir, 'src');
+	fs.mkdirSync(srcDir, { recursive: true });
+
+	const entrypointPath = path.join(srcDir, 'script.ts');
+	fs.writeFileSync(entrypointPath, 'console.log("hello");', 'utf8');
+
+	const config = await new ConfigBuilder().setRootDir(rootDir).build();
+	const manager = new HmrManager({
+		appConfig: config,
+		bridge: {
+			subscriberCount: 0,
+			broadcast: () => {},
+			subscribe: () => {},
+			unsubscribe: () => {},
+		} as any,
+	});
+
+	const outputPath = path.join(resolveInternalWorkDir(config), 'assets', '_hmr', 'script.js');
+	const buildCalls: string[] = [];
+	config.runtime!.buildExecutor = {
+		build: vi.fn(async (options) => {
+			buildCalls.push(options.entrypoints[0] as string);
+			fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+			fs.writeFileSync(outputPath, 'fresh-output', 'utf8');
+
+			return {
+				success: true,
+				logs: [],
+				outputs: [{ path: outputPath }],
+			};
+		}),
+	};
+
+	vi.spyOn(manager, 'handleFileChange').mockImplementation(async () => {});
+
+	const outputUrl = await manager.registerScriptEntrypoint(entrypointPath);
+
+	assert.equal(outputUrl, '/assets/_hmr/script.js');
+	assert.deepEqual(buildCalls, [entrypointPath]);
+	assert.equal(fs.readFileSync(outputPath, 'utf8'), 'fresh-output');
+
+	manager.stop();
+});
+
+test('HmrManager stop clears retained registration state', async () => {
+	const rootDir = createTempRoot('ecopages-bun-hmr-stop-cleanup');
+	const srcDir = path.join(rootDir, 'src');
+	const pagesDir = path.join(srcDir, 'pages');
+	fs.mkdirSync(pagesDir, { recursive: true });
+
+	const entrypointPath = path.join(pagesDir, 'react-content.tsx');
+	fs.writeFileSync(entrypointPath, 'export default function Page() { return null; }', 'utf8');
+
+	const config = await new ConfigBuilder().setRootDir(rootDir).build();
+	const manager = new HmrManager({
+		appConfig: config,
+		bridge: {
+			subscriberCount: 0,
+			broadcast: () => {},
+			subscribe: () => {},
+			unsubscribe: () => {},
+		} as any,
+	});
+
+	const relativePathJs = path
+		.relative(config.absolutePaths.srcDir, entrypointPath)
+		.replace(/\.(tsx?|jsx?|mdx?)$/, '.js');
+	const encodedPathJs = relativePathJs.replace(/\[([^\]]+)\]/g, '_$1_');
+	const outputPath = path.join(resolveInternalWorkDir(config), 'assets', '_hmr', encodedPathJs);
+
+	vi.spyOn(manager, 'handleFileChange').mockImplementation(async () => {
+		fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+		fs.writeFileSync(outputPath, 'export default 1;', 'utf8');
+	});
+
+	await manager.registerEntrypoint(entrypointPath);
+
+	manager.stop();
+
+	assert.equal(manager.getWatchedFiles().size, 0);
+});
+
+test('HmrManager keeps internal browser and server-module outputs out of distDir', async () => {
+	const rootDir = createTempRoot('ecopages-bun-hmr-internal-paths');
+	const config = await new ConfigBuilder().setRootDir(rootDir).build();
+	const manager = new HmrManager({
+		appConfig: config,
+		bridge: {
+			subscriberCount: 0,
+			broadcast: () => {},
+			subscribe: () => {},
+			unsubscribe: () => {},
+		} as any,
+	});
+
+	assert.equal(manager.getDistDir(), path.join(resolveInternalWorkDir(config), 'assets', '_hmr'));
+
+	const importModule = vi.fn(async (_options: { outdir: string }) => ({}));
+	(manager as unknown as { serverModuleTranspiler: { importModule: typeof importModule } }).serverModuleTranspiler = {
+		importModule,
+	};
+
+	await manager.getDefaultContext().importServerModule(path.join(config.absolutePaths.srcDir, 'pages', 'index.tsx'));
+
+	assert.equal(
+		importModule.mock.calls[0]?.[0]?.outdir,
+		path.join(resolveInternalExecutionDir(config), '.server-modules'),
+	);
+
+	manager.stop();
+});