# RVOIP - Comprehensive VoIP Library for Rust
[](https://crates.io/crates/rvoip)
[](https://docs.rs/rvoip)
[](LICENSE)
## Overview
⚠️ **ALPHA RELEASE - NOT READY FOR PRODUCTION** ⚠️
The `rvoip` library is the **unified entry point** for a comprehensive VoIP (Voice over IP) implementation in Rust. It provides a complete VoIP stack with SIP protocol support, real-time media processing, call management, and business logic coordination - all designed with modern Rust principles and async/await architecture.
**This is an alpha release intended for development and testing purposes only. The APIs are unstable and the implementation is not yet production-ready.**
### ✅ **Core Responsibilities**
- **Unified VoIP Stack**: Single crate providing access to all VoIP components
- **Developer Experience**: Simplified imports and consistent API across all layers
- **Production-Ready**: Complete VoIP solution from protocol to application
- **Modular Architecture**: Clean separation of concerns with specialized components
- **Integration Hub**: Seamless coordination between all VoIP layers
### ❌ **Delegated Responsibilities**
- **Individual Component Logic**: Each specialized crate handles its domain
- **Protocol Implementation**: Dedicated to `sip-core`, `dialog-core`, etc.
- **Media Processing**: Specialized in `media-core` and `rtp-core`
- **Business Logic**: Implemented in `call-engine` and applications
The RVOIP crate sits at the top of the VoIP ecosystem, providing unified access to all specialized components:
```
┌─────────────────────────────────────────┐
│ Your VoIP Application │
├─────────────────────────────────────────┤
│ rvoip ⬅️ YOU ARE HERE
│ (Unified Interface) │
├─────────────────────────────────────────┤
│ call-engine │ client-core │ session │
│ │ │ -core │
├─────────────────────────────────────────┤
│ dialog-core │ media-core │ rtp-core│
├─────────────────────────────────────────┤
│ transaction │ sip-core │ sip- │
│ -core │ │transport│
└─────────────────────────────────────────┘
```
### Complete VoIP Stack Components
1. **High-Level Application Layer**
- **[call-engine](../call-engine/)**: Call center operations, agent management, routing
- **[client-core](../client-core/)**: SIP client applications, softphones, user agents
- **[session-core](../session-core/)**: Session coordination, call control, media management
2. **Core Protocol Layer**
- **[dialog-core](../dialog-core/)**: SIP dialog state management, RFC 3261 compliance
- **[transaction-core](../transaction-core/)**: SIP transaction handling, retransmission
- **[sip-core](../sip-core/)**: SIP message parsing, headers, protocol primitives
3. **Media and Transport Layer**
- **[media-core](../media-core/)**: Audio processing, codecs, quality monitoring
- **[rtp-core](../rtp-core/)**: RTP/RTCP implementation, media transport
- **[sip-transport](../sip-transport/)**: SIP transport (UDP, TCP, TLS)
4. **Infrastructure Layer**
- **[infra-common](../infra-common/)**: Common utilities, logging, configuration
### Integration Architecture
Complete end-to-end VoIP application architecture:
```
┌─────────────────┐ Unified API ┌─────────────────┐
│ │ ──────────────────────► │ │
│ VoIP App │ │ rvoip │
│(Business Logic) │ ◄──────────────────────── │ (Unified Stack) │
│ │ Event Handling │ │
└─────────────────┘ └─────────────────┘
│
Component Coordination │ Module Access
▼ ▼
┌─────────────────────────────────────────────────┐
│ call-engine | client-core | session-core │
│ dialog-core | media-core | rtp-core │
│ transaction | sip-core | sip-transport │
└─────────────────────────────────────────────────┘
```
### Integration Flow
1. **Application → rvoip**: Single import for complete VoIP functionality
2. **rvoip → Components**: Coordinate between specialized crates
3. **Components → Protocol**: Handle SIP, RTP, media processing
4. **rvoip ↔ Developer**: Provide unified, consistent developer experience
## Features
### ✅ Completed Features - Alpha VoIP Stack
#### **Core VoIP Ecosystem**
- ✅ **Unified Interface**: Single crate access to entire VoIP stack
- ✅ Modular re-exports for clean imports (`rvoip::session_core::*`)
- ✅ Consistent API patterns across all components
- ✅ Zero-overhead abstractions with compile-time optimizations
- ✅ Comprehensive documentation and examples for all layers
- ✅ **Alpha Components**: Core VoIP functionality implemented (not production-ready)
- ✅ **Call Center Operations**: Agent management, queuing, routing (call-engine)
- ✅ **SIP Client Applications**: Softphones, user agents (client-core)
- ✅ **Session Management**: Call control, media coordination (session-core)
- ✅ **Protocol Compliance**: RFC 3261 SIP implementation (dialog-core)
#### **Alpha Call Management Stack**
- ✅ **Business Logic Layer**: Alpha call center with database integration
- ✅ Agent SIP registration and status management
- ✅ Database-backed call queuing with priority handling
- ✅ Round-robin load balancing with fair distribution
- ✅ B2BUA call bridging with bidirectional audio flow
- ✅ **Client Application Layer**: Complete SIP client capabilities
- ✅ High-level client API with intuitive builder pattern
- ✅ Call operations (make, answer, hold, transfer, terminate)
- ✅ Media controls (mute, quality monitoring, codec management)
- ✅ Event-driven architecture for UI integration
#### **Alpha Media and Protocol Stack**
- ✅ **Session Coordination**: Alpha session management
- ✅ Real media-core integration with MediaSessionController
- ✅ SIP-media lifecycle coordination with proper cleanup
- ✅ Quality monitoring with MOS scores and statistics
- ✅ Flexible call handling patterns (immediate and deferred)
- ✅ **Protocol Implementation**: Complete SIP protocol compliance
- ✅ SIP message parsing with header validation
- ✅ Transaction management with retransmission handling
- ✅ Dialog state management with RFC 3261 compliance
- ✅ Multi-transport support (UDP, TCP, TLS)
#### **Alpha Infrastructure**
- ✅ **Developer Experience**: Simple APIs with comprehensive examples
- ✅ 3-line SIP server creation with automatic configuration
- ✅ Builder patterns for complex setups with sensible defaults
- ✅ Comprehensive examples from basic to enterprise-grade
- ✅ Complete documentation with practical usage patterns
- ⚠️ **Quality Assurance**: Testing and validation in progress
- ✅ 400+ tests across all components with growing coverage
- ✅ End-to-end testing with SIPp integration and real media
- ✅ Performance benchmarks with scalability validation
- ⚠️ Alpha-level testing - not yet validated for production deployment
## 🚀 SIP Protocol Features
### 📋 Core SIP Methods Support
| **INVITE** | ✅ Complete | RFC 3261 | Session initiation and modification | Full state machine, media coordination |
| **ACK** | ✅ Complete | RFC 3261 | Final response acknowledgment | Automatic generation, dialog correlation |
| **BYE** | ✅ Complete | RFC 3261 | Session termination | Proper cleanup, B2BUA forwarding |
| **CANCEL** | ✅ Complete | RFC 3261 | Request cancellation | Transaction correlation, state management |
| **REGISTER** | ✅ Complete | RFC 3261 | User registration | Contact management, expiration handling |
| **OPTIONS** | ✅ Complete | RFC 3261 | Capability discovery | Method advertisement, feature negotiation |
| **SUBSCRIBE** | ✅ Complete | RFC 6665 | Event notification subscription | Event packages, subscription state |
| **NOTIFY** | ✅ Complete | RFC 6665 | Event notifications | Event delivery, subscription management |
| **MESSAGE** | ✅ Complete | RFC 3428 | Instant messaging | Message delivery, content types |
| **UPDATE** | ✅ Complete | RFC 3311 | Session modification | Mid-session updates, SDP negotiation |
| **INFO** | ✅ Complete | RFC 6086 | Mid-session information | DTMF relay, application data |
| **PRACK** | ✅ Complete | RFC 3262 | Provisional response acknowledgment | Reliable provisionals, sequence tracking |
| **REFER** | ✅ Complete | RFC 3515 | Call transfer initiation | Transfer correlation, refer-to handling |
| **PUBLISH** | ✅ Complete | RFC 3903 | Event state publication | Presence publishing, event state |
### 🔐 Authentication & Security
| **Digest Authentication** | ✅ Complete | MD5, SHA-256, SHA-512-256 | RFC 3261 | Challenge-response authentication |
| **Quality of Protection** | ✅ Complete | auth, auth-int | RFC 3261 | Integrity protection levels |
| **SRTP/SRTCP** | ✅ Complete | AES-CM, AES-GCM, HMAC-SHA1 | RFC 3711 | Secure media transport |
| **DTLS-SRTP** | ✅ Complete | ECDHE, RSA | RFC 5763 | WebRTC-compatible security |
| **ZRTP** | ✅ Complete | DH, ECDH, SAS | RFC 6189 | Peer-to-peer key agreement |
| **MIKEY-PSK** | ✅ Complete | Pre-shared keys | RFC 3830 | Enterprise key management |
| **MIKEY-PKE** | ✅ Complete | RSA, X.509 | RFC 3830 | Certificate-based keys |
| **SDES-SRTP** | ✅ Complete | SDP-based | RFC 4568 | SIP signaling key exchange |
| **TLS Transport** | ✅ Complete | TLS 1.2/1.3 | RFC 3261 | Secure SIP transport |
### 🎵 Media & Codec Support
| **Audio Codecs** | G.711 PCMU/PCMA | ✅ Complete | ITU-T G.711 | μ-law/A-law, 8kHz |
| | G.722 | ✅ Complete | ITU-T G.722 | Wideband audio, 16kHz |
| | Opus | ✅ Complete | RFC 6716 | Adaptive bitrate, 8-48kHz |
| | G.729 | ✅ Complete | ITU-T G.729 | Low bandwidth, 8kHz |
| **Audio Processing** | Echo Cancellation | ✅ Complete | Advanced AEC | 16.4 dB ERLE improvement |
| | Gain Control | ✅ Complete | Advanced AGC | Multi-band processing |
| | Voice Activity | ✅ Complete | Advanced VAD | Spectral analysis |
| | Noise Suppression | ✅ Complete | Spectral NS | Real-time processing |
| **RTP Features** | RTP/RTCP | ✅ Complete | RFC 3550 | Packet transport, statistics |
| | RTCP Feedback | ✅ Complete | RFC 4585 | Quality feedback |
| | RTP Extensions | ✅ Complete | RFC 8285 | Header extensions |
| **Conference** | Audio Mixing | ✅ Complete | N-way mixing | Multi-party conferences |
| | Media Bridging | ✅ Complete | B2BUA | Call bridging |
### 🌐 Transport Protocol Support
| **UDP** | ✅ Complete | Optional SRTP | RFC 3261 | Primary SIP transport |
| **TCP** | ✅ Complete | Optional TLS | RFC 3261 | Reliable transport |
| **TLS** | ✅ Complete | TLS 1.2/1.3 | RFC 3261 | Secure transport |
| **WebSocket** | ✅ Complete | WSS support | RFC 7118 | Web browser compatibility |
| **SCTP** | 🚧 Planned | DTLS-SCTP | RFC 4168 | Multi-streaming transport |
### 🔌 NAT Traversal Support
| **STUN Client** | ✅ Complete | RFC 5389 | NAT binding discovery |
| **TURN Client** | 🚧 Partial | RFC 5766 | Relay through NAT |
| **ICE** | 🚧 Partial | RFC 8445 | Connectivity establishment |
| **Symmetric RTP** | ✅ Complete | RFC 4961 | Bidirectional media flow |
### 📞 Dialog & Session Management
| **Early Dialogs** | ✅ Complete | RFC 3261 | 1xx response handling |
| **Confirmed Dialogs** | ✅ Complete | RFC 3261 | 2xx response handling |
| **Dialog Recovery** | ✅ Complete | RFC 3261 | State persistence |
| **Session Timers** | ✅ Complete | RFC 4028 | Keep-alive mechanism |
| **Dialog Forking** | 🚧 Planned | RFC 3261 | Parallel/sequential forking |
### 📋 SDP (Session Description Protocol)
| **Core SDP** | ✅ Complete | RFC 8866 | Session description |
| **WebRTC Extensions** | ✅ Complete | Various | Modern web compatibility |
| **ICE Attributes** | ✅ Complete | RFC 8839 | Connectivity attributes |
| **DTLS Fingerprints** | ✅ Complete | RFC 8122 | Security fingerprints |
| **Media Grouping** | ✅ Complete | RFC 5888 | BUNDLE support |
| **Simulcast** | ✅ Complete | RFC 8853 | Multiple stream support |
### 🎛️ Advanced Features
| **Call Center Operations** | ✅ Complete | Agent management, queuing, routing |
| **B2BUA Operations** | ✅ Complete | Back-to-back user agent |
| **Media Quality Monitoring** | ✅ Complete | Real-time MOS scoring |
| **Conference Mixing** | ✅ Complete | Multi-party audio mixing |
| **Call Transfer** | ✅ Complete | Blind transfer support |
| **Call Hold/Resume** | ✅ Complete | Media session control |
| **DTMF Support** | ✅ Complete | RFC 2833 DTMF relay |
### 🚧 Planned Features - Enterprise Enhancement
#### **Advanced VoIP Features**
- 🚧 **Video Calling**: Complete video call management with screen sharing
- 🚧 **WebRTC Integration**: Browser-based calling capabilities
- 🚧 **Advanced Conferencing**: Multi-party conferences with moderator controls
- 🚧 **Call Recording**: Built-in recording with compliance features
#### **Enhanced Developer Experience**
- 🚧 **Prelude Module**: Convenient imports for common VoIP patterns
- 🚧 **Configuration Wizards**: Interactive setup for complex deployments
- 🚧 **UI Component Library**: Pre-built components for common scenarios
- 🚧 **Performance Dashboard**: Built-in monitoring and diagnostics
#### **Enterprise Integration**
- 🚧 **Cloud-Native**: Kubernetes-ready deployment patterns
- 🚧 **Microservices**: Distributed VoIP architecture support
- 🚧 **Authentication**: OAuth 2.0 and modern auth integration
- 🚧 **Compliance**: GDPR, HIPAA, and regulatory compliance features
## 🏗️ **Architecture**
```
┌─────────────────────────────────────────────────────────────┐
│ VoIP Application │
├─────────────────────────────────────────────────────────────┤
│ rvoip │
│ ┌─────────────┬─────────────┬─────────────┬─────────────┐ │
│ │call-engine │client-core │session-core │ │ │
│ ├─────────────┼─────────────┼─────────────┼─────────────┤ │
│ │dialog-core │media-core │rtp-core │ │ │
│ ├─────────────┼─────────────┼─────────────┼─────────────┤ │
│ │transaction │sip-core │sip-transport│infra-common │ │
│ └─────────────┴─────────────┴─────────────┴─────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ Network Layer │
└─────────────────────────────────────────────────────────────┘
```
### **Component Overview**
#### **Application Layer (High-Level)**
- **`call-engine`**: Complete call center with agent management and routing
- **`client-core`**: SIP client applications and softphone functionality
- **`session-core`**: Session coordination and call control operations
#### **Protocol Layer (Core)**
- **`dialog-core`**: SIP dialog state management and RFC 3261 compliance
- **`transaction-core`**: SIP transaction handling and retransmission
- **`sip-core`**: SIP message parsing and protocol primitives
#### **Media Layer (Real-Time)**
- **`media-core`**: Audio processing, codecs, and quality monitoring
- **`rtp-core`**: RTP/RTCP implementation and media transport
- **`sip-transport`**: SIP transport layer (UDP, TCP, TLS)
#### **Infrastructure Layer (Common)**
- **`infra-common`**: Shared utilities, logging, and configuration
## 📦 **Installation**
Add to your `Cargo.toml`:
```toml
[dependencies]
rvoip = "0.1.5"
tokio = { version = "1.0", features = ["full"] }
```
## Usage
### Ultra-Simple SIP Server (3 Lines!)
```rust
use rvoip::session_core::prelude::*;
#[tokio::main]
async fn main() -> Result<()> {
let session_manager = SessionManagerBuilder::new().with_sip_port(5060).build().await?;
println!("🚀 SIP server running on port 5060");
tokio::signal::ctrl_c().await?;
Ok(())
}
```
### Simple SIP Client (5 Lines!)
```rust
use rvoip::client_core::{ClientConfig, ClientManager, MediaConfig};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let config = ClientConfig::new()
.with_sip_addr("127.0.0.1:5060".parse()?)
.with_media_addr("127.0.0.1:20000".parse()?)
.with_media(MediaConfig::default());
let client = ClientManager::new(config).await?;
client.start().await?;
// Make a call
let call_id = client.make_call(
"sip:alice@127.0.0.1".to_string(),
"sip:bob@example.com".to_string(),
None
).await?;
println!("📞 Call initiated: {}", call_id);
tokio::signal::ctrl_c().await?;
Ok(())
}
```
### Alpha Call Center (Development/Testing)
```rust
use rvoip::call_engine::{prelude::*, CallCenterServerBuilder};
use std::time::Duration;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Alpha call center configuration for development/testing
let mut config = CallCenterConfig::default();
config.general.local_signaling_addr = "0.0.0.0:5060".parse()?;
config.general.domain = "call-center.dev.com".to_string();
config.general.registrar_domain = "agents.dev.com".to_string();
config.database.url = "sqlite:alpha_call_center.db".to_string();
// Create call center server
let mut server = CallCenterServerBuilder::new()
.with_config(config)
.with_database_path("alpha_call_center.db".to_string())
.build()
.await?;
// Start server
server.start().await?;
// Create default call queues
server.create_default_queues().await?;
println!("🏢 Alpha Call Center Features (Development/Testing):");
println!(" ✅ Agent SIP Registration");
println!(" ✅ Database-Backed Queuing");
println!(" ✅ Round-Robin Load Balancing");
println!(" ✅ B2BUA Call Bridging");
println!(" ✅ Real-Time Quality Monitoring");
// Monitor system health
let server_clone = server.clone();
tokio::spawn(async move {
let mut interval = tokio::time::interval(Duration::from_secs(30));
loop {
interval.tick().await;
if let Ok(stats) = server_clone.get_stats().await {
println!("📊 Call Center Stats:");
println!(" 📞 Total Calls: {}", stats.total_calls);
println!(" 👥 Available Agents: {}", stats.available_agents);
println!(" 📋 Queue Depth: {}", stats.total_queued);
println!(" ⏱️ Avg Wait Time: {:.1}s", stats.average_wait_time);
}
}
});
// Run the call center
println!("🚀 Call Center Server ready on port 5060");
server.run().await?;
Ok(())
}
```
### Advanced Session Management
```rust
use rvoip::session_core::api::*;
use std::sync::Arc;
#[tokio::main]
async fn main() -> Result<()> {
// Create session manager with advanced configuration
let coordinator = Arc::new(SessionManagerBuilder::new()
.with_sip_port(5060)
.with_local_address("sip:pbx@dev.com:5060")
.with_rtp_port_range(10000, 20000)
.with_max_sessions(1000)
.with_session_timeout(Duration::from_secs(3600))
.with_handler(Arc::new(AdvancedCallHandler::new()))
.build()
.await?);
// Start session coordination
SessionControl::start(&coordinator).await?;
println!("🎯 Advanced Session Management Features (Alpha):");
println!(" ✅ Real Media-Core Integration");
println!(" ✅ Quality Monitoring (MOS, Jitter, Packet Loss)");
println!(" ✅ Bridge Management for Conferences");
println!(" ✅ Event-Driven Architecture");
// Example: Create outgoing call with media monitoring
let session = SessionControl::create_outgoing_call(
&coordinator,
"sip:system@dev.com",
"sip:support@partner.dev",
None
).await?;
// Wait for call to be answered
match SessionControl::wait_for_answer(
&coordinator,
&session.id,
Duration::from_secs(30)
).await {
Ok(_) => {
println!("✅ Call answered - starting quality monitoring");
// Start comprehensive quality monitoring
MediaControl::start_statistics_monitoring(
&coordinator,
&session.id,
Duration::from_secs(5)
).await?;
// Monitor call quality
monitor_call_quality(&coordinator, &session.id).await?;
}
Err(e) => {
println!("❌ Call failed: {}", e);
}
}
Ok(())
}
async fn monitor_call_quality(
coordinator: &Arc<SessionCoordinator>,
session_id: &SessionId
) -> Result<()> {
while let Some(session) = SessionControl::get_session(coordinator, session_id).await? {
if session.state().is_final() {
break;
}
if let Some(stats) = MediaControl::get_media_statistics(coordinator, session_id).await? {
if let Some(quality) = stats.quality_metrics {
let mos = quality.mos_score.unwrap_or(0.0);
let quality_rating = match mos {
x if x >= 4.0 => "Excellent",
x if x >= 3.5 => "Good",
x if x >= 3.0 => "Fair",
x if x >= 2.5 => "Poor",
_ => "Bad"
};
println!("📊 Call Quality: {:.1} MOS ({})", mos, quality_rating);
println!(" Packet Loss: {:.2}%", quality.packet_loss_percent);
println!(" Jitter: {:.1}ms", quality.jitter_ms);
println!(" RTT: {:.0}ms", quality.round_trip_time_ms);
}
}
tokio::time::sleep(Duration::from_secs(5)).await;
}
Ok(())
}
#[derive(Debug)]
struct AdvancedCallHandler;
#[async_trait]
impl CallHandler for AdvancedCallHandler {
async fn on_incoming_call(&self, call: IncomingCall) -> CallDecision {
println!("📞 Incoming call from {} to {}", call.from, call.to);
// Route based on called number
if call.to.contains("support") {
CallDecision::Accept(None)
} else if call.to.contains("sales") {
CallDecision::Forward("sip:sales-queue@dev.com".to_string())
} else {
CallDecision::Reject("Number not in service".to_string())
}
}
async fn on_call_established(&self, call: CallSession, _local_sdp: Option<String>, _remote_sdp: Option<String>) {
println!("✅ Call {} established with media", call.id());
}
async fn on_call_ended(&self, call: CallSession, reason: &str) {
println!("📴 Call {} ended: {}", call.id(), reason);
}
}
```
## VoIP Applications (Alpha Development)
### What Can You Build?
The rvoip library provides the foundation for VoIP applications (alpha development stage):
#### ⚠️ **Small to Medium Call Centers (5-500 agents) - Alpha**
- Complete inbound/outbound call handling (in development)
- Agent registration and real-time status tracking (alpha)
- Database-backed queuing with priority management (alpha)
- Round-robin and skills-based routing (alpha)
- Quality monitoring and reporting (alpha)
- B2BUA bridging with conference capabilities (alpha)
#### ⚠️ **SIP Client Applications - Alpha**
- Desktop softphones with full call control (alpha)
- Mobile VoIP applications (alpha)
- Embedded device calling (alpha)
- WebRTC gateway applications (planned)
- Custom SIP user agents (alpha)
#### ⚠️ **Enterprise Communication Systems - Alpha**
- PBX replacement systems (alpha)
- Unified communications platforms (alpha)
- Contact center solutions (alpha)
- Emergency calling systems (planned)
- IoT voice communication (alpha)
#### ✅ **Development and Integration Platforms - Alpha**
- VoIP testing frameworks (alpha)
- Protocol compliance testing (alpha)
- Performance benchmarking (alpha)
- Educational VoIP platforms (alpha)
- Integration with existing systems (alpha)
## Performance Characteristics (Alpha)
### VoIP Performance - Alpha Testing
#### **Call Processing Performance - Alpha**
- **Session Setup**: Sub-second call establishment across entire stack (alpha testing)
- **Concurrent Calls**: 1000+ simultaneous calls per server instance (alpha testing)
- **Media Processing**: Real-time audio with <50ms latency (alpha testing)
- **Database Operations**: 5000+ operations per second with SQLite (alpha testing)
#### **Resource Efficiency - Alpha**
- **Memory Usage**: ~5KB per active call (including all layers) (alpha testing)
- **CPU Usage**: <2% on modern hardware for 100 concurrent calls (alpha testing)
- **Network Efficiency**: Optimized SIP and RTP packet processing (alpha testing)
- **Database Efficiency**: Atomic operations with connection pooling (alpha testing)
#### **Scalability Characteristics - Alpha**
- **Agent Capacity**: 500+ registered agents with real-time status (alpha testing)
- **Queue Throughput**: 10,000+ calls per hour processing (alpha testing)
- **Event Processing**: 10,000+ events per second with zero-copy (alpha testing)
- **Integration Overhead**: Minimal - designed for alpha deployment
### Quality Assurance - Alpha
#### **Alpha Testing**
- **Unit Tests**: 400+ tests across all components (alpha coverage)
- **Integration Tests**: End-to-end call flows (alpha testing)
- **Performance Tests**: Load testing with realistic scenarios (alpha testing)
- **Interoperability**: SIPp integration for protocol compliance (alpha testing)
#### **Alpha Validation**
- **Known Issues**: Some bugs and limitations remain (alpha stage)
- **Performance Benchmarks**: Validated under load (alpha testing)
- **Memory Safety**: Zero memory leaks in long-running tests (alpha testing)
- **API Stability**: APIs may change - not yet stable (alpha stage)
## Component Integration
### How Components Work Together
The rvoip ecosystem provides seamless integration across all VoIP layers:
#### **Call-Engine ↔ Session-Core**
- Session events drive business logic
- Call control operations coordinate sessions
- Media quality affects routing decisions
- Agent status updates trigger queue processing
#### **Session-Core ↔ Media-Core**
- Real MediaSessionController integration
- Quality metrics drive session decisions
- Codec negotiation affects session setup
- RTP coordination ensures proper media flow
#### **Client-Core ↔ Dialog-Core**
- SIP protocol compliance for all client operations
- Dialog state affects client call state
- Transaction management ensures reliable operations
- Error handling provides user-friendly messages
#### **All Components ↔ Infra-Common**
- Shared configuration and logging
- Event bus for cross-component communication
- Common utilities and error handling
- Performance monitoring and metrics
## Module Reference
### High-Level Application Modules
```rust
use rvoip::call_engine::prelude::*; // Call center operations
use rvoip::client_core::{ClientConfig, ClientManager}; // SIP clients
use rvoip::session_core::api::*; // Session management
```
### Core Protocol Modules
```rust
use rvoip::dialog_core::prelude::*; // SIP dialog management
use rvoip::transaction_core::prelude::*; // SIP transactions
use rvoip::sip_core::prelude::*; // SIP message parsing
```
### Media and Transport Modules
```rust
use rvoip::media_core::prelude::*; // Audio processing
use rvoip::rtp_core::prelude::*; // RTP transport
use rvoip::sip_transport::prelude::*; // SIP transport
```
### Infrastructure Modules
```rust
use rvoip::infra_common::prelude::*; // Common utilities
```
## Error Handling
The library provides comprehensive error handling across all components:
```rust
use rvoip::call_engine::CallCenterError;
use rvoip::client_core::ClientError;
use rvoip::session_core::SessionError;
// Unified error handling patterns
match voip_operation().await {
Err(CallCenterError::DatabaseError(msg)) => {
log::error!("Database error: {}", msg);
// Handle database failover
}
Err(ClientError::NetworkError(msg)) => {
log::error!("Network error: {}", msg);
// Handle network recovery
}
Err(SessionError::MediaNotAvailable) => {
log::warn!("Media unavailable");
// Handle media fallback
}
Ok(result) => {
// Handle successful operation
}
}
```
## Future Roadmap
### Phase 1: Enhanced Developer Experience
- **Simplified APIs**: Even easier VoIP application development
- **Prelude Module**: Convenient imports for common patterns
- **Configuration Wizards**: Interactive setup for complex scenarios
- **Real-time Dashboard**: Built-in monitoring and diagnostics
### Phase 2: Advanced Features
- **Video Calling**: Complete video call management
- **WebRTC Integration**: Browser-based calling capabilities
- **Advanced Conferencing**: Multi-party conferences with controls
- **Call Recording**: Built-in recording with compliance
### Phase 3: Enterprise Features
- **Cloud-Native**: Kubernetes deployment patterns
- **Authentication**: OAuth 2.0 and modern auth
- **Compliance**: GDPR, HIPAA regulatory support
- **Load Balancing**: Distributed VoIP architecture
### Phase 4: Ecosystem Expansion
- **UI Component Library**: Pre-built components
- **Integration Plugins**: Popular service integrations
- **Performance Optimization**: Hardware acceleration
- **Advanced Analytics**: Machine learning insights
## 📚 **Examples**
### **Available Examples**
The rvoip ecosystem includes comprehensive examples demonstrating all capabilities:
#### **Call Center Examples**
- **[Complete Call Center](../call-engine/examples/e2e_test/)** - Full call center with SIPp testing
- **[Agent Applications](../call-engine/examples/e2e_test/agent/)** - Agent client implementations
- **[Load Testing](../call-engine/examples/e2e_test/)** - Performance validation
#### **Client Application Examples**
- **[Basic Client-Server](../client-core/examples/client-server/)** - Simple client-server setup
- **[SIPp Integration](../client-core/examples/sipp_integration/)** - Interoperability testing
- **[Advanced Media](../client-core/examples/)** - Media control examples
#### **Session Management Examples**
- **[Session Lifecycle](../session-core/examples/02_session_lifecycle.rs)** - Complete session patterns
- **[Media Coordination](../session-core/examples/04_media_coordination.rs)** - Media integration
- **[Event Handling](../session-core/examples/03_event_handling.rs)** - Event-driven patterns
### **Running Examples**
```bash
# Complete call center demonstration
cd examples/call-center
cargo run
# Peer-to-peer calling
cd examples/peer-to-peer
cargo run
# Component-specific examples
cargo run --example basic_client -p rvoip-client-core
cargo run --example session_lifecycle -p rvoip-session-core
cargo run --example call_center_server -p rvoip-call-engine
```
## Testing
Run the comprehensive test suite:
```bash
# Run all tests across the entire ecosystem
cargo test
# Run component-specific tests
cargo test -p rvoip-call-engine
cargo test -p rvoip-client-core
cargo test -p rvoip-session-core
# Run integration tests
cargo test --test '*'
# Run with real network tests (requires SIP server)
cargo test -- --ignored
# Run performance benchmarks
cargo test --release -- --ignored benchmark
```
## Contributing
Contributions are welcome! Please see the [contributing guidelines](../../CONTRIBUTING.md) for details.
### Development Areas
The modular architecture makes it easy to contribute:
- **Application Layer**: Enhance call-engine, client-core, session-core
- **Protocol Layer**: Improve dialog-core, transaction-core, sip-core
- **Media Layer**: Extend media-core, rtp-core capabilities
- **Infrastructure**: Optimize infra-common, add new utilities
- **Examples**: Add new use cases and integration patterns
- **Documentation**: Improve guides and API documentation
### Getting Started
1. **Fork the repository**
2. **Choose a component** to work on
3. **Run the tests** to ensure everything works
4. **Make your changes** following the existing patterns
5. **Add tests** for new functionality
6. **Submit a pull request** with clear documentation
## Status
**Development Status**: ⚠️ **Alpha VoIP Stack - NOT PRODUCTION READY**
- ⚠️ **Alpha Ecosystem**: Major VoIP components implemented but not production-ready
- ⚠️ **Alpha Quality**: Comprehensive testing in progress, known issues remain
- ✅ **Developer Experience**: Simple APIs with comprehensive examples
- ⚠️ **Alpha Validation**: End-to-end testing with actual SIP and media processing (alpha stage)
- ✅ **Modular Architecture**: Clean separation of concerns with specialized components
**Production Readiness**: ❌ **NOT READY for Production Use**
- ❌ **Unstable APIs**: APIs may change without notice (alpha stage)
- ⚠️ **Performance Testing**: Tested with 1000+ concurrent calls and sessions (alpha testing)
- ⚠️ **Integration Testing**: Stack integration with all components (alpha testing)
- ✅ **Documentation**: Comprehensive guides and examples for all use cases
**Current Capabilities**: ⚠️ **Alpha VoIP Stack**
- **Alpha Call Centers**: Call center operations (alpha - not production ready)
- **Alpha SIP Client Applications**: Softphones and user agents (alpha - not production ready)
- **Alpha Session Management**: Session coordination and media control (alpha - not production ready)
- **Alpha Protocol Compliance**: RFC 3261 SIP implementation (alpha - not production ready)
- **Alpha Media Processing**: Real-time audio with quality monitoring (alpha - not production ready)
- **Alpha Enterprise Features**: Database integration, event handling, scalability (alpha - not production ready)
**Ecosystem Status**: 🚧 **Alpha Development - Growing**
| **call-engine** | ⚠️ Alpha | Call center with database, queuing, routing (alpha - not production ready) |
| **client-core** | ⚠️ Alpha | SIP client applications with call control (alpha - not production ready) |
| **session-core** | ⚠️ Alpha | Session coordination with media integration (alpha - not production ready) |
| **dialog-core** | ⚠️ Alpha | SIP dialog management with RFC 3261 compliance (alpha - not production ready) |
| **transaction-core** | ⚠️ Alpha | SIP transaction handling with retransmission (alpha - not production ready) |
| **media-core** | ⚠️ Alpha | Audio processing with quality monitoring (alpha - not production ready) |
| **rtp-core** | ⚠️ Alpha | RTP/RTCP implementation with SRTP support (alpha - not production ready) |
| **sip-core** | ⚠️ Alpha | SIP message parsing and protocol primitives (alpha - not production ready) |
| **sip-transport** | ⚠️ Alpha | Multi-transport SIP (UDP, TCP, TLS) (alpha - not production ready) |
| **infra-common** | ⚠️ Alpha | Common utilities and infrastructure (alpha - not production ready) |
## License
This project is licensed under either of
- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
---
*Built with ❤️ for the Rust VoIP community - Alpha VoIP development for testing and exploration*
**Ready to explore VoIP development?** Start with the [examples](../examples/) or dive into the [documentation](https://docs.rs/rvoip)!
⚠️ **Remember: This is an alpha release - not suitable for production use**