Cluster PubSub

Overview

There are situations where one to send messages to all actors in the cluster that have registered interest in a named topic. Cluster pubsub provides a way to implement publish-subscribe communication between actors distributed across multiple nodes.

By encapsulating topic management and message routing, it simplifies the development of reactive and scalable distributed systems in Go. Its design ensures that messages are efficiently delivered to subscribers across the cluster, making it an essential building block for any distributed actor-based application.

Cluster PubSub is activated with the option WithPubsub during the creation of the actor system.

Cluster PubSub requires cluster mode to be activated first.

Design

Topic Registry

Cluster PubSub maintain a Topic registry that is managed by a dedicated system actor TopicActor

A single instance of TopicActor when cluster pubsub is enabled is created on all nodes. You register actors to the local TopicActor by a Subscribe message using Tell. To unsubscribe actors need to send Unsubscribe message using Tell.

Successful Subscribe and Unsubscribe is acknowledged with SubscribeAck and UnsubscribeAck replies from the local TopicActor .

Once cluster pubsub is enabled one can access the local instance of TopicActor from the ActorSystem.

Code Snippet

// create an actor on the actor system of the node1 in the cluster
actor1, err := node1.Spawn(ctx, "actor1", Subscriber())

topic := "test-topic"
// subscribe to the topic
err = actor1.Tell(ctx, node1.TopicActor(), &goaktpb.Subscribe{Topic: topic})

Publish

To publish a message to a given topic, local actors send a Publish using Tell message to the local TopicActor. The local TopicActor will route the message to all the local subscribers as well as to all the subscribers to the named topic in the cluster.

This is the true pub/sub mode. A typical usage of this mode is a chat room in an instant messaging application.

Code Snippet

// create an publisher actor
publisher, err := node1.Spawn(ctx, "publisher", Publisher())

// create the publish message
message := &goaktpb.Publish{
	Id:      "messsage1",
	Topic:   topic,
	Message: transformed,
}

// publish the message
err = publisher.Tell(ctx, node1.TopicActor(), message)