@ecopages/core 0.2.0-alpha.52 → 0.2.0-alpha.54

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

@@ -0,0 +1,214 @@
+/**
+ * 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 { appLogger } from '../../global/app-logger.ts';
+import type { ApiHandlerContext, RouteGroupBuilder } from '../../types/public-types.ts';
+import { SharedApplicationAdapter } from '../shared/application-adapter.ts';
+import { resolveRuntimeBinding, resolveStaticRuntimeMode } from '../shared/runtime-app-bootstrap.ts';
+import type { RuntimeHost } from '../shared/runtime-host.ts';
+import type { StaticPreviewHost } from '../shared/static-preview-host.ts';
+import type { EcopagesAppOptions } from '../create-app.ts';
+import { type BunServerAdapterResult, createBunServerAdapter } from './server-adapter.ts';
+import { BunStaticPreviewHost } from './static-preview-host.ts';
+import { BunRuntimeHost } from './runtime-host.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 readonly runtimeHost: RuntimeHost<Server<WebSocketData>, Bun.Serve.Options<WebSocketData>>;
+	private readonly previewHost: StaticPreviewHost;
+
+	constructor(
+		options: EcopagesAppOptions,
+		dependencies: {
+			runtimeHost: RuntimeHost<Server<WebSocketData>, Bun.Serve.Options<WebSocketData>>;
+			previewHost: StaticPreviewHost;
+		},
+	) {
+		super(options);
+		this.runtimeHost = dependencies.runtimeHost;
+		this.previewHost = dependencies.previewHost;
+	}
+
+	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 binding = resolveRuntimeBinding({
+			cliArgs: this.cliArgs,
+			serverOptions: this.serverOptions,
+		});
+
+		appLogger.debug('initializeServerAdapter', {
+			dev: this.cliArgs.dev,
+			cliPort: this.cliArgs.port,
+			cliHostname: this.cliArgs.hostname,
+			envPort: process.env.ECOPAGES_PORT,
+			envHostname: process.env.ECOPAGES_HOSTNAME,
+			preferredPort: binding.preferredPort,
+			preferredHostname: binding.preferredHostname,
+			composedUrl: binding.runtimeOrigin,
+		});
+
+		return await createBunServerAdapter({
+			runtimeOrigin: binding.runtimeOrigin,
+			appConfig: this.appConfig,
+			apiHandlers: this.apiHandlers,
+			staticRoutes: this.staticRoutes,
+			errorHandler: this.errorHandler,
+			options: { watch: binding.watch },
+			serveOptions: binding.serveOptions,
+		});
+	}
+
+	/**
+	 * 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 staticRuntimeMode = resolveStaticRuntimeMode({
+			appConfig: this.appConfig,
+			cliArgs: this.cliArgs,
+		});
+
+		if (staticRuntimeMode.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) && staticRuntimeMode.requiresFetchRuntime
+				? {
+						...serverOptions,
+						port: 0,
+					}
+				: serverOptions;
+		this.server = await this.runtimeHost.start({
+			serveOptions: runtimeServerOptions as Bun.Serve.Options<WebSocketData>,
+			handleRequest: async () => new Response(null, { status: 500 }),
+			onError: async () => {},
+		});
+
+		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 ${this.runtimeHost.getOrigin(this.server, runtimeServerOptions as Bun.Serve.Options<WebSocketData>)}`,
+		);
+
+		if (build || preview) {
+			appLogger.debugTime('Building static pages');
+			await this.serverAdapter.buildStatic({ preview: false });
+			await this.runtimeHost.stop(this.server, { force: true });
+
+			if (preview) {
+				const previewPort = await this.previewHost.start({
+					appConfig: this.appConfig,
+					hostname: configuredHostname,
+					port: configuredPort,
+				});
+
+				if (previewPort) {
+					appLogger.info(`Preview running at http://${configuredHostname}:${previewPort}`);
+				}
+			}
+
+			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, {
+		runtimeHost: new BunRuntimeHost<WebSocketData>(),
+		previewHost: new BunStaticPreviewHost(),
+	});
+}

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();
+});

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

@@ -0,0 +1,88 @@
+import type { ServerWebSocket, WebSocketHandler } from 'bun';
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import { appLogger } from '../../global/app-logger.ts';
+import type { ClientBridge } from './client-bridge.ts';
+import {
+	InMemoryEntrypointDependencyGraph,
+	type EntrypointDependencyGraph,
+} from '../../services/runtime-state/entrypoint-dependency-graph.service.ts';
+import { SharedHmrManager } from '../shared/shared-hmr-manager.ts';
+
+type BunSocket = ServerWebSocket<unknown>;
+type BunSocketHandler = WebSocketHandler<unknown>;
+
+export interface HmrManagerParams {
+	appConfig: EcoPagesAppConfig;
+	bridge: ClientBridge;
+}
+
+/**
+ * Bun development HMR manager.
+ *
+ * @remarks
+ * Bun shares the same public contract as the Node manager: page entrypoints are
+ * strict integration-owned registrations, while generic script assets use their
+ * own explicit registration path.
+ */
+export class HmrManager extends SharedHmrManager {
+	private wsHandler!: {
+		open: (ws: BunSocket) => void;
+		close: (ws: BunSocket) => void;
+	};
+
+	/**
+	 * Creates the Bun HMR manager around the shared HMR orchestration pipeline.
+	 *
+	 * @remarks
+	 * Bun delegates route watching, rebuild dispatch, and runtime bundle
+	 * generation to `SharedHmrManager`. The Bun subclass only supplies the
+	 * transport-specific dependency graph policy and websocket hook surface.
+	 */
+	constructor({ appConfig, bridge }: HmrManagerParams) {
+		super({ appConfig, bridge });
+	}
+
+	/**
+	 * Reuses the shared in-memory dependency graph when possible and otherwise
+	 * creates the Bun-compatible default graph implementation.
+	 */
+	protected createEntrypointDependencyGraph(existingEntrypointDependencyGraph: EntrypointDependencyGraph) {
+		return existingEntrypointDependencyGraph instanceof InMemoryEntrypointDependencyGraph
+			? existingEntrypointDependencyGraph
+			: new InMemoryEntrypointDependencyGraph();
+	}
+
+	/**
+	 * Returns the Bun websocket hooks that attach and detach live HMR subscribers.
+	 *
+	 * @remarks
+	 * `SharedHmrManager` stores the bridge behind the transport-agnostic
+	 * `IClientBridge` contract because most HMR coordination only needs broadcast
+	 * behavior. Bun connection lifecycle wiring is the point where that abstraction
+	 * intentionally narrows back to the concrete Bun bridge so websocket instances
+	 * can be tracked directly.
+	 */
+	public getWebSocketHandler(): BunSocketHandler {
+		const bridge = this.bridge as ClientBridge;
+
+		const open = (ws: BunSocket) => {
+			bridge.subscribe(ws);
+			appLogger.debug(`[HmrManager] Connection opened. Subscribers: ${bridge.subscriberCount}`);
+		};
+
+		const close = (ws: BunSocket) => {
+			bridge.unsubscribe(ws);
+			appLogger.debug(`[HmrManager] Connection closed. Subscribers: ${bridge.subscriberCount}`);
+		};
+
+		this.wsHandler = { open, close };
+
+		return {
+			open: this.wsHandler.open,
+			close: this.wsHandler.close,
+			message: (_ws, message) => {
+				appLogger.debug('[HMR] Received message from client:', message);
+			},
+		};
+	}
+}

package/src/adapters/bun/index.ts

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

package/src/adapters/bun/runtime-host.ts

@@ -0,0 +1,76 @@
+import type { Server } from 'bun';
+import { getBunRuntime } from '../../utils/runtime.ts';
+import { resolveServeRuntimeOrigin } from '../shared/runtime-app-bootstrap.ts';
+import type { RuntimeHost, RuntimeHostStartOptions } from '../shared/runtime-host.ts';
+
+type BunRuntimeProvider = {
+	serve(options: Bun.Serve.Options<unknown>): Server<unknown>;
+};
+
+/**
+ * Bun runtime host that adapts the shared runtime lifecycle contract onto
+ * `Bun.serve()`.
+ *
+ * @remarks
+ * The injected runtime provider exists so tests and non-Bun call sites can
+ * construct the host without assuming `globalThis.Bun` is present. The provider
+ * returns `null` instead of `undefined` to keep that absence explicit at the
+ * host boundary.
+ */
+export class BunRuntimeHost<WebSocketData = undefined> implements RuntimeHost<
+	Server<WebSocketData>,
+	Bun.Serve.Options<WebSocketData>
+> {
+	/**
+	 * Creates a Bun runtime host with an injectable runtime lookup.
+	 *
+	 * @remarks
+	 * Production code uses the default `getBunRuntime()` lookup. Tests may inject a
+	 * fake provider that either supplies a `serve()` implementation or returns
+	 * `null` to verify the runtime-required failure path.
+	 */
+	constructor(private readonly runtimeProvider: () => BunRuntimeProvider | null = () => getBunRuntime() ?? null) {}
+
+	/**
+	 * Starts the Bun server using the already-composed serve options from the
+	 * shared application bootstrap.
+	 */
+	public async start(
+		options: RuntimeHostStartOptions<Bun.Serve.Options<WebSocketData>>,
+	): Promise<Server<WebSocketData>> {
+		const bun = this.runtimeProvider();
+		if (!bun) {
+			throw new Error('Bun runtime is required for the Bun adapter');
+		}
+
+		return bun.serve(options.serveOptions as Bun.Serve.Options<unknown>) as Server<WebSocketData>;
+	}
+
+	/**
+	 * Stops the active Bun server immediately.
+	 *
+	 * @remarks
+	 * The shared runtime-host contract accepts optional stop options, but Bun's
+	 * server API already models the shutdown behavior directly. This host always
+	 * uses Bun's forceful stop path so preview and embedded runtime shutdowns do
+	 * not linger on open connections.
+	 */
+	public async stop(server: Server<WebSocketData>): Promise<void> {
+		server.stop(true);
+	}
+
+	/**
+	 * Resolves the externally reported runtime origin from the active server.
+	 *
+	 * @remarks
+	 * Bun may finalize the hostname or port differently from the requested serve
+	 * options. This method prefers the live server binding and only falls back to
+	 * the requested options when Bun leaves a field unset.
+	 */
+	public getOrigin(server: Server<WebSocketData>, fallbackServeOptions: Bun.Serve.Options<WebSocketData>): string {
+		return resolveServeRuntimeOrigin({
+			hostname: server.hostname ?? fallbackServeOptions.hostname,
+			port: server.port ?? fallbackServeOptions.port,
+		});
+	}
+}