@super-line/server 0.9.0 → 0.10.1

package/dist/index.js

@@ -1,13 +1,8 @@
-import "./chunk-MLKGABMK.js";
-
 // src/index.ts
 import {
   jsonSerializer,
   validate,
-  SuperLineError,
-  INSPECTOR_ROLE,
-  classifyContract,
-  eventPayload
+  SuperLineError
 } from "@super-line/core";
 
 // src/conn.ts
@@ -185,26 +180,82 @@ var TOPIC = "t:";
 var CONN = "c:";
 var USER = "u:";
 var REPLY = "reply:";
-var INSPECT = "i:";
-var inspectorEncoder = new TextEncoder();
-function encodedByteSize(encoded) {
-  return typeof encoded === "string" ? inspectorEncoder.encode(encoded).length : encoded.byteLength;
-}
+var PLUGIN = "x:";
 var STORE = "s:";
 var SERVER_ORIGIN = "server";
 function createSuperLineServer(contract, opts) {
   const c = contract;
   const serializer = opts.serializer ?? jsonSerializer;
   const adapter = opts.adapter ?? createInMemoryAdapter();
-  const inspectorEnabled = !!opts.inspector;
-  const inspectorRedact = new Set(
-    opts.inspector && typeof opts.inspector === "object" ? opts.inspector.redact ?? [] : []
-  );
   const storeMap = opts.stores ?? {};
+  const plugins = opts.plugins ?? [];
+  const pluginNames = /* @__PURE__ */ new Set();
+  for (const p of plugins) {
+    if (pluginNames.has(p.name)) throw new Error(`Duplicate plugin name: ${p.name}`);
+    pluginNames.add(p.name);
+  }
+  for (const p of plugins) {
+    if (!p.stores) continue;
+    for (const [name, store] of Object.entries(p.stores)) {
+      if (name in storeMap)
+        throw new Error(`Plugin '${p.name}' store '${name}' collides with an existing store of that name`);
+      storeMap[name] = store;
+    }
+  }
+  const reserved = [];
+  for (const p of plugins) {
+    if (!p.connection) continue;
+    const { role, subprotocol, match } = p.connection;
+    if (reserved.some((r) => r.role === role) || role in c.roles)
+      throw new Error(`Plugin '${p.name}' reserved role '${role}' collides with an existing role`);
+    reserved.push({ role, subprotocol, match });
+  }
+  const reservedRoles = new Set(reserved.map((r) => r.role));
+  const reservedServing = /* @__PURE__ */ new Map();
+  const errorHandlers = [];
+  if (opts.onError) errorHandlers.push(opts.onError);
+  for (const p of plugins) if (p.onError) errorHandlers.push(p.onError);
+  function fireError(error, info) {
+    for (const handler of errorHandlers) {
+      try {
+        handler(error, info);
+      } catch {
+      }
+    }
+  }
+  const connectionHooks = [];
+  if (opts.onConnection) connectionHooks.push(opts.onConnection);
+  for (const p of plugins) if (p.onConnection) connectionHooks.push(p.onConnection);
+  function fireConnection(conn, ctx) {
+    for (const handler of connectionHooks) {
+      try {
+        handler(conn, ctx);
+      } catch (err) {
+        fireError(err, { kind: "connect", name: "onConnection", conn });
+      }
+    }
+  }
+  const disconnectHooks = [];
+  if (opts.onDisconnect) disconnectHooks.push(opts.onDisconnect);
+  for (const p of plugins) if (p.onDisconnect) disconnectHooks.push(p.onDisconnect);
+  function fireDisconnect(conn, ctx, code) {
+    for (const handler of disconnectHooks) {
+      try {
+        handler(conn, ctx, code);
+      } catch (err) {
+        fireError(err, { kind: "disconnect", name: "onDisconnect", conn });
+      }
+    }
+  }
+  const middlewareChain = [
+    ...opts.use ?? [],
+    ...plugins.flatMap((p) => p.use ?? [])
+  ];
   const conns = /* @__PURE__ */ new Set();
-  const inspectorConns = /* @__PURE__ */ new Set();
+  const reservedConns = /* @__PURE__ */ new Set();
   const members = /* @__PURE__ */ new Map();
   const busListeners = /* @__PURE__ */ new Map();
+  const pluginChannels = /* @__PURE__ */ new Map();
   const instanceId = randomUUID();
   const envNodeName = typeof process !== "undefined" ? process.env.SUPER_LINE_NODE_NAME : void 0;
   const nodeName = opts.nodeName ?? envNodeName ?? instanceId.slice(0, 8);
@@ -248,6 +299,10 @@ function createSuperLineServer(contract, opts) {
       handleStoreRelay(channel, payload);
       return;
     }
+    if (channel.startsWith(PLUGIN)) {
+      handlePluginChannel(channel, payload);
+      return;
+    }
     const set = members.get(channel);
     if (set) for (const conn of set) conn.sendRaw(payload);
     const busSet = busListeners.get(channel);
@@ -307,9 +362,9 @@ function createSuperLineServer(contract, opts) {
     } 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), reqId: r.corrId } : {
+    if (taps.length)
+      emitTap(
+        env.ok ? { type: "msg.serverReply", target: conn.id, name: r.name, ok: true, output: env.d, reqId: r.corrId } : {
           type: "msg.serverReply",
           target: conn.id,
           name: r.name,
@@ -338,25 +393,26 @@ function createSuperLineServer(contract, opts) {
     }, hb.interval ?? 3e4);
     hbTimer.unref?.();
   }
-  function emitInspectorEvent(event) {
-    if (!inspectorEnabled) return;
-    const payload = eventPayload(event);
-    const envelope = {
-      event,
-      ts: Date.now(),
-      originNodeId: instanceId,
-      byteSize: payload === void 0 ? void 0 : encodedByteSize(serializer.encode(payload))
-    };
-    void adapter.publish(INSPECT + "events", serializer.encode({ t: "pub", c: "events", d: envelope }));
+  const taps = [];
+  function emitTap(event) {
+    if (!taps.length) return;
+    for (const tap of taps) {
+      try {
+        tap(event);
+      } catch (err) {
+        fireError(err, { kind: "event", name: event.type });
+      }
+    }
   }
+  for (const p of plugins) if (p.onEvent) taps.push(p.onEvent);
   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 });
+      emitTap({ 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) });
+      emitTap({ type: "topic.sub", connId: conn.id, topic: channel.slice(channel.indexOf(":", TOPIC.length) + 1) });
     }
     const set = members.get(channel);
     if (set) {
@@ -375,9 +431,9 @@ function createSuperLineServer(contract, opts) {
     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 });
+      emitTap({ 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) });
+      emitTap({ type: "topic.unsub", connId: conn.id, topic: channel.slice(channel.indexOf(":", TOPIC.length) + 1) });
     }
     if (set.size === 0) {
       members.delete(channel);
@@ -406,128 +462,47 @@ function createSuperLineServer(contract, opts) {
     }
     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);
+  const reservedBridges = /* @__PURE__ */ new WeakMap();
+  async function onReservedFrame(conn, frame) {
+    const serving = reservedServing.get(conn.role);
+    if (!serving) return;
+    if (frame.t === "req") {
+      const handler = serving.handlers[frame.m];
+      if (!handler) {
+        conn.send({ t: "err", i: frame.i, code: "NOT_FOUND", m: `Unknown message: ${frame.m}` });
+        return;
       }
-      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
-        };
+      try {
+        conn.send({ t: "res", i: frame.i, d: await handler(frame.d, conn) });
+      } 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 });
       }
-      const remote = await presenceOrThrow().get(id);
-      if (!remote) throw new SuperLineError("NOT_FOUND", `Unknown connection: ${id}`);
-      return { descriptor: remote, ctxAvailable: false };
-    },
-    listStores: async () => Object.entries(storeMap).map(([name, store]) => ({ name, model: store.model })),
-    listResources: async (input) => {
-      const store = storeMap[input.store];
-      if (!store) throw new SuperLineError("NOT_FOUND", `Unknown store: ${input.store}`);
-      return store.list();
-    },
-    readResource: async (input) => {
-      const { store: name, id } = input;
-      const store = storeMap[name];
-      if (!store) throw new SuperLineError("NOT_FOUND", `Unknown store: ${name}`);
-      const resource = await store.read(id);
-      if (!resource) throw new SuperLineError("NOT_FOUND", `No resource: ${name}/${id}`);
-      let data = resource.data;
-      if (store.open) {
-        const replica = store.open(id);
-        data = replica.getSnapshot();
-        replica.close();
+    } else if (frame.t === "sub") {
+      if (!isSubscribeTopic(serving.connection.contract, frame.c)) {
+        conn.send({ t: "err", i: frame.i, code: "NOT_FOUND", m: `Unknown topic: ${frame.c}` });
+        return;
       }
-      return { data: safeSnapshot(data), accessRules: resource.accessRules };
+      let bridges = reservedBridges.get(conn);
+      if (!bridges) {
+        bridges = /* @__PURE__ */ new Map();
+        reservedBridges.set(conn, bridges);
+      }
+      bridges.get(frame.c)?.();
+      bridges.set(frame.c, serving.ctx.channel(frame.c).subscribe((data) => conn.send({ t: "pub", c: frame.c, d: data })));
+      conn.send({ t: "res", i: frame.i, d: null });
+    } else if (frame.t === "unsub") {
+      const bridges = reservedBridges.get(conn);
+      bridges?.get(frame.c)?.();
+      bridges?.delete(frame.c);
     }
-  };
+  }
+  function isSubscribeTopic(contract2, name) {
+    const isTopicDef = (def) => !!def && typeof def === "object" && "subscribe" in def && def.subscribe === true;
+    if (isTopicDef(contract2.shared?.serverToClient?.[name])) return true;
+    for (const role of Object.keys(contract2.roles)) if (isTopicDef(contract2.roles[role]?.serverToClient?.[name])) return true;
+    return false;
+  }
   const authHook = async (handshake) => {
     const auth = await opts.authenticate(handshake);
     return { role: auth.role, ctx: auth.ctx, transport: handshake.transport };
@@ -535,11 +510,7 @@ function createSuperLineServer(contract, opts) {
   function acceptConn(raw, auth) {
     const role = auth.role;
     const ctx = auth.ctx;
-    const inspector = role === INSPECTOR_ROLE;
-    if (inspector && !inspectorEnabled) {
-      raw.close();
-      return;
-    }
+    const isReserved = reservedRoles.has(role);
     const connId = randomUUID();
     const conn = new Conn(
       raw,
@@ -547,17 +518,22 @@ function createSuperLineServer(contract, opts) {
       role,
       ctx,
       serializer,
-      inspectorEnabled ? (event, data) => emitInspectorEvent({ type: "msg.event", target: connId, name: event, data: safeSnapshot(data) }) : void 0
+      taps.length ? (event, data) => emitTap({ type: "msg.event", target: connId, name: event, data }) : void 0
     );
     conn.transport = auth.transport;
     conn.principal = resolvePrincipal(conn, opts.identify);
     raw.onMessage((bytes) => {
       void onMessage(conn, bytes);
     });
-    if (inspector) {
-      inspectorConns.add(conn);
+    if (isReserved) {
+      reservedConns.add(conn);
       raw.onClose(() => {
-        inspectorConns.delete(conn);
+        reservedConns.delete(conn);
+        const bridges = reservedBridges.get(conn);
+        if (bridges) {
+          for (const off of bridges.values()) off();
+          reservedBridges.delete(conn);
+        }
         for (const channel of conn.channels) leaveChannel(conn, channel);
       });
       return;
@@ -568,18 +544,18 @@ function createSuperLineServer(contract, opts) {
       for (const channel of conn.channels) leaveChannel(conn, channel);
       void adapter.presence?.del(conn.id);
       const goneUserId = opts.identify?.(conn);
-      emitInspectorEvent({
+      emitTap({
         type: "disconnect",
         connId: conn.id,
         nodeId: instanceId,
         ...goneUserId !== void 0 ? { userId: goneUserId } : {}
       });
-      opts.onDisconnect?.(conn, ctx, code);
+      fireDisconnect(conn, ctx, code);
     });
-    opts.onConnection?.(conn, ctx);
+    fireConnection(conn, ctx);
     const descriptor = buildDescriptor(conn);
     void adapter.presence?.set(descriptor);
-    emitInspectorEvent({ type: "connect", descriptor });
+    emitTap({ type: "connect", descriptor });
     void joinChannel(conn, CONN + conn.id);
     const uid = opts.identify?.(conn);
     if (uid !== void 0) void joinChannel(conn, USER + uid);
@@ -591,8 +567,8 @@ function createSuperLineServer(contract, opts) {
     } catch {
       return;
     }
-    if (inspectorConns.has(conn)) {
-      await onInspectorFrame(conn, frame);
+    if (reservedConns.has(conn)) {
+      await onReservedFrame(conn, frame);
       return;
     }
     if (frame.t === "req") await handleReq(conn, frame);
@@ -614,10 +590,10 @@ function createSuperLineServer(contract, opts) {
     }
   }
   for (const transport of opts.transports) {
-    void transport.start({ authenticate: authHook, onConnection: acceptConn });
+    void transport.start({ authenticate: authHook, onConnection: acceptConn, reserved });
   }
   function runMiddleware(info, terminal) {
-    const chain = opts.use ?? [];
+    const chain = middlewareChain;
     let last = -1;
     const dispatch = (idx) => {
       if (idx <= last) return Promise.reject(new Error("next() called multiple times"));
@@ -636,11 +612,11 @@ function createSuperLineServer(contract, opts) {
         responded = true;
       });
     } catch (err) {
-      opts.onError?.(err, info);
+      fireError(err, info);
       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({
+      if (taps.length && info.kind === "request")
+        emitTap({
           type: "msg.response",
           connId: conn.id,
           name: info.name,
@@ -652,30 +628,30 @@ function createSuperLineServer(contract, opts) {
   }
   async function handleReq(conn, frame) {
     const def = c.roles[conn.role]?.clientToServer?.[frame.m] ?? c.shared?.clientToServer?.[frame.m];
-    const handler = impl[conn.role]?.[frame.m] ?? impl.shared?.[frame.m];
+    const handler = impl[conn.role]?.[frame.m] ?? impl.shared?.[frame.m] ?? pluginHandlers[frame.m];
     if (!def || !handler) {
       conn.send({ t: "err", i: frame.i, code: "NOT_FOUND", m: `Unknown message: ${frame.m}` });
       return;
     }
     await dispatchOp(conn, frame.i, { kind: "request", name: frame.m, conn }, async () => {
       const input = await validate(def.input, frame.d);
-      if (inspectorEnabled)
-        emitInspectorEvent({
+      if (taps.length)
+        emitTap({
           type: "msg.request",
           connId: conn.id,
           role: conn.role,
           name: frame.m,
-          input: safeSnapshot(input),
+          input,
           reqId: frame.i
         });
       const output = await handler(input, conn.ctx, conn);
-      if (inspectorEnabled)
-        emitInspectorEvent({
+      if (taps.length)
+        emitTap({
           type: "msg.response",
           connId: conn.id,
           name: frame.m,
           ok: true,
-          output: safeSnapshot(output),
+          output,
           reqId: frame.i
         });
       conn.send({ t: "res", i: frame.i, d: output });
@@ -711,7 +687,7 @@ function createSuperLineServer(contract, opts) {
       if (!resource.accessRules[principal]?.read)
         throw new SuperLineError("FORBIDDEN", `Read denied: ${frame.n}/${frame.id}`);
       await joinChannel(conn, STORE + frame.n + ":" + frame.id);
-      if (inspectorEnabled) emitInspectorEvent({ type: "store.subscribe", connId: conn.id, store: frame.n, id: frame.id });
+      if (taps.length) emitTap({ type: "store.subscribe", connId: conn.id, store: frame.n, id: frame.id });
       conn.send({ t: "res", i: frame.i, d: resource.data });
     });
   }
@@ -737,14 +713,14 @@ function createSuperLineServer(contract, opts) {
       if (!resource.accessRules[principal]?.write)
         throw new SuperLineError("FORBIDDEN", `Write denied: ${frame.n}/${frame.id}`);
       await store.apply({ id: frame.id, update: frame.u, origin: frame.o });
-      if (inspectorEnabled)
-        emitInspectorEvent({
+      if (taps.length)
+        emitTap({
           type: "store.write",
           store: frame.n,
           id: frame.id,
           origin: frame.o,
           connId: conn.id,
-          data: safeSnapshot(frame.u)
+          data: frame.u
         });
       conn.send({ t: "res", i: frame.i, d: null });
     });
@@ -752,7 +728,7 @@ function createSuperLineServer(contract, opts) {
   function handleStoreClose(conn, frame) {
     if (!storeMap[frame.n]) return;
     leaveChannel(conn, STORE + frame.n + ":" + frame.id);
-    if (inspectorEnabled) emitInspectorEvent({ type: "store.unsubscribe", connId: conn.id, store: frame.n, id: frame.id });
+    if (taps.length) emitTap({ type: "store.unsubscribe", connId: conn.id, store: frame.n, id: frame.id });
   }
   for (const [name, store] of Object.entries(storeMap)) {
     const isSelf = store.clustering === "self";
@@ -813,8 +789,8 @@ function createSuperLineServer(contract, opts) {
         leaveChannel(conn, channel);
       },
       broadcast(event, data) {
-        if (inspectorEnabled)
-          emitInspectorEvent({ type: "msg.broadcast", room: name, name: String(event), data: safeSnapshot(data) });
+        if (taps.length)
+          emitTap({ type: "msg.broadcast", room: name, name: String(event), data });
         void adapter.publish(channel, serializer.encode({ t: "evt", e: String(event), d: data }));
       },
       get size() {
@@ -827,7 +803,7 @@ function createSuperLineServer(contract, opts) {
   }
   function publishTo(ns, name, data) {
     const channel = TOPIC + ns + ":" + name;
-    if (inspectorEnabled) emitInspectorEvent({ type: "msg.publish", topic: name, data: safeSnapshot(data) });
+    if (taps.length) emitTap({ type: "msg.publish", topic: name, 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 }));
@@ -836,7 +812,7 @@ function createSuperLineServer(contract, opts) {
     try {
       cb(data, { from });
     } catch (err) {
-      opts.onError?.(err, { kind: "event", name });
+      fireError(err, { kind: "event", name });
     }
   }
   function deliverBus(payload, set) {
@@ -857,22 +833,62 @@ function createSuperLineServer(contract, opts) {
         try {
           data = await validate(schema, frame.d);
         } catch (err) {
-          opts.onError?.(err, { kind: "event", name });
+          fireError(err, { kind: "event", name });
           return;
         }
       }
       for (const cb of set) callBus(cb, data, from, name);
     })();
   }
+  function handlePluginChannel(channel, payload) {
+    const set = pluginChannels.get(channel);
+    if (!set) return;
+    let frame;
+    try {
+      frame = serializer.decode(payload);
+    } catch {
+      return;
+    }
+    if (frame.i === instanceId) return;
+    for (const cb of set) callBus(cb, frame.d, frame.i, channel);
+  }
+  function pluginChannel(pluginName, name) {
+    const channel = PLUGIN + pluginName + ":" + name;
+    return {
+      publish(data) {
+        const set = pluginChannels.get(channel);
+        if (set) for (const cb of set) callBus(cb, data, instanceId, channel);
+        void adapter.publish(channel, serializer.encode({ i: instanceId, d: data }));
+      },
+      subscribe(handler) {
+        let set = pluginChannels.get(channel);
+        if (!set) {
+          set = /* @__PURE__ */ new Set();
+          pluginChannels.set(channel, set);
+          void adapter.subscribe(channel);
+        }
+        set.add(handler);
+        return () => {
+          const current = pluginChannels.get(channel);
+          if (!current) return;
+          current.delete(handler);
+          if (current.size === 0) {
+            pluginChannels.delete(channel);
+            void adapter.unsubscribe(channel);
+          }
+        };
+      }
+    };
+  }
   function personalTarget(channel) {
     return {
       emit(event, data) {
-        if (inspectorEnabled)
-          emitInspectorEvent({
+        if (taps.length)
+          emitTap({
             type: "msg.event",
             target: channel.slice(channel.indexOf(":") + 1),
             name: event,
-            data: safeSnapshot(data)
+            data
           });
         const env = { p: "emit", f: { t: "evt", e: event, d: data } };
         void adapter.publish(channel, serializer.encode(env));
@@ -901,8 +917,8 @@ function createSuperLineServer(contract, opts) {
         },
         { once: true }
       );
-      if (inspectorEnabled)
-        emitInspectorEvent({ type: "msg.serverRequest", target: id, name, input: safeSnapshot(input), reqId });
+      if (taps.length)
+        emitTap({ type: "msg.serverRequest", target: id, name, input, reqId });
       const env = { p: "req", o: instanceId, i: reqId, m: name, d: input };
       void adapter.publish(CONN + id, serializer.encode(env));
     });
@@ -917,7 +933,7 @@ function createSuperLineServer(contract, opts) {
     storeApi[name] = {
       async create(id, data, accessRules) {
         await store.create(id, data, accessRules);
-        if (inspectorEnabled) emitInspectorEvent({ type: "store.create", store: name, id });
+        if (taps.length) emitTap({ type: "store.create", store: name, id });
       },
       read(id) {
         return Promise.resolve(store.read(id));
@@ -925,20 +941,19 @@ function createSuperLineServer(contract, opts) {
       async write(id, data, opts2) {
         const origin = opts2?.origin ?? SERVER_ORIGIN;
         await store.apply({ id, update: data, origin });
-        if (inspectorEnabled)
-          emitInspectorEvent({ type: "store.write", store: name, id, origin, data: safeSnapshot(data) });
+        if (taps.length) emitTap({ type: "store.write", store: name, id, origin, data });
       },
       async grant(id, principal, perms) {
         const r = await readOrThrow(id);
         await store.setAccess(id, { ...r.accessRules, [principal]: perms });
-        if (inspectorEnabled) emitInspectorEvent({ type: "store.grant", store: name, id, principal, perms });
+        if (taps.length) emitTap({ type: "store.grant", store: name, id, principal, perms });
       },
       async revoke(id, principal) {
         const r = await readOrThrow(id);
         const next = { ...r.accessRules };
         delete next[principal];
         await store.setAccess(id, next);
-        if (inspectorEnabled) emitInspectorEvent({ type: "store.revoke", store: name, id, principal });
+        if (taps.length) emitTap({ type: "store.revoke", store: name, id, principal });
       },
       async delete(id) {
         await store.delete(id);
@@ -947,18 +962,21 @@ function createSuperLineServer(contract, opts) {
             STORE + name + ":" + id,
             serializer.encode({ t: "sdel", n: name, id, nd: instanceId })
           );
-        if (inspectorEnabled) emitInspectorEvent({ type: "store.delete", store: name, id });
+        if (taps.length) emitTap({ type: "store.delete", store: name, id });
       },
-      list() {
-        return Promise.resolve(store.list());
+      list(opts2) {
+        return Promise.resolve(store.list(opts2));
+      },
+      searchPrincipals(opts2) {
+        return Promise.resolve(store.searchPrincipals(opts2));
       },
       open(id, openOpts) {
         if (!store.open)
           throw new SuperLineError("UNSUPPORTED", `Store ${name} does not support reactive open()`);
         const replica = store.open(id, openOpts);
-        if (!inspectorEnabled) return replica;
+        if (!taps.length) return replica;
         const origin = openOpts?.origin ?? SERVER_ORIGIN;
-        const emit = (data) => emitInspectorEvent({ type: "store.write", store: name, id, origin, data: safeSnapshot(data) });
+        const emit = (data) => emitTap({ type: "store.write", store: name, id, origin, data });
         return {
           ...replica,
           set: (d) => {
@@ -977,6 +995,8 @@ function createSuperLineServer(contract, opts) {
       }
     };
   }
+  const pluginDisposers = [];
+  const pluginHandlers = {};
   const api = {
     nodeId: instanceId,
     nodeName,
@@ -1024,7 +1044,24 @@ function createSuperLineServer(contract, opts) {
       return { emit: t.emit, disconnect: t.close };
     },
     implement(handlers) {
-      impl = handlers;
+      const map = handlers;
+      const missing = [];
+      const duplicate = [];
+      const checkBlock = (block, defs) => {
+        if (!defs) return;
+        for (const key of Object.keys(defs)) {
+          const inImpl = !!map[block]?.[key];
+          const inPlugin = key in pluginHandlers;
+          if (inImpl && inPlugin) duplicate.push(`${block}.${key}`);
+          else if (!inImpl && !inPlugin) missing.push(`${block}.${key}`);
+        }
+      };
+      checkBlock("shared", c.shared?.clientToServer);
+      for (const role of Object.keys(c.roles)) checkBlock(role, c.roles[role]?.clientToServer);
+      if (duplicate.length)
+        throw new Error(`implement: these keys are also handled by a plugin \u2014 remove them: ${duplicate.join(", ")}`);
+      if (missing.length) throw new Error(`implement: missing handler(s) for: ${missing.join(", ")}`);
+      impl = map;
       return api;
     },
     room,
@@ -1066,14 +1103,89 @@ function createSuperLineServer(contract, opts) {
     async close() {
       if (closing) return;
       closing = true;
+      for (const dispose of pluginDisposers) {
+        try {
+          dispose();
+        } catch {
+        }
+      }
       if (hbTimer) clearInterval(hbTimer);
       for (const conn of conns) conn.close();
-      for (const conn of inspectorConns) conn.close();
+      for (const conn of reservedConns) conn.close();
       await adapter.presence?.clearNode(instanceId);
       await adapter.close?.();
       for (const transport of opts.transports) await transport.stop();
     }
   };
+  function makePluginContext(pluginName) {
+    return {
+      nodeId: instanceId,
+      nodeName,
+      instanceId,
+      serializer,
+      contract: c,
+      get conns() {
+        return [...conns];
+      },
+      get local() {
+        return api.local;
+      },
+      cluster: api.cluster,
+      isOnline: (userId) => api.isOnline(userId),
+      publish: (topic, data) => publishTo("shared", topic, data),
+      subscribe: (topic, handler) => api.subscribe(topic, handler),
+      toConn: (id) => {
+        const t = api.toConn(id);
+        return { emit: (event, data) => t.emit(event, data), close: t.close };
+      },
+      toUser: (userId) => {
+        const t = api.toUser(userId);
+        return { emit: (event, data) => t.emit(event, data), disconnect: t.disconnect };
+      },
+      room: (name) => {
+        const r = room(name);
+        return {
+          add: (conn) => r.add(conn),
+          remove: (conn) => r.remove(conn),
+          broadcast: (event, data) => r.broadcast(event, data),
+          get size() {
+            return r.size;
+          },
+          get connections() {
+            return r.connections;
+          }
+        };
+      },
+      store: (name) => api.store(name),
+      storeInfos: () => Object.entries(storeMap).map(([name, store]) => ({ name, model: store.model })),
+      describe: (conn) => buildDescriptor(conn),
+      connectionById: (id) => Promise.resolve(presenceOrThrow().get(id)),
+      channel: (name) => pluginChannel(pluginName, name)
+    };
+  }
+  const contractRequestKeys = new Set(Object.keys(c.shared?.clientToServer ?? {}));
+  for (const role of Object.keys(c.roles))
+    for (const k of Object.keys(c.roles[role]?.clientToServer ?? {})) contractRequestKeys.add(k);
+  for (const p of plugins) {
+    const ctx = makePluginContext(p.name);
+    if (p.handlers) {
+      for (const [key, fn] of Object.entries(p.handlers(ctx))) {
+        if (!contractRequestKeys.has(key))
+          throw new Error(`Plugin '${p.name}' handles '${key}', which the contract has no request for \u2014 did you forget to merge its surface?`);
+        if (key in pluginHandlers)
+          throw new Error(`Plugin handler collision on '${key}' (already provided by another plugin)`);
+        pluginHandlers[key] = fn;
+      }
+    }
+    if (p.connection)
+      reservedServing.set(p.connection.role, {
+        connection: p.connection,
+        handlers: p.connection.handlers?.(ctx) ?? {},
+        ctx
+      });
+    const dispose = p.setup?.(ctx);
+    if (dispose) pluginDisposers.push(dispose);
+  }
   return api;
 }
 export {