@openlivesync/server 1.0.2

package/src/protocol.ts

@@ -0,0 +1,137 @@
+/**
+ * Wire protocol types for @openlivesync.
+ * Shared between server and client; server handles these message types.
+ */
+
+/** Generic presence payload (cursor, name, color, etc.). Server does not interpret. */
+export type Presence = Record<string, unknown>;
+
+/** User/session info attached by server from auth (optional). */
+export interface UserInfo {
+  userId?: string;
+  name?: string;
+  email?: string;
+  provider?: string;
+  [key: string]: unknown;
+}
+
+// ----- Client → Server message types -----
+
+export const MSG_JOIN_ROOM = "join_room";
+export const MSG_LEAVE_ROOM = "leave_room";
+export const MSG_UPDATE_PRESENCE = "update_presence";
+export const MSG_BROADCAST_EVENT = "broadcast_event";
+export const MSG_SEND_CHAT = "send_chat";
+
+export interface JoinRoomPayload {
+  roomId: string;
+  presence?: Presence;
+  /** Optional OAuth/OpenID access token; server decodes to get name, email, provider. */
+  accessToken?: string;
+}
+
+export interface LeaveRoomPayload {
+  roomId?: string;
+}
+
+export interface UpdatePresencePayload {
+  presence: Presence;
+}
+
+export interface BroadcastEventPayload {
+  event: string;
+  payload?: unknown;
+}
+
+export interface SendChatPayload {
+  message: string;
+  /** Optional application-defined metadata */
+  metadata?: Record<string, unknown>;
+}
+
+export type ClientMessage =
+  | { type: typeof MSG_JOIN_ROOM; payload: JoinRoomPayload }
+  | { type: typeof MSG_LEAVE_ROOM; payload?: LeaveRoomPayload }
+  | { type: typeof MSG_UPDATE_PRESENCE; payload: UpdatePresencePayload }
+  | { type: typeof MSG_BROADCAST_EVENT; payload: BroadcastEventPayload }
+  | { type: typeof MSG_SEND_CHAT; payload: SendChatPayload };
+
+// ----- Server → Client message types -----
+
+export const MSG_ROOM_JOINED = "room_joined";
+export const MSG_PRESENCE_UPDATED = "presence_updated";
+export const MSG_BROADCAST_EVENT_RELAY = "broadcast_event";
+export const MSG_CHAT_MESSAGE = "chat_message";
+export const MSG_ERROR = "error";
+
+export interface PresenceEntry {
+  connectionId: string;
+  userId?: string;
+  name?: string;
+  email?: string;
+  provider?: string;
+  presence: Presence;
+}
+
+export interface RoomJoinedPayload {
+  roomId: string;
+  connectionId: string;
+  presence: Record<string, PresenceEntry>;
+  chatHistory?: StoredChatMessage[];
+}
+
+export interface PresenceUpdatedPayload {
+  roomId: string;
+  joined?: PresenceEntry[];
+  left?: string[];
+  updated?: PresenceEntry[];
+}
+
+export interface BroadcastEventRelayPayload {
+  roomId: string;
+  connectionId: string;
+  userId?: string;
+  event: string;
+  payload?: unknown;
+}
+
+export interface ChatMessagePayload {
+  roomId: string;
+  connectionId: string;
+  userId?: string;
+  message: string;
+  metadata?: Record<string, unknown>;
+  id?: string;
+  createdAt?: number;
+}
+
+export interface StoredChatMessage {
+  id: string;
+  roomId: string;
+  connectionId: string;
+  userId?: string;
+  message: string;
+  metadata?: Record<string, unknown>;
+  createdAt: number;
+}
+
+export interface ErrorPayload {
+  code: string;
+  message: string;
+}
+
+export type ServerMessage =
+  | { type: typeof MSG_ROOM_JOINED; payload: RoomJoinedPayload }
+  | { type: typeof MSG_PRESENCE_UPDATED; payload: PresenceUpdatedPayload }
+  | { type: typeof MSG_BROADCAST_EVENT_RELAY; payload: BroadcastEventRelayPayload }
+  | { type: typeof MSG_CHAT_MESSAGE; payload: ChatMessagePayload }
+  | { type: typeof MSG_ERROR; payload: ErrorPayload };
+
+/** Chat message as provided when appending (before storage adds id/createdAt). */
+export interface ChatMessageInput {
+  roomId: string;
+  connectionId: string;
+  userId?: string;
+  message: string;
+  metadata?: Record<string, unknown>;
+}

package/src/room-manager.ts

@@ -0,0 +1,45 @@
+/**
+ * Manages rooms: get-or-create by roomId.
+ */
+
+import { Room } from "./room.js";
+import type { ChatStorage } from "./storage/chat-storage.js";
+
+export interface RoomManagerOptions {
+  chatStorage: ChatStorage;
+  historyLimit: number;
+}
+
+export class RoomManager {
+  private readonly options: RoomManagerOptions;
+  private readonly rooms = new Map<string, Room>();
+
+  constructor(options: RoomManagerOptions) {
+    this.options = options;
+  }
+
+  getOrCreate(roomId: string): Room {
+    let room = this.rooms.get(roomId);
+    if (!room) {
+      room = new Room({
+        roomId,
+        chatStorage: this.options.chatStorage,
+        historyLimit: this.options.historyLimit,
+      });
+      this.rooms.set(roomId, room);
+    }
+    return room;
+  }
+
+  get(roomId: string): Room | undefined {
+    return this.rooms.get(roomId);
+  }
+
+  /** Remove room when empty (optional cleanup). */
+  removeIfEmpty(roomId: string): void {
+    const room = this.rooms.get(roomId);
+    if (room && room.connectionCount === 0) {
+      this.rooms.delete(roomId);
+    }
+  }
+}

package/src/room.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect } from "vitest";
+import { Room } from "./room.js";
+import { RoomManager } from "./room-manager.js";
+import { createInMemoryChatStorage } from "./storage/in-memory.js";
+import { MSG_ROOM_JOINED, MSG_PRESENCE_UPDATED, MSG_CHAT_MESSAGE, MSG_BROADCAST_EVENT_RELAY } from "./protocol.js";
+
+function mockHandle(
+  connectionId: string,
+  userId?: string,
+  sent: { value: unknown[] } = { value: [] }
+): { handle: import("./room.js").RoomConnectionHandle; sent: unknown[] } {
+  const list = sent.value;
+  return {
+    handle: {
+      connectionId,
+      userId,
+      presence: {},
+      send: (msg: unknown) => list.push(msg),
+    },
+    sent: list,
+  };
+}
+
+describe("Room", () => {
+  it("join sends room_joined with presence and chat history", async () => {
+    const storage = createInMemoryChatStorage({ historyLimit: 10 });
+    const room = new Room({
+      roomId: "r1",
+      chatStorage: storage,
+      historyLimit: 10,
+    });
+    const { handle, sent } = mockHandle("c1", "u1");
+    await room.join(handle, { cursor: { x: 1, y: 2 } });
+    expect(sent).toHaveLength(1);
+    expect(sent[0]).toMatchObject({
+      type: MSG_ROOM_JOINED,
+      payload: {
+        roomId: "r1",
+        connectionId: "c1",
+        presence: { c1: { connectionId: "c1", userId: "u1", presence: { cursor: { x: 1, y: 2 } } } },
+      },
+    });
+    expect((sent[0] as { payload: { chatHistory?: unknown[] } }).payload.chatHistory).toEqual([]);
+  });
+
+  it("join sends room_joined with empty chatHistory when getHistory throws", async () => {
+    const failingStorage = {
+      append: async () => {},
+      getHistory: async () => {
+        throw new Error("storage unavailable");
+      },
+    } as import("./storage/chat-storage.js").ChatStorage;
+    const room = new Room({
+      roomId: "r1",
+      chatStorage: failingStorage,
+      historyLimit: 10,
+    });
+    const { handle, sent } = mockHandle("c1");
+    await room.join(handle);
+    expect(sent).toHaveLength(1);
+    expect((sent[0] as { payload: { chatHistory?: unknown[] } }).payload.chatHistory).toEqual([]);
+  });
+
+  it("leave broadcasts presence_updated with left", async () => {
+    const storage = createInMemoryChatStorage();
+    const room = new Room({ roomId: "r1", chatStorage: storage, historyLimit: 10 });
+    const { handle: h1, sent: s1 } = mockHandle("c1");
+    const { handle: h2, sent: s2 } = mockHandle("c2");
+    await room.join(h1);
+    await room.join(h2);
+    s1.length = 0;
+    s2.length = 0;
+    room.leave("c1");
+    expect(s1).toHaveLength(0);
+    expect(s2).toHaveLength(1);
+    expect(s2[0]).toMatchObject({
+      type: MSG_PRESENCE_UPDATED,
+      payload: { roomId: "r1", left: ["c1"] },
+    });
+  });
+
+  it("updatePresence broadcasts to others only", async () => {
+    const storage = createInMemoryChatStorage();
+    const room = new Room({ roomId: "r1", chatStorage: storage, historyLimit: 10 });
+    const { handle: h1, sent: s1 } = mockHandle("c1");
+    const { handle: h2, sent: s2 } = mockHandle("c2");
+    await room.join(h1);
+    await room.join(h2);
+    s1.length = 0;
+    s2.length = 0;
+    room.updatePresence("c1", { cursor: { x: 10 } });
+    expect(s1).toHaveLength(0);
+    expect(s2).toHaveLength(1);
+    expect(s2[0]).toMatchObject({
+      type: MSG_PRESENCE_UPDATED,
+      payload: { roomId: "r1", updated: [{ connectionId: "c1", presence: { cursor: { x: 10 } } }] },
+    });
+  });
+
+  it("updatePresence with unknown connectionId does nothing", async () => {
+    const storage = createInMemoryChatStorage();
+    const room = new Room({ roomId: "r1", chatStorage: storage, historyLimit: 10 });
+    const { handle, sent } = mockHandle("c1");
+    await room.join(handle);
+    sent.length = 0;
+    room.updatePresence("unknown-connection", { x: 1 });
+    expect(sent).toHaveLength(0);
+  });
+
+  it("broadcastEvent relays to others only", async () => {
+    const storage = createInMemoryChatStorage();
+    const room = new Room({ roomId: "r1", chatStorage: storage, historyLimit: 10 });
+    const { handle: h1, sent: s1 } = mockHandle("c1");
+    const { handle: h2, sent: s2 } = mockHandle("c2");
+    await room.join(h1);
+    await room.join(h2);
+    s1.length = 0;
+    s2.length = 0;
+    room.broadcastEvent("c1", "draw", { x: 1, y: 2 }, "u1");
+    expect(s1).toHaveLength(0);
+    expect(s2).toHaveLength(1);
+    expect(s2[0]).toMatchObject({
+      type: MSG_BROADCAST_EVENT_RELAY,
+      payload: { roomId: "r1", connectionId: "c1", userId: "u1", event: "draw", payload: { x: 1, y: 2 } },
+    });
+  });
+
+  it("sendChat appends to storage and broadcasts to all", async () => {
+    const storage = createInMemoryChatStorage();
+    const room = new Room({ roomId: "r1", chatStorage: storage, historyLimit: 10 });
+    const { handle: h1, sent: s1 } = mockHandle("c1", "u1");
+    const { handle: h2, sent: s2 } = mockHandle("c2");
+    await room.join(h1);
+    await room.join(h2);
+    s1.length = 0;
+    s2.length = 0;
+    await room.sendChat("c1", "hello", { replyTo: "x" }, "u1");
+    expect(s1).toHaveLength(1);
+    expect(s2).toHaveLength(1);
+    expect(s1[0]).toMatchObject({
+      type: MSG_CHAT_MESSAGE,
+      payload: { roomId: "r1", connectionId: "c1", userId: "u1", message: "hello", metadata: { replyTo: "x" } },
+    });
+    const history = await storage.getHistory("r1");
+    expect(history).toHaveLength(1);
+    expect(history[0].message).toBe("hello");
+  });
+});
+
+describe("RoomManager", () => {
+  it("getOrCreate returns same room for same id", () => {
+    const storage = createInMemoryChatStorage();
+    const manager = new RoomManager({ chatStorage: storage, historyLimit: 10 });
+    const a = manager.getOrCreate("r1");
+    const b = manager.getOrCreate("r1");
+    expect(a).toBe(b);
+  });
+
+  it("get returns undefined for unknown room", () => {
+    const storage = createInMemoryChatStorage();
+    const manager = new RoomManager({ chatStorage: storage, historyLimit: 10 });
+    expect(manager.get("r1")).toBeUndefined();
+  });
+
+  it("removeIfEmpty removes room when no connections", async () => {
+    const storage = createInMemoryChatStorage();
+    const manager = new RoomManager({ chatStorage: storage, historyLimit: 10 });
+    const room = manager.getOrCreate("r1");
+    const { handle } = mockHandle("c1");
+    await room.join(handle);
+    room.leave("c1");
+    manager.removeIfEmpty("r1");
+    expect(manager.get("r1")).toBeUndefined();
+  });
+});

package/src/room.ts

@@ -0,0 +1,207 @@
+/**
+ * A single room: connections, presence map, broadcast, and chat.
+ */
+
+import type {
+  Presence,
+  PresenceEntry,
+  ServerMessage,
+  StoredChatMessage,
+} from "./protocol.js";
+import {
+  MSG_CHAT_MESSAGE,
+  MSG_PRESENCE_UPDATED,
+  MSG_ROOM_JOINED,
+  MSG_BROADCAST_EVENT_RELAY,
+} from "./protocol.js";
+import type { ChatStorage } from "./storage/chat-storage.js";
+
+/** Handle the room uses to send messages to a connection. */
+export interface RoomConnectionHandle {
+  connectionId: string;
+  userId?: string;
+  name?: string;
+  email?: string;
+  provider?: string;
+  presence: Presence;
+  send(msg: ServerMessage): void;
+}
+
+export interface RoomOptions {
+  roomId: string;
+  chatStorage: ChatStorage;
+  historyLimit: number;
+}
+
+export class Room {
+  private readonly roomId: string;
+  private readonly chatStorage: ChatStorage;
+  private readonly historyLimit: number;
+  private readonly connections = new Map<string, RoomConnectionHandle>();
+
+  constructor(options: RoomOptions) {
+    this.roomId = options.roomId;
+    this.chatStorage = options.chatStorage;
+    this.historyLimit = options.historyLimit;
+  }
+
+  get connectionCount(): number {
+    return this.connections.size;
+  }
+
+  /** Add connection to room; send room_joined to connection and presence_updated (joined) to others. */
+  async join(
+    handle: RoomConnectionHandle,
+    initialPresence: Presence = {}
+  ): Promise<void> {
+    const entry: RoomConnectionHandle = {
+      ...handle,
+      presence: { ...initialPresence },
+    };
+    this.connections.set(handle.connectionId, entry);
+
+    const presenceMap: Record<string, PresenceEntry> = {};
+    for (const [, c] of this.connections) {
+      presenceMap[c.connectionId] = {
+        connectionId: c.connectionId,
+        userId: c.userId,
+        name: c.name,
+        email: c.email,
+        provider: c.provider,
+        presence: c.presence,
+      };
+    }
+
+    let chatHistory: StoredChatMessage[] | undefined;
+    try {
+      chatHistory = await this.chatStorage.getHistory(
+        this.roomId,
+        this.historyLimit
+      );
+    } catch {
+      chatHistory = [];
+    }
+
+    handle.send({
+      type: MSG_ROOM_JOINED,
+      payload: {
+        roomId: this.roomId,
+        connectionId: handle.connectionId,
+        presence: presenceMap,
+        chatHistory,
+      },
+    });
+
+    this.broadcastExcept(handle.connectionId, {
+      type: MSG_PRESENCE_UPDATED,
+      payload: {
+        roomId: this.roomId,
+        joined: [
+          {
+            connectionId: handle.connectionId,
+            userId: handle.userId,
+            name: handle.name,
+            email: handle.email,
+            provider: handle.provider,
+            presence: entry.presence,
+          },
+        ],
+      },
+    });
+  }
+
+  /** Remove connection and notify others. */
+  leave(connectionId: string): void {
+    this.connections.delete(connectionId);
+    this.broadcast({
+      type: MSG_PRESENCE_UPDATED,
+      payload: {
+        roomId: this.roomId,
+        left: [connectionId],
+      },
+    });
+  }
+
+  /** Update presence for a connection and broadcast updated entry. */
+  updatePresence(connectionId: string, presence: Presence): void {
+    const conn = this.connections.get(connectionId);
+    if (!conn) return;
+    conn.presence = { ...presence };
+    this.broadcastExcept(connectionId, {
+      type: MSG_PRESENCE_UPDATED,
+      payload: {
+        roomId: this.roomId,
+        updated: [
+          {
+            connectionId: conn.connectionId,
+            userId: conn.userId,
+            name: conn.name,
+            email: conn.email,
+            provider: conn.provider,
+            presence: conn.presence,
+          },
+        ],
+      },
+    });
+  }
+
+  /** Relay collaboration event to other clients in the room. */
+  broadcastEvent(
+    connectionId: string,
+    event: string,
+    payload: unknown,
+    userId?: string
+  ): void {
+    this.broadcastExcept(connectionId, {
+      type: MSG_BROADCAST_EVENT_RELAY,
+      payload: {
+        roomId: this.roomId,
+        connectionId,
+        userId,
+        event,
+        payload,
+      },
+    });
+  }
+
+  /** Append chat message to storage and broadcast to all in room. */
+  async sendChat(
+    connectionId: string,
+    message: string,
+    metadata: Record<string, unknown> | undefined,
+    userId?: string
+  ): Promise<void> {
+    await this.chatStorage.append(this.roomId, {
+      roomId: this.roomId,
+      connectionId,
+      userId,
+      message,
+      metadata,
+    });
+    const payload = {
+      roomId: this.roomId,
+      connectionId,
+      userId,
+      message,
+      metadata,
+    };
+    this.broadcast({
+      type: MSG_CHAT_MESSAGE,
+      payload,
+    });
+  }
+
+  private broadcast(msg: ServerMessage): void {
+    for (const conn of this.connections.values()) {
+      conn.send(msg);
+    }
+  }
+
+  private broadcastExcept(exceptConnectionId: string, msg: ServerMessage): void {
+    for (const conn of this.connections.values()) {
+      if (conn.connectionId !== exceptConnectionId) {
+        conn.send(msg);
+      }
+    }
+  }
+}