Motivation

When a join is refused, LoroWebsocketClient rejects with a plain Error whose only content is the formatted string:

const err = new Error(`Join failed: ${msg.code} - ${msg.message}`);

That leaves an application no way to tell one refusal from another except by parsing that text. The protocol already anticipates this case — protocol.md documents 0x7F app_error as carrying an extra varString app_code ("free-form, e.g. quota_exceeded"), and encoding.ts decodes it faithfully — but the client discards appCode (and the numeric code) before the value reaches the caller. protocol.md also sketches the hook this closes:

Implementations may expose onError({ roomId, kind, code, message, app_code? }) for join or room messages …

Our own use case: our server permanently destroys a room when the underlying record is purged, and refuses any later join for it. Clients must treat that refusal as terminal — evict the local document, stop the reconnect loop — while every other refusal stays retryable. Today we express that by sending app_error with a sentinel message string and substring-matching it on the client, with a comment next to the matcher saying "switch to err.code when the library exposes it". With this change we can send it as an app_code and branch on a typed field instead.

Scope

One narrow change, in packages/loro-websocket:

• Add an exported JoinFailedError extends Error carrying code, appCode, roomId and crdt.
• Reject from handleJoinError with it instead of a bare Error.

Notes:

• No wire change. No new enum member, no renumbering, no encoder/decoder edit — appCode was already on the wire and already decoded. Nothing in rust/ needs a counterpart.
• Backwards compatible. err.message is byte-identical to before (Join failed: <code> - <message>), so consumers still matching on the string are unaffected; JoinFailedError is an Error, so instanceof Error and existing catch blocks behave the same.
• The VersionUnknown retry path is untouched.

I deliberately left the onRoomStatusChange listener signature alone — it already forwards the numeric code as messageCode, and widening it to carry appCode felt like a separate call. Happy to add it here if you'd prefer the two paths to match.

Tests

pnpm -r test — one test added in packages/loro-websocket/src/client/index.test.ts asserting an app_error join refusal rejects with a JoinFailedError exposing code and appCode. Full suite green (104 passing).

pnpm lint is clean (3 pre-existing warnings, 0 errors) and packages/loro-websocket typechecks. Two notes on pre-existing state, unrelated to this branch: pnpm typecheck fails in loro-adaptors (src/elo-adaptor.ts, duplicate CryptoKey types), and pnpm format:check is red for 34 files on main — including both files this PR touches — so I matched the surrounding style rather than reformatting them.

Thanks for the protocol and for the work on this repo — happy to adjust the shape of this however you'd like.