@emeryld/rrroutes-server 2.0.6 → 2.0.7

package/dist/index.cjs

@@ -447,8 +447,24 @@ var buildRoomPayloadSchema = (metaSchema) => import_zod.z.object({
   meta: metaSchema
 });
 var toArray = (rooms) => rooms == null ? [] : Array.isArray(rooms) ? rooms : [rooms];
+var snapshotSocketConfig = (socket) => {
+  const handshake = socket.handshake ?? {};
+  const conn = socket.conn;
+  const protocol = conn?.protocol;
+  return {
+    url: handshake.url,
+    transport: conn?.transport?.name,
+    protocol: protocol != null ? String(protocol) : void 0,
+    address: conn?.remoteAddress ?? handshake.address,
+    issued: handshake.issued,
+    time: handshake.time,
+    query: handshake.query,
+    auth: handshake.auth,
+    headers: handshake.headers
+  };
+};
 function createBuiltInConnectionHandlers(opts) {
-  const { heartbeat, sys, dbg, config, createCtx } = opts;
+  const { heartbeat, sys, dbg, config, createCtx, debugVerbose } = opts;
   const roomJoinEvent = "sys:room_join";
   const roomLeaveEvent = "sys:room_leave";
   const pingEvent = "sys:ping";
@@ -463,7 +479,30 @@ function createBuiltInConnectionHandlers(opts) {
   const socketTeardowns = /* @__PURE__ */ new WeakMap();
   const builtInConnectionListener = (socket) => {
     const typedSocket = socket;
+    const handshake = socket.handshake ?? {};
+    dbg(null, {
+      type: "lifecycle",
+      stage: "connection_init",
+      socketId: socket.id,
+      nsp: socket.nsp.name,
+      details: {
+        rooms: Array.from(socket.rooms),
+        handshakeIssued: handshake.issued
+      }
+    });
+    dbg(null, {
+      type: "config",
+      socketId: socket.id,
+      nsp: socket.nsp.name,
+      snapshot: snapshotSocketConfig(socket)
+    });
     const defaultConnect = () => {
+      dbg("sys:connect", {
+        type: "handler",
+        phase: "handler_success",
+        event: "sys:connect",
+        socketId: socket.id
+      });
       if (socket.data?.user) {
         dbg(null, {
           type: "auth",
@@ -472,17 +511,27 @@ function createBuiltInConnectionHandlers(opts) {
           sub: socket.data.user?.sub
         });
       }
+      const includeRaw = debugVerbose === true;
       const joinHandler = async (msg) => {
+        dbg(roomJoinEvent, {
+          type: "handler",
+          phase: "receive",
+          event: roomJoinEvent,
+          socketId: socket.id,
+          rooms: Array.from(socket.rooms),
+          raw: includeRaw ? msg : void 0
+        });
         const parsed = joinPayloadSchema.safeParse(msg);
         if (!parsed.success) {
           socket.emit(`${roomJoinEvent}:error`, {
             eventName: roomJoinEvent,
             issues: parsed.error.issues
           });
-          dbg("sys:room_join", {
+          dbg(roomJoinEvent, {
             type: "handler",
             phase: "validation_error",
             event: roomJoinEvent,
+            socketId: socket.id,
             issues: parsed.error.issues
           });
           return;
@@ -502,27 +551,45 @@ function createBuiltInConnectionHandlers(opts) {
         };
         try {
           await run();
+          dbg(roomJoinEvent, {
+            type: "handler",
+            phase: "handler_success",
+            event: roomJoinEvent,
+            socketId: socket.id,
+            rooms: list,
+            details: includeRaw ? { meta: parsed.data.meta } : void 0
+          });
         } catch (error) {
           socket.emit(`${roomJoinEvent}:error`, { error: normalizeError(error) });
-          dbg("sys:room_join", {
+          dbg(roomJoinEvent, {
             type: "handler",
             phase: "handler_error",
             event: roomJoinEvent,
+            socketId: socket.id,
             error
           });
         }
       };
       const leaveHandler = async (msg) => {
+        dbg(roomLeaveEvent, {
+          type: "handler",
+          phase: "receive",
+          event: roomLeaveEvent,
+          socketId: socket.id,
+          rooms: Array.from(socket.rooms),
+          raw: includeRaw ? msg : void 0
+        });
         const parsed = leavePayloadSchema.safeParse(msg);
         if (!parsed.success) {
           socket.emit(`${roomLeaveEvent}:error`, {
             eventName: roomLeaveEvent,
             issues: parsed.error.issues
           });
-          dbg("sys:room_leave", {
+          dbg(roomLeaveEvent, {
             type: "handler",
             phase: "validation_error",
             event: roomLeaveEvent,
+            socketId: socket.id,
             issues: parsed.error.issues
           });
           return;
@@ -542,18 +609,43 @@ function createBuiltInConnectionHandlers(opts) {
         };
         try {
           await run();
+          dbg(roomLeaveEvent, {
+            type: "handler",
+            phase: "handler_success",
+            event: roomLeaveEvent,
+            socketId: socket.id,
+            rooms: list,
+            details: includeRaw ? { meta: parsed.data.meta } : void 0
+          });
         } catch (error) {
           socket.emit(`${roomLeaveEvent}:error`, { error: normalizeError(error) });
-          dbg("sys:room_leave", {
+          dbg(roomLeaveEvent, {
             type: "handler",
             phase: "handler_error",
             event: roomLeaveEvent,
+            socketId: socket.id,
             error
           });
         }
       };
       const pingHandler = async (msg) => {
-        if (!heartbeatEnabled) return;
+        if (!heartbeatEnabled) {
+          dbg(null, {
+            type: "lifecycle",
+            stage: "early_return",
+            socketId: socket.id,
+            nsp: socket.nsp.name,
+            details: { reason: "heartbeat_disabled", event: pingEvent }
+          });
+          dbg(null, {
+            type: "heartbeat",
+            phase: "skip",
+            socketId: socket.id,
+            details: { reason: "heartbeat_disabled" },
+            error: false
+          });
+          return;
+        }
         const parsedPing = pingPayloadSchema.safeParse(msg);
         if (!parsedPing.success) {
           socket.emit(`${pingEvent}:error`, {
@@ -564,8 +656,10 @@ function createBuiltInConnectionHandlers(opts) {
             type: "heartbeat",
             phase: "ping",
             socketId: socket.id,
+            payload: includeRaw ? msg : void 0,
             issues: parsedPing.error.issues,
-            error: true
+            error: true,
+            details: { step: "parse" }
           });
           return;
         }
@@ -587,7 +681,8 @@ function createBuiltInConnectionHandlers(opts) {
             phase: "ping",
             socketId: socket.id,
             payload: parsedPing.data,
-            error: true
+            error: true,
+            details: { step: "sys_handler_error" }
           });
           return;
         }
@@ -601,8 +696,10 @@ function createBuiltInConnectionHandlers(opts) {
             type: "heartbeat",
             phase: "pong",
             socketId: socket.id,
+            payload: includeRaw ? pongPayload : void 0,
             issues: parsedPong.error.issues,
-            error: true
+            error: true,
+            details: { step: "parse" }
           });
           return;
         }
@@ -621,6 +718,13 @@ function createBuiltInConnectionHandlers(opts) {
         socket.on(pingEvent, pingHandler);
       }
       const cleanup = () => {
+        dbg(null, {
+          type: "lifecycle",
+          stage: "connection_cleanup",
+          socketId: socket.id,
+          nsp: socket.nsp.name,
+          details: { reason: "teardown" }
+        });
         socket.off(roomJoinEvent, joinHandler);
         socket.off(roomLeaveEvent, leaveHandler);
         if (heartbeatEnabled) {
@@ -628,7 +732,26 @@ function createBuiltInConnectionHandlers(opts) {
         }
       };
       socketTeardowns.set(socket, cleanup);
+      dbg(null, {
+        type: "lifecycle",
+        stage: "connection_handlers_attached",
+        socketId: socket.id,
+        nsp: socket.nsp.name,
+        details: {
+          heartbeatEnabled,
+          joinEvent: roomJoinEvent,
+          leaveEvent: roomLeaveEvent,
+          pingEvent: heartbeatEnabled ? pingEvent : void 0
+        }
+      });
       socket.once("disconnect", (reason) => {
+        dbg("sys:disconnect", {
+          type: "handler",
+          phase: "receive",
+          event: "sys:disconnect",
+          socketId: socket.id,
+          details: { reason: String(reason) }
+        });
         const defaultDisconnect = () => {
           cleanup();
           socketTeardowns.delete(socket);
@@ -640,6 +763,14 @@ function createBuiltInConnectionHandlers(opts) {
         });
       });
     };
+    dbg("sys:connect", {
+      type: "handler",
+      phase: "receive",
+      event: "sys:connect",
+      socketId: socket.id,
+      nsp: socket.nsp.name,
+      details: { hasAuthData: Boolean(socket.data?.user) }
+    });
     getSysEvent("sys:connect")({
       socket: typedSocket,
       initConnection: defaultConnect
@@ -681,6 +812,17 @@ var normalizeError2 = (error, verbose) => {
 function createSocketConnections(io, events, opts) {
   const dbg = createDebugger(opts?.debug);
   const socketConfig = opts.config;
+  const heartbeatEnabled = opts?.heartbeat?.enabled !== false;
+  const eventNames = Object.keys(events);
+  dbg(null, {
+    type: "lifecycle",
+    stage: "server_init",
+    details: {
+      eventCount: eventNames.length,
+      heartbeatEnabled,
+      debugEnabled: Boolean(opts?.debug?.logger)
+    }
+  });
   const getSchema = (k) => events[k].message;
   const toArray2 = (rooms) => rooms == null ? [] : Array.isArray(rooms) ? rooms : [rooms];
   const registrations = /* @__PURE__ */ new Map();
@@ -694,7 +836,14 @@ function createSocketConnections(io, events, opts) {
   };
   const removeAllForEvent = (eventName) => {
     const set = registrations.get(eventName);
-    if (!set) return;
+    if (!set) {
+      dbg(null, {
+        type: "lifecycle",
+        stage: "early_return",
+        details: { reason: "no_registrations", event: eventName }
+      });
+      return;
+    }
     for (const reg of set) {
       io.off("connection", reg.connectionListener);
       for (const socket of io.sockets.sockets.values()) {
@@ -716,9 +865,18 @@ function createSocketConnections(io, events, opts) {
     sys: opts.sys,
     dbg,
     config: socketConfig,
-    createCtx: createBaseHandlerCtx
+    createCtx: createBaseHandlerCtx,
+    debugVerbose: opts?.debug?.verbose === true
   });
   io.on("connection", builtInConnectionListener);
+  dbg(null, {
+    type: "lifecycle",
+    stage: "connection_listener_installed",
+    details: {
+      heartbeatEnabled,
+      sysEvents: Object.keys(opts.sys ?? {})
+    }
+  });
   const conn = {
     on(eventName, handler) {
       const socketListeners = /* @__PURE__ */ new WeakMap();
@@ -738,7 +896,8 @@ function createSocketConnections(io, events, opts) {
             socketId: ctx.socketId,
             nsp: ctx.nsp,
             rooms: ctx.rooms,
-            raw: opts?.debug?.verbose ? raw : void 0
+            raw: opts?.debug?.verbose ? raw : void 0,
+            details: { ack: Boolean(maybeAck) }
           });
           if (!parsed.success) {
             socket.emit(`${String(eventName)}:error`, {
@@ -750,7 +909,10 @@ function createSocketConnections(io, events, opts) {
               type: "handler",
               phase: "validation_error",
               event: String(eventName),
-              issues: parsed.error.issues
+              socketId: ctx.socketId,
+              nsp: ctx.nsp,
+              issues: parsed.error.issues,
+              details: { ack: Boolean(maybeAck) }
             });
             return;
           }
@@ -759,13 +921,20 @@ function createSocketConnections(io, events, opts) {
             dbg(String(eventName), {
               type: "handler",
               phase: "handler_success",
-              event: String(eventName)
+              event: String(eventName),
+              socketId: ctx.socketId,
+              nsp: ctx.nsp,
+              rooms: ctx.rooms,
+              details: { ack: Boolean(maybeAck) }
             });
           } catch (error) {
             dbg(String(eventName), {
               type: "handler",
               phase: "handler_error",
               event: String(eventName),
+              socketId: ctx.socketId,
+              nsp: ctx.nsp,
+              rooms: ctx.rooms,
               error
             });
             socket.emit(`${String(eventName)}:error`, {
@@ -791,7 +960,14 @@ function createSocketConnections(io, events, opts) {
       });
       return () => {
         const set = registrations.get(String(eventName));
-        if (!set) return;
+        if (!set) {
+          dbg(null, {
+            type: "lifecycle",
+            stage: "early_return",
+            details: { reason: "registration_missing_on_cleanup", event: String(eventName) }
+          });
+          return;
+        }
         for (const reg of Array.from(set)) {
           if (reg.connectionListener === connectionListener) {
             io.off("connection", reg.connectionListener);
@@ -816,10 +992,22 @@ function createSocketConnections(io, events, opts) {
     },
     emit(eventName, payload, rooms, metadata, onAck) {
       const schema = getSchema(eventName);
+      const targets = toArray2(rooms);
       const check = schema.safeParse(payload);
-      if (!check.success)
+      if (!check.success) {
+        dbg(String(eventName), {
+          type: "emit",
+          event: String(eventName),
+          rooms: targets,
+          envelope: opts?.debug?.verbose ? { eventName, attemptedPayload: payload, metadata } : void 0,
+          error: {
+            reason: "invalid_payload",
+            message: check.error.message,
+            issues: opts?.debug?.verbose ? check.error.issues : void 0
+          }
+        });
         throw new Error(`Invalid payload for "${String(eventName)}": ${check.error.message}`);
-      const targets = toArray2(rooms);
+      }
       const envelope = {
         eventName,
         sentAt: /* @__PURE__ */ new Date(),
@@ -849,6 +1037,15 @@ function createSocketConnections(io, events, opts) {
           });
           return;
         }
+        dbg(String(eventName), {
+          type: "emit",
+          event: String(eventName),
+          rooms: targets,
+          error: {
+            reason: "socket_not_found",
+            message: `Socket ${sid} not connected`
+          }
+        });
       }
       if (targets.length === 0) io.emit(String(eventName), envelope);
       else io.to(targets).emit(String(eventName), envelope);
@@ -860,6 +1057,14 @@ function createSocketConnections(io, events, opts) {
       });
     },
     destroy() {
+      dbg(null, {
+        type: "lifecycle",
+        stage: "destroy_start",
+        details: {
+          socketCount: io.sockets.sockets.size,
+          registrationCount: registrations.size
+        }
+      });
       io.off("connection", builtInConnectionListener);
       for (const socket of io.sockets.sockets.values()) {
         const cleanup = socketTeardowns.get(socket);
@@ -867,6 +1072,13 @@ function createSocketConnections(io, events, opts) {
           cleanup();
           socketTeardowns.delete(socket);
         } else {
+          dbg(null, {
+            type: "lifecycle",
+            stage: "early_return",
+            socketId: socket.id,
+            nsp: socket.nsp.name,
+            details: { reason: "teardown_missing" }
+          });
           try {
             socket.removeAllListeners(roomJoinEvent);
             socket.removeAllListeners(roomLeaveEvent);
@@ -879,6 +1091,14 @@ function createSocketConnections(io, events, opts) {
         removeAllForEvent(eventName);
       }
       registrations.clear();
+      dbg(null, {
+        type: "lifecycle",
+        stage: "destroy_complete",
+        details: {
+          socketCount: io.sockets.sockets.size,
+          registrationCount: registrations.size
+        }
+      });
     }
   };
   return conn;