Public, Private & Presence Channels

Channels are the core of the Pub/Sub system. They allow one-to-many and many-to-many real-time communication between WebSocket clients.

---

Channel Types

The channel_type enum determines who can subscribe to a channel.

enum class channel_type : uint8_t {
    public_channel,      // Any client can subscribe (no JWT required)
    private_channel,     // Requires JWT with a grant for this channel
    presence_channel     // Like private, plus shows connected members
};

Type	Naming Convention	JWT Required	Members Visible
Public	Any name	No	No
Private	private-*	Yes (read grant)	No
Presence	presence-*	Yes (read grant)	Yes

---

The Channel Object

Channels are managed by clients::registry. Each channel tracks its name, type, and usage metrics.

auto& clients = app.get_state()->of_clients();

// Get or create a channel
auto channel = clients.get_or_create_channel("room-general");

// channel->get_id()       — UUID of the channel
// channel->get_name()     — "room-general"
// channel->get_type()     — public|private|presence

Channel Metrics

Each channel automatically tracks publish, subscribe, and unsubscribe counts:

channel->get_publish_count();      // Total publishes to this channel
channel->get_subscribe_count();    // Total subscribes
channel->get_unsubscribe_count();  // Total unsubscribes

---

Channel API

Listing and Finding Channels

// List all channels
auto channels = clients.get_channels();
for (auto& ch : channels) {
    fmt::println("{}: {} ({})", ch->get_name(), ch->get_type(), ch->get_id());
}

// Find a channel by name
auto ch = clients.get_channel_by_name("room-general");

// Find a channel by ID
auto ch = clients.get_channel_by_id(some_uuid);

Channel Connections

// Get all WebSocket connections subscribed to a channel
auto connections = clients.get_websocket_connections_by_node_id_and_channel(
    node_id, "room-general");

// List all active WebSocket connections
auto all_ws = clients.get_websocket_connections();

Removing Empty Channels

// Remove a channel if it has no subscribers
clients.try_remove_channel(channel_id);

Getting Channel Members

For presence channels, get the list of connected member session IDs:

auto members = clients.get_channel_members(channel_id);

---

Broadcasting to a Channel

Send a message to all subscribers of a channel:

clients.broadcast_to_channel(
    node_id,           // Local node ID
    "room-general",    // Channel name
    frame,             // shared_buffer with the message
    std::nullopt,      // exclude_id (optional)
    false,             // local_only — if true, don't propagate to other nodes
    instance_ptr       // state instance for cross-node propagation
);

---

The Subscription Flow

1. Client sends an Opcode_ClientSubscribe message via WebSocket with the channel name.
2. The built-in handlers::subscribe handler processes the message.
3. The framework checks authorization: private/presence channels require a JWT grant.
4. clients::registry::add_subscription() registers the subscription.
5. When a message is published, clients::broadcast_to_channel() delivers it to all subscribers.
6. On disconnect, remove_subscriptions_by_session_id() cleans up automatically.