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

package/src/adapters/shared/node-http-websocket-upgrades.js

@@ -0,0 +1,125 @@
+import { WebSocketServer } from "ws";
+import { appLogger } from "../../global/app-logger.js";
+import { findWebSocketRoute } from "../abstract/ws-pattern-matcher.js";
+import { invokeWebSocketHandlerHook, toWebSocketCloseInfo } from "./websocket-lifecycle.js";
+const attachedUpgradeServers = /* @__PURE__ */ new WeakSet();
+function adaptNodeWebSocket(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)
+  };
+}
+function toUpgradeRequest(runtimeOrigin, req) {
+  const upgradeUrl = new URL(req.url ?? "/", runtimeOrigin);
+  return new Request(upgradeUrl, {
+    method: req.method,
+    headers: req.headers
+  });
+}
+async function resolveNodeContext(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;
+  }
+}
+async function setupNodeWebSocketConnection(ws, wsMatch, req, runtimeOrigin, search) {
+  const handler = wsMatch.handler;
+  const baseRequest = toUpgradeRequest(runtimeOrigin, req);
+  let context;
+  try {
+    context = await resolveNodeContext(baseRequest, handler, wsMatch.kind, wsMatch.params, search);
+  } catch {
+    ws.close(1011, "context initialization failed");
+    return;
+  }
+  const socket = adaptNodeWebSocket(ws, wsMatch.kind, wsMatch.params, search, context);
+  try {
+    await handler.onConnect?.(socket);
+  } catch (error) {
+    appLogger.error(`[WS:${wsMatch.kind}] onConnect failed:`, error);
+    ws.close(1011, "onConnect failed");
+    return;
+  }
+  ws.on("message", (msg, isBinary) => {
+    const message = isBinary ? {
+      kind: "binary",
+      data: msg instanceof ArrayBuffer ? new Uint8Array(msg) : Array.isArray(msg) ? new Uint8Array(Buffer.concat(msg)) : new Uint8Array(msg)
+    } : { kind: "text", text: msg.toString() };
+    invokeWebSocketHandlerHook(wsMatch.kind, "onMessage", handler.onMessage?.(socket, message));
+  });
+  ws.on("close", (code, reason) => {
+    const event = toWebSocketCloseInfo(code, reason.toString());
+    invokeWebSocketHandlerHook(wsMatch.kind, "onClose", handler.onClose?.(socket, event));
+  });
+  ws.on("error", (err) => {
+    appLogger.error(`[WS:${wsMatch.kind}] error:`, err);
+    invokeWebSocketHandlerHook(wsMatch.kind, "onError", handler.onError?.(socket, err));
+  });
+}
+function attachNodeHttpWebSocketUpgrades(server, options) {
+  if (options.websocketHandlers.size === 0) {
+    return;
+  }
+  if (attachedUpgradeServers.has(server)) {
+    appLogger.warn("[WS] WebSocket upgrades already attached to this HTTP server; skipping duplicate attach.");
+    return;
+  }
+  attachedUpgradeServers.add(server);
+  const userWss = new WebSocketServer({ noServer: true });
+  server.on("upgrade", (req, socket, head) => {
+    if (options.preflight?.(req, socket, head)) {
+      return;
+    }
+    const url = new URL(req.url ?? "/", options.runtimeOrigin);
+    const wsMatch = findWebSocketRoute(options.websocketHandlers, url.pathname);
+    if (!wsMatch) {
+      if (!options.passthroughUnmatched) {
+        socket.destroy();
+      }
+      return;
+    }
+    userWss.handleUpgrade(req, socket, head, (ws) => {
+      const search = Object.fromEntries(url.searchParams.entries());
+      void setupNodeWebSocketConnection(ws, wsMatch, req, options.runtimeOrigin, search).catch((error) => {
+        appLogger.error(`[WS:${wsMatch.kind}] unexpected error:`, error);
+        ws.close(1011, "internal error");
+      });
+    });
+  });
+}
+export {
+  attachNodeHttpWebSocketUpgrades
+};

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

@@ -10,6 +10,7 @@ import type { ServerModuleTranspiler } from '../../services/module-loading/serve
 type HandleFileChangeOptions = {
     broadcast?: boolean;
 };
+export declare function resolveHmrRegistrationTimeoutMs(explicitTimeoutMs?: number): number;
 type SharedHmrManagerParams = {
     appConfig: EcoPagesAppConfig;
     bridge: IClientBridge;

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

@@ -16,6 +16,24 @@ import {
   setAppEntrypointDependencyGraph
 } from "../../services/runtime-state/entrypoint-dependency-graph.service.js";
 import { resolveInternalExecutionDir, resolveInternalWorkDir } from "../../utils/resolve-work-dir.js";
+const DEFAULT_HMR_REGISTRATION_TIMEOUT_MS = 4e3;
+const DEVELOPMENT_HMR_REGISTRATION_TIMEOUT_MS = 15e3;
+function resolveHmrRegistrationTimeoutMs(explicitTimeoutMs) {
+  if (explicitTimeoutMs !== void 0) {
+    return explicitTimeoutMs;
+  }
+  const envTimeoutMs = process.env.ECOPAGES_HMR_REGISTRATION_TIMEOUT_MS;
+  if (envTimeoutMs !== void 0 && envTimeoutMs !== "") {
+    const parsedTimeoutMs = Number(envTimeoutMs);
+    if (Number.isFinite(parsedTimeoutMs) && parsedTimeoutMs > 0) {
+      return parsedTimeoutMs;
+    }
+  }
+  if (process.env.NODE_ENV === "development") {
+    return DEVELOPMENT_HMR_REGISTRATION_TIMEOUT_MS;
+  }
+  return DEFAULT_HMR_REGISTRATION_TIMEOUT_MS;
+}
 class SharedHmrManager {
   appConfig;
   bridge;
@@ -30,7 +48,7 @@ class SharedHmrManager {
   browserBundleService;
   entrypointDependencyGraph;
   serverModuleTranspiler;
-  constructor({ appConfig, bridge, registrationTimeoutMs = 4e3 }) {
+  constructor({ appConfig, bridge, registrationTimeoutMs }) {
     this.appConfig = appConfig;
     this.bridge = bridge;
     this.distDir = path.join(resolveInternalWorkDir(this.appConfig), RESOLVED_ASSETS_DIR, "_hmr");
@@ -40,7 +58,7 @@ class SharedHmrManager {
       entrypointRegistrations: this.entrypointRegistrations,
       watchedFiles: this.watchedFiles,
       clearFailedRegistration: (entrypointPath) => this.clearFailedEntrypointRegistration(entrypointPath),
-      registrationTimeoutMs
+      registrationTimeoutMs: resolveHmrRegistrationTimeoutMs(registrationTimeoutMs)
     });
     this.browserBundleService = new BrowserBundleService(appConfig);
     this.entrypointDependencyGraph = this.createEntrypointDependencyGraph(
@@ -237,5 +255,6 @@ class SharedHmrManager {
   }
 }
 export {
-  SharedHmrManager
+  SharedHmrManager,
+  resolveHmrRegistrationTimeoutMs
 };

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

@@ -0,0 +1,3 @@
+import type { WebSocketCloseInfo } from '../../types/public-types.js';
+export declare function toWebSocketCloseInfo(code: number, reason: string): WebSocketCloseInfo;
+export declare function invokeWebSocketHandlerHook(kind: string, hookName: string, result: void | Promise<void>): void;

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

@@ -0,0 +1,19 @@
+import { appLogger } from "../../global/app-logger.js";
+function toWebSocketCloseInfo(code, reason) {
+  return {
+    code,
+    reason,
+    wasClean: code === 1e3 || code === 1001
+  };
+}
+function invokeWebSocketHandlerHook(kind, hookName, result) {
+  if (result instanceof Promise) {
+    result.catch((error) => {
+      appLogger.error(`[WS:${kind}] ${hookName} failed:`, error);
+    });
+  }
+}
+export {
+  invokeWebSocketHandlerHook,
+  toWebSocketCloseInfo
+};

package/src/build/runtime-build-output-normalizer.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 const corePackageRequire = createRequire(new URL("../../package.json", import.meta.url));
 const appDeclaredPackageCache = /* @__PURE__ */ new Map();
+const CORE_RUNTIME_BARE_SPECIFIER_PACKAGES = /* @__PURE__ */ new Set(["ws"]);
 function tryResolveRuntimeImport(specifier, resolver) {
   try {
     return resolver.resolve(specifier);
@@ -49,11 +50,18 @@ function getDeclaredAppPackages(rootDir) {
 function isDeclaredAppPackageImport(specifier, rootDir) {
   return getDeclaredAppPackages(rootDir).has(getPackageNameFromSpecifier(specifier));
 }
+function isDeclaredInResolutionChain(specifier, rootDir) {
+  const packageName = getPackageNameFromSpecifier(specifier);
+  if (CORE_RUNTIME_BARE_SPECIFIER_PACKAGES.has(packageName)) {
+    return true;
+  }
+  return isDeclaredAppPackageImport(specifier, rootDir);
+}
 function rewriteRuntimeImportSpecifier(specifier, quote, rootDir) {
   if (!isBareRuntimeImport(specifier)) {
     return void 0;
   }
-  if (isDeclaredAppPackageImport(specifier, rootDir)) {
+  if (isDeclaredInResolutionChain(specifier, rootDir)) {
     return void 0;
   }
   const resolvedPath = tryResolveRuntimeImport(specifier, corePackageRequire);

package/src/types/public-types.d.ts

@@ -14,6 +14,82 @@ import type { EntrypointDependencyGraph } from '../services/runtime-state/entryp
 export type { EcoPagesAppConfig } from './internal-types.js';
 export type { EcoPageComponent } from '../eco/eco.types.js';
 export type { ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
+/**
+ * Runtime-agnostic incoming WebSocket frame.
+ *
+ * Both Bun and Node `ws` deliver text and binary frames; this discriminated
+ * union lets handlers deal with both without runtime-specific casts.
+ */
+export type IncomingWebSocketMessage = {
+    readonly kind: 'text';
+    readonly text: string;
+} | {
+    readonly kind: 'binary';
+    readonly data: Uint8Array;
+};
+/**
+ * Runtime-agnostic outgoing WebSocket payload.
+ *
+ * Strings are sent as text frames. Anything binary-shaped is sent as binary
+ * frames. `Blob` is included for cross-runtime parity and is normalized to a
+ * binary frame by each adapter.
+ */
+export type OutgoingWebSocketMessage = string | Uint8Array | ArrayBuffer | ArrayBufferView | Blob;
+/**
+ * Close event delivered to `onClose` after a connection terminates.
+ */
+export interface WebSocketCloseInfo {
+    readonly code: number;
+    readonly reason: string;
+    readonly wasClean: boolean;
+}
+/**
+ * Input passed to a WebSocket handler's `context()` factory.
+ *
+ * Adapters call `context()` exactly once per accepted upgrade. The returned
+ * value becomes `socket.context` and is shared by all lifecycle hooks.
+ */
+export interface WebSocketContextFactoryInput<TParams extends Record<string, string> = Record<string, string>> {
+    readonly request: Request;
+    readonly kind: string;
+    readonly params: TParams;
+    readonly search: Readonly<Record<string, string>>;
+    readonly locals?: RequestLocals;
+}
+/**
+ * Runtime-agnostic WebSocket socket view exposed to handlers.
+ *
+ * Framework-owned fields:
+ * - `kind`: the registered route pattern (e.g. '/ws/chat/:roomId')
+ * - `params`: dynamic segments captured at match time
+ * - `search`: query string, always string-typed
+ *
+ * App-owned field:
+ * - `context`: returned by the handler's `context()` factory
+ */
+export interface EcopagesSocket<TContext = unknown, TParams extends Record<string, string> = Record<string, string>> {
+    readonly kind: string;
+    readonly params: TParams;
+    readonly search: Readonly<Record<string, string>>;
+    readonly context: TContext;
+    send(message: OutgoingWebSocketMessage): void;
+    sendStream(stream: ReadableStream<Uint8Array>): Promise<void>;
+    close(code?: number, reason?: string): void;
+}
+/**
+ * Connection-lifecycle handler object.
+ *
+ * All hooks are optional. `context()` is the one-time initializer that
+ * produces the per-connection state shared by the lifecycle hooks. Returning
+ * a rejected promise from `context()` aborts the upgrade.
+ */
+export interface EcopagesWebSocketHandler<TContext = unknown, TParams extends Record<string, string> = Record<string, string>> {
+    context?(input: WebSocketContextFactoryInput<TParams>): TContext | Promise<TContext>;
+    onConnect?(socket: EcopagesSocket<TContext, TParams>): void | Promise<void>;
+    onMessage?(socket: EcopagesSocket<TContext, TParams>, message: IncomingWebSocketMessage): void | Promise<void>;
+    onClose?(socket: EcopagesSocket<TContext, TParams>, event: WebSocketCloseInfo): void | Promise<void>;
+    onError?(socket: EcopagesSocket<TContext, TParams>, error: unknown): void | Promise<void>;
+}
 import type { StandardSchema, StandardSchemaResult, StandardSchemaSuccessResult, StandardSchemaFailureResult, StandardSchemaIssue, InferOutput } from '../services/validation/standard-schema.types.js';
 export type { StandardSchema, StandardSchemaResult, StandardSchemaSuccessResult, StandardSchemaFailureResult, StandardSchemaIssue, InferOutput, ForeignChildRuntime, };
 export type InteractionEventsString = ScriptsInjectorInteractionEventsString;