@super-line/server 0.1.0 → 0.3.0

package/dist/index.js

@@ -1,38 +1,71 @@
+import "./chunk-MLKGABMK.js";
+
 // src/index.ts
 import { randomUUID } from "crypto";
 import { WebSocketServer } from "ws";
 import {
   jsonSerializer,
   validate,
-  SocketError
+  SuperLineError,
+  INSPECTOR_SUBPROTOCOL,
+  INSPECTOR_ROLE,
+  classifyContract
 } from "@super-line/core";
 
 // src/conn.ts
 var Conn = class {
-  constructor(ws, role, ctx, serializer) {
+  constructor(ws, id, role, ctx, serializer, backpressure, onEmit) {
     this.ws = ws;
+    this.id = id;
     this.role = role;
     this.ctx = ctx;
     this.serializer = serializer;
+    this.backpressure = backpressure;
+    this.onEmit = onEmit;
   }
   ws;
+  id;
   role;
   ctx;
   serializer;
+  backpressure;
+  onEmit;
   /** Namespaced channels (rooms + topics) this connection belongs to. */
   channels = /* @__PURE__ */ new Set();
+  /** Mutable per-connection scratch state, typed per role by the contract's `data` schema. */
+  data = {};
+  /** When this connection was accepted (`Date.now()` at the upgrade). */
+  connectedAt = Date.now();
+  /** When the server last sent a heartbeat ping to this connection (managed by the server). */
+  lastPingAt;
+  /** When a heartbeat pong was last received — liveness signal (managed by the server). */
+  lastPongAt;
+  /** Pings sent since the last pong; drives reaping (managed by the server). */
+  missedPongs = 0;
+  // true => the frame was handled by the backpressure policy and must not be sent
+  overBackpressure() {
+    const bp = this.backpressure;
+    if (!bp || this.ws.bufferedAmount <= bp.maxBufferedBytes) return false;
+    if (bp.onExceed === "drop") {
+      console.warn(`[super-line] dropping frame: conn ${this.id} over backpressure limit`);
+      return true;
+    }
+    this.ws.close(1013);
+    return true;
+  }
   /** Encode and send a frame (unicast, e.g. req/res). */
   send(frame) {
-    if (this.ws.readyState !== this.ws.OPEN) return;
+    if (this.ws.readyState !== this.ws.OPEN || this.overBackpressure()) return;
     this.ws.send(this.serializer.encode(frame));
   }
   /** Forward an already-encoded frame (fan-out path; encoded once at the source). */
   sendRaw(payload) {
-    if (this.ws.readyState !== this.ws.OPEN) return;
+    if (this.ws.readyState !== this.ws.OPEN || this.overBackpressure()) return;
     this.ws.send(payload);
   }
   /** Push an event to THIS connection (node-local). Scoped to the role's events. */
   emit(event, data) {
+    this.onEmit?.(String(event), data);
     this.send({ t: "evt", e: String(event), d: data });
   }
   /** Close the underlying socket. */
@@ -44,6 +77,8 @@ var Conn = class {
 // src/memory-adapter.ts
 var MemoryBus = class {
   channels = /* @__PURE__ */ new Map();
+  // shared presence directory; in-memory liveness = "has a descriptor" (graceful del on disconnect)
+  descriptors = /* @__PURE__ */ new Map();
   subscribe(channel, adapter) {
     let set = this.channels.get(channel);
     if (!set) {
@@ -64,12 +99,69 @@ var MemoryBus = class {
     for (const adapter of set) adapter.deliver(channel, payload);
   }
 };
+var MemoryPresence = class {
+  constructor(bus) {
+    this.bus = bus;
+  }
+  bus;
+  set(d) {
+    this.bus.descriptors.set(d.id, d);
+  }
+  del(connId) {
+    this.bus.descriptors.delete(connId);
+  }
+  beat() {
+  }
+  clearNode(nodeId) {
+    for (const [id, d] of this.bus.descriptors) if (d.nodeId === nodeId) this.bus.descriptors.delete(id);
+  }
+  addRoom(connId, room) {
+    const d = this.bus.descriptors.get(connId);
+    if (d && !d.rooms.includes(room)) d.rooms = [...d.rooms, room];
+  }
+  removeRoom(connId, room) {
+    const d = this.bus.descriptors.get(connId);
+    if (d) d.rooms = d.rooms.filter((r) => r !== room);
+  }
+  list() {
+    return [...this.bus.descriptors.values()];
+  }
+  get(connId) {
+    return this.bus.descriptors.get(connId);
+  }
+  byUser(userId) {
+    return this.list().filter((d) => d.userId === userId);
+  }
+  roomMembers(room) {
+    return this.list().filter((d) => d.rooms.includes(room));
+  }
+  count() {
+    return this.bus.descriptors.size;
+  }
+  topology() {
+    const byNode = /* @__PURE__ */ new Map();
+    for (const d of this.list()) {
+      const set = byNode.get(d.nodeId);
+      if (set) set.push(d);
+      else byNode.set(d.nodeId, [d]);
+    }
+    return [...byNode.entries()].map(([nodeId, ds]) => ({
+      nodeId,
+      nodeName: ds[0]?.nodeName ?? nodeId,
+      connections: ds.length,
+      rooms: new Set(ds.flatMap((d) => d.rooms)).size,
+      alive: true
+    }));
+  }
+};
 var MemoryAdapter = class {
   constructor(bus) {
     this.bus = bus;
+    this.presence = new MemoryPresence(bus);
   }
   bus;
   handler;
+  presence;
   subscribe(channel) {
     this.bus.subscribe(channel, this);
   }
@@ -93,93 +185,396 @@ function createInMemoryAdapter(bus = new MemoryBus()) {
 // src/index.ts
 var ROOM = "r:";
 var TOPIC = "t:";
-var S2S = "s2s";
-function createSocketServer(contract, opts) {
+var CONN = "c:";
+var USER = "u:";
+var REPLY = "reply:";
+var INSPECT = "i:";
+function createSuperLineServer(contract, opts) {
   const c = contract;
   const serializer = opts.serializer ?? jsonSerializer;
   const adapter = opts.adapter ?? createInMemoryAdapter();
-  const wss = new WebSocketServer({ noServer: true });
+  const inspectorEnabled = !!opts.inspector;
+  const inspectorRedact = new Set(
+    opts.inspector && typeof opts.inspector === "object" ? opts.inspector.redact ?? [] : []
+  );
+  const wss = new WebSocketServer({
+    noServer: true,
+    handleProtocols: (protocols) => inspectorEnabled && protocols.has(INSPECTOR_SUBPROTOCOL) ? INSPECTOR_SUBPROTOCOL : false
+  });
   const conns = /* @__PURE__ */ new Set();
+  const inspectorConns = /* @__PURE__ */ new Set();
   const members = /* @__PURE__ */ new Map();
-  const serverListeners = /* @__PURE__ */ new Map();
+  const busListeners = /* @__PURE__ */ new Map();
   const instanceId = randomUUID();
+  const nodeName = opts.nodeName ?? process.env.SUPER_LINE_NODE_NAME ?? instanceId.slice(0, 8);
+  const replyChannel = REPLY + instanceId;
   let impl = {};
+  let closing = false;
+  let nextSReq = 1;
+  const originWaiters = /* @__PURE__ */ new Map();
+  const ownerRouting = /* @__PURE__ */ new Map();
+  function buildDescriptor(conn) {
+    const userId = opts.identify?.(conn);
+    const rooms = [];
+    for (const ch of conn.channels) if (ch.startsWith(ROOM)) rooms.push(ch.slice(ROOM.length));
+    return {
+      id: conn.id,
+      role: conn.role,
+      nodeId: instanceId,
+      nodeName,
+      connectedAt: conn.connectedAt,
+      ...userId !== void 0 ? { userId } : {},
+      rooms,
+      ...opts.describeConn?.(conn)
+    };
+  }
+  function presenceOrThrow() {
+    if (!adapter.presence) throw new Error("cluster queries require an adapter with presence support");
+    return adapter.presence;
+  }
   adapter.onMessage((channel, payload) => {
-    if (channel === S2S) {
-      handleServerMessage(payload);
+    if (channel === replyChannel) {
+      handleReply(payload);
+      return;
+    }
+    if (channel.startsWith(CONN) || channel.startsWith(USER)) {
+      handlePersonal(channel, payload);
       return;
     }
     const set = members.get(channel);
-    if (!set) return;
-    for (const conn of set) conn.sendRaw(payload);
+    if (set) for (const conn of set) conn.sendRaw(payload);
+    const busSet = busListeners.get(channel);
+    if (busSet) deliverBus(payload, busSet);
   });
-  if (c.serverToServer) void adapter.subscribe(S2S);
-  function handleServerMessage(payload) {
-    let msg;
+  void adapter.subscribe(replyChannel);
+  function handlePersonal(channel, payload) {
+    const set = members.get(channel);
+    if (!set) return;
+    let env;
     try {
-      msg = serializer.decode(payload);
+      env = serializer.decode(payload);
     } catch {
       return;
     }
-    if (msg.from === instanceId) return;
-    const set = serverListeners.get(msg.e);
-    if (set) for (const cb of set) cb(msg.d);
+    if (env.p === "close") {
+      for (const conn of set) conn.close();
+      return;
+    }
+    if (env.p === "req") {
+      const localId = nextSReq++;
+      ownerRouting.set(localId, { origin: env.o, corrId: env.i, name: env.m });
+      for (const conn of set) conn.send({ t: "sreq", i: localId, m: env.m, d: env.d });
+      return;
+    }
+    const frame = serializer.encode(env.f);
+    for (const conn of set) conn.sendRaw(frame);
+  }
+  function handleReply(payload) {
+    let env;
+    try {
+      env = serializer.decode(payload);
+    } catch {
+      return;
+    }
+    const w = originWaiters.get(env.i);
+    if (!w) return;
+    originWaiters.delete(env.i);
+    if (w.timer) clearTimeout(w.timer);
+    if (env.ok) w.resolve(env.d);
+    else w.reject(new SuperLineError(env.code, env.m, env.d));
+  }
+  async function handleClientReply(conn, localId, result) {
+    const r = ownerRouting.get(localId);
+    if (!r) return;
+    ownerRouting.delete(localId);
+    let env;
+    if (result.ok) {
+      try {
+        const def = c.roles[conn.role]?.serverToClient?.[r.name] ?? c.shared?.serverToClient?.[r.name];
+        const out = def && "output" in def ? await validate(def.output, result.d) : result.d;
+        env = { i: r.corrId, ok: true, d: out };
+      } catch (err) {
+        const e = err instanceof SuperLineError ? err : new SuperLineError("INTERNAL", "Internal server error");
+        env = { i: r.corrId, ok: false, code: e.code, m: e.message, d: e.data };
+      }
+    } else {
+      env = { i: r.corrId, ok: false, code: result.code, m: result.m, d: result.d };
+    }
+    if (inspectorEnabled)
+      emitInspectorEvent(
+        env.ok ? { type: "msg.serverReply", target: conn.id, name: r.name, ok: true, output: safeSnapshot(env.d) } : {
+          type: "msg.serverReply",
+          target: conn.id,
+          name: r.name,
+          ok: false,
+          error: { code: env.code, message: env.m }
+        }
+      );
+    void adapter.publish(REPLY + r.origin, serializer.encode(env));
+  }
+  const hb = opts.heartbeat === false ? null : opts.heartbeat ?? {};
+  let hbTimer;
+  if (hb) {
+    hbTimer = setInterval(() => {
+      const now = Date.now();
+      void adapter.presence?.beat(instanceId);
+      for (const conn of conns) {
+        if (hb.maxMissed != null && conn.missedPongs >= hb.maxMissed) {
+          conn.ws.terminate();
+          continue;
+        }
+        conn.missedPongs++;
+        conn.lastPingAt = now;
+        conn.ws.ping();
+      }
+    }, hb.interval ?? 3e4);
+    hbTimer.unref?.();
+  }
+  function emitInspectorEvent(event) {
+    if (!inspectorEnabled) return;
+    void adapter.publish(INSPECT + "events", serializer.encode({ t: "pub", c: "events", d: event }));
   }
   function joinChannel(conn, channel) {
     conn.channels.add(channel);
+    if (channel.startsWith(ROOM)) {
+      const room2 = channel.slice(ROOM.length);
+      void adapter.presence?.addRoom(conn.id, room2);
+      emitInspectorEvent({ type: "room.add", connId: conn.id, room: room2 });
+    } else if (channel.startsWith(TOPIC)) {
+      emitInspectorEvent({ type: "topic.sub", connId: conn.id, topic: channel.slice(channel.indexOf(":", TOPIC.length) + 1) });
+    }
     const set = members.get(channel);
     if (set) {
       set.add(conn);
       return;
     }
+    const alreadySubscribed = busListeners.has(channel);
     members.set(channel, /* @__PURE__ */ new Set([conn]));
-    return adapter.subscribe(channel);
+    if (!alreadySubscribed) return adapter.subscribe(channel);
   }
   function leaveChannel(conn, channel) {
     const set = members.get(channel);
     if (!set) return;
     set.delete(conn);
     conn.channels.delete(channel);
+    if (channel.startsWith(ROOM)) {
+      const room2 = channel.slice(ROOM.length);
+      void adapter.presence?.removeRoom(conn.id, room2);
+      emitInspectorEvent({ type: "room.remove", connId: conn.id, room: room2 });
+    } else if (channel.startsWith(TOPIC)) {
+      emitInspectorEvent({ type: "topic.unsub", connId: conn.id, topic: channel.slice(channel.indexOf(":", TOPIC.length) + 1) });
+    }
     if (set.size === 0) {
       members.delete(channel);
-      void adapter.unsubscribe(channel);
+      if (!busListeners.has(channel)) void adapter.unsubscribe(channel);
     }
   }
+  function isTopic(name, block) {
+    const def = block?.serverToClient?.[name];
+    return !!def && typeof def === "object" && "subscribe" in def && def.subscribe === true;
+  }
   function topicNamespace(role, name) {
-    if (c.roles[role]?.serverToClient?.[name]?.subscribe) return role;
-    if (c.shared?.serverToClient?.[name]?.subscribe) return "shared";
+    if (isTopic(name, c.roles[role])) return role;
+    if (isTopic(name, c.shared)) return "shared";
     return void 0;
   }
+  function localRooms() {
+    const out = [];
+    for (const channel of members.keys()) if (channel.startsWith(ROOM)) out.push(channel.slice(ROOM.length));
+    return out;
+  }
+  function localTopics() {
+    const out = [];
+    for (const channel of members.keys()) {
+      if (!channel.startsWith(TOPIC)) continue;
+      out.push(channel.slice(channel.indexOf(":", TOPIC.length) + 1));
+    }
+    return out;
+  }
+  async function onInspectorFrame(conn, frame) {
+    if (frame.t === "req") await handleInspectorReq(conn, frame);
+    else if (frame.t === "sub") await handleInspectorSub(conn, frame);
+    else if (frame.t === "unsub") leaveChannel(conn, INSPECT + "events");
+  }
+  async function handleInspectorSub(conn, frame) {
+    if (frame.c !== "events") {
+      conn.send({ t: "err", i: frame.i, code: "NOT_FOUND", m: `Unknown topic: ${frame.c}` });
+      return;
+    }
+    await joinChannel(conn, INSPECT + "events");
+    conn.send({ t: "res", i: frame.i, d: null });
+  }
+  async function handleInspectorReq(conn, frame) {
+    const handler = inspectorHandlers[frame.m];
+    if (!handler) {
+      conn.send({ t: "err", i: frame.i, code: "NOT_FOUND", m: `Unknown message: ${frame.m}` });
+      return;
+    }
+    try {
+      const output = await handler(frame.d, conn);
+      conn.send({ t: "res", i: frame.i, d: output });
+    } catch (err) {
+      const e = err instanceof SuperLineError ? err : new SuperLineError("INTERNAL", "Internal server error");
+      conn.send({ t: "err", i: frame.i, code: e.code, m: e.message, d: e.data });
+    }
+  }
+  async function buildInspectedContract() {
+    let toJsonSchema;
+    try {
+      const mod = await import("./dist-S566F7HE.js");
+      toJsonSchema = mod.toJsonSchema;
+    } catch {
+      return classifyContract(c);
+    }
+    const schemas = /* @__PURE__ */ new Set();
+    classifyContract(c, (s) => {
+      schemas.add(s);
+      return void 0;
+    });
+    const converted = /* @__PURE__ */ new Map();
+    await Promise.all(
+      [...schemas].map(
+        (s) => toJsonSchema(s).then(
+          (j) => {
+            converted.set(s, j);
+          },
+          () => {
+          }
+          // unsupported vendor / missing per-vendor converter -> structure-only for this entry
+        )
+      )
+    );
+    return classifyContract(c, (s) => converted.get(s));
+  }
+  function safeSnapshot(value, depth = 0, seen = /* @__PURE__ */ new WeakSet()) {
+    if (value === null) return null;
+    const t = typeof value;
+    if (t === "bigint") return `${value.toString()}n`;
+    if (t === "function") return "[Function]";
+    if (t === "symbol") return value.toString();
+    if (t !== "object") return value;
+    const obj = value;
+    if (obj instanceof Date) return obj.toISOString();
+    if (seen.has(obj)) return "[Circular]";
+    if (depth >= 6) return "[MaxDepth]";
+    seen.add(obj);
+    try {
+      if (Array.isArray(obj)) return obj.slice(0, 1e3).map((v) => safeSnapshot(v, depth + 1, seen));
+      const ctor = Object.getPrototypeOf(obj)?.constructor?.name;
+      const out = {};
+      if (ctor && ctor !== "Object") out["#type"] = ctor;
+      for (const [k, v] of Object.entries(obj)) {
+        out[k] = inspectorRedact.has(k) ? "[Redacted]" : safeSnapshot(v, depth + 1, seen);
+      }
+      return out;
+    } finally {
+      seen.delete(obj);
+    }
+  }
+  const inspectorHandlers = {
+    getContract: () => buildInspectedContract(),
+    getTopology: async () => presenceOrThrow().topology(),
+    listConnections: async () => presenceOrThrow().list(),
+    getNode: async () => ({ nodeId: instanceId, nodeName, rooms: localRooms(), topics: localTopics() }),
+    getConn: async (input) => {
+      const id = input?.id;
+      if (!id) throw new SuperLineError("BAD_REQUEST", "getConn requires an id");
+      const local = [...conns].find((cn) => cn.id === id);
+      if (local) {
+        return {
+          descriptor: buildDescriptor(local),
+          ctx: safeSnapshot(local.ctx),
+          data: safeSnapshot(local.data),
+          ctxAvailable: true
+        };
+      }
+      const remote = await presenceOrThrow().get(id);
+      if (!remote) throw new SuperLineError("NOT_FOUND", `Unknown connection: ${id}`);
+      return { descriptor: remote, ctxAvailable: false };
+    }
+  };
   if (opts.server) {
     opts.server.on("upgrade", (req, socket, head) => {
       void handleUpgrade(req, socket, head);
     });
   }
+  function isInspectorRequest(req) {
+    if (!inspectorEnabled) return false;
+    const raw = req.headers["sec-websocket-protocol"];
+    if (!raw) return false;
+    const offered = (Array.isArray(raw) ? raw.join(",") : raw).split(",").map((p) => p.trim());
+    return offered.includes(INSPECTOR_SUBPROTOCOL);
+  }
   async function handleUpgrade(req, socket, head) {
     if (opts.path) {
       const { pathname } = new URL(req.url ?? "/", "http://localhost");
       if (pathname !== opts.path) return;
     }
-    let auth;
-    try {
-      auth = await opts.authenticate(req);
-    } catch {
-      socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
-      socket.destroy();
-      return;
+    const inspector = isInspectorRequest(req);
+    let role;
+    let ctx;
+    if (inspector) {
+      role = INSPECTOR_ROLE;
+      ctx = {};
+    } else {
+      let auth;
+      try {
+        auth = await opts.authenticate(req);
+      } catch {
+        socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+        socket.destroy();
+        return;
+      }
+      role = auth.role;
+      ctx = auth.ctx;
     }
     wss.handleUpgrade(req, socket, head, (ws) => {
-      const conn = new Conn(ws, auth.role, auth.ctx, serializer);
-      conns.add(conn);
+      const connId = randomUUID();
+      const conn = new Conn(
+        ws,
+        connId,
+        role,
+        ctx,
+        serializer,
+        opts.backpressure,
+        inspectorEnabled ? (event, data) => emitInspectorEvent({ type: "msg.event", target: connId, name: event, data: safeSnapshot(data) }) : void 0
+      );
       ws.on("message", (data, isBinary) => {
         void onMessage(conn, data, isBinary);
       });
+      if (inspector) {
+        inspectorConns.add(conn);
+        ws.on("close", () => {
+          inspectorConns.delete(conn);
+          for (const channel of conn.channels) leaveChannel(conn, channel);
+        });
+        return;
+      }
+      conns.add(conn);
+      ws.on("pong", () => {
+        conn.lastPongAt = Date.now();
+        conn.missedPongs = 0;
+      });
       ws.on("close", (code) => {
         conns.delete(conn);
         for (const channel of conn.channels) leaveChannel(conn, channel);
-        opts.onDisconnect?.(conn, auth.ctx, code);
+        void adapter.presence?.del(conn.id);
+        const goneUserId = opts.identify?.(conn);
+        emitInspectorEvent({
+          type: "disconnect",
+          connId: conn.id,
+          nodeId: instanceId,
+          ...goneUserId !== void 0 ? { userId: goneUserId } : {}
+        });
+        opts.onDisconnect?.(conn, ctx, code);
       });
-      opts.onConnection?.(conn, auth.ctx);
+      opts.onConnection?.(conn, ctx);
+      const descriptor = buildDescriptor(conn);
+      void adapter.presence?.set(descriptor);
+      emitInspectorEvent({ type: "connect", descriptor });
+      void joinChannel(conn, CONN + conn.id);
+      const uid = opts.identify?.(conn);
+      if (uid !== void 0) void joinChannel(conn, USER + uid);
     });
   }
   async function onMessage(conn, data, isBinary) {
@@ -189,11 +584,19 @@ function createSocketServer(contract, opts) {
     } catch {
       return;
     }
+    if (inspectorConns.has(conn)) {
+      await onInspectorFrame(conn, frame);
+      return;
+    }
     if (frame.t === "req") await handleReq(conn, frame);
     else if (frame.t === "sub") await handleSub(conn, frame);
     else if (frame.t === "unsub") {
       const ns = topicNamespace(conn.role, frame.c);
       if (ns) leaveChannel(conn, TOPIC + ns + ":" + frame.c);
+    } else if (frame.t === "sres") {
+      await handleClientReply(conn, frame.i, { ok: true, d: frame.d });
+    } else if (frame.t === "serr") {
+      await handleClientReply(conn, frame.i, { ok: false, code: frame.code, m: frame.m, d: frame.d });
     }
   }
   function runMiddleware(info, terminal) {
@@ -217,10 +620,16 @@ function createSocketServer(contract, opts) {
       });
     } catch (err) {
       opts.onError?.(err, info);
-      if (!responded) {
-        const e = err instanceof SocketError ? err : new SocketError("INTERNAL", "Internal server error");
-        conn.send({ t: "err", i: id, code: e.code, m: e.message, d: e.data });
-      }
+      const e = err instanceof SuperLineError ? err : new SuperLineError("INTERNAL", "Internal server error");
+      if (!responded) conn.send({ t: "err", i: id, code: e.code, m: e.message, d: e.data });
+      if (inspectorEnabled && info.kind === "request")
+        emitInspectorEvent({
+          type: "msg.response",
+          connId: conn.id,
+          name: info.name,
+          ok: false,
+          error: { code: e.code, message: e.message }
+        });
     }
   }
   async function handleReq(conn, frame) {
@@ -232,7 +641,23 @@ function createSocketServer(contract, opts) {
     }
     await dispatchOp(conn, frame.i, { kind: "request", name: frame.m, conn }, async () => {
       const input = await validate(def.input, frame.d);
+      if (inspectorEnabled)
+        emitInspectorEvent({
+          type: "msg.request",
+          connId: conn.id,
+          role: conn.role,
+          name: frame.m,
+          input: safeSnapshot(input)
+        });
       const output = await handler(input, conn.ctx, conn);
+      if (inspectorEnabled)
+        emitInspectorEvent({
+          type: "msg.response",
+          connId: conn.id,
+          name: frame.m,
+          ok: true,
+          output: safeSnapshot(output)
+        });
       conn.send({ t: "res", i: frame.i, d: output });
     });
   }
@@ -245,7 +670,7 @@ function createSocketServer(contract, opts) {
     await dispatchOp(conn, frame.i, { kind: "subscribe", name: frame.c, conn }, async () => {
       if (opts.authorizeSubscribe) {
         const ok = await opts.authorizeSubscribe(frame.c, conn.ctx, conn);
-        if (ok === false) throw new SocketError("FORBIDDEN", `Subscribe denied: ${frame.c}`);
+        if (ok === false) throw new SuperLineError("FORBIDDEN", `Subscribe denied: ${frame.c}`);
       }
       await joinChannel(conn, TOPIC + ns + ":" + frame.c);
       conn.send({ t: "res", i: frame.i, d: null });
@@ -261,17 +686,146 @@ function createSocketServer(contract, opts) {
         leaveChannel(conn, channel);
       },
       broadcast(event, data) {
+        if (inspectorEnabled)
+          emitInspectorEvent({ type: "msg.broadcast", room: name, name: String(event), data: safeSnapshot(data) });
         void adapter.publish(channel, serializer.encode({ t: "evt", e: String(event), d: data }));
       },
       get size() {
         return members.get(channel)?.size ?? 0;
+      },
+      get connections() {
+        return [...members.get(channel) ?? []];
       }
     };
   }
   function publishTo(ns, name, data) {
-    void adapter.publish(TOPIC + ns + ":" + name, serializer.encode({ t: "pub", c: name, d: data }));
+    const channel = TOPIC + ns + ":" + name;
+    if (inspectorEnabled) emitInspectorEvent({ type: "msg.publish", topic: name, data: safeSnapshot(data) });
+    const busSet = busListeners.get(channel);
+    if (busSet) for (const cb of busSet) callBus(cb, data, instanceId, name);
+    void adapter.publish(channel, serializer.encode({ t: "pub", c: name, d: data, i: instanceId }));
+  }
+  function callBus(cb, data, from, name) {
+    try {
+      cb(data, { from });
+    } catch (err) {
+      opts.onError?.(err, { kind: "event", name });
+    }
+  }
+  function deliverBus(payload, set) {
+    let frame;
+    try {
+      frame = serializer.decode(payload);
+    } catch {
+      return;
+    }
+    if (frame.i === instanceId) return;
+    const from = frame.i ?? "";
+    const name = frame.c;
+    const def = c.shared?.serverToClient?.[name];
+    const schema = def && typeof def === "object" && "payload" in def ? def.payload : void 0;
+    void (async () => {
+      let data = frame.d;
+      if (schema) {
+        try {
+          data = await validate(schema, frame.d);
+        } catch (err) {
+          opts.onError?.(err, { kind: "event", name });
+          return;
+        }
+      }
+      for (const cb of set) callBus(cb, data, from, name);
+    })();
+  }
+  function personalTarget(channel) {
+    return {
+      emit(event, data) {
+        if (inspectorEnabled)
+          emitInspectorEvent({
+            type: "msg.event",
+            target: channel.slice(channel.indexOf(":") + 1),
+            name: event,
+            data: safeSnapshot(data)
+          });
+        const env = { p: "emit", f: { t: "evt", e: event, d: data } };
+        void adapter.publish(channel, serializer.encode(env));
+      },
+      close() {
+        void adapter.publish(channel, serializer.encode({ p: "close" }));
+      }
+    };
+  }
+  function requestConn(id, name, input, opts2) {
+    const reqId = nextSReq++;
+    return new Promise((resolve, reject) => {
+      const ms = opts2?.timeout ?? 3e4;
+      const timer = ms > 0 ? setTimeout(() => {
+        originWaiters.delete(reqId);
+        reject(new SuperLineError("TIMEOUT", `Request '${name}' timed out`));
+      }, ms) : void 0;
+      originWaiters.set(reqId, { resolve, reject, timer });
+      opts2?.signal?.addEventListener(
+        "abort",
+        () => {
+          if (originWaiters.delete(reqId)) {
+            if (timer) clearTimeout(timer);
+            reject(new SuperLineError("BAD_REQUEST", "Aborted"));
+          }
+        },
+        { once: true }
+      );
+      if (inspectorEnabled)
+        emitInspectorEvent({ type: "msg.serverRequest", target: id, name, input: safeSnapshot(input) });
+      const env = { p: "req", o: instanceId, i: reqId, m: name, d: input };
+      void adapter.publish(CONN + id, serializer.encode(env));
+    });
   }
   const api = {
+    nodeId: instanceId,
+    nodeName,
+    get local() {
+      return {
+        connections: [...conns],
+        get rooms() {
+          return localRooms();
+        },
+        get topics() {
+          return localTopics();
+        }
+      };
+    },
+    cluster: {
+      async connections() {
+        return presenceOrThrow().list();
+      },
+      async count() {
+        return presenceOrThrow().count();
+      },
+      async byUser(userId) {
+        return presenceOrThrow().byUser(userId);
+      },
+      async room(name) {
+        return presenceOrThrow().roomMembers(name);
+      },
+      async topology() {
+        return presenceOrThrow().topology();
+      }
+    },
+    async isOnline(userId) {
+      return (await presenceOrThrow().byUser(userId)).length > 0;
+    },
+    toConn(id) {
+      const t = personalTarget(CONN + id);
+      return {
+        emit: t.emit,
+        close: t.close,
+        request: (name, input, opts2) => requestConn(id, String(name), input, opts2)
+      };
+    },
+    toUser(userId) {
+      const t = personalTarget(USER + userId);
+      return { emit: t.emit, disconnect: t.close };
+    },
     implement(handlers) {
       impl = handlers;
       return api;
@@ -280,33 +834,40 @@ function createSocketServer(contract, opts) {
     publish(topic, data) {
       publishTo("shared", String(topic), data);
     },
-    forRole(role) {
-      return {
-        publish(topic, data) {
-          publishTo(role, String(topic), data);
-        }
-      };
-    },
-    emitServer(event, data) {
-      void adapter.publish(S2S, serializer.encode({ from: instanceId, e: String(event), d: data }));
-    },
-    onServer(event, handler) {
-      const name = String(event);
-      let set = serverListeners.get(name);
+    subscribe(topic, handler) {
+      const channel = TOPIC + "shared:" + String(topic);
+      let set = busListeners.get(channel);
       if (!set) {
         set = /* @__PURE__ */ new Set();
-        serverListeners.set(name, set);
+        busListeners.set(channel, set);
+        if (!members.has(channel)) void adapter.subscribe(channel);
       }
-      set.add(handler);
+      const cb = handler;
+      set.add(cb);
       return () => {
-        const current = serverListeners.get(name);
+        const current = busListeners.get(channel);
         if (!current) return;
-        current.delete(handler);
-        if (current.size === 0) serverListeners.delete(name);
+        current.delete(cb);
+        if (current.size === 0) {
+          busListeners.delete(channel);
+          if (!members.has(channel)) void adapter.unsubscribe(channel);
+        }
+      };
+    },
+    forRole(role) {
+      return {
+        publish(topic, data) {
+          publishTo(role, String(topic), data);
+        }
       };
     },
     async close() {
+      if (closing) return;
+      closing = true;
+      if (hbTimer) clearInterval(hbTimer);
       for (const conn of conns) conn.close();
+      for (const conn of inspectorConns) conn.close();
+      await adapter.presence?.clearNode(instanceId);
       await adapter.close?.();
       await new Promise((resolve) => {
         wss.close(() => resolve());
@@ -324,5 +885,5 @@ export {
   Conn,
   MemoryBus,
   createInMemoryAdapter,
-  createSocketServer
+  createSuperLineServer
 };