Appearance
Watchers (Real-Time Monitoring)
The watchers system allows clients to subscribe to real-time events about nodes, clients, channels, cache, and queues via WebSocket.
Watching Resources
Clients watch resources via the Opcode_Watch opcode. Supported watchable types:
- Nodes — track node join/leave/status changes
- Clients — track client connect/disconnect
- Channels — track subscribe/unsubscribe events
- Cache — track key create/update/delete
- Metrics — track metric reports
- Queues — track job events (dispatch, complete, fail)
Watcher Registry API
cpp
auto& watchers = app.get_state()->of_watchers();
// Check if any watchers exist
bool any = watchers.has_watchers();The watchable_t type
watchable_t is a std::variant that identifies which resource is being watched. It has six concrete types, one per watchable resource:
| Type | Purpose |
|---|---|
watchable_node_t | A mesh node |
watchable_client_t | A client connection |
watchable_channel_t | A Pub/Sub channel |
watchable_cache_t | A cache key |
watchable_metrics_t | A metric report |
watchable_queue_t | A job queue |
Each concrete type holds the resource identifier (e.g., channel name, client UUID, cache key). The framework uses static factory methods on watched_t to construct them.
The watched_t type combines a watchable_t with a session ID — it represents "session X is watching resource Y":
cpp
// Check for watchers of a specific resource
bool watching_node = watchers.has_node_watchers();
bool watching_channel = watchers.has_channel_watchers("room-general");
bool watching_client = watchers.has_client_watchers(client_id);
bool watching_cache = watchers.has_cache_watchers("user:42:profile");
bool watching_queue = watchers.has_queue_watchers("emails");
// Get all watchers
auto all = watchers.get_watchers();
// Get receivers for a specific watchable
auto receivers = watchers.get_receivers(watchable, exclude_id);Adding and Removing Watchers
cpp
// Add a watcher (typically done via Opcode_Watch handler)
watchers.add_watcher(watched);
// Remove a watcher (via Opcode_Unwatch)
watchers.remove_watcher(watched);
// Remove all watchers for a disconnected session
watchers.remove_watchers_by_session_id(session_id);Watcher Events
When a watched event occurs, the framework dispatches events to all matching watchers:
cpp
// Broadcasting an event notifies all watchers
state->broadcast_event(type, watchable, session_id, payload);Next: Quotas & Backpressure.