OddSockets Rust SDK Documentation

Overview & Features

The OddSockets Rust SDK provides a high-performance, async-first interface for real-time messaging with full Rust type safety and zero-cost abstractions.

High Performance

Built on Tokio for maximum async performance with zero-cost abstractions.

Memory Safe

Rust's ownership system prevents memory leaks and data races at compile time.

Type Safe

Full Rust type safety with comprehensive compile-time error checking.

Async First

Native async/await support with efficient resource management.

Cost Effective

No per-message pricing, industry-standard 32KB message limits, transparent pricing.

Zero Dependencies

Minimal dependency footprint with carefully selected, well-maintained crates.

Installation

toml

[dependencies]
oddsockets = "0.1.0"
tokio = { version = "1.0", features = ["full"] }

bash

cargo add oddsockets
cargo add tokio --features full

toml

[dependencies]
oddsockets = { git = "https://github.com/tygacloud/oddsockets-rust-sdk" }
tokio = { version = "1.0", features = ["full"] }

Quick Start

Basic Usage

rust

use oddsockets::{OddSocketsClient, OddSocketsConfig};
use tokio;

#[tokio::main]
async fn main() -> Result<(), Box> {
    // Create a client
    let config = OddSocketsConfig::new("ak_live_1234567890abcdef");
    let client = OddSocketsClient::new(config).await?;

    // Connect to OddSockets
    client.connect().await?;

    // Get a channel
    let channel = client.channel("my-channel");

    // Subscribe to messages
    let mut message_stream = channel.subscribe(Default::default()).await?;
    
    // Publish a message
    channel.publish("Hello, Rust!", Default::default()).await?;

    // Listen for messages
    while let Some(message) = message_stream.recv().await {
        println!("Received: {:?}", message);
    }

    Ok(())
}

Advanced Configuration

rust

use oddsockets::OddSocketsConfig;
use std::time::Duration;

let config = OddSocketsConfig::builder("ak_live_1234567890abcdef")
    .high_performance() // Optimized for high-performance scenarios
    .heartbeat_interval(Duration::from_secs(60))
    .reconnect_attempts(3)
    .build()?;

Bulk Publishing

rust

use oddsockets::{BulkMessage, message_types};

let messages = vec![
    BulkMessage::new("channel1", message_types::chat_message("Hello", "user1", None), None),
    BulkMessage::new("channel2", message_types::chat_message("World", "user2", None), None),
];

let results = client.publish_bulk(messages).await?;
for result in results {
    if result.is_successful() {
        println!("Message published successfully");
    }
}

Configuration

Client Options

rust

let config = OddSocketsConfig::builder("ak_live_1234567890abcdef")
    .user_id("user-id".to_string())           // Optional: User identifier
    .auto_connect(true)                       // Optional: Auto-connect on creation
    .reconnect_attempts(5)                    // Optional: Max reconnection attempts
    .heartbeat_interval(Duration::from_secs(30)) // Optional: Heartbeat interval
    .build()?;

Channel Options

rust

let subscribe_options = SubscribeOptions::builder()
    .enable_presence(true)                    // Enable presence tracking
    .retain_history(true)                     // Retain message history
    .filter("user.premium == true".to_string()) // Message filter expression
    .build();

let publish_options = PublishOptions::builder()
    .ttl(3600)                               // Time to live (seconds)
    .metadata(serde_json::json!({"priority": "high"})) // Additional metadata
    .store_in_history(true)                  // Store in message history
    .build();

Examples

Explore comprehensive examples demonstrating the OddSockets Rust SDK in action:

View All Examples

Browse all available examples including async patterns, error handling, and production-ready code

Performance & Compatibility

OddSockets Rust SDK delivers superior performance with broad compatibility:

<10ms

Latency

99.9%

Uptime

32KB

Max Message

10M+

Messages/sec

Rust Support

Rust 1.70+ (MSRV)
Tokio 1.0+ async runtime
Cross-platform support
WebAssembly compatible

Platform Support

Linux (x86_64, ARM64)
macOS (Intel, Apple Silicon)
Windows (x86_64)
WebAssembly (WASM)

Async Patterns

The OddSockets Rust SDK is built with async-first design patterns. Here are common async usage patterns:

Concurrent Message Handling

rust

use tokio::task;
use futures::stream::StreamExt;

#[tokio::main]
async fn main() -> Result<(), Box> {
    let client = OddSocketsClient::new(config).await?;
    let channel = client.channel("events");
    
    let mut message_stream = channel.subscribe(Default::default()).await?;
    
    // Process messages concurrently
    while let Some(message) = message_stream.next().await {
        task::spawn(async move {
            // Handle each message in its own task
            process_message(message).await;
        });
    }
    
    Ok(())
}

async fn process_message(message: Message) {
    // Your message processing logic here
    println!("Processing: {:?}", message);
}

Error Handling with Results

rust

use oddsockets::{OddSocketsError, OddSocketsResultExt};

async fn handle_messages() -> Result<(), OddSocketsError> {
    let client = OddSocketsClient::new(config).await?;
    let channel = client.channel("my-channel");
    
    // Publish with error handling
    match channel.publish("Hello", Default::default()).await {
        Ok(result) => println!("Published: {:?}", result),
        Err(OddSocketsError::MessageTooLarge { size_kb, max_size_kb, message }) => {
            eprintln!("Message too large: {}KB > {}KB", size_kb, max_size_kb);
            eprintln!("Suggestion: {}", message);
        }
        Err(e) => {
            eprintln!("Error: {}", e);
            // Check if error is recoverable
            if e.is_recoverable() {
                println!("Retrying...");
                // Implement retry logic
            }
        }
    }
    
    Ok(())
}

Graceful Shutdown

rust

use tokio::signal;
use tokio::select;

#[tokio::main]
async fn main() -> Result<(), Box> {
    let client = OddSocketsClient::new(config).await?;
    let channel = client.channel("my-channel");
    let mut message_stream = channel.subscribe(Default::default()).await?;
    
    loop {
        select! {
            // Handle incoming messages
            message = message_stream.recv() => {
                if let Some(msg) = message {
                    println!("Received: {:?}", msg);
                }
            }
            
            // Handle shutdown signal
            _ = signal::ctrl_c() => {
                println!("Shutting down gracefully...");
                client.disconnect().await?;
                break;
            }
        }
    }
    
    Ok(())
}