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

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

@@ -0,0 +1,52 @@
+import type { Server } from 'bun';
+import type { RuntimeHost, RuntimeHostStartOptions } from '../shared/runtime-host.js';
+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 declare class BunRuntimeHost<WebSocketData = undefined> implements RuntimeHost<Server<WebSocketData>, Bun.Serve.Options<WebSocketData>> {
+    private readonly runtimeProvider;
+    /**
+     * 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(runtimeProvider?: () => BunRuntimeProvider | null);
+    /**
+     * Starts the Bun server using the already-composed serve options from the
+     * shared application bootstrap.
+     */
+    start(options: RuntimeHostStartOptions<Bun.Serve.Options<WebSocketData>>): Promise<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.
+     */
+    stop(server: Server<WebSocketData>): Promise<void>;
+    /**
+     * 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.
+     */
+    getOrigin(server: Server<WebSocketData>, fallbackServeOptions: Bun.Serve.Options<WebSocketData>): string;
+}
+export {};

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

@@ -0,0 +1,56 @@
+import { getBunRuntime } from "../../utils/runtime.js";
+import { resolveServeRuntimeOrigin } from "../shared/runtime-app-bootstrap.js";
+class BunRuntimeHost {
+  /**
+   * 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(runtimeProvider = () => getBunRuntime() ?? null) {
+    this.runtimeProvider = runtimeProvider;
+  }
+  runtimeProvider;
+  /**
+   * Starts the Bun server using the already-composed serve options from the
+   * shared application bootstrap.
+   */
+  async start(options) {
+    const bun = this.runtimeProvider();
+    if (!bun) {
+      throw new Error("Bun runtime is required for the Bun adapter");
+    }
+    return bun.serve(options.serveOptions);
+  }
+  /**
+   * 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.
+   */
+  async stop(server) {
+    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.
+   */
+  getOrigin(server, fallbackServeOptions) {
+    return resolveServeRuntimeOrigin({
+      hostname: server.hostname ?? fallbackServeOptions.hostname,
+      port: server.port ?? fallbackServeOptions.port
+    });
+  }
+}
+export {
+  BunRuntimeHost
+};

package/src/adapters/bun/server-adapter.d.ts

@@ -0,0 +1,223 @@
+import type { Server, WebSocketHandler } from 'bun';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { ApiHandler, ErrorHandler, StaticRoute } from '../../types/public-types.js';
+import { SharedServerAdapter } from '../shared/server-adapter.js';
+import type { ServerAdapterResult } from '../abstract/server-adapter.js';
+import type { StaticPreviewHost } from '../shared/static-preview-host.js';
+import { ClientBridge } from './client-bridge.js';
+import { HmrManager } from './hmr-manager.js';
+type BunServerInstance = Server<unknown>;
+type BunNativeServeOptions = Bun.Serve.Options<unknown>;
+export type BunServerRoutes = Bun.Serve.Routes<unknown, string>;
+export type BunServeAdapterServerOptions = Partial<Omit<BunNativeServeOptions, 'fetch'> & {
+    fetch(this: BunServerInstance, request: Request): Promise<void | Response>;
+}>;
+export type BunServeOptions = Omit<BunNativeServeOptions, 'fetch'> & {
+    fetch?: (this: BunServerInstance, request: Request, server: BunServerInstance) => Promise<void | Response>;
+    websocket?: WebSocketHandler<unknown>;
+};
+/**
+ * Construction parameters for the Bun server adapter.
+ *
+ * @remarks
+ * Callers normally provide only the app-facing fields such as routes, handlers,
+ * and `serveOptions`. The transport collaborators remain optional here because
+ * `createBunServerAdapter()` fills in Bun-specific defaults before the concrete
+ * adapter instance is created.
+ */
+export interface BunServerAdapterParams {
+    appConfig: EcoPagesAppConfig;
+    runtimeOrigin: string;
+    serveOptions: BunServeAdapterServerOptions;
+    apiHandlers?: ApiHandler<string, Request, BunServerInstance>[];
+    staticRoutes?: StaticRoute[];
+    errorHandler?: ErrorHandler;
+    options?: {
+        watch?: boolean;
+    };
+    hmrManager?: HmrManager;
+    bridge?: ClientBridge;
+    previewHost?: StaticPreviewHost;
+}
+export interface BunServerAdapterResult extends ServerAdapterResult {
+    getServerOptions: (options?: {
+        enableHmr?: boolean;
+    }) => BunServeOptions;
+    buildStatic: (options?: {
+        preview?: boolean;
+    }) => Promise<void>;
+    completeInitialization: (server?: BunServerInstance | null) => Promise<void>;
+    handleRequest: (request: Request) => Promise<Response>;
+}
+/**
+ * Bun transport adapter that wires shared Ecopages request handling onto a live
+ * `Bun.serve()` runtime.
+ *
+ * @remarks
+ * The adapter owns Bun-specific concerns that do not exist in the shared server
+ * abstraction: websocket-backed HMR transport, runtime plugin registration, and
+ * preview-host startup for static builds. Routing, rendering, and response
+ * composition still delegate to the shared server adapter base.
+ */
+export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapterParams, BunServerAdapterResult> {
+    appConfig: EcoPagesAppConfig;
+    options: BunServerAdapterParams['options'];
+    serveOptions: BunServeAdapterServerOptions;
+    protected apiHandlers: ApiHandler<string, Request, BunServerInstance>[];
+    protected staticRoutes: StaticRoute[];
+    protected errorHandler?: ErrorHandler;
+    private bridge;
+    hmrManager: HmrManager;
+    private initializationPromise;
+    private fullyInitialized;
+    serverInstance: BunServerInstance | null;
+    private readonly previewHost;
+    /**
+     * Creates a Bun server adapter with already-resolved runtime collaborators.
+     *
+     * @remarks
+     * The public params interface keeps `hmrManager`, `bridge`, and `previewHost`
+     * optional so factory callers can omit them. By the time the concrete adapter
+     * is constructed, those collaborators are mandatory because the adapter cannot
+     * initialize Bun HMR or preview flows without them.
+     */
+    constructor({ appConfig, runtimeOrigin, serveOptions, apiHandlers, staticRoutes, errorHandler, options, hmrManager, bridge, previewHost, }: BunServerAdapterParams & {
+        hmrManager: HmrManager;
+        bridge: ClientBridge;
+        previewHost: StaticPreviewHost;
+    });
+    /**
+     * Returns whether adapter-level HTML responses still need HMR runtime injection.
+     *
+     * @remarks
+     * Filesystem-routed pages are wrapped later in the shared route layer. This
+     * adapter-level check exists for explicit API handlers that return HTML and
+     * would otherwise bypass the route wrapper entirely.
+     */
+    private shouldInjectHmrScript;
+    /**
+     * Delegates the HTML-response test to the shared response helper used by both
+     * adapters.
+     */
+    private isHtmlResponse;
+    /**
+     * Injects HMR script into HTML responses in development mode.
+     * Ensures explicit API handlers that return HTML get auto-reload capability.
+     */
+    private maybeInjectHmrScript;
+    /**
+     * Initializes the server adapter's core runtime components.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Copies the source `public` directory into the runtime output and ensures the
+     * HMR assets directory exists before any runtime bundles are emitted.
+     */
+    private prepareRuntimePublicDir;
+    /**
+     * Registers runtime plugins and propagates the final HMR manager into each
+     * integration.
+     *
+     * @remarks
+     * This is where Bun's runtime-plugin registration path meets the integration
+     * lifecycle. A failure here leaves the runtime partially bootstrapped, so the
+     * method logs the underlying error and rethrows instead of trying to limp on.
+     */
+    private initializeRuntimePlugins;
+    /**
+     * Rebuilds the shared routing state and hot-reloads the live Bun server when a
+     * watched route file changes.
+     */
+    private refreshRouterRoutes;
+    private watch;
+    /**
+     * Builds the `Bun.serve()` options for the current adapter state.
+     *
+     * @remarks
+     * The HMR-enabled variant wraps the base fetch handler so one Bun server can
+     * serve normal requests, accept HMR websocket upgrades, and expose the HMR
+     * runtime asset without splitting responsibility across separate listeners.
+     */
+    getServerOptions({ enableHmr }?: {
+        enableHmr?: boolean | undefined;
+    }): BunServeOptions;
+    /**
+     * Helper method to retrieve and parse the request body.
+     * Handles JSON and plain text content types.
+     * For FormData (multipart/form-data, x-www-form-urlencoded), use ctx.request.formData() directly.
+     * Returns undefined for unsupported content types.
+     */
+    private retrieveBodyFromRequest;
+    /**
+     * Composes the base Bun server settings that all runtime modes build from.
+     *
+     * @remarks
+     * This method centralizes the Bun-specific error boundary. It preserves the
+     * shared route pipeline while still allowing adapter-level custom error-handler
+     * execution and `HttpError` passthrough.
+     */
+    private buildServerSettings;
+    /**
+     * Generates a static build of the site for deployment.
+     * @param options.preview - If true, starts a preview server after build
+     */
+    buildStatic(options?: {
+        preview?: boolean;
+    }): Promise<void>;
+    /**
+     * Initializes the server with dynamic routes after server creation.
+     * Must be called before handling any requests.
+     * @param server - The Bun server instance
+     */
+    completeInitialization(server?: BunServerInstance | null): Promise<void>;
+    /**
+     * Performs the one-time post-bind initialization path for Bun servers.
+     *
+     * @remarks
+     * This is intentionally split from `initialize()` because shared route handling
+     * and file watching need the live server instance to exist before Bun can
+     * reload updated route handlers in place.
+     */
+    private _performInitialization;
+    /**
+     * Creates and initializes the Bun server adapter.
+     * @returns Configured adapter with server methods
+     */
+    createAdapter(): Promise<BunServerAdapterResult>;
+    /**
+     * Handles HTTP requests by passing them securely to the shared core router adapter.
+     *
+     * @remarks
+     * Filesystem page responses are wrapped by `ServerRouteHandler`. This
+     * adapter-level pass only covers HTML returned by explicit API handlers,
+     * which bypass that route-layer wrapper and would otherwise miss the
+     * dev HMR runtime — so the HMR script injection happens here, after
+     * the shared handler runs.
+     */
+    handleRequest(request: Request): Promise<Response>;
+    /**
+     * Ensures server initialization completes before request handling.
+     * Prevents race conditions during startup.
+     */
+    private waitForInitialization;
+    /**
+     * Handles HTTP requests from the router adapter.
+     */
+    handleResponse(request: Request): Promise<Response>;
+    /**
+     * Handles requests that do not match any routes.
+     */
+    private handleNoMatch;
+}
+/**
+ * Creates the Bun server adapter and fills in the runtime-specific collaborators
+ * that Bun callers usually leave implicit.
+ *
+ * @remarks
+ * This is the canonical entry point for Bun server-adapter construction. It
+ * guarantees that the concrete adapter receives a Bun websocket bridge, HMR
+ * manager, and preview host even though those dependencies are optional on the
+ * public params type.
+ */
+export declare function createBunServerAdapter(params: BunServerAdapterParams): Promise<BunServerAdapterResult>;
+export {};