# WebSocket Module
WebSocket streaming implementation for real-time bidirectional communication with
the Gemini API.
## Overview
This module provides WebSocket-based streaming for real-time content generation,
offering lower latency and bidirectional communication compared to HTTP streaming.
**Feature Gate**: This module is only available when the `websocket_streaming`
feature is enabled.
## Module Structure
```
websocket/
├── mod.rs - Module exports and public interface
├── connection.rs - WebSocket connection management and lifecycle
├── streaming.rs - Streaming operations (send/receive)
└── protocol.rs - WebSocket protocol handling and message framing
```
## Key Components
### Connection Management (connection.rs)
- WebSocket connection establishment
- Connection pooling
- Reconnection logic
- Connection health monitoring
### Streaming Operations (streaming.rs)
- Bidirectional message streaming
- Chunk buffering
- Stream control (pause, resume, cancel)
- Error handling and recovery
### Protocol Handling (protocol.rs)
- Message framing (text/binary)
- Protocol negotiation
- Keepalive ping/pong
- Close handshake
## Usage Example
```rust
use api_gemini::Client;
#[tokio::main]
async fn main() -> Result< (), Box< dyn std::error::Error > >
{
let client = Client::new()?;
// Create WebSocket stream for content generation
let mut stream = client
.models()
.by_name( "gemini-2.5-flash" )
.stream_generate_content_websocket( &request )
.await?;
// Receive chunks in real-time
while let Some( chunk ) = stream.next().await
{
let response = chunk?;
println!( "Received: {:?}", response );
}
Ok( () )
}
```
## Advantages Over HTTP Streaming
### Lower Latency
- Direct TCP connection (no HTTP overhead)
- Immediate chunk delivery
- Reduced time to first token
### Bidirectional Communication
- Send additional context during generation
- Update generation parameters in real-time
- Interactive conversations with immediate feedback
### Connection Efficiency
- Single persistent connection
- Connection pooling and reuse
- Reduced connection overhead for multiple requests
## Stream Control
WebSocket streams support advanced control operations:
```rust
// Pause stream
stream.pause().await?;
// Resume stream
stream.resume().await?;
// Cancel stream
stream.cancel().await?;
```
## Error Handling
WebSocket errors are reported through the `Error::WebSocketError` variant:
```rust
pub enum Error
{
WebSocketError( String ),
// ... other variants
}
```
Common error scenarios:
- Connection failures
- Protocol violations
- Message parsing errors
- Unexpected disconnections
## Performance Characteristics
- **Connection establishment**: ~100-300ms
- **Time to first token**: ~50-200ms (50% faster than HTTP)
- **Chunk delivery latency**: <10ms
- **Memory overhead**: Minimal (streaming chunks, not buffering)
## Design Principles
### Transparent Failures
All connection and protocol errors are exposed explicitly. No silent reconnections
or hidden retries.
### Process-Stateless
WebSocket connections are **runtime state** only. Connections die with the process.
No persistent connection state across restarts.
### Feature-Gated
WebSocket functionality has **zero overhead** when the `websocket_streaming` feature
is disabled (compile-time elimination).
## See Also
- HTTP streaming: `../models/api/content_generation.rs`
- Stream control: `../models/streaming_control/`
- Client implementation: `../client/`
- Protocol specs: See Gemini API documentation