WebSocket Gateway

The WebSocket Gateway is the core component that maintains a persistent connection to QQ Guild's real-time event system. It handles authentication, heartbeat management, automatic reconnection, and event dispatching, providing the foundation for your bot's real-time functionality.

Overview

The Gateway manages a WebSocket connection that receives events from QQ's servers in real-time. Unlike REST API calls which are request-response based, the Gateway provides a continuous stream of events such as new messages, member joins, guild updates, and more.

use botrs::{Client, Gateway, Token, Intents};

// Gateway is automatically managed by the Client
let mut client = Client::new("your_app_id", handler)
    .intents(Intents::GUILD_MESSAGES | Intents::GUILDS)
    .build()
    .await?;

// Gateway connection is established when starting the client
client.start().await?;

Gateway Architecture

Connection Lifecycle

The Gateway follows a specific connection lifecycle:

1. Initial Connection: Establishes WebSocket connection to the gateway URL
2. Authentication: Sends IDENTIFY or RESUME payload based on session state
3. Ready State: Receives READY event and begins heartbeat mechanism
4. Event Processing: Continuously receives and processes events
5. Reconnection: Automatically handles disconnections and reconnects

Event Flow

// Events flow from Gateway -> Client -> EventHandler
impl EventHandler for MyBot {
    async fn message_create(&self, ctx: Context, msg: Message) {
        // This event came through the Gateway
        println!("Received message: {}", msg.content.unwrap_or_default());
    }
    
    async fn ready(&self, ctx: Context, ready: Ready) {
        // Gateway is ready and authenticated
        println!("Bot {} is ready with {} guilds", 
                ready.user.username, ready.guilds.len());
    }
}

Heartbeat System

The Gateway implements a robust heartbeat mechanism to maintain connection health:

Automatic Heartbeats

// Heartbeats are sent automatically every 30 seconds
// This is handled internally by the Gateway

The heartbeat system:

• Sends heartbeat packets every 30 seconds (fixed interval)
• Tracks heartbeat acknowledgments from the server
• Monitors connection health and detects timeouts
• Automatically terminates unhealthy connections

Heartbeat Monitoring

// Internal heartbeat tracking (read-only access)
impl Gateway {
    pub fn is_ready(&self) -> bool {
        // Returns true if connection is authenticated and ready
    }
    
    pub fn last_sequence(&self) -> u64 {
        // Returns the last sequence number received
    }
    
    pub fn session_id(&self) -> Option<&str> {
        // Returns the current session ID if available
    }
}

Connection Management

Automatic Reconnection

The Gateway handles disconnections gracefully with exponential backoff:

// Reconnection is automatic with intelligent backoff
// - Initial attempts: 5 second delay
// - Subsequent attempts: exponential backoff (5, 10, 20, 40 seconds max)
// - Maximum attempts: unlimited until explicitly stopped

Session Recovery

The Gateway maintains session state for seamless reconnection:

// Session state is automatically preserved
// - Session ID for session resumption
// - Last sequence number for event continuity
// - Connection state for proper recovery

Connection States

use botrs::Gateway;

// Check connection status
if gateway.is_ready() {
    println!("Gateway is connected and ready");
}

if gateway.can_reconnect() {
    println!("Gateway can attempt reconnection");
}

// Access session information
if let Some(session_id) = gateway.session_id() {
    println!("Current session: {}", session_id);
}

let last_seq = gateway.last_sequence();
println!("Last sequence number: {}", last_seq);

Event Handling

System Events

The Gateway handles several system-level events automatically:

HELLO Event

• Receives server heartbeat interval
• Triggers authentication process
• Initializes heartbeat mechanism

READY Event

• Confirms successful authentication
• Provides bot information and guild list
• Starts regular heartbeat transmission

HEARTBEAT_ACK Event

• Acknowledges heartbeat packets
• Used for connection health monitoring
• Tracks round-trip latency

RECONNECT Event

• Server requests reconnection
• Triggers graceful connection reset
• Preserves session state

INVALID_SESSION Event

• Indicates session has expired
• Forces full re-authentication
• Clears session state

Dispatch Events

All other events are dispatched to your EventHandler:

impl EventHandler for MyBot {
    async fn message_create(&self, ctx: Context, msg: Message) {
        // Regular message events
    }
    
    async fn guild_member_add(&self, ctx: Context, member: Member) {
        // Member join events
    }
    
    async fn guild_create(&self, ctx: Context, guild: Guild) {
        // Guild events
    }
    
    // Handle unknown events
    async fn unknown_event(&self, event_type: String, data: serde_json::Value) {
        println!("Unknown event: {}", event_type);
    }
}

Advanced Gateway Usage

Direct Gateway Access

While the Client manages the Gateway automatically, you can access it for advanced use cases:

use botrs::{Gateway, Token, Intents};
use tokio::sync::mpsc;

// Create gateway manually
let token = Token::new("app_id", "secret");
let intents = Intents::GUILD_MESSAGES | Intents::GUILDS;
let mut gateway = Gateway::new(
    "wss://api.sgroup.qq.com/websocket",
    token,
    intents,
    None, // No sharding
);

// Set up event channel
let (event_sender, mut event_receiver) = mpsc::unbounded_channel();

// Connect and handle events manually
tokio::spawn(async move {
    if let Err(e) = gateway.connect(event_sender).await {
        eprintln!("Gateway error: {}", e);
    }
});

// Process events manually
while let Some(event) = event_receiver.recv().await {
    println!("Received event: {:?}", event.event_type);
}

Gateway Configuration

use botrs::{Gateway, Token, Intents};

// Basic gateway setup
let gateway = Gateway::new(
    "wss://api.sgroup.qq.com/websocket", // Gateway URL
    Token::new("app_id", "secret"),      // Authentication
    Intents::non_privileged(),           // Event subscriptions
    None,                                // Sharding info
);

// With sharding (for large bots)
let shard_info = [0, 4]; // Shard 0 of 4 total shards
let gateway = Gateway::new(
    gateway_url,
    token,
    intents,
    Some(shard_info),
);

Error Handling

Connection Errors

The Gateway handles various connection scenarios:

// Connection errors are logged and trigger reconnection
// - Network timeouts
// - WebSocket protocol errors
// - Server-side disconnections
// - Authentication failures

Error Recovery

impl EventHandler for MyBot {
    async fn error(&self, error: BotError) {
        match error {
            BotError::WebSocket(_) => {
                // WebSocket connection issues
                // Gateway will automatically reconnect
                eprintln!("WebSocket error, reconnecting...");
            }
            BotError::Gateway(msg) => {
                // Gateway-specific errors
                eprintln!("Gateway error: {}", msg);
            }
            BotError::AuthenticationFailed(_) => {
                // Authentication problems
                // May require token refresh
                eprintln!("Authentication failed");
            }
            _ => {
                eprintln!("Other error: {}", error);
            }
        }
    }
}

Close Code Handling

The Gateway responds appropriately to different close codes:

// Close code handling (internal)
// - 4004: Authentication failed - reset session
// - 9001, 9005: Invalid session - create new connection
// - Others: Attempt reconnection with session resume

Performance Considerations

Memory Usage

The Gateway is designed for efficient memory usage:

• Minimal state tracking (session ID, sequence number, heartbeat status)
• Efficient JSON parsing with serde
• Connection pooling for HTTP requests
• Automatic cleanup of resources

Network Efficiency

• Compression support for WebSocket messages
• Intelligent reconnection with exponential backoff
• Heartbeat optimization (30-second fixed interval)
• Event filtering based on intents

Concurrency

// Gateway operations are async and non-blocking
// - Event processing doesn't block heartbeats
// - Reconnection doesn't block event handling
// - Multiple Gateway instances can run concurrently (sharding)

Monitoring and Debugging

Connection Monitoring

use tracing::{info, debug, warn};

// Gateway provides extensive logging
// Set log level to DEBUG for detailed information
tracing_subscriber::fmt()
    .with_max_level(tracing::Level::DEBUG)
    .init();

// Logs include:
// - Connection attempts and duration
// - Heartbeat timing and acknowledgments
// - Event counts and types
// - Error conditions and recovery

Health Metrics

// Internal metrics tracked by Gateway:
// - Total connection time
// - Heartbeat count and timing
// - Last heartbeat acknowledgment
// - Sequence number tracking
// - Connection state changes

Debugging Tips

1. Enable Debug Logging: Set log level to DEBUG for detailed Gateway activity
2. Monitor Heartbeats: Watch for heartbeat timing issues
3. Check Session State: Verify session ID and sequence numbers
4. Network Connectivity: Ensure stable internet connection
5. Token Validity: Verify authentication credentials

Best Practices

Production Deployment

1. Robust Error Handling: Implement comprehensive error handling in your EventHandler
2. Graceful Shutdown: Use proper signal handling for clean disconnection
3. Health Monitoring: Monitor Gateway health and connection metrics
4. Log Management: Configure appropriate log levels for production

Development Tips

1. Use Sandbox: Test with sandbox environment before production
2. Intent Optimization: Only subscribe to events you actually need
3. Rate Limiting: Be aware of Gateway rate limits and connection frequency
4. Session Management: Understand session lifecycle for debugging

Scaling Considerations

// For large bots (2500+ guilds), implement sharding:
let total_shards = 4;
for shard_id in 0..total_shards {
    let shard_info = [shard_id, total_shards];
    let gateway = Gateway::new(gateway_url, token.clone(), intents, Some(shard_info));
    // Start each shard in separate task
}

The Gateway provides the real-time foundation for your QQ Guild bot, handling all the complexities of WebSocket connection management, authentication, and event delivery. By understanding its capabilities and following best practices, you can build reliable bots that maintain stable connections and process events efficiently.