Custom transport
Every server in this package has two parts:
- a session host:
DocumentSessionHost(server–client) orRelaySessionHost(relay). It keeps the registry or the store, the sessions, the broadcasting, theServerEventstream and the coordinator of aligned snapshots. Both extendSessionHostServer, and have no socket of their own. - a transport that feeds it connections through
acceptConnection(TransportConnection).
WebSocketServer and WebSocketRelayServer are those hosts plus
IoWebSocketHost, a mixin that owns a dart:io HttpServer. The
Dart Frog and Serverpod adapters are the hosts plus
the framework's own sockets. There are two ways to put the protocol on a
different transport.
A transport you do not own
When a framework accepts the connections for you, use the host directly and hand it each socket:
import 'package:crdt_socket_sync/server.dart';
final host = DocumentSessionHost(serverRegistry: registry);
await host.start();
// Wherever your framework hands you a connected socket:
host.acceptConnection(WebSocketChannelConnection(channel));
acceptConnection takes any TransportConnection.
WebSocketChannelConnection covers every framework built on
package:web_socket_channel, and anything else is four members (incoming,
send, close, isConnected). It returns the session. When the host cannot
take the connection (stopped, disposed, or handed a session id already in use),
it closes the connection and returns null.
The transport does not have to be HTTP, or even a socket: the host tests drive
both protocols over a plain StreamController. What it must do is keep the
message boundaries: one send, one event on the peer's incoming. A WebSocket
or an isolate port does. A raw TCP socket does not, and needs its own framing
first.
Two things worth knowing:
start()is optional here. A host with no transport of its own starts on its first connection. Call it explicitly when you want theServerEventType.startedevent at a point you choose. Callstop()to refuse further connections and close the open ones.isRunningmeans "accepting sessions", not "listening on a socket". It is what gates the snapshot coordinator, so a stopped host takes no snapshot even with every client aligned.
server.dart and relay_server.dart are free of dart:io and stay that way: a
test in this package walks their imports and fails if one creeps in. Only
web_socket_server.dart and web_socket_relay_server.dart pull it in.
A transport the host owns
When the host should bind and listen itself, write a mixin like
IoWebSocketHost (exported from web_socket_server.dart and
web_socket_relay_server.dart, and worth reading: it is under 70 lines). The
contract with SessionHostServer is three hooks and one flag:
| Member | Role |
|---|---|
ownsTransport | Return true. start() and stop() now call the hooks, and a connection handed over before start() is refused. |
onStart() | Bind. Runs before the started event, so startedMessage can report the address. A thrown Exception becomes an error event, and start() returns false. |
onStarted() | Listen. Runs after the host is isRunning, so a connection accepted synchronously finds it up. |
onStop() | Close the listener. Runs after every session has been closed. |
The hooks throw UnimplementedError when ownsTransport is true and they are
not overridden, so a forgotten mixin fails at start() instead of serving
nothing. onDispose() stays a no-op, and is the place to release anything else
the host holds.
Each accepted connection becomes a TransportConnection; for a dart:io
WebSocket that is IoWebSocketConnection. The whole of IoWebSocketHost has
this shape:
mixin MyTransportHost<S extends ClientSession> on SessionHostServer<S> {
MyListener? _listener;
bool get ownsTransport => true;
Future<void> onStart() async {
_listener = await MyListener.bind();
}
Future<void> onStarted() async {
_listener!.connections.listen(
(socket) => acceptConnection(MyConnection(socket)),
);
}
Future<void> onStop() async {
await _listener?.close();
_listener = null;
}
}
class MyDocumentServer extends DocumentSessionHost
with MyTransportHost<DocumentClientSession> {
MyDocumentServer({required super.serverRegistry});
String get debugLabel => 'MyDocumentServer';
}
debugLabel names the host in diagnostics. startedMessage,
stoppedMessage and startFailureMessage are the other strings you can
override.