@ecopages/core 0.2.0-beta.3 → 0.2.0-beta.5

package/src/adapters/bun/server-adapter.js

@@ -4,6 +4,7 @@ import { RESOLVED_ASSETS_DIR } from "../../config/constants.js";
 import { appLogger } from "../../global/app-logger.js";
 import { HttpError } from "../../errors/http-error.js";
 import { createRequire } from "../../utils/locals-utils.js";
+import { findWebSocketRoute } from "../abstract/ws-pattern-matcher.js";
 import { fileSystem } from "@ecopages/file-system";
 import { getAppBrowserBuildPlugins, setupAppRuntimePlugins } from "../../build/build-adapter.js";
 import { installAppRuntimeBuildExecutor } from "../../build/runtime-build-executor.js";
@@ -17,6 +18,8 @@ import {
   isHtmlResponse,
   shouldInjectHmrHtmlResponse
 } from "../shared/hmr-html-response.js";
+import { attachNodeHttpWebSocketUpgrades } from "../shared/node-http-websocket-upgrades.js";
+import { createBunUserWebSocketLifecycle } from "../shared/bun-user-websocket-lifecycle.js";
 import { resolveServeRuntimeOrigin } from "../shared/runtime-app-bootstrap.js";
 import { ClientBridge } from "./client-bridge.js";
 import { HmrManager } from "./hmr-manager.js";
@@ -30,6 +33,90 @@ class BunServerAdapter extends SharedServerAdapter {
   initializationPromise = null;
   fullyInitialized = false;
   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.
+   */
+  websocketHandlers = /* @__PURE__ */ new Map();
+  /**
+   * Adapts a Bun ServerWebSocket to the public EcopagesSocket interface.
+   *
+   * @remarks
+   * This is the single source of truth for the Bun→public type adaptation.
+   * Both the HMR and production branches use this helper to ensure consistency.
+   *
+   * @param ws - The raw Bun ServerWebSocket
+   * @param kind - The registered route pattern
+   * @param params - Dynamic path parameters
+   * @param search - Query string parameters
+   * @param context - The resolved per-connection context
+   * @returns An EcopagesSocket view
+   */
+  adaptBunWebSocket(ws, kind, params, search, context) {
+    return {
+      kind,
+      params,
+      search,
+      context,
+      send: (message) => {
+        if (typeof message === "string") {
+          ws.send(message);
+        } else if (message instanceof Blob) {
+          void message.arrayBuffer().then((buf) => ws.send(new Uint8Array(buf)));
+        } else if (message instanceof ArrayBuffer) {
+          ws.send(new Uint8Array(message));
+        } else if (ArrayBuffer.isView(message)) {
+          ws.send(new Uint8Array(message.buffer, message.byteOffset, message.byteLength));
+        } else {
+          ws.send(message);
+        }
+      },
+      sendStream: async (stream) => {
+        const reader = stream.getReader();
+        try {
+          while (true) {
+            const { value, done } = await reader.read();
+            if (done) break;
+            if (value) ws.send(value);
+          }
+        } finally {
+          reader.releaseLock();
+        }
+      },
+      close: (code, reason) => ws.close(code, reason)
+    };
+  }
+  /**
+   * 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
+   */
+  async resolveBunContext(request, handler, kind, params, search) {
+    if (!handler.context) {
+      return void 0;
+    }
+    try {
+      return await handler.context({ request, kind, params, search });
+    } catch (error) {
+      appLogger.error(`[WS:${kind}] context() failed; closing connection.`, error);
+      throw error;
+    }
+  }
   /**
    * Creates a Bun server adapter with already-resolved runtime collaborators.
    *
@@ -46,6 +133,7 @@ class BunServerAdapter extends SharedServerAdapter {
     apiHandlers,
     staticRoutes,
     errorHandler,
+    websocketHandlers,
     options,
     hmrManager,
     bridge,
@@ -58,6 +146,19 @@ class BunServerAdapter extends SharedServerAdapter {
     this.bridge = bridge;
     this.hmrManager = hmrManager;
     this.previewHost = previewHost;
+    if (websocketHandlers) {
+      this.websocketHandlers = websocketHandlers;
+    }
+  }
+  /**
+   * Wires user WebSocket routes onto a Node HTTP server used by host integrations.
+   */
+  attachUserWebSocketUpgrades(server, options) {
+    attachNodeHttpWebSocketUpgrades(server, {
+      runtimeOrigin: this.runtimeOrigin,
+      websocketHandlers: this.websocketHandlers,
+      passthroughUnmatched: options?.passthroughUnmatched
+    });
   }
   /**
    * Returns whether adapter-level HTML responses still need HMR runtime injection.
@@ -181,9 +282,13 @@ class BunServerAdapter extends SharedServerAdapter {
    * 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 = false } = {}) {
     appLogger.debug(`[BunServerAdapter] getServerOptions called with enableHmr: ${enableHmr}`);
@@ -192,14 +297,54 @@ class BunServerAdapter extends SharedServerAdapter {
       const originalFetch = serverOptions.fetch;
       const hmrHandler = this.hmrManager.getWebSocketHandler();
       const hmrManager = this.hmrManager;
+      const matchRoute = (pathname) => findWebSocketRoute(this.websocketHandlers, pathname);
+      const userLifecycle = createBunUserWebSocketLifecycle({
+        runtimeOrigin: this.runtimeOrigin,
+        userHandlers: this.websocketHandlers,
+        resolveContext: this.resolveBunContext.bind(this),
+        adaptSocket: (ws, kind, params, search, context) => this.adaptBunWebSocket(ws, kind, params, search, context)
+      });
       serverOptions.development = true;
-      serverOptions.websocket = hmrHandler;
+      serverOptions.websocket = {
+        open(ws) {
+          const kind = ws.data?.kind ?? "__hmr__";
+          if (kind === "__hmr__") {
+            hmrHandler.open?.(ws);
+            return;
+          }
+          userLifecycle.open(ws);
+        },
+        message(ws, msg) {
+          const kind = ws.data?.kind ?? "__hmr__";
+          if (kind === "__hmr__") {
+            hmrHandler.message?.(ws, msg);
+            return;
+          }
+          userLifecycle.message(ws, msg);
+        },
+        close(ws, code, reason) {
+          const kind = ws.data?.kind ?? "__hmr__";
+          if (kind === "__hmr__") {
+            hmrHandler.close?.(ws, code, reason);
+            return;
+          }
+          userLifecycle.close(ws, code, reason);
+        },
+        error(ws, error) {
+          const kind = ws.data?.kind ?? "__hmr__";
+          if (kind === "__hmr__") {
+            appLogger.error("[HMR] WebSocket error:", error);
+            return;
+          }
+          userLifecycle.error(ws, error);
+        }
+      };
       serverOptions.fetch = async function(request, _server) {
         const url = new URL(request.url);
         appLogger.debug(`[HMR] Request: ${url.pathname}`);
         if (url.pathname === "/_hmr") {
           const success = this.upgrade(request, {
-            data: void 0
+            data: { kind: "__hmr__", params: {}, search: {} }
           });
           if (success) return;
           return new Response("WebSocket upgrade failed", { status: 400 });
@@ -210,6 +355,55 @@ class BunServerAdapter extends SharedServerAdapter {
             headers: { "Content-Type": "application/javascript" }
           });
         }
+        const wsMatch = matchRoute(url.pathname);
+        if (wsMatch && request.headers.get("upgrade")?.toLowerCase() === "websocket") {
+          const search = Object.fromEntries(url.searchParams.entries());
+          const success = this.upgrade(request, {
+            data: {
+              kind: wsMatch.kind,
+              params: wsMatch.params,
+              search,
+              upgradeUrl: request.url
+            }
+          });
+          if (success) return;
+          return new Response("WebSocket upgrade failed", { status: 400 });
+        }
+        let response;
+        if (originalFetch) {
+          const res = await originalFetch.call(this, request, this);
+          response = res instanceof Response ? res : new Response("Not Found", { status: 404 });
+        } else {
+          response = new Response("Not Found", { status: 404 });
+        }
+        return response;
+      };
+    } else if (this.websocketHandlers.size > 0) {
+      const matchRoute = (pathname) => findWebSocketRoute(this.websocketHandlers, pathname);
+      const userLifecycle = createBunUserWebSocketLifecycle({
+        runtimeOrigin: this.runtimeOrigin,
+        userHandlers: this.websocketHandlers,
+        resolveContext: this.resolveBunContext.bind(this),
+        adaptSocket: (ws, kind, params, search, context) => this.adaptBunWebSocket(ws, kind, params, search, context)
+      });
+      serverOptions.websocket = userLifecycle;
+      const originalFetch = serverOptions.fetch;
+      serverOptions.fetch = async function(request, _server) {
+        const url = new URL(request.url);
+        const wsMatch = matchRoute(url.pathname);
+        if (wsMatch && request.headers.get("upgrade")?.toLowerCase() === "websocket") {
+          const search = Object.fromEntries(url.searchParams.entries());
+          const success = this.upgrade(request, {
+            data: {
+              kind: wsMatch.kind,
+              params: wsMatch.params,
+              search,
+              upgradeUrl: request.url
+            }
+          });
+          if (success) return;
+          return new Response("WebSocket upgrade failed", { status: 400 });
+        }
         let response;
         if (originalFetch) {
           const res = await originalFetch.call(this, request, this);
@@ -380,7 +574,8 @@ class BunServerAdapter extends SharedServerAdapter {
       getServerOptions: this.getServerOptions.bind(this),
       buildStatic: this.buildStatic.bind(this),
       completeInitialization: this.completeInitialization.bind(this),
-      handleRequest: this.handleRequest.bind(this)
+      handleRequest: this.handleRequest.bind(this),
+      attachUserWebSocketUpgrades: this.attachUserWebSocketUpgrades.bind(this)
     };
   }
   /**

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

@@ -19,6 +19,9 @@ export declare class NodeEcopagesApp extends SharedApplicationAdapter<EcopagesAp
     protected initializeServerAdapter(): Promise<NodeServerAdapterResult>;
     start(): Promise<NodeServerInstance | void>;
     fetch(request: Request): Promise<Response>;
+    attachWebSocketUpgrades(httpServer: import('node:http').Server, options?: {
+        passthroughUnmatched?: boolean;
+    }): Promise<void>;
 }
 export declare function createNodeApp(options: EcopagesAppOptions): Promise<NodeEcopagesApp>;
 export declare function createApp(options: EcopagesAppOptions): Promise<NodeEcopagesApp>;

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

@@ -36,6 +36,7 @@ class NodeEcopagesApp extends SharedApplicationAdapter {
       apiHandlers: this.apiHandlers,
       staticRoutes: this.staticRoutes,
       errorHandler: this.errorHandler,
+      websocketHandlers: this.websocketHandlers.size > 0 ? this.websocketHandlers : void 0,
       options: { watch: binding.watch },
       serveOptions: binding.serveOptions
     });
@@ -76,6 +77,12 @@ class NodeEcopagesApp extends SharedApplicationAdapter {
     }
     return this.serverAdapter.handleRequest(request);
   }
+  async attachWebSocketUpgrades(httpServer, options) {
+    if (!this.serverAdapter) {
+      this.serverAdapter = await this.initializeServerAdapter();
+    }
+    this.serverAdapter.attachUserWebSocketUpgrades(httpServer, options);
+  }
 }
 async function createNodeApp(options) {
   return new NodeEcopagesApp(options, {

package/src/adapters/node/node-hmr-manager.d.ts

@@ -4,6 +4,7 @@ import { SharedHmrManager } from '../shared/shared-hmr-manager.js';
 export interface NodeHmrManagerParams {
     appConfig: EcoPagesAppConfig;
     bridge: IClientBridge;
+    registrationTimeoutMs?: number;
 }
 /**
  * Node development HMR manager.
@@ -28,7 +29,7 @@ export declare class NodeHmrManager extends SharedHmrManager {
      * actually differs: dependency-graph storage, missing-file tolerance, and how
      * runtime bundle failures disable HMR.
      */
-    constructor({ appConfig, bridge }: NodeHmrManagerParams);
+    constructor({ appConfig, bridge, registrationTimeoutMs }: NodeHmrManagerParams);
     /**
      * Reuses the shared in-memory dependency graph when the app already has one and
      * otherwise creates the default Node development graph.

package/src/adapters/node/node-hmr-manager.js

@@ -13,8 +13,8 @@ class NodeHmrManager extends SharedHmrManager {
    * actually differs: dependency-graph storage, missing-file tolerance, and how
    * runtime bundle failures disable HMR.
    */
-  constructor({ appConfig, bridge }) {
-    super({ appConfig, bridge });
+  constructor({ appConfig, bridge, registrationTimeoutMs }) {
+    super({ appConfig, bridge, registrationTimeoutMs });
   }
   /**
    * Reuses the shared in-memory dependency graph when the app already has one and

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

@@ -1,6 +1,6 @@
 import { type Server as NodeHttpServer } from 'node:http';
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { ApiHandler, ErrorHandler, StaticRoute } from '../../types/public-types.js';
+import type { ApiHandler, ErrorHandler, StaticRoute, EcopagesWebSocketHandler } from '../../types/public-types.js';
 import { SharedServerAdapter } from '../shared/server-adapter.js';
 import type { ServerAdapterResult } from '../abstract/server-adapter.js';
 import { NodeHttpRequestBridge } from './http-request-bridge.js';
@@ -19,6 +19,7 @@ export interface NodeServerAdapterParams {
     apiHandlers?: ApiHandler[];
     staticRoutes?: StaticRoute[];
     errorHandler?: ErrorHandler;
+    websocketHandlers?: Map<string, EcopagesWebSocketHandler<any, any>>;
     options?: {
         watch?: boolean;
     };
@@ -29,6 +30,9 @@ export interface NodeServerAdapterParams {
 export interface NodeServerAdapterResult extends ServerAdapterResult {
     completeInitialization: (server: NodeServerInstance) => Promise<void>;
     handleRequest: (request: Request) => Promise<Response>;
+    attachUserWebSocketUpgrades: (server: NodeServerInstance, options?: {
+        passthroughUnmatched?: boolean;
+    }) => void;
 }
 /**
  * Node.js HTTP server adapter for the Ecopages runtime.
@@ -61,6 +65,25 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
     private readonly previewHost;
     private readonly requestBridge;
     private readonly devRuntimeFactory;
+    /**
+     * 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 Node adapter reads from it to wire
+     * WebSocket upgrades for user-registered patterns.
+     */
+    protected websocketHandlers: Map<string, EcopagesWebSocketHandler<any, any>>;
+    /**
+     * Wires user WebSocket routes onto a foreign Node HTTP server.
+     *
+     * Host integrations such as the Vite plugin call this so `app.websocket()`
+     * handlers work while HTTP is still served by the host dev server.
+     */
+    attachUserWebSocketUpgrades(server: NodeServerInstance, options?: {
+        passthroughUnmatched?: boolean;
+    }): void;
+    private wireUserWebSocketUpgrades;
     private shouldInjectHmrScript;
     private isHtmlResponse;
     private maybeInjectHmrScript;
@@ -123,7 +146,7 @@ export declare class NodeServerAdapter extends SharedServerAdapter<NodeServerAda
      * - Shared watcher bootstrapping listens for route-level file changes and
      *   refreshes the router and response handlers when pages are added or removed.
      *
-     * WebSocket upgrade requests that do not target `/_hmr` are rejected with an
+     * WebSocket upgrade requests that do not match a known path are rejected with an
      * immediate socket destroy to prevent unhandled upgrade leaks.
      */
     completeInitialization(server: NodeServerInstance): Promise<void>;

package/src/adapters/node/server-adapter.js

@@ -8,6 +8,9 @@ import { appLogger } from "../../global/app-logger.js";
 import { NodeClientBridge } from "./node-client-bridge.js";
 import { NodeHmrManager } from "./node-hmr-manager.js";
 import { ProjectWatcher } from "../../watchers/project-watcher.js";
+import {
+  attachNodeHttpWebSocketUpgrades
+} from "../shared/node-http-websocket-upgrades.js";
 import { StaticSiteGenerator } from "../../static-site-generator/static-site-generator.js";
 import { SharedServerAdapter } from "../shared/server-adapter.js";
 import { ServerStaticBuilder } from "../shared/server-static-builder.js";
@@ -32,6 +35,36 @@ class NodeServerAdapter extends SharedServerAdapter {
   previewHost;
   requestBridge;
   devRuntimeFactory;
+  /**
+   * 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 Node adapter reads from it to wire
+   * WebSocket upgrades for user-registered patterns.
+   */
+  websocketHandlers = /* @__PURE__ */ new Map();
+  /**
+   * Wires user WebSocket routes onto a foreign Node HTTP server.
+   *
+   * Host integrations such as the Vite plugin call this so `app.websocket()`
+   * handlers work while HTTP is still served by the host dev server.
+   */
+  attachUserWebSocketUpgrades(server, options) {
+    attachNodeHttpWebSocketUpgrades(server, {
+      runtimeOrigin: this.runtimeOrigin,
+      websocketHandlers: this.websocketHandlers,
+      passthroughUnmatched: options?.passthroughUnmatched
+    });
+  }
+  wireUserWebSocketUpgrades(server, preflight) {
+    attachNodeHttpWebSocketUpgrades(server, {
+      runtimeOrigin: this.runtimeOrigin,
+      websocketHandlers: this.websocketHandlers,
+      passthroughUnmatched: false,
+      preflight
+    });
+  }
   shouldInjectHmrScript() {
     return shouldInjectHmrHtmlResponse(this.options?.watch === true, this.hmrManager ?? void 0);
   }
@@ -52,6 +85,9 @@ class NodeServerAdapter extends SharedServerAdapter {
     this.previewHost = options.previewHost;
     this.requestBridge = options.requestBridge;
     this.devRuntimeFactory = options.devRuntimeFactory;
+    if (options.websocketHandlers) {
+      this.websocketHandlers = options.websocketHandlers;
+    }
   }
   /**
    * Prepares the adapter for use.
@@ -200,7 +236,8 @@ class NodeServerAdapter extends SharedServerAdapter {
       getServerOptions: this.getServerOptions.bind(this),
       buildStatic: this.buildStatic.bind(this),
       completeInitialization: this.completeInitialization.bind(this),
-      handleRequest: this.handleRequest.bind(this)
+      handleRequest: this.handleRequest.bind(this),
+      attachUserWebSocketUpgrades: this.attachUserWebSocketUpgrades.bind(this)
     };
   }
   /**
@@ -244,11 +281,12 @@ class NodeServerAdapter extends SharedServerAdapter {
    * - Shared watcher bootstrapping listens for route-level file changes and
    *   refreshes the router and response handlers when pages are added or removed.
    *
-   * WebSocket upgrade requests that do not target `/_hmr` are rejected with an
+   * WebSocket upgrade requests that do not match a known path are rejected with an
    * immediate socket destroy to prevent unhandled upgrade leaks.
    */
   async completeInitialization(server) {
     this.serverInstance = server;
+    const hasUserWs = this.websocketHandlers.size > 0;
     if (this.options?.watch) {
       const devRuntime = this.devRuntimeFactory.create({ appConfig: this.appConfig });
       const wss = devRuntime.websocketServer;
@@ -256,18 +294,25 @@ class NodeServerAdapter extends SharedServerAdapter {
       this.hmrManager = devRuntime.hmrManager;
       this.hmrManager.setEnabled(true);
       await this.hmrManager.buildRuntime();
-      server.on("upgrade", (req, socket, head) => {
+      const hmrPreflight = (req, socket, head) => {
         const url = new URL(req.url ?? "/", this.runtimeOrigin);
-        if (url.pathname === "/_hmr") {
-          wss.handleUpgrade(req, socket, head, (ws) => {
-            this.bridge.subscribe(ws);
-            ws.on("close", () => this.bridge.unsubscribe(ws));
-            ws.on("error", (err) => appLogger.error("[HMR] WebSocket error:", err));
-          });
-        } else {
-          socket.destroy();
-        }
-      });
+        if (url.pathname !== "/_hmr") return false;
+        wss.handleUpgrade(req, socket, head, (ws) => {
+          this.bridge.subscribe(ws);
+          ws.on("close", () => this.bridge.unsubscribe(ws));
+          ws.on("error", (err) => appLogger.error("[HMR] WebSocket error:", err));
+        });
+        return true;
+      };
+      if (hasUserWs) {
+        this.wireUserWebSocketUpgrades(server, hmrPreflight);
+      } else {
+        server.on("upgrade", (req, socket, head) => {
+          if (!hmrPreflight(req, socket, head)) {
+            socket.destroy();
+          }
+        });
+      }
       const browserBuildPlugins = getAppBrowserBuildPlugins(this.appConfig);
       this.hmrManager.setPlugins(browserBuildPlugins);
       for (const integration of this.appConfig.integrations) {
@@ -284,6 +329,8 @@ class NodeServerAdapter extends SharedServerAdapter {
         bridge: this.bridge
       });
       await watcher.createWatcherSubscription();
+    } else if (hasUserWs) {
+      this.wireUserWebSocketUpgrades(server);
     }
     appLogger.debug("Node server adapter initialization completed", {
       apiHandlers: this.apiHandlers.length,

package/src/adapters/shared/bun-user-websocket-lifecycle.d.ts

@@ -0,0 +1,22 @@
+import type { ServerWebSocket } from 'bun';
+import type { EcopagesSocket, EcopagesWebSocketHandler } from '../../types/public-types.js';
+export type BunUserWebSocketData = {
+    kind: string;
+    params: Record<string, string>;
+    search: Record<string, string>;
+    upgradeUrl?: string;
+    context?: unknown;
+    [key: string]: unknown;
+};
+export type BunUserWebSocketLifecycleDeps<TWsData extends BunUserWebSocketData> = {
+    runtimeOrigin: string;
+    userHandlers: Map<string, EcopagesWebSocketHandler<any, any>>;
+    resolveContext: <TContext, TParams extends Record<string, string>>(request: Request, handler: EcopagesWebSocketHandler<TContext, TParams>, kind: string, params: TParams, search: Record<string, string>) => Promise<TContext>;
+    adaptSocket: <TContext, TParams extends Record<string, string>>(ws: ServerWebSocket<TWsData>, kind: string, params: TParams, search: Record<string, string>, context: TContext) => EcopagesSocket<TContext, TParams>;
+};
+export declare function createBunUserWebSocketLifecycle<TWsData extends BunUserWebSocketData>(deps: BunUserWebSocketLifecycleDeps<TWsData>): {
+    open(ws: ServerWebSocket<TWsData>): void;
+    message(ws: ServerWebSocket<TWsData>, msg: string | Buffer): void;
+    close(ws: ServerWebSocket<TWsData>, code: number, reason: string): void;
+    error(ws: ServerWebSocket<TWsData>, error: Error): void;
+};

package/src/adapters/shared/bun-user-websocket-lifecycle.js

@@ -0,0 +1,102 @@
+import { appLogger } from "../../global/app-logger.js";
+import { invokeWebSocketHandlerHook, toWebSocketCloseInfo } from "./websocket-lifecycle.js";
+function toUpgradeRequest(ws, runtimeOrigin) {
+  const upgradeUrl = ws.data?.upgradeUrl;
+  if (upgradeUrl) {
+    return new Request(upgradeUrl);
+  }
+  return new Request(runtimeOrigin);
+}
+async function runUserWebSocketOpen(ws, kind, deps) {
+  const handler = deps.userHandlers.get(kind);
+  if (!handler) {
+    return;
+  }
+  const params = ws.data?.params ?? {};
+  const search = ws.data?.search ?? {};
+  const request = toUpgradeRequest(ws, deps.runtimeOrigin);
+  let context;
+  try {
+    context = await deps.resolveContext(request, handler, kind, params, search);
+  } catch {
+    ws.close(1011, "context initialization failed");
+    return;
+  }
+  ws.data.context = context;
+  const socket = deps.adaptSocket(ws, kind, params, search, context);
+  try {
+    await handler.onConnect?.(socket);
+  } catch (error) {
+    appLogger.error(`[WS:${kind}] onConnect failed:`, error);
+    ws.close(1011, "onConnect failed");
+  }
+}
+function createBunUserWebSocketLifecycle(deps) {
+  return {
+    open(ws) {
+      const kind = ws.data?.kind;
+      if (!kind) {
+        return;
+      }
+      void runUserWebSocketOpen(ws, kind, deps).catch((error) => {
+        appLogger.error(`[WS:${kind}] open failed:`, error);
+        ws.close(1011, "internal error");
+      });
+    },
+    message(ws, msg) {
+      const kind = ws.data?.kind;
+      if (!kind) {
+        return;
+      }
+      const handler = deps.userHandlers.get(kind);
+      if (!handler) {
+        return;
+      }
+      const context = ws.data?.context;
+      if (context === void 0 && handler.context) {
+        appLogger.warn(`[WS:${kind}] message received before context resolved; dropping.`);
+        return;
+      }
+      const params = ws.data?.params ?? {};
+      const search = ws.data?.search ?? {};
+      const socket = deps.adaptSocket(ws, kind, params, search, context);
+      const message = typeof msg === "string" ? { kind: "text", text: msg } : { kind: "binary", data: new Uint8Array(msg.buffer, msg.byteOffset, msg.byteLength) };
+      invokeWebSocketHandlerHook(kind, "onMessage", handler.onMessage?.(socket, message));
+    },
+    close(ws, code, reason) {
+      const kind = ws.data?.kind;
+      if (!kind) {
+        return;
+      }
+      const handler = deps.userHandlers.get(kind);
+      if (!handler) {
+        return;
+      }
+      const context = ws.data?.context;
+      const params = ws.data?.params ?? {};
+      const search = ws.data?.search ?? {};
+      const socket = deps.adaptSocket(ws, kind, params, search, context);
+      const event = toWebSocketCloseInfo(code, reason);
+      invokeWebSocketHandlerHook(kind, "onClose", handler.onClose?.(socket, event));
+    },
+    error(ws, error) {
+      const kind = ws.data?.kind;
+      if (!kind) {
+        return;
+      }
+      const handler = deps.userHandlers.get(kind);
+      if (!handler) {
+        return;
+      }
+      appLogger.error(`[WS:${kind}] error:`, error);
+      const context = ws.data?.context;
+      const params = ws.data?.params ?? {};
+      const search = ws.data?.search ?? {};
+      const socket = deps.adaptSocket(ws, kind, params, search, context);
+      invokeWebSocketHandlerHook(kind, "onError", handler.onError?.(socket, error));
+    }
+  };
+}
+export {
+  createBunUserWebSocketLifecycle
+};

package/src/adapters/shared/node-http-websocket-upgrades.d.ts

@@ -0,0 +1,21 @@
+import type { Duplex } from 'node:stream';
+import type { Server as NodeHttpServer, IncomingMessage } from 'node:http';
+import type { EcopagesWebSocketHandler } from '../../types/public-types.js';
+export type NodeHttpWebSocketUpgradePreflight = (req: IncomingMessage, socket: Duplex, head: Buffer) => boolean;
+export type AttachNodeHttpWebSocketUpgradesOptions = {
+    runtimeOrigin: string;
+    websocketHandlers: Map<string, EcopagesWebSocketHandler<any, any>>;
+    /**
+     * When true, unmatched upgrade requests are left for other listeners (e.g.
+     * Vite HMR). When false, unmatched upgrades are destroyed immediately.
+     */
+    passthroughUnmatched?: boolean;
+    preflight?: NodeHttpWebSocketUpgradePreflight;
+};
+/**
+ * Wires Ecopages user WebSocket routes onto a Node HTTP server's `upgrade` event.
+ *
+ * Used by the Node adapter in standalone mode and by host integrations such as
+ * the Vite plugin that embed Ecopages behind a foreign HTTP server.
+ */
+export declare function attachNodeHttpWebSocketUpgrades(server: NodeHttpServer, options: AttachNodeHttpWebSocketUpgradesOptions): void;