Multi-node Clustering

Overview

Put two or more WebSocket servers behind a load balancer and a message published on one node still reaches subscribers connected to the others. TsgcWSCluster adds a pub-sub backplane between your nodes, so channels, broadcasts and Presence work cluster-wide. Drop the component next to your server, point the nodes at each other, and your existing Publish, channel and Presence code stays unchanged.

At a glance

Features

• Two backplane engines. Published property EngineType: clusterMesh (no external infrastructure) or clusterRedis (Redis Pub/Sub).
• Mesh, zero-infrastructure. Each node listens on ClusterPort and connects directly to the peers listed in Peers — nothing extra to install.
• Redis Pub/Sub. Properties RedisHost, RedisPort and RedisChannel route messages through Redis for larger deployments.
• Attach / Detach. Cluster the sgc protocol and the Presence protocol with one call each; Start and Stop control the backplane.
• Cluster-wide Presence. The member roster becomes the union across all nodes; a node that drops has its members purged, so there are no ghost members.
• Readiness signals. Property Ready, ConnectedPeerCount and events OnPeerConnected, OnPeerDisconnected and OnClusterMessage let you observe cluster health.
• Loop prevention. Every message carries an origin node id so it is never echoed back to the node that produced it.
• Drop-in. Your existing Publish and channel/subscription code is unchanged — clustering is transparent to the protocol layer.

Technical specification

Main properties

The principal published / public properties used to configure and drive the component. Consult the online help for the full list.

Main methods

The principal public methods exposed by the component.

Public events

The component exposes the following published events; consult the online help for full event-handler signatures.

Quick Start

Drop the component next to your TsgcWebSocketServer and the sgc protocol, point the nodes at each other and start it. A client on one node can Publish to a channel and clients on the other nodes receive it, with no sticky sessions.

Delphi (VCL / FireMonkey)

uses
  sgcWebSocket, sgcWebSocket_Protocols, sgcWebSocket_Cluster;
var
  Server: TsgcWebSocketServer;
  Protocol: TsgcWSPServer_sgc;
  Cluster: TsgcWSCluster;
begin
  Server := TsgcWebSocketServer.Create(nil);
  Server.Port := 8080;

  Protocol := TsgcWSPServer_sgc.Create(nil);
  Protocol.Server := Server;

  Cluster := TsgcWSCluster.Create(nil);
  Cluster.EngineType  := clusterMesh;                // zero-infrastructure backplane
  Cluster.ClusterPort := 5410;                       // this node's mesh listener
  Cluster.Peers.Add('192.168.1.101:5410');          // the other nodes
  Cluster.Peers.Add('192.168.1.102:5410');
  Cluster.Attach(Protocol);                          // cluster this protocol's pub/sub
  Cluster.Start;

  Server.Active := True;
end;

C++ Builder

#include "sgcWebSocket.hpp"
#include "sgcWebSocket_Protocols.hpp"
#include "sgcWebSocket_Cluster.hpp"

TsgcWebSocketServer *Server = new TsgcWebSocketServer(NULL);
Server->Port = 8080;

TsgcWSPServer_sgc *Protocol = new TsgcWSPServer_sgc(NULL);
Protocol->Server = Server;

TsgcWSCluster *Cluster = new TsgcWSCluster(NULL);
Cluster->EngineType  = clusterMesh;                // zero-infrastructure backplane
Cluster->ClusterPort = 5410;                       // this node's mesh listener
Cluster->Peers->Add("192.168.1.101:5410");          // the other nodes
Cluster->Peers->Add("192.168.1.102:5410");
Cluster->Attach(Protocol);                          // cluster this protocol's pub/sub
Cluster->Start();

Server->Active = true;

.NET (C#)

var server = new TsgcWSServer { Port = 8080 };
var protocol = new TsgcWSPServer_sgc { Server = server };

var cluster = new TsgcWSCluster {
    EngineType  = ClusterEngineType.Mesh,   // zero-infrastructure backplane
    ClusterPort = 5414,
    Protocol    = protocol
};
cluster.Peers.Add("192.168.1.101:5414");
cluster.Peers.Add("192.168.1.102:5414");
cluster.Start();

server.Active = true;

Common scenarios

The following scenarios show the configuration and method calls needed to drive the component through a specific real-world flow.

1 · Redis Pub/Sub backplane

For larger deployments, switch the engine from mesh to Redis. Every node publishes to and subscribes from the same Redis channel, so you do not need to maintain a peer list.

  Cluster := TsgcWSCluster.Create(nil);
  Cluster.EngineType   := clusterRedis;             // Redis Pub/Sub backplane
  Cluster.RedisHost    := '127.0.0.1';
  Cluster.RedisPort    := 6379;
  Cluster.RedisChannel := 'sgc-cluster';
  Cluster.Attach(Protocol);
  Cluster.Start;

Cluster = new TsgcWSCluster(NULL);
Cluster->EngineType   = clusterRedis;             // Redis Pub/Sub backplane
Cluster->RedisHost    = "127.0.0.1";
Cluster->RedisPort    = 6379;
Cluster->RedisChannel = "sgc-cluster";
Cluster->Attach(Protocol);
Cluster->Start();

var cluster = new TsgcWSCluster {
    EngineType   = ClusterEngineType.Redis,      // Redis Pub/Sub backplane
    RedisHost    = "127.0.0.1",
    RedisPort    = 6379,
    RedisChannel = "sgc-cluster",
    Protocol     = protocol
};
cluster.Start();

2 · Cluster-wide Presence

Attach the Presence protocol to the cluster as well. The member roster becomes the union across all nodes, and when a node drops its members are purged so there are no ghost members.

  Cluster.Attach(Protocol);          // the sgc protocol
  Cluster.Attach(Presence);          // the Presence protocol
  Cluster.Start;
  // Presence.Members now reflects every node in the cluster

Cluster->Attach(Protocol);          // the sgc protocol
Cluster->Attach(Presence);          // the Presence protocol
Cluster->Start();
// Presence->Members now reflects every node in the cluster

cluster.Attach(protocol);          // the sgc protocol
cluster.Attach(presence);          // the Presence protocol
cluster.Start();
// presence.Members now reflects every node in the cluster

3 · Readiness signals

Watch the backplane come up and observe peer connections through the readiness property and events.

procedure OnPeerConnected(Sender: TObject; const aPeer: string);
begin
  // a peer node joined the cluster
  ShowStatus('Peers: ' + IntToStr(Cluster.ConnectedPeerCount));
end;

if Cluster.Ready then
  // the backplane is up and relaying messages;

void __fastcall OnPeerConnected(TObject *Sender, const String aPeer)
{
  // a peer node joined the cluster
  ShowStatus("Peers: " + IntToStr(Cluster->ConnectedPeerCount));
}

if (Cluster->Ready)
{
  // the backplane is up and relaying messages
}

cluster.OnPeerConnected += (sender, peer) =>
{
    // a peer node joined the cluster
    ShowStatus($"Peers: {cluster.ConnectedPeerCount}");
};

if (cluster.Ready)
{
    // the backplane is up and relaying messages
}

Sources used to build this document

Every external claim links back to a primary source. The online-help references decode the canonical deep-link the company maintains for this component.