@super-line/server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# @super-line/server
+
+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
+```
+
+```ts
+import http from 'node:http'
+import { createSocketServer } from '@super-line/server'
+import { api } from './contract'
+
+const server = http.createServer()
+const srv = createSocketServer(api, {
+  server,
+  authenticate: (req) => ({ role: 'user' as const, ctx: { id: '1' } }), // throw -> 401
+})
+
+srv.implement({
+  user: {
+    send: async ({ text }, ctx, conn) => {
+      conn.emit('message', { text })
+      return { id: crypto.randomUUID() }
+    },
+  },
+})
+
+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).
+
+- 📖 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)
+- 📕 API reference: <https://mertdogar.github.io/super-line/reference/>
+- 🧩 Source: <https://github.com/mertdogar/super-line>
+
+MIT © Mert

package/dist/index.cjs

@@ -0,0 +1,352 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Conn: () => Conn,
+  MemoryBus: () => MemoryBus,
+  createInMemoryAdapter: () => createInMemoryAdapter,
+  createSocketServer: () => createSocketServer
+});
+module.exports = __toCommonJS(index_exports);
+var import_node_crypto = require("crypto");
+var import_ws = require("ws");
+var import_core = require("@super-line/core");
+
+// src/conn.ts
+var Conn = class {
+  constructor(ws, role, ctx, serializer) {
+    this.ws = ws;
+    this.role = role;
+    this.ctx = ctx;
+    this.serializer = serializer;
+  }
+  ws;
+  role;
+  ctx;
+  serializer;
+  /** Namespaced channels (rooms + topics) this connection belongs to. */
+  channels = /* @__PURE__ */ new Set();
+  /** Encode and send a frame (unicast, e.g. req/res). */
+  send(frame) {
+    if (this.ws.readyState !== this.ws.OPEN) return;
+    this.ws.send(this.serializer.encode(frame));
+  }
+  /** Forward an already-encoded frame (fan-out path; encoded once at the source). */
+  sendRaw(payload) {
+    if (this.ws.readyState !== this.ws.OPEN) return;
+    this.ws.send(payload);
+  }
+  /** Push an event to THIS connection (node-local). Scoped to the role's events. */
+  emit(event, data) {
+    this.send({ t: "evt", e: String(event), d: data });
+  }
+  /** Close the underlying socket. */
+  close() {
+    this.ws.close();
+  }
+};
+
+// src/memory-adapter.ts
+var MemoryBus = class {
+  channels = /* @__PURE__ */ new Map();
+  subscribe(channel, adapter) {
+    let set = this.channels.get(channel);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.channels.set(channel, set);
+    }
+    set.add(adapter);
+  }
+  unsubscribe(channel, adapter) {
+    const set = this.channels.get(channel);
+    if (!set) return;
+    set.delete(adapter);
+    if (set.size === 0) this.channels.delete(channel);
+  }
+  publish(channel, payload) {
+    const set = this.channels.get(channel);
+    if (!set) return;
+    for (const adapter of set) adapter.deliver(channel, payload);
+  }
+};
+var MemoryAdapter = class {
+  constructor(bus) {
+    this.bus = bus;
+  }
+  bus;
+  handler;
+  subscribe(channel) {
+    this.bus.subscribe(channel, this);
+  }
+  unsubscribe(channel) {
+    this.bus.unsubscribe(channel, this);
+  }
+  publish(channel, payload) {
+    this.bus.publish(channel, payload);
+  }
+  onMessage(handler) {
+    this.handler = handler;
+  }
+  deliver(channel, payload) {
+    this.handler?.(channel, payload);
+  }
+};
+function createInMemoryAdapter(bus = new MemoryBus()) {
+  return new MemoryAdapter(bus);
+}
+
+// src/index.ts
+var ROOM = "r:";
+var TOPIC = "t:";
+var S2S = "s2s";
+function createSocketServer(contract, opts) {
+  const c = contract;
+  const serializer = opts.serializer ?? import_core.jsonSerializer;
+  const adapter = opts.adapter ?? createInMemoryAdapter();
+  const wss = new import_ws.WebSocketServer({ noServer: true });
+  const conns = /* @__PURE__ */ new Set();
+  const members = /* @__PURE__ */ new Map();
+  const serverListeners = /* @__PURE__ */ new Map();
+  const instanceId = (0, import_node_crypto.randomUUID)();
+  let impl = {};
+  adapter.onMessage((channel, payload) => {
+    if (channel === S2S) {
+      handleServerMessage(payload);
+      return;
+    }
+    const set = members.get(channel);
+    if (!set) return;
+    for (const conn of set) conn.sendRaw(payload);
+  });
+  if (c.serverToServer) void adapter.subscribe(S2S);
+  function handleServerMessage(payload) {
+    let msg;
+    try {
+      msg = serializer.decode(payload);
+    } catch {
+      return;
+    }
+    if (msg.from === instanceId) return;
+    const set = serverListeners.get(msg.e);
+    if (set) for (const cb of set) cb(msg.d);
+  }
+  function joinChannel(conn, channel) {
+    conn.channels.add(channel);
+    const set = members.get(channel);
+    if (set) {
+      set.add(conn);
+      return;
+    }
+    members.set(channel, /* @__PURE__ */ new Set([conn]));
+    return adapter.subscribe(channel);
+  }
+  function leaveChannel(conn, channel) {
+    const set = members.get(channel);
+    if (!set) return;
+    set.delete(conn);
+    conn.channels.delete(channel);
+    if (set.size === 0) {
+      members.delete(channel);
+      void adapter.unsubscribe(channel);
+    }
+  }
+  function topicNamespace(role, name) {
+    if (c.roles[role]?.serverToClient?.[name]?.subscribe) return role;
+    if (c.shared?.serverToClient?.[name]?.subscribe) return "shared";
+    return void 0;
+  }
+  if (opts.server) {
+    opts.server.on("upgrade", (req, socket, head) => {
+      void handleUpgrade(req, socket, head);
+    });
+  }
+  async function handleUpgrade(req, socket, head) {
+    if (opts.path) {
+      const { pathname } = new URL(req.url ?? "/", "http://localhost");
+      if (pathname !== opts.path) return;
+    }
+    let auth;
+    try {
+      auth = await opts.authenticate(req);
+    } catch {
+      socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      const conn = new Conn(ws, auth.role, auth.ctx, serializer);
+      conns.add(conn);
+      ws.on("message", (data, isBinary) => {
+        void onMessage(conn, data, isBinary);
+      });
+      ws.on("close", (code) => {
+        conns.delete(conn);
+        for (const channel of conn.channels) leaveChannel(conn, channel);
+        opts.onDisconnect?.(conn, auth.ctx, code);
+      });
+      opts.onConnection?.(conn, auth.ctx);
+    });
+  }
+  async function onMessage(conn, data, isBinary) {
+    let frame;
+    try {
+      frame = serializer.decode(toWire(data, isBinary));
+    } catch {
+      return;
+    }
+    if (frame.t === "req") await handleReq(conn, frame);
+    else if (frame.t === "sub") await handleSub(conn, frame);
+    else if (frame.t === "unsub") {
+      const ns = topicNamespace(conn.role, frame.c);
+      if (ns) leaveChannel(conn, TOPIC + ns + ":" + frame.c);
+    }
+  }
+  function runMiddleware(info, terminal) {
+    const chain = opts.use ?? [];
+    let last = -1;
+    const dispatch = (idx) => {
+      if (idx <= last) return Promise.reject(new Error("next() called multiple times"));
+      last = idx;
+      const mw = chain[idx];
+      if (!mw) return terminal();
+      return Promise.resolve(mw(info.conn.ctx, info, () => dispatch(idx + 1)));
+    };
+    return dispatch(0);
+  }
+  async function dispatchOp(conn, id, info, terminal) {
+    let responded = false;
+    try {
+      await runMiddleware(info, async () => {
+        await terminal();
+        responded = true;
+      });
+    } catch (err) {
+      opts.onError?.(err, info);
+      if (!responded) {
+        const e = err instanceof import_core.SocketError ? err : new import_core.SocketError("INTERNAL", "Internal server error");
+        conn.send({ t: "err", i: id, code: e.code, m: e.message, d: e.data });
+      }
+    }
+  }
+  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];
+    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 (0, import_core.validate)(def.input, frame.d);
+      const output = await handler(input, conn.ctx, conn);
+      conn.send({ t: "res", i: frame.i, d: output });
+    });
+  }
+  async function handleSub(conn, frame) {
+    const ns = topicNamespace(conn.role, frame.c);
+    if (!ns) {
+      conn.send({ t: "err", i: frame.i, code: "NOT_FOUND", m: `Unknown topic: ${frame.c}` });
+      return;
+    }
+    await dispatchOp(conn, frame.i, { kind: "subscribe", name: frame.c, conn }, async () => {
+      if (opts.authorizeSubscribe) {
+        const ok = await opts.authorizeSubscribe(frame.c, conn.ctx, conn);
+        if (ok === false) throw new import_core.SocketError("FORBIDDEN", `Subscribe denied: ${frame.c}`);
+      }
+      await joinChannel(conn, TOPIC + ns + ":" + frame.c);
+      conn.send({ t: "res", i: frame.i, d: null });
+    });
+  }
+  function room(name) {
+    const channel = ROOM + name;
+    return {
+      add(conn) {
+        void joinChannel(conn, channel);
+      },
+      remove(conn) {
+        leaveChannel(conn, channel);
+      },
+      broadcast(event, data) {
+        void adapter.publish(channel, serializer.encode({ t: "evt", e: String(event), d: data }));
+      },
+      get size() {
+        return members.get(channel)?.size ?? 0;
+      }
+    };
+  }
+  function publishTo(ns, name, data) {
+    void adapter.publish(TOPIC + ns + ":" + name, serializer.encode({ t: "pub", c: name, d: data }));
+  }
+  const api = {
+    implement(handlers) {
+      impl = handlers;
+      return api;
+    },
+    room,
+    publish(topic, data) {
+      publishTo("shared", String(topic), data);
+    },
+    forRole(role) {
+      return {
+        publish(topic, data) {
+          publishTo(role, String(topic), data);
+        }
+      };
+    },
+    emitServer(event, data) {
+      void adapter.publish(S2S, serializer.encode({ from: instanceId, e: String(event), d: data }));
+    },
+    onServer(event, handler) {
+      const name = String(event);
+      let set = serverListeners.get(name);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        serverListeners.set(name, set);
+      }
+      set.add(handler);
+      return () => {
+        const current = serverListeners.get(name);
+        if (!current) return;
+        current.delete(handler);
+        if (current.size === 0) serverListeners.delete(name);
+      };
+    },
+    async close() {
+      for (const conn of conns) conn.close();
+      await adapter.close?.();
+      await new Promise((resolve) => {
+        wss.close(() => resolve());
+      });
+    }
+  };
+  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,
+  createSocketServer
+});

package/dist/index.d.cts

@@ -0,0 +1,197 @@
+import { Server, IncomingMessage } from 'node:http';
+import { ServerMessageDef, Serializer, ServerFrame, EmitData, Adapter, Contract, RoleOf, SharedRequests, ServerInput, SharedEvents, Output, RoleRequests, Events, RoleTopics, SharedTopics, ServerEvents, ServerEmit, ServerData } from '@super-line/core';
+import { WebSocket } from 'ws';
+
+/**
+ * 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
+ * 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> {
+    /** The underlying `ws` socket. `conn.ws.terminate()` simulates a drop in tests. */
+    readonly ws: WebSocket;
+    /** This connection's role (the literal resolved by `authenticate`). */
+    readonly role: Role;
+    /** The context `authenticate` returned for this connection. */
+    readonly ctx: Ctx;
+    private readonly serializer;
+    /** Namespaced channels (rooms + topics) this connection belongs to. */
+    readonly channels: Set<string>;
+    constructor(
+    /** The underlying `ws` socket. `conn.ws.terminate()` simulates a drop in tests. */
+    ws: WebSocket, 
+    /** This connection's role (the literal resolved by `authenticate`). */
+    role: Role, 
+    /** The context `authenticate` returned for this connection. */
+    ctx: Ctx, serializer: Serializer);
+    /** 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. */
+    close(): void;
+}
+
+/**
+ * In-process pub/sub bus. Share one bus across multiple servers to simulate
+ * multiple nodes in a test (each server gets its own adapter bound to the bus).
+ */
+declare class MemoryBus {
+    private readonly channels;
+    subscribe(channel: string, adapter: MemoryAdapter): void;
+    unsubscribe(channel: string, adapter: MemoryAdapter): void;
+    publish(channel: string, payload: string | Uint8Array): void;
+}
+declare class MemoryAdapter implements Adapter {
+    private readonly bus;
+    private handler?;
+    constructor(bus: MemoryBus);
+    subscribe(channel: string): void;
+    unsubscribe(channel: string): void;
+    publish(channel: string, payload: string | Uint8Array): void;
+    onMessage(handler: (channel: string, payload: string | Uint8Array) => void): void;
+    deliver(channel: string, payload: string | Uint8Array): void;
+}
+/**
+ * Create an in-memory {@link Adapter}. The default for a single-node server.
+ * Pass a shared {@link MemoryBus} to two servers to simulate cross-node fan-out.
+ */
+declare function createInMemoryAdapter(bus?: MemoryBus): Adapter;
+
+type Awaitable<T> = T | Promise<T>;
+/**
+ * The discriminated value `authenticate` returns: a `role` (one of the contract's
+ * roles) plus its `ctx`. Returning different ctx shapes per role narrows both the
+ * handler surface and `ctx` together.
+ */
+type AuthResult<C extends Contract> = {
+    [R in RoleOf<C>]: {
+        role: R;
+        ctx: unknown;
+    };
+}[RoleOf<C>];
+type CtxFor<A, R> = A extends {
+    role: R;
+    ctx: infer X;
+} ? X : never;
+type CtxUnion<A> = A extends {
+    ctx: infer X;
+} ? X : never;
+type RoleHandlers<C extends Contract, A, R extends RoleOf<C>> = {
+    [K in keyof RoleRequests<C, R>]: (input: ServerInput<RoleRequests<C, R>[K]>, ctx: CtxFor<A, R>, conn: Conn<Events<C, R>, CtxFor<A, R>, R>) => Awaitable<Output<RoleRequests<C, R>[K]>>;
+};
+type SharedHandlers<C extends Contract, A> = {
+    [K in keyof SharedRequests<C>]: (input: ServerInput<SharedRequests<C>[K]>, ctx: CtxUnion<A>, conn: Conn<SharedEvents<C>, CtxUnion<A>, RoleOf<C>>) => Awaitable<Output<SharedRequests<C>[K]>>;
+};
+/**
+ * The handler map passed to `implement`: one block per role plus an optional
+ * `shared` block. Each handler's `input`/`ctx`/`conn` are narrowed to its role.
+ * The `shared` key is required only when the contract has shared requests.
+ */
+type Handlers<C extends Contract, A> = ([keyof SharedRequests<C>] extends [never] ? {} : {
+    shared: SharedHandlers<C, A>;
+}) & {
+    [R in RoleOf<C>]: RoleHandlers<C, A, R>;
+};
+/** Context passed to middleware and lifecycle hooks about the current operation. */
+interface MiddlewareInfo {
+    /** Whether this is a request or a topic subscribe. */
+    kind: 'request' | 'subscribe';
+    /** The request/topic name. */
+    name: string;
+    /** The connection the operation is on (`conn.role` available). */
+    conn: Conn;
+}
+/**
+ * Flat middleware run before request/subscribe handlers. Call `next()` to proceed,
+ * or `throw` to short-circuit (rejecting the operation). Does not change `ctx`'s type.
+ */
+type Middleware<A> = (ctx: CtxUnion<A>, info: MiddlewareInfo, next: () => Promise<void>) => Awaitable<void>;
+/**
+ * A mixed-role, server-controlled connection group. `broadcast` delivers a
+ * **shared** event to every member, regardless of their role.
+ */
+interface Room<C extends Contract> {
+    /** Add a connection to the room (server-controlled membership). */
+    add(conn: Conn): void;
+    /** Remove a connection from the room. */
+    remove(conn: Conn): void;
+    /** Broadcast a shared event to all members. */
+    broadcast<E extends keyof SharedEvents<C>>(event: E, data: EmitData<SharedEvents<C>[E]>): void;
+    /** Member count **on the current node** (membership is node-local). */
+    readonly size: number;
+}
+/** Lens for role-scoped server sends, returned by `srv.forRole(role)`. */
+interface RoleLens<C extends Contract, R extends RoleOf<C>> {
+    /** Publish to a topic in role `R`'s surface (reaches that role's subscribers). */
+    publish<T extends keyof RoleTopics<C, R>>(topic: T, data: EmitData<RoleTopics<C, R>[T]>): void;
+}
+/** Options for {@link createSocketServer}. */
+interface ServerOptions<C extends Contract, A extends AuthResult<C>> {
+    /** The `http.Server` to attach to (compose with Express/Fastify/Hono). */
+    server?: Server;
+    /** 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;
+    /** Runs at the HTTP upgrade. Return { role, ctx }, or throw to reject with 401. */
+    authenticate: (req: IncomingMessage) => Awaitable<A>;
+    /** Runs on each client subscribe. Return false or throw to deny. */
+    authorizeSubscribe?: (topic: string, ctx: CtxUnion<A>, conn: Conn) => Awaitable<boolean | void>;
+    /** Middleware chain run before req/subscribe handlers (rate-limit, authz, logging, metrics). */
+    use?: Middleware<A>[];
+    /** Called once per accepted connection. */
+    onConnection?: (conn: Conn, ctx: CtxUnion<A>) => void;
+    /** Called when a connection closes, with the WebSocket close `code`. */
+    onDisconnect?: (conn: Conn, ctx: CtxUnion<A>, code: number) => void;
+    /** Called for any error thrown in middleware/handlers (after the client is replied to). */
+    onError?: (error: unknown, info: MiddlewareInfo) => void;
+}
+/** A running super-line server, returned by {@link createSocketServer}. */
+interface SocketServer<C extends Contract, A extends AuthResult<C>> {
+    /** Register handlers for shared + per-role requests (chainable). */
+    implement(handlers: Handlers<C, A>): SocketServer<C, A>;
+    /** Mixed-role connection group; broadcast() sends a shared contract event to members. */
+    room(name: string): Room<C>;
+    /** Publish a SHARED topic to all subscribers (server-only publish). */
+    publish<T extends keyof SharedTopics<C>>(topic: T, data: EmitData<SharedTopics<C>[T]>): void;
+    /** Lens for role-scoped sends, e.g. forRole('user').publish('feed', data). */
+    forRole<R extends RoleOf<C>>(role: R): RoleLens<C, R>;
+    /** Broadcast a typed event to all OTHER server nodes (at-most-once, excludes self). */
+    emitServer<E extends keyof ServerEvents<C>>(event: E, data: ServerEmit<ServerEvents<C>[E]>): void;
+    /** Listen for inter-server events from other nodes. Returns an unsubscribe fn. */
+    onServer<E extends keyof ServerEvents<C>>(event: E, handler: (data: ServerData<ServerEvents<C>[E]>) => void): () => void;
+    close(): Promise<void>;
+}
+/**
+ * Create a server bound to a contract. Attach it to an `http.Server`, then call
+ * {@link SocketServer.implement} with your handlers. `authenticate` resolves each
+ * connection's `{ role, ctx }` at the upgrade.
+ *
+ * @param contract - the shared contract.
+ * @param opts - server options; `authenticate` is required.
+ * @returns the {@link SocketServer}.
+ * @throws nothing directly; handler throws become a typed `SocketError` to the client.
+ *
+ * @example
+ * ```ts
+ * const srv = createSocketServer(api, {
+ *   server,
+ *   authenticate: (req) => ({ role: 'user' as const, ctx: { id: '1' } }),
+ * })
+ * srv.implement({
+ *   shared: { join: async ({ room }, _ctx, conn) => { srv.room(room).add(conn); return { ok: true } } },
+ *   user:   { say:  async ({ text }, ctx)        => ({ id: '...' }) },
+ * })
+ * ```
+ */
+declare function createSocketServer<C extends Contract, A extends AuthResult<C>>(contract: C, opts: ServerOptions<C, A>): SocketServer<C, A>;
+
+export { type AuthResult, Conn, type Handlers, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type ServerOptions, type SocketServer, createInMemoryAdapter, createSocketServer };

package/dist/index.d.ts

@@ -0,0 +1,197 @@
+import { Server, IncomingMessage } from 'node:http';
+import { ServerMessageDef, Serializer, ServerFrame, EmitData, Adapter, Contract, RoleOf, SharedRequests, ServerInput, SharedEvents, Output, RoleRequests, Events, RoleTopics, SharedTopics, ServerEvents, ServerEmit, ServerData } from '@super-line/core';
+import { WebSocket } from 'ws';
+
+/**
+ * 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
+ * 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> {
+    /** The underlying `ws` socket. `conn.ws.terminate()` simulates a drop in tests. */
+    readonly ws: WebSocket;
+    /** This connection's role (the literal resolved by `authenticate`). */
+    readonly role: Role;
+    /** The context `authenticate` returned for this connection. */
+    readonly ctx: Ctx;
+    private readonly serializer;
+    /** Namespaced channels (rooms + topics) this connection belongs to. */
+    readonly channels: Set<string>;
+    constructor(
+    /** The underlying `ws` socket. `conn.ws.terminate()` simulates a drop in tests. */
+    ws: WebSocket, 
+    /** This connection's role (the literal resolved by `authenticate`). */
+    role: Role, 
+    /** The context `authenticate` returned for this connection. */
+    ctx: Ctx, serializer: Serializer);
+    /** 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. */
+    close(): void;
+}
+
+/**
+ * In-process pub/sub bus. Share one bus across multiple servers to simulate
+ * multiple nodes in a test (each server gets its own adapter bound to the bus).
+ */
+declare class MemoryBus {
+    private readonly channels;
+    subscribe(channel: string, adapter: MemoryAdapter): void;
+    unsubscribe(channel: string, adapter: MemoryAdapter): void;
+    publish(channel: string, payload: string | Uint8Array): void;
+}
+declare class MemoryAdapter implements Adapter {
+    private readonly bus;
+    private handler?;
+    constructor(bus: MemoryBus);
+    subscribe(channel: string): void;
+    unsubscribe(channel: string): void;
+    publish(channel: string, payload: string | Uint8Array): void;
+    onMessage(handler: (channel: string, payload: string | Uint8Array) => void): void;
+    deliver(channel: string, payload: string | Uint8Array): void;
+}
+/**
+ * Create an in-memory {@link Adapter}. The default for a single-node server.
+ * Pass a shared {@link MemoryBus} to two servers to simulate cross-node fan-out.
+ */
+declare function createInMemoryAdapter(bus?: MemoryBus): Adapter;
+
+type Awaitable<T> = T | Promise<T>;
+/**
+ * The discriminated value `authenticate` returns: a `role` (one of the contract's
+ * roles) plus its `ctx`. Returning different ctx shapes per role narrows both the
+ * handler surface and `ctx` together.
+ */
+type AuthResult<C extends Contract> = {
+    [R in RoleOf<C>]: {
+        role: R;
+        ctx: unknown;
+    };
+}[RoleOf<C>];
+type CtxFor<A, R> = A extends {
+    role: R;
+    ctx: infer X;
+} ? X : never;
+type CtxUnion<A> = A extends {
+    ctx: infer X;
+} ? X : never;
+type RoleHandlers<C extends Contract, A, R extends RoleOf<C>> = {
+    [K in keyof RoleRequests<C, R>]: (input: ServerInput<RoleRequests<C, R>[K]>, ctx: CtxFor<A, R>, conn: Conn<Events<C, R>, CtxFor<A, R>, R>) => Awaitable<Output<RoleRequests<C, R>[K]>>;
+};
+type SharedHandlers<C extends Contract, A> = {
+    [K in keyof SharedRequests<C>]: (input: ServerInput<SharedRequests<C>[K]>, ctx: CtxUnion<A>, conn: Conn<SharedEvents<C>, CtxUnion<A>, RoleOf<C>>) => Awaitable<Output<SharedRequests<C>[K]>>;
+};
+/**
+ * The handler map passed to `implement`: one block per role plus an optional
+ * `shared` block. Each handler's `input`/`ctx`/`conn` are narrowed to its role.
+ * The `shared` key is required only when the contract has shared requests.
+ */
+type Handlers<C extends Contract, A> = ([keyof SharedRequests<C>] extends [never] ? {} : {
+    shared: SharedHandlers<C, A>;
+}) & {
+    [R in RoleOf<C>]: RoleHandlers<C, A, R>;
+};
+/** Context passed to middleware and lifecycle hooks about the current operation. */
+interface MiddlewareInfo {
+    /** Whether this is a request or a topic subscribe. */
+    kind: 'request' | 'subscribe';
+    /** The request/topic name. */
+    name: string;
+    /** The connection the operation is on (`conn.role` available). */
+    conn: Conn;
+}
+/**
+ * Flat middleware run before request/subscribe handlers. Call `next()` to proceed,
+ * or `throw` to short-circuit (rejecting the operation). Does not change `ctx`'s type.
+ */
+type Middleware<A> = (ctx: CtxUnion<A>, info: MiddlewareInfo, next: () => Promise<void>) => Awaitable<void>;
+/**
+ * A mixed-role, server-controlled connection group. `broadcast` delivers a
+ * **shared** event to every member, regardless of their role.
+ */
+interface Room<C extends Contract> {
+    /** Add a connection to the room (server-controlled membership). */
+    add(conn: Conn): void;
+    /** Remove a connection from the room. */
+    remove(conn: Conn): void;
+    /** Broadcast a shared event to all members. */
+    broadcast<E extends keyof SharedEvents<C>>(event: E, data: EmitData<SharedEvents<C>[E]>): void;
+    /** Member count **on the current node** (membership is node-local). */
+    readonly size: number;
+}
+/** Lens for role-scoped server sends, returned by `srv.forRole(role)`. */
+interface RoleLens<C extends Contract, R extends RoleOf<C>> {
+    /** Publish to a topic in role `R`'s surface (reaches that role's subscribers). */
+    publish<T extends keyof RoleTopics<C, R>>(topic: T, data: EmitData<RoleTopics<C, R>[T]>): void;
+}
+/** Options for {@link createSocketServer}. */
+interface ServerOptions<C extends Contract, A extends AuthResult<C>> {
+    /** The `http.Server` to attach to (compose with Express/Fastify/Hono). */
+    server?: Server;
+    /** 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;
+    /** Runs at the HTTP upgrade. Return { role, ctx }, or throw to reject with 401. */
+    authenticate: (req: IncomingMessage) => Awaitable<A>;
+    /** Runs on each client subscribe. Return false or throw to deny. */
+    authorizeSubscribe?: (topic: string, ctx: CtxUnion<A>, conn: Conn) => Awaitable<boolean | void>;
+    /** Middleware chain run before req/subscribe handlers (rate-limit, authz, logging, metrics). */
+    use?: Middleware<A>[];
+    /** Called once per accepted connection. */
+    onConnection?: (conn: Conn, ctx: CtxUnion<A>) => void;
+    /** Called when a connection closes, with the WebSocket close `code`. */
+    onDisconnect?: (conn: Conn, ctx: CtxUnion<A>, code: number) => void;
+    /** Called for any error thrown in middleware/handlers (after the client is replied to). */
+    onError?: (error: unknown, info: MiddlewareInfo) => void;
+}
+/** A running super-line server, returned by {@link createSocketServer}. */
+interface SocketServer<C extends Contract, A extends AuthResult<C>> {
+    /** Register handlers for shared + per-role requests (chainable). */
+    implement(handlers: Handlers<C, A>): SocketServer<C, A>;
+    /** Mixed-role connection group; broadcast() sends a shared contract event to members. */
+    room(name: string): Room<C>;
+    /** Publish a SHARED topic to all subscribers (server-only publish). */
+    publish<T extends keyof SharedTopics<C>>(topic: T, data: EmitData<SharedTopics<C>[T]>): void;
+    /** Lens for role-scoped sends, e.g. forRole('user').publish('feed', data). */
+    forRole<R extends RoleOf<C>>(role: R): RoleLens<C, R>;
+    /** Broadcast a typed event to all OTHER server nodes (at-most-once, excludes self). */
+    emitServer<E extends keyof ServerEvents<C>>(event: E, data: ServerEmit<ServerEvents<C>[E]>): void;
+    /** Listen for inter-server events from other nodes. Returns an unsubscribe fn. */
+    onServer<E extends keyof ServerEvents<C>>(event: E, handler: (data: ServerData<ServerEvents<C>[E]>) => void): () => void;
+    close(): Promise<void>;
+}
+/**
+ * Create a server bound to a contract. Attach it to an `http.Server`, then call
+ * {@link SocketServer.implement} with your handlers. `authenticate` resolves each
+ * connection's `{ role, ctx }` at the upgrade.
+ *
+ * @param contract - the shared contract.
+ * @param opts - server options; `authenticate` is required.
+ * @returns the {@link SocketServer}.
+ * @throws nothing directly; handler throws become a typed `SocketError` to the client.
+ *
+ * @example
+ * ```ts
+ * const srv = createSocketServer(api, {
+ *   server,
+ *   authenticate: (req) => ({ role: 'user' as const, ctx: { id: '1' } }),
+ * })
+ * srv.implement({
+ *   shared: { join: async ({ room }, _ctx, conn) => { srv.room(room).add(conn); return { ok: true } } },
+ *   user:   { say:  async ({ text }, ctx)        => ({ id: '...' }) },
+ * })
+ * ```
+ */
+declare function createSocketServer<C extends Contract, A extends AuthResult<C>>(contract: C, opts: ServerOptions<C, A>): SocketServer<C, A>;
+
+export { type AuthResult, Conn, type Handlers, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type ServerOptions, type SocketServer, createInMemoryAdapter, createSocketServer };

package/dist/index.js

@@ -0,0 +1,328 @@
+// src/index.ts
+import { randomUUID } from "crypto";
+import { WebSocketServer } from "ws";
+import {
+  jsonSerializer,
+  validate,
+  SocketError
+} from "@super-line/core";
+
+// src/conn.ts
+var Conn = class {
+  constructor(ws, role, ctx, serializer) {
+    this.ws = ws;
+    this.role = role;
+    this.ctx = ctx;
+    this.serializer = serializer;
+  }
+  ws;
+  role;
+  ctx;
+  serializer;
+  /** Namespaced channels (rooms + topics) this connection belongs to. */
+  channels = /* @__PURE__ */ new Set();
+  /** Encode and send a frame (unicast, e.g. req/res). */
+  send(frame) {
+    if (this.ws.readyState !== this.ws.OPEN) return;
+    this.ws.send(this.serializer.encode(frame));
+  }
+  /** Forward an already-encoded frame (fan-out path; encoded once at the source). */
+  sendRaw(payload) {
+    if (this.ws.readyState !== this.ws.OPEN) return;
+    this.ws.send(payload);
+  }
+  /** Push an event to THIS connection (node-local). Scoped to the role's events. */
+  emit(event, data) {
+    this.send({ t: "evt", e: String(event), d: data });
+  }
+  /** Close the underlying socket. */
+  close() {
+    this.ws.close();
+  }
+};
+
+// src/memory-adapter.ts
+var MemoryBus = class {
+  channels = /* @__PURE__ */ new Map();
+  subscribe(channel, adapter) {
+    let set = this.channels.get(channel);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.channels.set(channel, set);
+    }
+    set.add(adapter);
+  }
+  unsubscribe(channel, adapter) {
+    const set = this.channels.get(channel);
+    if (!set) return;
+    set.delete(adapter);
+    if (set.size === 0) this.channels.delete(channel);
+  }
+  publish(channel, payload) {
+    const set = this.channels.get(channel);
+    if (!set) return;
+    for (const adapter of set) adapter.deliver(channel, payload);
+  }
+};
+var MemoryAdapter = class {
+  constructor(bus) {
+    this.bus = bus;
+  }
+  bus;
+  handler;
+  subscribe(channel) {
+    this.bus.subscribe(channel, this);
+  }
+  unsubscribe(channel) {
+    this.bus.unsubscribe(channel, this);
+  }
+  publish(channel, payload) {
+    this.bus.publish(channel, payload);
+  }
+  onMessage(handler) {
+    this.handler = handler;
+  }
+  deliver(channel, payload) {
+    this.handler?.(channel, payload);
+  }
+};
+function createInMemoryAdapter(bus = new MemoryBus()) {
+  return new MemoryAdapter(bus);
+}
+
+// src/index.ts
+var ROOM = "r:";
+var TOPIC = "t:";
+var S2S = "s2s";
+function createSocketServer(contract, opts) {
+  const c = contract;
+  const serializer = opts.serializer ?? jsonSerializer;
+  const adapter = opts.adapter ?? createInMemoryAdapter();
+  const wss = new WebSocketServer({ noServer: true });
+  const conns = /* @__PURE__ */ new Set();
+  const members = /* @__PURE__ */ new Map();
+  const serverListeners = /* @__PURE__ */ new Map();
+  const instanceId = randomUUID();
+  let impl = {};
+  adapter.onMessage((channel, payload) => {
+    if (channel === S2S) {
+      handleServerMessage(payload);
+      return;
+    }
+    const set = members.get(channel);
+    if (!set) return;
+    for (const conn of set) conn.sendRaw(payload);
+  });
+  if (c.serverToServer) void adapter.subscribe(S2S);
+  function handleServerMessage(payload) {
+    let msg;
+    try {
+      msg = serializer.decode(payload);
+    } catch {
+      return;
+    }
+    if (msg.from === instanceId) return;
+    const set = serverListeners.get(msg.e);
+    if (set) for (const cb of set) cb(msg.d);
+  }
+  function joinChannel(conn, channel) {
+    conn.channels.add(channel);
+    const set = members.get(channel);
+    if (set) {
+      set.add(conn);
+      return;
+    }
+    members.set(channel, /* @__PURE__ */ new Set([conn]));
+    return adapter.subscribe(channel);
+  }
+  function leaveChannel(conn, channel) {
+    const set = members.get(channel);
+    if (!set) return;
+    set.delete(conn);
+    conn.channels.delete(channel);
+    if (set.size === 0) {
+      members.delete(channel);
+      void adapter.unsubscribe(channel);
+    }
+  }
+  function topicNamespace(role, name) {
+    if (c.roles[role]?.serverToClient?.[name]?.subscribe) return role;
+    if (c.shared?.serverToClient?.[name]?.subscribe) return "shared";
+    return void 0;
+  }
+  if (opts.server) {
+    opts.server.on("upgrade", (req, socket, head) => {
+      void handleUpgrade(req, socket, head);
+    });
+  }
+  async function handleUpgrade(req, socket, head) {
+    if (opts.path) {
+      const { pathname } = new URL(req.url ?? "/", "http://localhost");
+      if (pathname !== opts.path) return;
+    }
+    let auth;
+    try {
+      auth = await opts.authenticate(req);
+    } catch {
+      socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      const conn = new Conn(ws, auth.role, auth.ctx, serializer);
+      conns.add(conn);
+      ws.on("message", (data, isBinary) => {
+        void onMessage(conn, data, isBinary);
+      });
+      ws.on("close", (code) => {
+        conns.delete(conn);
+        for (const channel of conn.channels) leaveChannel(conn, channel);
+        opts.onDisconnect?.(conn, auth.ctx, code);
+      });
+      opts.onConnection?.(conn, auth.ctx);
+    });
+  }
+  async function onMessage(conn, data, isBinary) {
+    let frame;
+    try {
+      frame = serializer.decode(toWire(data, isBinary));
+    } catch {
+      return;
+    }
+    if (frame.t === "req") await handleReq(conn, frame);
+    else if (frame.t === "sub") await handleSub(conn, frame);
+    else if (frame.t === "unsub") {
+      const ns = topicNamespace(conn.role, frame.c);
+      if (ns) leaveChannel(conn, TOPIC + ns + ":" + frame.c);
+    }
+  }
+  function runMiddleware(info, terminal) {
+    const chain = opts.use ?? [];
+    let last = -1;
+    const dispatch = (idx) => {
+      if (idx <= last) return Promise.reject(new Error("next() called multiple times"));
+      last = idx;
+      const mw = chain[idx];
+      if (!mw) return terminal();
+      return Promise.resolve(mw(info.conn.ctx, info, () => dispatch(idx + 1)));
+    };
+    return dispatch(0);
+  }
+  async function dispatchOp(conn, id, info, terminal) {
+    let responded = false;
+    try {
+      await runMiddleware(info, async () => {
+        await terminal();
+        responded = true;
+      });
+    } catch (err) {
+      opts.onError?.(err, info);
+      if (!responded) {
+        const e = err instanceof SocketError ? err : new SocketError("INTERNAL", "Internal server error");
+        conn.send({ t: "err", i: id, code: e.code, m: e.message, d: e.data });
+      }
+    }
+  }
+  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];
+    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);
+      const output = await handler(input, conn.ctx, conn);
+      conn.send({ t: "res", i: frame.i, d: output });
+    });
+  }
+  async function handleSub(conn, frame) {
+    const ns = topicNamespace(conn.role, frame.c);
+    if (!ns) {
+      conn.send({ t: "err", i: frame.i, code: "NOT_FOUND", m: `Unknown topic: ${frame.c}` });
+      return;
+    }
+    await dispatchOp(conn, frame.i, { kind: "subscribe", name: frame.c, conn }, async () => {
+      if (opts.authorizeSubscribe) {
+        const ok = await opts.authorizeSubscribe(frame.c, conn.ctx, conn);
+        if (ok === false) throw new SocketError("FORBIDDEN", `Subscribe denied: ${frame.c}`);
+      }
+      await joinChannel(conn, TOPIC + ns + ":" + frame.c);
+      conn.send({ t: "res", i: frame.i, d: null });
+    });
+  }
+  function room(name) {
+    const channel = ROOM + name;
+    return {
+      add(conn) {
+        void joinChannel(conn, channel);
+      },
+      remove(conn) {
+        leaveChannel(conn, channel);
+      },
+      broadcast(event, data) {
+        void adapter.publish(channel, serializer.encode({ t: "evt", e: String(event), d: data }));
+      },
+      get size() {
+        return members.get(channel)?.size ?? 0;
+      }
+    };
+  }
+  function publishTo(ns, name, data) {
+    void adapter.publish(TOPIC + ns + ":" + name, serializer.encode({ t: "pub", c: name, d: data }));
+  }
+  const api = {
+    implement(handlers) {
+      impl = handlers;
+      return api;
+    },
+    room,
+    publish(topic, data) {
+      publishTo("shared", String(topic), data);
+    },
+    forRole(role) {
+      return {
+        publish(topic, data) {
+          publishTo(role, String(topic), data);
+        }
+      };
+    },
+    emitServer(event, data) {
+      void adapter.publish(S2S, serializer.encode({ from: instanceId, e: String(event), d: data }));
+    },
+    onServer(event, handler) {
+      const name = String(event);
+      let set = serverListeners.get(name);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        serverListeners.set(name, set);
+      }
+      set.add(handler);
+      return () => {
+        const current = serverListeners.get(name);
+        if (!current) return;
+        current.delete(handler);
+        if (current.size === 0) serverListeners.delete(name);
+      };
+    },
+    async close() {
+      for (const conn of conns) conn.close();
+      await adapter.close?.();
+      await new Promise((resolve) => {
+        wss.close(() => resolve());
+      });
+    }
+  };
+  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,
+  createInMemoryAdapter,
+  createSocketServer
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@super-line/server",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Typesafe WebSocket server for super-line — rooms, topics, middleware, pluggable adapters.",
+  "license": "MIT",
+  "author": "Mert",
+  "keywords": [
+    "websocket",
+    "server",
+    "typesafe",
+    "realtime",
+    "rooms",
+    "pubsub",
+    "ws"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mertdogar/super-line.git",
+    "directory": "packages/server"
+  },
+  "homepage": "https://mertdogar.github.io/super-line/",
+  "bugs": "https://github.com/mertdogar/super-line/issues",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ws": "^8.18.0",
+    "@super-line/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.13",
+    "testcontainers": "^10.13.2",
+    "zod": "^3.24.1",
+    "@super-line/adapter-redis": "0.1.0",
+    "@super-line/client": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup"
+  }
+}