@ecopages/core 0.2.0-beta.4 → 0.2.0-beta.40

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

@@ -1,9 +1,10 @@
+import type { Server as NodeHttpServer } from 'node:http';
 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 { ApiHandler, ErrorHandler, StaticRoute, EcopagesWebSocketHandler } from '../../types/public-types.js';
+import { SharedServerAdapter } from '../shared/runtime/server-adapter.js';
 import type { ServerAdapterResult } from '../abstract/server-adapter.js';
-import type { StaticPreviewHost } from '../shared/static-preview-host.js';
+import type { StaticPreviewHost } from '../shared/runtime/static-preview-host.js';
 import { ClientBridge } from './client-bridge.js';
 import { HmrManager } from './hmr-manager.js';
 type BunServerInstance = Server<unknown>;
@@ -32,9 +33,13 @@ export interface BunServerAdapterParams {
     apiHandlers?: ApiHandler<string, Request, BunServerInstance>[];
     staticRoutes?: StaticRoute[];
     errorHandler?: ErrorHandler;
+    websocketHandlers?: Map<string, EcopagesWebSocketHandler<any, any>>;
     options?: {
         watch?: boolean;
     };
+    hostOwnsDevClient?: boolean;
+    deferRuntimeAssetSetup?: boolean;
+    allowPortFallback?: boolean;
     hmrManager?: HmrManager;
     bridge?: ClientBridge;
     previewHost?: StaticPreviewHost;
@@ -45,9 +50,15 @@ export interface BunServerAdapterResult extends ServerAdapterResult {
     }) => BunServeOptions;
     buildStatic: (options?: {
         preview?: boolean;
-    }) => Promise<void>;
+        force?: boolean;
+    }) => Promise<string | undefined>;
+    servePreviewOnly: () => Promise<string | undefined>;
     completeInitialization: (server?: BunServerInstance | null) => Promise<void>;
     handleRequest: (request: Request) => Promise<Response>;
+    attachUserWebSocketUpgrades: (server: NodeHttpServer, options?: {
+        passthroughUnmatched?: boolean;
+    }) => void;
+    dispose: () => Promise<void>;
 }
 /**
  * Bun transport adapter that wires shared Ecopages request handling onto a live
@@ -71,7 +82,39 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
     private initializationPromise;
     private fullyInitialized;
     serverInstance: BunServerInstance | null;
+    private projectWatcher;
+    private adapterDisposed;
+    private readonly deferRuntimeAssetSetup;
+    private readonly allowPortFallback;
     private readonly previewHost;
+    /**
+     * Reference to the application-level WebSocket handlers map.
+     *
+     * @remarks
+     * This is a reference to the map owned by `AbstractApplicationAdapter`,
+     * passed in via the constructor. The Bun adapter reads from it to wire
+     * WebSocket upgrades for user-registered patterns.
+     */
+    protected websocketHandlers: Map<string, EcopagesWebSocketHandler<any, any>>;
+    private registerBunRuntimePlugin;
+    private adaptBunWebSocket;
+    /**
+     * Resolves the per-connection context for a Bun user connection.
+     *
+     * @remarks
+     * `context()` is invoked exactly once per accepted connection. Its
+     * resolved value is shared by all subsequent lifecycle hooks. If
+     * `context()` throws, the connection is closed immediately with code
+     * 1011 (server error) and the error is logged.
+     *
+     * @param request - The original upgrade request (best-effort reconstructed)
+     * @param handler - The registered handler
+     * @param kind - The registered route pattern
+     * @param params - Dynamic path parameters
+     * @param search - Query string parameters
+     * @returns The resolved per-connection context
+     */
+    private resolveBunContext;
     /**
      * Creates a Bun server adapter with already-resolved runtime collaborators.
      *
@@ -81,39 +124,21 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
      * 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 & {
+    constructor({ appConfig, runtimeOrigin, serveOptions, apiHandlers, staticRoutes, errorHandler, websocketHandlers, options, hostOwnsDevClient, deferRuntimeAssetSetup, allowPortFallback, 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.
+     * Wires user WebSocket routes onto a Node HTTP server used by host integrations.
      */
-    private maybeInjectHmrScript;
+    attachUserWebSocketUpgrades(server: NodeHttpServer, options?: {
+        passthroughUnmatched?: boolean;
+    }): void;
     /**
      * 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.
@@ -134,20 +159,32 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
      * 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.
+     * When HMR is enabled the websocket dispatcher merges HMR and user handlers,
+     * routing by the `kind` field embedded in socket data at upgrade time.
+     * This prevents user-registered websocket handlers from being silently overwritten
+     * by the HMR handler in development mode.
+     *
+     * User WebSocket paths are intercepted in the fetch handler via the pattern matcher.
+     * The upgrade happens implicitly — no manual GET route registration needed.
      */
     getServerOptions({ enableHmr }?: {
         enableHmr?: boolean | undefined;
     }): BunServeOptions;
+    private createBunUserLifecycle;
+    /**
+     * @remarks
+     * HMR and user sockets share one Bun `websocket` handler. Upgrade tags HMR
+     * connections with `kind: '__hmr__'`; everything else routes to the user lifecycle.
+     */
+    private createHmrAwareWebSocketHandler;
     /**
-     * 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.
+     * @remarks
+     * When `serveHmrEndpoints` is set, `/_hmr` is checked before user websocket
+     * patterns so HMR upgrades are never captured by app routes. Runtime assets are
+     * served by `SharedServerAdapter.handleSharedRequest` via `tryHandleAssetRequest`.
+     * Production mode with only user handlers skips the HMR branch entirely.
      */
-    private retrieveBodyFromRequest;
+    private wrapFetchWithWebSocketUpgrades;
     /**
      * Composes the base Bun server settings that all runtime modes build from.
      *
@@ -163,7 +200,14 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
      */
     buildStatic(options?: {
         preview?: boolean;
-    }): Promise<void>;
+        force?: boolean;
+    }): Promise<string | undefined>;
+    /**
+     * Serves an existing static export without running SSG. Used by e2e preview
+     * launchers after a shared prewarm build.
+     */
+    servePreviewOnly(): Promise<string | undefined>;
+    private startPreviewServer;
     /**
      * Initializes the server with dynamic routes after server creation.
      * Must be called before handling any requests.
@@ -184,15 +228,21 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
      * @returns Configured adapter with server methods
      */
     createAdapter(): Promise<BunServerAdapterResult>;
+    /**
+     * Releases dev-time resources owned by the adapter.
+     *
+     * @remarks
+     * Safe to call multiple times. Does not stop the bound Bun server — callers
+     * should shut down transport through the runtime host before disposing.
+     */
+    dispose(): Promise<void>;
     /**
      * 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.
+     * HMR HTML injection for API and page responses is owned by
+     * `SharedServerAdapter.handleSharedRequest`. This method only maps the
+     * request into the shared pipeline.
      */
     handleRequest(request: Request): Promise<Response>;
     /**