@openlivesync/server 1.0.2

package/src/server.test.ts

@@ -0,0 +1,223 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import * as http from "node:http";
+import { WebSocket } from "ws";
+import {
+  createServer,
+  createWebSocketServer,
+  createWebSocketHandler,
+  createInMemoryChatStorage,
+} from "./index.js";
+import { MSG_JOIN_ROOM, MSG_ROOM_JOINED, MSG_SEND_CHAT, MSG_CHAT_MESSAGE } from "./protocol.js";
+
+describe("WebSocket server integration", () => {
+  let server: http.Server;
+  let port: number;
+  const path = "/live";
+
+  beforeAll(async () => {
+    const storage = createInMemoryChatStorage({ historyLimit: 10 });
+    server = http.createServer((_req, res) => {
+      res.writeHead(200);
+      res.end();
+    });
+    createWebSocketServer(server, {
+      path,
+      chat: { storage, historyLimit: 10 },
+    });
+    await new Promise<void>((resolve) => {
+      server.listen(0, () => {
+        const addr = server.address();
+        port = typeof addr === "object" && addr && "port" in addr ? addr.port : 0;
+        resolve();
+      });
+    });
+  });
+
+  afterAll(() => {
+    return new Promise<void>((resolve) => server.close(() => resolve()));
+  });
+
+  it("responds to join_room with room_joined", async () => {
+    const ws = new WebSocket(`ws://127.0.0.1:${port}${path}`);
+    const messages: unknown[] = [];
+    ws.on("message", (data) => messages.push(JSON.parse(data.toString())));
+
+    await new Promise<void>((resolve) => {
+      ws.on("open", () => {
+        ws.send(
+          JSON.stringify({
+            type: MSG_JOIN_ROOM,
+            payload: { roomId: "test-room", presence: { name: "alice" } },
+          })
+        );
+        const check = (): void => {
+          const roomJoined = messages.find((m: { type?: string }) => m?.type === MSG_ROOM_JOINED);
+          if (roomJoined) {
+            resolve();
+            return;
+          }
+          setTimeout(check, 20);
+        };
+        setTimeout(check, 50);
+      });
+    });
+
+    const roomJoined = messages.find((m: { type?: string }) => m?.type === MSG_ROOM_JOINED) as {
+      type: string;
+      payload: {
+        roomId: string;
+        connectionId: string;
+        presence: Record<string, { connectionId: string; presence?: unknown }>;
+      };
+    };
+    expect(roomJoined).toBeDefined();
+    expect(roomJoined.payload.roomId).toBe("test-room");
+    expect(roomJoined.payload.connectionId).toBeDefined();
+    const presenceEntries = Object.values(roomJoined.payload.presence);
+    expect(presenceEntries.length).toBe(1);
+    expect(presenceEntries[0].connectionId).toBe(roomJoined.payload.connectionId);
+
+    ws.close();
+  });
+
+  it("broadcasts chat to same room", async () => {
+    const storage = createInMemoryChatStorage({ historyLimit: 10 });
+    const srv = http.createServer((_req, res) => {
+      res.writeHead(200);
+      res.end();
+    });
+    createWebSocketServer(srv, { path: "/chat", chat: { storage, historyLimit: 10 } });
+    await new Promise<void>((resolve) => {
+      srv.listen(0, () => resolve());
+    });
+    const addr = srv.address();
+    const p = typeof addr === "object" && addr && "port" in addr ? addr.port : 0;
+
+    const ws1 = new WebSocket(`ws://127.0.0.1:${p}/chat`);
+    const msgs1: unknown[] = [];
+    ws1.on("message", (data) => msgs1.push(JSON.parse(data.toString())));
+
+    await new Promise<void>((resolve) => {
+      ws1.on("open", () => {
+        ws1.send(JSON.stringify({ type: MSG_JOIN_ROOM, payload: { roomId: "chat-room" } }));
+        const check = (): void => {
+          if (msgs1.some((m: { type?: string }) => m?.type === MSG_ROOM_JOINED)) {
+            resolve();
+            return;
+          }
+          setTimeout(check, 20);
+        };
+        setTimeout(check, 50);
+      });
+    });
+
+    const ws2 = new WebSocket(`ws://127.0.0.1:${p}/chat`);
+    const msgs2: unknown[] = [];
+    ws2.on("message", (data) => msgs2.push(JSON.parse(data.toString())));
+
+    await new Promise<void>((resolve) => {
+      ws2.on("open", () => {
+        ws2.send(JSON.stringify({ type: MSG_JOIN_ROOM, payload: { roomId: "chat-room" } }));
+        const check = (): void => {
+          if (msgs2.some((m: { type?: string }) => m?.type === MSG_ROOM_JOINED)) {
+            resolve();
+            return;
+          }
+          setTimeout(check, 20);
+        };
+        setTimeout(check, 50);
+      });
+    });
+
+    ws1.send(
+      JSON.stringify({ type: MSG_SEND_CHAT, payload: { message: "hello from 1" } })
+    );
+
+    await new Promise<void>((resolve) => {
+      const check = (): void => {
+        const chatOn2 = msgs2.some(
+          (m: { type?: string }) => m?.type === MSG_CHAT_MESSAGE && (m as { payload?: { message?: string } }).payload?.message === "hello from 1"
+        );
+        if (chatOn2) {
+          resolve();
+          return;
+        }
+        setTimeout(check, 50);
+      };
+      setTimeout(check, 100);
+    });
+
+    const chatMsg = msgs2.find(
+      (m: { type?: string; payload?: { message?: string } }) =>
+        m?.type === MSG_CHAT_MESSAGE && m?.payload?.message === "hello from 1"
+    );
+    expect(chatMsg).toBeDefined();
+
+    ws1.close();
+    ws2.close();
+    await new Promise<void>((resolve) => srv.close(() => resolve()));
+  });
+});
+
+describe("createServer and createWebSocketHandler", () => {
+  it("createServer returns server with .ws WebSocketServer", async () => {
+    const server = createServer({ port: 0 });
+    expect(server).toBeDefined();
+    expect((server as { ws?: unknown }).ws).toBeDefined();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  });
+
+  it("createWebSocketHandler ignores upgrade on wrong path", () => {
+    const handler = createWebSocketHandler({ path: "/live" });
+    const request = { url: "/other" } as http.IncomingMessage;
+    const socket = { destroy: () => {} } as import("node:stream").Duplex;
+    const head = Buffer.alloc(0);
+    expect(() => handler(request, socket, head)).not.toThrow();
+  });
+
+  it("onAuth returning null closes connection with 4401", async () => {
+    const srv = http.createServer((_req, res) => {
+      res.writeHead(200);
+      res.end();
+    });
+    createWebSocketServer(srv, {
+      path: "/auth",
+      onAuth: async () => null,
+    });
+    await new Promise<void>((resolve) => srv.listen(0, () => resolve()));
+    const addr = srv.address();
+    const port = typeof addr === "object" && addr && "port" in addr ? addr.port : 0;
+
+    const ws = new WebSocket(`ws://127.0.0.1:${port}/auth`);
+    const closeEvent = await new Promise<{ code: number }>((resolve) => {
+      ws.on("close", (code: number) => resolve({ code }));
+    });
+    expect(closeEvent.code).toBe(4401);
+
+    await new Promise<void>((resolve) => srv.close(() => resolve()));
+  });
+
+  it("onAuth throwing closes connection with 4500", async () => {
+    const srv = http.createServer((_req, res) => {
+      res.writeHead(200);
+      res.end();
+    });
+    createWebSocketServer(srv, {
+      path: "/auth2",
+      onAuth: async () => {
+        throw new Error("auth failed");
+      },
+    });
+    await new Promise<void>((resolve) => srv.listen(0, () => resolve()));
+    const addr = srv.address();
+    const port = typeof addr === "object" && addr && "port" in addr ? addr.port : 0;
+
+    const ws = new WebSocket(`ws://127.0.0.1:${port}/auth2`);
+    const closeEvent = await new Promise<{ code: number }>((resolve) => {
+      ws.on("close", (code: number) => resolve({ code }));
+    });
+    expect(closeEvent.code).toBe(4500);
+
+    await new Promise<void>((resolve) => srv.close(() => resolve()));
+  });
+});

package/src/server.ts

@@ -0,0 +1,153 @@
+/**
+ * createServer, createWebSocketServer, createWebSocketHandler.
+ */
+
+import * as http from "node:http";
+import { randomUUID } from "node:crypto";
+import { WebSocketServer, WebSocket } from "ws";
+import { createInMemoryChatStorage } from "./storage/in-memory.js";
+import type { ChatStorage } from "./storage/chat-storage.js";
+import type { UserInfo } from "./protocol.js";
+import type { AuthOptions } from "./auth/index.js";
+import { RoomManager } from "./room-manager.js";
+import { Connection } from "./connection.js";
+
+const DEFAULT_PATH = "/live";
+const DEFAULT_PRESENCE_THROTTLE_MS = 100;
+const DEFAULT_HISTORY_LIMIT = 100;
+
+export interface ChatOptions {
+  storage?: ChatStorage;
+  historyLimit?: number;
+}
+
+export interface WebSocketServerOptions {
+  /** WebSocket upgrade path (default: "/live"). */
+  path?: string;
+  /** If provided and returns null, connection is rejected. */
+  onAuth?: (request: http.IncomingMessage) => Promise<UserInfo | null>;
+  /** Optional: decode/verify access tokens in join_room (Google, Microsoft, custom OAuth). */
+  auth?: AuthOptions;
+  /** Min interval between presence updates per connection in ms (default: 100). */
+  presenceThrottleMs?: number;
+  /** Chat storage and history limit. If storage omitted, uses in-memory. */
+  chat?: ChatOptions;
+}
+
+export interface ServerOptions extends WebSocketServerOptions {
+  /** Port for standalone server (default: 3000). */
+  port?: number;
+}
+
+function randomConnectionId(): string {
+  return randomUUID();
+}
+
+function createRoomManager(options: WebSocketServerOptions): RoomManager {
+  const chat = options.chat ?? {};
+  const storage = chat.storage ?? createInMemoryChatStorage({ historyLimit: chat.historyLimit ?? DEFAULT_HISTORY_LIMIT });
+  const historyLimit = chat.historyLimit ?? DEFAULT_HISTORY_LIMIT;
+  return new RoomManager({ chatStorage: storage, historyLimit });
+}
+
+function handleUpgrade(
+  wss: WebSocketServer,
+  options: WebSocketServerOptions,
+  roomManager: RoomManager,
+  request: http.IncomingMessage,
+  socket: import("node:stream").Duplex,
+  head: Buffer
+): void {
+  const path = options.path ?? DEFAULT_PATH;
+  const url = request.url ?? "";
+  const pathname = url.split("?")[0];
+  if (pathname !== path) return;
+
+  wss.handleUpgrade(request, socket, head, (ws: WebSocket) => {
+    wss.emit("connection", ws, request);
+    const connectionId = randomConnectionId();
+    let authResult: UserInfo | null = {};
+
+    const proceed = (): void => {
+      const presenceThrottleMs = options.presenceThrottleMs ?? DEFAULT_PRESENCE_THROTTLE_MS;
+      new Connection(ws, {
+        connectionId,
+        userId: authResult?.userId,
+        userName: authResult?.name,
+        userEmail: authResult?.email,
+        provider: authResult?.provider,
+        presenceThrottleMs,
+        roomManager,
+        auth: options.auth,
+      });
+    };
+
+    if (options.onAuth) {
+      options.onAuth(request).then((result) => {
+        authResult = result;
+        if (result === null) {
+          ws.close(4401, "Unauthorized");
+          return;
+        }
+        proceed();
+      }).catch(() => {
+        ws.close(4500, "Auth error");
+      });
+    } else {
+      proceed();
+    }
+  });
+}
+
+/**
+ * Returns the raw upgrade handler. Attach to your HTTP server with
+ * server.on('upgrade', handler).
+ */
+export function createWebSocketHandler(
+  options: WebSocketServerOptions = {}
+): (request: http.IncomingMessage, socket: import("node:stream").Duplex, head: Buffer) => void {
+  const roomManager = createRoomManager(options);
+  const wss = new WebSocketServer({ noServer: true });
+  const path = options.path ?? DEFAULT_PATH;
+
+  return (request: http.IncomingMessage, socket: import("node:stream").Duplex, head: Buffer) => {
+    const url = request.url ?? "";
+    const pathname = url.split("?")[0];
+    if (pathname !== path) return;
+    handleUpgrade(wss, options, roomManager, request, socket, head);
+  };
+}
+
+/**
+ * Attaches WebSocket upgrade handling to an existing Node HTTP server.
+ * Returns the WebSocketServer instance (e.g. for closing later).
+ */
+export function createWebSocketServer(
+  server: http.Server,
+  options: WebSocketServerOptions = {}
+): WebSocketServer {
+  const roomManager = createRoomManager(options);
+  const wss = new WebSocketServer({ noServer: true });
+
+  server.on("upgrade", (request: http.IncomingMessage, socket: import("node:stream").Duplex, head: Buffer) => {
+    handleUpgrade(wss, options, roomManager, request, socket, head);
+  });
+
+  return wss;
+}
+
+/**
+ * Creates an HTTP server with a simple root handler and WebSocket support.
+ * Returns the server and the WebSocketServer (as server.ws).
+ */
+export function createServer(options: ServerOptions = {}): http.Server & { ws: WebSocketServer } {
+  const port = options.port ?? 3000;
+  const server = http.createServer((_req, res) => {
+    res.writeHead(200, { "Content-Type": "text/plain" });
+    res.end("openlivesync");
+  });
+  const wss = createWebSocketServer(server, options);
+  (server as http.Server & { ws: WebSocketServer }).ws = wss;
+  server.listen(port);
+  return server as http.Server & { ws: WebSocketServer };
+}

package/src/storage/chat-storage.ts

@@ -0,0 +1,23 @@
+/**
+ * Chat storage interface for pluggable persistence.
+ * Implementations: in-memory, Postgres, MySQL, SQLite.
+ */
+
+import type { ChatMessageInput, StoredChatMessage } from "../protocol.js";
+
+export type { ChatMessageInput };
+
+/**
+ * Pluggable chat storage. Pass an implementation into server options
+ * via chat.storage. Omit to use default in-memory storage.
+ */
+export interface ChatStorage {
+  /** Append a message to the room's history. */
+  append(roomId: string, message: ChatMessageInput): Promise<void>;
+
+  /** Get messages for a room. Order: oldest first. Use limit and optional offset for pagination. */
+  getHistory(roomId: string, limit?: number, offset?: number): Promise<StoredChatMessage[]>;
+
+  /** Optional: release connections / cleanup. */
+  close?(): Promise<void>;
+}

package/src/storage/db-types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Minimal type declarations for optional DB drivers.
+ * Install pg / mysql2 / better-sqlite3 only when using those adapters.
+ */
+declare module "pg" {
+  export interface PoolConfig {
+    connectionString?: string;
+    host?: string;
+    port?: number;
+    database?: string;
+    user?: string;
+    password?: string;
+    [key: string]: unknown;
+  }
+  export class Pool {
+    constructor(config?: PoolConfig);
+    query(text: string, values?: unknown[]): Promise<{ rows: unknown[] }>;
+    end(): Promise<void>;
+  }
+}
+
+declare module "mysql2/promise" {
+  export function createPool(config: Record<string, unknown>): {
+    query<T>(sql: string, values?: unknown[]): Promise<[T]>;
+    end(): Promise<void>;
+  };
+}
+
+declare module "better-sqlite3" {
+  interface BetterSqlite3Database {
+    exec(sql: string): this;
+    prepare(sql: string): {
+      run(...params: unknown[]): unknown;
+      all(...params: unknown[]): unknown[];
+    };
+    close(): void;
+  }
+  interface DatabaseConstructor {
+    new (filename: string, options?: Record<string, unknown>): BetterSqlite3Database;
+  }
+  const Database: DatabaseConstructor;
+  export default Database;
+}

package/src/storage/in-memory.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from "vitest";
+import { createInMemoryChatStorage } from "./in-memory.js";
+
+describe("createInMemoryChatStorage", () => {
+  it("appends messages and returns them oldest first", async () => {
+    const storage = createInMemoryChatStorage({ historyLimit: 10 });
+    await storage.append("room1", {
+      roomId: "room1",
+      connectionId: "c1",
+      message: "first",
+    });
+    await storage.append("room1", {
+      roomId: "room1",
+      connectionId: "c2",
+      message: "second",
+    });
+    const history = await storage.getHistory("room1");
+    expect(history).toHaveLength(2);
+    expect(history[0].message).toBe("first");
+    expect(history[1].message).toBe("second");
+    expect(history[0].connectionId).toBe("c1");
+    expect(history[1].connectionId).toBe("c2");
+  });
+
+  it("respects limit", async () => {
+    const storage = createInMemoryChatStorage({ historyLimit: 100 });
+    for (let i = 0; i < 5; i++) {
+      await storage.append("room1", {
+        roomId: "room1",
+        connectionId: "c1",
+        message: `msg${i}`,
+      });
+    }
+    const all = await storage.getHistory("room1", 100);
+    expect(all).toHaveLength(5);
+    const limited = await storage.getHistory("room1", 2);
+    expect(limited).toHaveLength(2);
+    expect(limited[0].message).toBe("msg0");
+    expect(limited[1].message).toBe("msg1");
+  });
+
+  it("respects offset for pagination", async () => {
+    const storage = createInMemoryChatStorage({ historyLimit: 100 });
+    for (let i = 0; i < 5; i++) {
+      await storage.append("room1", {
+        roomId: "room1",
+        connectionId: "c1",
+        message: `msg${i}`,
+      });
+    }
+    const page = await storage.getHistory("room1", 2, 2);
+    expect(page).toHaveLength(2);
+    expect(page[0].message).toBe("msg2");
+    expect(page[1].message).toBe("msg3");
+  });
+
+  it("returns empty for unknown room", async () => {
+    const storage = createInMemoryChatStorage();
+    const history = await storage.getHistory("nonexistent");
+    expect(history).toEqual([]);
+  });
+
+  it("keeps at most historyLimit messages per room", async () => {
+    const storage = createInMemoryChatStorage({ historyLimit: 3 });
+    for (let i = 0; i < 5; i++) {
+      await storage.append("room1", {
+        roomId: "room1",
+        connectionId: "c1",
+        message: `msg${i}`,
+      });
+    }
+    const history = await storage.getHistory("room1", 10);
+    expect(history).toHaveLength(3);
+    expect(history.map((m) => m.message)).toEqual(["msg2", "msg3", "msg4"]);
+  });
+
+  it("isolates rooms", async () => {
+    const storage = createInMemoryChatStorage({ historyLimit: 10 });
+    await storage.append("room1", {
+      roomId: "room1",
+      connectionId: "c1",
+      message: "in room1",
+    });
+    await storage.append("room2", {
+      roomId: "room2",
+      connectionId: "c1",
+      message: "in room2",
+    });
+    const h1 = await storage.getHistory("room1");
+    const h2 = await storage.getHistory("room2");
+    expect(h1).toHaveLength(1);
+    expect(h2).toHaveLength(1);
+    expect(h1[0].message).toBe("in room1");
+    expect(h2[0].message).toBe("in room2");
+  });
+});

package/src/storage/in-memory.ts

@@ -0,0 +1,52 @@
+/**
+ * In-memory chat storage. Keeps last N messages per room.
+ * No DB required; default when no storage is configured.
+ */
+
+import type { ChatMessageInput, StoredChatMessage } from "../protocol.js";
+import type { ChatStorage } from "./chat-storage.js";
+
+export interface InMemoryChatStorageOptions {
+  /** Max messages to keep per room (default 100). */
+  historyLimit?: number;
+}
+
+const DEFAULT_HISTORY_LIMIT = 100;
+
+export function createInMemoryChatStorage(
+  options: InMemoryChatStorageOptions = {}
+): ChatStorage {
+  const historyLimit = options.historyLimit ?? DEFAULT_HISTORY_LIMIT;
+  const store = new Map<string, StoredChatMessage[]>();
+  let idCounter = 0;
+
+  return {
+    async append(roomId: string, message: ChatMessageInput): Promise<void> {
+      const list = store.get(roomId) ?? [];
+      const stored: StoredChatMessage = {
+        id: `msg_${++idCounter}_${Date.now()}`,
+        roomId,
+        connectionId: message.connectionId,
+        userId: message.userId,
+        message: message.message,
+        metadata: message.metadata,
+        createdAt: Date.now(),
+      };
+      list.push(stored);
+      if (list.length > historyLimit) {
+        list.splice(0, list.length - historyLimit);
+      }
+      store.set(roomId, list);
+    },
+
+    async getHistory(
+      roomId: string,
+      limit: number = historyLimit,
+      offset: number = 0
+    ): Promise<StoredChatMessage[]> {
+      const list = store.get(roomId) ?? [];
+      const start = Math.max(0, offset);
+      return list.slice(start, start + limit);
+    },
+  };
+}