@jxsuite/collab 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/collab",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Realtime co-editing for Jx Studio — Y.Doc schema, op bridge, structural differ, wire envelope, and provider contracts shared by every collab backend",
   "license": "MIT",
   "repository": {
@@ -19,6 +19,7 @@
     "./op-bridge": "./src/op-bridge.ts",
     "./diff": "./src/diff.ts",
     "./envelope": "./src/envelope.ts",
+    "./negotiate": "./src/negotiate.ts",
     "./awareness-types": "./src/awareness-types.ts",
     "./provider": "./src/provider.ts",
     "./client": "./src/ws-client.ts",
@@ -32,7 +33,7 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/schema": "^1.5.0",
+    "@jxsuite/schema": "^1.6.0",
     "lib0": "^0.2.99",
     "y-protocols": "^1.0.6",
     "yjs": "13.6.27"

package/src/awareness-types.ts

@@ -21,8 +21,14 @@ export interface CollabAwarenessState {
   focusedPath: string | null;
   /** Which representation the client is editing (drives the Phase-B canonical lock). */
   mode?: "structure" | "source";
-  /** The client's structural (canvas) selection in the focused document. */
-  structuralSelection?: JxPath | null;
+  /**
+   * The client's structural (canvas) selection in the focused document — the whole SET.
+   *
+   * A list because `session.selection` is one (studio §6.5): a peer who has selected six cards
+   * publishes six paths, and the remote canvas draws a presence box for each. A peer with one node
+   * selected publishes a one-entry list, which draws exactly the one box it always did.
+   */
+  structuralSelection?: JxPath[] | null;
   /**
    * RESERVED for y-monaco: the in-buffer text cursor as {anchor, head} Y.RelativePosition JSON.
    * MonacoBinding owns this field via setLocalStateField("selection", …) while a code view is

package/src/envelope.ts

@@ -14,11 +14,17 @@
  * are dropped and answered with a `doc-reset` control message, upon which the client destroys its
  * Y.Doc and re-opens. The invariant "Y history is never deleted or replaced without an epoch bump"
  * is what prevents divergent-history duplicate-content merges.
+ *
+ * The layout above is what the `jx.collab.v1` WebSocket subprotocol names. A change that would make
+ * a peer mis-parse a frame is a new token, not a silent edit here — see `negotiate.ts` for the bump
+ * rule and for why the capability probe, not the socket, is where the two sides agree.
  */
 
 import * as decoding from "lib0/decoding";
 import * as encoding from "lib0/encoding";
 
+export { COLLAB_SUBPROTOCOL } from "./negotiate.ts";
+
 export const FRAME_DOC_SYNC = 0;
 export const FRAME_AWARENESS = 1;
 export const FRAME_DOC_CLOSE = 2;

package/src/negotiate.ts

@@ -0,0 +1,131 @@
+/**
+ * WebSocket subprotocol negotiation for the collab socket (RFC 6455 §1.9, §4.2.2).
+ *
+ * **The token names the wire envelope, not the package.** `jx.collab.v1` means "I speak the frame
+ * layout `envelope.ts` documents". There is one token per envelope **major**, and the rule for
+ * bumping it is narrow on purpose: bump when {@link decodeFrame} would _mis-parse_ a peer's frame —
+ * a field reordered, a type widened, a length prefix changed. **Do not bump for a new frame type.**
+ * Both halves already skip a frame type they do not know, so a v1 peer and a v1-plus-one-frame peer
+ * interoperate; bumping there would refuse a room that would have worked.
+ *
+ * **Why the capability probe does the negotiating.** RFC 6455 §4.1 requires a client that offered
+ * subprotocols and received no echo to _fail the connection_, and browsers enforce it. So a new
+ * Studio that unconditionally offered `jx.collab.v1` would lose collab entirely against an older
+ * dev server — a regression caused by the fix. The probe already exists, already returns a version
+ * the client discards, and runs before the socket: it is the one place the client can learn what
+ * the server speaks without risking the handshake. Hence {@link negotiateCollab}, which turns a
+ * probe body into the list to offer — empty against a server that advertises nothing.
+ *
+ * **Nothing here may go in the `hello` control message.** That arrives after the socket is up and
+ * after frames may already have been exchanged, which is too late to prevent the divergent-history
+ * merge `schema.ts` warns about. Negotiation has to conclude before a byte of document state
+ * moves.
+ *
+ * This module imports nothing, deliberately: the Studio platform adapters read it eagerly, before
+ * the dynamic import that pulls in Yjs, so it must not drag the CRDT into the initial bundle.
+ */
+
+/** The subprotocol token for the envelope in `envelope.ts`. One token per envelope major. */
+export const COLLAB_SUBPROTOCOL = "jx.collab.v1";
+
+/** What the client should do with the socket, given what the server advertised. */
+export interface CollabNegotiation {
+  /**
+   * The subprotocols to offer as `Sec-WebSocket-Protocol`. **Empty means offer none**, which is the
+   * correct answer against a server that advertises none: an offer it cannot echo would fail the
+   * handshake outright, where offering nothing connects exactly as it does today.
+   */
+  offer: string[];
+  /**
+   * Non-null when the peers cannot interoperate: the server advertised subprotocols and none of
+   * them is one we speak. The client must not connect — the string says which side speaks what, so
+   * the degradation is legible rather than a silent solo session.
+   */
+  refused: string | null;
+}
+
+/**
+ * Decide what to offer, from the body of a `GET /__studio/collab` capability probe.
+ *
+ * @param {unknown} probe The parsed probe body, or null if it did not parse as JSON.
+ * @returns {CollabNegotiation}
+ */
+export function negotiateCollab(probe: unknown): CollabNegotiation {
+  if (probe === null || typeof probe !== "object") {
+    // A 200 that is not a JSON object: pre-negotiation server. Connect as before, offering nothing.
+    return { offer: [], refused: null };
+  }
+  const body = probe as { collab?: unknown; protocols?: unknown };
+  if (body.collab === false) {
+    return { offer: [], refused: "This server has collaboration disabled." };
+  }
+  const { protocols } = body;
+  if (!Array.isArray(protocols) || protocols.length === 0) {
+    // A server that predates negotiation. It would echo nothing, so we must offer nothing.
+    return { offer: [], refused: null };
+  }
+  if (protocols.includes(COLLAB_SUBPROTOCOL)) {
+    return { offer: [COLLAB_SUBPROTOCOL], refused: null };
+  }
+  const theirs = protocols.filter((p) => typeof p === "string").join(", ") || "none";
+  return {
+    offer: [],
+    refused: `This server speaks collab envelope ${theirs}; this editor speaks ${COLLAB_SUBPROTOCOL}.`,
+  };
+}
+
+/**
+ * The subprotocols a client offered, from its `Sec-WebSocket-Protocol` request header.
+ *
+ * RFC 6455 §4.1 allows the field to be split across several header lines and comma-separated within
+ * one; `Headers.get` already joins repeats with `, `, so one split covers both spellings.
+ *
+ * @param {string | null} header
+ * @returns {string[]}
+ */
+export function offeredSubprotocols(header: string | null): string[] {
+  if (!header) {
+    return [];
+  }
+  return header
+    .split(",")
+    .map((token) => token.trim())
+    .filter((token) => token !== "");
+}
+
+/** What the server should do with an upgrade, given the client's offer. */
+export interface SubprotocolAnswer {
+  /** The token to echo in the 101 response, or null to echo nothing. */
+  echo: string | null;
+  /** Non-null when the handshake must be refused instead of upgraded. */
+  reject: string | null;
+}
+
+/**
+ * Choose the subprotocol to echo (RFC 6455 §4.2.2 step 4).
+ *
+ * Three cases, and the middle one is the one that is easy to get wrong:
+ *
+ * - **No offer** — an older client. Upgrade and echo nothing; it is not expecting an echo, and
+ *   refusing it would break every Studio built before this shipped.
+ * - **An offer we speak** — echo exactly that token. Echoing a token the client did not offer is
+ *   itself a protocol violation, so the echo is always a member of the offer.
+ * - **An offer we do not speak** — refuse. This is the whole point: two peers whose envelopes
+ *   disagree about merge granularity (see `collab.md` §3.1) must not end up in one room, and a
+ *   refused handshake is a far better outcome than a divergent-history merge.
+ *
+ * @param {string[]} offered
+ * @returns {SubprotocolAnswer}
+ */
+export function selectSubprotocol(offered: string[]): SubprotocolAnswer {
+  if (offered.length === 0) {
+    return { echo: null, reject: null };
+  }
+  if (offered.includes(COLLAB_SUBPROTOCOL)) {
+    return { echo: COLLAB_SUBPROTOCOL, reject: null };
+  }
+  return {
+    echo: null,
+    reject: `No supported collab subprotocol offered (this server speaks ${COLLAB_SUBPROTOCOL}).`,
+  };
+}

package/src/ws-client.ts

@@ -34,8 +34,17 @@ export interface WsLike {
 export interface WsCollabConnectionOptions {
   /** The ws(s):// endpoint for this project's collab socket. */
   url: string;
+  /**
+   * Subprotocols to offer (`Sec-WebSocket-Protocol`), normally `negotiateCollab`'s `offer`.
+   *
+   * Left empty or undefined deliberately when the server advertised none: RFC 6455 §4.1 makes a
+   * client that offers a subprotocol and receives no echo fail the connection, so an unconditional
+   * offer would break collab against every server built before negotiation shipped. The caller
+   * decides, from the capability probe, and `negotiate.ts` holds the reasoning.
+   */
+  protocols?: string[];
   /** WebSocket constructor override (tests, non-browser runtimes). */
-  webSocketImpl?: new (url: string) => WsLike;
+  webSocketImpl?: new (url: string, protocols?: string[]) => WsLike;
   /**
    * Called when the server refuses a doc with content-not-loaded: hydrate the file over HTTP (which
    * caches it server-side) so the retry can seed. One retry per open.
@@ -74,7 +83,8 @@ interface DocEntry {
 
 export function createWsCollabConnection(options: WsCollabConnectionOptions): WsCollabConnection {
   const WebSocketCtor =
-    options.webSocketImpl ?? (globalThis.WebSocket as unknown as new (url: string) => WsLike);
+    options.webSocketImpl ??
+    (globalThis.WebSocket as unknown as new (url: string, protocols?: string[]) => WsLike);
   const openTimeoutMs = options.openTimeoutMs ?? 10_000;
   const docs = new Map<string, DocEntry>();
   const statusCbs = new Set<(status: CollabStatus) => void>();
@@ -257,7 +267,13 @@ export function createWsCollabConnection(options: WsCollabConnectionOptions): Ws
       return;
     }
     setStatus("connecting");
-    const ws = new WebSocketCtor(options.url);
+    /* Re-offered on every reconnect: a socket that comes back after the server was restarted must
+       negotiate again, and the offer is a property of this client's envelope, not of one socket. */
+    const offer = options.protocols;
+    const ws =
+      offer === undefined || offer.length === 0
+        ? new WebSocketCtor(options.url)
+        : new WebSocketCtor(options.url, offer);
     socket = ws;
     ws.binaryType = "arraybuffer";
     /* Each connect() builds a FRESH socket; single-assignment handlers are the point (and keep