docs: rename the join custom payload as metadata instead of just auth

Author: zxch3n

README.md

@@ -134,13 +134,13 @@ Requirements:
 
 ### Optional: SimpleServer hooks
 
-`SimpleServer` accepts optional hooks for basic auth and persistence:
+`SimpleServer` accepts optional hooks for basic join metadata/auth handling and persistence:
 
 ```ts
 const server = new SimpleServer({
   port: 8787,
   authenticate: async (roomId, crdt, auth) => {
-    // return 'read' | 'write' | null to deny
+    // join metadata arrives as `auth`; return 'read' | 'write' | null to deny
     return "write";
   },
   onLoadDocument: async (roomId, crdt) => null, // return snapshot bytes
@@ -205,4 +205,4 @@ Node 18+ is required for local development.
 ## FAQ
 
 - How do I test locally? Use `SimpleServer` in `loro-websocket` or the Rust server.
-- Can I bring my own auth/storage? Yes — `SimpleServer` and the Rust server provide hooks for auth and persistence.
+- Can I bring my own auth/storage? Yes — `SimpleServer` and the Rust server provide hooks for join metadata/auth and persistence.

llms.md

@@ -32,7 +32,7 @@ end-to-end encrypted extension, and the full surface of the
 
 | Type ID | Name                      | Payload Summary                                                                                  |
 | ------: | ------------------------- | ------------------------------------------------------------------------------------------------ |
-|  `0x00` | `JoinRequest`             | `varBytes auth`, `varBytes version`.                                                             |
+|  `0x00` | `JoinRequest`             | `varBytes joinPayload` (app-defined metadata, e.g., auth/session info), `varBytes version`.      |
 |  `0x01` | `JoinResponseOk`          | `varString permission ("read"/"write")`, `varBytes version`, `varBytes extraMetadata`.           |
 |  `0x02` | `JoinError`               | `u8 code`, `varString message`, optional `varBytes receiverVersion` when `code=version_unknown`. |
 |  `0x03` | `DocUpdate`               | `varUint N` updates followed by `N` `varBytes` chunks.                                           |
@@ -43,12 +43,13 @@ end-to-end encrypted extension, and the full surface of the
 
 ### 1.2 Sync Lifecycle
 
-1. Client (`Req`) sends `JoinRequest` with auth payload and local version.
+1. Client (`Req`) sends `JoinRequest` with a join payload (auth or other metadata) and local version.
 2. Server (`Recv`) responds:
    - `JoinResponseOk` with current version and permission, then streams
      backfills via `DocUpdate`/`DocUpdateFragment`.
-   - or `JoinError` for authentication failure or unknown version. On
-     `version_unknown`, the server includes its version for reseeding.
+   - or `JoinError` when the join payload is rejected (e.g., auth failure) or
+     for unknown version. On `version_unknown`, the server includes its
+     version for reseeding.
 3. Clients broadcast local edits using `DocUpdate`. Payloads exceeding the
    size limit are sliced into fragments: send header first, then numbered
    fragments. Recipients reassemble by `batchId`.
@@ -237,7 +238,7 @@ adaptor.getDoc().setPeerId(1);
 const room = await client.join({
   roomId: "doc-123",
   crdtAdaptor: adaptor,
-  auth?: Uint8Array,           // Optional bytes forwarded to the server.
+  auth?: Uint8Array,           // Optional join metadata forwarded to the server.
 });
 ```
 
@@ -302,7 +303,7 @@ const server = new SimpleServer({
   port: 8787,
   host?: string,
   saveInterval?: number,   // Default 60_000 ms.
-  authenticate?: async (roomId, crdtType, auth) => "read" | "write" | null,
+  authenticate?: async (roomId, crdtType, auth) => "read" | "write" | null, // auth is join metadata
   onLoadDocument?: async (roomId, crdtType) => Uint8Array | null,
   onSaveDocument?: async (roomId, crdtType, data) => void,
 });
@@ -330,7 +331,8 @@ Key behaviors:
 - Subscribe to `onStatusChange` to gate CRDT mutations behind `Connected`.
 - Use `waitForReachingServerVersion()` before assuming local state matches the
   server (important after reconnects).
-- For auth flows, encode credentials as `Uint8Array` and pass via `join({ auth })`.
+- For join metadata (auth tokens, roles, etc.), encode bytes as `Uint8Array`
+  and pass via `join({ auth })`.
 - Remember that keepalive frames are raw text messages: handle them before
   attempting to decode binary protocol messages.
 

packages/loro-protocol/README.md

@@ -28,7 +28,7 @@ const join = encode({
   type: MessageType.JoinRequest,
   crdt: CrdtType.Loro,
   roomId: "room-1",
-  auth: new Uint8Array(),
+  auth: new Uint8Array(), // join metadata (auth/session tokens, etc.)
   version: new Uint8Array(),
 });
 
@@ -79,4 +79,3 @@ Notes
 ## License
 
 MIT
-

packages/loro-protocol/src/protocol.ts

@@ -75,6 +75,7 @@ export interface MessageBase {
 
 export interface JoinRequest extends MessageBase {
   type: typeof MessageType.JoinRequest;
+  /** Application-defined join payload (auth or other metadata). */
   auth: Uint8Array;
   version: Uint8Array;
 }

packages/loro-websocket/README.md

@@ -98,7 +98,7 @@ type ClientStatusValue = typeof ClientStatus[keyof typeof ClientStatus];
   - `onLatency(cb): () => void` subscribes to latency updates; if a value exists, emits immediately; returns unsubscribe.
 
 - Rooms
-  - `join({ roomId, crdtAdaptor, auth? }): Promise<LoroWebsocketClientRoom>` joins a room for a given CRDT type via its adaptor. Optional `auth` is forwarded to the server’s `authenticate` hook.
+- `join({ roomId, crdtAdaptor, auth? }): Promise<LoroWebsocketClientRoom>` joins a room for a given CRDT type via its adaptor. Optional `auth` carries application-defined join metadata (e.g., auth/session tokens) and is forwarded to the server’s `authenticate` hook.
   - Room API: `leave(): Promise<void>`, `waitForReachingServerVersion(): Promise<void>`, `destroy(): Promise<void>`.
 
 ## Status & Reconnect Model
@@ -127,11 +127,11 @@ type ClientStatusValue = typeof ClientStatus[keyof typeof ClientStatus];
 ## Rooms & Rejoin
 
 - Join handshake
-  - `join()` sends a `JoinRequest` with the adaptor’s CRDT type, version, and optional auth.
+  - `join()` sends a `JoinRequest` with the adaptor’s CRDT type, version, and optional join metadata (`auth` bytes).
   - On `JoinResponseOk`, the adaptor reconciles to the server’s version and begins streaming updates.
 
 - Rejoin after reconnect
-  - The client tracks active rooms and their auth. After reconnect, it re‑sends `JoinRequest` for each active room and the adaptor re‑syncs.
+  - The client tracks active rooms and their join metadata. After reconnect, it re‑sends `JoinRequest` for each active room and the adaptor re‑syncs.
   - If the server responds `VersionUnknown`, the client retries using `adaptor.getAlternativeVersion()` or an empty version as a fallback.
   - For `%ELO`, updates that arrive right after join may be buffered briefly to cover backfills that race the join.
 
@@ -148,7 +148,7 @@ import { SimpleServer } from "loro-websocket/server";
 const server = new SimpleServer({
   port: 8787,
   authenticate: async (_roomId, _crdt, auth) => {
-    // return "read" | "write" | null
+    // join metadata is passed as `auth`; return "read" | "write" | null
     return new TextDecoder().decode(auth) === "readonly" ? "read" : "write";
   },
   onLoadDocument: async (_roomId, _crdt) => null,
@@ -183,15 +183,15 @@ console.log("last RTT:", client.getLatency());
 off();
 ```
 
-- Join with auth
+- Join with join metadata/auth
 
 ```ts
 const adaptor = new LoroAdaptor();
 adaptor.getDoc().setPeerId(42);
 await client.join({
   roomId: "project-123",
   crdtAdaptor: adaptor,
-  auth: new TextEncoder().encode("write-token"),
+  auth: new TextEncoder().encode("write-token"), // application-defined join payload
 });
 ```
 

packages/loro-websocket/src/client/index.ts

@@ -770,6 +770,9 @@ export class LoroWebsocketClient {
     });
   }
 
+  /**
+   * Join a room; `auth` carries application-defined join metadata forwarded to the server.
+   */
   join({
     roomId,
     crdtAdaptor,

packages/loro-websocket/src/server/simple-server.ts

@@ -40,6 +40,7 @@ export interface SimpleServerConfig {
     crdtType: CrdtType,
     data: Uint8Array
   ) => Promise<void>;
+  /** Map join payload (`auth`) to permission; return null to reject. */
   authenticate?: (
     roomId: string,
     crdtType: CrdtType,

protocol-e2ee.md

@@ -104,7 +104,7 @@ Rationale: An explicit random IV per record eliminates IV‑reuse risk and simpl
 
 Req and Recv follow the same join/sync rules as `%LOR`:
 
-- JoinRequest carries authentication and a document version (opaque to the protocol). Recv may respond with JoinResponseOk, JoinError, and may push missing updates.
+- JoinRequest carries application-defined join metadata (often auth) and a document version (both opaque to the protocol). Recv may respond with JoinResponseOk, JoinError, and may push missing updates.
 - When sending updates, Req packs one or more `%ELO` records into a `DocUpdate` payload. If large, use fragments per the base protocol.
 - Recv broadcasts received updates to other subscribers in the same room.
 - Leave unsubscribes from the room.

protocol.md

@@ -49,7 +49,7 @@ Note: Keepalive frames are special and bypass this envelope entirely. When the e
 ## Message Types
 
 - 0x00: JoinRequest.
-  - `varBytes` authentication payload for the target room.
+  - `varBytes` join payload (application-defined metadata such as auth/session info).
   - `varBytes` for the requester's document version.
 - 0x01: JoinResponseOk.
   - `varString` permission: "read" | "write".
@@ -80,9 +80,9 @@ Note: Keepalive frames are special and bypass this envelope entirely. When the e
 
 Req sends a `JoinRequest` to Recv.
 
-- If authentication fails, Recv sends `JoinError(code=0x02 auth_failed)`.
-- If authentication succeeds but the version is unknown, Recv sends `JoinError(code=0x01 version_unknown)` and includes its version.
-- If authentication succeeds, Recv sends `JoinResponseOk` with its latest known version of the document. Recv may then send the updates missing from Req through `DocUpdate` or `DocUpdateFragment` messages.
+- If Recv rejects the join payload (e.g., authentication/authorization fails), it sends `JoinError(code=0x02 auth_failed)`.
+- If the join payload is accepted but the version is unknown, Recv sends `JoinError(code=0x01 version_unknown)` and includes its version.
+- If the join payload is accepted, Recv sends `JoinResponseOk` with its latest known version of the document. Recv may then send the updates missing from Req through `DocUpdate` or `DocUpdateFragment` messages.
 
 When Recv receives updates in the same room from other peers, it broadcasts them to all the other peers through `DocUpdate` or `DocUpdateFragment` messages.
 
@@ -118,7 +118,7 @@ Codes:
 
 - 0x00 unknown: unspecified error.
 - 0x01 version_unknown: cannot interpret provided version. Extra: `receiver_version`.
-- 0x02 auth_failed: authentication/authorization failed.
+- 0x02 auth_failed: authentication/authorization failed or the join payload was rejected.
 - 0x7F app_error: Extra `varString app_code` (free-form, e.g., `quota_exceeded`).
 
 ### UpdateError (0x06)