Collaboration provider
Options, events and lifecycle of CollaborationProvider — tokens, saving with acknowledgements, reconnects, remote cursors — and the in-page LocalCollaborationBridge.
CollaborationProvider connects one WASM editor replica to GoTipe Cloud. It owns the WebSocket, the handshake, saving with acknowledgements, reconnects and awareness. The document, its undo history and any local storage stay with the editor and your app.
Install
npm install @gotipe/collaboration @gotipe/core @gotipe/wasmpnpm add @gotipe/collaboration @gotipe/core @gotipe/wasmyarn add @gotipe/collaboration @gotipe/core @gotipe/wasmbun add @gotipe/collaboration @gotipe/core @gotipe/wasmExample
This React component shows the carets of other people in BlockEditor from the commercial @gotipe/block-editor. state is the document's collaboration_state, loaded as in Connect to GoTipe Cloud.
import { BlockEditor } from "@gotipe/block-editor";
import { CollaborationProvider, type CollaborationState } from "@gotipe/collaboration";
import { createId } from "@gotipe/core";
import { FullPreset } from "@gotipe/core/presets";
import { useEditor } from "@gotipe/react";
import { useEffect, useMemo } from "react";
export function SharedDocument(props: {
documentId: string;
state: CollaborationState;
getToken: () => Promise<string>;
}) {
const { documentId, state, getToken } = props;
const editor = useEditor({ engine: "wasm", content: state.baseline, extensions: [FullPreset] });
// One peer ID per editor replica, kept across reconnects.
const peerId = useMemo(() => createId(), [editor]);
useEffect(() => {
if (!editor) return;
const provider = new CollaborationProvider({
documentId,
wsUrl: "wss://sync.example.com/sync",
peerId,
initialState: state,
token: getToken,
user: { name: "Alice", color: "#2c62d4" },
});
provider.connect(editor);
return () => provider.destroy();
}, [editor, peerId, documentId, state, getToken]);
// BlockEditor draws the people the provider writes into the editor's `collaboration` layer.
return <BlockEditor editor={editor} />;
}Options
| Option | Type | Default | Description |
|---|---|---|---|
documentId |
string |
— | Required. Sent as the document_id query parameter. |
wsUrl |
string |
— | An absolute ws: or wss: URL of the sync endpoint, for example wss:. No user info and no token parameter. |
user |
AwarenessUser |
— | { name, color, avatar? } that other peers see. name has at most 256 characters, color is #rgb or #rrggbb, avatar an http:, https: or data:image/ URL of at most 16 384 characters. Other fields are not sent. |
peerId |
string |
createId() |
The replica's ID: not blank, at most 256 bytes in UTF-8, not starting with @base. Stays the same across reconnects; every editor and every tab needs its own. |
initialState |
Collaboration |
— | { baseline, updates, generation } from Cloud. Applied once, on the first connect(). Create the editor from baseline. With generation the provider sends operations without the baseline; without it every frame repeats the baseline. |
token |
string | () => string | Promise< |
— | The credential. A function is called before every connection attempt. |
reconnect |
number |
1000 |
First reconnect delay in ms. It doubles on each attempt, up to 30 000. |
max |
number |
10 |
Attempts before the provider stops with an error. |
handshake |
number |
15000 |
Time in ms for each connection step: getting the token, opening the socket, receiving the state. |
acknowledgement |
number |
15000 |
Time in ms to wait for the server to confirm a saved update. |
createWebSocket |
( |
— | Your own socket factory, for example outside the browser or in tests. |
The constructor throws a TypeError for a wsUrl, user, peerId or generation that breaks these rules. Such a mistake can never connect, so it is not retried.
Methods
| Method | Description |
|---|---|
connect(editor) |
Applies initialState the first time, enables the replica, subscribes to the editor and opens the socket. On a stopped provider it resumes. Throws for a second editor or after destroy(). |
disconnect() |
Closes the socket and stops reconnecting. Edits stay in the editor; connect(editor) resumes the same replica. |
destroy() |
Final cleanup. Destroying a connected editor destroys its provider too. |
getState() |
The current ConnectionState. |
getSyncState() |
{ pending. |
getPeers() |
Copies of the other peers' PeerState. |
peerId |
The replica's ID (read-only). |
Events
Pass these callbacks as options.
| Option | Payload | When |
|---|---|---|
onStateChange |
"connecting" | "connected" | "disconnected" | "error" |
The connection changes. connected means the initial state exchange has finished. |
onSyncChange |
{ pending |
After local edits, saves and handshakes. pending counts operations the server has not confirmed; saving is true while a frame waits for its ACK. |
onPeersChange |
PeerState[] |
A peer joins, moves the caret or leaves. Empty after the connection drops. |
on |
— | The document's content was replaced in GoTipe Cloud. The provider has stopped; load the document again. See When the document is replaced. |
onError |
Error |
A token, socket, protocol or saving failure, and recoverable problems such as an unreadable peer presence. A failure never turns into success. |
Tokens
- Pass a function as
token. The provider calls it before every connection attempt, so a reconnect gets a fresh short-lived token. A token that resolves afterdisconnect()ordestroy()is ignored. - The token travels as a WebSocket subprotocol,
gotipe.auth.<base64url>, next togotipe.v2andgotipe.v1. It never appears in the URL. - GoTipe Cloud checks the token, the
documents:writescope and editor access to the document before the upgrade. It closes the socket when the token expires or is revoked, and the provider reconnects with a new token. List your browser origins inSYNC_ALLOWED_ORIGINS. See Authentication.
Saving and reconnecting
- One frame is in flight at a time. It carries operations the server has not confirmed, oldest first, and nothing else: no baseline and no operation sent before. A frame holds at most 512 KiB, half of what Cloud accepts in one message, so a large document or a long offline session takes more frames, not a larger one.
- A frame always ends after a whole edit (transaction): other editors check the document they receive, and half an edit is no valid document. An edit larger than a frame goes whole when it fits into a message (1 MiB); a larger one, such as a long paste, goes as parts that Cloud keeps until the last one, then saves and confirms together. If the connection drops in between, nothing was saved and the whole edit is sent again.
- Operations a peer typed into an inline atom it did not know (a mention, a formula) lose the atom's marks when they arrive. That repair is a local edit outside the undo history, sent to everyone, so all editors agree.
- The server writes the frame to its database, then answers with an empty ACK and forwards the operations to the other peers. A duplicate gets an ACK too.
- Typing is merged: after a pause a frame leaves at once, during a burst at most one every 50 ms, and over time at most 300 frames a minute. Nothing is dropped; later keystrokes travel in the next frame.
- Without an ACK within
acknowledgementTimeout, the provider reconnects. The handshake then shows which operations the server already has, and only the rest is sent again. - The handshake also finds operations in the editor that the server lacks and that this replica did not make, such as a local copy of a closed tab. They are sent once, before the replica's own.
- Reconnect delays double from
reconnectIntervalup to 30 seconds and reset after a successful handshake. With the defaults the provider tries for about three minutes (1, 2, 4, 8, 16, then 30 seconds), then reportserrorand stops. Edits stay in the editor; callconnect(editor)to try again.
The provider offers the subprotocols gotipe.v2 and gotipe.v1. With gotipe.v2 it names the baseline by initialState.generation. Without a generation, or with a server that selects gotipe.v1, it falls back to the first protocol: the same rules, but every frame repeats the baseline, so the baseline itself must fit into a message.
| Failure | What the provider does |
|---|---|
| The socket closes | Reports disconnected and reconnects. |
A socket error, a timeout, a token function that throws, the server error UPDATE_NOT_SAVED |
Calls onError and reconnects. |
The browser refuses the endpoint (SecurityError, for example ws: from an HTTPS page) |
Calls onError and stops without retrying. |
An unreadable presence from a peer, the server error INVALID_AWARENESS |
Calls onError and keeps working. The peer's caret disappears until its next valid presence. |
The server error BASELINE_REPLACED (also when it refuses the generation at the handshake), or a full state from another baseline |
Stops and calls on. See below. |
The server error UPDATE_TOO_LARGE (an edit larger than SYNC_TRANSACTION_LIMIT) |
Calls onError, reconnects and sends that edit in frames the server takes one by one. Other editors may see it in pieces; one their schema refuses waits until the rest arrives. |
One operation larger than a message (1 MiB), the server error DOCUMENT_TOO_LARGE, or over gotipe.v1 a baseline or an edit that does not fit into one message |
Calls onError and stops; reconnecting cannot help. |
| A malformed frame, an unexpected ACK, an update the editor rejects, any other server error | Calls onError and stops. Fix the cause, then call connect(editor). |
When the document is replaced
A replica can only merge edits made from the same baseline. When someone replaces the document's content over REST (PATCH with content, or a version restore), GoTipe Cloud sends BASELINE_REPLACED to every connected editor and closes their connections. An editor that was offline, or that loaded the document just before the replacement, gets the same answer at its next handshake, because its generation no longer matches.
The provider then stops for good: reconnecting cannot help. It reports disconnected and calls onBaselineReplaced; without that option it reports error and calls onError. Edits the server had not confirmed stay in the editor but cannot be saved: getSyncState().pendingOperations tells how many. Load the document again and create a new editor and provider:
import { CollaborationProvider, type CollaborationState } from "@gotipe/collaboration";
import { createEditor, type GoTipeEditor } from "@gotipe/core";
import { FullPreset } from "@gotipe/core/presets";
export async function openShared(
documentId: string,
load: () => Promise<CollaborationState>,
getToken: () => Promise<string>,
mount: (editor: GoTipeEditor) => void,
): Promise<() => void> {
const initialState = await load();
const editor = await createEditor({
engine: "wasm",
content: initialState.baseline,
extensions: [FullPreset],
});
let close = () => {};
const provider = new CollaborationProvider({
documentId,
wsUrl: "wss://sync.example.com/sync",
initialState,
token: getToken,
user: { name: "Alice", color: "#3264ab" },
onBaselineReplaced: () => {
const unsaved = provider.getSyncState().pendingOperations;
if (unsaved) console.warn(`${unsaved} unsaved changes were replaced`);
close();
void openShared(documentId, load, getToken, mount).then((next) => {
close = next;
});
},
});
provider.connect(editor);
mount(editor);
close = () => {
provider.destroy();
editor.destroy();
};
return () => close();
}Awareness and remote cursors
After each handshake, and then whenever the caret or the selection changes, the provider sends the local peer: user, the caret as cursor: { blockId, offset } (the selection head), and selection: { blockId, from, to } for a range inside one block. A selection across blocks shows only the caret. Changes are sent at most once per 100 ms, after the last one, and only if they differ from what peers already have: edits from other peers do not resend your presence.
Remote peers arrive in onPeersChange as PeerState[]. The provider also writes them to the editor's collaboration decoration layer as remote-cursor and remote-selection decorations. Peers disappear when they leave, and all at once when the connection drops. The server relays awareness and does not store it.
Each person is drawn once, by one owner:
BlockEditordraws the layer with its overlay and leaves it out of the document. ItsremotePeersprop adds people from another source; a peer ID in both is drawn once.EditorandEditorContentof@gotipe/reactandEditorContentof@gotipe/vuedraw the layer inside the text: a caret with the name, and a tinted range.- To draw the layer yourself, name it in
hostLayersand the renderer leaves it out. For example, the overlay ofBlockEditorover an editor surface of your own:
import {
COLLABORATION_LAYER,
CollaborationCursors,
type RemotePeer,
} from "@gotipe/block-editor";
import type { GoTipeEditor } from "@gotipe/core";
import { Editor } from "@gotipe/react";
import { useRef } from "react";
export function EditorWithCursors(props: { editor: GoTipeEditor; peers: RemotePeer[] }) {
const container = useRef<HTMLDivElement>(null);
return (
<div ref={container} style={{ position: "relative" }}>
<Editor editor={props.editor} hostLayers={[COLLABORATION_LAYER]} />
<CollaborationCursors peers={props.peers} containerRef={container} />
</div>
);
}peersFromDecorations(editor.getDecorations(COLLABORATION_LAYER)) turns the layer into RemotePeer[]; read it again on the editor's decorationsChange event.
Each caret carries the peer's name in their color; selections are tinted. Positions follow container scroll and window resize.
The extension
defineCollaboration creates and connects a provider when the editor is created and destroys it with the editor. It takes the same options and does nothing without documentId and wsUrl. Without user, peers see Anonymous in #6366f1.
import {
type CollaborationState,
defineCollaboration,
getCollaborationProvider,
} from "@gotipe/collaboration";
import { createEditor } from "@gotipe/core";
import { FullPreset } from "@gotipe/core/presets";
export async function createSharedEditor(
initialState: CollaborationState,
getToken: () => Promise<string>,
) {
const editor = await createEditor({
engine: "wasm",
content: initialState.baseline,
extensions: [
FullPreset,
defineCollaboration.configure({
documentId: "doc-123",
wsUrl: "wss://sync.example.com/sync",
initialState,
token: getToken,
user: { name: "Alice", color: "#3264ab" },
}),
],
});
return { editor, provider: getCollaborationProvider(editor) };
}LocalCollaborationBridge
LocalCollaborationBridge syncs editors on one page without a server, for demos, tests and side-by-side views. It sends the same CRDT updates as the provider, with no storage and no authentication. Create every editor with engine: "wasm" from the same content, block IDs included.
import { LocalCollaborationBridge } from "@gotipe/collaboration";
import { createEditor } from "@gotipe/core";
import { DefaultPreset } from "@gotipe/core/presets";
const content = {
version: 1,
blocks: [
{
id: "intro",
type: "paragraph",
attrs: {},
content: [{ text: "Type in either editor.", marks: [] }],
children: [],
},
],
};
const [left, right] = await Promise.all([
createEditor({ engine: "wasm", content, extensions: [DefaultPreset] }),
createEditor({ engine: "wasm", content, extensions: [DefaultPreset] }),
]);
left.mount(document.querySelector<HTMLElement>("#left")!);
right.mount(document.querySelector<HTMLElement>("#right")!);
const bridge = new LocalCollaborationBridge();
bridge.join("alice", left, { name: "Alice", color: "#2c62d4" });
bridge.join("bob", right, { name: "Bob", color: "#2b7547" });
bridge.onPeersChange(() => console.log(bridge.getPeersFor("alice")));| Method | Description |
|---|---|
join( |
Enables the replica, replays the operations of the editors already joined and starts syncing. Throws for a destroyed editor or a peer ID that another editor uses. |
leave(peerId) |
Stops syncing one editor. Destroying an editor leaves too. |
get / getAllPeers() |
The peers other than peerId / every peer. |
on |
Called with every peer on joins, leaves and caret moves. Returns an unsubscribe function. |
destroy() |
Removes every editor and callback. |
The bridge writes no decorations: pass getPeersFor(peerId) to remotePeers or CollaborationCursors. Its caret is the selection anchor, while the provider sends the head.
Limitations
- One operation cannot exceed a WebSocket message of GoTipe Cloud, 1 MiB. Text and formatting never come near it; a file embedded in an attribute as a
data:URL can. Keep files in host storage. - Without
initialState.generationthe provider uses the first protocol, whose frames repeat the baseline: a document of about 1 MiB or more, or an edit larger than one message, then cannot sync. - GoTipe Cloud saves an edit whole up to
SYNC_TRANSACTION_LIMIT(16 MiB by default); a larger one is saved in pieces. A document's stored state may not exceed 60 MiB. acknowledgementTimeoutstarts once the browser has sent the frame (bufferedAmount), so a slow connection does not cause reconnects. Reconnect attempts are counted until an edit is confirmed.LocalCollaborationBridgeand your own transport built ongetCollaborationUpdate()without options still exchange the full state on every change.CollaborationCursorsshows names, not avatars.- GoTipe Cloud limits messages per connection (
RATE_LIMIT_WS, 1000 per minute by default) and closes the socket with code 1008 above it. The provider sends at most 300 update frames and 600 presence messages in any minute, so it stays below the default. If you lower the limit below about 900, connections of people who type continuously will be closed and reconnect. - After the document is replaced, edits the server had not confirmed are not merged into the new content; the provider only counts them.
Related
- Collaboration: how replication works and what is shared.
- Offline and conflicts: pending edits, local copies, IME.
- Realtime: the frames and the server side.
- BlockEditor: the
remotePeersprop.