@lolyjs/core 0.2.0-alpha.16 → 0.2.0-alpha.17

package/dist/index.cjs

@@ -89,6 +89,7 @@ __export(src_exports, {
   createModuleLogger: () => createModuleLogger,
   createRateLimiter: () => createRateLimiter,
   defaultRateLimiter: () => defaultRateLimiter,
+  defineWssRoute: () => defineWssRoute,
   generateRequestId: () => generateRequestId,
   getAppDir: () => getAppDir,
   getBuildDir: () => getBuildDir,
@@ -462,6 +463,58 @@ var import_path8 = __toESM(require("path"));
 var import_fs5 = __toESM(require("fs"));
 var import_path6 = __toESM(require("path"));
 init_globals();
+
+// modules/router/helpers/routes/extract-wss-route.ts
+function extractDefineWssRoute(mod, namespace) {
+  if (!mod.default) {
+    if (mod.events && Array.isArray(mod.events)) {
+      throw new Error(
+        `[loly:realtime] BREAKING CHANGE: 'export const events = []' is no longer supported.
+Please use 'export default defineWssRoute({ events: { ... } })' instead.
+See migration guide: https://loly.dev/docs/migration
+File: ${mod.__filename || "unknown"}`
+      );
+    }
+    return null;
+  }
+  const routeDef = mod.default;
+  if (!routeDef || typeof routeDef !== "object" || !routeDef.events) {
+    throw new Error(
+      `[loly:realtime] Module must export default from defineWssRoute().
+Expected: export default defineWssRoute({ events: { ... } })
+File: ${mod.__filename || "unknown"}`
+    );
+  }
+  const normalizedEvents = /* @__PURE__ */ new Map();
+  for (const [eventName, eventDef] of Object.entries(routeDef.events)) {
+    if (typeof eventDef === "function") {
+      normalizedEvents.set(eventName.toLowerCase(), {
+        handler: eventDef
+      });
+    } else if (eventDef && typeof eventDef === "object" && eventDef.handler) {
+      normalizedEvents.set(eventName.toLowerCase(), {
+        schema: eventDef.schema,
+        rateLimit: eventDef.rateLimit,
+        guard: eventDef.guard,
+        handler: eventDef.handler
+      });
+    } else {
+      throw new Error(
+        `[loly:realtime] Invalid event definition for '${eventName}'. Event must be a handler function or an object with a 'handler' property.
+File: ${mod.__filename || "unknown"}`
+      );
+    }
+  }
+  return {
+    namespace,
+    auth: routeDef.auth,
+    onConnect: routeDef.onConnect,
+    onDisconnect: routeDef.onDisconnect,
+    events: normalizedEvents
+  };
+}
+
+// modules/router/helpers/routes/index.ts
 function readManifest(projectRoot) {
   const manifestPath = import_path6.default.join(
     projectRoot,
@@ -536,18 +589,6 @@ function extractWssHandlers(mod, events) {
   }
   return handlers;
 }
-function extractWssHandlersFromModule(mod) {
-  const handlers = {};
-  if (!Array.isArray(mod?.events)) {
-    return handlers;
-  }
-  for (const event of mod.events) {
-    if (typeof event.handler === "function" && typeof event.name === "string") {
-      handlers[event.name.toLowerCase()] = event.handler;
-    }
-  }
-  return handlers;
-}
 function loadPageComponent(pageFile, projectRoot) {
   const fullPath = import_path6.default.join(projectRoot, pageFile);
   const pageMod = loadModuleSafely(fullPath);
@@ -1024,8 +1065,29 @@ function loadRoutesFromManifest(projectRoot) {
     if (!mod) {
       continue;
     }
+    let namespace = entry.pattern.replace(/^\/wss/, "");
+    if (!namespace.startsWith("/")) {
+      namespace = "/" + namespace;
+    }
+    if (namespace === "") {
+      namespace = "/";
+    }
+    let normalized = null;
+    try {
+      normalized = extractDefineWssRoute(mod, namespace);
+    } catch (error) {
+      console.warn(
+        `[loly:realtime] Failed to extract normalized route from ${filePath}:`,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
     const handlers = extractWssHandlers(mod, entry.events || []);
     const { global: globalMiddlewares, methodSpecific: methodMiddlewares } = extractApiMiddlewares(mod, []);
+    if (normalized) {
+      for (const [eventName, eventDef] of normalized.events.entries()) {
+        handlers[eventName] = eventDef.handler;
+      }
+    }
     wssRoutes.push({
       pattern: entry.pattern,
       regex,
@@ -1033,7 +1095,9 @@ function loadRoutesFromManifest(projectRoot) {
       handlers,
       middlewares: globalMiddlewares,
       methodMiddlewares,
-      filePath
+      filePath,
+      normalized: normalized || void 0
+      // Store normalized structure (use undefined instead of null)
     });
   }
   return { routes: pageRoutes, apiRoutes, wssRoutes };
@@ -1139,7 +1203,30 @@ function loadWssRoutes(appDir) {
       if (!mod) {
         continue;
       }
-      const handlers = extractWssHandlersFromModule(mod);
+      let namespace = pattern.replace(/^\/wss/, "");
+      if (!namespace.startsWith("/")) {
+        namespace = "/" + namespace;
+      }
+      if (namespace === "") {
+        namespace = "/";
+      }
+      let normalized = null;
+      try {
+        normalized = extractDefineWssRoute(mod, namespace);
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        continue;
+      }
+      if (!normalized) {
+        console.warn(
+          `[loly:realtime] Skipping route at ${fullPath}: No default export from defineWssRoute() found`
+        );
+        continue;
+      }
+      const handlers = {};
+      for (const [eventName, eventDef] of normalized.events.entries()) {
+        handlers[eventName] = eventDef.handler;
+      }
       const { global: globalMiddlewares, methodSpecific: methodMiddlewares } = extractApiMiddlewares(mod, []);
       routes.push({
         pattern,
@@ -1148,7 +1235,9 @@ function loadWssRoutes(appDir) {
         handlers,
         middlewares: globalMiddlewares,
         methodMiddlewares,
-        filePath: fullPath
+        filePath: fullPath,
+        normalized
+        // Store normalized structure
       });
     }
   }
@@ -5756,6 +5845,31 @@ init_globals();
 
 // modules/server/config.ts
 var CONFIG_FILE_NAME = "loly.config";
+var DEFAULT_REALTIME_CONFIG = {
+  enabled: true,
+  path: "/wss",
+  transports: ["websocket", "polling"],
+  pingIntervalMs: 25e3,
+  pingTimeoutMs: 2e4,
+  maxPayloadBytes: 64 * 1024,
+  allowedOrigins: process.env.NODE_ENV === "production" ? [] : "*",
+  cors: {
+    credentials: true,
+    allowedHeaders: ["content-type", "authorization"]
+  },
+  scale: {
+    mode: "single"
+  },
+  limits: {
+    connectionsPerIp: 20,
+    eventsPerSecond: 30,
+    burst: 60
+  },
+  logging: {
+    level: "info",
+    pretty: process.env.NODE_ENV !== "production"
+  }
+};
 var DEFAULT_CONFIG2 = {
   bodyLimit: "1mb",
   corsOrigin: process.env.CORS_ORIGIN ? process.env.CORS_ORIGIN.includes(",") ? process.env.CORS_ORIGIN.split(",").map((s) => s.trim()) : process.env.CORS_ORIGIN : process.env.NODE_ENV === "production" ? [] : true,
@@ -5798,7 +5912,8 @@ var DEFAULT_CONFIG2 = {
       // 1 year
       includeSubDomains: true
     }
-  }
+  },
+  realtime: DEFAULT_REALTIME_CONFIG
 };
 async function getServerConfig(projectRoot) {
   let mod = await getServerFile(projectRoot, CONFIG_FILE_NAME);
@@ -5814,12 +5929,76 @@ async function getServerConfig(projectRoot) {
       security: {
         ...DEFAULT_CONFIG2.security,
         ...options.security
+      },
+      realtime: {
+        ...DEFAULT_REALTIME_CONFIG,
+        ...options.realtime,
+        cors: {
+          ...DEFAULT_REALTIME_CONFIG.cors,
+          ...options.realtime?.cors
+        },
+        scale: options.realtime?.scale ? {
+          ...DEFAULT_REALTIME_CONFIG.scale,
+          ...options.realtime.scale,
+          adapter: options.realtime.scale.adapter,
+          stateStore: options.realtime.scale.stateStore ? {
+            ...DEFAULT_REALTIME_CONFIG.scale?.stateStore,
+            ...options.realtime.scale.stateStore,
+            // Ensure name is set (user config takes priority, fallback to default or "memory")
+            name: options.realtime.scale.stateStore.name || DEFAULT_REALTIME_CONFIG.scale?.stateStore?.name || "memory"
+          } : DEFAULT_REALTIME_CONFIG.scale?.stateStore
+        } : DEFAULT_REALTIME_CONFIG.scale,
+        limits: {
+          ...DEFAULT_REALTIME_CONFIG.limits,
+          ...options.realtime?.limits
+        },
+        logging: {
+          ...DEFAULT_REALTIME_CONFIG.logging,
+          ...options.realtime?.logging
+        }
       }
     };
+    validateRealtimeConfig(merged.realtime);
     return merged;
   }
+  validateRealtimeConfig(DEFAULT_CONFIG2.realtime);
   return DEFAULT_CONFIG2;
 }
+function validateRealtimeConfig(config) {
+  if (!config.enabled) {
+    return;
+  }
+  if (config.scale?.mode === "cluster") {
+    if (!config.scale.adapter) {
+      throw new Error(
+        "[loly:realtime] Cluster mode requires a Redis adapter. Please configure realtime.scale.adapter in your loly.config.ts"
+      );
+    }
+    if (config.scale.adapter.name !== "redis") {
+      throw new Error(
+        "[loly:realtime] Only Redis adapter is supported for cluster mode"
+      );
+    }
+    if (!config.scale.adapter.url) {
+      throw new Error(
+        "[loly:realtime] Redis adapter requires a URL. Set realtime.scale.adapter.url or REDIS_URL environment variable"
+      );
+    }
+    if (config.scale.stateStore?.name === "memory") {
+      console.warn(
+        "[loly:realtime] WARNING: Using memory state store in cluster mode. State will diverge across instances. Consider using Redis state store."
+      );
+    }
+  }
+  if (process.env.NODE_ENV === "production") {
+    if (!config.allowedOrigins || Array.isArray(config.allowedOrigins) && config.allowedOrigins.length === 0 || config.allowedOrigins === "*") {
+      config.allowedOrigins = "*";
+      console.warn(
+        "[loly:realtime] No allowedOrigins configured. Auto-allowing localhost for local development. For production deployment, configure realtime.allowedOrigins in loly.config.ts"
+      );
+    }
+  }
+}
 
 // modules/server/routes.ts
 var import_path24 = __toESM(require("path"));
@@ -5882,44 +6061,841 @@ function setupRoutes(options) {
 
 // modules/server/wss.ts
 var import_socket = require("socket.io");
-var generateActions = (socket, namespace) => {
+
+// modules/realtime/state/memory-store.ts
+var MemoryStateStore = class {
+  constructor() {
+    this.store = /* @__PURE__ */ new Map();
+    this.lists = /* @__PURE__ */ new Map();
+    this.sets = /* @__PURE__ */ new Map();
+    this.locks = /* @__PURE__ */ new Map();
+    this.cleanupInterval = setInterval(() => {
+      this.cleanupExpired();
+    }, 6e4);
+  }
+  /**
+   * Cleanup expired entries
+   */
+  cleanupExpired() {
+    const now = Date.now();
+    for (const [key, entry] of this.store.entries()) {
+      if (entry.expiresAt && entry.expiresAt < now) {
+        this.store.delete(key);
+      }
+    }
+    for (const [key, lock] of this.locks.entries()) {
+      if (lock.expiresAt < now) {
+        this.locks.delete(key);
+      }
+    }
+  }
+  /**
+   * Get a value by key
+   */
+  async get(key) {
+    const entry = this.store.get(key);
+    if (!entry) {
+      return null;
+    }
+    if (entry.expiresAt && entry.expiresAt < Date.now()) {
+      this.store.delete(key);
+      return null;
+    }
+    return entry.value;
+  }
+  /**
+   * Set a value with optional TTL
+   */
+  async set(key, value, opts) {
+    const entry = {
+      value
+    };
+    if (opts?.ttlMs) {
+      entry.expiresAt = Date.now() + opts.ttlMs;
+    }
+    this.store.set(key, entry);
+  }
+  /**
+   * Delete a key
+   */
+  async del(key) {
+    this.store.delete(key);
+    this.lists.delete(key);
+    this.sets.delete(key);
+    this.locks.delete(key);
+  }
+  /**
+   * Increment a numeric value
+   */
+  async incr(key, by = 1) {
+    const current = await this.get(key);
+    const newValue = (current ?? 0) + by;
+    await this.set(key, newValue);
+    return newValue;
+  }
+  /**
+   * Decrement a numeric value
+   */
+  async decr(key, by = 1) {
+    return this.incr(key, -by);
+  }
+  /**
+   * Push to a list (left push)
+   */
+  async listPush(key, value, opts) {
+    let list = this.lists.get(key);
+    if (!list) {
+      list = [];
+      this.lists.set(key, list);
+    }
+    list.unshift(value);
+    if (opts?.maxLen && list.length > opts.maxLen) {
+      list.splice(opts.maxLen);
+    }
+  }
+  /**
+   * Get range from a list
+   */
+  async listRange(key, start, end) {
+    const list = this.lists.get(key);
+    if (!list) {
+      return [];
+    }
+    const len = list.length;
+    const actualStart = start < 0 ? Math.max(0, len + start) : Math.min(start, len);
+    const actualEnd = end < 0 ? Math.max(0, len + end + 1) : Math.min(end + 1, len);
+    return list.slice(actualStart, actualEnd);
+  }
+  /**
+   * Add member to a set
+   */
+  async setAdd(key, member) {
+    let set = this.sets.get(key);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.sets.set(key, set);
+    }
+    set.add(member);
+  }
+  /**
+   * Remove member from a set
+   */
+  async setRem(key, member) {
+    const set = this.sets.get(key);
+    if (set) {
+      set.delete(member);
+      if (set.size === 0) {
+        this.sets.delete(key);
+      }
+    }
+  }
+  /**
+   * Get all members of a set
+   */
+  async setMembers(key) {
+    const set = this.sets.get(key);
+    if (!set) {
+      return [];
+    }
+    return Array.from(set);
+  }
+  /**
+   * Acquire a distributed lock
+   */
+  async lock(key, ttlMs) {
+    const lockKey = `__lock:${key}`;
+    const now = Date.now();
+    const existingLock = this.locks.get(lockKey);
+    if (existingLock && existingLock.expiresAt > now) {
+      throw new Error(`Lock '${key}' is already held`);
+    }
+    this.locks.set(lockKey, {
+      expiresAt: now + ttlMs
+    });
+    return async () => {
+      const lock = this.locks.get(lockKey);
+      if (lock && lock.expiresAt > Date.now()) {
+        this.locks.delete(lockKey);
+      }
+    };
+  }
+  /**
+   * Cleanup resources (call when shutting down)
+   */
+  destroy() {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = void 0;
+    }
+    this.store.clear();
+    this.lists.clear();
+    this.sets.clear();
+    this.locks.clear();
+  }
+};
+
+// modules/realtime/state/redis-store.ts
+var RedisStateStore = class {
+  constructor(client, prefix = "loly:rt:") {
+    this.client = client;
+    this.prefix = prefix;
+  }
+  /**
+   * Add prefix to key
+   */
+  key(key) {
+    return `${this.prefix}${key}`;
+  }
+  /**
+   * Serialize value to JSON string
+   */
+  serialize(value) {
+    return JSON.stringify(value);
+  }
+  /**
+   * Deserialize JSON string to value
+   */
+  deserialize(value) {
+    if (value === null) {
+      return null;
+    }
+    try {
+      return JSON.parse(value);
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Get a value by key
+   */
+  async get(key) {
+    const value = await this.client.get(this.key(key));
+    return this.deserialize(value);
+  }
+  /**
+   * Set a value with optional TTL
+   */
+  async set(key, value, opts) {
+    const serialized = this.serialize(value);
+    const prefixedKey = this.key(key);
+    if (opts?.ttlMs) {
+      await this.client.psetex(prefixedKey, opts.ttlMs, serialized);
+    } else {
+      await this.client.set(prefixedKey, serialized);
+    }
+  }
+  /**
+   * Delete a key
+   */
+  async del(key) {
+    await this.client.del(this.key(key));
+  }
+  /**
+   * Increment a numeric value
+   */
+  async incr(key, by = 1) {
+    const prefixedKey = this.key(key);
+    if (by === 1) {
+      return await this.client.incr(prefixedKey);
+    } else {
+      return await this.client.incrby(prefixedKey, by);
+    }
+  }
+  /**
+   * Decrement a numeric value
+   */
+  async decr(key, by = 1) {
+    const prefixedKey = this.key(key);
+    if (by === 1) {
+      return await this.client.decr(prefixedKey);
+    } else {
+      return await this.client.decrby(prefixedKey, by);
+    }
+  }
+  /**
+   * Push to a list (left push)
+   */
+  async listPush(key, value, opts) {
+    const serialized = this.serialize(value);
+    const prefixedKey = this.key(key);
+    await this.client.lpush(prefixedKey, serialized);
+    if (opts?.maxLen) {
+      await this.client.eval(
+        `redis.call('ltrim', KEYS[1], 0, ARGV[1])`,
+        1,
+        prefixedKey,
+        String(opts.maxLen - 1)
+      );
+    }
+  }
+  /**
+   * Get range from a list
+   */
+  async listRange(key, start, end) {
+    const prefixedKey = this.key(key);
+    const values = await this.client.lrange(prefixedKey, start, end);
+    return values.map((v) => this.deserialize(v)).filter((v) => v !== null);
+  }
+  /**
+   * Add member to a set
+   */
+  async setAdd(key, member) {
+    const prefixedKey = this.key(key);
+    await this.client.sadd(prefixedKey, member);
+  }
+  /**
+   * Remove member from a set
+   */
+  async setRem(key, member) {
+    const prefixedKey = this.key(key);
+    await this.client.srem(prefixedKey, member);
+  }
+  /**
+   * Get all members of a set
+   */
+  async setMembers(key) {
+    const prefixedKey = this.key(key);
+    return await this.client.smembers(prefixedKey);
+  }
+  /**
+   * Acquire a distributed lock using Redis SET NX EX
+   */
+  async lock(key, ttlMs) {
+    const lockKey = this.key(`__lock:${key}`);
+    const lockValue = `${Date.now()}-${Math.random()}`;
+    const ttlSeconds = Math.ceil(ttlMs / 1e3);
+    const result = await this.client.set(
+      lockKey,
+      lockValue,
+      "NX",
+      // Only set if not exists
+      "EX",
+      // Expire in seconds
+      ttlSeconds
+    );
+    if (result === null) {
+      throw new Error(`Lock '${key}' is already held`);
+    }
+    return async () => {
+      const unlockScript = `
+        if redis.call("get", KEYS[1]) == ARGV[1] then
+          return redis.call("del", KEYS[1])
+        else
+          return 0
+        end
+      `;
+      await this.client.eval(unlockScript, 1, lockKey, lockValue);
+    };
+  }
+};
+
+// modules/realtime/state/index.ts
+async function createStateStore(config) {
+  if (!config.enabled) {
+    return createNoOpStore();
+  }
+  const storeType = config.scale?.stateStore?.name || "memory";
+  const prefix = config.scale?.stateStore?.prefix || "loly:rt:";
+  if (storeType === "memory") {
+    return new MemoryStateStore();
+  }
+  if (storeType === "redis") {
+    const url = config.scale?.stateStore?.url || process.env.REDIS_URL;
+    if (!url) {
+      throw new Error(
+        "[loly:realtime] Redis state store requires a URL. Set realtime.scale.stateStore.url or REDIS_URL environment variable"
+      );
+    }
+    const client = await createRedisClient(url);
+    return new RedisStateStore(client, prefix);
+  }
+  throw new Error(
+    `[loly:realtime] Unknown state store type: ${storeType}. Supported types: 'memory', 'redis'`
+  );
+}
+async function createRedisClient(url) {
+  try {
+    const Redis = await import("ioredis");
+    return new Redis.default(url);
+  } catch {
+    try {
+      const { createClient } = await import("redis");
+      const client = createClient({ url });
+      await client.connect();
+      return client;
+    } catch (err) {
+      throw new Error(
+        `[loly:realtime] Failed to create Redis client. Please install 'ioredis' or 'redis' package. Error: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+}
+function createNoOpStore() {
+  const noOp = async () => {
+  };
+  const noOpReturn = async () => null;
+  const noOpNumber = async () => 0;
+  const noOpArray = async () => [];
+  const noOpUnlock = async () => {
+  };
   return {
+    get: noOpReturn,
+    set: noOp,
+    del: noOp,
+    incr: noOpNumber,
+    decr: noOpNumber,
+    listPush: noOp,
+    listRange: noOpArray,
+    setAdd: noOp,
+    setRem: noOp,
+    setMembers: noOpArray,
+    lock: async () => noOpUnlock
+  };
+}
+
+// modules/realtime/presence/index.ts
+var PresenceManager = class {
+  constructor(stateStore, prefix = "loly:rt:") {
+    this.stateStore = stateStore;
+    this.prefix = prefix;
+  }
+  /**
+   * Add a socket for a user
+   */
+  async addSocketForUser(userId, socketId) {
+    const key = this.key(`userSockets:${userId}`);
+    await this.stateStore.setAdd(key, socketId);
+    const socketKey = this.key(`socketUser:${socketId}`);
+    await this.stateStore.set(socketKey, userId);
+  }
+  /**
+   * Remove a socket for a user
+   */
+  async removeSocketForUser(userId, socketId) {
+    const key = this.key(`userSockets:${userId}`);
+    await this.stateStore.setRem(key, socketId);
+    const socketKey = this.key(`socketUser:${socketId}`);
+    await this.stateStore.del(socketKey);
+    const sockets = await this.stateStore.setMembers(key);
+    if (sockets.length === 0) {
+      await this.stateStore.del(key);
+    }
+  }
+  /**
+   * Get all socket IDs for a user
+   */
+  async getSocketsForUser(userId) {
+    const key = this.key(`userSockets:${userId}`);
+    return await this.stateStore.setMembers(key);
+  }
+  /**
+   * Get user ID for a socket
+   */
+  async getUserForSocket(socketId) {
+    const socketKey = this.key(`socketUser:${socketId}`);
+    return await this.stateStore.get(socketKey);
+  }
+  /**
+   * Add user to a room's presence (optional feature)
+   */
+  async addUserToRoom(namespace, room, userId) {
+    const key = this.key(`presence:${namespace}:${room}`);
+    await this.stateStore.setAdd(key, userId);
+  }
+  /**
+   * Remove user from a room's presence
+   */
+  async removeUserFromRoom(namespace, room, userId) {
+    const key = this.key(`presence:${namespace}:${room}`);
+    await this.stateStore.setRem(key, userId);
+    const members = await this.stateStore.setMembers(key);
+    if (members.length === 0) {
+      await this.stateStore.del(key);
+    }
+  }
+  /**
+   * Get all users in a room
+   */
+  async getUsersInRoom(namespace, room) {
+    const key = this.key(`presence:${namespace}:${room}`);
+    return await this.stateStore.setMembers(key);
+  }
+  /**
+   * Add prefix to key
+   */
+  key(key) {
+    return `${this.prefix}${key}`;
+  }
+};
+
+// modules/realtime/rate-limit/token-bucket.ts
+var TokenBucket = class {
+  // tokens per second
+  constructor(capacity, refillRate) {
+    this.capacity = capacity;
+    this.refillRate = refillRate;
+    this.tokens = capacity;
+    this.lastRefill = Date.now();
+  }
+  /**
+   * Try to consume tokens. Returns true if successful, false if rate limited.
+   */
+  consume(tokens = 1) {
+    this.refill();
+    if (this.tokens >= tokens) {
+      this.tokens -= tokens;
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Get current available tokens
+   */
+  getAvailable() {
+    this.refill();
+    return this.tokens;
+  }
+  /**
+   * Refill tokens based on elapsed time
+   */
+  refill() {
+    const now = Date.now();
+    const elapsed = (now - this.lastRefill) / 1e3;
+    const tokensToAdd = elapsed * this.refillRate;
+    this.tokens = Math.min(this.capacity, this.tokens + tokensToAdd);
+    this.lastRefill = now;
+  }
+  /**
+   * Reset bucket to full capacity
+   */
+  reset() {
+    this.tokens = this.capacity;
+    this.lastRefill = Date.now();
+  }
+};
+
+// modules/realtime/rate-limit/index.ts
+var RateLimiter = class {
+  constructor(stateStore, prefix = "loly:rt:rate:") {
+    this.memoryBuckets = /* @__PURE__ */ new Map();
+    this.stateStore = stateStore;
+    this.prefix = prefix;
+  }
+  /**
+   * Check if a request should be rate limited.
+   * 
+   * @param key - Unique key for the rate limit (e.g., socketId or socketId:eventName)
+   * @param config - Rate limit configuration
+   * @returns true if allowed, false if rate limited
+   */
+  async checkLimit(key, config) {
+    const fullKey = `${this.prefix}${key}`;
+    const burst = config.burst || config.eventsPerSecond * 2;
+    if (this.stateStore) {
+      return this.checkLimitWithStore(fullKey, config.eventsPerSecond, burst);
+    } else {
+      return this.checkLimitInMemory(fullKey, config.eventsPerSecond, burst);
+    }
+  }
+  /**
+   * Check rate limit using state store (for cluster mode)
+   */
+  async checkLimitWithStore(key, ratePerSecond, burst) {
+    const count = await this.stateStore.get(key) || 0;
+    if (count >= burst) {
+      return false;
+    }
+    await this.stateStore.incr(key, 1);
+    await this.stateStore.set(key, count + 1, { ttlMs: 1e3 });
+    return true;
+  }
+  /**
+   * Check rate limit using in-memory token bucket
+   */
+  checkLimitInMemory(key, ratePerSecond, burst) {
+    let bucket = this.memoryBuckets.get(key);
+    if (!bucket) {
+      bucket = new TokenBucket(burst, ratePerSecond);
+      this.memoryBuckets.set(key, bucket);
+    }
+    return bucket.consume(1);
+  }
+  /**
+   * Cleanup old buckets (call periodically)
+   */
+  cleanup() {
+  }
+};
+
+// modules/realtime/auth/index.ts
+async function executeAuth(authFn, socket, namespace) {
+  if (!authFn) {
+    return null;
+  }
+  const authCtx = {
+    req: {
+      headers: socket.handshake.headers,
+      ip: socket.handshake.address,
+      url: socket.handshake.url,
+      cookies: socket.handshake.headers.cookie ? parseCookies(socket.handshake.headers.cookie) : void 0
+    },
+    socket,
+    namespace
+  };
+  const user = await authFn(authCtx);
+  if (user) {
+    socket.data = socket.data || {};
+    socket.data.user = user;
+  }
+  return user;
+}
+function parseCookies(cookieString) {
+  const cookies = {};
+  cookieString.split(";").forEach((cookie) => {
+    const [name, value] = cookie.trim().split("=");
+    if (name && value) {
+      cookies[name] = decodeURIComponent(value);
+    }
+  });
+  return cookies;
+}
+
+// modules/realtime/guards/index.ts
+async function executeGuard(guardFn, ctx) {
+  if (!guardFn) {
+    return true;
+  }
+  const guardCtx = {
+    user: ctx.user,
+    req: ctx.req,
+    socket: ctx.socket,
+    namespace: ctx.pathname
+  };
+  const result = await guardFn(guardCtx);
+  return result === true;
+}
+
+// modules/realtime/validation/index.ts
+function validateSchema(schema, data) {
+  if (!schema) {
+    return { success: true, data };
+  }
+  if (typeof schema.safeParse === "function") {
+    const result = schema.safeParse(data);
+    if (result.success) {
+      return { success: true, data: result.data };
+    } else {
+      return { success: false, error: result.error };
+    }
+  }
+  if (typeof schema.parse === "function") {
+    try {
+      const parsed = schema.parse(data);
+      return { success: true, data: parsed };
+    } catch (error) {
+      return { success: false, error };
+    }
+  }
+  return {
+    success: false,
+    error: new Error("Schema must have 'parse' or 'safeParse' method")
+  };
+}
+
+// modules/realtime/logging/index.ts
+function createWssLogger(namespace, socket, baseLogger) {
+  const context = {
+    namespace,
+    socketId: socket.id,
+    userId: socket.data?.user?.id || null
+  };
+  const log = (level, message, meta) => {
+    const fullMeta = {
+      ...context,
+      ...meta,
+      requestId: socket.requestId || generateRequestId2()
+    };
+    if (baseLogger) {
+      baseLogger[level](message, fullMeta);
+    } else {
+      console[level === "error" ? "error" : "log"](
+        `[${level.toUpperCase()}] [${namespace}] ${message}`,
+        fullMeta
+      );
+    }
+  };
+  return {
+    debug: (message, meta) => log("debug", message, meta),
+    info: (message, meta) => log("info", message, meta),
+    warn: (message, meta) => log("warn", message, meta),
+    error: (message, meta) => log("error", message, meta)
+  };
+}
+function generateRequestId2() {
+  return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+
+// modules/server/wss.ts
+var generateActions = (socket, namespace, presence) => {
+  return {
+    // Emit to current socket only (reply)
+    reply: (event, payload) => {
+      socket.emit(event, payload);
+    },
     // Emit to all clients in the namespace
-    emit: (event, ...args) => {
-      socket.nsp.emit(event, ...args);
+    emit: (event, payload) => {
+      socket.nsp.emit(event, payload);
     },
-    // Emit to a specific socket by Socket.IO socket ID
+    // Emit to everyone except current socket
+    broadcast: (event, payload, opts) => {
+      if (opts?.excludeSelf === false) {
+        socket.nsp.emit(event, payload);
+      } else {
+        socket.broadcast.emit(event, payload);
+      }
+    },
+    // Join a room
+    join: async (room) => {
+      await socket.join(room);
+    },
+    // Leave a room
+    leave: async (room) => {
+      await socket.leave(room);
+    },
+    // Emit to a specific room
+    toRoom: (room) => {
+      return {
+        emit: (event, payload) => {
+          namespace.to(room).emit(event, payload);
+        }
+      };
+    },
+    // Emit to a specific user (by userId)
+    toUser: (userId) => {
+      return {
+        emit: async (event, payload) => {
+          if (!presence) {
+            console.warn(
+              "[loly:realtime] toUser() requires presence manager. Make sure realtime is properly configured."
+            );
+            return;
+          }
+          const socketIds = await presence.getSocketsForUser(userId);
+          for (const socketId of socketIds) {
+            const targetSocket = namespace.sockets.get(socketId);
+            if (targetSocket) {
+              targetSocket.emit(event, payload);
+            }
+          }
+        }
+      };
+    },
+    // Emit error event (reserved event: __loly:error)
+    error: (code, message, details) => {
+      socket.emit("__loly:error", {
+        code,
+        message,
+        details,
+        requestId: socket.requestId || void 0
+      });
+    },
+    // Legacy: Emit to a specific socket by Socket.IO socket ID
     emitTo: (socketId, event, ...args) => {
       const targetSocket = namespace.sockets.get(socketId);
       if (targetSocket) {
         targetSocket.emit(event, ...args);
       }
     },
-    // Emit to a specific client by custom clientId
-    // Requires clientId to be stored in socket.data.clientId during connection
+    // Legacy: Emit to a specific client by custom clientId
     emitToClient: (clientId, event, ...args) => {
       namespace.sockets.forEach((s) => {
         if (s.data?.clientId === clientId) {
           s.emit(event, ...args);
         }
       });
-    },
-    // Broadcast to all clients except the sender
-    broadcast: (event, ...args) => {
-      socket.broadcast.emit(event, ...args);
     }
   };
 };
-function setupWssEvents(options) {
-  const { httpServer, wssRoutes } = options;
+async function setupWssEvents(options) {
+  const { httpServer, wssRoutes, projectRoot } = options;
   if (wssRoutes.length === 0) {
     return;
   }
+  const serverConfig = await getServerConfig(projectRoot);
+  const realtimeConfig = serverConfig.realtime;
+  if (!realtimeConfig || !realtimeConfig.enabled) {
+    return;
+  }
+  const stateStore = await createStateStore(realtimeConfig);
+  const stateStorePrefix = realtimeConfig.scale?.stateStore?.prefix || "loly:rt:";
+  const presence = new PresenceManager(stateStore, stateStorePrefix);
+  const rateLimiter = new RateLimiter(
+    realtimeConfig.scale?.mode === "cluster" ? stateStore : void 0,
+    `${stateStorePrefix}rate:`
+  );
+  const allowedOrigins = realtimeConfig.allowedOrigins;
+  const corsOrigin = !allowedOrigins || Array.isArray(allowedOrigins) && allowedOrigins.length === 0 || allowedOrigins === "*" ? (
+    // Auto-allow localhost on any port for simplicity
+    (origin, callback) => {
+      if (!origin) {
+        callback(null, true);
+        return;
+      }
+      if (origin.startsWith("http://localhost:") || origin.startsWith("http://127.0.0.1:") || origin.startsWith("https://localhost:") || origin.startsWith("https://127.0.0.1:")) {
+        callback(null, true);
+      } else {
+        callback(new Error("Not allowed by CORS"));
+      }
+    }
+  ) : allowedOrigins;
+  const corsOptions = {
+    origin: corsOrigin,
+    credentials: realtimeConfig.cors?.credentials ?? true,
+    methods: ["GET", "POST"],
+    allowedHeaders: realtimeConfig.cors?.allowedHeaders || [
+      "content-type",
+      "authorization"
+    ]
+  };
   const io = new import_socket.Server(httpServer, {
-    path: "/wss"
+    path: realtimeConfig.path || "/wss",
+    transports: realtimeConfig.transports || ["websocket", "polling"],
+    pingInterval: realtimeConfig.pingIntervalMs || 25e3,
+    pingTimeout: realtimeConfig.pingTimeoutMs || 2e4,
+    maxHttpBufferSize: realtimeConfig.maxPayloadBytes || 64 * 1024,
+    cors: corsOptions
   });
+  if (realtimeConfig.scale?.mode === "cluster" && realtimeConfig.scale.adapter) {
+    try {
+      const redisAdapterModule = await import("@socket.io/redis-adapter").catch(() => null);
+      const ioredisModule = await import("ioredis").catch(() => null);
+      if (!redisAdapterModule || !ioredisModule) {
+        throw new Error(
+          "[loly:realtime] Redis adapter dependencies not found. Install @socket.io/redis-adapter and ioredis for cluster mode: pnpm add @socket.io/redis-adapter ioredis"
+        );
+      }
+      const { createAdapter } = redisAdapterModule;
+      const Redis = ioredisModule.default || ioredisModule;
+      const pubClient = new Redis(realtimeConfig.scale.adapter.url);
+      const subClient = pubClient.duplicate();
+      io.adapter(createAdapter(pubClient, subClient));
+    } catch (error) {
+      console.error(
+        "[loly:realtime] Failed to setup Redis adapter:",
+        error instanceof Error ? error.message : String(error)
+      );
+      throw error;
+    }
+  }
   for (const wssRoute of wssRoutes) {
-    let namespacePath = wssRoute.pattern.replace(/^\/wss/, "");
+    const normalized = wssRoute.normalized;
+    if (!normalized) {
+      console.warn(
+        `[loly:realtime] Skipping route ${wssRoute.pattern}: No normalized route definition`
+      );
+      continue;
+    }
+    let namespacePath = normalized.namespace || wssRoute.pattern.replace(/^\/wss/, "");
     if (!namespacePath.startsWith("/")) {
       namespacePath = "/" + namespacePath;
     }
@@ -5927,34 +6903,158 @@ function setupWssEvents(options) {
       namespacePath = "/";
     }
     const namespace = io.of(namespacePath);
-    namespace.on("connection", (socket) => {
-      Object.entries(wssRoute.handlers).forEach(([event, handler]) => {
-        if (event.toLowerCase() === "connection") {
-          const ctx = {
-            socket,
-            io: namespace.server,
-            params: {},
-            pathname: wssRoute.pattern,
-            actions: generateActions(socket, namespace)
-          };
-          handler(ctx);
-        } else {
-          socket.on(event, (data) => {
-            const ctx = {
-              socket,
-              io: namespace.server,
-              actions: generateActions(socket, namespace),
-              params: {},
-              pathname: wssRoute.pattern,
-              data
-            };
-            handler(ctx);
+    console.log(`[loly:realtime] Registered namespace: ${namespacePath} (from pattern: ${wssRoute.pattern})`);
+    namespace.on("connection", async (socket) => {
+      console.log(`[loly:realtime] Client connected to namespace ${namespacePath}, socket: ${socket.id}`);
+      const requestId = generateRequestId();
+      socket.requestId = requestId;
+      const log = createWssLogger(namespacePath, socket);
+      try {
+        const user = await executeAuth(normalized.auth, socket, namespacePath);
+        socket.data = socket.data || {};
+        socket.data.user = user;
+        if (user && user.id) {
+          await presence.addSocketForUser(String(user.id), socket.id);
+        }
+        const baseCtx = {
+          socket,
+          io: namespace.server,
+          req: {
+            headers: socket.handshake.headers,
+            ip: socket.handshake.address,
+            url: socket.handshake.url,
+            cookies: socket.handshake.headers.cookie ? parseCookies2(socket.handshake.headers.cookie) : void 0
+          },
+          user: user || null,
+          params: {},
+          pathname: wssRoute.pattern,
+          actions: generateActions(socket, namespace, presence),
+          state: stateStore,
+          log
+        };
+        if (normalized.onConnect) {
+          try {
+            await normalized.onConnect(baseCtx);
+          } catch (error) {
+            log.error("Error in onConnect hook", {
+              error: error instanceof Error ? error.message : String(error)
+            });
+          }
+        }
+        for (const [eventName, eventDef] of normalized.events.entries()) {
+          socket.on(eventName, async (data) => {
+            const eventRequestId = generateRequestId();
+            socket.requestId = eventRequestId;
+            const eventLog = createWssLogger(namespacePath, socket);
+            eventLog.debug(`Event received: ${eventName}`, { data });
+            try {
+              const ctx = {
+                ...baseCtx,
+                data,
+                log: eventLog
+              };
+              if (eventDef.schema) {
+                const validation = validateSchema(eventDef.schema, data);
+                if (!validation.success) {
+                  ctx.actions.error("BAD_PAYLOAD", "Invalid payload", {
+                    error: validation.error
+                  });
+                  eventLog.warn("Schema validation failed", {
+                    error: validation.error
+                  });
+                  return;
+                }
+                ctx.data = validation.data;
+              }
+              if (eventDef.guard) {
+                const allowed = await executeGuard(eventDef.guard, ctx);
+                if (!allowed) {
+                  ctx.actions.error("FORBIDDEN", "Access denied");
+                  eventLog.warn("Guard check failed");
+                  return;
+                }
+              }
+              const globalLimit = realtimeConfig.limits;
+              if (globalLimit) {
+                const globalAllowed = await rateLimiter.checkLimit(
+                  socket.id,
+                  {
+                    eventsPerSecond: globalLimit.eventsPerSecond || 30,
+                    burst: globalLimit.burst || 60
+                  }
+                );
+                if (!globalAllowed) {
+                  ctx.actions.error("RATE_LIMIT", "Rate limit exceeded");
+                  eventLog.warn("Global rate limit exceeded");
+                  return;
+                }
+              }
+              if (eventDef.rateLimit) {
+                const eventAllowed = await rateLimiter.checkLimit(
+                  `${socket.id}:${eventName}`,
+                  eventDef.rateLimit
+                );
+                if (!eventAllowed) {
+                  ctx.actions.error("RATE_LIMIT", "Event rate limit exceeded");
+                  eventLog.warn("Event rate limit exceeded");
+                  return;
+                }
+              }
+              await eventDef.handler(ctx);
+              eventLog.debug(`Event handled: ${eventName}`);
+            } catch (error) {
+              const errorLog = createWssLogger(namespacePath, socket);
+              errorLog.error(`Error handling event ${eventName}`, {
+                error: error instanceof Error ? error.message : String(error),
+                stack: error instanceof Error ? error.stack : void 0
+              });
+              socket.emit("__loly:error", {
+                code: "INTERNAL_ERROR",
+                message: "An error occurred while processing your request",
+                requestId: eventRequestId
+              });
+            }
           });
         }
-      });
+        socket.on("disconnect", async (reason) => {
+          const userId = socket.data?.user?.id;
+          if (userId) {
+            await presence.removeSocketForUser(String(userId), socket.id);
+          }
+          if (normalized.onDisconnect) {
+            try {
+              const disconnectCtx = {
+                ...baseCtx,
+                log: createWssLogger(namespacePath, socket)
+              };
+              await normalized.onDisconnect(disconnectCtx, reason);
+            } catch (error) {
+              log.error("Error in onDisconnect hook", {
+                error: error instanceof Error ? error.message : String(error)
+              });
+            }
+          }
+          log.info("Socket disconnected", { reason });
+        });
+      } catch (error) {
+        log.error("Error during connection setup", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+        socket.disconnect();
+      }
     });
   }
 }
+function parseCookies2(cookieString) {
+  const cookies = {};
+  cookieString.split(";").forEach((cookie) => {
+    const [name, value] = cookie.trim().split("=");
+    if (name && value) {
+      cookies[name] = decodeURIComponent(value);
+    }
+  });
+  return cookies;
+}
 
 // modules/server/application.ts
 var import_http = __toESM(require("http"));
@@ -6185,9 +7285,10 @@ async function startServer(options = {}) {
     config
   });
   const routeLoader = isDev ? new FilesystemRouteLoader(appDir, projectRoot) : new ManifestRouteLoader(projectRoot);
-  setupWssEvents({
+  await setupWssEvents({
     httpServer,
-    wssRoutes
+    wssRoutes,
+    projectRoot
   });
   setupRoutes({
     app,
@@ -6576,6 +7677,90 @@ async function buildApp(options = {}) {
   console.log(`[framework][build] Build completed successfully`);
 }
 
+// modules/realtime/define-wss-route.ts
+function defineWssRoute(definition) {
+  if (process.env.NODE_ENV !== "production") {
+    validateRouteDefinition(definition);
+  }
+  return definition;
+}
+function validateRouteDefinition(definition) {
+  if (!definition) {
+    throw new Error(
+      "[loly:realtime] Route definition is required. Use defineWssRoute({ events: { ... } })"
+    );
+  }
+  if (!definition.events || typeof definition.events !== "object") {
+    throw new Error(
+      "[loly:realtime] Route definition must have an 'events' object. Example: defineWssRoute({ events: { message: { handler: ... } } })"
+    );
+  }
+  if (Object.keys(definition.events).length === 0) {
+    throw new Error(
+      "[loly:realtime] Route definition must have at least one event handler"
+    );
+  }
+  for (const [eventName, eventDef] of Object.entries(definition.events)) {
+    if (typeof eventName !== "string" || eventName.trim() === "") {
+      throw new Error(
+        "[loly:realtime] Event names must be non-empty strings"
+      );
+    }
+    if (eventName === "__loly:error") {
+      throw new Error(
+        "[loly:realtime] '__loly:error' is a reserved event name"
+      );
+    }
+    if (typeof eventDef === "function") {
+      continue;
+    }
+    if (typeof eventDef !== "object" || eventDef === null) {
+      throw new Error(
+        `[loly:realtime] Event '${eventName}' must be a handler function or an object with a 'handler' property`
+      );
+    }
+    if (typeof eventDef.handler !== "function") {
+      throw new Error(
+        `[loly:realtime] Event '${eventName}' must have a 'handler' function`
+      );
+    }
+    if (eventDef.schema !== void 0) {
+      if (typeof eventDef.schema !== "object" || eventDef.schema === null || typeof eventDef.schema.parse !== "function" && typeof eventDef.schema.safeParse !== "function") {
+        throw new Error(
+          `[loly:realtime] Event '${eventName}' schema must be a Zod or Valibot schema (must have 'parse' or 'safeParse' method)`
+        );
+      }
+    }
+    if (eventDef.rateLimit !== void 0) {
+      if (typeof eventDef.rateLimit !== "object" || eventDef.rateLimit === null || typeof eventDef.rateLimit.eventsPerSecond !== "number" || eventDef.rateLimit.eventsPerSecond <= 0) {
+        throw new Error(
+          `[loly:realtime] Event '${eventName}' rateLimit must have a positive 'eventsPerSecond' number`
+        );
+      }
+    }
+    if (eventDef.guard !== void 0 && typeof eventDef.guard !== "function") {
+      throw new Error(
+        `[loly:realtime] Event '${eventName}' guard must be a function`
+      );
+    }
+  }
+  if (definition.auth !== void 0 && typeof definition.auth !== "function") {
+    throw new Error(
+      "[loly:realtime] 'auth' must be a function"
+    );
+  }
+  if (definition.onConnect !== void 0 && typeof definition.onConnect !== "function") {
+    throw new Error(
+      "[loly:realtime] 'onConnect' must be a function"
+    );
+  }
+  if (definition.onDisconnect !== void 0 && typeof definition.onDisconnect !== "function") {
+    throw new Error(
+      "[loly:realtime] 'onDisconnect' must be a function"
+    );
+  }
+}
+
 // modules/runtime/client/bootstrap.tsx
 var import_client5 = require("react-dom/client");
 
@@ -7710,6 +8895,7 @@ var commonSchemas = {
   createModuleLogger,
   createRateLimiter,
   defaultRateLimiter,
+  defineWssRoute,
   generateRequestId,
   getAppDir,
   getBuildDir,