Server events

Serverpod framework comes with a built-in event messaging system. This enables efficient message exchange within and across servers, making it ideal for scenarios where shared state is needed, such as coordinating streams or managing data across a server cluster.

The event message system is accessed on the Session object through the field messages.

Quick Reference

Here is a quick reference to the key messaging methods:

Method	Description
postMessage	Send a message to a channel.
addListener	Add a listener to a channel.
removeListener	Remove a listener from a channel.
createStream	Create a stream that listens to a channel.
revokeAuthentication	Revoke authentication tokens.

Sending messages

To send a message, you can use the postMessage method. The message is published to the specified channel and needs to be a Serverpod model.

var message = UserUpdate(); // Model that represents changes to user data.
session.messages.postMessage('user_updates', message);

In the example above, the message published on the user_updates channel. Any subscriber to this channel in the server will receive the message.

Global messages

Serverpod uses Redis to pass messages between servers. To send a message to another server, enable Redis and then set the global parameter to true when posting a message.

var message = UserUpdate(); // Model that represents changes to user data.
session.messages.postMessage('user_updates', message, global: true);

In the example above, the message is published to the user_updates channel and will be received by all servers connected to the same Redis instance.

warning

If Redis is not enabled, sending global messages will throw an exception.

Receiving messages

Receiving messages is just as simple as sending them! Serverpod provides two ways to handle incoming messages: by creating a stream that subscribes to a channel or by adding a listener to a channel.

Creating a stream

To create a stream that subscribes to a channel, use the createStream method. The stream will emit a value whenever a message is posted to the channel.

var stream = session.messages.createStream('user_updates');
stream.listen((message) {
    print('Received message: $message');
})

In the above example, a stream is created that listens to the user_updates channel and processes incoming requests.

Stream lifecycle

The stream is automatically closed when the session is closed. If you want to close the stream manually, you simply cancel the stream subscription.

var stream = session.messages.createStream('user_updates');
var subscription = stream.listen((message) {
    print('Received message: $message');
});

subscription.cancel();

In the above example, the stream is first created and then canceled.

Adding a listener

To add a listener to a channel, use the addListener method. The listener will be called whenever a message is posted to the channel.

session.messages.addListener('user_updates', (message) {
  print('Received message: $message');
});

In the above example, the listener will be called whenever a message is posted to the user_updates channel. The listener will be called regardless if a message is published globally by another server or internally by the same server.

Listener lifecycle

The listener is automatically removed when the session is closed. To manually remove a listener, use the removeListener method.

var myListenerCallback = (message) {
  print('Received message: $message');
};
// Register the listener
session.messages.addListener('user_updates', myListenerCallback);

// Remove the listener
session.messages.removeListener('user_updates', myListenerCallback);

In the above example, the listener is first added and then removed from the user_updates channel.

Revoke authentication

The messaging interface also exposes a method for revoking authentication. For more details on handling revoked authentication, refer to the section on handling revoked authentication.