Skip to main content

A relay in a Dart Frog backend

Add a relay to a Dart Frog backend you already have: a host, a middleware and one route.

A relay in a Dart Frog backendSource ↗

A Dart Frog route that serves a relay: any document id is a room, with no setup. The rooms live in memory.

import 'package:crdt_socket_sync/relay_server.dart';

/// The relay host for this process.
///
/// Constructed at the top level, so `_middleware.dart` finds it when Dart Frog
/// builds the handler tree; started by `init()` in `main.dart`. One instance
/// per process, shared by every request: a host per request would give each
/// client its own empty room.
///
/// The host has no socket of its own — Dart Frog upgrades the requests and
/// hands them over. The store is in-memory, so a restart loses every room;
/// there is no durable `RelayStore` in this repository yet, so a real backend
/// implements one over its database and closes it after `dispose()`.
final relayHost = RelaySessionHost(store: InMemoryRelayStore());

/// Sends every server event to [log], so the console shows what the protocol
/// is doing. A real backend would use its logger.
void logRelayEvents(void Function(String line) log) {
relayHost.serverEvents.listen(
(e) => log('[relay] ${e.type.name}: ${e.message}'),
);
}

Key points

  • Build the host once, outside the routes, and share it with every request: a host per request gives each client an empty room.
  • The middleware puts the host in the request context; the route upgrades the request and hands it to the host.
  • Start the host before serving, and dispose it on shutdown.
  • Clients connect with WebSocketRelayClient to the route's URL.