Skip to main content

Plugins and awareness

A plugin adds behavior to the client, to the server, or to both. Plugins work the same way in both modes.

Writing a plugin​

A plugin extends ClientSyncPlugin or ServerSyncPlugin. Extend, do not implement: the base class wires the plugin into its client or server. Pass it in the plugins list of the client or of the server.

  • The host calls the plugin for every message it decodes, and when a connection or a session opens and closes.
  • A plugin that sends messages of its own gives a messageCodec for them. Its messages extend Message and use type codes from 100 up (see Wire format).

The awareness plugin is the reference to copy: its client and its server. The members to override are in the API reference.

The same plugins work on the relay pair (WebSocketRelayClient / WebSocketRelayServer) unchanged: see Plugins on a relay. A server plugin instance belongs to one host: give each host its own.

Awareness plugin​

The awareness plugin shares presence: who is in the room, and ephemeral state such as their name, their color and where their caret is. It runs on both sides: ClientAwarenessPlugin on each client, ServerAwarenessPlugin on the server. Awareness state is never written into the document history, and a relay rebroadcasts it without storing it.

On the server, one plugin instance per host:

import 'dart:io';

import 'package:crdt_socket_sync/web_socket_relay_server.dart';

/// Starts a relay on [port] that also shares the presence of each room.
Future<WebSocketRelayServer> startPresenceRelay({int port = 8080}) async {
final server = WebSocketRelayServer(
serverFactory: () => HttpServer.bind(InternetAddress.anyIPv4, port),
// One instance per server: it keeps who is in which room.
plugins: [ServerAwarenessPlugin()],
);
await server.start();
return server;
}

On each client, with what the other peers should know about this one:

/// Opens the note on this device and joins it on the relay at [url], as
/// [name] drawn in [color].
Future<SharedNote> openNote(
String url, {
required String name,
required Color color,
}) async {
// Sent on every connection: who this peer is, before any caret.
final presence = ClientAwarenessPlugin(
initialMetadata: {'name': name, 'color': color.toARGB32()},
);
final replica = await CRDTReplica.open(
documentId: 'note',
storage: CRDTHive.open,
sync:
(document) => WebSocketRelayClient(
url: url,
document: document,
author: document.peerId,
plugins: [presence],
),
);
// The cursors need a Fugue text: its anchors stay valid after any edit.
final text = CRDTFugueTextHandler(replica.document, 'note');
return (replica: replica, presence: presence, text: text);
}

A WebSocketServer and a WebSocketClient take the same two plugins, in the same plugins argument.

This is the channel for the Flutter text cursors and mouse pointers: publish the local caret or pointer into the awareness state, and map the other peers' states to cursors. The presence recipe does both, from the server to the carets on screen.

The server example and its Flutter client use it to show the active users (name, surname, a random color) and their position in the document.