Open a replica
A client app needs three things together: the document as this device last
left it, a storage that keeps writing it down, and a sync client. They have to
open and close in a set order. CRDTReplica, from
crdt_socket_sync, holds all
three and keeps that order.
import 'package:crdt_lf/crdt_lf.dart';
import 'package:crdt_lf_hive/crdt_lf_hive.dart';
import 'package:crdt_socket_sync/replica.dart';
import 'package:crdt_socket_sync/web_socket_relay_client.dart';
import 'package:flutter/foundation.dart';
/// Opens the note on this device, and syncs it through the relay at [url].
///
/// Completes once the local copy is ready, even when the relay is down.
Future<CRDTReplica> openNote(String url) async {
final replica = await CRDTReplica.open(
// The relay room: every peer of the note opens the same id.
documentId: 'note',
storage: CRDTHive.open,
sync:
(document) => WebSocketRelayClient(
url: url,
document: document,
author: document.peerId,
),
// Without it, a storage that cannot be read makes `open` throw. With it,
// the note starts empty and in memory.
onStorageError: (error, stack) => debugPrint('Storage error: $error'),
);
CRDTFugueTextHandler(replica.document, 'note');
return replica;
}
The handlers are built on replica.document. When the app is done with it,
await replica.close(). The
offline-first recipe is the complete
Flutter app around this function: the page that opens and closes the replica,
and the connection status.
What open and close do
openrestores the document first, then builds the client on it and starts to connect. It returns without waiting for the network, so the local copy is ready at once. Followreplica.client!.connectionStatusfor the connection.closedisposes the client, writes what is still waiting, then closes the document and the storage.- Leave
storageout to keep the document in memory. Leavesyncout to keep it on this device. storagereturns any storage backend:CRDTHive.open,() => CRDTSqlite.open('notes.db'), a Drift one.syncreturns the client of your mode: aWebSocketRelayClientfor the relay mode, aWebSocketClientfor the server–client mode.onDocumentruns on the new document before the restore. Use it for what has to exist first, such as a listener onevents.- Pass
onStorageErrorto keep going when the storage cannot be read: the document then starts empty, in memory, andonDocumentruns again on it. Without it,openthrows.
The restored document is what the sync client reconciles against. Restore first, connect second, and what you wrote on a plane reaches the others after the restart. Connect first, and the client catches up from the server before it knows what it already had. Offline, or on a relay that has forgotten the room, the local copy is all there is.
A complete app: Greyhound Markdown
This is how Greyhound Markdown opens a room: a relay client with the awareness plugin, a Hive storage, a text handler and an undo manager. Source: room_host.dart.
// 1. Who else is in the room, and where their carets are. `AwarenessService`
// is the app's own wrapper over the awareness plugin of crdt_socket_sync.
final awareness = AwarenessService(
name: profile.displayName,
color: profile.color,
);
// 2. The document as this device last left it, and the relay client on it.
// The backend keeps the identity too, so the device writes under the same
// author on every launch.
final replica = await CRDTReplica.open(
documentId: roomId,
storage: CRDTHive.open,
sync: (document) => WebSocketRelayClient(
url: roomUrl(kServerUrl, roomId),
document: document,
author: document.peerId,
plugins: [awareness.plugin],
),
// A device that cannot read its storage still edits the room.
onStorageError: reportRoomError,
);
// 3. The handler, built on the restored document.
final text = CRDTFugueTextHandler(replica.document, kHandlerId);
final undo = CRDTUndoManager(replica.document)..track(text);
Closing is one call too. What the app built goes first. Then close stops the
client, writes what is still waiting, and lets the document and the storage go:
undo.dispose();
awareness.dispose();
await replica.close();
The editor on top of it
crdt_lf_flutter turns the handler into a TextEditingController and draws the
remote carets. CrdtTextFieldBuilder owns the controller and keeps it in step
with the document both ways. onSelectionAnchorsChanged reports this user's
caret to awareness, and CrdtTextCursorsOverlay paints everyone else's.
Source:
editor_pane.dart.
CrdtTextFieldBuilder(
id: kHandlerId,
// This user's caret, on every selection change.
onSelectionAnchorsChanged: awareness.setLocalCursor,
builder: (context, controller) =>
ValueListenableBuilder<Map<String, PeerState>>(
// Everyone else's, as they move.
valueListenable: awareness.peers,
builder: (context, peers, child) => CrdtTextCursorsOverlay(
id: kHandlerId,
cursors: [
for (final entry in peers.entries)
if (entry.value.base != null)
CrdtTextCursor(
id: entry.key,
label: entry.value.name,
color: entry.value.color,
base: entry.value.base!,
extent: entry.value.extent,
),
],
child: child!,
),
child: TextField(controller: controller, maxLines: null),
),
)
The document is reached through CrdtProvider, so nothing above has to be
passed down.
Without a replica
CRDTReplica is a convenience. You can open the pieces yourself; keep the same
order:
final backend = CRDTSqlite.open('notes.db');
final room = await backend.openDocument('notes'); // 1. restore
final client = WebSocketClient(
url: 'ws://localhost:8080',
document: room.document,
author: room.document.peerId,
);
await client.connect(); // 2. only now