@openlivesync/server 1.0.2

package/src/connection.test.ts

@@ -0,0 +1,339 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { Connection } from "./connection.js";
+import { RoomManager } from "./room-manager.js";
+import { createInMemoryChatStorage } from "./storage/in-memory.js";
+import {
+  MSG_JOIN_ROOM,
+  MSG_LEAVE_ROOM,
+  MSG_UPDATE_PRESENCE,
+  MSG_BROADCAST_EVENT,
+  MSG_SEND_CHAT,
+  MSG_ERROR,
+  MSG_ROOM_JOINED,
+  MSG_CHAT_MESSAGE,
+  MSG_BROADCAST_EVENT_RELAY,
+} from "./protocol.js";
+import { SignJWT } from "jose";
+
+function createMockWs(): {
+  ws: {
+    readyState: number;
+    on: (ev: string, fn: (data?: unknown) => void) => void;
+    emit: (ev: string, data?: unknown) => void;
+    send: (data: string) => void;
+    close: () => void;
+  };
+  sent: unknown[];
+  emitMessage: (data: string | Buffer) => void;
+  emitClose: () => void;
+} {
+  const listeners: Record<string, (data?: unknown) => void> = {};
+  const sent: unknown[] = [];
+  return {
+    ws: {
+      readyState: 1,
+      OPEN: 1,
+      on(ev: string, fn: (data?: unknown) => void) {
+        listeners[ev] = fn;
+      },
+      emit(ev: string, data?: unknown) {
+        if (listeners[ev]) listeners[ev](data);
+      },
+      send(data: string) {
+        sent.push(JSON.parse(data));
+      },
+      close() {
+        listeners["close"]?.();
+      },
+    },
+    sent,
+    emitMessage(data: string | Buffer) {
+      const raw = typeof data === "string" ? data : data.toString("utf8");
+      listeners["message"]?.(raw);
+    },
+    emitClose() {
+      listeners["close"]?.();
+    },
+  };
+}
+
+describe("Connection", () => {
+  let mock: ReturnType<typeof createMockWs>;
+  let roomManager: RoomManager;
+
+  beforeEach(() => {
+    mock = createMockWs();
+    const storage = createInMemoryChatStorage({ historyLimit: 10 });
+    roomManager = new RoomManager({ chatStorage: storage, historyLimit: 10 });
+  });
+
+  it("sends INVALID_JSON error for invalid JSON", () => {
+    new Connection(mock.ws as import("ws").WebSocket, {
+      connectionId: "c1",
+      presenceThrottleMs: 0,
+      roomManager,
+    });
+    mock.emitMessage("not json");
+    expect(mock.sent).toHaveLength(1);
+    expect(mock.sent[0]).toMatchObject({
+      type: MSG_ERROR,
+      payload: { code: "INVALID_JSON", message: "Invalid JSON" },
+    });
+  });
+
+  it("sends INVALID_MESSAGE error for unknown message type", () => {
+    new Connection(mock.ws as import("ws").WebSocket, {
+      connectionId: "c1",
+      presenceThrottleMs: 0,
+      roomManager,
+    });
+    mock.emitMessage(JSON.stringify({ type: "unknown", payload: {} }));
+    expect(mock.sent).toHaveLength(1);
+    expect(mock.sent[0]).toMatchObject({
+      type: MSG_ERROR,
+      payload: { code: "INVALID_MESSAGE", message: "Unknown or invalid message type" },
+    });
+  });
+
+  it("join_room sends room_joined and leave_room cleans up", async () => {
+    new Connection(mock.ws as import("ws").WebSocket, {
+      connectionId: "c1",
+      presenceThrottleMs: 0,
+      roomManager,
+    });
+    mock.emitMessage(
+      JSON.stringify({ type: MSG_JOIN_ROOM, payload: { roomId: "r1", presence: { x: 1 } } })
+    );
+    await vi.waitFor(() => {
+      expect(mock.sent.some((m: { type?: string }) => m?.type === MSG_ROOM_JOINED)).toBe(true);
+    });
+    expect(roomManager.get("r1")?.connectionCount).toBe(1);
+    mock.emitMessage(JSON.stringify({ type: MSG_LEAVE_ROOM, payload: { roomId: "r1" } }));
+    await vi.waitFor(() => {
+      expect(roomManager.get("r1")).toBeUndefined();
+    });
+  });
+
+  it("update_presence is throttled when throttleMs > 0", async () => {
+    const mock1 = createMockWs();
+    const mock2 = createMockWs();
+    new Connection(mock1.ws as import("ws").WebSocket, {
+      connectionId: "c1",
+      presenceThrottleMs: 10000,
+      roomManager,
+    });
+    new Connection(mock2.ws as import("ws").WebSocket, {
+      connectionId: "c2",
+      presenceThrottleMs: 10000,
+      roomManager,
+    });
+    mock1.emitMessage(JSON.stringify({ type: MSG_JOIN_ROOM, payload: { roomId: "r1" } }));
+    mock2.emitMessage(JSON.stringify({ type: MSG_JOIN_ROOM, payload: { roomId: "r1" } }));
+    await vi.waitFor(() => {
+      expect(mock2.sent.some((m: { type?: string }) => m?.type === MSG_ROOM_JOINED)).toBe(true);
+    });
+    mock2.sent.length = 0;
+    mock1.emitMessage(JSON.stringify({ type: MSG_UPDATE_PRESENCE, payload: { presence: { a: 1 } } }));
+    mock1.emitMessage(JSON.stringify({ type: MSG_UPDATE_PRESENCE, payload: { presence: { a: 2 } } }));
+    await new Promise((r) => setTimeout(r, 10));
+    const presenceUpdates = mock2.sent.filter(
+      (m: { type?: string }) => m?.type === "presence_updated"
+    );
+    expect(presenceUpdates.length).toBe(1);
+  });
+
+  it("broadcast_event when not in room does nothing", () => {
+    new Connection(mock.ws as import("ws").WebSocket, {
+      connectionId: "c1",
+      presenceThrottleMs: 0,
+      roomManager,
+    });
+    mock.emitMessage(
+      JSON.stringify({
+        type: MSG_BROADCAST_EVENT,
+        payload: { event: "draw", payload: { x: 1 } },
+      })
+    );
+    expect(mock.sent).toHaveLength(0);
+  });
+
+  it("send_chat when not in room does nothing", async () => {
+    new Connection(mock.ws as import("ws").WebSocket, {
+      connectionId: "c1",
+      presenceThrottleMs: 0,
+      roomManager,
+    });
+    mock.emitMessage(
+      JSON.stringify({ type: MSG_SEND_CHAT, payload: { message: "hi" } })
+    );
+    await new Promise((r) => setTimeout(r, 10));
+    expect(mock.sent).toHaveLength(0);
+  });
+
+  it("handleClose leaves room and removes if empty", async () => {
+    new Connection(mock.ws as import("ws").WebSocket, {
+      connectionId: "c1",
+      presenceThrottleMs: 0,
+      roomManager,
+    });
+    mock.emitMessage(JSON.stringify({ type: MSG_JOIN_ROOM, payload: { roomId: "r1" } }));
+    await vi.waitFor(() => {
+      expect(roomManager.get("r1")?.connectionCount).toBe(1);
+    });
+    mock.emitClose();
+    expect(roomManager.get("r1")).toBeUndefined();
+  });
+
+  it("dispatch error sends SERVER_ERROR", async () => {
+    const fakeRoom = {
+      connectionCount: 0,
+      join: () => Promise.reject(new Error("join failed")),
+      leave: () => {},
+      updatePresence: () => {},
+      broadcastEvent: () => {},
+      sendChat: () => Promise.resolve(),
+    };
+    const roomManagerWithFailingJoin = {
+      get: () => undefined,
+      getOrCreate: () => fakeRoom as import("./room.js").Room,
+      removeIfEmpty: () => {},
+    };
+    new Connection(mock.ws as import("ws").WebSocket, {
+      connectionId: "c1",
+      presenceThrottleMs: 0,
+      roomManager: roomManagerWithFailingJoin as unknown as RoomManager,
+    });
+    mock.emitMessage(JSON.stringify({ type: MSG_JOIN_ROOM, payload: { roomId: "r1" } }));
+    await vi.waitFor(() => {
+      const errMsg = mock.sent.find((m: { type?: string }) => m?.type === MSG_ERROR);
+      expect(errMsg).toBeDefined();
+      expect((errMsg as { payload?: { message?: string } }).payload?.message).toBe("join failed");
+    });
+  });
+
+  it("leave_room with no current room does nothing", () => {
+    new Connection(mock.ws as import("ws").WebSocket, {
+      connectionId: "c1",
+      presenceThrottleMs: 0,
+      roomManager,
+    });
+    mock.emitMessage(JSON.stringify({ type: MSG_LEAVE_ROOM }));
+    expect(mock.sent).toHaveLength(0);
+  });
+
+  it("ignores messages after close", () => {
+    new Connection(mock.ws as import("ws").WebSocket, {
+      connectionId: "c1",
+      presenceThrottleMs: 0,
+      roomManager,
+    });
+    mock.emitClose();
+    mock.emitMessage(JSON.stringify({ type: MSG_JOIN_ROOM, payload: { roomId: "r1" } }));
+    expect(mock.sent).toHaveLength(0);
+  });
+
+  it("joining another room leaves current room and removeIfEmpty clears it", async () => {
+    new Connection(mock.ws as import("ws").WebSocket, {
+      connectionId: "c1",
+      presenceThrottleMs: 0,
+      roomManager,
+    });
+    mock.emitMessage(JSON.stringify({ type: MSG_JOIN_ROOM, payload: { roomId: "r1" } }));
+    await vi.waitFor(() => {
+      expect(roomManager.get("r1")?.connectionCount).toBe(1);
+    });
+    mock.emitMessage(JSON.stringify({ type: MSG_JOIN_ROOM, payload: { roomId: "r2" } }));
+    await vi.waitFor(() => {
+      expect(mock.sent.some((m: { type?: string }) => m?.type === MSG_ROOM_JOINED)).toBe(true);
+    });
+    expect(roomManager.get("r1")).toBeUndefined();
+    expect(roomManager.get("r2")?.connectionCount).toBe(1);
+  });
+
+  it("broadcast_event when in room forwards to room", async () => {
+    const mock2 = createMockWs();
+    new Connection(mock.ws as import("ws").WebSocket, {
+      connectionId: "c1",
+      presenceThrottleMs: 0,
+      roomManager,
+    });
+    new Connection(mock2.ws as import("ws").WebSocket, {
+      connectionId: "c2",
+      presenceThrottleMs: 0,
+      roomManager,
+    });
+    mock.emitMessage(JSON.stringify({ type: MSG_JOIN_ROOM, payload: { roomId: "br" } }));
+    mock2.emitMessage(JSON.stringify({ type: MSG_JOIN_ROOM, payload: { roomId: "br" } }));
+    await vi.waitFor(() => {
+      expect(mock2.sent.some((m: { type?: string }) => m?.type === MSG_ROOM_JOINED)).toBe(true);
+    });
+    mock2.sent.length = 0;
+    mock.emitMessage(
+      JSON.stringify({
+        type: MSG_BROADCAST_EVENT,
+        payload: { event: "draw", payload: { x: 1 } },
+      })
+    );
+    await vi.waitFor(() => {
+      expect(mock2.sent.some((m: { type?: string }) => m?.type === MSG_BROADCAST_EVENT_RELAY)).toBe(true);
+    });
+  });
+
+  it("send_chat when in room appends and broadcasts", async () => {
+    new Connection(mock.ws as import("ws").WebSocket, {
+      connectionId: "c1",
+      presenceThrottleMs: 0,
+      roomManager,
+    });
+    mock.emitMessage(JSON.stringify({ type: MSG_JOIN_ROOM, payload: { roomId: "cr" } }));
+    await vi.waitFor(() => {
+      expect(mock.sent.some((m: { type?: string }) => m?.type === MSG_ROOM_JOINED)).toBe(true);
+    });
+    mock.emitMessage(JSON.stringify({ type: MSG_SEND_CHAT, payload: { message: "hello room" } }));
+    await vi.waitFor(() => {
+      const chatMsg = mock.sent.find(
+        (m: { type?: string; payload?: { message?: string } }) =>
+          m?.type === MSG_CHAT_MESSAGE && m?.payload?.message === "hello room"
+      );
+      expect(chatMsg).toBeDefined();
+    });
+  });
+
+  it("join_room with accessToken sets userId, name, email, provider from decoded token", async () => {
+    const secret = new TextEncoder().encode("auth-secret");
+    const token = await new SignJWT({
+      sub: "auth-user-1",
+      name: "Auth User",
+      email: "auth@example.com",
+      iss: "https://accounts.google.com",
+    })
+      .setProtectedHeader({ alg: "HS256" })
+      .setIssuedAt()
+      .setExpirationTime("1h")
+      .sign(secret);
+
+    new Connection(mock.ws as import("ws").WebSocket, {
+      connectionId: "c1",
+      presenceThrottleMs: 0,
+      roomManager,
+      auth: {},
+    });
+    mock.emitMessage(
+      JSON.stringify({
+        type: MSG_JOIN_ROOM,
+        payload: { roomId: "r1", presence: {}, accessToken: token },
+      })
+    );
+    await vi.waitFor(() => {
+      expect(mock.sent.some((m: { type?: string }) => m?.type === MSG_ROOM_JOINED)).toBe(true);
+    });
+    const roomJoined = mock.sent.find((m: { type?: string }) => m?.type === MSG_ROOM_JOINED) as {
+      payload?: { presence?: Record<string, { userId?: string; name?: string; email?: string; provider?: string }> };
+    };
+    const selfEntry = roomJoined?.payload?.presence?.["c1"];
+    expect(selfEntry?.userId).toBe("auth-user-1");
+    expect(selfEntry?.name).toBe("Auth User");
+    expect(selfEntry?.email).toBe("auth@example.com");
+    expect(selfEntry?.provider).toBe("google");
+  });
+});

package/src/connection.ts

@@ -0,0 +1,204 @@
+/**
+ * Wraps a WebSocket: parse messages, throttle presence, dispatch to room.
+ */
+
+import type { WebSocket } from "ws";
+import type {
+  ClientMessage,
+  ServerMessage,
+  Presence,
+} from "./protocol.js";
+import {
+  MSG_JOIN_ROOM,
+  MSG_LEAVE_ROOM,
+  MSG_UPDATE_PRESENCE,
+  MSG_BROADCAST_EVENT,
+  MSG_SEND_CHAT,
+  MSG_ERROR,
+} from "./protocol.js";
+import type { RoomManager } from "./room-manager.js";
+import type { RoomConnectionHandle } from "./room.js";
+import { decodeAccessToken } from "./auth/index.js";
+import type { AuthOptions } from "./auth/index.js";
+
+function isClientMessage(msg: unknown): msg is ClientMessage {
+  if (msg === null || typeof msg !== "object" || !("type" in msg)) return false;
+  const t = (msg as { type: string }).type;
+  return [
+    MSG_JOIN_ROOM,
+    MSG_LEAVE_ROOM,
+    MSG_UPDATE_PRESENCE,
+    MSG_BROADCAST_EVENT,
+    MSG_SEND_CHAT,
+  ].includes(t);
+}
+
+function send(ws: WebSocket, msg: ServerMessage): void {
+  if (ws.readyState !== ws.OPEN) return;
+  ws.send(JSON.stringify(msg));
+}
+
+export interface ConnectionOptions {
+  connectionId: string;
+  userId?: string;
+  userName?: string;
+  userEmail?: string;
+  provider?: string;
+  presenceThrottleMs: number;
+  roomManager: RoomManager;
+  auth?: AuthOptions;
+}
+
+export class Connection {
+  private readonly ws: WebSocket;
+  private readonly connectionId: string;
+  private userId: string | undefined;
+  private userName: string | undefined;
+  private userEmail: string | undefined;
+  private provider: string | undefined;
+  private readonly presenceThrottleMs: number;
+  private readonly roomManager: RoomManager;
+  private readonly auth: AuthOptions | undefined;
+  private currentRoomId: string | null = null;
+  private lastPresenceUpdate = 0;
+  private closed = false;
+
+  constructor(ws: WebSocket, options: ConnectionOptions) {
+    this.ws = ws;
+    this.connectionId = options.connectionId;
+    this.userId = options.userId;
+    this.userName = options.userName;
+    this.userEmail = options.userEmail;
+    this.provider = options.provider;
+    this.presenceThrottleMs = options.presenceThrottleMs;
+    this.roomManager = options.roomManager;
+    this.auth = options.auth;
+
+    this.ws.on("message", (data: Buffer | string) => this.handleMessage(data));
+    this.ws.on("close", () => this.handleClose());
+  }
+
+  private send(msg: ServerMessage): void {
+    send(this.ws, msg);
+  }
+
+  private handleMessage(data: Buffer | string): void {
+    if (this.closed) return;
+    let msg: unknown;
+    try {
+      const raw = typeof data === "string" ? data : data.toString("utf8");
+      msg = JSON.parse(raw) as unknown;
+    } catch {
+      this.send({
+        type: MSG_ERROR,
+        payload: { code: "INVALID_JSON", message: "Invalid JSON" },
+      });
+      return;
+    }
+    if (!isClientMessage(msg)) {
+      this.send({
+        type: MSG_ERROR,
+        payload: { code: "INVALID_MESSAGE", message: "Unknown or invalid message type" },
+      });
+      return;
+    }
+    this.dispatch(msg).catch((err) => {
+      this.send({
+        type: MSG_ERROR,
+        payload: {
+          code: "SERVER_ERROR",
+          message: err instanceof Error ? err.message : String(err),
+        },
+      });
+    });
+  }
+
+  private async dispatch(clientMsg: ClientMessage): Promise<void> {
+    switch (clientMsg.type) {
+      case MSG_JOIN_ROOM: {
+        const { roomId, presence, accessToken } = clientMsg.payload;
+        if (accessToken && this.userId === undefined) {
+          const decoded = await decodeAccessToken(accessToken, this.auth);
+          if (decoded) {
+            this.userId = decoded.sub;
+            this.userName = decoded.name;
+            this.userEmail = decoded.email;
+            this.provider = decoded.provider;
+          }
+        }
+        if (this.currentRoomId) {
+          const room = this.roomManager.get(this.currentRoomId);
+          if (room) room.leave(this.connectionId);
+          this.roomManager.removeIfEmpty(this.currentRoomId);
+        }
+        this.currentRoomId = roomId;
+        const room = this.roomManager.getOrCreate(roomId);
+        const handle: RoomConnectionHandle = {
+          connectionId: this.connectionId,
+          userId: this.userId,
+          name: this.userName,
+          email: this.userEmail,
+          provider: this.provider,
+          presence: {},
+          send: (m) => this.send(m),
+        };
+        await room.join(handle, presence);
+        break;
+      }
+      case MSG_LEAVE_ROOM: {
+        const roomId = clientMsg.payload?.roomId ?? this.currentRoomId;
+        if (roomId && this.currentRoomId === roomId) {
+          const room = this.roomManager.get(roomId);
+          if (room) room.leave(this.connectionId);
+          this.roomManager.removeIfEmpty(roomId);
+          this.currentRoomId = null;
+        }
+        break;
+      }
+      case MSG_UPDATE_PRESENCE: {
+        const now = Date.now();
+        if (now - this.lastPresenceUpdate < this.presenceThrottleMs) return;
+        this.lastPresenceUpdate = now;
+        if (!this.currentRoomId) return;
+        const room = this.roomManager.get(this.currentRoomId);
+        if (room) room.updatePresence(this.connectionId, clientMsg.payload.presence as Presence);
+        break;
+      }
+      case MSG_BROADCAST_EVENT: {
+        if (!this.currentRoomId) return;
+        const room = this.roomManager.get(this.currentRoomId);
+        if (room) {
+          room.broadcastEvent(
+            this.connectionId,
+            clientMsg.payload.event,
+            clientMsg.payload.payload,
+            this.userId
+          );
+        }
+        break;
+      }
+      case MSG_SEND_CHAT: {
+        if (!this.currentRoomId) return;
+        const room = this.roomManager.get(this.currentRoomId);
+        if (room) {
+          await room.sendChat(
+            this.connectionId,
+            clientMsg.payload.message,
+            clientMsg.payload.metadata,
+            this.userId
+          );
+        }
+        break;
+      }
+    }
+  }
+
+  private handleClose(): void {
+    this.closed = true;
+    if (this.currentRoomId) {
+      const room = this.roomManager.get(this.currentRoomId);
+      if (room) room.leave(this.connectionId);
+      this.roomManager.removeIfEmpty(this.currentRoomId);
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,80 @@
+/**
+ * @openlivesync/server - Node.js package for collaboration, presence, and chat.
+ * Export all public API and protocol types for use in a Node.js backend.
+ */
+
+// Server API
+export {
+  createServer,
+  createWebSocketServer,
+  createWebSocketHandler,
+  type ServerOptions,
+  type WebSocketServerOptions,
+  type ChatOptions,
+} from "./server.js";
+
+// Protocol (for client compatibility and typing)
+export type {
+  Presence,
+  UserInfo,
+  ClientMessage,
+  ServerMessage,
+  JoinRoomPayload,
+  LeaveRoomPayload,
+  UpdatePresencePayload,
+  BroadcastEventPayload,
+  SendChatPayload,
+  PresenceEntry,
+  RoomJoinedPayload,
+  PresenceUpdatedPayload,
+  BroadcastEventRelayPayload,
+  ChatMessagePayload,
+  StoredChatMessage,
+  ErrorPayload,
+  ChatMessageInput,
+} from "./protocol.js";
+export {
+  MSG_JOIN_ROOM,
+  MSG_LEAVE_ROOM,
+  MSG_UPDATE_PRESENCE,
+  MSG_BROADCAST_EVENT,
+  MSG_SEND_CHAT,
+  MSG_ROOM_JOINED,
+  MSG_PRESENCE_UPDATED,
+  MSG_BROADCAST_EVENT_RELAY,
+  MSG_CHAT_MESSAGE,
+  MSG_ERROR,
+} from "./protocol.js";
+
+// Auth (decode/verify access tokens; Google, Microsoft, custom OAuth)
+export { decodeAccessToken, createTokenAuth } from "./auth/index.js";
+export type {
+  AuthOptions,
+  AuthGoogleConfig,
+  AuthMicrosoftConfig,
+  AuthCustomConfig,
+  CreateTokenAuthOptions,
+  DecodedToken,
+} from "./auth/index.js";
+
+// Chat storage interface and in-memory (no extra deps)
+export type { ChatStorage } from "./storage/chat-storage.js";
+export { createInMemoryChatStorage } from "./storage/in-memory.js";
+export type { InMemoryChatStorageOptions } from "./storage/in-memory.js";
+
+// Optional DB adapters (require pg / mysql2 / better-sqlite3 to be installed)
+export { createPostgresChatStorage } from "./storage/postgres.js";
+export type {
+  PostgresChatStorageOptions,
+  PostgresConnectionConfig,
+} from "./storage/postgres.js";
+export { createMySQLChatStorage } from "./storage/mysql.js";
+export type {
+  MySQLChatStorageOptions,
+  MySQLConnectionConfig,
+} from "./storage/mysql.js";
+export { createSQLiteChatStorage } from "./storage/sqlite.js";
+export type {
+  SQLiteChatStorageOptions,
+  SQLiteConnectionConfig,
+} from "./storage/sqlite.js";

package/src/protocol.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from "vitest";
+import {
+  MSG_JOIN_ROOM,
+  MSG_LEAVE_ROOM,
+  MSG_UPDATE_PRESENCE,
+  MSG_BROADCAST_EVENT,
+  MSG_SEND_CHAT,
+  MSG_ROOM_JOINED,
+  MSG_PRESENCE_UPDATED,
+  MSG_CHAT_MESSAGE,
+  MSG_ERROR,
+} from "./protocol.js";
+
+describe("protocol constants", () => {
+  it("client message types are string constants", () => {
+    expect(MSG_JOIN_ROOM).toBe("join_room");
+    expect(MSG_LEAVE_ROOM).toBe("leave_room");
+    expect(MSG_UPDATE_PRESENCE).toBe("update_presence");
+    expect(MSG_BROADCAST_EVENT).toBe("broadcast_event");
+    expect(MSG_SEND_CHAT).toBe("send_chat");
+  });
+
+  it("server message types are string constants", () => {
+    expect(MSG_ROOM_JOINED).toBe("room_joined");
+    expect(MSG_PRESENCE_UPDATED).toBe("presence_updated");
+    expect(MSG_CHAT_MESSAGE).toBe("chat_message");
+    expect(MSG_ERROR).toBe("error");
+  });
+});