Broadcasting Events

Events are the mechanism for distributing messages to subscribers, watchers, and connected nodes. The framework provides three event distribution methods, each with a different scope.

---

Event Distribution Methods

The framework provides three event distribution methods with different scopes.

distribute_event(frame, exclude_id) — Fan-out to all nodes

Distributes an event to all nodes in the mesh AND all local subscribers. Use this for messages that need to reach every node, such as cache invalidation or global announcements. Every subscriber across the entire cluster receives it.

auto state = app.get_state();
state->distribute_event(event_frame, exclude_id);

Parameter	Type	Description
event_frame	shared_buffer	FlatBuffers-encoded message frame.
exclude_id	optional<uuid>	Optional node ID to exclude from distribution.

broadcast_event(type, watchable, session_id, payload, exclude_id) — Local sessions only

Sends an event to every connected WebSocket session on this node only. Does NOT propagate to other nodes. Use for local system-wide announcements.

state->broadcast_event(
    protocol::fbs::EventType::ChannelEvent,
    watchable,
    session_id,
    payload,
    exclude_id
);

notify_event(type, watchable, session_id, payload, exclude_id) — Watched sessions only

Sends an event only to sessions that are watching a specific resource. Use for the watcher system. Does NOT propagate to other nodes unless the watchers system is configured to forward them.

state->notify_event(
    protocol::fbs::EventType::NodeEvent,     // Event type
    watchable,                                // The resource being watched
    session_id,                               // Originating session
    payload,                                  // Event payload
    exclude_id                                // Session to exclude
);

Parameter	Type	Description
type	protocol::fbs::EventType	Type of event (NodeEvent, ClientEvent, ChannelEvent, CacheEvent, etc.).
watchable	clients::websocket::watchable_t	The resource that was changed.
session_id	optional<uuid>	Session that triggered the event.
payload	shared_buffer	Optional event payload.

---

Broadcasting to a Channel

When a client publishes via the Opcode_Publish opcode:

1. The built-in handlers::publish processes the message.
2. The client's permission to publish to the channel is validated.
3. clients::registry::broadcast_to_channel() delivers the message to all subscribers.

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

clients.broadcast_to_channel(
    node_id,           // Local node ID
    "room-general",    // Channel name
    frame,             // Message frame
    std::nullopt,      // Exclude this session
    false,             // local_only: if true, don't propagate to other nodes
    instance_ptr       // State instance for cross-node routing
);

---

Cross-Node Propagation

When mesh networking is enabled:

• distribute_event() automatically propagates to all connected nodes.
• Each receiving node delivers the event to its local subscribers.
• broadcast_to_channel() with local_only = false sends to subscribers on all nodes.