@super-line/server 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -32,26 +32,51 @@ var import_core = require("@super-line/core");
 
 // src/conn.ts
 var Conn = class {
-  constructor(ws, role, ctx, serializer) {
+  constructor(ws, id, role, ctx, serializer, backpressure) {
     this.ws = ws;
+    this.id = id;
     this.role = role;
     this.ctx = ctx;
     this.serializer = serializer;
+    this.backpressure = backpressure;
   }
   ws;
+  id;
   role;
   ctx;
   serializer;
+  backpressure;
   /** 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. */
@@ -67,6 +92,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) {
@@ -87,12 +114,68 @@ 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,
+      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);
   }
@@ -116,6 +199,9 @@ function createInMemoryAdapter(bus = new MemoryBus()) {
 // src/index.ts
 var ROOM = "r:";
 var TOPIC = "t:";
+var CONN = "c:";
+var USER = "u:";
+var REPLY = "reply:";
 var S2S = "s2s";
 function createSocketServer(contract, opts) {
   const c = contract;
@@ -126,17 +212,122 @@ function createSocketServer(contract, opts) {
   const members = /* @__PURE__ */ new Map();
   const serverListeners = /* @__PURE__ */ new Map();
   const instanceId = (0, import_node_crypto.randomUUID)();
+  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,
+      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);
       return;
     }
+    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);
   });
+  void adapter.subscribe(replyChannel);
+  function handlePersonal(channel, payload) {
+    const set = members.get(channel);
+    if (!set) return;
+    let env;
+    try {
+      env = serializer.decode(payload);
+    } catch {
+      return;
+    }
+    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 import_core.SocketError(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 (0, import_core.validate)(def.output, result.d) : result.d;
+        env = { i: r.corrId, ok: true, d: out };
+      } catch (err) {
+        const e = err instanceof import_core.SocketError ? err : new import_core.SocketError("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 };
+    }
+    void adapter.publish(REPLY + r.origin, serializer.encode(env));
+  }
   if (c.serverToServer) void adapter.subscribe(S2S);
+  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 handleServerMessage(payload) {
     let msg;
     try {
@@ -150,6 +341,7 @@ function createSocketServer(contract, opts) {
   }
   function joinChannel(conn, channel) {
     conn.channels.add(channel);
+    if (channel.startsWith(ROOM)) void adapter.presence?.addRoom(conn.id, channel.slice(ROOM.length));
     const set = members.get(channel);
     if (set) {
       set.add(conn);
@@ -163,14 +355,19 @@ function createSocketServer(contract, opts) {
     if (!set) return;
     set.delete(conn);
     conn.channels.delete(channel);
+    if (channel.startsWith(ROOM)) void adapter.presence?.removeRoom(conn.id, channel.slice(ROOM.length));
     if (set.size === 0) {
       members.delete(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;
   }
   if (opts.server) {
@@ -192,17 +389,26 @@ function createSocketServer(contract, opts) {
       return;
     }
     wss.handleUpgrade(req, socket, head, (ws) => {
-      const conn = new Conn(ws, auth.role, auth.ctx, serializer);
+      const conn = new Conn(ws, (0, import_node_crypto.randomUUID)(), auth.role, auth.ctx, serializer, opts.backpressure);
       conns.add(conn);
+      ws.on("pong", () => {
+        conn.lastPongAt = Date.now();
+        conn.missedPongs = 0;
+      });
       ws.on("message", (data, isBinary) => {
         void onMessage(conn, data, isBinary);
       });
       ws.on("close", (code) => {
         conns.delete(conn);
         for (const channel of conn.channels) leaveChannel(conn, channel);
+        void adapter.presence?.del(conn.id);
         opts.onDisconnect?.(conn, auth.ctx, code);
       });
       opts.onConnection?.(conn, auth.ctx);
+      void adapter.presence?.set(buildDescriptor(conn));
+      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) {
@@ -217,6 +423,10 @@ function createSocketServer(contract, opts) {
     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) {
@@ -288,13 +498,101 @@ function createSocketServer(contract, opts) {
       },
       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 }));
   }
+  function personalTarget(channel) {
+    return {
+      emit(event, 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 import_core.SocketError("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 import_core.SocketError("BAD_REQUEST", "Aborted"));
+          }
+        },
+        { once: true }
+      );
+      const env = { p: "req", o: instanceId, i: reqId, m: name, d: input };
+      void adapter.publish(CONN + id, serializer.encode(env));
+    });
+  }
   const api = {
+    nodeId: instanceId,
+    get local() {
+      return {
+        connections: [...conns],
+        get rooms() {
+          const out = [];
+          for (const channel of members.keys()) if (channel.startsWith(ROOM)) out.push(channel.slice(ROOM.length));
+          return out;
+        },
+        get topics() {
+          const out = [];
+          for (const channel of members.keys()) {
+            if (!channel.startsWith(TOPIC)) continue;
+            out.push(channel.slice(channel.indexOf(":", TOPIC.length) + 1));
+          }
+          return out;
+        }
+      };
+    },
+    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;
@@ -329,7 +627,11 @@ function createSocketServer(contract, opts) {
       };
     },
     async close() {
+      if (closing) return;
+      closing = true;
+      if (hbTimer) clearInterval(hbTimer);
       for (const conn of conns) conn.close();
+      await adapter.presence?.clearNode(instanceId);
       await adapter.close?.();
       await new Promise((resolve) => {
         wss.close(() => resolve());

package/dist/index.d.cts

@@ -1,7 +1,14 @@
 import { Server, IncomingMessage } from 'node:http';
-import { ServerMessageDef, Serializer, ServerFrame, EmitData, Adapter, Contract, RoleOf, SharedRequests, ServerInput, SharedEvents, Output, RoleRequests, Events, RoleTopics, SharedTopics, ServerEvents, ServerEmit, ServerData } from '@super-line/core';
+import { ServerMessageDef, Serializer, ServerFrame, EmitData, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, SharedRequests, ServerInput, AnyData, RoleRequests, Events, DataOf, RoleTopics, SharedTopics, ServerEvents, ServerEmit, ServerData } from '@super-line/core';
 import { WebSocket } from 'ws';
 
+/** Backpressure policy: what to do when a connection's send buffer grows too large. */
+interface Backpressure {
+    /** Buffer size (bytes) above which {@link Backpressure.onExceed} kicks in. */
+    maxBufferedBytes: number;
+    /** `'close'` (default) drops the connection with code 1013; `'drop'` skips the frame. */
+    onExceed?: 'close' | 'drop';
+}
 /**
  * A single client connection, passed to handlers as the third argument.
  *
@@ -10,23 +17,39 @@ import { WebSocket } from 'ws';
  * (use a per-user room instead). Generic over the events it may emit (scoped by
  * role), its `ctx`, and its `role`.
  */
-declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role extends string = string> {
+declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role extends string = string, Data = unknown> {
     /** The underlying `ws` socket. `conn.ws.terminate()` simulates a drop in tests. */
     readonly ws: WebSocket;
+    /** Server-assigned unique id for this connection (stable for its lifetime). */
+    readonly id: string;
     /** This connection's role (the literal resolved by `authenticate`). */
     readonly role: Role;
     /** The context `authenticate` returned for this connection. */
     readonly ctx: Ctx;
     private readonly serializer;
+    private readonly backpressure?;
     /** Namespaced channels (rooms + topics) this connection belongs to. */
     readonly channels: Set<string>;
+    /** Mutable per-connection scratch state, typed per role by the contract's `data` schema. */
+    data: Data;
+    /** When this connection was accepted (`Date.now()` at the upgrade). */
+    readonly connectedAt: number;
+    /** When the server last sent a heartbeat ping to this connection (managed by the server). */
+    lastPingAt?: number;
+    /** When a heartbeat pong was last received — liveness signal (managed by the server). */
+    lastPongAt?: number;
+    /** Pings sent since the last pong; drives reaping (managed by the server). */
+    missedPongs: number;
     constructor(
     /** The underlying `ws` socket. `conn.ws.terminate()` simulates a drop in tests. */
     ws: WebSocket, 
+    /** Server-assigned unique id for this connection (stable for its lifetime). */
+    id: string, 
     /** This connection's role (the literal resolved by `authenticate`). */
     role: Role, 
     /** The context `authenticate` returned for this connection. */
-    ctx: Ctx, serializer: Serializer);
+    ctx: Ctx, serializer: Serializer, backpressure?: Backpressure | undefined);
+    private overBackpressure;
     /** Encode and send a frame (unicast, e.g. req/res). */
     send(frame: ServerFrame): void;
     /** Forward an already-encoded frame (fan-out path; encoded once at the source). */
@@ -40,9 +63,12 @@ declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role ex
 /**
  * In-process pub/sub bus. Share one bus across multiple servers to simulate
  * multiple nodes in a test (each server gets its own adapter bound to the bus).
+ * The presence directory also lives here, so servers sharing a bus see the whole
+ * cluster (mirroring how Redis is shared in production).
  */
 declare class MemoryBus {
     private readonly channels;
+    readonly descriptors: Map<string, ConnDescriptor>;
     subscribe(channel: string, adapter: MemoryAdapter): void;
     unsubscribe(channel: string, adapter: MemoryAdapter): void;
     publish(channel: string, payload: string | Uint8Array): void;
@@ -50,6 +76,7 @@ declare class MemoryBus {
 declare class MemoryAdapter implements Adapter {
     private readonly bus;
     private handler?;
+    readonly presence: PresenceStore;
     constructor(bus: MemoryBus);
     subscribe(channel: string): void;
     unsubscribe(channel: string): void;
@@ -83,10 +110,10 @@ type CtxUnion<A> = A extends {
     ctx: infer X;
 } ? X : never;
 type RoleHandlers<C extends Contract, A, R extends RoleOf<C>> = {
-    [K in keyof RoleRequests<C, R>]: (input: ServerInput<RoleRequests<C, R>[K]>, ctx: CtxFor<A, R>, conn: Conn<Events<C, R>, CtxFor<A, R>, R>) => Awaitable<Output<RoleRequests<C, R>[K]>>;
+    [K in keyof RoleRequests<C, R>]: (input: ServerInput<RoleRequests<C, R>[K]>, ctx: CtxFor<A, R>, conn: Conn<Events<C, R>, CtxFor<A, R>, R, DataOf<C, R>>) => Awaitable<Output<RoleRequests<C, R>[K]>>;
 };
 type SharedHandlers<C extends Contract, A> = {
-    [K in keyof SharedRequests<C>]: (input: ServerInput<SharedRequests<C>[K]>, ctx: CtxUnion<A>, conn: Conn<SharedEvents<C>, CtxUnion<A>, RoleOf<C>>) => Awaitable<Output<SharedRequests<C>[K]>>;
+    [K in keyof SharedRequests<C>]: (input: ServerInput<SharedRequests<C>[K]>, ctx: CtxUnion<A>, conn: Conn<SharedEvents<C>, CtxUnion<A>, RoleOf<C>, AnyData<C>>) => Awaitable<Output<SharedRequests<C>[K]>>;
 };
 /**
  * The handler map passed to `implement`: one block per role plus an optional
@@ -125,6 +152,56 @@ interface Room<C extends Contract> {
     broadcast<E extends keyof SharedEvents<C>>(event: E, data: EmitData<SharedEvents<C>[E]>): void;
     /** Member count **on the current node** (membership is node-local). */
     readonly size: number;
+    /** Snapshot of this room's members **on the current node**. */
+    readonly connections: Conn[];
+}
+/** Synchronous, node-local introspection of the current server process. */
+interface LocalView {
+    /** Snapshot of all connections accepted on this node. */
+    readonly connections: Conn[];
+    /** Names of rooms with at least one member on this node. */
+    readonly rooms: string[];
+    /** Names of topics with at least one subscriber on this node. */
+    readonly topics: string[];
+}
+/**
+ * Asynchronous, cluster-wide introspection backed by the adapter's presence
+ * directory. Methods reject if the configured adapter has no presence support.
+ */
+interface ClusterView {
+    /** Every live connection across the cluster. */
+    connections(): Promise<ConnDescriptor[]>;
+    /** Total live connection count across the cluster. */
+    count(): Promise<number>;
+    /** Connections for a given user key (the `identify` hook). */
+    byUser(userId: string): Promise<ConnDescriptor[]>;
+    /** Connections that are members of `room`, across nodes. */
+    room(name: string): Promise<ConnDescriptor[]>;
+    /** Per-node aggregates (the other nodes and their counts). */
+    topology(): Promise<NodeStat[]>;
+}
+/** A single targeted connection, reachable on whatever node holds it. */
+interface ConnTarget<C extends Contract> {
+    /** Push a shared event to this connection (cross-node). */
+    emit<E extends keyof SharedEvents<C>>(event: E, data: EmitData<SharedEvents<C>[E]>): void;
+    /**
+     * Send a shared server→client request and await the client's typed reply
+     * (cross-node). Rejects with a `TIMEOUT` `SocketError` if no live node owns
+     * the connection or the client doesn't answer in time.
+     */
+    request<M extends keyof SharedServerRequests<C>>(name: M, input: ClientInput<SharedServerRequests<C>[M]>, opts?: {
+        timeout?: number;
+        signal?: AbortSignal;
+    }): Promise<Output<SharedServerRequests<C>[M]>>;
+    /** Close this connection (cross-node kick). */
+    close(): void;
+}
+/** All of a user's connections (0..N devices), reachable across nodes. */
+interface UserTarget<C extends Contract> {
+    /** Push a shared event to every one of the user's connections (cross-node). */
+    emit<E extends keyof SharedEvents<C>>(event: E, data: EmitData<SharedEvents<C>[E]>): void;
+    /** Disconnect every one of the user's connections (cross-node). */
+    disconnect(): void;
 }
 /** Lens for role-scoped server sends, returned by `srv.forRole(role)`. */
 interface RoleLens<C extends Contract, R extends RoleOf<C>> {
@@ -143,10 +220,26 @@ interface ServerOptions<C extends Contract, A extends AuthResult<C>> {
     path?: string;
     /** Runs at the HTTP upgrade. Return { role, ctx }, or throw to reject with 401. */
     authenticate: (req: IncomingMessage) => Awaitable<A>;
+    /** Stable user key for a connection (powers `cluster.byUser`, `isOnline`, and `toUser`). */
+    identify?: (conn: Conn) => string | undefined;
+    /** Extra fields merged into the connection's cluster descriptor (e.g. `{ plan }`). `ctx` is never auto-serialized. */
+    describeConn?: (conn: Conn) => Record<string, unknown>;
     /** Runs on each client subscribe. Return false or throw to deny. */
     authorizeSubscribe?: (topic: string, ctx: CtxUnion<A>, conn: Conn) => Awaitable<boolean | void>;
     /** Middleware chain run before req/subscribe handlers (rate-limit, authz, logging, metrics). */
     use?: Middleware<A>[];
+    /**
+     * Heartbeat: one timer pings every connection each `interval` ms (updating
+     * `conn.lastPingAt`/`lastPongAt`). Set `maxMissed` to terminate a connection
+     * that misses that many consecutive pongs. `false` disables it.
+     * Defaults to `{ interval: 30_000 }` (no reaping).
+     */
+    heartbeat?: {
+        interval?: number;
+        maxMissed?: number;
+    } | false;
+    /** Guard against slow consumers: when a connection's send buffer exceeds the limit, close or drop. */
+    backpressure?: Backpressure;
     /** Called once per accepted connection. */
     onConnection?: (conn: Conn, ctx: CtxUnion<A>) => void;
     /** Called when a connection closes, with the WebSocket close `code`. */
@@ -156,6 +249,18 @@ interface ServerOptions<C extends Contract, A extends AuthResult<C>> {
 }
 /** A running super-line server, returned by {@link createSocketServer}. */
 interface SocketServer<C extends Contract, A extends AuthResult<C>> {
+    /** This node's stable id (unique per server process). */
+    readonly nodeId: string;
+    /** Synchronous, node-local introspection (connections, rooms, topics on this process). */
+    readonly local: LocalView;
+    /** Asynchronous, cluster-wide introspection backed by the adapter's presence directory. */
+    readonly cluster: ClusterView;
+    /** Whether a user (by `identify` key) has at least one live connection anywhere. */
+    isOnline(userId: string): Promise<boolean>;
+    /** Target a single connection by id, on whatever node holds it (cross-node emit/close). */
+    toConn(id: string): ConnTarget<C>;
+    /** Target all of a user's connections (by `identify` key) across nodes (emit/disconnect). */
+    toUser(userId: string): UserTarget<C>;
     /** Register handlers for shared + per-role requests (chainable). */
     implement(handlers: Handlers<C, A>): SocketServer<C, A>;
     /** Mixed-role connection group; broadcast() sends a shared contract event to members. */
@@ -194,4 +299,4 @@ interface SocketServer<C extends Contract, A extends AuthResult<C>> {
  */
 declare function createSocketServer<C extends Contract, A extends AuthResult<C>>(contract: C, opts: ServerOptions<C, A>): SocketServer<C, A>;
 
-export { type AuthResult, Conn, type Handlers, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type ServerOptions, type SocketServer, createInMemoryAdapter, createSocketServer };
+export { type AuthResult, type Backpressure, type ClusterView, Conn, type ConnTarget, type Handlers, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type ServerOptions, type SocketServer, type UserTarget, createInMemoryAdapter, createSocketServer };

package/dist/index.d.ts

@@ -1,7 +1,14 @@
 import { Server, IncomingMessage } from 'node:http';
-import { ServerMessageDef, Serializer, ServerFrame, EmitData, Adapter, Contract, RoleOf, SharedRequests, ServerInput, SharedEvents, Output, RoleRequests, Events, RoleTopics, SharedTopics, ServerEvents, ServerEmit, ServerData } from '@super-line/core';
+import { ServerMessageDef, Serializer, ServerFrame, EmitData, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, SharedRequests, ServerInput, AnyData, RoleRequests, Events, DataOf, RoleTopics, SharedTopics, ServerEvents, ServerEmit, ServerData } from '@super-line/core';
 import { WebSocket } from 'ws';
 
+/** Backpressure policy: what to do when a connection's send buffer grows too large. */
+interface Backpressure {
+    /** Buffer size (bytes) above which {@link Backpressure.onExceed} kicks in. */
+    maxBufferedBytes: number;
+    /** `'close'` (default) drops the connection with code 1013; `'drop'` skips the frame. */
+    onExceed?: 'close' | 'drop';
+}
 /**
  * A single client connection, passed to handlers as the third argument.
  *
@@ -10,23 +17,39 @@ import { WebSocket } from 'ws';
  * (use a per-user room instead). Generic over the events it may emit (scoped by
  * role), its `ctx`, and its `role`.
  */
-declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role extends string = string> {
+declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role extends string = string, Data = unknown> {
     /** The underlying `ws` socket. `conn.ws.terminate()` simulates a drop in tests. */
     readonly ws: WebSocket;
+    /** Server-assigned unique id for this connection (stable for its lifetime). */
+    readonly id: string;
     /** This connection's role (the literal resolved by `authenticate`). */
     readonly role: Role;
     /** The context `authenticate` returned for this connection. */
     readonly ctx: Ctx;
     private readonly serializer;
+    private readonly backpressure?;
     /** Namespaced channels (rooms + topics) this connection belongs to. */
     readonly channels: Set<string>;
+    /** Mutable per-connection scratch state, typed per role by the contract's `data` schema. */
+    data: Data;
+    /** When this connection was accepted (`Date.now()` at the upgrade). */
+    readonly connectedAt: number;
+    /** When the server last sent a heartbeat ping to this connection (managed by the server). */
+    lastPingAt?: number;
+    /** When a heartbeat pong was last received — liveness signal (managed by the server). */
+    lastPongAt?: number;
+    /** Pings sent since the last pong; drives reaping (managed by the server). */
+    missedPongs: number;
     constructor(
     /** The underlying `ws` socket. `conn.ws.terminate()` simulates a drop in tests. */
     ws: WebSocket, 
+    /** Server-assigned unique id for this connection (stable for its lifetime). */
+    id: string, 
     /** This connection's role (the literal resolved by `authenticate`). */
     role: Role, 
     /** The context `authenticate` returned for this connection. */
-    ctx: Ctx, serializer: Serializer);
+    ctx: Ctx, serializer: Serializer, backpressure?: Backpressure | undefined);
+    private overBackpressure;
     /** Encode and send a frame (unicast, e.g. req/res). */
     send(frame: ServerFrame): void;
     /** Forward an already-encoded frame (fan-out path; encoded once at the source). */
@@ -40,9 +63,12 @@ declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role ex
 /**
  * In-process pub/sub bus. Share one bus across multiple servers to simulate
  * multiple nodes in a test (each server gets its own adapter bound to the bus).
+ * The presence directory also lives here, so servers sharing a bus see the whole
+ * cluster (mirroring how Redis is shared in production).
  */
 declare class MemoryBus {
     private readonly channels;
+    readonly descriptors: Map<string, ConnDescriptor>;
     subscribe(channel: string, adapter: MemoryAdapter): void;
     unsubscribe(channel: string, adapter: MemoryAdapter): void;
     publish(channel: string, payload: string | Uint8Array): void;
@@ -50,6 +76,7 @@ declare class MemoryBus {
 declare class MemoryAdapter implements Adapter {
     private readonly bus;
     private handler?;
+    readonly presence: PresenceStore;
     constructor(bus: MemoryBus);
     subscribe(channel: string): void;
     unsubscribe(channel: string): void;
@@ -83,10 +110,10 @@ type CtxUnion<A> = A extends {
     ctx: infer X;
 } ? X : never;
 type RoleHandlers<C extends Contract, A, R extends RoleOf<C>> = {
-    [K in keyof RoleRequests<C, R>]: (input: ServerInput<RoleRequests<C, R>[K]>, ctx: CtxFor<A, R>, conn: Conn<Events<C, R>, CtxFor<A, R>, R>) => Awaitable<Output<RoleRequests<C, R>[K]>>;
+    [K in keyof RoleRequests<C, R>]: (input: ServerInput<RoleRequests<C, R>[K]>, ctx: CtxFor<A, R>, conn: Conn<Events<C, R>, CtxFor<A, R>, R, DataOf<C, R>>) => Awaitable<Output<RoleRequests<C, R>[K]>>;
 };
 type SharedHandlers<C extends Contract, A> = {
-    [K in keyof SharedRequests<C>]: (input: ServerInput<SharedRequests<C>[K]>, ctx: CtxUnion<A>, conn: Conn<SharedEvents<C>, CtxUnion<A>, RoleOf<C>>) => Awaitable<Output<SharedRequests<C>[K]>>;
+    [K in keyof SharedRequests<C>]: (input: ServerInput<SharedRequests<C>[K]>, ctx: CtxUnion<A>, conn: Conn<SharedEvents<C>, CtxUnion<A>, RoleOf<C>, AnyData<C>>) => Awaitable<Output<SharedRequests<C>[K]>>;
 };
 /**
  * The handler map passed to `implement`: one block per role plus an optional
@@ -125,6 +152,56 @@ interface Room<C extends Contract> {
     broadcast<E extends keyof SharedEvents<C>>(event: E, data: EmitData<SharedEvents<C>[E]>): void;
     /** Member count **on the current node** (membership is node-local). */
     readonly size: number;
+    /** Snapshot of this room's members **on the current node**. */
+    readonly connections: Conn[];
+}
+/** Synchronous, node-local introspection of the current server process. */
+interface LocalView {
+    /** Snapshot of all connections accepted on this node. */
+    readonly connections: Conn[];
+    /** Names of rooms with at least one member on this node. */
+    readonly rooms: string[];
+    /** Names of topics with at least one subscriber on this node. */
+    readonly topics: string[];
+}
+/**
+ * Asynchronous, cluster-wide introspection backed by the adapter's presence
+ * directory. Methods reject if the configured adapter has no presence support.
+ */
+interface ClusterView {
+    /** Every live connection across the cluster. */
+    connections(): Promise<ConnDescriptor[]>;
+    /** Total live connection count across the cluster. */
+    count(): Promise<number>;
+    /** Connections for a given user key (the `identify` hook). */
+    byUser(userId: string): Promise<ConnDescriptor[]>;
+    /** Connections that are members of `room`, across nodes. */
+    room(name: string): Promise<ConnDescriptor[]>;
+    /** Per-node aggregates (the other nodes and their counts). */
+    topology(): Promise<NodeStat[]>;
+}
+/** A single targeted connection, reachable on whatever node holds it. */
+interface ConnTarget<C extends Contract> {
+    /** Push a shared event to this connection (cross-node). */
+    emit<E extends keyof SharedEvents<C>>(event: E, data: EmitData<SharedEvents<C>[E]>): void;
+    /**
+     * Send a shared server→client request and await the client's typed reply
+     * (cross-node). Rejects with a `TIMEOUT` `SocketError` if no live node owns
+     * the connection or the client doesn't answer in time.
+     */
+    request<M extends keyof SharedServerRequests<C>>(name: M, input: ClientInput<SharedServerRequests<C>[M]>, opts?: {
+        timeout?: number;
+        signal?: AbortSignal;
+    }): Promise<Output<SharedServerRequests<C>[M]>>;
+    /** Close this connection (cross-node kick). */
+    close(): void;
+}
+/** All of a user's connections (0..N devices), reachable across nodes. */
+interface UserTarget<C extends Contract> {
+    /** Push a shared event to every one of the user's connections (cross-node). */
+    emit<E extends keyof SharedEvents<C>>(event: E, data: EmitData<SharedEvents<C>[E]>): void;
+    /** Disconnect every one of the user's connections (cross-node). */
+    disconnect(): void;
 }
 /** Lens for role-scoped server sends, returned by `srv.forRole(role)`. */
 interface RoleLens<C extends Contract, R extends RoleOf<C>> {
@@ -143,10 +220,26 @@ interface ServerOptions<C extends Contract, A extends AuthResult<C>> {
     path?: string;
     /** Runs at the HTTP upgrade. Return { role, ctx }, or throw to reject with 401. */
     authenticate: (req: IncomingMessage) => Awaitable<A>;
+    /** Stable user key for a connection (powers `cluster.byUser`, `isOnline`, and `toUser`). */
+    identify?: (conn: Conn) => string | undefined;
+    /** Extra fields merged into the connection's cluster descriptor (e.g. `{ plan }`). `ctx` is never auto-serialized. */
+    describeConn?: (conn: Conn) => Record<string, unknown>;
     /** Runs on each client subscribe. Return false or throw to deny. */
     authorizeSubscribe?: (topic: string, ctx: CtxUnion<A>, conn: Conn) => Awaitable<boolean | void>;
     /** Middleware chain run before req/subscribe handlers (rate-limit, authz, logging, metrics). */
     use?: Middleware<A>[];
+    /**
+     * Heartbeat: one timer pings every connection each `interval` ms (updating
+     * `conn.lastPingAt`/`lastPongAt`). Set `maxMissed` to terminate a connection
+     * that misses that many consecutive pongs. `false` disables it.
+     * Defaults to `{ interval: 30_000 }` (no reaping).
+     */
+    heartbeat?: {
+        interval?: number;
+        maxMissed?: number;
+    } | false;
+    /** Guard against slow consumers: when a connection's send buffer exceeds the limit, close or drop. */
+    backpressure?: Backpressure;
     /** Called once per accepted connection. */
     onConnection?: (conn: Conn, ctx: CtxUnion<A>) => void;
     /** Called when a connection closes, with the WebSocket close `code`. */
@@ -156,6 +249,18 @@ interface ServerOptions<C extends Contract, A extends AuthResult<C>> {
 }
 /** A running super-line server, returned by {@link createSocketServer}. */
 interface SocketServer<C extends Contract, A extends AuthResult<C>> {
+    /** This node's stable id (unique per server process). */
+    readonly nodeId: string;
+    /** Synchronous, node-local introspection (connections, rooms, topics on this process). */
+    readonly local: LocalView;
+    /** Asynchronous, cluster-wide introspection backed by the adapter's presence directory. */
+    readonly cluster: ClusterView;
+    /** Whether a user (by `identify` key) has at least one live connection anywhere. */
+    isOnline(userId: string): Promise<boolean>;
+    /** Target a single connection by id, on whatever node holds it (cross-node emit/close). */
+    toConn(id: string): ConnTarget<C>;
+    /** Target all of a user's connections (by `identify` key) across nodes (emit/disconnect). */
+    toUser(userId: string): UserTarget<C>;
     /** Register handlers for shared + per-role requests (chainable). */
     implement(handlers: Handlers<C, A>): SocketServer<C, A>;
     /** Mixed-role connection group; broadcast() sends a shared contract event to members. */
@@ -194,4 +299,4 @@ interface SocketServer<C extends Contract, A extends AuthResult<C>> {
  */
 declare function createSocketServer<C extends Contract, A extends AuthResult<C>>(contract: C, opts: ServerOptions<C, A>): SocketServer<C, A>;
 
-export { type AuthResult, Conn, type Handlers, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type ServerOptions, type SocketServer, createInMemoryAdapter, createSocketServer };
+export { type AuthResult, type Backpressure, type ClusterView, Conn, type ConnTarget, type Handlers, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type ServerOptions, type SocketServer, type UserTarget, createInMemoryAdapter, createSocketServer };

package/dist/index.js

@@ -9,26 +9,51 @@ import {
 
 // src/conn.ts
 var Conn = class {
-  constructor(ws, role, ctx, serializer) {
+  constructor(ws, id, role, ctx, serializer, backpressure) {
     this.ws = ws;
+    this.id = id;
     this.role = role;
     this.ctx = ctx;
     this.serializer = serializer;
+    this.backpressure = backpressure;
   }
   ws;
+  id;
   role;
   ctx;
   serializer;
+  backpressure;
   /** 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. */
@@ -44,6 +69,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 +91,68 @@ 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,
+      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,6 +176,9 @@ function createInMemoryAdapter(bus = new MemoryBus()) {
 // src/index.ts
 var ROOM = "r:";
 var TOPIC = "t:";
+var CONN = "c:";
+var USER = "u:";
+var REPLY = "reply:";
 var S2S = "s2s";
 function createSocketServer(contract, opts) {
   const c = contract;
@@ -103,17 +189,122 @@ function createSocketServer(contract, opts) {
   const members = /* @__PURE__ */ new Map();
   const serverListeners = /* @__PURE__ */ new Map();
   const instanceId = randomUUID();
+  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,
+      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);
       return;
     }
+    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);
   });
+  void adapter.subscribe(replyChannel);
+  function handlePersonal(channel, payload) {
+    const set = members.get(channel);
+    if (!set) return;
+    let env;
+    try {
+      env = serializer.decode(payload);
+    } catch {
+      return;
+    }
+    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 SocketError(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 SocketError ? err : new SocketError("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 };
+    }
+    void adapter.publish(REPLY + r.origin, serializer.encode(env));
+  }
   if (c.serverToServer) void adapter.subscribe(S2S);
+  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 handleServerMessage(payload) {
     let msg;
     try {
@@ -127,6 +318,7 @@ function createSocketServer(contract, opts) {
   }
   function joinChannel(conn, channel) {
     conn.channels.add(channel);
+    if (channel.startsWith(ROOM)) void adapter.presence?.addRoom(conn.id, channel.slice(ROOM.length));
     const set = members.get(channel);
     if (set) {
       set.add(conn);
@@ -140,14 +332,19 @@ function createSocketServer(contract, opts) {
     if (!set) return;
     set.delete(conn);
     conn.channels.delete(channel);
+    if (channel.startsWith(ROOM)) void adapter.presence?.removeRoom(conn.id, channel.slice(ROOM.length));
     if (set.size === 0) {
       members.delete(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;
   }
   if (opts.server) {
@@ -169,17 +366,26 @@ function createSocketServer(contract, opts) {
       return;
     }
     wss.handleUpgrade(req, socket, head, (ws) => {
-      const conn = new Conn(ws, auth.role, auth.ctx, serializer);
+      const conn = new Conn(ws, randomUUID(), auth.role, auth.ctx, serializer, opts.backpressure);
       conns.add(conn);
+      ws.on("pong", () => {
+        conn.lastPongAt = Date.now();
+        conn.missedPongs = 0;
+      });
       ws.on("message", (data, isBinary) => {
         void onMessage(conn, data, isBinary);
       });
       ws.on("close", (code) => {
         conns.delete(conn);
         for (const channel of conn.channels) leaveChannel(conn, channel);
+        void adapter.presence?.del(conn.id);
         opts.onDisconnect?.(conn, auth.ctx, code);
       });
       opts.onConnection?.(conn, auth.ctx);
+      void adapter.presence?.set(buildDescriptor(conn));
+      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) {
@@ -194,6 +400,10 @@ function createSocketServer(contract, opts) {
     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) {
@@ -265,13 +475,101 @@ function createSocketServer(contract, opts) {
       },
       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 }));
   }
+  function personalTarget(channel) {
+    return {
+      emit(event, 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 SocketError("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 SocketError("BAD_REQUEST", "Aborted"));
+          }
+        },
+        { once: true }
+      );
+      const env = { p: "req", o: instanceId, i: reqId, m: name, d: input };
+      void adapter.publish(CONN + id, serializer.encode(env));
+    });
+  }
   const api = {
+    nodeId: instanceId,
+    get local() {
+      return {
+        connections: [...conns],
+        get rooms() {
+          const out = [];
+          for (const channel of members.keys()) if (channel.startsWith(ROOM)) out.push(channel.slice(ROOM.length));
+          return out;
+        },
+        get topics() {
+          const out = [];
+          for (const channel of members.keys()) {
+            if (!channel.startsWith(TOPIC)) continue;
+            out.push(channel.slice(channel.indexOf(":", TOPIC.length) + 1));
+          }
+          return out;
+        }
+      };
+    },
+    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;
@@ -306,7 +604,11 @@ function createSocketServer(contract, opts) {
       };
     },
     async close() {
+      if (closing) return;
+      closing = true;
+      if (hbTimer) clearInterval(hbTimer);
       for (const conn of conns) conn.close();
+      await adapter.presence?.clearNode(instanceId);
       await adapter.close?.();
       await new Promise((resolve) => {
         wss.close(() => resolve());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super-line/server",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Typesafe WebSocket server for super-line — rooms, topics, middleware, pluggable adapters.",
   "license": "MIT",
@@ -48,14 +48,15 @@
   },
   "dependencies": {
     "ws": "^8.18.0",
-    "@super-line/core": "^0.1.0"
+    "@super-line/core": "^0.2.0"
   },
   "devDependencies": {
     "@types/ws": "^8.5.13",
+    "ioredis": "^5.4.2",
     "testcontainers": "^10.13.2",
     "zod": "^3.24.1",
-    "@super-line/adapter-redis": "0.1.0",
-    "@super-line/client": "0.1.0"
+    "@super-line/adapter-redis": "0.2.0",
+    "@super-line/client": "0.2.0"
   },
   "scripts": {
     "build": "tsup"