Skip to main content

Sync

crdt_socket_sync sends each change to the other peers as it happens, over WebSocket. A peer that was offline catches up when it reconnects, and a client that cannot keep up is dropped and re-syncs. It comes with reconnection, liveness checks, history pruning, a version handshake and plugins (such as awareness, for remote cursors).

dart pub add crdt_socket_sync

It plugs into your server​

You do not need a dedicated sync server. The sync protocol runs inside the backend framework you already use:

FrameworkPackage
Dart Frogcrdt_socket_sync_dart_frog: handlers ready to return from a route
Serverpodcrdt_socket_sync_serverpod: web routes ready to add to your pod
plain dart:ioWebSocketServer / WebSocketRelayServer, included in crdt_socket_sync
anything elsea transport of your own, or a relay in any language

Your authentication, routing and deployment stay the framework's. The server frameworks page shows both, side by side. The client is the same whatever the server: a WebSocketClient or a WebSocketRelayClient, usually opened through a replica.

Two modes​

The package has two independent sync models. The only fundamental difference is where the CRDT logic lives:

Server–clientRelay
The serverunderstands crdt_lf: holds the documents, applies and merges changesstores and rebroadcasts opaque change blobs; never parses CRDT data
Mergingon the server and on the clientson the clients only
History pruningthe server takes a snapshot once every client is alignedthe relay asks one client to upload a snapshot
Server codeDart, with crdt_lfany runtime: Dart, a Cloudflare Worker in TypeScript, …
Pick it whenone authoritative backend should understand the documentsyou want a cheap, CRDT-agnostic backend, easy to port and to scale

Everything else (delivery guarantees, reconnect policy, initial sync) follows from that choice.

Several Flutter clients synced through one server

How this section is organized​

Pick a mode with the table above, then read its group and the shared one. You can skip the group of the other mode.

Server–client mode​

A server that holds the documents and merges the changes.

  • Server–client mode: quick start, how the handshake and the pruning work, the server events.
  • Server registry: where the server keeps its documents, in memory or on disk with any storage adapter.
  • Examples: a persistent server with the awareness plugin, and its Flutter client, with the same screens as the Flutter examples. The repository has VS Code launch settings to run both.

Relay mode​

A server that stores and forwards opaque blobs. The clients do all the merging.

  • Relay mode: quick start, join and push, log compaction, and how Greyhound Markdown uses it.
  • Relay protocol: the JSON contract, to write a relay on any runtime.
  • Example: Greyhound Markdown syncs through a relay, live and on your machine. The live app talks to a Cloudflare Worker written in TypeScript. Locally, the same client talks to a Dart Frog or Serverpod relay from the repository: see Greyhound Markdown on a relay.

Both modes​

What both modes share lists the pages that apply to either mode:

Imports​

One library per side and per mode:

// Both modes. CRDTReplica: the document, its local storage and its client
import 'package:crdt_socket_sync/replica.dart';

// Server–client mode
import 'package:crdt_socket_sync/client.dart'; // client interfaces
import 'package:crdt_socket_sync/web_socket_client.dart'; // WebSocket client
import 'package:crdt_socket_sync/server.dart'; // server interfaces, DocumentSessionHost (no dart:io)
import 'package:crdt_socket_sync/web_socket_server.dart'; // WebSocket server (dart:io)

// Relay mode
import 'package:crdt_socket_sync/relay_client.dart'; // relay client interfaces
import 'package:crdt_socket_sync/web_socket_relay_client.dart'; // WebSocket relay client
import 'package:crdt_socket_sync/relay_server.dart'; // RelayStore, RelaySessionHost (no dart:io)
import 'package:crdt_socket_sync/web_socket_relay_server.dart'; // WebSocket relay server (dart:io)

Runnable Dart Frog and Serverpod servers, one per mode, are listed in Server frameworks.