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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-beta.3",
+  "version": "0.2.0-beta.5",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-beta.3",
+    "@ecopages/file-system": "0.2.0-beta.5",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
     "@oxc-project/runtime": "0.134.0",

package/src/adapters/abstract/application-adapter.d.ts

@@ -9,6 +9,7 @@
 import type { SourceModuleLoader } from '../../services/module-loading/module-loading-types.js';
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 import type { ApiHandler, ApiHandlerContext, ErrorHandler, Middleware, RouteOptions, StaticRoute, ViewLoader } from '../../types/public-types.js';
+import type { EcopagesWebSocketHandler } from '../../types/public-types.js';
 import { type ReturnParseCliArgs } from '../../utils/parse-cli-args.js';
 /**
  * Runtime bootstrap options layered on top of the app config.
@@ -72,6 +73,11 @@ export declare abstract class AbstractApplicationAdapter<TOptions extends Applic
     protected apiHandlers: ApiHandler[];
     protected staticRoutes: StaticRoute[];
     protected errorHandler?: ErrorHandler;
+    /**
+     * App-level WebSocket handlers keyed by URL path pattern (e.g. '/ws/chat/:id').
+     * Both Bun and Node adapters read this map to register upgrade routes.
+     */
+    protected websocketHandlers: Map<string, EcopagesWebSocketHandler<any, any>>;
     constructor(options: TOptions);
     private clearDistFolder;
     /**
@@ -160,6 +166,46 @@ export declare abstract class AbstractApplicationAdapter<TOptions extends Applic
      * Get all registered static routes
      */
     getStaticRoutes(): StaticRoute[];
+    /**
+     * Register a WebSocket handler for the given path pattern.
+     *
+     * The runtime adapter handles the HTTP→WebSocket upgrade for this path
+     * and routes lifecycle events to `handler`.
+     *
+     * Supports dynamic segments via `:param` syntax. The handler receives
+     * typed `params` and `search` fields, and a typed `context` produced by
+     * the optional `context()` factory.
+     *
+     * One pattern registration matches infinite path variations. For example,
+     * `app.websocket('/ws/chat/:roomId', handler)` matches `/ws/chat/abc`,
+     * `/ws/chat/xyz`, etc. Each connection receives its own `params.roomId`.
+     *
+     * Works across both Bun and Node runtimes — no runtime-specific imports needed.
+     *
+     * @example
+     * ```typescript
+     * app.websocket<ChatContext, { roomId: string }>('/ws/chat/:roomId', {
+     *   async context({ params, search }) {
+     *     return { username: search.username ?? 'anonymous', roomId: params.roomId };
+     *   },
+     *   onConnect(socket) {
+     *     socket.send(`Welcome to room ${socket.context.roomId}`);
+     *   },
+     *   onMessage(socket, message) {
+     *     if (message.kind === 'text') {
+     *       socket.send(message.text);
+     *     }
+     *   },
+     * });
+     * ```
+     */
+    websocket<TContext = unknown, TParams extends Record<string, string> = Record<string, string>>(path: string, handler: EcopagesWebSocketHandler<TContext, TParams>): this;
+    /**
+     * Get the registered WebSocket handlers map.
+     *
+     * @returns The map of WebSocket route patterns to handlers
+     */
+    getWebsocketHandlers(): Map<string, EcopagesWebSocketHandler<any, any>>;
     /**
      * Register a global error handler for all routes.
      * Useful for logging, monitoring integration, and custom error formatting.

package/src/adapters/abstract/application-adapter.js

@@ -15,6 +15,11 @@ class AbstractApplicationAdapter {
   apiHandlers = [];
   staticRoutes = [];
   errorHandler;
+  /**
+   * App-level WebSocket handlers keyed by URL path pattern (e.g. '/ws/chat/:id').
+   * Both Bun and Node adapters read this map to register upgrade routes.
+   */
+  websocketHandlers = /* @__PURE__ */ new Map();
   constructor(options) {
     this.appConfig = options.appConfig;
     this.serverOptions = options.serverOptions || {};
@@ -93,6 +98,71 @@ class AbstractApplicationAdapter {
   getStaticRoutes() {
     return this.staticRoutes;
   }
+  /**
+   * Register a WebSocket handler for the given path pattern.
+   *
+   * The runtime adapter handles the HTTP→WebSocket upgrade for this path
+   * and routes lifecycle events to `handler`.
+   *
+   * Supports dynamic segments via `:param` syntax. The handler receives
+   * typed `params` and `search` fields, and a typed `context` produced by
+   * the optional `context()` factory.
+   *
+   * One pattern registration matches infinite path variations. For example,
+   * `app.websocket('/ws/chat/:roomId', handler)` matches `/ws/chat/abc`,
+   * `/ws/chat/xyz`, etc. Each connection receives its own `params.roomId`.
+   *
+   * Works across both Bun and Node runtimes — no runtime-specific imports needed.
+   *
+   * @example
+   * ```typescript
+   * app.websocket<ChatContext, { roomId: string }>('/ws/chat/:roomId', {
+   *   async context({ params, search }) {
+   *     return { username: search.username ?? 'anonymous', roomId: params.roomId };
+   *   },
+   *   onConnect(socket) {
+   *     socket.send(`Welcome to room ${socket.context.roomId}`);
+   *   },
+   *   onMessage(socket, message) {
+   *     if (message.kind === 'text') {
+   *       socket.send(message.text);
+   *     }
+   *   },
+   * });
+   * ```
+   */
+  websocket(path, handler) {
+    invariant(
+      typeof path === "string" && path.startsWith("/"),
+      `app.websocket(): path must be a string starting with "/", got "${path}".`
+    );
+    const segments = path.split("/").filter(Boolean);
+    const paramNames = /* @__PURE__ */ new Set();
+    for (const segment of segments) {
+      if (segment.startsWith(":")) {
+        const paramName = segment.slice(1);
+        invariant(
+          paramName.length > 0,
+          `app.websocket(): invalid pattern "${path}" \u2014 empty param name in segment ":${paramName}".`
+        );
+        invariant(
+          !paramNames.has(paramName),
+          `app.websocket(): invalid pattern "${path}" \u2014 duplicate param name ":${paramName}".`
+        );
+        paramNames.add(paramName);
+      }
+    }
+    this.websocketHandlers.set(path, handler);
+    return this;
+  }
+  /**
+   * Get the registered WebSocket handlers map.
+   *
+   * @returns The map of WebSocket route patterns to handlers
+   */
+  getWebsocketHandlers() {
+    return this.websocketHandlers;
+  }
   /**
    * Register a global error handler for all routes.
    * Useful for logging, monitoring integration, and custom error formatting.

package/src/adapters/abstract/ws-pattern-matcher.d.ts

@@ -0,0 +1,60 @@
+import type { EcopagesWebSocketHandler } from '../../types/public-types.js';
+/**
+ * Pattern matcher for WebSocket route paths.
+ *
+ * Supports dynamic segments via `:param` syntax. Matches are exact on literal
+ * segments and capture dynamic segments into a params object.
+ *
+ * @example
+ * ```ts
+ * matchWebSocketPath('/ws/chat/:id', '/ws/chat/abc123')
+ * // Returns: { id: 'abc123' }
+ *
+ * matchWebSocketPath('/ws/chat/:id', '/ws/chat/abc123/messages')
+ * // Returns: null (length mismatch)
+ *
+ * matchWebSocketPath('/ws/chat', '/ws/chat')
+ * // Returns: {} (no params)
+ * ```
+ *
+ * @remarks
+ * This is a minimal segment-based matcher. It does not support wildcards,
+ * optional segments, or catch-all patterns. Those are future concerns.
+ *
+ * @param pattern - The registered route pattern (e.g. '/ws/chat/:id')
+ * @param pathname - The actual request pathname (e.g. '/ws/chat/abc123')
+ * @returns A params object if the pattern matches, or null if it does not
+ */
+export declare function matchWebSocketPath(pattern: string, pathname: string): Record<string, string> | null;
+/**
+ * Represents a matched WebSocket route.
+ */
+export type WebSocketRouteMatch = {
+    handler: EcopagesWebSocketHandler<any, any>;
+    params: Record<string, string>;
+    kind: string;
+};
+/**
+ * Scores a pattern for specificity ordering.
+ *
+ * Higher scores win. Rules, in order:
+ * 1. More literal segments beats more dynamic segments.
+ * 2. Fewer dynamic segments beats more dynamic segments.
+ * 3. Longer route (more segments) beats shorter route.
+ *
+ * @param pattern - The registered route pattern
+ * @returns A numeric specificity score
+ */
+export declare function scoreWebSocketPattern(pattern: string): number;
+/**
+ * Find the registered WebSocket handler that best matches a pathname.
+ *
+ * Iterates through the provided handlers map, computes each pattern's
+ * specificity score, and returns the highest-scoring match. Ties resolve
+ * to the earliest-registered pattern.
+ *
+ * @param handlers - The map of registered WebSocket handlers
+ * @param pathname - The actual request pathname
+ * @returns The best match, or null if no pattern matches
+ */
+export declare function findWebSocketRoute(handlers: Map<string, EcopagesWebSocketHandler<any, any>>, pathname: string): WebSocketRouteMatch | null;

package/src/adapters/abstract/ws-pattern-matcher.js

@@ -0,0 +1,61 @@
+function matchWebSocketPath(pattern, pathname) {
+  const patternSegments = pattern.split("/").filter(Boolean);
+  const pathSegments = pathname.split("/").filter(Boolean);
+  if (patternSegments.length !== pathSegments.length) {
+    return null;
+  }
+  const params = {};
+  for (let i = 0; i < patternSegments.length; i++) {
+    const patternSegment = patternSegments[i];
+    const pathSegment = pathSegments[i];
+    if (!patternSegment || !pathSegment) {
+      return null;
+    }
+    if (patternSegment.startsWith(":")) {
+      const paramName = patternSegment.slice(1);
+      if (!paramName) {
+        return null;
+      }
+      params[paramName] = pathSegment;
+    } else if (patternSegment !== pathSegment) {
+      return null;
+    }
+  }
+  return params;
+}
+function scoreWebSocketPattern(pattern) {
+  const segments = pattern.split("/").filter(Boolean);
+  let literals = 0;
+  let dynamics = 0;
+  for (const segment of segments) {
+    if (segment.startsWith(":")) {
+      dynamics += 1;
+    } else {
+      literals += 1;
+    }
+  }
+  return literals * 100 - dynamics * 10 + segments.length;
+}
+function findWebSocketRoute(handlers, pathname) {
+  let best = null;
+  let index = 0;
+  for (const [pattern, handler] of handlers) {
+    const params = matchWebSocketPath(pattern, pathname);
+    if (params === null) {
+      index += 1;
+      continue;
+    }
+    const score = scoreWebSocketPattern(pattern);
+    const match = { handler, params, kind: pattern };
+    if (best === null || score > best.score || score === best.score && index < best.index) {
+      best = { score, match, index };
+    }
+    index += 1;
+  }
+  return best?.match ?? null;
+}
+export {
+  findWebSocketRoute,
+  matchWebSocketPath,
+  scoreWebSocketPattern
+};

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

@@ -38,6 +38,9 @@ export declare class BunEcopagesApp<WebSocketData = undefined> extends SharedApp
         previewHost: StaticPreviewHost;
     });
     fetch(request: Request): Promise<Response>;
+    attachWebSocketUpgrades(httpServer: import('node:http').Server, options?: {
+        passthroughUnmatched?: boolean;
+    }): Promise<void>;
     /**
      * Complete the initialization of the server adapter by processing dynamic routes
      * @param server The Bun server instance

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

@@ -22,6 +22,12 @@ class BunEcopagesApp extends SharedApplicationAdapter {
     await this.serverAdapter.completeInitialization(this.server);
     return this.serverAdapter.handleRequest(request);
   }
+  async attachWebSocketUpgrades(httpServer, options) {
+    if (!this.serverAdapter) {
+      this.serverAdapter = await this.initializeServerAdapter();
+    }
+    this.serverAdapter.attachUserWebSocketUpgrades(httpServer, options);
+  }
   /**
    * Complete the initialization of the server adapter by processing dynamic routes
    * @param server The Bun server instance
@@ -50,12 +56,13 @@ class BunEcopagesApp extends SharedApplicationAdapter {
       preferredHostname: binding.preferredHostname,
       composedUrl: binding.runtimeOrigin
     });
-    return await createBunServerAdapter({
+    return createBunServerAdapter({
       runtimeOrigin: binding.runtimeOrigin,
       appConfig: this.appConfig,
       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
     });

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

@@ -7,6 +7,7 @@ type BunSocketHandler = WebSocketHandler<unknown>;
 export interface HmrManagerParams {
     appConfig: EcoPagesAppConfig;
     bridge: ClientBridge;
+    registrationTimeoutMs?: number;
 }
 /**
  * Bun development HMR manager.
@@ -26,7 +27,7 @@ export declare class HmrManager extends SharedHmrManager {
      * generation to `SharedHmrManager`. The Bun subclass only supplies the
      * transport-specific dependency graph policy and websocket hook surface.
      */
-    constructor({ appConfig, bridge }: HmrManagerParams);
+    constructor({ appConfig, bridge, registrationTimeoutMs }: HmrManagerParams);
     /**
      * Reuses the shared in-memory dependency graph when possible and otherwise
      * creates the Bun-compatible default graph implementation.

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

@@ -13,8 +13,8 @@ class HmrManager extends SharedHmrManager {
    * generation to `SharedHmrManager`. The Bun subclass only supplies the
    * transport-specific dependency graph policy and websocket hook surface.
    */
-  constructor({ appConfig, bridge }) {
-    super({ appConfig, bridge });
+  constructor({ appConfig, bridge, registrationTimeoutMs }) {
+    super({ appConfig, bridge, registrationTimeoutMs });
   }
   /**
    * Reuses the shared in-memory dependency graph when possible and otherwise

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

@@ -1,6 +1,7 @@
+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 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 type { StaticPreviewHost } from '../shared/static-preview-host.js';
@@ -32,6 +33,7 @@ export interface BunServerAdapterParams {
     apiHandlers?: ApiHandler<string, Request, BunServerInstance>[];
     staticRoutes?: StaticRoute[];
     errorHandler?: ErrorHandler;
+    websocketHandlers?: Map<string, EcopagesWebSocketHandler<any, any>>;
     options?: {
         watch?: boolean;
     };
@@ -48,6 +50,9 @@ export interface BunServerAdapterResult extends ServerAdapterResult {
     }) => Promise<void>;
     completeInitialization: (server?: BunServerInstance | null) => Promise<void>;
     handleRequest: (request: Request) => Promise<Response>;
+    attachUserWebSocketUpgrades: (server: NodeHttpServer, options?: {
+        passthroughUnmatched?: boolean;
+    }) => void;
 }
 /**
  * Bun transport adapter that wires shared Ecopages request handling onto a live
@@ -72,6 +77,47 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
     private fullyInitialized;
     serverInstance: BunServerInstance | null;
     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>>;
+    /**
+     * 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
+     */
+    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,11 +127,17 @@ 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, hmrManager, bridge, previewHost, }: BunServerAdapterParams & {
         hmrManager: HmrManager;
         bridge: ClientBridge;
         previewHost: StaticPreviewHost;
     });
+    /**
+     * Wires user WebSocket routes onto a Node HTTP server used by host integrations.
+     */
+    attachUserWebSocketUpgrades(server: NodeHttpServer, options?: {
+        passthroughUnmatched?: boolean;
+    }): void;
     /**
      * Returns whether adapter-level HTML responses still need HMR runtime injection.
      *
@@ -134,9 +186,13 @@ 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;