@super-line/server 0.3.0 → 0.5.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

@@ -16272,36 +16272,38 @@ __export(index_exports, {
   Conn: () => Conn,
   MemoryBus: () => MemoryBus,
   createInMemoryAdapter: () => createInMemoryAdapter,
-  createSuperLineServer: () => createSuperLineServer
+  createSuperLineServer: () => createSuperLineServer,
+  resolvePrincipal: () => resolvePrincipal
 });
 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;
+  /** ACL identity for stores: `identify(conn) ?? conn.id`, set by the server at accept (always defined there). */
+  principal;
+  /** 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,37 +16311,33 @@ 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();
   }
 };
+function resolvePrincipal(conn, identify) {
+  return identify?.(conn) ?? conn.id;
+}
 
 // src/memory-adapter.ts
 var MemoryBus = class {
@@ -16456,6 +16454,8 @@ var CONN = "c:";
 var USER = "u:";
 var REPLY = "reply:";
 var INSPECT = "i:";
+var STORE = "s:";
+var SERVER_ORIGIN = "server";
 function createSuperLineServer(contract, opts) {
   const c = contract;
   const serializer = opts.serializer ?? import_core2.jsonSerializer;
@@ -16464,10 +16464,7 @@ 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 storeMap = opts.stores ?? {};
   const conns = /* @__PURE__ */ new Set();
   const inspectorConns = /* @__PURE__ */ new Set();
   const members = /* @__PURE__ */ new Map();
@@ -16477,6 +16474,7 @@ function createSuperLineServer(contract, opts) {
   const replyChannel = REPLY + instanceId;
   let impl = {};
   let closing = false;
+  let relaying = false;
   let nextSReq = 1;
   const originWaiters = /* @__PURE__ */ new Map();
   const ownerRouting = /* @__PURE__ */ new Map();
@@ -16492,6 +16490,7 @@ function createSuperLineServer(contract, opts) {
       connectedAt: conn.connectedAt,
       ...userId !== void 0 ? { userId } : {},
       rooms,
+      ...conn.transport !== void 0 ? { transport: conn.transport } : {},
       ...opts.describeConn?.(conn)
     };
   }
@@ -16508,6 +16507,10 @@ function createSuperLineServer(contract, opts) {
       handlePersonal(channel, payload);
       return;
     }
+    if (channel.startsWith(STORE)) {
+      handleStoreRelay(channel, payload);
+      return;
+    }
     const set = members.get(channel);
     if (set) for (const conn of set) conn.sendRaw(payload);
     const busSet = busListeners.get(channel);
@@ -16587,12 +16590,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 +16763,66 @@ 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;
+    conn.principal = resolvePrincipal(conn, opts.identify);
+    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;
     }
@@ -16860,12 +16835,22 @@ function createSuperLineServer(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") {
+    } else if (frame.t === "sopen") await handleStoreOpen(conn, frame);
+    else if (frame.t === "srd") await handleStoreRead(conn, frame);
+    else if (frame.t === "swr") await handleStoreWrite(conn, frame);
+    else if (frame.t === "sclose") handleStoreClose(conn, frame);
+    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 });
+    } 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;
@@ -16943,6 +16928,100 @@ function createSuperLineServer(contract, opts) {
       conn.send({ t: "res", i: frame.i, d: null });
     });
   }
+  function storeOrErr(conn, id, name) {
+    const store = storeMap[name];
+    if (!store) conn.send({ t: "err", i: id, code: "NOT_FOUND", m: `Unknown store: ${name}` });
+    return store;
+  }
+  async function handleStoreOpen(conn, frame) {
+    const store = storeOrErr(conn, frame.i, frame.n);
+    if (!store) return;
+    await dispatchOp(conn, frame.i, { kind: "subscribe", name: `store:${frame.n}/${frame.id}`, conn }, async () => {
+      const resource = await store.read(frame.id);
+      if (!resource) throw new import_core2.SuperLineError("NOT_FOUND", `No resource: ${frame.n}/${frame.id}`);
+      const principal = conn.principal ?? conn.id;
+      if (!resource.accessRules[principal]?.read)
+        throw new import_core2.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 });
+      conn.send({ t: "res", i: frame.i, d: resource.data });
+    });
+  }
+  async function handleStoreRead(conn, frame) {
+    const store = storeOrErr(conn, frame.i, frame.n);
+    if (!store) return;
+    await dispatchOp(conn, frame.i, { kind: "request", name: `store:${frame.n}/${frame.id}`, conn }, async () => {
+      const resource = await store.read(frame.id);
+      if (!resource) throw new import_core2.SuperLineError("NOT_FOUND", `No resource: ${frame.n}/${frame.id}`);
+      const principal = conn.principal ?? conn.id;
+      if (!resource.accessRules[principal]?.read)
+        throw new import_core2.SuperLineError("FORBIDDEN", `Read denied: ${frame.n}/${frame.id}`);
+      conn.send({ t: "res", i: frame.i, d: resource.data });
+    });
+  }
+  async function handleStoreWrite(conn, frame) {
+    const store = storeOrErr(conn, frame.i, frame.n);
+    if (!store) return;
+    await dispatchOp(conn, frame.i, { kind: "request", name: `store:${frame.n}/${frame.id}`, conn }, async () => {
+      const resource = await store.read(frame.id);
+      if (!resource) throw new import_core2.SuperLineError("NOT_FOUND", `No resource: ${frame.n}/${frame.id}`);
+      const principal = conn.principal ?? conn.id;
+      if (!resource.accessRules[principal]?.write)
+        throw new import_core2.SuperLineError("FORBIDDEN", `Write denied: ${frame.n}/${frame.id}`);
+      await store.apply({ id: frame.id, update: frame.u, origin: frame.o });
+      if (inspectorEnabled)
+        emitInspectorEvent({
+          type: "store.write",
+          store: frame.n,
+          id: frame.id,
+          origin: frame.o,
+          connId: conn.id,
+          data: safeSnapshot(frame.u)
+        });
+      conn.send({ t: "res", i: frame.i, d: null });
+    });
+  }
+  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 });
+  }
+  for (const [name, store] of Object.entries(storeMap)) {
+    store.onChange((change) => {
+      if (relaying) return;
+      void adapter.publish(
+        STORE + name + ":" + change.id,
+        serializer.encode({
+          t: "sch",
+          n: name,
+          id: change.id,
+          u: change.update,
+          o: change.origin,
+          nd: instanceId
+        })
+      );
+    });
+  }
+  function handleStoreRelay(channel, payload) {
+    const set = members.get(channel);
+    if (set) for (const conn of set) conn.sendRaw(payload);
+    let frame;
+    try {
+      frame = serializer.decode(payload);
+    } catch {
+      return;
+    }
+    if (frame.nd === instanceId) return;
+    const store = storeMap[frame.n];
+    if (!store || store.clustering !== "relay") return;
+    relaying = true;
+    try {
+      void store.apply({ id: frame.id, update: frame.u, origin: frame.o });
+    } catch {
+    } finally {
+      relaying = false;
+    }
+  }
   function room(name) {
     const channel = ROOM + name;
     return {
@@ -17047,6 +17126,45 @@ function createSuperLineServer(contract, opts) {
       void adapter.publish(CONN + id, serializer.encode(env));
     });
   }
+  const storeApi = {};
+  for (const [name, store] of Object.entries(storeMap)) {
+    const readOrThrow = async (id) => {
+      const r = await store.read(id);
+      if (!r) throw new import_core2.SuperLineError("NOT_FOUND", `No resource: ${name}/${id}`);
+      return r;
+    };
+    storeApi[name] = {
+      async create(id, data, accessRules) {
+        await store.create(id, data, accessRules);
+      },
+      read(id) {
+        return Promise.resolve(store.read(id));
+      },
+      async write(id, data) {
+        await store.apply({ id, update: data, origin: SERVER_ORIGIN });
+        if (inspectorEnabled)
+          emitInspectorEvent({ type: "store.write", store: name, id, origin: SERVER_ORIGIN, data: safeSnapshot(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 });
+      },
+      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 });
+      },
+      async delete(id) {
+        await store.delete(id);
+      },
+      list() {
+        return Promise.resolve(store.list());
+      }
+    };
+  }
   const api = {
     nodeId: instanceId,
     nodeName,
@@ -17128,6 +17246,11 @@ function createSuperLineServer(contract, opts) {
         }
       };
     },
+    store(name) {
+      const handle = storeApi[name];
+      if (!handle) throw new import_core2.SuperLineError("NOT_FOUND", `Store not configured: ${name}`);
+      return handle;
+    },
     async close() {
       if (closing) return;
       closing = true;
@@ -17136,22 +17259,16 @@ 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,
   MemoryBus,
   createInMemoryAdapter,
-  createSuperLineServer
+  createSuperLineServer,
+  resolvePrincipal
 });