serverpod_live_server

Serverpod Live adds reliable collaboration semantics above Serverpod streaming: durable typed channels, idempotent commands, snapshot-backed collections, and ephemeral presence.

Install

Add the module to the Serverpod server package that owns your application:

dependencies:
  serverpod_live_server: ^0.1.0

Run dart pub get, add this module's migrations to your normal Serverpod migration workflow, and expose the generated endpoint from the consuming Serverpod application.

Configure

Create one LiveServer during server startup. Authorization is mandatory and should make the application's membership decision for each channel.

final live = LiveServer.initialize(
  pod,
  authorize: (session, channel) async {
    return channel.startsWith('team:');
  },
);

Use live.publish from trusted server code. It persists the durable event and your application mutation in one transaction, then fans out only after commit. When publishing in a command handler, return the event through LiveCommandResult.events so that fan-out also waits for the receipt transaction to commit.

Example

See example/main.dart for the minimal startup wiring. Replace the channel check with your own membership lookup; channel names are dynamic and do not need to be declared when the server starts.

Delivery contract

Durable events are delivered at least once and ordered within a channel. The client resumes from its last contiguous cursor and suppresses repeats. If an old cursor falls outside retention, the client receives resyncRequired and must load a fresh application snapshot.

LiveDeliveryMode.local is the default for one Serverpod process. LiveDeliveryMode.redis uses Serverpod MessageCentral to fan out committed events and presence updates between processes that share PostgreSQL and Redis. Redis delivery is asynchronous and best effort; PostgreSQL replay repairs missed messages after reconnecting. Use await live.fanOut(...) only when the host explicitly needs broker-delivery confirmation.

Set onFanoutError to report final Redis delivery failures. Without it, Serverpod Live writes the first failure for a topic to stderr without throwing into the host zone. For an end-to-end example, see the repository README.