fix!: enforce to use string for room-id (#27)

* fix: parsing roomId err in simple server

* refactor!: enforce that roomId must be a utf8 string in the protocol

This can make the behavior more explicit and easy to understand. It can also make the overall app easier to inspect and maintain

* fix: check length with bytes

* fix: type err about elo

* fix: update rust crates to reflect the changes on the protocol

Author: zxch3n

AGENTS.md

@@ -38,7 +38,7 @@ pnpm clean
 - **packages/loro-protocol**: Protocol types and binary encoders/decoders, bytes utilities, and `%ELO` container/crypto helpers (TypeScript). Key files: `src/{protocol,encoding,bytes,e2ee}.ts` with tests under `src/`.
 - **packages/loro-websocket**: WebSocket client and a `SimpleServer` (TypeScript).
   - Features: message fragmentation/reassembly (≤256 KiB), connection‑scoped keepalive frames (`"ping"/"pong"` text), permission hooks, optional persistence hooks.
-- **packages/loro-adaptors**: Adaptors that connect the WebSocket client to `loro-crdt` (`LoroAdaptor`, `LoroEphemeralAdaptor`) and `%ELO` (`EloLoroAdaptor`).
+- **packages/loro-adaptors**: Adaptors that connect the WebSocket client to `loro-crdt` (`LoroAdaptor`, `LoroEphemeralAdaptor`) and `%ELO` (`EloAdaptor`).
 - **examples/excalidraw-example**: React demo using `SimpleServer`; syncs a Loro doc and ephemeral presence.
 - **rust/**: Rust workspace mirroring the TS packages:
   - `rust/loro-protocol`: Encoder/decoder parity with JS (snapshot tests included).

README.md

@@ -69,15 +69,15 @@ Tip: For a working reference, see `packages/loro-websocket/src/e2e.test.ts` whic
 
 `%ELO` adds end‑to‑end encryption to Loro sync. The server never decrypts; it indexes plaintext headers only to support backfill and routing. Clients encrypt/decrypt using AES‑GCM with a 12‑byte IV and the exact encoded header bytes as AAD.
 
-- TypeScript: use `EloLoroAdaptor` from `loro-adaptors` + `LoroWebsocketClient`.
+- TypeScript: use `EloAdaptor` from `loro-adaptors` + `LoroWebsocketClient`.
   - Provide a `getPrivateKey()` hook that resolves `{ keyId, key }` (Web Crypto CryptoKey or Uint8Array).
   - The adaptor packages updates into `%ELO` containers and decrypts incoming ones, applying to its internal `LoroDoc`.
 
 Example (Node 18+):
 
 ```ts
 import { LoroWebsocketClient } from "loro-websocket/client";
-import { EloLoroAdaptor } from "loro-adaptors/loro";
+import { EloAdaptor } from "loro-adaptors/loro";
 import { WebSocket } from "ws";
 (globalThis as any).WebSocket =
   WebSocket as unknown as typeof globalThis.WebSocket;
@@ -89,7 +89,7 @@ const key = new Uint8Array([
 
 const client = new LoroWebsocketClient({ url: "ws://localhost:8787" });
 await client.waitConnected();
-const adaptor = new EloLoroAdaptor({
+const adaptor = new EloAdaptor({
   getPrivateKey: async () => ({ keyId: "k1", key }),
 });
 const room = await client.join({ roomId: "elo-room", crdtAdaptor: adaptor });

llms.md

@@ -183,7 +183,7 @@ Adaptors bridge the client to actual CRDT state:
 
 - `LoroAdaptor` – Loro document (`const adaptor = new LoroAdaptor()`).
 - `LoroEphemeralAdaptor` – transient presence (`%EPH`).
-- `EloLoroAdaptor` – `%ELO` encrypted Loro with `getPrivateKey()`.
+- `EloAdaptor` – `%ELO` encrypted Loro with `getPrivateKey()`.
 
 ### 3.2 Constructor Options
 

packages/loro-adaptors/src/elo-adaptor.ts

@@ -16,9 +16,9 @@ import {
 } from "loro-protocol";
 
 // Minimal placeholder to avoid requiring DOM lib in this package
-interface CryptoKey {}
+interface CryptoKey { }
 
-export interface EloLoroAdaptorConfig {
+export interface EloAdaptorConfig {
   getPrivateKey: (
     keyId?: string
   ) => Promise<{ keyId: string; key: CryptoKey | Uint8Array }>;
@@ -36,7 +36,7 @@ export class EloAdaptor implements CrdtDocAdaptor {
   private doc: LoroDoc;
   private ctx?: CrdtAdaptorContext;
   private destroyed = false;
-  private config: EloLoroAdaptorConfig;
+  private config: EloAdaptorConfig;
   private localUpdateUnsubscribe?: () => void;
   private initServerVersion?: VersionVector;
   private hasReachedServerVersion = false;
@@ -48,15 +48,15 @@ export class EloAdaptor implements CrdtDocAdaptor {
   private lastSentVV?: Record<string, number>;
 
   // Overloads to allow (config) or (doc, config)
-  constructor(doc: LoroDoc, config: EloLoroAdaptorConfig);
-  constructor(config: EloLoroAdaptorConfig);
+  constructor(doc: LoroDoc, config: EloAdaptorConfig);
+  constructor(config: EloAdaptorConfig);
   constructor(
-    docOrConfig: LoroDoc | EloLoroAdaptorConfig,
-    maybeConfig?: EloLoroAdaptorConfig
+    docOrConfig: LoroDoc | EloAdaptorConfig,
+    maybeConfig?: EloAdaptorConfig
   ) {
     if (docOrConfig instanceof LoroDoc) {
       this.doc = docOrConfig;
-      this.config = maybeConfig as EloLoroAdaptorConfig;
+      this.config = maybeConfig as EloAdaptorConfig;
     } else {
       this.doc = new LoroDoc();
       this.config = docOrConfig;

packages/loro-adaptors/tests/elo-adaptor.test.ts

@@ -15,7 +15,7 @@ function hexToBytes(hex: string): Uint8Array {
   return out;
 }
 
-describe("EloLoroAdaptor — snapshot join", () => {
+describe("EloAdaptor — snapshot join", () => {
   let doc: LoroDoc;
   let adaptor: EloAdaptor;
   const key = hexToBytes(KEY_HEX);
@@ -60,7 +60,7 @@ describe("EloLoroAdaptor — snapshot join", () => {
   });
 });
 
-describe("EloLoroAdaptor — apply snapshot update", () => {
+describe("EloAdaptor — apply snapshot update", () => {
   it("applies a snapshot container and updates the doc", async () => {
     const key = hexToBytes(KEY_HEX);
     // Create a source doc with content
@@ -99,7 +99,7 @@ describe("EloLoroAdaptor — apply snapshot update", () => {
   });
 });
 
-describe("EloLoroAdaptor — apply delta update", () => {
+describe("EloAdaptor — apply delta update", () => {
   it("applies a delta container update and updates the doc", async () => {
     const key = hexToBytes(KEY_HEX);
     // Create source update plaintext via standard update export

packages/loro-protocol/README.md

@@ -27,7 +27,7 @@ import { encode, decode, CrdtType, MessageType } from "loro-protocol";
 const join = encode({
   type: MessageType.JoinRequest,
   crdt: CrdtType.Loro,
-  roomId: new TextEncoder().encode("room-1"),
+  roomId: "room-1",
   auth: new Uint8Array(),
   version: new Uint8Array(),
 });

packages/loro-protocol/src/encoding.ts

@@ -88,18 +88,13 @@ export function encode(message: ProtocolMessage): Uint8Array {
   const crdtBytes = new TextEncoder().encode(message.crdt);
   writer.pushBytes(crdtBytes);
 
-  // Write room ID as varBytes
-  if (typeof message.roomId === "string") {
-    if (message.roomId.length > MAX_ROOM_ID_LENGTH) {
-      throw new Error("Room ID too long");
-    }
-    writer.pushVarString(message.roomId);
-  } else {
-    if (message.roomId.length > MAX_ROOM_ID_LENGTH) {
-      throw new Error("Room ID too long");
-    }
-    writer.pushVarBytes(message.roomId);
+  // Write room ID as varString
+  const roomIdBytes = new TextEncoder().encode(message.roomId);
+  if (roomIdBytes.byteLength > MAX_ROOM_ID_LENGTH) {
+    throw new Error("Room ID too long");
   }
+  writer.pushVarBytes(roomIdBytes);
+
 
   // Write message type
   writer.pushByte(message.type);
@@ -209,10 +204,7 @@ export function decode(data: Uint8Array): ProtocolMessage {
   }
 
   // Read room ID
-  const roomId = reader.readVarBytes();
-  if (roomId.length > 128) {
-    throw new Error("Room ID exceeds maximum length of 128 bytes");
-  }
+  const roomId = reader.readVarString();
 
   // Read message type
   const typeByte = reader.readByte();

packages/loro-protocol/src/protocol.ts

@@ -66,7 +66,7 @@ export const UpdateErrorCode = {
 export type UpdateErrorCode =
   (typeof UpdateErrorCode)[keyof typeof UpdateErrorCode];
 
-export type RoomId = string | Uint8Array;
+export type RoomId = string;
 
 export interface MessageBase {
   crdt: CrdtType;

packages/loro-protocol/tests/__snapshots__/encoding.snap.test.ts.snap

@@ -1,27 +1,27 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`encoding snapshots > DocUpdate multiple updates 1`] = `"0x25594a53040102030403030301020304040506070108"`;
+exports[`encoding snapshots > DocUpdate multiple updates 1`] = `"0x25594a5309726f6f6d2d3132333403030301020304040506070108"`;
 
-exports[`encoding snapshots > DocUpdateFragment 1`] = `"0x254c4f5204010203040500000000000000000320000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f"`;
+exports[`encoding snapshots > DocUpdateFragment 1`] = `"0x254c4f5209726f6f6d2d313233340500000000000000000320000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f"`;
 
-exports[`encoding snapshots > DocUpdateFragmentHeader 1`] = `"0x254c4f52040102030404ff112233445566770a80c03e"`;
+exports[`encoding snapshots > DocUpdateFragmentHeader 1`] = `"0x254c4f5209726f6f6d2d3132333404ff112233445566770a80c03e"`;
 
-exports[`encoding snapshots > JoinError app error with appCode 1`] = `"0x25594a530401020304027f1a4170706c69636174696f6e207370656369666963206572726f720e71756f74615f6578636565646564"`;
+exports[`encoding snapshots > JoinError app error with appCode 1`] = `"0x25594a5309726f6f6d2d31323334027f1a4170706c69636174696f6e207370656369666963206572726f720e71756f74615f6578636565646564"`;
 
-exports[`encoding snapshots > JoinError auth failed 1`] = `"0x254550480401020304020213496e76616c69642063726564656e7469616c73"`;
+exports[`encoding snapshots > JoinError auth failed 1`] = `"0x2545504809726f6f6d2d31323334020213496e76616c69642063726564656e7469616c73"`;
 
-exports[`encoding snapshots > JoinError version unknown with receiver version 1`] = `"0x254c4f52040102030402011056657273696f6e206d69736d61746368026364"`;
+exports[`encoding snapshots > JoinError version unknown with receiver version 1`] = `"0x254c4f5209726f6f6d2d3132333402011056657273696f6e206d69736d61746368026364"`;
 
-exports[`encoding snapshots > JoinRequest 1`] = `"0x254c4f52040102030400030a141e0328323c"`;
+exports[`encoding snapshots > JoinRequest 1`] = `"0x254c4f5209726f6f6d2d3132333400030a141e0328323c"`;
 
-exports[`encoding snapshots > JoinResponseOk read 1`] = `"0x25594a530401020304010472656164030b162100"`;
+exports[`encoding snapshots > JoinResponseOk read 1`] = `"0x25594a5309726f6f6d2d31323334010472656164030b162100"`;
 
-exports[`encoding snapshots > JoinResponseOk write + extra 1`] = `"0x254c4f52040102030401057772697465022c3703424d58"`;
+exports[`encoding snapshots > JoinResponseOk write + extra 1`] = `"0x254c4f5209726f6f6d2d3132333401057772697465022c3703424d58"`;
 
-exports[`encoding snapshots > Leave 1`] = `"0x254c4f52040102030407"`;
+exports[`encoding snapshots > Leave 1`] = `"0x254c4f5209726f6f6d2d3132333407"`;
 
-exports[`encoding snapshots > UpdateError app error with appCode 1`] = `"0x254c4f520401020304067f10437573746f6d20617070206572726f720f637573746f6d5f636f64655f313233"`;
+exports[`encoding snapshots > UpdateError app error with appCode 1`] = `"0x254c4f5209726f6f6d2d31323334067f10437573746f6d20617070206572726f720f637573746f6d5f636f64655f313233"`;
 
-exports[`encoding snapshots > UpdateError fragment timeout with batchId 1`] = `"0x255941570401020304060710467261676d656e742074696d656f75740100000000000000"`;
+exports[`encoding snapshots > UpdateError fragment timeout with batchId 1`] = `"0x2559415709726f6f6d2d31323334060710467261676d656e742074696d656f75740100000000000000"`;
 
-exports[`encoding snapshots > UpdateError permission denied 1`] = `"0x254c4f5204010203040603134e6f207772697465207065726d697373696f6e"`;
+exports[`encoding snapshots > UpdateError permission denied 1`] = `"0x254c4f5209726f6f6d2d313233340603134e6f207772697465207065726d697373696f6e"`;

packages/loro-protocol/tests/encoding.snap.test.ts

@@ -19,7 +19,7 @@ import {
 // TODO: REVIEW ensure binary snapshots stay stable across changes to protocol
 
 describe("encoding snapshots", () => {
-  const roomId = new Uint8Array([1, 2, 3, 4]);
+  const roomId = "room-1234";
 
   it("JoinRequest", () => {
     const msg: JoinRequest = {