Skip to main content
Version: 2.3.0

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:

MethodDescription
postMessageSend a message to a channel.
addListenerAdd a listener to a channel.
removeListenerRemove a listener from a channel.
createStreamCreate a stream that listens to a channel.
revokeAuthenticationRevoke 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.