@super-line/server 0.3.0 → 0.4.0

package/README.md

@@ -3,18 +3,19 @@
 The server for [**super-line**](https://mertdogar.github.io/super-line/) — end-to-end typesafe WebSockets for TypeScript. Implements a shared contract over [`ws`](https://www.npmjs.com/package/ws): role-keyed handlers, rooms, topics, middleware, lifecycle hooks, and node-to-node messaging.
 
 ```bash
-pnpm add @super-line/core @super-line/server zod
+pnpm add @super-line/core @super-line/server @super-line/transport-websocket zod
 ```
 
 ```ts
 import http from 'node:http'
 import { createSuperLineServer } from '@super-line/server'
+import { webSocketServerTransport } from '@super-line/transport-websocket'
 import { api } from './contract'
 
 const server = http.createServer()
 const srv = createSuperLineServer(api, {
-  server,
-  authenticate: (req) => ({ role: 'user' as const, ctx: { id: '1' } }), // throw -> 401
+  transports: [webSocketServerTransport({ server })],
+  authenticate: (h) => ({ role: 'user' as const, ctx: { id: '1' } }), // throw -> 401
 })
 
 srv.implement({
@@ -29,7 +30,7 @@ srv.implement({
 server.listen(3000)
 ```
 
-Authenticate returns `{ role, ctx }`; cross-role calls are rejected with `NOT_FOUND`. Scale across processes with [`@super-line/adapter-redis`](https://www.npmjs.com/package/@super-line/adapter-redis).
+Authenticate receives the `Handshake` (`{ transport, headers, query, peer?, raw }`) and returns `{ role, ctx }`; cross-role calls are rejected with `NOT_FOUND`. The wire is carried by a pluggable transport — [`@super-line/transport-websocket`](https://www.npmjs.com/package/@super-line/transport-websocket) provides the WS transport shown above; other transports (HTTP/SSE, libp2p) are available — see the Transports guide. Scale across processes with [`@super-line/adapter-redis`](https://www.npmjs.com/package/@super-line/adapter-redis).
 
 - 📖 Docs: <https://mertdogar.github.io/super-line/>
 - 📚 Guides: [roles & auth](https://mertdogar.github.io/super-line/guide/roles-auth), [events & rooms](https://mertdogar.github.io/super-line/guide/events-rooms)

package/dist/index.cjs

@@ -16276,32 +16276,31 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 var import_node_crypto = require("crypto");
-var import_ws = require("ws");
 var import_core2 = require("@super-line/core");
 
 // src/conn.ts
 var Conn = class {
-  constructor(ws, id, role, ctx, serializer, backpressure, onEmit) {
-    this.ws = ws;
+  constructor(raw, id, role, ctx, serializer, onEmit) {
+    this.raw = raw;
     this.id = id;
     this.role = role;
     this.ctx = ctx;
     this.serializer = serializer;
-    this.backpressure = backpressure;
     this.onEmit = onEmit;
   }
-  ws;
+  raw;
   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). */
+  /** The client↔server transport (wire) this connection was accepted on (set by the server at accept). */
+  transport;
+  /** When this connection was accepted (`Date.now()`). */
   connectedAt = Date.now();
   /** When the server last sent a heartbeat ping to this connection (managed by the server). */
   lastPingAt;
@@ -16309,35 +16308,28 @@ var Conn = class {
   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 || this.overBackpressure()) return;
-    this.ws.send(this.serializer.encode(frame));
+    if (!this.raw.writable) return;
+    this.raw.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 || this.overBackpressure()) return;
-    this.ws.send(payload);
+    if (!this.raw.writable) return;
+    this.raw.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. */
+  /** Graceful close of the underlying transport connection. */
   close() {
-    this.ws.close();
+    this.raw.close();
+  }
+  /** Hard close with no handshake — used by heartbeat reaping. */
+  terminate() {
+    this.raw.terminate();
   }
 };
 
@@ -16464,10 +16456,6 @@ function createSuperLineServer(contract, opts) {
   const inspectorRedact = new Set(
     opts.inspector && typeof opts.inspector === "object" ? opts.inspector.redact ?? [] : []
   );
-  const wss = new import_ws.WebSocketServer({
-    noServer: true,
-    handleProtocols: (protocols) => inspectorEnabled && protocols.has(import_core2.INSPECTOR_SUBPROTOCOL) ? import_core2.INSPECTOR_SUBPROTOCOL : false
-  });
   const conns = /* @__PURE__ */ new Set();
   const inspectorConns = /* @__PURE__ */ new Set();
   const members = /* @__PURE__ */ new Map();
@@ -16492,6 +16480,7 @@ function createSuperLineServer(contract, opts) {
       connectedAt: conn.connectedAt,
       ...userId !== void 0 ? { userId } : {},
       rooms,
+      ...conn.transport !== void 0 ? { transport: conn.transport } : {},
       ...opts.describeConn?.(conn)
     };
   }
@@ -16587,12 +16576,12 @@ function createSuperLineServer(contract, opts) {
       void adapter.presence?.beat(instanceId);
       for (const conn of conns) {
         if (hb.maxMissed != null && conn.missedPongs >= hb.maxMissed) {
-          conn.ws.terminate();
+          conn.terminate();
           continue;
         }
         conn.missedPongs++;
         conn.lastPingAt = now;
-        conn.ws.ping();
+        conn.send({ t: "ping" });
       }
     }, hb.interval ?? 3e4);
     hbTimer.unref?.();
@@ -16760,94 +16749,65 @@ function createSuperLineServer(contract, opts) {
       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(import_core2.INSPECTOR_SUBPROTOCOL);
-  }
-  async function handleUpgrade(req, socket, head) {
-    if (opts.path) {
-      const { pathname } = new URL(req.url ?? "/", "http://localhost");
-      if (pathname !== opts.path) return;
+  const authHook = async (handshake) => {
+    const auth = await opts.authenticate(handshake);
+    return { role: auth.role, ctx: auth.ctx, transport: handshake.transport };
+  };
+  function acceptConn(raw, auth) {
+    const role = auth.role;
+    const ctx = auth.ctx;
+    const inspector = role === import_core2.INSPECTOR_ROLE;
+    if (inspector && !inspectorEnabled) {
+      raw.close();
+      return;
     }
-    const inspector = isInspectorRequest(req);
-    let role;
-    let ctx;
+    const connId = (0, import_node_crypto.randomUUID)();
+    const conn = new Conn(
+      raw,
+      connId,
+      role,
+      ctx,
+      serializer,
+      inspectorEnabled ? (event, data) => emitInspectorEvent({ type: "msg.event", target: connId, name: event, data: safeSnapshot(data) }) : void 0
+    );
+    conn.transport = auth.transport;
+    raw.onMessage((bytes) => {
+      void onMessage(conn, bytes);
+    });
     if (inspector) {
-      role = import_core2.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 connId = (0, import_node_crypto.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);
+      inspectorConns.add(conn);
+      raw.onClose(() => {
+        inspectorConns.delete(conn);
         for (const channel of conn.channels) leaveChannel(conn, channel);
-        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, 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);
+      return;
+    }
+    conns.add(conn);
+    raw.onClose((code) => {
+      conns.delete(conn);
+      for (const channel of conn.channels) leaveChannel(conn, channel);
+      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);
     });
-  }
-  async function onMessage(conn, data, isBinary) {
+    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, bytes) {
     let frame;
     try {
-      frame = serializer.decode(toWire(data, isBinary));
+      frame = serializer.decode(bytes);
     } catch {
       return;
     }
@@ -16864,8 +16824,14 @@ function createSuperLineServer(contract, opts) {
       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 });
+    } else if (frame.t === "pong") {
+      conn.lastPongAt = Date.now();
+      conn.missedPongs = 0;
     }
   }
+  for (const transport of opts.transports) {
+    void transport.start({ authenticate: authHook, onConnection: acceptConn });
+  }
   function runMiddleware(info, terminal) {
     const chain = opts.use ?? [];
     let last = -1;
@@ -17136,18 +17102,11 @@ function createSuperLineServer(contract, opts) {
       for (const conn of inspectorConns) conn.close();
       await adapter.presence?.clearNode(instanceId);
       await adapter.close?.();
-      await new Promise((resolve) => {
-        wss.close(() => resolve());
-      });
+      for (const transport of opts.transports) await transport.stop();
     }
   };
   return api;
 }
-function toWire(data, _isBinary) {
-  if (Array.isArray(data)) return Buffer.concat(data);
-  if (data instanceof ArrayBuffer) return new Uint8Array(data);
-  return data;
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Conn,

package/dist/index.d.cts

@@ -1,25 +1,16 @@
-import { Server, IncomingMessage } from 'node:http';
-import { ServerMessageDef, Serializer, ServerFrame, EmitData, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, SharedRequests, ServerInput, AnyData, RoleRequests, Events, DataOf, RoleTopics, SharedTopics, EventData } from '@super-line/core';
-import { WebSocket } from 'ws';
+import { ServerMessageDef, RawConn, Serializer, ServerFrame, EmitData, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, SharedRequests, ServerInput, AnyData, RoleRequests, Events, DataOf, RoleTopics, SharedTopics, EventData, ServerTransport, Handshake } from '@super-line/core';
 
-/** 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.
  *
- * Node-local: `conn` objects live on the node that accepted the upgrade, so don't
+ * Node-local: `conn` objects live on the node that accepted the connection, so don't
  * stash one to reach a user later — cross-node delivery goes through the Adapter
  * (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, Data = unknown> {
-    /** The underlying `ws` socket. `conn.ws.terminate()` simulates a drop in tests. */
-    readonly ws: WebSocket;
+    /** The underlying transport connection. `conn.terminate()` simulates a drop in tests. */
+    readonly raw: RawConn;
     /** Server-assigned unique id for this connection (stable for its lifetime). */
     readonly id: string;
     /** This connection's role (the literal resolved by `authenticate`). */
@@ -27,14 +18,15 @@ declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role ex
     /** The context `authenticate` returned for this connection. */
     readonly ctx: Ctx;
     private readonly serializer;
-    private readonly backpressure?;
     /** Optional inspector tap: called with each `emit` so the server can mirror it to inspectors. */
     private readonly onEmit?;
     /** 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). */
+    /** The client↔server transport (wire) this connection was accepted on (set by the server at accept). */
+    transport?: string;
+    /** When this connection was accepted (`Date.now()`). */
     readonly connectedAt: number;
     /** When the server last sent a heartbeat ping to this connection (managed by the server). */
     lastPingAt?: number;
@@ -43,25 +35,26 @@ declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role ex
     /** 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, 
+    /** The underlying transport connection. `conn.terminate()` simulates a drop in tests. */
+    raw: RawConn, 
     /** 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, backpressure?: Backpressure | undefined, 
+    ctx: Ctx, serializer: Serializer, 
     /** Optional inspector tap: called with each `emit` so the server can mirror it to inspectors. */
     onEmit?: ((event: string, data: unknown) => void) | 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). */
     sendRaw(payload: string | Uint8Array): void;
     /** Push an event to THIS connection (node-local). Scoped to the role's events. */
     emit<E extends keyof Ev>(event: E, data: EmitData<Ev[E]>): void;
-    /** Close the underlying socket. */
+    /** Graceful close of the underlying transport connection. */
     close(): void;
+    /** Hard close with no handshake — used by heartbeat reaping. */
+    terminate(): void;
 }
 
 /**
@@ -219,21 +212,19 @@ interface RoleLens<C extends Contract, R extends RoleOf<C>> {
 }
 /** Options for {@link createSuperLineServer}. */
 interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>> {
-    /** The `http.Server` to attach to (compose with Express/Fastify/Hono). */
-    server?: Server;
+    /** Client↔server transports to accept connections on (e.g. `webSocketServerTransport({ server })`). */
+    transports: ServerTransport[];
     /** Wire serializer; MUST match the client. Defaults to `jsonSerializer`. */
     serializer?: Serializer;
     /** Cross-node fan-out adapter. Defaults to a per-server in-memory adapter. */
     adapter?: Adapter;
-    /** Only handle upgrades for this pathname; others are left untouched. */
-    path?: string;
     /**
      * Friendly name for this node, surfaced in `srv.nodeName`, the cluster descriptor, and the
      * Control Center topology. Defaults to `SUPER_LINE_NODE_NAME` or a short slice of `nodeId`.
      */
     nodeName?: string;
-    /** Runs at the HTTP upgrade. Return { role, ctx }, or throw to reject with 401. */
-    authenticate: (req: IncomingMessage) => Awaitable<A>;
+    /** Authenticate a connection from its normalized {@link Handshake}. Return { role, ctx }, or throw to reject. */
+    authenticate: (handshake: Handshake) => 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. */
@@ -252,12 +243,10 @@ interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>> {
         interval?: number;
         maxMissed?: number;
     } | false;
-    /** Guard against slow consumers: when a connection's send buffer exceeds the limit, close or drop. */
-    backpressure?: Backpressure;
     /**
-     * Read-only Control Center inspector channel, reached via the WS subprotocol
-     * `superline.inspector.v1`. Connections on it bypass `authenticate` and are kept out of
-     * presence, the heartbeat, and `local`/`cluster` results. **Default off; dev / trusted-network only.**
+     * Enable the read-only Control Center inspector: emit `msg.*` telemetry and accept inspector
+     * clients. The WS transport must also be created with `inspector: true` to negotiate the
+     * `superline.inspector.v1` subprotocol. **Default off; dev / trusted-network only.**
      */
     inspector?: boolean | {
         redact?: string[];
@@ -315,8 +304,8 @@ interface SuperLineServer<C extends Contract, A extends AuthResult<C>> {
  * @example
  * ```ts
  * const srv = createSuperLineServer(api, {
- *   server,
- *   authenticate: (req) => ({ role: 'user' as const, ctx: { id: '1' } }),
+ *   transports: [webSocketServerTransport({ server })],
+ *   authenticate: (h) => ({ role: 'user' as const, ctx: { id: '1' } }),
  * })
  * srv.implement({
  *   shared: { join: async ({ room }, _ctx, conn) => { srv.room(room).add(conn); return { ok: true } } },
@@ -326,4 +315,4 @@ interface SuperLineServer<C extends Contract, A extends AuthResult<C>> {
  */
 declare function createSuperLineServer<C extends Contract, A extends AuthResult<C>>(contract: C, opts: SuperLineServerOptions<C, A>): SuperLineServer<C, A>;
 
-export { type AuthResult, type Backpressure, type BusMeta, type ClusterView, Conn, type ConnTarget, type Handlers, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type SuperLineServer, type SuperLineServerOptions, type UserTarget, createInMemoryAdapter, createSuperLineServer };
+export { type AuthResult, type BusMeta, type ClusterView, Conn, type ConnTarget, type Handlers, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type SuperLineServer, type SuperLineServerOptions, type UserTarget, createInMemoryAdapter, createSuperLineServer };

package/dist/index.d.ts

@@ -1,25 +1,16 @@
-import { Server, IncomingMessage } from 'node:http';
-import { ServerMessageDef, Serializer, ServerFrame, EmitData, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, SharedRequests, ServerInput, AnyData, RoleRequests, Events, DataOf, RoleTopics, SharedTopics, EventData } from '@super-line/core';
-import { WebSocket } from 'ws';
+import { ServerMessageDef, RawConn, Serializer, ServerFrame, EmitData, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, SharedRequests, ServerInput, AnyData, RoleRequests, Events, DataOf, RoleTopics, SharedTopics, EventData, ServerTransport, Handshake } from '@super-line/core';
 
-/** 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.
  *
- * Node-local: `conn` objects live on the node that accepted the upgrade, so don't
+ * Node-local: `conn` objects live on the node that accepted the connection, so don't
  * stash one to reach a user later — cross-node delivery goes through the Adapter
  * (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, Data = unknown> {
-    /** The underlying `ws` socket. `conn.ws.terminate()` simulates a drop in tests. */
-    readonly ws: WebSocket;
+    /** The underlying transport connection. `conn.terminate()` simulates a drop in tests. */
+    readonly raw: RawConn;
     /** Server-assigned unique id for this connection (stable for its lifetime). */
     readonly id: string;
     /** This connection's role (the literal resolved by `authenticate`). */
@@ -27,14 +18,15 @@ declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role ex
     /** The context `authenticate` returned for this connection. */
     readonly ctx: Ctx;
     private readonly serializer;
-    private readonly backpressure?;
     /** Optional inspector tap: called with each `emit` so the server can mirror it to inspectors. */
     private readonly onEmit?;
     /** 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). */
+    /** The client↔server transport (wire) this connection was accepted on (set by the server at accept). */
+    transport?: string;
+    /** When this connection was accepted (`Date.now()`). */
     readonly connectedAt: number;
     /** When the server last sent a heartbeat ping to this connection (managed by the server). */
     lastPingAt?: number;
@@ -43,25 +35,26 @@ declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role ex
     /** 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, 
+    /** The underlying transport connection. `conn.terminate()` simulates a drop in tests. */
+    raw: RawConn, 
     /** 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, backpressure?: Backpressure | undefined, 
+    ctx: Ctx, serializer: Serializer, 
     /** Optional inspector tap: called with each `emit` so the server can mirror it to inspectors. */
     onEmit?: ((event: string, data: unknown) => void) | 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). */
     sendRaw(payload: string | Uint8Array): void;
     /** Push an event to THIS connection (node-local). Scoped to the role's events. */
     emit<E extends keyof Ev>(event: E, data: EmitData<Ev[E]>): void;
-    /** Close the underlying socket. */
+    /** Graceful close of the underlying transport connection. */
     close(): void;
+    /** Hard close with no handshake — used by heartbeat reaping. */
+    terminate(): void;
 }
 
 /**
@@ -219,21 +212,19 @@ interface RoleLens<C extends Contract, R extends RoleOf<C>> {
 }
 /** Options for {@link createSuperLineServer}. */
 interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>> {
-    /** The `http.Server` to attach to (compose with Express/Fastify/Hono). */
-    server?: Server;
+    /** Client↔server transports to accept connections on (e.g. `webSocketServerTransport({ server })`). */
+    transports: ServerTransport[];
     /** Wire serializer; MUST match the client. Defaults to `jsonSerializer`. */
     serializer?: Serializer;
     /** Cross-node fan-out adapter. Defaults to a per-server in-memory adapter. */
     adapter?: Adapter;
-    /** Only handle upgrades for this pathname; others are left untouched. */
-    path?: string;
     /**
      * Friendly name for this node, surfaced in `srv.nodeName`, the cluster descriptor, and the
      * Control Center topology. Defaults to `SUPER_LINE_NODE_NAME` or a short slice of `nodeId`.
      */
     nodeName?: string;
-    /** Runs at the HTTP upgrade. Return { role, ctx }, or throw to reject with 401. */
-    authenticate: (req: IncomingMessage) => Awaitable<A>;
+    /** Authenticate a connection from its normalized {@link Handshake}. Return { role, ctx }, or throw to reject. */
+    authenticate: (handshake: Handshake) => 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. */
@@ -252,12 +243,10 @@ interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>> {
         interval?: number;
         maxMissed?: number;
     } | false;
-    /** Guard against slow consumers: when a connection's send buffer exceeds the limit, close or drop. */
-    backpressure?: Backpressure;
     /**
-     * Read-only Control Center inspector channel, reached via the WS subprotocol
-     * `superline.inspector.v1`. Connections on it bypass `authenticate` and are kept out of
-     * presence, the heartbeat, and `local`/`cluster` results. **Default off; dev / trusted-network only.**
+     * Enable the read-only Control Center inspector: emit `msg.*` telemetry and accept inspector
+     * clients. The WS transport must also be created with `inspector: true` to negotiate the
+     * `superline.inspector.v1` subprotocol. **Default off; dev / trusted-network only.**
      */
     inspector?: boolean | {
         redact?: string[];
@@ -315,8 +304,8 @@ interface SuperLineServer<C extends Contract, A extends AuthResult<C>> {
  * @example
  * ```ts
  * const srv = createSuperLineServer(api, {
- *   server,
- *   authenticate: (req) => ({ role: 'user' as const, ctx: { id: '1' } }),
+ *   transports: [webSocketServerTransport({ server })],
+ *   authenticate: (h) => ({ role: 'user' as const, ctx: { id: '1' } }),
  * })
  * srv.implement({
  *   shared: { join: async ({ room }, _ctx, conn) => { srv.room(room).add(conn); return { ok: true } } },
@@ -326,4 +315,4 @@ interface SuperLineServer<C extends Contract, A extends AuthResult<C>> {
  */
 declare function createSuperLineServer<C extends Contract, A extends AuthResult<C>>(contract: C, opts: SuperLineServerOptions<C, A>): SuperLineServer<C, A>;
 
-export { type AuthResult, type Backpressure, type BusMeta, type ClusterView, Conn, type ConnTarget, type Handlers, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type SuperLineServer, type SuperLineServerOptions, type UserTarget, createInMemoryAdapter, createSuperLineServer };
+export { type AuthResult, type BusMeta, type ClusterView, Conn, type ConnTarget, type Handlers, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type SuperLineServer, type SuperLineServerOptions, type UserTarget, createInMemoryAdapter, createSuperLineServer };

package/dist/index.js

@@ -2,39 +2,37 @@ import "./chunk-MLKGABMK.js";
 
 // src/index.ts
 import { randomUUID } from "crypto";
-import { WebSocketServer } from "ws";
 import {
   jsonSerializer,
   validate,
   SuperLineError,
-  INSPECTOR_SUBPROTOCOL,
   INSPECTOR_ROLE,
   classifyContract
 } from "@super-line/core";
 
 // src/conn.ts
 var Conn = class {
-  constructor(ws, id, role, ctx, serializer, backpressure, onEmit) {
-    this.ws = ws;
+  constructor(raw, id, role, ctx, serializer, onEmit) {
+    this.raw = raw;
     this.id = id;
     this.role = role;
     this.ctx = ctx;
     this.serializer = serializer;
-    this.backpressure = backpressure;
     this.onEmit = onEmit;
   }
-  ws;
+  raw;
   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). */
+  /** The client↔server transport (wire) this connection was accepted on (set by the server at accept). */
+  transport;
+  /** When this connection was accepted (`Date.now()`). */
   connectedAt = Date.now();
   /** When the server last sent a heartbeat ping to this connection (managed by the server). */
   lastPingAt;
@@ -42,35 +40,28 @@ var Conn = class {
   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 || this.overBackpressure()) return;
-    this.ws.send(this.serializer.encode(frame));
+    if (!this.raw.writable) return;
+    this.raw.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 || this.overBackpressure()) return;
-    this.ws.send(payload);
+    if (!this.raw.writable) return;
+    this.raw.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. */
+  /** Graceful close of the underlying transport connection. */
   close() {
-    this.ws.close();
+    this.raw.close();
+  }
+  /** Hard close with no handshake — used by heartbeat reaping. */
+  terminate() {
+    this.raw.terminate();
   }
 };
 
@@ -197,10 +188,6 @@ function createSuperLineServer(contract, opts) {
   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();
@@ -225,6 +212,7 @@ function createSuperLineServer(contract, opts) {
       connectedAt: conn.connectedAt,
       ...userId !== void 0 ? { userId } : {},
       rooms,
+      ...conn.transport !== void 0 ? { transport: conn.transport } : {},
       ...opts.describeConn?.(conn)
     };
   }
@@ -320,12 +308,12 @@ function createSuperLineServer(contract, opts) {
       void adapter.presence?.beat(instanceId);
       for (const conn of conns) {
         if (hb.maxMissed != null && conn.missedPongs >= hb.maxMissed) {
-          conn.ws.terminate();
+          conn.terminate();
           continue;
         }
         conn.missedPongs++;
         conn.lastPingAt = now;
-        conn.ws.ping();
+        conn.send({ t: "ping" });
       }
     }, hb.interval ?? 3e4);
     hbTimer.unref?.();
@@ -493,94 +481,65 @@ function createSuperLineServer(contract, opts) {
       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;
+  const authHook = async (handshake) => {
+    const auth = await opts.authenticate(handshake);
+    return { role: auth.role, ctx: auth.ctx, transport: handshake.transport };
+  };
+  function acceptConn(raw, auth) {
+    const role = auth.role;
+    const ctx = auth.ctx;
+    const inspector = role === INSPECTOR_ROLE;
+    if (inspector && !inspectorEnabled) {
+      raw.close();
+      return;
     }
-    const inspector = isInspectorRequest(req);
-    let role;
-    let ctx;
+    const connId = randomUUID();
+    const conn = new Conn(
+      raw,
+      connId,
+      role,
+      ctx,
+      serializer,
+      inspectorEnabled ? (event, data) => emitInspectorEvent({ type: "msg.event", target: connId, name: event, data: safeSnapshot(data) }) : void 0
+    );
+    conn.transport = auth.transport;
+    raw.onMessage((bytes) => {
+      void onMessage(conn, bytes);
+    });
     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 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);
+      inspectorConns.add(conn);
+      raw.onClose(() => {
+        inspectorConns.delete(conn);
         for (const channel of conn.channels) leaveChannel(conn, channel);
-        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, 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);
+      return;
+    }
+    conns.add(conn);
+    raw.onClose((code) => {
+      conns.delete(conn);
+      for (const channel of conn.channels) leaveChannel(conn, channel);
+      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);
     });
-  }
-  async function onMessage(conn, data, isBinary) {
+    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, bytes) {
     let frame;
     try {
-      frame = serializer.decode(toWire(data, isBinary));
+      frame = serializer.decode(bytes);
     } catch {
       return;
     }
@@ -597,8 +556,14 @@ function createSuperLineServer(contract, opts) {
       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 });
+    } else if (frame.t === "pong") {
+      conn.lastPongAt = Date.now();
+      conn.missedPongs = 0;
     }
   }
+  for (const transport of opts.transports) {
+    void transport.start({ authenticate: authHook, onConnection: acceptConn });
+  }
   function runMiddleware(info, terminal) {
     const chain = opts.use ?? [];
     let last = -1;
@@ -869,18 +834,11 @@ function createSuperLineServer(contract, opts) {
       for (const conn of inspectorConns) conn.close();
       await adapter.presence?.clearNode(instanceId);
       await adapter.close?.();
-      await new Promise((resolve) => {
-        wss.close(() => resolve());
-      });
+      for (const transport of opts.transports) await transport.stop();
     }
   };
   return api;
 }
-function toWire(data, _isBinary) {
-  if (Array.isArray(data)) return Buffer.concat(data);
-  if (data instanceof ArrayBuffer) return new Uint8Array(data);
-  return data;
-}
 export {
   Conn,
   MemoryBus,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super-line/server",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Typesafe WebSocket server for super-line — rooms, topics, middleware, pluggable adapters.",
   "license": "MIT",
@@ -47,8 +47,7 @@
     "access": "public"
   },
   "dependencies": {
-    "ws": "^8.18.0",
-    "@super-line/core": "^0.3.0"
+    "@super-line/core": "^0.4.0"
   },
   "devDependencies": {
     "@chainsafe/libp2p-noise": "^17.0.0",
@@ -60,18 +59,23 @@
     "@libp2p/memory": "^2.0.22",
     "@libp2p/tcp": "^11.0.22",
     "@types/ws": "^8.5.13",
+    "eventsource": "^3.0.2",
     "ioredis": "^5.4.2",
+    "ws": "^8.18.0",
     "libp2p": "^3.3.4",
     "rabbitmq-client": "^5.0.0",
     "testcontainers": "^10.13.2",
     "zeromq": "^6.0.0",
     "zod": "^3.24.1",
     "zod-to-json-schema": "^3.25.2",
-    "@super-line/adapter-rabbitmq": "0.3.0",
-    "@super-line/adapter-libp2p": "0.3.0",
-    "@super-line/adapter-redis": "0.3.0",
-    "@super-line/client": "0.3.0",
-    "@super-line/adapter-zeromq": "0.3.0"
+    "@super-line/adapter-zeromq": "0.4.0",
+    "@super-line/adapter-libp2p": "0.4.0",
+    "@super-line/client": "0.4.0",
+    "@super-line/transport-http": "0.4.0",
+    "@super-line/transport-loopback": "0.4.0",
+    "@super-line/transport-websocket": "0.4.0",
+    "@super-line/adapter-rabbitmq": "0.4.0",
+    "@super-line/adapter-redis": "0.4.0"
   },
   "optionalDependencies": {
     "@standard-community/standard-json": "^0.3.5"