Skip to main content

Server–client mode

In this mode the server owns the documents, through a server registry. It validates each handshake with version vectors, applies incoming changes, broadcasts them to the other clients, and takes snapshots to prune the history every client has confirmed.

This group has two pages: this one and the server registry. Plugins, connection, compatibility and the framework adapters work the same in the relay mode: see What both modes share.

Quick start​

This is the standalone dart:io server. In a Dart Frog or Serverpod backend, use the framework adapter instead: the client is the same.

Server​

The server serves only the documents its registry holds: register each one, or a client of it is refused with DOCUMENT_NOT_FOUND.

import 'dart:io';

import 'package:crdt_socket_sync/web_socket_server.dart';

/// Starts a sync server on [port] that hosts the note `notes`.
Future<WebSocketServer> startServer({int port = 8080}) async {
final registry = InMemoryCRDTServerRegistry();

// The server answers DOCUMENT_NOT_FOUND for a document it does not hold.
await registry.addDocument('notes');

final server = WebSocketServer(
serverFactory: () => HttpServer.bind(InternetAddress.anyIPv4, port),
serverRegistry: registry,
);
await server.start();
return server;
}

Client​

Every client opens the document with the same documentId the server registered:

import 'package:crdt_lf/crdt_lf.dart';
import 'package:crdt_socket_sync/web_socket_client.dart';

/// Opens the note [documentId] and connects it to the server at [url].
///
/// [onStatus] gets every move of the connection status.
Future<({WebSocketClient client, CRDTFugueTextHandler text})> connectClient(
String url, {
String documentId = 'notes',
void Function(ConnectionStatus status)? onStatus,
}) async {
// The same documentId on every client: the server registered it.
final document = CRDTDocument(
documentId: documentId,
peerId: PeerId.generate(),
);
final text = CRDTFugueTextHandler(document, 'body');

final client = WebSocketClient(
url: url,
document: document,
author: document.peerId,
);
client.connectionStatus.listen(onStatus);

// Returns false when the handshake fails (DOCUMENT_NOT_FOUND, say),
// and the client retries on its own.
await client.connect();

return (client: client, text: text);
}

In an app, open the document through CRDTReplica: it restores the local copy before it connects.

How it works​

Connection and handshake​

The handshake also checks that the client's build can read what the document holds: see Versions and compatibility.

Real-time updates​

Out-of-sync recovery​

When a client receives a change it cannot apply yet (a change it depends on is missing), it asks the server for the document again:

Server events​

Monitor what happens on the server:

server.serverEvents.listen((event) {
if (event.type == ServerEventType.error) {
log('Sync error: ${event.message}');
}
});

Every event has a type, a message and, for some types, data. The types are the values of ServerEventType: a client that connects, a handshake, a change applied, a snapshot taken, an error.