Skip to main content

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​

  • open restores 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. Follow replica.client!.connectionStatus for the connection.
  • close disposes the client, writes what is still waiting, then closes the document and the storage.
  • Leave storage out to keep the document in memory. Leave sync out to keep it on this device.
  • storage returns any storage backend: CRDTHive.open, () => CRDTSqlite.open('notes.db'), a Drift one.
  • sync returns the client of your mode: a WebSocketRelayClient for the relay mode, a WebSocketClient for the server–client mode.
  • onDocument runs on the new document before the restore. Use it for what has to exist first, such as a listener on events.
  • Pass onStorageError to keep going when the storage cannot be read: the document then starts empty, in memory, and onDocument runs again on it. Without it, open throws.
Why the order matters

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