WebSocketTool Plugin for FastPluggy
The WebSocketTool plugin provides real-time WebSocket communication capabilities for FastPluggy applications. It enables bidirectional communication between the server and clients, supports message broadcasting, targeted messaging, and integrates with the task worker system for real-time task monitoring.
Table of Contents
Installation
Requirements
- FastPluggy framework >=0.0.3
- UI Tools plugin >=0.0.3
Quick Start & Installation
Configuration
The WebSocketTool plugin can be configured through the WebSocketSettings class.
Settings can be set via environment variables with the FP_WST_ prefix (e.g. FP_WST_MAX_QUEUE_SIZE=20000).
| Setting | Env var | Type | Default | Description |
|---|---|---|---|---|
max_queue_size |
FP_WST_MAX_QUEUE_SIZE |
int | 10000 | Maximum size of the message queue |
consumer_pool_size |
FP_WST_CONSUMER_POOL_SIZE |
int | 4 | Max concurrent per-client consumer tasks |
enable_heartbeat |
FP_WST_ENABLE_HEARTBEAT |
bool | True | Enable heartbeat mechanism |
heartbeat_interval |
FP_WST_HEARTBEAT_INTERVAL |
int | 30 | Seconds between heartbeat pings |
heartbeat_timeout |
FP_WST_HEARTBEAT_TIMEOUT |
int | 60 | Seconds before connection timeout |
max_client_errors |
FP_WST_MAX_CLIENT_ERRORS |
int | 10 | Disconnect after N consecutive errors |
task_restart_interval |
FP_WST_TASK_RESTART_INTERVAL |
int | 5 | Seconds between background task health checks |
rate_limit_messages_per_window |
FP_WST_RATE_LIMIT_MESSAGES_PER_WINDOW |
int | 60 | Max messages per client per window |
rate_limit_message_window |
FP_WST_RATE_LIMIT_MESSAGE_WINDOW |
int | 60 | Message rate window (seconds) |
rate_limit_connections_per_window |
FP_WST_RATE_LIMIT_CONNECTIONS_PER_WINDOW |
int | 10 | Max connections per IP per window |
rate_limit_connection_window |
FP_WST_RATE_LIMIT_CONNECTION_WINDOW |
int | 60 | Connection rate window (seconds) |
rate_limit_burst_multiplier |
FP_WST_RATE_LIMIT_BURST_MULTIPLIER |
float | 2.0 | Allow short bursts up to N× the base rate |
rate_limit_disconnect_after |
FP_WST_RATE_LIMIT_DISCONNECT_AFTER |
int | 3 | Consecutive rate limit violations before disconnect |
Rate Limiting
The plugin enforces two independent rate limits using in-memory sliding windows:
- Per-connection message rate — limits how fast a single connection can send messages (default: 60 msgs / 60s, with 2× burst allowance)
- Per-IP connection rate — limits how fast one IP can open new connections (default: 10 / 60s)
Behavior:
1. When a client exceeds the message rate, it receives a system.rate_limited response with retry_after indicating when to resume
2. system.* messages (ping, pong, heartbeat) are exempt from rate limiting
3. After rate_limit_disconnect_after consecutive violations, the client is disconnected
4. Successful message processing resets the violation counter
Admin visibility: The WS Statistics dashboard shows rate-limited message/connection/disconnect totals, top rate-limited clients, and top rate-limited IPs. Per-client rate limit remaining is visible in the WS Clients dashboard. Health endpoints report warning when messages are being rate-limited and critical when disconnects occur.
Config endpoint: GET /info/config exposes the active rate limiting configuration.
Documentation
The WebSocketTool plugin has comprehensive documentation available in the docs directory:
- Quick Start Guide - Basic examples to help you get started
- Core Components - Details about ConnectionManager, WebSocketMessage, and AsyncWidget
- WebSocket Handlers - Information about the handler registry system and event hooks
- WebSocket Message Types - Message types and naming conventions
- API Reference - WebSocket and REST API endpoints
- Widgets - Available widgets including AsyncWidget and WebSocketDetailsWidget
- Tasks Worker Integration - Integration with the Tasks Worker module
- Advanced Usage - Advanced usage, health monitoring, and troubleshooting
Metrics
The plugin declares the metrics capability and exposes WebSocket stats via the MetricsProvider protocol. When the metrics plugin is installed, these are automatically collected and available at /plugin/metrics/api/prometheus.
Counters
| Metric | Description |
|---|---|
connections_total |
Total WebSocket connections |
disconnections_total |
Total disconnections |
messages_sent_total |
Total messages sent |
messages_failed_total |
Total message send failures |
queue_overflows_total |
Queue overflow events |
heartbeat_timeouts_total |
Heartbeat timeout disconnects |
Gauges
| Metric | Description |
|---|---|
active_connections |
Current active connections |
active_named_connections |
Active named client connections |
active_anonymous_connections |
Active anonymous connections |
queue_size |
Current message queue size |
queue_utilization |
Queue utilization (0.0–1.0) |
handlers_registered |
Registered message handlers |
received_per_sec |
Messages received/sec (60s window) |
sent_per_sec |
Messages sent/sec (60s window) |
failed_per_sec |
Messages failed/sec (60s window) |
Metric names are bare — the aggregator prefixes with
fp_websocket_tool_in Prometheus output.
Grafana Dashboard
A ready-to-import dashboard is available at grafana/websocket-tool.json.
Quick Start
For a quick introduction to using the WebSocketTool plugin, including client-side connection examples and basic server-side usage, see the Quick Start Guide.
License
This plugin is licensed under the same license as the FastPluggy framework.